Vendor screen online state and compose textShadow

Refresh vendored OpenAPI and protocol from backend
6ead1108379151a0325bcb3db21c8ddad49d9c31. Screen requires online and
may carry last_online_at and last_ip. Native pairing is 72 hours
unclaimed plus a fresh 72-hour collection window after claim.
RuntimeManifest may emit playlistName. ScreenPatch cannot write
observation, online, last_online_at, or last_ip.

Optional Text textShadow is local compose render paint only. It is
not screenrig.canvas/v1 and not a player feature.

vendor/ is a snapshot refresh from backend 6ead110, not authored
protocol:
  vendor/openapi.yaml
    4acf9f8a86e123bd5ba0bee76a0adca7a09330e2bbee19ce0a6a1c2113af9007
  vendor/protocol/openapi.gen.ts
    4ad837a89687fdd7a5c5516a5cac8ea0fa0802fb4788fb0a78ae43a0fbf5d370

Gates: implementer reported check:public, vendor:check,
vendor:check:drift vs backend 6ead110, typecheck, lint, smoke:mock,
pack:dry. npm test: 231 pass, 1 fail rejects duplicate case-folded
names in dist/pack.test.js (macOS APFS; not in this write set), 1
skip. Did not re-run npm test. Public hygiene npm run check:public
re-run before push.

Known: APFS pack case-fold fail does not hold this pre-production
push.

Skipped: npm ci, smoke:server.

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

Author: gersham

AGENTS.md

@@ -283,6 +283,11 @@ installation, players, backend services, the site, or production deployment.
   render envelope is paths and layout metadata only. Never put PNG bytes in
   stdout, the envelope, or human text. `--open` opens a local path through
   `CliRuntime.openPath`; it is not the agent vision loop.
+- Optional Text `textShadow` is local `compose render` paint only. Author
+  `{ x, y, blur?, color }` in px; omit it to paint without a shadow. It is
+  not `screenrig.canvas/v1` and not a player feature. Layout `x`/`y` on Text
+  stay forbidden. This is **source-ready** in the working tree. It is not in
+  the locked plugin bundle. Do not claim marketplace or deployed.
 
 ## Verification
 

README.md

