@vincentt-xr/cli 0.23.0 → 0.25.0

package/MIGRATION.md

@@ -3,16 +3,39 @@
 Per version, newest first. Read by the platform's own version surface and served to
 creators' agents. Accurate or absent, never speculative (B-F5-2).
 
+## 0.25.0
+
+required: false
+No action required. `vincentt preview` leads with the console page and no creator-facing screen prints a localhost address.
+- The start block prints `→ <project> · <workspace>` before the preview is created, then `✓ Preview is live`, then `Open the console:` with the project's console page, then `On a phone:` with the phone link and QR. The `→ Serving http://localhost:<port>` line is gone.
+- Running `vincentt preview` while one is running in the folder prints the same two blocks: the console page, then the phone link.
+- The not-signed-in screen ends with `Sign in:  vincentt login` and `Then start it again:  vincentt preview`. It no longer names the dev command or a local address. The preview's upgrade refusal likewise ends on the upgrade and `vincentt preview`.
+- When the dev server is down, the advisory reads `! Your dev server isn't responding on port <n>.`
+- `vincentt create` and `vincentt init` next steps no longer list the dev server; `vincentt preview` starts it. A non-interactive `create` that scaffolded without an account ends with `Signing in is what gives it an address a phone can open.`
+- The browser page at the end of `vincentt login` reads `You're Signed In` and `Go back to your AI assistant to continue.` The problem-report consent page reads `Problem Reports Are On` or `Problem Reports Are Off` with the same line. Neither mentions the terminal.
+
+## 0.24.0
+
+required: false
+No action required. `vincentt preview` accepts feedback from the console the CLI signs in through, and the relay now refuses marks outside fixed bounds.
+- The relay admits one browser origin besides the preview's own: the origin of the console the CLI is configured with (https, or http on this machine's loopback; anything else admits none). It answers that console's preflight and probe only on the annotation route, with that exact origin, never `*` and never with credentials.
+- The diagnostics socket, the diagnostics query and the feedback drain refuse the console origin with 403, like any other browser origin.
+- An annotation from any sender is refused with 400 and stored nowhere when a coordinate is outside [-1, 2], it has more than 50 marks, a pen path has more than 500 points, a note is over 2,000 characters, the message is over 110,000 characters, or `frameInImage` does not fit inside the screenshot's PNG size.
+- Also refused with 400: a mark whose colour is not red, yellow or blue, or whose number is not 1 to 50; more than 50 legacy strokes, pins or labels; a stroke over 500 points or with a colour that is not a short colour token; a pin label or label over 2,000 characters.
+- The stored annotation's `spec` is rebuilt from the fields the relay checked, so a field it does not know is dropped and never reaches the agent.
+- An annotation sent from the console carries no tester.
+- When the configured console is not the production console (a flag, an environment variable or the machine config can change it), the preview start block prints `Feedback is accepted from the console at <origin>`.
+
 ## 0.23.0
 
 required: false
 No action required. New verb `vincentt editor`, which hands the project to the Vincentt Editor desktop app.
-- `vincentt editor` (macOS 14 or later, no account) finds `Vincentt Editor.app` in `/Applications`, then `~/Applications`, checks it is signed by Vincentt, hands it the project folder and exits 0 with `✓ Sent <name> to Vincentt Editor.` It does not wait for the app. The app is a separate download from https://vincentt.studio/editor; the CLI installs no editor binary and has no port option for it.
+- `vincentt editor` (macOS 14 or later, no account) finds the Vincentt Editor app in the Mac's Applications folder, then in the user's own Applications folder, checks it is signed by Vincentt, hands it the project folder and exits 0 with `✓ Sent <name> to Vincentt Editor.` It does not wait for the app. The app is a separate download from https://vincentt.studio/editor; the CLI installs no editor binary and has no port option for it.
 - It exits 1, last line `Nothing was opened.`, when the app is not installed, the installed copy is not signed by Vincentt, the Mac is not on macOS 14 or later, or another copy of the app is running from a different folder.
 - `vincentt editor --json` prints one `vincentt.editor-open/1` object: `{"schema","handedOff":true,"project","app","appVersion"}`, or `handedOff: false` with a `reason` (`not_installed`, `bad_signature`, `unsupported_os`, `other_copy_running`, `open_failed`) and, where known, `app` and `detail`. The sentence goes to stderr.
 - `vincentt editor --selection [--json]` prints what is selected in the editor (`vincentt.editor-selection/1`), and `vincentt editor --status --json` the editor's state for the folder (`vincentt.editor-state/1`, including `app.lastOpen`). Both work on any OS and exit 1, with one JSON object still on stdout, when no editor is running for the folder.
 - In `--status --json`, `app` is always `{"version","lastOpen"}`; when no editor is running, `lastOpen` is reported only for a folder this machine handed over with `vincentt editor`, from a state file written after that hand-off, and is `null` otherwise.
-- The CLI keeps those hand-offs in `~/.vincentt/editor-handoffs.json`, as a hash of each folder's path and a time, never the path itself. A file written in a newer format than this CLI reads is refused with an upgrade line on stderr and nothing on stdout.
+- The CLI keeps those hand-offs in a file in its own settings folder, as a hash of each folder's path and a time, never the path itself. A file written in a newer format than this CLI reads is refused with an upgrade line on stderr and nothing on stdout.
 
 ## 0.22.0
 

package/README.md

@@ -108,9 +108,8 @@ later verbs run without prompting. `init` never reaches that gate at all.
 
 ## The loop, once a project exists
 
-- `pnpm dev` — local dev server at `http://localhost:5173`.
-- `npx vincentt preview` — build, serve, and tunnel the app so you get one `https`
-  URL (and a desktop QR page) to open on a phone. AR needs a secure context for
+- `npx vincentt preview` — start the dev server and tunnel the app, then hand over
+  the project's console page, which carries the phone link and its QR. AR needs a secure context for
   camera access, so this is how you test tracking and gestures on a device.
 - `npx vincentt logs | network | trace` — read what the phone reported to the
   preview relay. Debug on-device misbehavior instead of guessing.

package/dist/cli/index.js

@@ -39,7 +39,7 @@ import { USAGE_TEXT } from "./usage-text.js";
 import { PreviewUi } from "../preview/command.js";
 import { httpRelayClient } from "../lib/diagnostics.js";
 import { readLivePreview, relayInfoDir } from "../lib/relayInfo.js";
-import { attachedToRunning, mintRateLimited, noDiagnosticsStatic, notSignedIn, previewConflict, previewUserLimitRefused, settingsBanner, startBlock, } from "../preview/copy.js";
+import { attachedToRunning, bindingLine, mintRateLimited, noDiagnosticsStatic, notSignedIn, previewConflict, previewUserLimitRefused, settingsBanner, startBlock, } from "../preview/copy.js";
 import { chooseDevPort } from "../preview/devPort.js";
 import { isPortListening } from "../preview/net.js";
 import { readSettings, resolveSettings, SettingsError, TEMPLATE_DEFAULTS, validateField, } from "../lib/settings.js";
@@ -570,9 +570,6 @@ async function preview() {
     }
     const devCommand = settings.devCommand.value;
     const { port: devPort, fresh: devPortFresh } = await chooseDevPort(settings);
