Teach the SDK startup order and where preview pixels come from

The applications reference now opens with the canonical startup:
waitUntilActive(), then ready(), with no SDK call (log included) while
inert, input queued until activation, and emitConfirmed where a receipt
matters. SKILL.md points at it. It replaces the old wording that implied
ready() could run before activation.

playlists.md says preview draws local <media_id> files or fetches project
media when logged in, and how placeholders are reported. Bundles CLI
b99b48a, which fetches project media for file previews.

Counts: repository 105 files, 2,975,031 -> 2,979,853 bytes; plugins/screenrig
49 files, 1,906,477 -> 1,909,548 bytes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: gersham

components.lock.json

@@ -3,10 +3,10 @@
   "state": "resolved",
   "cli": {
     "repository": "screenrig/cli",
-    "commit": "ec1bfeb03fe41a957372ab3261ef1a712de2d5a2",
+    "commit": "b99b48a266a4569da30d3b2ef77a017f57b2959b",
     "artifact": {
       "file": "screenrig-cli.tgz",
-      "sha256": "c4c2d917c4e242c46924ec7588320909122c945e9c5a23698347acebce9317d9"
+      "sha256": "222c04cfe816cef4d89cdbfdcce4b293bdbcf25e80bc41440dac6b04aecb6d59"
     }
   }
 }

plugins/screenrig/cli/dist/bin.js

@@ -411,7 +411,10 @@ rotation, billing and a scheduled-agent recipe are in
 
 For screen controls, reload, screenshots, comments, events and feedback, use
 [operations](references/operations.md). For app uploads, page completion and K/V,
