@vincentt-xr/harness 1.1.0 → 1.2.0

package/dist/client/HarnessProvider.d.ts

@@ -25,9 +25,17 @@ export interface HarnessProviderProps {
     captureTrace?: boolean;
     /**
      * Mount the floating "Send feedback" button (the reverse-channel capture
-     * overlay). Defaults to `enabled` — on in preview, gone in production.
+     * overlay). Present in code and shares the Share control's cluster mount, but
+     * defaults to OFF (`false`) pending a later decision — a creator sees only the
+     * Share control today. Re-displaying it is a one-line default flip; the button
+     * takes the adjacent flex slot with no layout move.
      */
     feedback?: boolean;
+    /**
+     * Mount the in-app Share control (the desktop-to-phone QR handoff overlay).
+     * Defaults to `enabled` — on in preview, tree-shaken out of production.
+     */
+    share?: boolean;
 }
 /**
  * 128 bits of CSPRNG, hex, as `s2_<32 hex>`.

package/dist/client/HarnessProvider.js

@@ -91,7 +91,10 @@ export function HarnessProvider(props) {
             });
         });
         let unmountFeedback;
-        if (props.feedback !== false) {
+        // Feedback defaults OFF (opt-in with `feedback={true}`) — the code path stays
+        // present so re-enabling it later is a one-line default flip, but a creator
+        // sees only the Share control today.
+        if (props.feedback === true) {
             // Separate dynamic import so the capture overlay (and its DOM code) also
             // drops from a production bundle.
             void import("./annotate.js").then(({ mountFeedbackButton }) => {
@@ -107,10 +110,21 @@ export function HarnessProvider(props) {
                 });
             });
         }
+        let unmountShare;
+        // Share defaults to `enabled`. Separate dynamic import so the overlay's DOM
+        // code and `qrcode` (reached only from here) drop from a production bundle.
+        if (props.share !== false) {
+            void import("./share.js").then(({ mountShareButton }) => {
+                if (cancelled)
+                    return;
+                unmountShare = mountShareButton({});
+            });
+        }
         return () => {
             cancelled = true;
             teardown?.();
             unmountFeedback?.();
+            unmountShare?.();
         };
         // Instrumentation is installed once for the provider's lifetime; option
         // changes mid-session are not a supported case.

package/dist/client/annotate.js

@@ -6,6 +6,7 @@
 //
 // Loaded via dynamic import from HarnessProvider (like the instrumentation), so a
 // production build never ships it. DOM-only, no React.
+import { getClusterContainer, releaseClusterContainer } from "./cluster.js";
 /** Default relay HTTP base: the same origin the app is served on + the harness path. */
 function defaultRelayHttpUrl() {
     return `${window.location.origin}/__harness`;
@@ -58,10 +59,6 @@ export function mountFeedbackButton(opts = {}) {
     const btn = document.createElement("button");
     btn.textContent = "Send feedback";
     Object.assign(btn.style, {
-        position: "fixed",
-        right: "12px",
-        bottom: "12px",
-        zIndex: "2147483647",
         padding: "10px 14px",
         borderRadius: "10px",
         border: "none",
@@ -99,6 +96,11 @@ export function mountFeedbackButton(opts = {}) {
             console.error("[harness] annotation send failed:", err);
         }
     });
-    document.body.appendChild(btn);
-    return () => btn.remove();
+    // Shares the top-right cluster with the other bare-DOM controls (Share today);
+    // the container positions it, so no fixed-position styles here.
+    getClusterContainer().appendChild(btn);
+    return () => {
+        btn.remove();
+        releaseClusterContainer();
+    };
 }

package/dist/client/cluster.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The shared control container — idempotent. Creates one `#vt-cluster` node on the
+ * first call and returns the SAME node on every subsequent call. Each call counts
+ * as one holder; pair it with exactly one `releaseClusterContainer()` on unmount.
+ */
+export declare function getClusterContainer(): HTMLElement;
+/**
+ * Release one holder of the container. When the last holder releases (count hits
+ * zero) the `#vt-cluster` node is removed from the DOM. Extra releases past zero
+ * are a no-op, so an over-release cannot go negative or throw.
+ */
+export declare function releaseClusterContainer(): void;

package/dist/client/cluster.js

@@ -0,0 +1,51 @@
+// The one shared fixed-position mount for the harness's bare-DOM dev controls.
+// Every floating control (Share today; feedback when re-displayed) appends into
+// this single top-right flex row rather than positioning itself, so controls sit
+// in a stable cluster and a new one takes the adjacent slot with no layout move.
+//
+// DOM-only, no React. Loaded only through the dynamic imports in HarnessProvider,
+// so it never enters a production bundle.
+const CLUSTER_ID = "vt-cluster";
+// Ref-counted so the container is created on the first control's mount and removed
+// only when the last control unmounts. A module-level count is the shared owner:
+// getClusterContainer() increments, releaseClusterContainer() decrements.
+let refCount = 0;
+/**
+ * The shared control container — idempotent. Creates one `#vt-cluster` node on the
+ * first call and returns the SAME node on every subsequent call. Each call counts
+ * as one holder; pair it with exactly one `releaseClusterContainer()` on unmount.
+ */
+export function getClusterContainer() {
+    const existing = document.getElementById(CLUSTER_ID);
+    if (existing) {
+        refCount += 1;
+        return existing;
+    }
+    const el = document.createElement("div");
+    el.id = CLUSTER_ID;
+    Object.assign(el.style, {
+        position: "fixed",
+        top: "12px",
+        right: "12px",
+        zIndex: "2147483647",
+        display: "flex",
+        gap: "8px",
+        alignItems: "flex-start",
+    });
+    document.body.appendChild(el);
+    refCount += 1;
+    return el;
+}
+/**
+ * Release one holder of the container. When the last holder releases (count hits
+ * zero) the `#vt-cluster` node is removed from the DOM. Extra releases past zero
+ * are a no-op, so an over-release cannot go negative or throw.
+ */
+export function releaseClusterContainer() {
+    if (refCount === 0)
+        return;
+    refCount -= 1;
+    if (refCount === 0) {
+        document.getElementById(CLUSTER_ID)?.remove();
+    }
+}

package/dist/client/index.d.ts

@@ -1,5 +1,7 @@
 export { HarnessProvider } from "./HarnessProvider.js";
 export type { HarnessProviderProps } from "./HarnessProvider.js";
 export { sendAnnotation, captureScreenshot, mountFeedbackButton, type SendAnnotationOptions, type FeedbackButtonOptions, } from "./annotate.js";
+export { mountShareButton, deriveShareUrl, isPhone, isPreviewOrigin, renderQr, PREVIEW_APEXES, type ShareButtonOptions, } from "./share.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

@@ -4,3 +4,5 @@
 // run-from-bin, not imported.
 export { HarnessProvider } from "./HarnessProvider.js";
 export { sendAnnotation, captureScreenshot, mountFeedbackButton, } from "./annotate.js";
+export { mountShareButton, deriveShareUrl, isPhone, isPreviewOrigin, renderQr, PREVIEW_APEXES, } from "./share.js";
+export { getClusterContainer, releaseClusterContainer } from "./cluster.js";

package/dist/client/instrument.js

@@ -16,7 +16,15 @@ export function installInstrumentation(opts) {
     if (w.__vincenttHarness)
         return () => undefined;
     w.__vincenttHarness = true;
-    const socket = openSocket(opts.relayUrl);
+    // The hello is the FIRST message on the socket, sent on every open (including a
+    // reconnect, which is a fresh connection the relay must re-attribute). It rides
+    // the socket directly, NOT the EventBuffer flush: a silent app never flushes, so
+    // routing it through the buffer would reintroduce the exact silence-on-connect
+    // this exists to kill. The buffer path stays untouched.
+    const hello = { type: "hello", sessionId: opts.sessionId };
+    const socket = openSocket(opts.relayUrl, () => {
+        socket.send(JSON.stringify(hello));
+    });
     const buffer = new EventBuffer({
         sessionId: opts.sessionId,
         send: (batch) => {
@@ -44,8 +52,9 @@ export function installInstrumentation(opts) {
         w.__vincenttHarness = false;
     };
 }
-/** A tiny reconnecting WebSocket wrapper. */
-function openSocket(url) {
+/** A tiny reconnecting WebSocket wrapper. `onOpen` fires on every open (each
+ *  reconnect is a fresh connection), so the caller can re-send its hello. */
+function openSocket(url, onOpen) {
     let ws = null;
     let closed = false;
     const connect = () => {
@@ -53,6 +62,7 @@ function openSocket(url) {
             return;
         try {
             ws = new WebSocket(url);
+            ws.onopen = () => onOpen?.();
             ws.onclose = () => {
                 ws = null;
                 if (!closed)

package/dist/client/share.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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"];
+/**
+ * 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
+ * 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,318 @@
+// 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";
+/**
+ * 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"];
+/**
+ * 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 + "/";
+}
+/**
+ * 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
+ * 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/harness",
-  "version": "1.1.0",
+  "version": "1.2.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",