-    // What the creator gets running the dev command by hand, without PORT.
-    const handRunUrl = `http://localhost:${settings.devPort.value}`;
-    const localUrl = `http://localhost:${devPort}`;
     for (const l of settingsBanner({
         devCommand,
         devCommandSource: sourceWords(settings.devCommand),
@@ -589,7 +586,7 @@ async function preview() {
     // The gate is LOCAL and NOTHING IS ATTEMPTED: no spinner, no partial mint, no
     // session left in `pending`. The command stops before it touches the network.
     if (!(await currentToken())) {
-        for (const l of notSignedIn(devCommand, handRunUrl))
+        for (const l of notSignedIn())
             console.log(l);
         process.exitCode = EXIT.NOT_AUTHENTICATED;
         return;
@@ -600,7 +597,7 @@ async function preview() {
     const ui = new PreviewUi({
         print: (l) => console.log(l),
         now: () => Date.now(),
-        targetUrl: localUrl,
+        devPort,
         color,
         filterTester,
         filterViewer,
@@ -629,8 +626,10 @@ async function preview() {
             // No filter means the caller wanted the preview, not a diagnostics stream:
             // hand them the link and exit rather than blocking in the follow loop.
             // Following a live preview is what `vincentt logs`/`network`/`trace` are.
-            for (const l of attachedToRunning(existing.url, existing.expiresAt))
+            const consoleUrl = await projectConsoleUrl(cwd, existing.sessionId);
+            for (const l of attachedToRunning(existing.url, consoleUrl, existing.expiresAt)) {
                 console.log(l);
+            }
             return;
         }
         else {
@@ -642,11 +641,7 @@ async function preview() {
     let endingRefusal;
     let resolveDone;
     const refusedAtStart = (facts) => {
-        for (const l of upgradeRefusalLines(facts, {
-            kind: "preview_start",
-            devCommand,
-            localUrl: handRunUrl,
-        })) {
+        for (const l of upgradeRefusalLines(facts, { kind: "preview_start" })) {
             console.log(l);
         }
         process.exitCode = EXIT.UPGRADE_REQUIRED;
@@ -654,12 +649,21 @@ async function preview() {
     const done = new Promise((r) => {
         resolveDone = r;
     });
+    // The binding line prints BEFORE the mint: a wrong binding is cheap to catch
+    // only while no session exists. An unlinked folder prints none — previewStart
+    // refuses it, and a guessed name would be a line about the wrong project.
+    if (await locateProjectBinding(cwd)) {
+        for (const l of bindingLine(await projectDisplayName(cwd), await activeOrgName())) {
+            console.log(l);
+        }
+    }
     let running;
     try {
         const started = await previewStart(cwd, (m) => console.error(`[preview] ${m}`), {
             appPort: devPort,
             appPortFresh: devPortFresh,
             devCommand,
+            consoleUrl: (await resolveAuthUrls()).consoleUrl,
             onHiddenPath: (p) => ui.hiddenPath(p),
             appStdio: has("--verbose") ? "inherit" : "ignore",
             onViewer: (label, uaClass) => ui.viewerSeen(label, uaClass),
@@ -722,11 +726,12 @@ async function preview() {
         ? await renderTerminalQr(running.url).catch(() => undefined)
         : undefined;
     for (const l of startBlock({
-        projectName: await projectDisplayName(cwd),
-        orgName: await activeOrgName(),
-        targetUrl: `http://localhost:${running.appPort}`,
         url: running.url,
         consoleUrl: await projectConsoleUrl(cwd, running.sessionId),
+        feedbackOrigin: running.consoleOrigin !== undefined &&
+            running.consoleOrigin !== new URL(DEFAULT_CONSOLE_URL).origin
+            ? running.consoleOrigin
+            : undefined,
         qr,
         expiresInHours: 12,
     })) {

package/dist/dx/consent.js

@@ -195,7 +195,7 @@ export async function runConsentInBrowser(opts) {
                     value: result.decision,
                     page: {
                         status: 200,
-                        html: browserPage(granted, granted ? "Reports allowed" : "Not enabled", "Return to your terminal. You can close this tab."),
+                        html: browserPage(granted, granted ? "Problem Reports Are On" : "Problem Reports Are Off", "Go back to your AI assistant to continue."),
                     },
                 };
             }

package/dist/lib/initCommand.js

@@ -134,11 +134,13 @@ export async function initCommand(deps, opts = {}) {
         }
     }
     // The template ships a pnpm lockfile and a hoisted node-linker, so telling a
-    // creator to `npm run dev` in it produces a second lockfile and an unproven
+    // creator to `npm install` in it produces a second lockfile and an unproven
     // node_modules layout. Name the manager the scaffold is actually set up for.
     const pm = await detectPackageManager(target).catch(() => "npm");
     deps.print("");
     deps.print(`✓ Created ${label}`);
+    // No dev-server step: `vincentt preview` starts it, and the product never
+    // points the creator at the local loop (B-F3-6).
     const steps = [];
     // Keyed off the RESOLVED dir, not the flag — a prompted name needs the cd too.
     if (dir !== ".")
@@ -146,16 +148,18 @@ export async function initCommand(deps, opts = {}) {
     if (!installed || opts.skipInstall) {
         steps.push([`${pm} install`, "Install dependencies"]);
     }
-    steps.push([`${pm} run dev`, "Start the local dev server"]);
     if (!opts.from) {
-        deps.print("");
-        for (const line of alignedSteps(steps))
-            deps.print(line);
+        if (steps.length > 0) {
+            deps.print("");
+            for (const line of alignedSteps(steps))
+                deps.print(line);
+        }
         deps.print("");
         deps.print("  No account needed. When you're ready to put it online:");
         for (const line of alignedSteps([
             ["vincentt login", "Connect this machine to Vincentt"],
             ["vincentt create", "Register the project and reserve its address"],
+            ["vincentt preview", "Try it on your phone"],
         ])) {
             deps.print(line);
         }
@@ -181,6 +185,7 @@ export async function initCommand(deps, opts = {}) {
         return code;
     deps.print("");
     deps.print("  Next:");
+    steps.push(["vincentt preview", "Try it on your phone"]);
     for (const line of alignedSteps(steps))
         deps.print(line);
     return 0;

package/dist/lib/initFrom.js

@@ -86,10 +86,10 @@ export async function registerAfterScaffold(deps, opts = {}) {
             resume(deps.print, deps.dirLabel, resumeCommand, needsCd);
             if (scaffolded) {
                 deps.print("");
-                // B-F2-9(a): the open route must be named in something the creator's
-                // agent reads. On a non-TTY this output IS that artifact — the TTY
-                // branch's login prompt, which carries the same line, is unreachable here.
-                deps.print("  Or don't: the local dev loop needs no account.");
+                // B-F3-6 (amended): the product points only at the platform, so this
+                // ending names what signing in buys, never the local dev loop. The open
+                // route B-F2-9(a) requires stays named by the template's verb list.
+                deps.print("  Signing in is what gives it an address a phone can open.");
             }
             deps.print("");
             deps.print(closing);

package/dist/lib/lifecycle.js

@@ -176,6 +176,7 @@ export async function previewStart(projectCwd, onLog, extra = {}) {
         expiresAt: preview.expiresAt,
         pidStartTime: await readProcessStartTime(process.pid),
         token: preview.relayToken,
+        sessionId: preview.sessionId,
     });
     return { preview, started: true };
 }

package/dist/lib/projects.js

@@ -203,16 +203,15 @@ export async function createCommand(deps, opts = {}) {
     if (code !== 0 && code !== EXIT.DELIVERED_NOT_REGISTERED)
         return code;
     if (scaffolded) {
-        // This reader has never run the dev server, so the block that fits is the one
-        // `init` already ships for exactly this reader — two aligned columns off the
-        // DETECTED package manager, never a hardcoded one (the template ships a pnpm
-        // lockfile and a hoisted node-linker).
+        // Two aligned columns off the DETECTED package manager, never a hardcoded one
+        // (the template ships a pnpm lockfile and a hoisted node-linker). No dev-server
+        // step: `vincentt preview` starts it, and the product never points the creator
+        // at the local loop (B-F3-6).
         const steps = [];
         if (opts.dir)
             steps.push([`cd ${opts.dir}`, ""]);
         if (!installed || opts.skipInstall)
             steps.push([`${pm} install`, "Install dependencies"]);
-        steps.push([`${pm} run dev`, "Start the local dev server"]);
         steps.push(["vincentt preview", "Try it on your phone"]);
         deps.print("");
         for (const line of alignedSteps(steps))

package/dist/lib/relayInfo.d.ts

@@ -30,6 +30,12 @@ export interface RelayInfo {
      * whose relay asks for none.
      */
     token?: string;
+    /**
+     * The running session's id, so a re-run can hand over the console page that
+     * shows THIS preview rather than the bare project page. Never printed on its
+     * own; absent from markers written by an older CLI.
+     */
+    sessionId?: string;
 }
 export declare function relayInfoPath(cwd: string): string;
 /**

package/dist/login/pkceLogin.js

@@ -166,7 +166,7 @@ export async function runPkceLogin(opts) {
                     value: result.code,
                     page: {
                         status: 200,
-                        html: browserPage(true, "You're all set", "Return to your terminal. You can close this tab."),
+                        html: browserPage(true, "You're Signed In", "Go back to your AI assistant to continue."),
                     },
                 };
             }

package/dist/preview/command.d.ts

@@ -6,8 +6,8 @@ import { type UpgradeFacts } from "../shared/upgradeError.js";
 export interface PreviewUiDeps {
     print: (line: string) => void;
     now: () => number;
-    /** The forward target, named identically in the start block and the 502. */
-    targetUrl: string;
+    /** The forwarded dev port, named identically in the settings banner and the 502. */
+    devPort: number;
     color: boolean;
     /** Filter the stream to one tester (`--tester`) — one tab, across refreshes. */
     filterTester?: string;

package/dist/preview/command.js

@@ -238,7 +238,7 @@ export class PreviewUi {
         const settings = this.deps.devCommand !== undefined && this.deps.portSource !== undefined
             ? { devCommand: this.deps.devCommand, portSource: this.deps.portSource }
             : undefined;
-        this.lines(copy.originDown(this.deps.targetUrl, settings).map((l) => `  ${l}`));
+        this.lines(copy.originDown(this.deps.devPort, settings).map((l) => `  ${l}`));
     }
     originRecovered() {
         this.originDown = false;

package/dist/preview/copy.d.ts

@@ -1,33 +1,41 @@
+/**
+ * Flow L13 — the binding line, printed BEFORE the mint. The creator sees which
+ * project this folder is before anything is minted, the only moment a wrong
+ * binding is cheap to catch; the start block follows once the preview is live.
+ */
+export declare function bindingLine(projectName: string, orgName: string): string[];
+/** Flow L13 — the start block, after the binding line. */
 export interface StartBlockInput {
-    projectName: string;
-    orgName: string;
-    /** The forward target, printed BEFORE the URL so the 502 advisory matches it. */
-    targetUrl: string;
     url: string;
     /**
-     * The project's console page, or undefined for a folder with no binding. An
-     * unlinked folder gets NO console line rather than a guessed one — the same rule
-     * `consoleVerbCommand` follows, and for the same reason: a link to the wrong
-     * project is worse than no link.
+     * The project's console page. Always set on the start path, because a preview
+     * refuses an unlinked folder; kept optional so a missing binding prints NO
+     * console line rather than a guessed one — a link to the wrong project is worse
+     * than no link.
      */
     consoleUrl?: string;
+    /**
+     * The console origin the relay accepts feedback from, passed ONLY when it is
+     * not the production console. A flag or environment variable can point the
+     * CLI at another console, and the creator sees which one before any feedback
+     * arrives from it.
+     */
+    feedbackOrigin?: string;
     /** Pre-rendered QR rows, or undefined for non-TTY / piped / --no-qr. */
     qr?: string[];
     expiresInHours: number;
 }
 export declare function startBlock(i: StartBlockInput): string[];
 /**
- * Flow L14 — not signed in. The B2/B21 line, and the one screen that must not
- * feel like a wall.
+ * Flow L14 — not signed in.
  *
  * Line 1 is f1's exact string, so a creator meeting this gate in a second
- * command reads one product. The last paragraph is the most important copy in
- * f3's CLI: the overview commits that the local room stays a real room, and a
- * creator told only "sign in" has just been told the product does not work
- * without an account, which is false. It is offered as a CAPABILITY, not as
- * consolation — no "unfortunately", no "you can still".
+ * command reads one product. The second line is the reason, not a rule. No local
+ * alternative is offered (B-F3-6 as amended: the local loop keeps working, but
+ * no product surface points at it) — an agent reading this screen relays what
+ * it says, and the only thing to relay is: sign in.
  */
-export declare function notSignedIn(devCommand?: string, localUrl?: string): string[];
+export declare function notSignedIn(): string[];
 /**
  * Flow P1 — the two settings lines, printed right after resolution and before
  * the sign-in check, the mint and the spawn. They are the ONLY disclosure of the
@@ -65,9 +73,10 @@ export declare function followingFooter(): string[];
  * room over an `npm run dev` they forgot.
  *
  * The middle line splits the wire in two, because the creator's first instinct
- * on a 502 is to suspect us.
+ * on a 502 is to suspect us. It names the PORT, matching the settings banner,
+ * never a loopback URL an agent could paste.
  */
-export declare function originDown(targetUrl: string, settings?: {
+export declare function originDown(devPort: number, settings?: {
     devCommand: string;
     portSource: "flag" | "vincentt.json" | "default";
 }): string[];
@@ -190,10 +199,13 @@ export declare function supersededLoser(): string[];
  * each of those re-runs superseded the previous session: the link really did
  * keep changing, because the attach never printed one.
  *
- * The URL renders bare on its own line, matching the start block, so anything
- * scraping for a link finds it in the same shape either way.
+ * The two addresses render in the start block's order and shape (Flow L16a),
+ * console page first, so an agent that re-runs preview to recover a link finds
+ * the console page exactly where the start block put it. `consoleUrl` carries
+ * the running session when the marker holds its id, and is undefined only for an
+ * unlinked folder, which prints no console line rather than a guessed one.
  */
-export declare function attachedToRunning(url: string, expiresAt?: string): string[];
+export declare function attachedToRunning(url: string, consoleUrl?: string, expiresAt?: string): string[];
 /**
  * c. Superseded — the terminal that WON. This sits ABOVE the `✓ Preview is live`
  * block so the consequence is read before the URL is copied.

package/dist/preview/copy.js

@@ -16,53 +16,60 @@
 // session id, the edge hostname, or the workingTreeKey. The grant is the
 // sharpest — it transits an agent's tool-output transcript by default in this
 // product, so f1's "a token is never printed" extends to it verbatim.
-/** Flow L13 — the start block. */
 import { escapeControl, terminalSafe } from "../lib/terminalText.js";
 import { INSTALL_COMMAND } from "../shared/upgradeError.js";
-export function startBlock(i) {
-    const out = [
+/**
+ * Flow L13 — the binding line, printed BEFORE the mint. The creator sees which
+ * project this folder is before anything is minted, the only moment a wrong
+ * binding is cheap to catch; the start block follows once the preview is live.
+ */
+export function bindingLine(projectName, orgName) {
+    return [
         "",
         // The org is dropped rather than rendered as a dangling separator when it
         // is not known. `Museum AR Tour · ` reads as a truncated line — the one
         // moment a wrong binding is cheap to catch is the one moment the line must
         // not look broken.
-        i.orgName ? `→ ${i.projectName} · ${i.orgName}` : `→ ${i.projectName}`,
-        `→ Serving ${i.targetUrl}`,
-        "",
-        "✓ Preview is live",
-        "",
-        // The URL is on its own line, indented, unwrapped and UNADORNED. No `URL:`
-        // label, no backticks, no surrounding punctuation — it is the single
-        // most-copied string in the product, and anything beside it ends up in
-        // someone's paste.
-        `    ${i.url}`,
-        "",
+        orgName ? `→ ${projectName} · ${orgName}` : `→ ${projectName}`,
     ];
+}
+export function startBlock(i) {
+    // No loopback address: the settings banner already names the dev port, and a
+    // URL in this transcript is a URL an agent can paste. A loopback one reaches
+    // nobody but this machine (B-F3-6: the local loop works, no surface points at
+    // it).
+    const out = ["", "✓ Preview is live", ""];
+    // Each URL is on its own line, indented, unwrapped and UNADORNED. No `URL:`
+    // label, no backticks, no surrounding punctuation — anything beside it ends up
+    // in someone's paste.
+    //
+    // The console page comes FIRST: it carries the phone link, the QR, the live
+    // device view and Stop, so it is the one address an agent hands over, and the
+    // first one it reads.
+    if (i.consoleUrl) {
+        out.push("  Open the console:", "", `    ${i.consoleUrl}`, "");
+    }
+    out.push("  On a phone:", "", `    ${i.url}`, "");
     if (i.qr && i.qr.length > 0) {
         out.push(...i.qr.map((row) => `    ${row}`), "");
     }
     out.push("    Scan it, or open the link on any phone. No sign-in needed on the phone.", `    Expires in ${i.expiresInHours}h · Ctrl-C to stop`, "");
-    // BELOW the phone URL and its instruction, never above. The phone address is the
-    // line the creator is waiting on; a second URL printed first is a second thing to
-    // read before the one that matters. Dropped entirely when the folder is unlinked.
-    if (i.consoleUrl) {
-        out.push("  In the console:", "", `    ${i.consoleUrl}`, "");
+    if (i.feedbackOrigin) {
+        out.push(`  Feedback is accepted from the console at ${terminalSafe(i.feedbackOrigin)}`, "");
     }
     out.push("  Waiting for a device…", "");
     return out;
 }
 /**
- * Flow L14 — not signed in. The B2/B21 line, and the one screen that must not
- * feel like a wall.
+ * Flow L14 — not signed in.
  *
  * Line 1 is f1's exact string, so a creator meeting this gate in a second
- * command reads one product. The last paragraph is the most important copy in
- * f3's CLI: the overview commits that the local room stays a real room, and a
- * creator told only "sign in" has just been told the product does not work
- * without an account, which is false. It is offered as a CAPABILITY, not as
- * consolation — no "unfortunately", no "you can still".
+ * command reads one product. The second line is the reason, not a rule. No local
+ * alternative is offered (B-F3-6 as amended: the local loop keeps working, but
+ * no product surface points at it) — an agent reading this screen relays what
+ * it says, and the only thing to relay is: sign in.
  */
-export function notSignedIn(devCommand = "npm run dev", localUrl = "http://localhost:5173") {
+export function notSignedIn() {
     return [
         "",
         "✗ You're not signed in.",
@@ -70,10 +77,7 @@ export function notSignedIn(devCommand = "npm run dev", localUrl = "http://local
         "  A preview needs a hostname your phone can reach, and that needs an account.",
         "",
         "  Sign in:  vincentt login",
-        "",
-        `  Your local dev loop does not need one. Run \`${devCommand}\` and open`,
-        `  ${localUrl} on this machine. The camera works there.`,
-        "  What signing in adds is the phone.",
+        "  Then start it again:  vincentt preview",
         "",
     ];
 }
@@ -153,12 +157,13 @@ export function followingFooter() {
  * room over an `npm run dev` they forgot.
  *
  * The middle line splits the wire in two, because the creator's first instinct
- * on a 502 is to suspect us.
+ * on a 502 is to suspect us. It names the PORT, matching the settings banner,
+ * never a loopback URL an agent could paste.
  */
-export function originDown(targetUrl, settings) {
+export function originDown(devPort, settings) {
     if (settings === undefined) {
         return [
-            `! Your dev server isn't responding on ${targetUrl}.`,
+            `! Your dev server isn't responding on port ${devPort}.`,
             "",
             "  The preview is still live. The phone is reaching us; we can't reach your app.",
             "  Start it and reload the phone:  npm run dev",
@@ -176,7 +181,7 @@ export function originDown(targetUrl, settings) {
             ? "  If it runs on another port, pass that port with --port."
             : "  If it runs on another port, pass --port or add vincentt.json.";
     return [
-        `! Your dev server isn't responding on ${targetUrl}${source}.`,
+        `! Your dev server isn't responding on port ${devPort}${source}.`,
         "",
         "  The preview is still live. The phone is reaching us; we can't reach your app.",
         `  Start it and reload the phone:  ${settings.devCommand}`,
@@ -402,11 +407,18 @@ export function supersededLoser() {
  * each of those re-runs superseded the previous session: the link really did
  * keep changing, because the attach never printed one.
  *
- * The URL renders bare on its own line, matching the start block, so anything
- * scraping for a link finds it in the same shape either way.
+ * The two addresses render in the start block's order and shape (Flow L16a),
+ * console page first, so an agent that re-runs preview to recover a link finds
+ * the console page exactly where the start block put it. `consoleUrl` carries
+ * the running session when the marker holds its id, and is undefined only for an
+ * unlinked folder, which prints no console line rather than a guessed one.
  */
-export function attachedToRunning(url, expiresAt) {
-    const lines = ["", "→ A preview is already running for this folder.", "", url, ""];
+export function attachedToRunning(url, consoleUrl, expiresAt) {
+    const lines = ["", "→ A preview is already running for this folder.", ""];
+    if (consoleUrl) {
+        lines.push("  Open the console:", "", `    ${consoleUrl}`, "");
+    }
+    lines.push("  On a phone:", "", `    ${url}`, "");
     // Stated only when known: a marker written by an older CLI has no expiry, and
     // inventing one would be the over-claim this copy exists to avoid.
     if (expiresAt !== undefined) {

package/dist/preview/runner.d.ts

@@ -101,6 +101,11 @@ export interface StartPreviewOptions {
     appReadyTimeoutMs?: number;
     /** Progress sink. Never write app stdout to an MCP server's stdout. */
     onLog?: (message: string) => void;
+    /**
+     * The console this CLI signs in through, from the creator's own configuration.
+     * Its origin, if valid, may send feedback to the relay's annotation route.
+     */
+    consoleUrl?: string;
     /**
      * A viewer label appearing on a stream. Fires per OPEN, so the roster's
      * per-label idempotence is what keeps one device from announcing itself once
@@ -171,6 +176,8 @@ export interface RunningPreview {
     appPort: number;
     /** Whether the app was responding when we returned. */
     appReady: boolean;
+    /** The console origin the relay admits on its annotation route, if any. */
+    consoleOrigin?: string;
     /** Tear down the tunnel, the app dev serve, the front proxy and the relay. */
     stop: () => Promise<void>;
 }

package/dist/preview/runner.js

@@ -17,6 +17,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { realpath } from "node:fs/promises";
 import { createServer } from "node:http";
 import { TunnelClient, resolveForwardTarget, } from "../tunnel/index.js";
+import { consoleOriginOf } from "../relay/consoleOrigin.js";
 import { startRelay } from "../relay/server.js";
 import { mintRelayToken } from "../relay/guard.js";
 import { isHiddenAppPath, proxyWeb, proxyWs, relayRoute } from "./proxy.js";
@@ -168,10 +169,12 @@ export async function startPreview(opts) {
         }
         // Fixed here, from the server-computed URL, and never from a request.
         const previewOrigin = new URL(minted.url).origin;
+        const consoleOrigin = consoleOriginOf(opts.consoleUrl);
         relay = startRelay({
             port: relayPort,
             path: harnessPath,
             allowedOrigins: [previewOrigin],
+            consoleOrigin,
             token: relayToken,
             // Annotations land beside the binding, so `vincentt feedback` finds them
             // from anywhere in the tree rather than only from the folder that started
@@ -293,6 +296,7 @@ export async function startPreview(opts) {
             relayToken,
             appPort,
             appReady,
+            consoleOrigin,
             stop,
         };
     }

package/dist/relay/consoleOrigin.d.ts

@@ -0,0 +1,12 @@
+/** The console origin to admit for `consoleUrl`, or undefined to admit none. */
+export declare function consoleOriginOf(consoleUrl: string | undefined): string | undefined;
+/**
+ * Is this preflight one the relay answers? The Origin was already matched
+ * exactly. The method must be exactly POST, and the requested headers, parsed
+ * as a comma list, trimmed and lowercased, a subset of `content-type`.
+ */
+export declare function isConsolePreflight(method: string | string[] | undefined, requestHeaders: string | string[] | undefined): boolean;
+/** The CORS headers on a preflight the relay answers. Nothing else, ever. */
+export declare function preflightHeaders(consoleOrigin: string): Record<string, string>;
+/** The CORS headers on the probe and on every POST response to the console. */
+export declare function responseHeaders(consoleOrigin: string): Record<string, string>;

package/dist/relay/consoleOrigin.js

@@ -0,0 +1,68 @@
+// The one browser origin the relay admits besides the preview's own: the console
+// this CLI signs in through, and only on the annotation route.
+//
+// It comes from the creator's own configuration (flag, env, machine config),
+// never from a request and never from the folder's binding. A value that is not
+// exactly an https origin, or an http origin on this machine's loopback, grants
+// nothing, and the relay then behaves as one with no console origin at all.
+import { isLoopbackOrigin } from "./guard.js";
+/** The console origin to admit for `consoleUrl`, or undefined to admit none. */
+export function consoleOriginOf(consoleUrl) {
+    if (consoleUrl === undefined)
+        return undefined;
+    let url;
+    try {
+        url = new URL(consoleUrl.trim());
+    }
+    catch {
+        return undefined;
+    }
+    // `origin` is the literal "null" for every scheme without a host, so this one
+    // check refuses `javascript:`, `data:`, `file:` and a blob URL alike.
+    const origin = url.origin;
+    if (origin === "null" || origin === "*")
+        return undefined;
+    if (url.username !== "" || url.password !== "")
+        return undefined;
+    if (url.protocol === "https:")
+        return origin;
+    if (url.protocol === "http:" && isLoopbackOrigin(origin))
+        return origin;
+    return undefined;
+}
+/**
+ * Is this preflight one the relay answers? The Origin was already matched
+ * exactly. The method must be exactly POST, and the requested headers, parsed
+ * as a comma list, trimmed and lowercased, a subset of `content-type`.
+ */
+export function isConsolePreflight(method, requestHeaders) {
+    if (method !== "POST")
+        return false;
+    if (requestHeaders === undefined)
+        return true;
+    if (typeof requestHeaders !== "string")
+        return false;
+    if (requestHeaders.trim() === "")
+        return true;
+    return requestHeaders
+        .split(",")
+        .map((h) => h.trim().toLowerCase())
+        .every((h) => h === "content-type");
+}
+/** The CORS headers on a preflight the relay answers. Nothing else, ever. */
+export function preflightHeaders(consoleOrigin) {
+    return {
+        "access-control-allow-origin": consoleOrigin,
+        "access-control-allow-methods": "POST",
+        "access-control-allow-headers": "content-type",
+        "access-control-max-age": "600",
+        vary: "Origin",
+    };
+}
+/** The CORS headers on the probe and on every POST response to the console. */
+export function responseHeaders(consoleOrigin) {
+    return {
+        "access-control-allow-origin": consoleOrigin,
+        vary: "Origin",
+    };
+}

package/dist/relay/guard.d.ts

@@ -16,8 +16,9 @@ export declare function isAllowedOrigin(raw: string | string[] | undefined, allo
 export declare function isLoopbackOrigin(raw: string): boolean;
 /**
  * A cross-site form or `no-cors` fetch can only send `text/plain`, form or
- * multipart bodies without a preflight. Requiring JSON forces a preflight the
- * relay never answers.
+ * multipart bodies without a preflight. Requiring JSON forces a preflight, and
+ * the relay answers one only for the configured console origin, only on the
+ * annotation route.
  */
 export declare function isJsonContentType(raw: string | undefined): boolean;
 export declare function hasRelayToken(raw: string | string[] | undefined, token: string): boolean;

package/dist/relay/guard.js

@@ -1,8 +1,9 @@
 // The relay's request gate. Every caller the relay serves is on this machine:
 // the CLI (no Origin), the tunnel client and the front proxy (both rewrite Host
 // to the loopback target), and the preview page itself (its own minted origin).
-// A web page the creator happens to have open is none of those, and these checks
-// are what tell it apart.
+// The one exception is the creator's console, admitted on the annotation route
+// only (see consoleOrigin.ts). A web page the creator happens to have open is
+// none of those, and these checks are what tell it apart.
 import { randomBytes, timingSafeEqual } from "node:crypto";
 /** The header carrying the per-session token on the local-only routes. */
 export const RELAY_TOKEN_HEADER = "x-vincentt-relay-token";
@@ -55,8 +56,9 @@ export function isLoopbackOrigin(raw) {
 }
 /**
  * A cross-site form or `no-cors` fetch can only send `text/plain`, form or
- * multipart bodies without a preflight. Requiring JSON forces a preflight the
- * relay never answers.
+ * multipart bodies without a preflight. Requiring JSON forces a preflight, and
+ * the relay answers one only for the configured console origin, only on the
+ * annotation route.
  */
 export function isJsonContentType(raw) {
     if (raw === undefined)

package/dist/relay/server.d.ts

@@ -64,6 +64,15 @@ export interface RelayOptions {
      * loopback pass, which is what a standalone `vincentt relay` serves.
      */
     allowedOrigins?: readonly string[];
+    /**
+     * The console this CLI signs in through, already validated (`consoleOriginOf`).
+     * Admitted on the annotation route ONLY: its preflight and probe are answered
+     * there and its POST carries CORS headers. It is never added to
+     * `allowedOrigins`, which also gates the WebSocket, so the diagnostics socket,
+     * `/query` and `feedback/next` refuse it like any foreign origin. Omitted, the
+     * relay admits no console.
+     */
+    consoleOrigin?: string;
     /**
      * The per-session secret `/query` and `feedback/next` require in
      * `x-vincentt-relay-token`. The preview always sets it; without it those
@@ -136,3 +145,9 @@ export declare function isUnsafeRelayPath(rawUrl: string): boolean;
  * number before it reaches a timer.
  */
 export declare function feedbackTimeoutMs(raw: string | null): number;
+/**
+ * The body as UTF-8, decoded ONCE from the joined bytes: decoding each chunk on
+ * its own turns a multi-byte character split across two chunks into U+FFFD.
+ * The size limit is in bytes.
+ */
+export declare function readBody(req: IncomingMessage, maxBytes?: number): Promise<string>;

package/dist/relay/server.js

@@ -10,6 +10,8 @@ import { EventStore } from "./store.js";
 import { TesterRegistry, isTesterId } from "./testers.js";
 import { AnnotationStore } from "./annotations.js";
 import { RELAY_TOKEN_HEADER, hasRelayToken, isAllowedHost, isAllowedOrigin, isJsonContentType, } from "./guard.js";
+import { isConsolePreflight, preflightHeaders, responseHeaders, } from "./consoleOrigin.js";
+import { boundedSpec } from "./specBounds.js";
 import { VIEWER_LABEL_RE, VIEWER_STAMP_HEADER } from "../tunnel/index.js";
 /** Cap an annotation POST body so a bad/huge upload can't exhaust memory. */
 const MAX_ANNOTATION_BYTES = 25 * 1024 * 1024;
@@ -56,6 +58,7 @@ export function startRelay(opts = {}) {
         host,
         port: boundPort(),
         allowedOrigins,
+        consoleOrigin: opts.consoleOrigin,
         token: opts.token,
         store,
         annotations,
@@ -144,7 +147,9 @@ export function startRelay(opts = {}) {
         });
         ws.on("close", () => log("client disconnected"));
     });
-    http.listen(port, host, () => log(`relay listening on ${host}:${port} (ws ${wsPath}, http /query)`));
+    // Port only: this line reaches `vincentt preview`'s transcript, and a loopback
+    // address there is one an agent can paste and hand over.
+    http.listen(port, host, () => log(`relay listening on port ${port} (ws ${wsPath}, http /query)`));
     return {
         store,
         annotations,
@@ -208,9 +213,22 @@ function handleHttp(req, res, ctx) {
         res.writeHead(403).end();
         return;
     }
+    const annotationRoute = p === `${ctx.wsPath}/annotation`;
+    // The console origin is matched HERE, inside the annotation route, and never
+    // joins the origin list: that list also gates the WebSocket, and a console
+    // page reaching the diagnostics socket is the hole this placement closes.
+    // Exact string equality, so `null`, a duplicated header, a trailing slash and
+    // a case variant all miss.
+    const fromConsole = annotationRoute &&
+        ctx.consoleOrigin !== undefined &&
+        req.headers.origin === ctx.consoleOrigin;
+    if (annotationRoute && req.method === "OPTIONS") {
+        handlePreflight(req, res, ctx, fromConsole);
+        return;
+    }
     // The local-only routes have no browser caller at all, so any Origin is foreign.
     const origins = localOnly ? [] : ctx.allowedOrigins;
-    if (!isAllowedOrigin(req.headers.origin, origins)) {
+    if (!fromConsole && !isAllowedOrigin(req.headers.origin, origins)) {
         ctx.log("refused a request from a foreign Origin");
         res.writeHead(403).end();
         return;
@@ -221,6 +239,26 @@ function handleHttp(req, res, ctx) {
             return;
         }
     }
+    // On EVERY status from here, so the console can read a refusal as well as a
+    // 200 and never retries an annotation the relay already stored.
+    if (fromConsole) {
+        for (const [k, v] of Object.entries(responseHeaders(ctx.consoleOrigin))) {
+            res.setHeader(k, v);
+        }
+    }
+    if (annotationRoute && req.method === "GET") {
+        // The console's probe: presence only, and it writes nothing.
+        if (!fromConsole) {
+            res.writeHead(405).end();
+            return;
+        }
+        res.writeHead(ctx.annotations ? 204 : 503).end();
+        return;
+    }
+    if (annotationRoute && req.method !== "POST") {
+        res.writeHead(405).end();
+        return;
+    }
     if (req.method === "POST" && !isJsonContentType(req.headers["content-type"])) {
         res.writeHead(415).end();
         return;
@@ -229,7 +267,9 @@ function handleHttp(req, res, ctx) {
         handleQuery(req, res, url, ctx);
         return;
     }
-    if (p === `${ctx.wsPath}/annotation`) {
+    if (annotationRoute) {
+        if (fromConsole)
+            ctx.log("annotation from the console origin");
         handleAnnotationPost(req, res, ctx);
         return;
     }
@@ -239,6 +279,27 @@ function handleHttp(req, res, ctx) {
     }
     res.writeHead(404).end();
 }
+/**
+ * The console's CORS preflight on the annotation route. Answered only for the
+ * exact console origin asking for POST with at most `content-type`; anything
+ * else is 403 with no CORS header at all. Never `*`, never credentials, never a
+ * private-network grant.
+ */
+function handlePreflight(req, res, ctx, fromConsole) {
+    if (!fromConsole) {
+        ctx.log("refused a preflight from a foreign Origin");
+        res.writeHead(403).end();
+        return;
+    }
+    const ok = isConsolePreflight(req.headers["access-control-request-method"], req.headers["access-control-request-headers"]);
+    if (!ok) {
+        ctx.log("refused a console preflight for a method or header it does not allow");
+        res.writeHead(403).end();
+        return;
+    }
+    ctx.log("answered a console preflight");
+    res.writeHead(204, preflightHeaders(ctx.consoleOrigin)).end();
+}
 // The CLI (same laptop) GETs/POSTs /query with a RelayQuery, carrying the
 // session token from the 0600 relay marker.
 function handleQuery(req, res, url, ctx) {
@@ -279,6 +340,16 @@ function handleAnnotationPost(req, res, ctx) {
             res.writeHead(400).end("annotation requires message + screenshot");
             return;
         }
+        // Refused, never clamped: the agent acts on these values, and a stored
+        // coordinate must be exactly the one that was sent.
+        // What is stored is the spec REBUILT from the checked fields, never the
+        // body's own object: an unknown key would otherwise ride to the agent.
+        const bounded = boundedSpec(input);
+        if (!bounded.ok) {
+            ctx.log("refused marks out of bounds");
+            res.writeHead(400).end("annotation marks out of bounds");
+            return;
+        }
         // The annotation's session key is RESOLVED, never assigned — `resolve`,
         // not `attribute`. This route is unauthenticated and reachable by anyone
         // holding the capability URL, so a door that minted here would let 64 bare
@@ -288,7 +359,12 @@ function handleAnnotationPost(req, res, ctx) {
         // The key is still hostile input either way: the record reaches an agent's
         // context on the consumer's stdout, so the raw string must never survive
         // onto it.
-        const annotation = await ctx.annotations.add({ ...input, sessionId: ctx.testers.resolve(input.sessionId) }, { now: Date.now(), id: ctx.makeId() });
+        const annotation = await ctx.annotations.add({
+            message: input.message,
+            screenshot: input.screenshot,
+            spec: bounded.spec,
+            sessionId: ctx.testers.resolve(input.sessionId),
+        }, { now: Date.now(), id: ctx.makeId() });
         // The live stream is told an annotation ARRIVED, with the resolved tester
         // and nothing else. It is a fact, not a directive: the consumer is the
         // long-poll, and a terminal line naming what to run would be the platform
@@ -299,7 +375,11 @@ function handleAnnotationPost(req, res, ctx) {
             .end(JSON.stringify({ id: annotation.id, seq: annotation.seq }));
     })
         .catch((err) => {
-        ctx.log(`annotation error: ${err}`);
+        // A fixed line, never the error's text: a JSON.parse message quotes the
+        // body, which is hostile input, and this log reaches the terminal.
+        ctx.log(err instanceof SyntaxError
+            ? "annotation error: the body is not JSON"
+            : "annotation error: not stored (too large, or the write failed)");
         if (!res.headersSent)
             res.writeHead(400).end();
     });
@@ -397,9 +477,14 @@ async function readQuery(req, url) {
         q.presence = true;
     return normalizeTester(q);
 }
-function readBody(req, maxBytes = Infinity) {
+/**
+ * The body as UTF-8, decoded ONCE from the joined bytes: decoding each chunk on
+ * its own turns a multi-byte character split across two chunks into U+FFFD.
+ * The size limit is in bytes.
+ */
+export function readBody(req, maxBytes = Infinity) {
     return new Promise((resolve, reject) => {
-        let data = "";
+        const chunks = [];
         let bytes = 0;
         req.on("data", (c) => {
             bytes += c.length;
@@ -408,9 +493,9 @@ function readBody(req, maxBytes = Infinity) {
                 req.destroy();
                 return;
             }
-            data += c;
+            chunks.push(c);
         });
-        req.on("end", () => resolve(data));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
         req.on("error", reject);
     });
 }

package/dist/relay/specBounds.d.ts

@@ -0,0 +1,39 @@
+import type { AnnotationInput, AnnotationSpec } from "@vincentt-xr/harness/events";
+export declare const COORD_MIN = -1;
+export declare const COORD_MAX = 2;
+export declare const MAX_SHAPES = 50;
+export declare const MAX_STROKES = 50;
+export declare const MAX_PINS = 50;
+export declare const MAX_LABELS = 50;
+export declare const MAX_PATH_POINTS = 500;
+export declare const MAX_NOTE_CHARS = 2000;
+export declare const MAX_MESSAGE_CHARS = 110000;
+/** The mark colours every sender draws with: the keys of the harness's MARK_COLORS. */
+export declare const MARK_COLOR_NAMES: ReadonlySet<string>;
+/**
+ * The width and height a PNG data URL's IHDR declares, or undefined when it is
+ * not a PNG data URL. Reads only the first 24 decoded bytes; never decodes the
+ * image.
+ */
+export declare function pngSize(dataUrl: string): {
+    width: number;
+    height: number;
+} | undefined;
+/** Refused, or in bounds with the `spec` to store (undefined when none was sent). */
+export type BoundedSpec = {
+    ok: false;
+} | {
+    ok: true;
+    spec?: AnnotationSpec;
+};
+/**
+ * Check an annotation's message and marks, and rebuild `spec` from the fields
+ * that passed. Assumes the caller already checked `message` and `screenshot` are
+ * strings.
+ *
+ * `spec` absent, `{}` and `{shapes: []}` are all in bounds. A field the relay
+ * does not know is not an error; it is simply not stored.
+ */
+export declare function boundedSpec(input: AnnotationInput): BoundedSpec;
+/** Whether an annotation's message and marks are within bounds. */
+export declare function isWithinBounds(input: AnnotationInput): boolean;

package/dist/relay/specBounds.js

@@ -0,0 +1,157 @@
+// The annotation's marks are hostile input the agent then acts on, from any
+// sender: the phone, the console, or anyone holding the preview address. The
+// relay refuses an annotation outside these bounds rather than clamping it, and
+// stores a `spec` REBUILT from the fields it checked: an unknown key is dropped,
+// so what reaches the agent is exactly what was validated, value for value.
+//
+// Coordinates are picture-relative: [0,1] spans the picture and a value outside
+// it is a point past the picture's edge. No sender's drawing margin reaches past
+// [-1, 2].
+export const COORD_MIN = -1;
+export const COORD_MAX = 2;
+export const MAX_SHAPES = 50;
+export const MAX_STROKES = 50;
+export const MAX_PINS = 50;
+export const MAX_LABELS = 50;
+export const MAX_PATH_POINTS = 500;
+export const MAX_NOTE_CHARS = 2_000;
+export const MAX_MESSAGE_CHARS = 110_000;
+/** The mark colours every sender draws with: the keys of the harness's MARK_COLORS. */
+export const MARK_COLOR_NAMES = new Set(["red", "yellow", "blue"]);
+/**
+ * A legacy stroke's colour, which an app could set itself: a mark colour name, a
+ * hex colour, or one short lowercase word. Never free text.
+ */
+const STROKE_COLOR_RE = /^(?:#[0-9a-fA-F]{3,8}|[a-z]{1,16})$/;
+const SHAPE_TYPES = new Set(["rect", "circle", "arrow", "pen"]);
+const PNG_PREFIX = "data:image/png;base64,";
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/** Thrown inside the rebuild; never escapes `boundedSpec`. */
+class Refused extends Error {
+}
+const refuse = () => {
+    throw new Refused();
+};
+const isRec = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const coord = (v) => typeof v === "number" && Number.isFinite(v) && v >= COORD_MIN && v <= COORD_MAX
+    ? v
+    : refuse();
+const size = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : refuse();
+const point = (v) => isRec(v) ? { x: coord(v.x), y: coord(v.y) } : refuse();
+const text = (v) => typeof v === "string" && v.length <= MAX_NOTE_CHARS ? v : refuse();
+const list = (v, max) => Array.isArray(v) && v.length <= max ? v : refuse();
+const path = (v) => list(v, MAX_PATH_POINTS).map(point);
+function shape(v) {
+    if (!isRec(v))
+        return refuse();
+    if (typeof v.type !== "string" || !SHAPE_TYPES.has(v.type))
+        return refuse();
+    const n = typeof v.n === "number" && Number.isInteger(v.n) && v.n >= 1 && v.n <= MAX_SHAPES
+        ? v.n
+        : refuse();
+    const color = typeof v.color === "string" && MARK_COLOR_NAMES.has(v.color) ? v.color : refuse();
+    const base = { n, color, ...(v.note === undefined ? {} : { note: text(v.note) }) };
+    if (v.type === "arrow")
+        return { ...base, type: "arrow", from: point(v.from), to: point(v.to) };
+    if (v.type === "pen")
+        return { ...base, type: "pen", points: path(v.points) };
+    const [x, y, w, h] = [coord(v.x), coord(v.y), size(v.w), size(v.h)];
+    // The far corner is a coordinate too. Its sum carries float error, so it alone
+    // gets a hair of tolerance; every coordinate a sender wrote is checked exactly.
+    if (x + w > COORD_MAX + 1e-9 || y + h > COORD_MAX + 1e-9)
+        return refuse();
+    return { ...base, type: v.type, x, y, w, h };
+}
+function stroke(v) {
+    if (!isRec(v))
+        return refuse();
+    const out = { points: path(v.points) };
+    if (v.color !== undefined) {
+        if (typeof v.color !== "string" || !STROKE_COLOR_RE.test(v.color))
+            return refuse();
+        out.color = v.color;
+    }
+    return out;
+}
+function pin(v) {
+    if (!isRec(v))
+        return refuse();
+    const out = { x: coord(v.x), y: coord(v.y) };
+    if (v.label !== undefined)
+        out.label = text(v.label);
+    return out;
+}
+/**
+ * The width and height a PNG data URL's IHDR declares, or undefined when it is
+ * not a PNG data URL. Reads only the first 24 decoded bytes; never decodes the
+ * image.
+ */
+export function pngSize(dataUrl) {
+    if (!dataUrl.startsWith(PNG_PREFIX))
+        return undefined;
+    // 32 base64 characters decode to exactly the 24 header bytes.
+    const head = Buffer.from(dataUrl.slice(PNG_PREFIX.length, PNG_PREFIX.length + 32), "base64");
+    if (head.length < 24)
+        return undefined;
+    if (!PNG_SIGNATURE.every((b, i) => head[i] === b))
+        return undefined;
+    if (head.toString("latin1", 12, 16) !== "IHDR")
+        return undefined;
+    return { width: head.readUInt32BE(16), height: head.readUInt32BE(20) };
+}
+function frameInImage(v, screenshot) {
+    if (!isRec(v))
+        return refuse();
+    const { x, y, w, h } = v;
+    if (![x, y, w, h].every((n) => typeof n === "number" && Number.isInteger(n)))
+        return refuse();
+    const [fx, fy, fw, fh] = [x, y, w, h];
+    if (fx < 0 || fy < 0 || fw < 1 || fh < 1)
+        return refuse();
+    const image = pngSize(screenshot) ?? refuse();
+    if (fx + fw > image.width || fy + fh > image.height)
+        return refuse();
+    return { x: fx, y: fy, w: fw, h: fh };
+}
+/**
+ * Check an annotation's message and marks, and rebuild `spec` from the fields
+ * that passed. Assumes the caller already checked `message` and `screenshot` are
+ * strings.
+ *
+ * `spec` absent, `{}` and `{shapes: []}` are all in bounds. A field the relay
+ * does not know is not an error; it is simply not stored.
+ */
+export function boundedSpec(input) {
+    if (input.message.length > MAX_MESSAGE_CHARS)
+        return { ok: false };
+    const raw = input.spec;
+    if (raw === undefined)
+        return { ok: true };
+    try {
+        if (!isRec(raw))
+            return refuse();
+        const spec = {};
+        if (raw.shapes !== undefined)
+            spec.shapes = list(raw.shapes, MAX_SHAPES).map(shape);
+        if (raw.strokes !== undefined)
+            spec.strokes = list(raw.strokes, MAX_STROKES).map(stroke);
+        if (raw.pins !== undefined)
+            spec.pins = list(raw.pins, MAX_PINS).map(pin);
+        if (raw.labels !== undefined)
+            spec.labels = list(raw.labels, MAX_LABELS).map(text);
+        if (raw.note !== undefined)
+            spec.note = text(raw.note);
+        if (raw.frameInImage !== undefined)
+            spec.frameInImage = frameInImage(raw.frameInImage, input.screenshot);
+        return { ok: true, spec };
+    }
+    catch (err) {
+        if (err instanceof Refused)
+            return { ok: false };
+        throw err;
+    }
+}
+/** Whether an annotation's message and marks are within bounds. */
+export function isWithinBounds(input) {
+    return boundedSpec(input).ok;
+}

package/dist/shared/upgradeError.d.ts

@@ -50,8 +50,6 @@ export type RefusalArm = {
     stillServing?: number;
 } | {
     kind: "preview_start";
-    devCommand: string;
-    localUrl: string;
 };
 /** Flow L22: the version refusal on any verb, in the arm that knows where it landed. */
 export declare function upgradeRefusalLines(facts: UpgradeFacts, arm?: RefusalArm, own?: string): string[];

package/dist/shared/upgradeError.js

@@ -171,11 +171,10 @@ export function upgradeRefusalLines(facts, arm = { kind: "generic" }, own = clie
         "",
         remedy(variant),
     ];
+    // No local-loop paragraph on preview_start (B-F3-6 as amended): the remedy is
+    // the upgrade, and the screen ends on the command that leads back to a preview.
     if (variant !== "not_received")
         out.push(thenLine(arm));
-    if (arm.kind === "preview_start") {
-        out.push("", `  Your local dev loop does not need an upgrade. Run \`${arm.devCommand}\` and open`, `  ${arm.localUrl} on this machine. The camera works there.`);
-    }
     out.push("");
     return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",
@@ -28,7 +28,7 @@
     "qrcode": "^1.5.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8",
-    "@vincentt-xr/harness": "3.1.0"
+    "@vincentt-xr/harness": "3.2.0"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.5",