@vincentt-xr/harness 1.4.0 → 1.5.0

package/dist/client/channel.d.ts

@@ -1,4 +1,4 @@
-import { type AnnouncedPreset, type ConsoleSetMediaSourceMessage, type HarnessAnnounceMessage } from "../shared/channel.js";
+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 {
@@ -13,6 +13,16 @@ export interface ChannelOptions {
     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`. */
@@ -21,12 +31,23 @@ export interface ChannelOptions {
     framing?: FramingView;
 }
 /**
- * The announce, built from a preset list.
+ * 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[]): HarnessAnnounceMessage;
+export declare function buildAnnounce(presets: AnnouncedPreset[], handlers?: Pick<ChannelOptions, "onSetRenderHold">): HarnessAnnounceMessage;
 /**
  * Is this a command this app acts on?
  *
@@ -36,6 +57,15 @@ export declare function buildAnnounce(presets: AnnouncedPreset[]): HarnessAnnoun
  * 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.
  *

package/dist/client/channel.js

@@ -1,11 +1,16 @@
 // The app side of the console↔app channel.
 //
-// It does two things and refuses everything else: it announces its own presets
-// ONCE on mount, and it listens for `set-media-source`. It never acknowledges,
-// never reports an outcome, never re-announces, never counts, and never requests
+// 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";
@@ -39,14 +44,25 @@ function isValidPreset(preset) {
     return true;
 }
 /**
- * The announce, built from a preset list.
+ * 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) {
+export function buildAnnounce(presets, handlers = {}) {
     const valid = presets.filter(isValidPreset).slice(0, ANNOUNCE_MAX_PRESETS);
-    return {
+    const announce = {
         source: HARNESS_MESSAGE_SOURCE,
         v: CHANNEL_PROTOCOL_VERSION,
         type: "announce",
@@ -57,6 +73,9 @@ export function buildAnnounce(presets) {
             mirrored: p.mirrored,
         })),
     };
+    if (handlers.onSetRenderHold)
+        announce.capabilities = ["render-hold"];
+    return announce;
 }
 /**
  * Is this a command this app acts on?
@@ -80,6 +99,26 @@ export function isSetMediaSourceCommand(data) {
         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.
  *
@@ -107,9 +146,21 @@ export function openConsoleChannel(opts) {
         // about — and no test could see it, because none delivered a null source.
         if (event.source !== view.parent)
             return;
-        if (!isSetMediaSourceCommand(event.data))
+        // 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;
-        opts.onSetMediaSource(event.data.presetId);
+        }
+        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
@@ -119,7 +170,7 @@ export function openConsoleChannel(opts) {
     // 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);
+    const announce = buildAnnounce(opts.presets, opts);
     for (const origin of allowed) {
         try {
             view.parent?.postMessage(announce, origin);

package/dist/client/index.d.ts

@@ -3,9 +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, type ChannelOptions, type ChannelWindow, } from "./channel.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, ANNOUNCE_MAX_PRESETS, type AnnouncedPreset, type PresetKind, type HarnessAnnounceMessage, type ConsoleSetMediaSourceMessage, } from "../shared/channel.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,7 +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, } from "./channel.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, ANNOUNCE_MAX_PRESETS, } from "../shared/channel.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/shared/channel.d.ts

@@ -1,9 +1,9 @@
 /** 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 one. */
-export declare const CONSOLE_INBOUND_MESSAGE_TYPES: readonly ["set-media-source"];
+/** 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"];
+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. */
@@ -15,6 +15,18 @@ 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.
  *
@@ -37,14 +49,34 @@ export interface HarnessAnnounceMessage {
     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. The only command name that exists. */
+/** 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.
  *
@@ -56,5 +88,12 @@ export interface ConsoleSetMediaSourceMessage {
 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

@@ -1,6 +1,6 @@
 // The console↔app channel's wire contract. Pure data: no DOM, no React, no node.
 //
-// The console mirrors these two names in its own `contract.ts`. They ship on
+// 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
@@ -13,10 +13,17 @@
 // 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 one. */
-export const CONSOLE_INBOUND_MESSAGE_TYPES = ["set-media-source"];
+/** 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,
@@ -30,6 +37,17 @@ export const CONSOLE_MESSAGE_SOURCE = "vincentt-console";
 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.
  *
@@ -41,5 +59,12 @@ export const PRESET_KINDS = ["video", "image", "camera"];
 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.4.0",
+  "version": "1.5.0",
   "description": "Vincentt AR dev-loop harness - in-app diagnostics provider + wire contract",
   "license": "UNLICENSED",
   "type": "module",