From 87cfecf8a802e22462c5326e74a9ca6e29e6aac9 Mon Sep 17 00:00:00 2001
From: "K. O. A." <topkoa@gmail.com>
Date: Sun, 5 Jul 2026 21:48:38 -0400
Subject: [PATCH 1/2] best-practices: add "Organizing client code across files"
 section
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add guidance for splitting a plugin's client JS instead of one monolithic
screen.js, ground-truthed against how the Host loads and serves plugin JS.

Rules (27-29):
- Prefer bundling to one screen.js if you have build tooling — the Host loads one
  script, sidestepping the runtime gotchas. (No bundler ships in-tree; it's your
  own build step.)
- screen.js runs as a CLASSIC script: no top-level import/export, no import.meta.
  Split files share state via window (namespaced by id), not ES exports.
- Serve extra files from assets/ (the plugin root is NOT servable — a file there
  404s; under assets/ the Host serves it traversal-guarded with a JS MIME), or a
  routes.py-served dir. Reference by ABSOLUTE /api/plugins/<id>/assets/... URLs —
  a relative import() from a classic script resolves against the document, not
  the script. Dynamic import() of an ES module from assets/ works; classic
  <script> injection works for window-attaching helpers.
- Load each split file exactly once (idempotent) — the Host may re-run screen.js,
  so de-dupe with a loaded-set / window-symbol check or re-hydration double-loads.

Renumber Shipping to 30-34 and add a checklist block. Docs only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: K. O. A. <topkoa@gmail.com>
---
 CHANGELOG.md           |  8 ++++
 spec/best-practices.md | 88 +++++++++++++++++++++++++++++++++++++++---
 2 files changed, 91 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c7d0a42..1603f86 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -67,6 +67,14 @@ for how the document, manifest, and per-plugin versions relate.
   `start` (double-tap / navigate-away races), standalone-by-default vs `usesPlayer`, and host-owned
   scoring/persistence (report via the SDK; single active session). Added a Minigames checklist block.
   Docs only.
+- Best-practices guide: added an **"Organizing client code across files"** section for splitting a
+  plugin's client JS instead of shipping one monolithic `screen.js`, ground-truthed against how the
+  Host loads and serves plugin JS. Covers bundling to one `screen.js` as the simplest path;
+  the constraint that `screen.js` is a **classic script** (no `import`/`export`/`import.meta` — split
+  files share state via `window`); serving extra files from **`assets/`** (the plugin root isn't
+  servable) referenced by **absolute `/api/plugins/<id>/…` URLs** (relative resolves against the
+  document, not the script); and **idempotent** runtime loading so re-hydration doesn't double-load.
+  Added a matching checklist block. Docs only.
 
 ## [0.1.0] - 2026-07-05
 
diff --git a/spec/best-practices.md b/spec/best-practices.md
index e27f27b..07c7836 100644
--- a/spec/best-practices.md
+++ b/spec/best-practices.md
@@ -397,9 +397,79 @@ abandonment/cleanup for that hop.
 
 ---
 
