best-practices: organizing client code across files

[topkoa]

Summary

Answers "how do I split screen.js so my plugin isn't one giant file?" — ground-truthed against how the Host actually loads and serves plugin JS, so the advice matches what really works (not what you'd assume).

The constraints that shape the advice

• screen.js is a classic script, not an ES module — the Host injects it with no type="module". So top-level import/export and import.meta don't work in it; split files share state through window (namespaced by id).
• The plugin root is not servable. Only screen.js, screen.html, settings.html, tour.json, and everything under assets/ are served. /api/plugins/<id>/lib/util.js → 404; /api/plugins/<id>/assets/lib/util.js → served (traversal-guarded, correct JS MIME).
• Relative URLs break. A relative import('./part.js') from a classic script resolves against the document base, not the script — so extra files must be referenced by absolute /api/plugins/<id>/assets/… URLs.
• No bundler ships in-tree — plugins are served verbatim, so runtime splitting is the observed path (tuner splits into utils//visualization//workers/ via its own routes.py; highway_3d lazy-loads vendor code from assets/). Bundling is still the cleanest option, just your own build step.

Rules (27–29)

• 27 — Prefer bundling to one screen.js; split at runtime only when you must. Plus the classic-script constraint and window-sharing.
• 28 — Serve extra files from assets/, reference by absolute URL. assets/ is the built-in served dir; a routes.py is the escape hatch for other layouts. Dynamic import() of an ES module from assets/ works; classic <script> injection works for window-attaching helpers. Includes an ASSET_BASE example.
• 29 — Load each split file exactly once. Re-hydration re-runs screen.js (rule 12), so de-dupe runtime loads with a Set/symbol check. Includes a loadScriptOnce helper.

Added a "Split client code" checklist block; Shipping renumbered to 30–34 (contiguous 1–34).

Scope & stacking

Docs only (spec/best-practices.md + CHANGELOG.md). No version bump. API facts framed as the current Host contract. Stacked on #7. Full stack: #2 → #4 → #3 → #5 → #6 → #7 → #8. mkdocs build --strict and check_versions.py pass.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 213339e0-c57c-4cc2-9e39-d83db65b2f02

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/best-practices-code-splitting

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Adds documentation guidance on splitting a plugin’s client-side screen.js into multiple files in a way that matches the Host’s actual loading/serving behavior (classic script execution, served paths, URL resolution, and re-hydration idempotency).

Changes:

• Introduces a new “Organizing client code across files” section with rules 27–29 (bundling preferred; runtime splitting via assets/ + absolute URLs; load-once/idempotency).
• Renumbers “Shipping & good citizenship” rules to 30–34 and adds a “Split client code” checklist block.
• Updates CHANGELOG.md to describe the new best-practices section.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
spec/best-practices.md	Adds new best-practices section + checklist for splitting client code; renumbers later rules.
CHANGELOG.md	Documents the added best-practices section in Unreleased notes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[topkoa]

Fixed: checklist now uses window["<id>"].