@@ -55,6 +55,10 @@ The ordinary pair command currently accepts six canonical characters:
 screenrig --json screen pair ABC234
 ```
 
+Native player pairing codes last 72 hours while unclaimed. A successful claim
+starts a fresh independent 72-hour collection window. `screen pair` claims the
+code on the control plane; the CLI does not time the code locally.
+
 The separate homepage handoff command accepts either `ABC-234` or `ABC234`,
 normalizes it, and returns only safe status fields:
 
@@ -217,7 +221,9 @@ The spec is a fail-closed tree of `Frame`, `Column`, `Row`, `Box`, `Spacer`,
 `Text`, and `Image`. Roles are `display`, `title`, `body`, `caption`, and
 `label`. Spacing tokens are `xs`, `s`, `m`, `l`, and `xl`. Pins are `top`,
 `bottom`, `left`, and `right`. Do not author `x`/`y` except on the Frame
-canvas. Do not author `fontSize`. `Image.src` is a local filesystem path
+canvas. Do not author `fontSize`. Optional Text `textShadow` is
+`{ "x": 2, "y": 2, "blur": 4, "color": "#00000080" }`; omit it to paint
+without a shadow. `Image.src` is a local filesystem path
 relative to the spec file. The CLI does not fetch URLs.
 
 `--open` is only for viewing the still on this computer. Agent vision reads

src/adapters/protocol.test.ts

@@ -213,8 +213,11 @@ test("adapter shapes mirror generated OpenAPI contract fields and Capabilities l
     "created_at",
     "id",
     "label",
+    "last_ip",
+    "last_online_at",
     "manifest_revision",
     "observation",
+    "online",
     "playlist_id",
     "public_id",
     "revision",
@@ -228,6 +231,12 @@ test("adapter shapes mirror generated OpenAPI contract fields and Capabilities l
   assert.match(screen, /"timezone"\?: string/);
   // Observation is player-reported and absent until the first report.
   assert.match(screen, /"observation"\?: ScreenObservation/);
+  // online is required and false until the first paired runtime connect.
+  // last_online_at and last_ip stay optional until that first connect.
+  assert.match(screen, /"online": boolean/);
+  assert.doesNotMatch(screen, /"online"\?: boolean/);
+  assert.match(screen, /"last_online_at"\?: string/);
+  assert.match(screen, /"last_ip"\?: string/);
   assert.doesNotMatch(source, /Bootstrap/);
   assert.deepEqual(quotedProperties(interfaceBody(source, "ScreenPatch")), [
     "name",
@@ -348,6 +357,42 @@ test("screen observation is optional, read-only, and absent from ScreenPatch", (
   assert.match(commands, /screen update requires <id>, --if-match, and --name, --playlist-id, or --timezone/);
 });
 
+test("screen online is required, last_online_at and last_ip are optional, and ScreenPatch cannot write them", () => {
+  const generated = readFileSync(GENERATED_CONTRACT, "utf8");
+  const openapi = readFileSync(OPENAPI_CONTRACT, "utf8");
+  const adapter = readFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), "../../src/adapters/protocol.ts"),
+    "utf8",
+  );
+  const commands = readFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), "../../src/commands.ts"),
+    "utf8",
+  );
+
+  const screen = interfaceBody(generated, "Screen");
+  assert.match(screen, /"online": boolean/);
+  assert.doesNotMatch(screen, /"online"\?: boolean/);
+  assert.match(screen, /"last_online_at"\?: string/);
+  assert.match(screen, /"last_ip"\?: string/);
+
+  const patch = interfaceBody(generated, "ScreenPatch");
+  assert.deepEqual(quotedProperties(patch), ["name", "playlist_id", "timezone"]);
+  assert.doesNotMatch(patch, /online|last_online_at|last_ip/);
+  assert.doesNotMatch(interfaceBody(generated, "PairScreen"), /online|last_online_at|last_ip/);
+  assert.doesNotMatch(interfaceBody(adapter, "ScreenPatch"), /online|last_online_at|last_ip/);
+  assert.match(adapter, /online: boolean/);
+  assert.match(adapter, /last_online_at\?: string/);
+  assert.match(adapter, /last_ip\?: string/);
+
+  const screenSchema = openapi.slice(openapi.indexOf("    Screen:\n"), openapi.indexOf("    ScreenList:"));
+  assert.match(screenSchema, /state, online, created_at, updated_at/);
+  assert.match(screenSchema, /not a player heartbeat or presence\.write report/);
+  assert.match(screenSchema, /maxLength: 45/);
+  assert.match(screenSchema, /ScreenPatch, pairing bodies, session[\s\S]*runtime manifest cannot write it/);
+  assert.doesNotMatch(commands, /--online|--last-online-at|--last-ip/);
+  assert.match(commands, /screen update requires <id>, --if-match, and --name, --playlist-id, or --timezone/);
+});
+
 test("published problem codes include payment_required at 402", () => {
   const source = readFileSync(OPENAPI_CONTRACT, "utf8");
   const listed = source.match(/x-problem-codes: \[([^\]]+)\]/);

src/adapters/protocol.ts

@@ -171,8 +171,24 @@ export interface Screen {
   created_at: string;
   id: string;
   label: string;
+  /**
+   * Last client IP at a paired runtime events connect. Absent until the first
+   * connect. Operational metadata; IDs and IPs are never authorization.
+   */
+  last_ip?: string;
+  /**
+   * Instant a paired runtime events stream last became connected. Present
+   * after the first connect. When offline, last time the screen was online.
+   */
+  last_online_at?: string;
   manifest_revision: number;
   observation?: ScreenObservation;
+  /**
+   * True while at least one paired runtime events stream is connected,
+   * including a short reconnect window. Always present; false until first
+   * connect. Read-only; not a player heartbeat.
+   */
+  online: boolean;
   playlist_id?: string;
   public_id: string;
   revision: number;
@@ -188,8 +204,8 @@ export interface Screen {
 /**
  * The screen patch body. Every member is optional and the server requires at
  * least one, which is why each command builds only the members it was asked
- * for rather than sending undefined placeholders. Observation is not a
- * patchable field.
+ * for rather than sending undefined placeholders. Observation, online,
+ * last_online_at, and last_ip are not patchable fields.
  */
 export interface ScreenPatch {
   name?: string;

src/cli.test.ts

@@ -477,9 +477,15 @@ test("browser setup --open opens only the public handoff URL by argv", async ()
   await rm(result.configDir, { recursive: true, force: true });
 });
 
-test("browser setup fails closed on extra delivery fields without echoing them", async () => {
+const BROWSER_CLAIM_SCREEN = {
+  id: "scr_browser_link",
+  public_id: "browser-link-screen",
+  state: "pairing_pending" as const,
+  public_url: "https://play.screenrig.ai/s/browser-link-screen",
+};
+
+function browserSetupClaimTransport(body: unknown): FakeTransport {
   const transport = new FakeTransport();
-  const secret = `https://play.screenrig.ai/s/browser-link-screen#provision=${"S".repeat(43)}`;
   transport.on("POST", "/api/v1/enrollments", () => ({
     status: 201,
     headers: { "cache-control": "private, no-store" },
@@ -494,24 +500,61 @@ test("browser setup fails closed on extra delivery fields without echoing them",
   transport.on("POST", "/api/v1/account/browser-links/claim", () => ({
     status: 201,
     headers: { "cache-control": "private, no-store" },
-    body: {
-      session_id: "bls_fixture",
-      status: "claimed",
-      screen: {
-        id: "scr_browser_link",
-        public_id: "browser-link-screen",
-        state: "pairing_pending",
-        public_url: "https://play.screenrig.ai/s/browser-link-screen",
+    body,
+  }));
+  return transport;
+}
+
+test("browser setup ignores extra claim and screen keys without echoing them", async () => {
+  const secret = `https://play.screenrig.ai/s/browser-link-screen#provision=${"S".repeat(43)}`;
+  const transport = browserSetupClaimTransport({
+    session_id: "bls_fixture",
+    status: "claimed",
+    screen: {
+      ...BROWSER_CLAIM_SCREEN,
+      timezone: "America/Los_Angeles",
+      observation: {
+        observed_at: "2026-08-14T17:00:00.000Z",
+        surfaces: [{ id: "primary", width: 1920, height: 1080, pixel_ratio: 1, presentation: "output" }],
       },
-      provisioning_url: secret,
     },
-  }));
+    provisioning_url: secret,
+  });
   const result = await withRuntime(["--json", "browser", "setup", "--code", "ABC234"], transport);
-  assert.equal(result.code, ExitCode.Usage);
-  assert.doesNotMatch(result.stdout, /#provision=|provisioning_url|SSSSSS/i);
+  assert.equal(result.code, 0, result.stdout);
+  const envelope = JSON.parse(result.stdout) as { data: Record<string, unknown> };
+  assert.deepEqual(envelope.data, {
+    code: "ABC-234",
+    status: "claimed",
+    player_public_url: "https://play.screenrig.ai/s/browser-link-screen",
+  });
+  assert.doesNotMatch(result.stdout, /#provision=|provisioning_url|SSSSSS|timezone|observation|America\/Los_Angeles/i);
   await rm(result.configDir, { recursive: true, force: true });
 });
 
+test("browser setup rejects missing required claim fields, bad status, and unsafe public URLs", async () => {
+  const cases: Array<{ name: string; body: Record<string, unknown> }> = [
+    { name: "missing session_id", body: { status: "claimed", screen: BROWSER_CLAIM_SCREEN } },
+    { name: "bad status", body: { session_id: "bls_fixture", status: "waiting", screen: BROWSER_CLAIM_SCREEN } },
+    { name: "missing screen", body: { session_id: "bls_fixture", status: "claimed" } },
+    { name: "missing screen id", body: { session_id: "bls_fixture", status: "claimed", screen: { ...BROWSER_CLAIM_SCREEN, id: "" } } },
+    { name: "missing public_id", body: { session_id: "bls_fixture", status: "claimed", screen: { ...BROWSER_CLAIM_SCREEN, public_id: "" } } },
+    { name: "bad screen state", body: { session_id: "bls_fixture", status: "claimed", screen: { ...BROWSER_CLAIM_SCREEN, state: "active" } } },
+    { name: "missing public_url", body: { session_id: "bls_fixture", status: "claimed", screen: { ...BROWSER_CLAIM_SCREEN, public_url: "" } } },
+    { name: "hash in public_url", body: { session_id: "bls_fixture", status: "claimed", screen: { ...BROWSER_CLAIM_SCREEN, public_url: "https://play.screenrig.ai/s/browser-link-screen#provision=SSS" } } },
+    { name: "search in public_url", body: { session_id: "bls_fixture", status: "claimed", screen: { ...BROWSER_CLAIM_SCREEN, public_url: "https://play.screenrig.ai/s/browser-link-screen?q=1" } } },
+    { name: "userinfo in public_url", body: { session_id: "bls_fixture", status: "claimed", screen: { ...BROWSER_CLAIM_SCREEN, public_url: "https://user:pass@play.screenrig.ai/s/browser-link-screen" } } },
+    { name: "wrong origin", body: { session_id: "bls_fixture", status: "claimed", screen: { ...BROWSER_CLAIM_SCREEN, public_url: "https://example.invalid/s/browser-link-screen" } } },
+    { name: "pathname mismatch", body: { session_id: "bls_fixture", status: "claimed", screen: { ...BROWSER_CLAIM_SCREEN, public_url: "https://play.screenrig.ai/s/other-id" } } },
+  ];
+  for (const item of cases) {
+    const result = await withRuntime(["--json", "browser", "setup", "--code", "ABC234"], browserSetupClaimTransport(item.body));
+    assert.equal(result.code, ExitCode.Usage, item.name);
+    assert.doesNotMatch(result.stdout, /#provision=|user:pass|token|cookie|proof/i, item.name);
+    await rm(result.configDir, { recursive: true, force: true });
+  }
+});
+
 test("browser setup rejects malformed codes before claim and keeps exact ambiguous retry state", async () => {
   const invalid = await withRuntime(["--json", "browser", "setup", "--code", "ABC10I"], memoryBackend());
   assert.equal(invalid.code, ExitCode.Usage);
@@ -2693,6 +2736,153 @@ test("screen update cannot send observation", async () => {
   await rm(configDir, { recursive: true, force: true });
 });
 
+const DOCUMENTATION_IPV4 = "192.0.2.10";
+const DOCUMENTATION_IPV6 = "2001:db8::1";
+
+test("screen show includes online and optional last_online_at and last_ip", async () => {
+  const transport = new FakeTransport();
+  const screen = {
+    content_access_generation: 1,
+    created_at: "2026-08-14T17:00:00.000Z",
+    id: "scr_PAIRINGAAAAAAAAAAAAAAAA",
+    label: "Lobby",
+    last_ip: DOCUMENTATION_IPV4,
+    last_online_at: "2026-08-19T12:00:00Z",
+    manifest_revision: 1,
+    online: true,
+    public_id: "scr_public_pairing",
+    revision: 1,
+    state: "active" as const,
+    updated_at: "2026-08-14T17:00:00.000Z",
+  };
+  transport.on("GET", "/api/v1/screens/scr_PAIRINGAAAAAAAAAAAAAAAA", () => ({
+    status: 200,
+    headers: { "x-request-id": "req_show_online" },
+    body: screen,
+  }));
+  const configDir = await testTemp("screen-show-online-");
+  const fsLike = { mkdir, open, rename, rm, chmod, stat, homedir: () => configDir, env: { XDG_CONFIG_HOME: configDir } };
+  await writeConfigAtomic(
+    path.join(configDir, "screenrig", "config.json"),
+    { api_url: "https://api.screenrig.ai", token: "sr_live_existing_secret" },
+    fsLike,
+  );
+
+  const jsonResult = await withRuntime(
+    ["--json", "screen", "show", "scr_PAIRINGAAAAAAAAAAAAAAAA"],
+    transport,
+    { fs: fsLike },
+  );
+  assert.equal(jsonResult.code, ExitCode.Success, jsonResult.stdout);
+  const envelope = JSON.parse(jsonResult.stdout) as {
+    ok: boolean;
+    data: { online?: boolean; last_online_at?: string; last_ip?: string };
+  };
+  assert.equal(envelope.ok, true);
+  assert.equal(envelope.data.online, true);
+  assert.equal(envelope.data.last_online_at, "2026-08-19T12:00:00Z");
+  assert.equal(envelope.data.last_ip, DOCUMENTATION_IPV4);
+
+  const humanResult = await withRuntime(
+    ["screen", "show", "scr_PAIRINGAAAAAAAAAAAAAAAA"],
+    transport,
+    { fs: fsLike },
+  );
+  assert.equal(humanResult.code, ExitCode.Success, humanResult.stdout);
+  assert.match(humanResult.stdout, /^Screen\n/);
+  assert.match(humanResult.stdout, /"online": true/);
+  assert.match(humanResult.stdout, /"last_online_at": "2026-08-19T12:00:00Z"/);
+  assert.match(humanResult.stdout, /"last_ip": "192.0.2.10"/);
+
+  screen.last_ip = DOCUMENTATION_IPV6;
+  const v6Result = await withRuntime(
+    ["--json", "screen", "show", "scr_PAIRINGAAAAAAAAAAAAAAAA"],
+    transport,
+    { fs: fsLike },
+  );
+  assert.equal(v6Result.code, ExitCode.Success, v6Result.stdout);
+  const v6Envelope = JSON.parse(v6Result.stdout) as { ok: boolean; data: { last_ip?: string } };
+  assert.equal(v6Envelope.data.last_ip, DOCUMENTATION_IPV6);
+  await rm(configDir, { recursive: true, force: true });
+});
+
+test("screen show still works when last_online_at and last_ip are absent", async () => {
+  const transport = new FakeTransport();
+  const screen = {
+    content_access_generation: 1,
+    created_at: "2026-08-14T17:00:00.000Z",
+    id: "scr_PAIRINGAAAAAAAAAAAAAAAA",
+    label: "Lobby",
+    manifest_revision: 1,
+    online: false,
+    public_id: "scr_public_pairing",
+    revision: 1,
+    state: "pairing_pending" as const,
+    updated_at: "2026-08-14T17:00:00.000Z",
+  };
+  transport.on("GET", "/api/v1/screens/scr_PAIRINGAAAAAAAAAAAAAAAA", () => ({
+    status: 200,
+    headers: { "x-request-id": "req_show_offline" },
+    body: screen,
+  }));
+  const configDir = await testTemp("screen-show-offline-");
+  const fsLike = { mkdir, open, rename, rm, chmod, stat, homedir: () => configDir, env: { XDG_CONFIG_HOME: configDir } };
+  await writeConfigAtomic(
+    path.join(configDir, "screenrig", "config.json"),
+    { api_url: "https://api.screenrig.ai", token: "sr_live_existing_secret" },
+    fsLike,
+  );
+
+  const result = await withRuntime(
+    ["--json", "screen", "show", "scr_PAIRINGAAAAAAAAAAAAAAAA"],
+    transport,
+    { fs: fsLike },
+  );
+  assert.equal(result.code, ExitCode.Success, result.stdout);
+  const envelope = JSON.parse(result.stdout) as {
+    ok: boolean;
+    data: { id: string; online?: boolean; last_online_at?: string; last_ip?: string };
+  };
+  assert.equal(envelope.ok, true);
+  assert.equal(envelope.data.id, "scr_PAIRINGAAAAAAAAAAAAAAAA");
+  assert.equal(envelope.data.online, false);
+  assert.equal(envelope.data.last_online_at, undefined);
+  assert.equal(envelope.data.last_ip, undefined);
+  assert.equal(JSON.stringify(envelope.data).includes("last_online_at"), false);
+  assert.equal(JSON.stringify(envelope.data).includes("last_ip"), false);
+  await rm(configDir, { recursive: true, force: true });
+});
+
+test("screen update cannot send online, last_online_at, or last_ip", async () => {
+  const transport = memoryBackend();
+  const { code, configDir } = await withRuntime(["--json", "screen", "pair", "ABC234"], transport);
+  assert.equal(code, ExitCode.Success);
+  const fsLike = { mkdir, open, rename, rm, chmod, stat, homedir: () => configDir, env: { XDG_CONFIG_HOME: configDir } };
+  transport.calls.length = 0;
+
+  const result = await withRuntime(
+    [
+      "--json", "screen", "update", "scr_PAIRINGAAAAAAAAAAAAAAAA",
+      "--name", "Lobby",
+      "--if-match", "1",
+      "--online", "true",
+      "--last-online-at", "2026-08-19T12:00:00Z",
+      "--last-ip", DOCUMENTATION_IPV4,
+    ],
+    transport,
+    { fs: fsLike },
+  );
+  assert.equal(result.code, ExitCode.Success, result.stdout);
+  const patch = transport.calls.find((call) => call.method === "PATCH");
+  assert.equal(patch?.path, "/api/v1/screens/scr_PAIRINGAAAAAAAAAAAAAAAA");
+  assert.deepEqual(patch?.body, { name: "Lobby" });
+  const patchJson = JSON.stringify(patch?.body);
+  assert.equal(patchJson.includes("online"), false);
+  assert.equal(patchJson.includes("last_online_at"), false);
+  assert.equal(patchJson.includes("last_ip"), false);
+  await rm(configDir, { recursive: true, force: true });
+});
+
 test("adding a schedule to a playlist an unzoned screen already runs is refused", async () => {
   const transport = memoryBackend();
   const { configDir, fsLike, file } = await scheduledPlaylistFixture(false, "tz-playlist-update-");