+## Organizing client code across files
+
+A plugin declares a single `script` (`screen.js`), but that doesn't force you into one giant file.
+You can split your client code — you just have to work within how the Host loads and serves it.
+The mechanics below are the current Host contract.
+
+### 27. Prefer bundling to one `screen.js`; split at runtime only when you must
+
+If you have any build tooling, author your plugin as many source files and **bundle them into the
+one `screen.js` you ship**. The Host loads exactly one script, so a bundle sidesteps every gotcha in
+the next two rules — no extra routes, no load-order or idempotency concerns. (feedBack ships no
+bundler and serves plugin JS verbatim, so this is your own build step, not a Host feature — but it's
+the simplest path to a non-monolithic plugin.)
+
+If you split at runtime instead, know the constraint that shapes everything else: **`screen.js` runs
+as a *classic* script, not an ES module.** Top-level `import` / `export` and `import.meta` do not
+work in it. Split files therefore share state through **`window`** (namespaced under your `id`, per
+rule 2), not through ES exports — each file attaches what it provides to a `window.<yourId>…` object
+and reads its dependencies from there.
+
+### 28. Serve extra files from `assets/`, and reference them by absolute URL
+
+The plugin **root is not a servable directory** — only `screen.js`, `screen.html`, `settings.html`,
+`tour.json`, and everything under **`assets/`** are served. A helper at your plugin root
+(`/api/plugins/<id>/lib/util.js`) returns 404; the same file under `assets/`
+(`/api/plugins/<id>/assets/lib/util.js`) is served by the Host, path-traversal-guarded and with the
+correct JavaScript MIME type. So put your split-out `.js` (and any `.css`, workers, or `.wasm`)
+under `assets/`. (If you genuinely need a non-`assets/` layout, a `routes.py` can serve your own
+sibling directories — but `assets/` is the built-in path and needs no server code.)
+
+Reference these files by an **absolute** `/api/plugins/<id>/assets/…` URL, never a relative one.
+Because `screen.js` is a classic script, a relative `import('./part.js')` resolves against the
+document's base URL (the app root), not your script — so it silently hits the wrong path. Build a
+base constant once and use it everywhere:
+
+```js
+const ASSET_BASE = '/api/plugins/my-plugin/assets/';   // hardcode your id
+// ES module served from assets/ (the Host serves it with a JS MIME):
+const util = await import(ASSET_BASE + 'lib/util.js');
+// or a classic, window-attaching helper:
+loadScriptOnce(ASSET_BASE + 'lib/legacy.js');          // see rule 29
+```
+
+Dynamic `import()` of a real ES module works this way (the module can use `import`/`export` among
+*its own* files, addressed by absolute URL); classic `<script>` injection works for non-module
+helpers that attach to `window`.
+
+### 29. Load each split file exactly once
+
+The Host may re-run your `screen.js` mid-session (rule 12), and your own screen may re-mount — so any
+runtime loading must be **idempotent**. De-dupe it: track what you've loaded (a `Set` of URLs, or a
+check for the `window.<yourId>…` symbol the file defines) and skip a second load. Otherwise
+re-hydration injects duplicate `<script>` tags or re-runs a module's side effects, which is exactly
+the duplication rule 12 exists to prevent.
+
+```js
+const _loaded = new Set();
+function loadScriptOnce(src) {
+  if (_loaded.has(src)) return Promise.resolve();
+  _loaded.add(src);
+  return new Promise((res, rej) => {
+    const s = document.createElement('script');       // classic; attaches to window
+    s.src = src; s.onload = res; s.onerror = rej;
+    document.body.appendChild(s);
+  });
+}
+```
+
+---
+
 ## Shipping & good citizenship
 
-### 27. Fail soft, log clearly
+### 30. Fail soft, log clearly
 
 - Use `context["log"]` (server) so your messages land in the Host log under your plugin's
   namespace.
@@ -408,25 +478,25 @@ abandonment/cleanup for that hop.
 - If a surface can't initialise, degrade to a reduced-but-working state rather than taking the
   whole plugin down.
 
-### 28. Degrade gracefully across Host versions
+### 31. Degrade gracefully across Host versions
 
 A plugin may run on a Host older than the one you developed against. Don't assume a `context` key
 or a client runtime API exists without a documented Host version guaranteeing it. If an optional
 surface isn't supported, your plugin's other surfaces must still work.
 
-### 29. Only declare capabilities you actually implement
+### 32. Only declare capabilities you actually implement
 
 `capabilities` and `standards` wire you into cross-plugin pipelines (diagnostics, capability
 inspection). Declaring a capability you don't service registers a phantom participant and breaks
 the pipeline. If you don't participate, omit both keys entirely.
 
-### 30. Mind the security boundary
+### 33. Mind the security boundary
 
 Your `routes` run arbitrary Python in the server process and your `script` runs in the app's
 renderer. Validate every route input, don't shell out on user data, and don't reach outside your
 plugin directory. Users installing your plugin are trusting it like an app extension — earn it.
 
-### 31. Ship a README and a changelog
+### 34. Ship a README and a changelog
 
 A plugin folder should carry a short `README.md` (what it does, which Host version it targets) and
 note changes per version. It costs little and saves every future reader — including you.
@@ -483,6 +553,14 @@ note changes per version. It costs little and saves every future reader — incl
 - [ ] Standalone by default (`usesPlayer` only if the game drives the highway); results reported via
       the SDK (host owns scoring/persistence); assumes a single active session.
 