-use [applications](references/applications.md). The [command inventory](references/commands.md)
+use [applications](references/applications.md). App code must
+`await screenrig.waitUntilActive()` before `await screenrig.ready()` and make
+no SDK call, `log()` included, while `readyState` is not `active`; see
+[SDK startup](references/applications.md#start-the-sdk-in-this-order). The [command inventory](references/commands.md)
 provides a compact reference for supported operations.
 
 ## Resolve issues and ask for support

plugins/screenrig/skills/screenrig/SKILL.md

@@ -16,6 +16,37 @@ the archive first. The packer injects the screenRIG browser SDK at
 reaches `window.screenrig` at runtime with no build step and no dependency to
 install.
 
+#### Start the SDK in this order
+
+`window.screenrig` starts `inert` and turns `active` only when the Player's
+handshake and context arrive; a page that is not on screen yet stays inert.
+While inert, `ready()`, `log()`, `emit()`, `emitConfirmed()`, `nextPage()` and
+`kv` throw or reject with code `inert`. Every app starts like this:
+
+```javascript
+const sr = window.screenrig;
+async function start() {
+  render(); // draw the UI; it must also work outside screenRIG
+  if (!sr) return;
+  for (;;) {
+    try { await sr.waitUntilActive(60000); break; }
+    catch (err) { if (err.code !== "activation_timeout") return; }
+  }
+  await sr.ready();
+  // Only from here: emit, emitConfirmed, log, kv, nextPage.
+}
+start();
+```
+
+- Call `ready()` only after `waitUntilActive()` resolves, never before.
+- Check `sr.readyState === "active"` before every SDK call made from an event
+  handler, timer or `catch`. Never call `log()` in a handler that can run while
+  inert: it throws too, and that throw stops the rest of startup, so no event
+  is ever sent.
+- Queue input that arrives before activation and send it after `ready()`. Use
+  `emitConfirmed(code)` when a receipt matters and handle its rejection; plain
+  `emit(code)` is a send attempt.
+
 Released apps run under a strict Content-Security-Policy (`script-src 'self';
 style-src 'self'`), so inline code in the served HTML never runs. The packer
 moves inline `<style>` blocks and inline `<script>` blocks into generated files
@@ -110,12 +141,11 @@ For an interactive kiosk, use application mode with a `max_ms` long enough
 for the intended visit. A duration page advances at its deadline even while a
 visitor is using the app; pointer activity does not extend that deadline.
 Call `nextPage()` after completion or a deliberate idle reset, and explain the
-bounded fallback in the experience. `await window.screenrig.ready()` completes
-the bridge handshake; it does not prove the candidate page is active. Use
-`await window.screenrig.waitUntilActive()` before starting a visitor idle clock
-or sending active-page events. Use `await window.screenrig.emitConfirmed(code)`
-when the UI promises that an event was accepted, and handle its rejection;
-plain `emit(code)` is a send attempt. The receipt resolves only after the
+bounded fallback in the experience. Start the visitor idle clock and send
+events only after the [startup sequence](#start-the-sdk-in-this-order)
+(`waitUntilActive()`, then `ready()`) finishes. Use
+`await window.screenrig.emitConfirmed(code)` when the UI promises that an event
+was accepted, and handle its rejection. The receipt resolves only after the
 backend accepted the event; do not retry automatically after a timeout, since
 the event may already be recorded. Choose a shorter duration only for a
 preview that is supposed to rotate regardless of input.

plugins/screenrig/skills/screenrig/references/applications.md

@@ -10,6 +10,12 @@ screenrig playlist preview lobby.json --output preview --contact-sheet
 screenrig screen publish scr_LOBBY lobby.json
 ```
 
+Preview draws each image and video from a local `<media_id>.png` (or `.jpg`,
+`.webp`, `.gif`, `.mp4`, `.webm`) beside the playlist, in the working directory
+or in `--output`, and otherwise fetches it from the project when the CLI is
+logged in. A grey box labelled with a media ID is a placeholder, not the page:
+`data.placeholders` and the `preview_media_placeholder` warning name each one.
+
 Inspect the document and preview before publishing. `playlist init` accepts local
 image/video/audio files, ready `med_` IDs, pinned `rel_` application releases, and HTTPS
 iframe URLs in playback order, including mixed inputs:

plugins/screenrig/skills/screenrig/references/playlists.md

@@ -411,7 +411,10 @@ rotation, billing and a scheduled-agent recipe are in
 
 For screen controls, reload, screenshots, comments, events and feedback, use
 [operations](references/operations.md). For app uploads, page completion and K/V,
-use [applications](references/applications.md). The [command inventory](references/commands.md)
+use [applications](references/applications.md). App code must
+`await screenrig.waitUntilActive()` before `await screenrig.ready()` and make
+no SDK call, `log()` included, while `readyState` is not `active`; see
+[SDK startup](references/applications.md#start-the-sdk-in-this-order). The [command inventory](references/commands.md)
 provides a compact reference for supported operations.
 
 ## Resolve issues and ask for support

skills/screenrig/SKILL.md

@@ -16,6 +16,37 @@ the archive first. The packer injects the screenRIG browser SDK at
 reaches `window.screenrig` at runtime with no build step and no dependency to
 install.
 
+#### Start the SDK in this order
+
+`window.screenrig` starts `inert` and turns `active` only when the Player's
+handshake and context arrive; a page that is not on screen yet stays inert.
+While inert, `ready()`, `log()`, `emit()`, `emitConfirmed()`, `nextPage()` and
+`kv` throw or reject with code `inert`. Every app starts like this:
+
+```javascript
+const sr = window.screenrig;
+async function start() {
+  render(); // draw the UI; it must also work outside screenRIG
+  if (!sr) return;
+  for (;;) {
+    try { await sr.waitUntilActive(60000); break; }
+    catch (err) { if (err.code !== "activation_timeout") return; }
+  }
+  await sr.ready();
+  // Only from here: emit, emitConfirmed, log, kv, nextPage.
+}
+start();
+```
+
+- Call `ready()` only after `waitUntilActive()` resolves, never before.
+- Check `sr.readyState === "active"` before every SDK call made from an event
+  handler, timer or `catch`. Never call `log()` in a handler that can run while
+  inert: it throws too, and that throw stops the rest of startup, so no event
+  is ever sent.
+- Queue input that arrives before activation and send it after `ready()`. Use
+  `emitConfirmed(code)` when a receipt matters and handle its rejection; plain
+  `emit(code)` is a send attempt.
+
 Released apps run under a strict Content-Security-Policy (`script-src 'self';
 style-src 'self'`), so inline code in the served HTML never runs. The packer
 moves inline `<style>` blocks and inline `<script>` blocks into generated files
@@ -110,12 +141,11 @@ For an interactive kiosk, use application mode with a `max_ms` long enough
 for the intended visit. A duration page advances at its deadline even while a
 visitor is using the app; pointer activity does not extend that deadline.
 Call `nextPage()` after completion or a deliberate idle reset, and explain the
-bounded fallback in the experience. `await window.screenrig.ready()` completes
-the bridge handshake; it does not prove the candidate page is active. Use
-`await window.screenrig.waitUntilActive()` before starting a visitor idle clock
-or sending active-page events. Use `await window.screenrig.emitConfirmed(code)`
-when the UI promises that an event was accepted, and handle its rejection;
-plain `emit(code)` is a send attempt. The receipt resolves only after the
+bounded fallback in the experience. Start the visitor idle clock and send
+events only after the [startup sequence](#start-the-sdk-in-this-order)
+(`waitUntilActive()`, then `ready()`) finishes. Use
+`await window.screenrig.emitConfirmed(code)` when the UI promises that an event
+was accepted, and handle its rejection. The receipt resolves only after the
 backend accepted the event; do not retry automatically after a timeout, since
 the event may already be recorded. Choose a shorter duration only for a
 preview that is supposed to rotate regardless of input.

skills/screenrig/references/applications.md

@@ -10,6 +10,12 @@ screenrig playlist preview lobby.json --output preview --contact-sheet
 screenrig screen publish scr_LOBBY lobby.json
 ```
 
+Preview draws each image and video from a local `<media_id>.png` (or `.jpg`,
+`.webp`, `.gif`, `.mp4`, `.webm`) beside the playlist, in the working directory
+or in `--output`, and otherwise fetches it from the project when the CLI is
+logged in. A grey box labelled with a media ID is a placeholder, not the page:
+`data.placeholders` and the `preview_media_placeholder` warning name each one.
+
 Inspect the document and preview before publishing. `playlist init` accepts local
 image/video/audio files, ready `med_` IDs, pinned `rel_` application releases, and HTTPS
 iframe URLs in playback order, including mixed inputs: