@vincentt-xr/harness 1.3.0 → 1.5.0

package/dist/client/HarnessProvider.js

@@ -9,6 +9,7 @@
 // but both are overridable for the production review-service path later.
 import { useEffect } from "react";
 import { CLIENT_SESSION_ID_RE } from "../shared/events.js";
+import { isFramed } from "./previewOrigin.js";
 function defaultRelayUrl() {
     if (typeof window === "undefined")
         return "ws://localhost:7331";
@@ -108,7 +109,8 @@ export function HarnessProvider(props) {
         //
         // Share defaults to `enabled`. Feedback defaults to `enabled` too (opt OUT
         // with `feedback={false}`); the chip gates itself on the origin at mount, so
-        // the flag only decides whether the module is fetched at all.
+        // the flag decides whether the module is fetched at all — as does the
+        // framing check hoisted into `mountFeedback` below.
         if (props.share !== false) {
             void import("./share.js").then(({ mountShareButton }) => {
                 if (cancelled)
@@ -126,6 +128,16 @@ export function HarnessProvider(props) {
         function mountFeedback() {
             if (props.feedback === false)
                 return;
+            // THE FRAMING CHECK RUNS BEFORE THE IMPORT, not only inside the mount.
+            // `mountFeedbackButton` gates itself too (defence in depth), but that gate
+            // runs after the module has already been fetched and evaluated — so the
+            // annotation module, which carries an unauthenticated same-origin write
+            // path, was being loaded inside the framed document that now holds a
+            // camera delegation. Nothing was appended and no chip rendered, so there
+            // was no redress target; the code was simply present. Hoisting the check
+            // here closes that outright rather than mitigating it.
+            if (isFramed())
+                return;
             void import("./annotate.js").then(({ mountFeedbackButton }) => {
                 if (cancelled)
                     return;

package/dist/client/channel.d.ts

@@ -0,0 +1,77 @@
+import { type AnnouncedPreset, type ConsoleSetMediaSourceMessage, type ConsoleSetRenderHoldMessage, type HarnessAnnounceMessage } from "../shared/channel.js";
+import { type FramingView } from "./previewOrigin.js";
+/** The minimum of `window` this needs, so the whole module is testable without a DOM. */
+export interface ChannelWindow {
+    parent: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    } | null;
+    addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+}
+export interface ChannelOptions {
+    /** The presets this app can play. Announced verbatim after validation. */
+    presets: AnnouncedPreset[];
+    /** Applied when the console names a preset. The app owns the swap; the console never does. */
+    onSetMediaSource: (presetId: string) => void;
+    /**
+     * Called when the console asks the app to freeze or resume its own render.
+     *
+     * SUPPLYING THIS IS WHAT DECLARES THE CAPABILITY — see `buildAnnounce`. The
+     * harness holds no opinion about how the app holds; it hands over `held` and
+     * the app decides what stops. Omit it and the app declares nothing and the
+     * console renders no control, which is the correct state for an app that
+     * cannot hold.
+     */
+    onSetRenderHold?: (held: boolean) => void;
+    /** The console origins commands may come from. Injected; defaults to the production set. */
+    allowedOrigins?: readonly string[];
+    /** Injectable for tests. Defaults to `window`. */
+    view?: ChannelWindow;
+    /** Injectable for tests. Defaults to `window`'s own handles. */
+    framing?: FramingView;
+}
+/**
+ * The announce, built from a preset list and the app's WIRED handlers.
+ *
+ * Exported so a test can assert the payload's exact shape without a window, and
+ * so `url` never being on the wire is checkable at the boundary that produces it.
+ *
+ * THE CAPABILITY IS DERIVED, NEVER DECLARED. The second parameter is the handler
+ * itself, not a capability list, so there is no way to spell a declaration the
+ * app cannot honour: `render-hold` appears exactly when `onSetRenderHold` was
+ * supplied. An app that declared it without implementing it would render a live
+ * button that does nothing, and the console cannot detect that — there is no ack,
+ * by design — so this boundary is the only place it is preventable.
+ *
+ * The key is OMITTED rather than set to `[]` when nothing is wired: an old
+ * harness omits it, and emitting an empty array would hand the console a second
+ * shape meaning the same thing.
+ */
+export declare function buildAnnounce(presets: AnnouncedPreset[], handlers?: Pick<ChannelOptions, "onSetRenderHold">): HarnessAnnounceMessage;
+/**
+ * Is this a command this app acts on?
+ *
+ * Shape check only — the origin is checked separately and BOTH must pass. Any
+ * other `type` on a well-formed envelope is ignored, which is what keeps `ack`,
+ * `error`, `log`, `count`, `re-announce` and `request` from becoming reachable
+ * by a console that decides to send one.
+ */
+export declare function isSetMediaSourceCommand(data: unknown): data is ConsoleSetMediaSourceMessage;
+/**
+ * Is this a hold command this app acts on?
+ *
+ * Shape check only, mirroring `isSetMediaSourceCommand` — the origin and the
+ * source are checked separately and ALL must pass. `held` is required to be a
+ * real boolean rather than coerced: a truthy string arriving as `held` would
+ * freeze an app that could never be told to resume by the same mistake.
+ */
+export declare function isSetRenderHoldCommand(data: unknown): data is ConsoleSetRenderHoldMessage;
+/**
+ * Open the app's side of the channel. Returns a teardown.
+ *
+ * UNFRAMED IS A NO-OP. With no console around the app there is nothing to
+ * announce to and no chrome to command it, and the app keeps its own in-page
+ * controls instead. Nothing is posted and no listener is installed — the same
+ * absent-rather-than-inert rule the cluster controls follow.
+ */
+export declare function openConsoleChannel(opts: ChannelOptions): () => void;

package/dist/client/channel.js

@@ -0,0 +1,186 @@
+// The app side of the console↔app channel.
+//
+// It does two things and refuses everything else: it announces ONCE on mount,
+// and it listens for the console's commands. It never acknowledges, never
+// reports an outcome, never re-announces, never counts, and never requests
+// (B-F13-3). The transport is bidirectional — postMessage has no one-way mode —
+// so the vocabulary in `shared/channel.ts` and the single-send guard below are
+// the only cap there is.
+//
+// It carries the hold command and does not perform the hold. The harness has
+// ZERO coupling to r3f/three, and that absence is load-bearing rather than
+// incidental: it is what lets the harness be transport with no opinion about the
+// app. The app freezes itself in its own render tree.
+import { ANNOUNCE_MAX_PRESETS, CHANNEL_PROTOCOL_VERSION, CONSOLE_MESSAGE_SOURCE, HARNESS_MESSAGE_SOURCE, PRESET_ID_RE, PRESET_KINDS, PRESET_MAX_ID_LENGTH, PRESET_MAX_LABEL_LENGTH, } from "../shared/channel.js";
+import { isAllowedConsoleOrigin, PRODUCTION_CONSOLE_ORIGINS } from "./consoleOrigin.js";
+import { isFramed } from "./previewOrigin.js";
+/**
+ * Is this a well-formed preset the console can render?
+ *
+ * Applied to the app's OWN list before it goes out, which is not paranoia: the
+ * presets come from the SDK or from creator code, and an oversized or malformed
+ * announce is dropped whole by the console rather than partially rendered. A
+ * validated send means a drop on the far side is a version mismatch and never a
+ * payload we could have caught here.
+ */
+function isValidPreset(preset) {
+    if (typeof preset !== "object" || preset === null)
+        return false;
+    const p = preset;
+    if (typeof p.id !== "string" || p.id.length > PRESET_MAX_ID_LENGTH)
+        return false;
+    if (!PRESET_ID_RE.test(p.id))
+        return false;
+    if (typeof p.label !== "string" || p.label.length === 0)
+        return false;
+    if (p.label.length > PRESET_MAX_LABEL_LENGTH)
+        return false;
+    if (typeof p.kind !== "string")
+        return false;
+    if (!PRESET_KINDS.includes(p.kind))
+        return false;
+    if (typeof p.mirrored !== "boolean")
+        return false;
+    return true;
+}
+/**
+ * The announce, built from a preset list and the app's WIRED handlers.
+ *
+ * Exported so a test can assert the payload's exact shape without a window, and
+ * so `url` never being on the wire is checkable at the boundary that produces it.
+ *
+ * THE CAPABILITY IS DERIVED, NEVER DECLARED. The second parameter is the handler
+ * itself, not a capability list, so there is no way to spell a declaration the
+ * app cannot honour: `render-hold` appears exactly when `onSetRenderHold` was
+ * supplied. An app that declared it without implementing it would render a live
+ * button that does nothing, and the console cannot detect that — there is no ack,
+ * by design — so this boundary is the only place it is preventable.
+ *
+ * The key is OMITTED rather than set to `[]` when nothing is wired: an old
+ * harness omits it, and emitting an empty array would hand the console a second
+ * shape meaning the same thing.
+ */
+export function buildAnnounce(presets, handlers = {}) {
+    const valid = presets.filter(isValidPreset).slice(0, ANNOUNCE_MAX_PRESETS);
+    const announce = {
+        source: HARNESS_MESSAGE_SOURCE,
+        v: CHANNEL_PROTOCOL_VERSION,
+        type: "announce",
+        presets: valid.map((p) => ({
+            id: p.id,
+            label: p.label,
+            kind: p.kind,
+            mirrored: p.mirrored,
+        })),
+    };
+    if (handlers.onSetRenderHold)
+        announce.capabilities = ["render-hold"];
+    return announce;
+}
+/**
+ * Is this a command this app acts on?
+ *
+ * Shape check only — the origin is checked separately and BOTH must pass. Any
+ * other `type` on a well-formed envelope is ignored, which is what keeps `ack`,
+ * `error`, `log`, `count`, `re-announce` and `request` from becoming reachable
+ * by a console that decides to send one.
+ */
+export function isSetMediaSourceCommand(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const m = data;
+    if (m.source !== CONSOLE_MESSAGE_SOURCE)
+        return false;
+    if (m.v !== CHANNEL_PROTOCOL_VERSION)
+        return false;
+    if (m.type !== "set-media-source")
+        return false;
+    if (typeof m.presetId !== "string" || m.presetId.length > PRESET_MAX_ID_LENGTH)
+        return false;
+    return PRESET_ID_RE.test(m.presetId);
+}
+/**
+ * Is this a hold command this app acts on?
+ *
+ * Shape check only, mirroring `isSetMediaSourceCommand` — the origin and the
+ * source are checked separately and ALL must pass. `held` is required to be a
+ * real boolean rather than coerced: a truthy string arriving as `held` would
+ * freeze an app that could never be told to resume by the same mistake.
+ */
+export function isSetRenderHoldCommand(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const m = data;
+    if (m.source !== CONSOLE_MESSAGE_SOURCE)
+        return false;
+    if (m.v !== CHANNEL_PROTOCOL_VERSION)
+        return false;
+    if (m.type !== "set-render-hold")
+        return false;
+    return typeof m.held === "boolean";
+}
+/**
+ * Open the app's side of the channel. Returns a teardown.
+ *
+ * UNFRAMED IS A NO-OP. With no console around the app there is nothing to
+ * announce to and no chrome to command it, and the app keeps its own in-page
+ * controls instead. Nothing is posted and no listener is installed — the same
+ * absent-rather-than-inert rule the cluster controls follow.
+ */
+export function openConsoleChannel(opts) {
+    const view = opts.view ??
+        (typeof window === "undefined" ? undefined : window);
+    if (!view)
+        return () => undefined;
+    if (!isFramed(opts.framing))
+        return () => undefined;
+    const allowed = opts.allowedOrigins ?? PRODUCTION_CONSOLE_ORIGINS;
+    const onMessage = (event) => {
+        // BOTH checks, and neither is sufficient. Iteration 1 shipped this channel
+        // with source-equality alone (archived SEV-3), which made any embedding page
+        // the de-facto parent and let it drive the runtime.
+        if (!isAllowedConsoleOrigin(event.origin, allowed))
+            return;
+        // Fail CLOSED on a missing source, matching the console side. Tolerating null
+        // here left one of the pair non-binding — the SEV-3 shape this comment warns
+        // about — and no test could see it, because none delivered a null source.
+        if (event.source !== view.parent)
+            return;
+        // Both commands clear the IDENTICAL two checks above before any dispatch.
+        // Neither name is privileged and neither has its own gate — a second command
+        // is one more branch inside a parser that already validates by exact match
+        // against a closed set, which is the whole reason growing the vocabulary is
+        // cheap and growing the CHECKS would not be.
+        if (isSetMediaSourceCommand(event.data)) {
+            opts.onSetMediaSource(event.data.presetId);
+            return;
+        }
+        if (isSetRenderHoldCommand(event.data)) {
+            // An app with no handler ignores it in silence. It never declared the
+            // capability, so a console sending this is speaking to the wrong app —
+            // and there is no channel to say so on.
+            opts.onSetRenderHold?.(event.data.held);
+        }
+    };
+    view.addEventListener("message", onMessage);
+    // ONE MESSAGE, ONCE. Posted to each allowed console origin explicitly — never
+    // "*", which is the outgoing half of the same archived SEV-3. Only the real
+    // parent's origin matches, so the others are delivered nowhere.
+    //
+    // There is deliberately no re-announce, no retry and no interval: a console
+    // that mounts after the app misses it and stays in its waiting state, which is
+    // the honest failure the design chose over a channel that keeps talking.
+    const announce = buildAnnounce(opts.presets, opts);
+    for (const origin of allowed) {
+        try {
+            view.parent?.postMessage(announce, origin);
+        }
+        catch {
+            // A refused target origin is not an error the app reports anywhere — there
+            // is no channel to report it on, by construction.
+        }
+    }
+    return () => {
+        view.removeEventListener("message", onMessage);
+    };
+}

package/dist/client/consoleOrigin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The production console origins. A closed, exact set.
+ *
+ * Both are real deployed consoles (`project_console_workspace_vs_org_naming`:
+ * the console is `console.vincentt.studio`). Adding an entry here is a visible,
+ * reviewable act — which is what makes the artifact assertion meaningful.
+ */
+export declare const PRODUCTION_CONSOLE_ORIGINS: readonly ["https://console.vincentt.studio", "https://console.staging.vincentt.studio"];
+/**
+ * Is this origin one the console may command us from?
+ *
+ * `origins` is injected so the predicate is pure and the dev set can be supplied
+ * by a caller that has it, rather than reached by an import this module would
+ * then carry into every published bundle.
+ */
+export declare function isAllowedConsoleOrigin(origin: unknown, origins?: readonly string[]): boolean;

package/dist/client/consoleOrigin.js

@@ -0,0 +1,39 @@
+// The compiled-in console-origin allowlist — the app side's inbound check.
+//
+// THIS MODULE SHIPS IN CREATORS' PRODUCTION BUNDLES. @vincentt-xr/harness is a
+// published npm package installed into creators' own apps, so whatever is written
+// here to make local development work is present in every published bundle,
+// where anything holding a local port — a second dev server, a local tool's web
+// UI, a malicious postinstall binding a port — could post a command into a live
+// preview. That is why the dev origins are not in this file at all; see
+// `consoleOriginDev.dev.ts` and the `*.dev.ts` exclusion in `tsconfig.build.json`.
+//
+// EXACT-STRING EQUALITY, never a prefix, a suffix, a `startsWith` or a regex.
+// `event.origin` is already a browser-normalised origin string, so set membership
+// is the whole check. A prefix test admits `https://console.vincentt.studio.evil.com`,
+// which is the standard way this check is broken; a suffix test on a hostname is
+// what `isPreviewOrigin` does deliberately for a WILDCARD apex, and a fixed set
+// of two origins is not that case.
+/**
+ * The production console origins. A closed, exact set.
+ *
+ * Both are real deployed consoles (`project_console_workspace_vs_org_naming`:
+ * the console is `console.vincentt.studio`). Adding an entry here is a visible,
+ * reviewable act — which is what makes the artifact assertion meaningful.
+ */
+export const PRODUCTION_CONSOLE_ORIGINS = [
+    "https://console.vincentt.studio",
+    "https://console.staging.vincentt.studio",
+];
+/**
+ * Is this origin one the console may command us from?
+ *
+ * `origins` is injected so the predicate is pure and the dev set can be supplied
+ * by a caller that has it, rather than reached by an import this module would
+ * then carry into every published bundle.
+ */
+export function isAllowedConsoleOrigin(origin, origins = PRODUCTION_CONSOLE_ORIGINS) {
+    if (typeof origin !== "string" || origin === "")
+        return false;
+    return origins.includes(origin);
+}

package/dist/client/index.d.ts

@@ -3,6 +3,9 @@ export type { HarnessProviderProps } from "./HarnessProvider.js";
 export { sendAnnotation, captureScreenshot, mountFeedbackButton, shouldShowFeedback, type SendAnnotationOptions, type FeedbackButtonOptions, } from "./annotate.js";
 export { mountShareButton, deriveShareUrl, isPhone, isPreviewOrigin, renderQr, PREVIEW_APEXES, type ShareButtonOptions, } from "./share.js";
 export { isFramed, type FramingView } from "./previewOrigin.js";
+export { openConsoleChannel, buildAnnounce, isSetMediaSourceCommand, isSetRenderHoldCommand, type ChannelOptions, type ChannelWindow, } from "./channel.js";
+export { isAllowedConsoleOrigin, PRODUCTION_CONSOLE_ORIGINS } from "./consoleOrigin.js";
+export { CHANNEL_MESSAGE_TYPES, HARNESS_OUTBOUND_MESSAGE_TYPES, CONSOLE_INBOUND_MESSAGE_TYPES, HARNESS_MESSAGE_SOURCE, CONSOLE_MESSAGE_SOURCE, CHANNEL_PROTOCOL_VERSION, PRESET_KINDS, APP_CAPABILITIES, ANNOUNCE_MAX_PRESETS, ANNOUNCE_MAX_CAPABILITIES, type AnnouncedPreset, type PresetKind, type AppCapability, type HarnessAnnounceMessage, type ConsoleSetMediaSourceMessage, type ConsoleSetRenderHoldMessage, } from "../shared/channel.js";
 export { getClusterContainer, releaseClusterContainer } from "./cluster.js";
 export type { DiagEvent, LogEvent, NetworkEvent, TraceEvent } from "../shared/events.js";
 export type { Annotation, AnnotationInput, AnnotationSpec, AnnotationStroke, AnnotationPin, } from "../shared/events.js";

package/dist/client/index.js

@@ -6,4 +6,7 @@ export { HarnessProvider } from "./HarnessProvider.js";
 export { sendAnnotation, captureScreenshot, mountFeedbackButton, shouldShowFeedback, } from "./annotate.js";
 export { mountShareButton, deriveShareUrl, isPhone, isPreviewOrigin, renderQr, PREVIEW_APEXES, } from "./share.js";
 export { isFramed } from "./previewOrigin.js";
+export { openConsoleChannel, buildAnnounce, isSetMediaSourceCommand, isSetRenderHoldCommand, } from "./channel.js";
+export { isAllowedConsoleOrigin, PRODUCTION_CONSOLE_ORIGINS } from "./consoleOrigin.js";
+export { CHANNEL_MESSAGE_TYPES, HARNESS_OUTBOUND_MESSAGE_TYPES, CONSOLE_INBOUND_MESSAGE_TYPES, HARNESS_MESSAGE_SOURCE, CONSOLE_MESSAGE_SOURCE, CHANNEL_PROTOCOL_VERSION, PRESET_KINDS, APP_CAPABILITIES, ANNOUNCE_MAX_PRESETS, ANNOUNCE_MAX_CAPABILITIES, } from "../shared/channel.js";
 export { getClusterContainer, releaseClusterContainer } from "./cluster.js";

package/dist/client/share.d.ts

@@ -1,3 +1,4 @@
+import { type FramingView } from "./previewOrigin.js";
 export { isPhone, isPreviewOrigin, PREVIEW_APEXES } from "./previewOrigin.js";
 /**
  * The canonical preview URL to encode — `origin + "/"`, stable across in-app SPA
@@ -16,13 +17,23 @@ export interface ShareButtonOptions {
     matchMedia?: typeof window.matchMedia;
     /** Injectable for tests. Defaults to `window.location`. */
     location?: Pick<Location, "origin" | "protocol" | "hostname">;
+    /** Injectable for tests. Defaults to `window`'s own handles. */
+    view?: FramingView;
 }
 /**
  * Mount the icon-only Share chip into the shared cluster and wire its popover.
  *
- * The show-gate is evaluated ONCE, here at mount: render iff the viewer is not a
- * phone AND the origin is a real preview origin. If the gate fails, nothing is
- * appended to the DOM (no disabled state) and the returned unmount is a no-op.
+ * The show-gate is evaluated ONCE, here at mount: render iff the document is not
+ * framed AND the viewer is not a phone AND the origin is a real preview origin.
+ * If the gate fails, nothing is appended to the DOM (no disabled state) and the
+ * returned unmount is a no-op.
+ *
+ * THE FRAMED VETO. The console renders its own Share control beside the frame,
+ * so an in-frame chip would give the creator two Share buttons in one workspace
+ * — and this one is inside a document that now holds a camera delegation, which
+ * makes an overlay near the frame boundary read as console UI. GATED, NOT
+ * DELETED: an unframed local preview (`vincentt preview` opened directly) has no
+ * console chrome around it to take over, and keeps its Share.
  *
  * Returns an unmount function that removes the chip + popover, tears down listeners,
  * and releases the shared cluster.

package/dist/client/share.js

@@ -11,7 +11,7 @@
 // whole module — and `qrcode`, reached only from here — tree-shakes out of prod.
 import QRCode from "qrcode";
 import { getClusterContainer, releaseClusterContainer } from "./cluster.js";
-import { isPhone, isPreviewOrigin } from "./previewOrigin.js";
+import { isFramed, isPhone, isPreviewOrigin } from "./previewOrigin.js";
 // The viewer/origin predicates moved to the dependency-free `previewOrigin.ts` so
 // the feedback chip can gate on them without importing this module (and with it
 // `qrcode`). Re-exported here because this is the path every existing caller and
@@ -46,9 +46,17 @@ const QR_GLYPH_SVG = `<svg width="18" height="18" viewBox="0 0 24 24" fill="curr
 /**
  * Mount the icon-only Share chip into the shared cluster and wire its popover.
  *
- * The show-gate is evaluated ONCE, here at mount: render iff the viewer is not a
- * phone AND the origin is a real preview origin. If the gate fails, nothing is
- * appended to the DOM (no disabled state) and the returned unmount is a no-op.
+ * The show-gate is evaluated ONCE, here at mount: render iff the document is not
+ * framed AND the viewer is not a phone AND the origin is a real preview origin.
+ * If the gate fails, nothing is appended to the DOM (no disabled state) and the
+ * returned unmount is a no-op.
+ *
+ * THE FRAMED VETO. The console renders its own Share control beside the frame,
+ * so an in-frame chip would give the creator two Share buttons in one workspace
+ * — and this one is inside a document that now holds a camera delegation, which
+ * makes an overlay near the frame boundary read as console UI. GATED, NOT
+ * DELETED: an unframed local preview (`vincentt preview` opened directly) has no
+ * console chrome around it to take over, and keeps its Share.
  *
  * Returns an unmount function that removes the chip + popover, tears down listeners,
  * and releases the shared cluster.
@@ -60,7 +68,7 @@ export function mountShareButton(opts = {}) {
     const location = opts.location ?? (typeof window !== "undefined" ? window.location : undefined);
     if (!location)
         return () => undefined;
-    const show = !isPhone(matchMedia) && isPreviewOrigin(location);
+    const show = !isFramed(opts.view) && !isPhone(matchMedia) && isPreviewOrigin(location);
     if (!show)
         return () => undefined;
     const url = deriveShareUrl(location);

package/dist/shared/channel.d.ts

@@ -0,0 +1,99 @@
+/** The app→console message names. Exactly one, and adding a second is the failure. */
+export declare const HARNESS_OUTBOUND_MESSAGE_TYPES: readonly ["announce"];
+/** The console→app message names. Exactly two. */
+export declare const CONSOLE_INBOUND_MESSAGE_TYPES: readonly ["set-media-source", "set-render-hold"];
+/** The whole channel vocabulary, both directions. */
+export declare const CHANNEL_MESSAGE_TYPES: readonly ["announce", "set-media-source", "set-render-hold"];
+export type HarnessOutboundMessageType = (typeof HARNESS_OUTBOUND_MESSAGE_TYPES)[number];
+export type ConsoleInboundMessageType = (typeof CONSOLE_INBOUND_MESSAGE_TYPES)[number];
+/** Envelope discriminator for app→console traffic. */
+export declare const HARNESS_MESSAGE_SOURCE = "vincentt-harness";
+/** Envelope discriminator for console→app traffic. */
+export declare const CONSOLE_MESSAGE_SOURCE = "vincentt-console";
+/** The channel's protocol version. Bumped only with both repos in one release. */
+export declare const CHANNEL_PROTOCOL_VERSION = 1;
+/** The media kinds a preset may declare. Closed — an unknown kind drops the announce. */
+export declare const PRESET_KINDS: readonly ["video", "image", "camera"];
+export type PresetKind = (typeof PRESET_KINDS)[number];
+/**
+ * What an app may declare it CAN DO. Closed and validated exactly as
+ * `PRESET_KINDS` is — an unknown entry is dropped rather than passed through.
+ *
+ * A capability is a property of the app's own code, never a report of its
+ * current condition: `render-hold` says *this app carries a hold handler*, not
+ * *this app is held*. The console renders a control on the strength of it and
+ * can never learn whether the app acted, so the declaration has to be derived
+ * from the wiring rather than written by hand — see `buildAnnounce`.
+ */
+export declare const APP_CAPABILITIES: readonly ["render-hold"];
+export type AppCapability = (typeof APP_CAPABILITIES)[number];
+/**
+ * One announced preset — CAPABILITY, not observation.
+ *
+ * `url` is deliberately NOT on the wire (security SHOULD-FIX 5.1). The console
+ * names an `id` and the app resolves it against the SDK list it already holds,
+ * so a creator-controlled URL never reaches console chrome to be rendered as an
+ * `href`, a `src`, or a thumbnail. If the console does not render it, it must
+ * not receive it.
+ */
+export interface AnnouncedPreset {
+    id: string;
+    label: string;
+    kind: PresetKind;
+    /** Whether the SDK mirrors this source. The console renders the difference it now causes. */
+    mirrored: boolean;
+}
+/** app → console, posted ONCE on mount to the console's exact origin. */
+export interface HarnessAnnounceMessage {
+    source: typeof HARNESS_MESSAGE_SOURCE;
+    v: typeof CHANNEL_PROTOCOL_VERSION;
+    type: "announce";
+    presets: AnnouncedPreset[];
+    /**
+     * OPTIONAL, and the key is OMITTED when there is nothing to declare — never
+     * `[]`. An old harness omits it, so a console reading `undefined` cannot tell
+     * an old app from a new one that declares nothing, and must not be given two
+     * shapes to mean the same thing.
+     */
+    capabilities?: readonly AppCapability[];
+}
+/** console → app. Applies a named media preset. */
+export interface ConsoleSetMediaSourceMessage {
+    source: typeof CONSOLE_MESSAGE_SOURCE;
+    v: typeof CHANNEL_PROTOCOL_VERSION;
+    type: "set-media-source";
+    presetId: string;
+}
+/**
+ * console → app. Freezes or resumes the app's own render loop.
+ *
+ * `held` is absolute, never a toggle: the console tracks only what it last sent
+ * and cannot read the app, so a toggle would drift the moment one message was
+ * dropped and neither side could tell.
+ */
+export interface ConsoleSetRenderHoldMessage {
+    source: typeof CONSOLE_MESSAGE_SOURCE;
+    v: typeof CHANNEL_PROTOCOL_VERSION;
+    type: "set-render-hold";
+    held: boolean;
+}
+/**
+ * Caps on an inbound announce, mirrored by the console's own validator.
+ *
+ * They live in the shared contract rather than in the parser so both repos
+ * refuse the same payload: a cap enforced on one side only means the sender can
+ * emit something the receiver silently drops, which is the drift this file exists
+ * to prevent.
+ */
+export declare const ANNOUNCE_MAX_PRESETS = 32;
+export declare const PRESET_MAX_ID_LENGTH = 64;
+export declare const PRESET_MAX_LABEL_LENGTH = 120;
+/**
+ * The same class of cap as `ANNOUNCE_MAX_PRESETS`, and it exists for the same
+ * reason: the receiver must be able to refuse an oversized list BEFORE walking
+ * it, and both repos must refuse the identical payload. It is comfortably above
+ * `APP_CAPABILITIES.length` so growing the closed set does not require moving it.
+ */
+export declare const ANNOUNCE_MAX_CAPABILITIES = 8;
+/** Conservative id grammar. Ids are ours; a label is creator-facing text, an id is not. */
+export declare const PRESET_ID_RE: RegExp;

package/dist/shared/channel.js

@@ -0,0 +1,70 @@
+// The console↔app channel's wire contract. Pure data: no DOM, no React, no node.
+//
+// The console mirrors these three names in its own `contract.ts`. They ship on
+// DIFFERENT release cadences — @vincentt-xr/harness is caret-pinned and reaches
+// old projects on a plain reinstall, the console deploys independently — so a
+// rename in one lands in creators' apps weeks apart from the other, and the
+// channel then fails into a permanent waiting state indistinguishable from an
+// old project. That is why the vocabulary is a pinned constant in both repos
+// rather than a string literal at each call site.
+//
+// B-F13-3, and the reason this file is a CLOSED set rather than a union that
+// grows: the app declares its own capability, once, and never reports an
+// observation. postMessage has no one-way mode — both directions of the
+// transport are open at all times — so the vocabulary is the only cap there is,
+// and a vocabulary is a convention until a test asserts it.
+//
+// THE ONE-WAY LINE IS UNCHANGED BY THE SECOND COMMAND. Console→app grew to two
+// names; app→console is still exactly one, still posted once on mount. The
+// announce's `capabilities` field is the app declaring WHAT IT CAN DO — the same
+// class of fact as its preset list, which B-F13-3 permits in terms — and never
+// what it is doing. Capability crosses; observation does not. A second app→console
+// name, or an ack for `set-render-hold`, would be the breach.
+/** The app→console message names. Exactly one, and adding a second is the failure. */
+export const HARNESS_OUTBOUND_MESSAGE_TYPES = ["announce"];
+/** The console→app message names. Exactly two. */
+export const CONSOLE_INBOUND_MESSAGE_TYPES = ["set-media-source", "set-render-hold"];
+/** The whole channel vocabulary, both directions. */
+export const CHANNEL_MESSAGE_TYPES = [
+    ...HARNESS_OUTBOUND_MESSAGE_TYPES,
+    ...CONSOLE_INBOUND_MESSAGE_TYPES,
+];
+/** Envelope discriminator for app→console traffic. */
+export const HARNESS_MESSAGE_SOURCE = "vincentt-harness";
+/** Envelope discriminator for console→app traffic. */
+export const CONSOLE_MESSAGE_SOURCE = "vincentt-console";
+/** The channel's protocol version. Bumped only with both repos in one release. */
+export const CHANNEL_PROTOCOL_VERSION = 1;
+/** The media kinds a preset may declare. Closed — an unknown kind drops the announce. */
+export const PRESET_KINDS = ["video", "image", "camera"];
+/**
+ * What an app may declare it CAN DO. Closed and validated exactly as
+ * `PRESET_KINDS` is — an unknown entry is dropped rather than passed through.
+ *
+ * A capability is a property of the app's own code, never a report of its
+ * current condition: `render-hold` says *this app carries a hold handler*, not
+ * *this app is held*. The console renders a control on the strength of it and
+ * can never learn whether the app acted, so the declaration has to be derived
+ * from the wiring rather than written by hand — see `buildAnnounce`.
+ */
+export const APP_CAPABILITIES = ["render-hold"];
+/**
+ * Caps on an inbound announce, mirrored by the console's own validator.
+ *
+ * They live in the shared contract rather than in the parser so both repos
+ * refuse the same payload: a cap enforced on one side only means the sender can
+ * emit something the receiver silently drops, which is the drift this file exists
+ * to prevent.
+ */
+export const ANNOUNCE_MAX_PRESETS = 32;
+export const PRESET_MAX_ID_LENGTH = 64;
+export const PRESET_MAX_LABEL_LENGTH = 120;
+/**
+ * The same class of cap as `ANNOUNCE_MAX_PRESETS`, and it exists for the same
+ * reason: the receiver must be able to refuse an oversized list BEFORE walking
+ * it, and both repos must refuse the identical payload. It is comfortably above
+ * `APP_CAPABILITIES.length` so growing the closed set does not require moving it.
+ */
+export const ANNOUNCE_MAX_CAPABILITIES = 8;
+/** Conservative id grammar. Ids are ours; a label is creator-facing text, an id is not. */
+export const PRESET_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/harness",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Vincentt AR dev-loop harness - in-app diagnostics provider + wire contract",
   "license": "UNLICENSED",
   "type": "module",