spec §6: document the client screen contract + normative hot-path rules

CHANGELOG.md

@@ -17,6 +17,37 @@ for how the document, manifest, and per-plugin versions relate.
   `events`), plus `kind` and `description`. The `compatibility` field is no longer a hard schema
   enum (its values are an open set); the observed values are documented instead. Purely additive
   and clarifying — every existing manifest still validates.
+- §6 (Client surface) rewritten to document the client screen contract, ground-truthed against the
+  Host. Adds the **mount lifecycle** (§6.1 — Host-created container, `screen`-sourced markup,
+  self-executing `script` with **no Host-invoked entry point**, and a normative **idempotent
+  re-hydration MUST**), **screen activation/visibility** (§6.2), and a description of the
+  **Host-provided, Host-versioned runtime surface** (§6.3 — event bus, contribution registries, and
+  the forward-stable capability control plane; raw window globals documented as supported-but-legacy).
+  New **§6.4 "Performance and the shared main thread"** makes the hot-path rules normative
+  (SHOULD NOT do per-frame DOM/layout/IO; don't observe/mutate the shell — use contribution
+  registries; suspend work when hidden; keep state per-instance). Replaces the previous "client
+  runtime API is out of scope" placeholder. Settings/Styles/Static-assets renumbered to §6.5–6.7.
+- Best-practices guide: added a **"Client screen & the shared main thread"** section grounded in
+  real feedBack performance regressions — no DOM/layout work on a per-frame path, don't
+  DOM-observe or mutate the app shell (use registration APIs instead of injecting into song/library
+  cards), no synchronous storage/network on hot or gameplay-event paths, idempotent re-hydration
+  (`plugin-runtime-idempotent.v1`), stop work when hidden, stay per-instance, and talk to other
+  plugins through the capability `claim`/`dispatch`/`release` flow rather than their globals.
+  Regrouped the guide (Getting started / Server routes / Client screen / Shipping) and expanded the
+  pre-publish checklist with a client-performance block. Docs only.
+- Best-practices guide: added a **"Visualizations"** section for `type: "visualization"` plugins,
+  ground-truthed against the Host's renderer contract and recent splitscreen/settings fixes. Covers
+  the **factory pattern** (`window.feedBackViz_<id>` returns a fresh renderer per call — required for
+  splitscreen's N simultaneous panels), the renderer interface (`draw`/`init`/`resize`/`destroy`/
+  `contextType`), per-instance resource ownership and `destroy()` cleanup, treating the per-frame
+  bundle as read-only, self-detecting canvas size drift, and **communicating settings via
+  `applySetting(key, value)` per instance** (declare `settings` on the `visualization` capability;
+  the Host applies each change to the specific per-panel instance) — including the concrete failure
+  modes recent fixes addressed (apply-live-not-reload, no cross-setting leakage, deliberate
+  per-panel vs global key scoping, fan-out to all panels, settings panel loads before the renderer),
+  and persistence guidance (Host owns persistence — don't hand-roll `localStorage`; if self-managed,
+  stage an in-memory fallback before the quota-fallible `setItem` and keep it off the per-frame path),
+  plus the fail-safe auto-revert. Expanded the checklist with a Visualizations block. Docs only.
 
 ## [0.1.0] - 2026-07-05
 

examples/full-plugin/README.md

@@ -19,5 +19,7 @@ python tools/validate.py examples/full-plugin
 ```
 
 Target Host: written against the plugin runtime documented for feedBack as of spec v0.1.0. The
-client runtime API (how `screen.js` mounts) is Host-provided and not yet pinned by the spec — see
-[§6.1](../../spec/plugin-spec-v1.md#61-screen).
+mount lifecycle is described in [§6.1](../../spec/plugin-spec-v1.md#61-screen-mount-lifecycle) and
+the Host-provided (and Host-versioned) runtime surface in
+[§6.3](../../spec/plugin-spec-v1.md#63-the-client-runtime-surface); the portable performance rules
+are normative in [§6.4](../../spec/plugin-spec-v1.md#64-performance-and-the-shared-main-thread).