@vincentt-xr/harness 1.2.0 → 1.4.0

package/dist/client/channel.js

@@ -0,0 +1,135 @@
+// 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
+// (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.
+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.
+ *
+ * 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.
+ */
+export function buildAnnounce(presets) {
+    const valid = presets.filter(isValidPreset).slice(0, ANNOUNCE_MAX_PRESETS);
+    return {
+        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,
+        })),
+    };
+}
+/**
+ * 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);
+}
+/**
+ * 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;
+        if (!isSetMediaSourceCommand(event.data))
+            return;
+        opts.onSetMediaSource(event.data.presetId);
+    };
+    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);
+    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

@@ -1,7 +1,11 @@
 export { HarnessProvider } from "./HarnessProvider.js";
 export type { HarnessProviderProps } from "./HarnessProvider.js";
-export { sendAnnotation, captureScreenshot, mountFeedbackButton, type SendAnnotationOptions, type FeedbackButtonOptions, } from "./annotate.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 { 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 { 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

@@ -3,6 +3,10 @@
 // tree-shakes it). The relay and MCP server are NOT exported here; they are
 // run-from-bin, not imported.
 export { HarnessProvider } from "./HarnessProvider.js";
-export { sendAnnotation, captureScreenshot, mountFeedbackButton, } from "./annotate.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 { 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 { getClusterContainer, releaseClusterContainer } from "./cluster.js";

package/dist/client/previewOrigin.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The compiled-in preview-apex allowlist. Previews sit on their own registrable
+ * domain, `vincentt.dev` (f3's `D-Preview-is-its-own-registrable-domain`); staging
+ * and dev are subdomains of it (`*.staging.vincentt.dev`, `*.local.vincentt.dev`),
+ * so a single `.vincentt.dev` suffix matches every environment. The leading dot is a
+ * real subdomain-label boundary, so `<label>.vincentt.dev` matches but a bare
+ * `vincentt.dev` or a look-alike (`evilvincentt.dev`) does not. This is a public DNS
+ * name, not a secret — the same host the viewer's address bar already shows.
+ */
+export declare const PREVIEW_APEXES: readonly [".vincentt.dev"];
+/**
+ * Is the viewer a phone? True iff BOTH `(pointer: coarse)` and `(max-width: 820px)`
+ * match — a coarse-pointer narrow viewer is the device you would hand off to, so the
+ * Share button is pointless there. A missing or THROWING `matchMedia`, or a viewer we
+ * cannot classify, folds to `false` ⇒ the button shows (the "unknown shows" rule: a
+ * missing handoff on a desktop is worse than a stray, send-nothing button on an odd
+ * device). `matchMedia` is injected so the predicate is pure and testable without a DOM.
+ */
+export declare function isPhone(matchMedia?: typeof window.matchMedia): boolean;
+/**
+ * Is this a real, phone-reachable preview origin? `https:` AND the hostname ends with
+ * a `PREVIEW_APEXES` suffix (`.vincentt.dev`). On the creator's plain local loop
+ * (`http://localhost`) or a self-signed LAN origin (`https://192.168.1.20`, `foo.local`)
+ * there is no phone-reachable preview link to encode and no relay a phone can POST to,
+ * so neither cluster control appears.
+ */
+export declare function isPreviewOrigin(loc: Pick<Location, "protocol" | "hostname">): boolean;
+/** The two window handles the framed check compares. Injected so it is testable. */
+export interface FramingView {
+    self: unknown;
+    top: unknown;
+}
+/**
+ * Is this document running inside a frame? `window.self !== window.top`.
+ *
+ * A fact the app reads about ITSELF — no sender, no parameter, no message, no
+ * channel from the embedder. It is also true inside ANY frame, which is correct:
+ * the reason a control is withheld holds for any embedder, not just ours.
+ *
+ * Cross-origin does not break it. Reading `window.top` as an opaque handle and
+ * comparing references is same-origin-policy-safe; only reaching THROUGH it
+ * (`top.location`, `top.document`) throws. Nothing here dereferences it.
+ *
+ * A missing or throwing `window` folds to `false` ⇒ NOT framed. That direction is
+ * deliberate and is the only one that is safe here: it means an unknown context
+ * behaves like today's shipped top-level case rather than silently withholding a
+ * control on the creator's own phone. The framed case this exists for is a real
+ * browser with a real `window`, where the comparison is exact.
+ */
+export declare function isFramed(view?: FramingView): boolean;

package/dist/client/previewOrigin.js

@@ -0,0 +1,76 @@
+// The viewer/origin predicates the bare-DOM cluster controls gate on. A LEAF
+// module: no imports, no dependencies.
+//
+// It exists as its own file so a control can ask "is this a real preview origin?"
+// without importing `share.ts`, which statically pulls in `qrcode`. Both overlays
+// sit behind guarded dynamic imports, so a prod fold drops either one — but with
+// the predicates living in share.ts, mounting only the FEEDBACK chip would still
+// drag the QR encoder into its chunk for a 40-line string check.
+/**
+ * The compiled-in preview-apex allowlist. Previews sit on their own registrable
+ * domain, `vincentt.dev` (f3's `D-Preview-is-its-own-registrable-domain`); staging
+ * and dev are subdomains of it (`*.staging.vincentt.dev`, `*.local.vincentt.dev`),
+ * so a single `.vincentt.dev` suffix matches every environment. The leading dot is a
+ * real subdomain-label boundary, so `<label>.vincentt.dev` matches but a bare
+ * `vincentt.dev` or a look-alike (`evilvincentt.dev`) does not. This is a public DNS
+ * name, not a secret — the same host the viewer's address bar already shows.
+ */
+export const PREVIEW_APEXES = [".vincentt.dev"];
+/**
+ * Is the viewer a phone? True iff BOTH `(pointer: coarse)` and `(max-width: 820px)`
+ * match — a coarse-pointer narrow viewer is the device you would hand off to, so the
+ * Share button is pointless there. A missing or THROWING `matchMedia`, or a viewer we
+ * cannot classify, folds to `false` ⇒ the button shows (the "unknown shows" rule: a
+ * missing handoff on a desktop is worse than a stray, send-nothing button on an odd
+ * device). `matchMedia` is injected so the predicate is pure and testable without a DOM.
+ */
+export function isPhone(matchMedia) {
+    if (typeof matchMedia !== "function")
+        return false;
+    try {
+        return (matchMedia("(pointer: coarse)").matches && matchMedia("(max-width: 820px)").matches);
+    }
+    catch {
+        // A throwing matchMedia is "unknown", never an error to propagate ⇒ show.
+        return false;
+    }
+}
+/**
+ * Is this a real, phone-reachable preview origin? `https:` AND the hostname ends with
+ * a `PREVIEW_APEXES` suffix (`.vincentt.dev`). On the creator's plain local loop
+ * (`http://localhost`) or a self-signed LAN origin (`https://192.168.1.20`, `foo.local`)
+ * there is no phone-reachable preview link to encode and no relay a phone can POST to,
+ * so neither cluster control appears.
+ */
+export function isPreviewOrigin(loc) {
+    return (loc.protocol === "https:" &&
+        PREVIEW_APEXES.some((apex) => loc.hostname.endsWith(apex)));
+}
+/**
+ * Is this document running inside a frame? `window.self !== window.top`.
+ *
+ * A fact the app reads about ITSELF — no sender, no parameter, no message, no
+ * channel from the embedder. It is also true inside ANY frame, which is correct:
+ * the reason a control is withheld holds for any embedder, not just ours.
+ *
+ * Cross-origin does not break it. Reading `window.top` as an opaque handle and
+ * comparing references is same-origin-policy-safe; only reaching THROUGH it
+ * (`top.location`, `top.document`) throws. Nothing here dereferences it.
+ *
+ * A missing or throwing `window` folds to `false` ⇒ NOT framed. That direction is
+ * deliberate and is the only one that is safe here: it means an unknown context
+ * behaves like today's shipped top-level case rather than silently withholding a
+ * control on the creator's own phone. The framed case this exists for is a real
+ * browser with a real `window`, where the comparison is exact.
+ */
+export function isFramed(view) {
+    const w = view ?? (typeof window === "undefined" ? undefined : window);
+    if (!w)
+        return false;
+    try {
+        return w.self !== w.top;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/client/share.d.ts

@@ -1,35 +1,11 @@
-/**
- * The compiled-in preview-apex allowlist. Previews sit on their own registrable
- * domain, `vincentt.dev` (f3's `D-Preview-is-its-own-registrable-domain`); staging
- * and dev are subdomains of it (`*.staging.vincentt.dev`, `*.local.vincentt.dev`),
- * so a single `.vincentt.dev` suffix matches every environment. The leading dot is a
- * real subdomain-label boundary, so `<label>.vincentt.dev` matches but a bare
- * `vincentt.dev` or a look-alike (`evilvincentt.dev`) does not. This is a public DNS
- * name, not a secret — the same host the viewer's address bar already shows.
- */
-export declare const PREVIEW_APEXES: readonly [".vincentt.dev"];
+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
  * navigation. Reads ONLY the origin, so a deep path, query-param secret, or hash is
  * never encoded into the QR or the text field.
  */
 export declare function deriveShareUrl(location: Pick<Location, "origin">): string;
-/**
- * Is the viewer a phone? True iff BOTH `(pointer: coarse)` and `(max-width: 820px)`
- * match — a coarse-pointer narrow viewer is the device you would hand off to, so the
- * button is pointless there. A missing or THROWING `matchMedia`, or a viewer we cannot
- * classify, folds to `false` ⇒ the button shows (the "unknown shows" rule: a missing
- * handoff on a desktop is worse than a stray, send-nothing button on an odd device).
- * `matchMedia` is injected so the predicate is pure and testable without a DOM.
- */
-export declare function isPhone(matchMedia?: typeof window.matchMedia): boolean;
-/**
- * Is this a real, phone-reachable preview origin? `https:` AND the hostname ends with
- * a `PREVIEW_APEXES` suffix (`.vincentt.dev`). On the creator's plain local loop
- * (`http://localhost`) or a self-signed LAN origin (`https://192.168.1.20`, `foo.local`)
- * there is no phone-reachable preview link to encode, so the button does not appear.
- */
-export declare function isPreviewOrigin(loc: Pick<Location, "protocol" | "hostname">): boolean;
 /**
  * Render the preview URL as an inline SVG QR. Same params as the CLI's `qrPage.ts`
  * (`margin:2`, ECC `M`) so the on-screen QR is identical to the proven-scannable
@@ -41,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,16 +11,12 @@
 // whole module — and `qrcode`, reached only from here — tree-shakes out of prod.
 import QRCode from "qrcode";
 import { getClusterContainer, releaseClusterContainer } from "./cluster.js";
-/**
- * The compiled-in preview-apex allowlist. Previews sit on their own registrable
- * domain, `vincentt.dev` (f3's `D-Preview-is-its-own-registrable-domain`); staging
- * and dev are subdomains of it (`*.staging.vincentt.dev`, `*.local.vincentt.dev`),
- * so a single `.vincentt.dev` suffix matches every environment. The leading dot is a
- * real subdomain-label boundary, so `<label>.vincentt.dev` matches but a bare
- * `vincentt.dev` or a look-alike (`evilvincentt.dev`) does not. This is a public DNS
- * name, not a secret — the same host the viewer's address bar already shows.
- */
-export const PREVIEW_APEXES = [".vincentt.dev"];
+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
+// test imports them from, and the wire/API surface should not move for a refactor.
+export { isPhone, isPreviewOrigin, PREVIEW_APEXES } from "./previewOrigin.js";
 /**
  * The canonical preview URL to encode — `origin + "/"`, stable across in-app SPA
  * navigation. Reads ONLY the origin, so a deep path, query-param secret, or hash is
@@ -29,35 +25,6 @@ export const PREVIEW_APEXES = [".vincentt.dev"];
 export function deriveShareUrl(location) {
     return location.origin + "/";
 }
-/**
- * Is the viewer a phone? True iff BOTH `(pointer: coarse)` and `(max-width: 820px)`
- * match — a coarse-pointer narrow viewer is the device you would hand off to, so the
- * button is pointless there. A missing or THROWING `matchMedia`, or a viewer we cannot
- * classify, folds to `false` ⇒ the button shows (the "unknown shows" rule: a missing
- * handoff on a desktop is worse than a stray, send-nothing button on an odd device).
- * `matchMedia` is injected so the predicate is pure and testable without a DOM.
- */
-export function isPhone(matchMedia) {
-    if (typeof matchMedia !== "function")
-        return false;
-    try {
-        return (matchMedia("(pointer: coarse)").matches && matchMedia("(max-width: 820px)").matches);
-    }
-    catch {
-        // A throwing matchMedia is "unknown", never an error to propagate ⇒ show.
-        return false;
-    }
-}
-/**
- * Is this a real, phone-reachable preview origin? `https:` AND the hostname ends with
- * a `PREVIEW_APEXES` suffix (`.vincentt.dev`). On the creator's plain local loop
- * (`http://localhost`) or a self-signed LAN origin (`https://192.168.1.20`, `foo.local`)
- * there is no phone-reachable preview link to encode, so the button does not appear.
- */
-export function isPreviewOrigin(loc) {
-    return (loc.protocol === "https:" &&
-        PREVIEW_APEXES.some((apex) => loc.hostname.endsWith(apex)));
-}
 /**
  * Render the preview URL as an inline SVG QR. Same params as the CLI's `qrPage.ts`
  * (`margin:2`, ECC `M`) so the on-screen QR is identical to the proven-scannable
@@ -79,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.
@@ -93,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,60 @@
+/** 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 whole channel vocabulary, both directions. */
+export declare const CHANNEL_MESSAGE_TYPES: readonly ["announce", "set-media-source"];
+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];
+/**
+ * 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[];
+}
+/** console → app. The only command name that exists. */
+export interface ConsoleSetMediaSourceMessage {
+    source: typeof CONSOLE_MESSAGE_SOURCE;
+    v: typeof CHANNEL_PROTOCOL_VERSION;
+    type: "set-media-source";
+    presetId: string;
+}
+/**
+ * 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;
+/** 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,45 @@
+// 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
+// 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 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 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"];
+/**
+ * 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;
+/** 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;