+**Split client code (if `screen.js` isn't a single bundle):**
+
+- [ ] Extra JS lives under `assets/` (or a `routes.py`-served dir), not the plugin root, and is
+      referenced by absolute `/api/plugins/<id>/…` URLs.
+- [ ] Split files share state via `window.<id>…` (classic script — no `import`/`export` in
+      `screen.js`).
+- [ ] Runtime loads are de-duped so re-hydration doesn't load them twice.
+
 **Capabilities & shipping:**
 
 - [ ] Capabilities/standards declared only if actually implemented; cross-plugin calls go through

From 2c0f69371995c0f958f7b52b378dd454a0a45b0f Mon Sep 17 00:00:00 2001
From: "K. O. A." <topkoa@gmail.com>
Date: Mon, 6 Jul 2026 00:29:27 -0400
Subject: [PATCH 2/2] best-practices: code-splitting review fixes (window[id],
 no top-level await, robust loader)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rule 27 + checklist: key the window namespace with bracket notation
  (window['my-plugin']), since ids may contain '-' (window.my-plugin is a
  syntax error).
- Rule 28: the example no longer uses top-level await (a syntax error in a
  classic script) — use import(...).then / an async IIFE.
- Rule 29: rewrite loadScriptOnce to keep its cache on window (survives a
  screen.js re-run), cache the in-flight promise, and drop the entry on failure
  so a transient error can be retried.

Signed-off-by: K. O. A. <topkoa@gmail.com>
---
 spec/best-practices.md | 36 ++++++++++++++++++++----------------
 1 file changed, 20 insertions(+), 16 deletions(-)

diff --git a/spec/best-practices.md b/spec/best-practices.md
index 07c7836..51406c5 100644
--- a/spec/best-practices.md
+++ b/spec/best-practices.md
@@ -414,8 +414,10 @@ the simplest path to a non-monolithic plugin.)
 If you split at runtime instead, know the constraint that shapes everything else: **`screen.js` runs
 as a *classic* script, not an ES module.** Top-level `import` / `export` and `import.meta` do not
 work in it. Split files therefore share state through **`window`** (namespaced under your `id`, per
-rule 2), not through ES exports — each file attaches what it provides to a `window.<yourId>…` object
-and reads its dependencies from there.
+rule 2), not through ES exports — each file attaches what it provides to a per-plugin object and
+reads its dependencies from there. Key that object by `id` with **bracket notation**, since an `id`
+may contain `-` (which isn't a valid JS identifier): `window['my-plugin']` or a shared
+`(window.__feedBackPlugins ||= {})['my-plugin']` — not `window.my-plugin`, which is a syntax error.
 
 ### 28. Serve extra files from `assets/`, and reference them by absolute URL
 
@@ -434,8 +436,8 @@ base constant once and use it everywhere:
 
 ```js
 const ASSET_BASE = '/api/plugins/my-plugin/assets/';   // hardcode your id
-// ES module served from assets/ (the Host serves it with a JS MIME):
-const util = await import(ASSET_BASE + 'lib/util.js');
+// screen.js is a classic script, so there's no top-level await — use .then (or an async IIFE):
+import(ASSET_BASE + 'lib/util.js').then(util => { /* ES module served from assets/ */ });
 // or a classic, window-attaching helper:
 loadScriptOnce(ASSET_BASE + 'lib/legacy.js');          // see rule 29
 ```
@@ -447,21 +449,23 @@ helpers that attach to `window`.
 ### 29. Load each split file exactly once
 
 The Host may re-run your `screen.js` mid-session (rule 12), and your own screen may re-mount — so any
-runtime loading must be **idempotent**. De-dupe it: track what you've loaded (a `Set` of URLs, or a
-check for the `window.<yourId>…` symbol the file defines) and skip a second load. Otherwise
-re-hydration injects duplicate `<script>` tags or re-runs a module's side effects, which is exactly
-the duplication rule 12 exists to prevent.
+runtime loading must be **idempotent**. De-dupe it, but keep the cache **on `window`** (a module-local
+`Set` is wiped when `screen.js` re-runs, so it wouldn't actually prevent a re-load), cache the
+**in-flight promise** so concurrent callers share one load, and **drop the entry on failure** so a
+transient error can be retried:
 
 ```js
-const _loaded = new Set();
+const _loading = (window.__myPluginScripts ||= new Map());   // survives screen.js re-run
 function loadScriptOnce(src) {
-  if (_loaded.has(src)) return Promise.resolve();
-  _loaded.add(src);
-  return new Promise((res, rej) => {
-    const s = document.createElement('script');       // classic; attaches to window
+  let p = _loading.get(src);
+  if (p) return p;                                            // resolved or in-flight — reuse
+  p = new Promise((res, rej) => {
+    const s = document.createElement('script');               // classic; attaches to window
     s.src = src; s.onload = res; s.onerror = rej;
     document.body.appendChild(s);
-  });
+  }).catch(err => { _loading.delete(src); throw err; });      // allow retry after a failure
+  _loading.set(src, p);
+  return p;
 }
 ```
 
@@ -557,8 +561,8 @@ note changes per version. It costs little and saves every future reader — incl
 
 - [ ] Extra JS lives under `assets/` (or a `routes.py`-served dir), not the plugin root, and is
       referenced by absolute `/api/plugins/<id>/…` URLs.
-- [ ] Split files share state via `window.<id>…` (classic script — no `import`/`export` in
-      `screen.js`).
+- [ ] Split files share state via a bracket-keyed `window["<id>"]` namespace (classic script — no
+      `import`/`export` or top-level `await` in `screen.js`).
 - [ ] Runtime loads are de-duped so re-hydration doesn't load them twice.
 
 **Capabilities & shipping:**