@vincentt-xr/harness 1.1.0 → 1.3.0

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

@@ -0,0 +1,30 @@
+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;
+/**
+ * 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
+ * terminal one.
+ */
+export declare function renderQr(url: string): Promise<string>;
+export interface ShareButtonOptions {
+    /** Injectable for tests. Defaults to `window.matchMedia`. */
+    matchMedia?: typeof window.matchMedia;
+    /** Injectable for tests. Defaults to `window.location`. */
+    location?: Pick<Location, "origin" | "protocol" | "hostname">;
+}
+/**
+ * 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.
+ *
+ * Returns an unmount function that removes the chip + popover, tears down listeners,
+ * and releases the shared cluster.
+ */
+export declare function mountShareButton(opts?: ShareButtonOptions): () => void;

package/dist/client/share.js

@@ -0,0 +1,285 @@
+// The in-app Share control — the creator's desktop-to-phone handoff, rendered
+// inside the running preview. An icon-only QR-glyph chip in the shared top-right
+// cluster; clicking it drops a popover with an inline SVG QR of the preview origin,
+// a heading + instruction, and the URL as selectable text (no Copy button).
+//
+// It re-presents ONLY `window.location.origin + "/"` — the capability URL the
+// link-holder already has (B17). It makes NO network call and sends nothing to the
+// relay (B19): pure client-side rendering of a string already in the page.
+//
+// DOM-only, no React. Loaded through the dynamic import in HarnessProvider, so the
+// 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";
+// 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
+ * never encoded into the QR or the text field.
+ */
+export function deriveShareUrl(location) {
+    return location.origin + "/";
+}
+/**
+ * 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
+ * terminal one.
+ */
+export function renderQr(url) {
+    return QRCode.toString(url, {
+        type: "svg",
+        margin: 2,
+        errorCorrectionLevel: "M",
+    });
+}
+const HEADING = "Open on your phone";
+const INSTRUCTION = "Point your phone's camera at the code, or type in the link below.";
+// A single QR-code glyph (three finder squares + a scattering of modules), ~18px,
+// `currentColor` so it inherits the chip's `#f5f2ef`. Chosen over a share arrow
+// because a QR square most directly says "get this onto a phone".
+const QR_GLYPH_SVG = `<svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" focusable="false"><path d="M3 3h8v8H3V3Zm2 2v4h4V5H5Zm-2 8h8v8H3v-8Zm2 2v4h4v-4H5ZM13 3h8v8h-8V3Zm2 2v4h4V5h-4Zm-2 8h2v2h-2v-2Zm2 2h2v2h-2v-2Zm2-2h2v2h-2v-2Zm0 4h2v2h-2v-2Zm2-2h2v2h-2v-2Zm0 4h2v2h-2v-2Zm-4 0h2v2h-2v-2Z"/></svg>`;
+/**
+ * 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.
+ *
+ * Returns an unmount function that removes the chip + popover, tears down listeners,
+ * and releases the shared cluster.
+ */
+export function mountShareButton(opts = {}) {
+    if (typeof document === "undefined")
+        return () => undefined;
+    const matchMedia = opts.matchMedia ?? (typeof window !== "undefined" ? window.matchMedia : undefined);
+    const location = opts.location ?? (typeof window !== "undefined" ? window.location : undefined);
+    if (!location)
+        return () => undefined;
+    const show = !isPhone(matchMedia) && isPreviewOrigin(location);
+    if (!show)
+        return () => undefined;
+    const url = deriveShareUrl(location);
+    const container = getClusterContainer();
+    let released = false;
+    const btn = document.createElement("button");
+    btn.type = "button";
+    btn.setAttribute("aria-label", "Share preview");
+    btn.title = "Share preview";
+    btn.setAttribute("aria-haspopup", "dialog");
+    btn.setAttribute("aria-controls", "vt-popover");
+    btn.setAttribute("aria-expanded", "false");
+    btn.innerHTML = QR_GLYPH_SVG;
+    Object.assign(btn.style, {
+        width: "36px",
+        height: "36px",
+        padding: "0",
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        borderRadius: "10px",
+        border: "1px solid rgba(255,255,255,.14)",
+        background: "rgba(28,27,26,.92)",
+        color: "#f5f2ef",
+        boxShadow: "0 1px 4px rgba(0,0,0,.5)",
+        cursor: "pointer",
+        transition: "background 100ms, border-color 100ms",
+    });
+    const IDLE_BG = "rgba(28,27,26,.92)";
+    const IDLE_BORDER = "rgba(255,255,255,.14)";
+    const HOVER_BG = "rgba(40,38,36,.95)";
+    const HOVER_BORDER = "rgba(255,255,255,.24)";
+    const ACTIVE_BG = "rgba(40,38,36,.95)";
+    const ACTIVE_BORDER = "rgba(147,184,240,.5)";
+    const applyIdle = () => {
+        btn.style.background = IDLE_BG;
+        btn.style.borderColor = IDLE_BORDER;
+    };
+    const applyActive = () => {
+        btn.style.background = ACTIVE_BG;
+        btn.style.borderColor = ACTIVE_BORDER;
+    };
+    btn.addEventListener("mouseenter", () => {
+        if (popover)
+            return; // active state wins over hover
+        btn.style.background = HOVER_BG;
+        btn.style.borderColor = HOVER_BORDER;
+    });
+    btn.addEventListener("mouseleave", () => {
+        if (popover)
+            return;
+        applyIdle();
+    });
+    // Focus ring: a brand-blue outline that reads on any background. Set inline on
+    // focus/blur since there is no stylesheet on this surface for :focus-visible.
+    btn.addEventListener("focus", () => {
+        btn.style.outline = "2px solid #93b8f0";
+        btn.style.outlineOffset = "2px";
+    });
+    btn.addEventListener("blur", () => {
+        btn.style.outline = "none";
+    });
+    let popover = null;
+    let outsideHandler = null;
+    let keyHandler = null;
+    const prefersReducedMotion = typeof matchMedia === "function"
+        ? (() => {
+            try {
+                return matchMedia("(prefers-reduced-motion: reduce)").matches;
+            }
+            catch {
+                return false;
+            }
+        })()
+        : false;
+    const closePopover = (returnFocus) => {
+        if (!popover)
+            return;
+        popover.remove();
+        popover = null;
+        if (outsideHandler) {
+            document.removeEventListener("mousedown", outsideHandler, true);
+            outsideHandler = null;
+        }
+        if (keyHandler) {
+            document.removeEventListener("keydown", keyHandler);
+            keyHandler = null;
+        }
+        btn.setAttribute("aria-expanded", "false");
+        applyIdle();
+        if (returnFocus)
+            btn.focus();
+    };
+    const buildPopover = () => {
+        const pop = document.createElement("div");
+        pop.id = "vt-popover";
+        pop.setAttribute("role", "dialog");
+        pop.setAttribute("aria-label", "Open this preview on your phone");
+        Object.assign(pop.style, {
+            position: "fixed",
+            top: "56px",
+            right: "12px",
+            zIndex: "2147483647",
+            width: "260px",
+            padding: "16px",
+            borderRadius: "12px",
+            border: "1px solid rgba(255,255,255,.14)",
+            background: "rgba(23,22,21,.86)",
+            backdropFilter: "blur(16px) saturate(1.1)",
+            // @ts-expect-error vendor-prefixed for Safari; not in the typed CSSStyleDeclaration
+            WebkitBackdropFilter: "blur(16px) saturate(1.1)",
+            boxShadow: "0 12px 32px rgba(0,0,0,.45)",
+            boxSizing: "border-box",
+            transformOrigin: "top right",
+        });
+        const qrTile = document.createElement("div");
+        qrTile.className = "vt-qr";
+        Object.assign(qrTile.style, {
+            width: "100%",
+            aspectRatio: "1 / 1",
+            background: "#fff",
+            padding: "8px",
+            borderRadius: "8px",
+            border: "1px solid rgba(0,0,0,.06)",
+            boxSizing: "border-box",
+        });
+        // Async QR render; the tile holds its space via aspect-ratio until it lands.
+        void renderQr(url).then((svg) => {
+            // Guard against a close-before-resolve race.
+            if (qrTile.isConnected)
+                qrTile.innerHTML = svg;
+        });
+        const heading = document.createElement("div");
+        heading.className = "vt-heading";
+        heading.textContent = HEADING;
+        Object.assign(heading.style, {
+            font: "600 14px/1.35 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif",
+            color: "#f5f2ef",
+            margin: "12px 0 2px",
+        });
+        const instr = document.createElement("div");
+        instr.className = "vt-instr";
+        instr.textContent = INSTRUCTION;
+        Object.assign(instr.style, {
+            font: "400 13px/1.45 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif",
+            color: "#b8b2a9",
+            margin: "0 0 10px",
+        });
+        const urlField = document.createElement("div");
+        urlField.className = "vt-url";
+        urlField.textContent = url;
+        Object.assign(urlField.style, {
+            font: "500 12px/1.5 ui-monospace,monospace",
+            color: "#93b8f0",
+            background: "rgba(255,255,255,.06)",
+            border: "1px solid rgba(255,255,255,.10)",
+            borderRadius: "8px",
+            padding: "8px 10px",
+            wordBreak: "break-all",
+            cursor: "text",
+            userSelect: "all",
+            // @ts-expect-error vendor-prefixed for Safari
+            WebkitUserSelect: "all",
+            boxSizing: "border-box",
+        });
+        pop.append(qrTile, heading, instr, urlField);
+        if (!prefersReducedMotion) {
+            pop.style.opacity = "0";
+            pop.style.transform = "translateY(-4px) scale(.98)";
+            pop.style.transition =
+                "opacity 160ms cubic-bezier(0.16,1,0.3,1), transform 160ms cubic-bezier(0.16,1,0.3,1)";
+            // Next frame: animate to the resting state.
+            requestAnimationFrame(() => {
+                pop.style.opacity = "1";
+                pop.style.transform = "translateY(0) scale(1)";
+            });
+        }
+        return pop;
+    };
+    const openPopover = () => {
+        if (popover)
+            return;
+        popover = buildPopover();
+        container.appendChild(popover);
+        btn.setAttribute("aria-expanded", "true");
+        applyActive();
+        // Click-outside: a capture-phase mousedown outside both popover and button
+        // closes it. Registered only while open, removed on close.
+        outsideHandler = (e) => {
+            const target = e.target;
+            if (!target)
+                return;
+            if (popover && (popover.contains(target) || btn.contains(target)))
+                return;
+            closePopover(false);
+        };
+        document.addEventListener("mousedown", outsideHandler, true);
+        // Escape closes and returns focus to the Share button.
+        keyHandler = (e) => {
+            if (e.key === "Escape") {
+                e.stopPropagation();
+                closePopover(true);
+            }
+        };
+        document.addEventListener("keydown", keyHandler);
+    };
+    btn.addEventListener("click", () => {
+        if (popover)
+            closePopover(false);
+        else
+            openPopover();
+    });
+    container.appendChild(btn);
+    return () => {
+        closePopover(false);
+        btn.remove();
+        if (!released) {
+            released = true;
+            releaseClusterContainer();
+        }
+    };
+}

package/dist/shared/events.d.ts

@@ -85,6 +85,27 @@ export interface ClientToRelay {
     sessionId: string;
     events: DiagEvent[];
 }
+/**
+ * The FIRST message on the diagnostics WS, sent at WS-open before HarnessProvider
+ * mounts and independent of the EventBuffer having pending events. It carries the
+ * same `sessionStorage` key the events batch carries, so the relay can resolve the
+ * TESTER on connect rather than waiting for a batch — which is why a SILENT app
+ * (no console/network/trace events) and an app that crashes during mount are both
+ * attributed instead of reading as an absence.
+ *
+ * It is a relay-layer message in the `{type:"events"}` family, NOT a tunnel
+ * control frame: the edge splices the tunnel as opaque bytes and never reads it.
+ * The `sessionId` is grammar-guarded by the relay against CLIENT_SESSION_ID_RE
+ * with no sanitize-and-keep branch, exactly as the batch key is — a malformed key
+ * is ingested un-keyed, never a crash.
+ */
+export interface ClientHello {
+    type: "hello";
+    /** The client's `sessionStorage` key — same value the events batch carries. */
+    sessionId: string;
+}
+/** Every message the client sends up the diagnostics WS. Discriminated on `type`. */
+export type ClientMessage = ClientToRelay | ClientHello;
 /** What the MCP server asks the relay for. `since` is an exclusive seq cursor. */
 export interface RelayQuery {
     kind?: DiagEventKind;
@@ -108,6 +129,20 @@ export interface RelayQuery {
      * debugging rather than for "whose phone".
      */
     viewer?: string;
+    /**
+     * Ask the relay to also report how many connections are attached RIGHT NOW.
+     *
+     * An OPTIONAL BOOLEAN and not a `kind` value: `kind` is a `DiagEventKind`
+     * event-type FILTER shared with `DiagEvent.kind`, so a "presence" member there
+     * would invent a meaningless event type. It is also not an `op` discriminator,
+     * which would imply a mode the type never had and need a default — a version
+     * branch by another name.
+     *
+     * An unknown field is IGNORED by a relay that predates this, so an old relay
+     * answers a valid envelope with no counts and the caller reads none. That is
+     * the whole of the version negotiation: there is none.
+     */
+    presence?: boolean;
 }
 export interface RelayResult {
     events: DiagEvent[];
@@ -150,6 +185,31 @@ export interface RelayResult {
      * set rather than remembering one.
      */
     viewers: string[];
+    /**
+     * How many connections are attached RIGHT NOW. Present only when the query
+     * asked for presence, and only from a relay that understands the field.
+     *
+     * ⚠ THIS IS NOT `viewers.length`, AND THE TWO SIT IN THE SAME OBJECT.
+     * `viewers`/`testers` are EVER-SEEN sets that are never pruned by design, so
+     * they answer "who has ever connected to this run". A caller that falls back
+     * to them when this field is absent prints a phone that closed its tab twenty
+     * minutes ago as still watching. ABSENT MEANS UNKNOWN, and the only correct
+     * response to unknown is to say nothing.
+     *
+     * The source is the relay's live socket set, so a socket that closes leaves
+     * it. Counts CONNECTIONS, not devices or people: one tab opens several under
+     * HTTP/1.1, which is why every surface that prints this says "connections".
+     */
+    liveConnections?: number;
+    /**
+     * Distinct resolved testers among the currently-open connections. Present
+     * under the same condition as `liveConnections`.
+     *
+     * A connection whose key missed the grammar resolves to no tester, so it
+     * counts toward `liveConnections` and not toward this — correct, because it
+     * is a real attached connection of an unknown tab.
+     */
+    liveTesters?: number;
 }
 /** A freehand stroke over the frame, in normalized [0,1] frame coordinates. */
 export interface AnnotationStroke {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/harness",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Vincentt AR dev-loop harness - in-app diagnostics provider + wire contract",
   "license": "UNLICENSED",
   "type": "module",
@@ -31,10 +31,13 @@
   "devDependencies": {
     "@types/react": "^18.3.12",
     "@types/ws": "^8.5.13",
-    "@types/node": "^22.9.0"
+    "@types/node": "^22.9.0",
+    "@types/qrcode": "^1.5.5",
+    "jsdom": "^25.0.1"
   },
   "dependencies": {
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "qrcode": "^1.5.4"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",