@vincentt-xr/harness 1.0.0 → 1.2.0

package/dist/client/HarnessProvider.d.ts

@@ -12,15 +12,60 @@ export interface HarnessProviderProps {
      * app). Override for the production review-service sink.
      */
     relayUrl?: string;
-    /** Session id grouping this preview run's events. Defaults to a per-load id. */
+    /**
+     * The key grouping this tab's events into one TESTER. Defaults to a per-tab
+     * CSPRNG id in `sessionStorage`, which is what you want; override only for the
+     * production review-service path. A value passed here is client-supplied input
+     * like any other — the relay validates it and never renders it, and passing
+     * another tab's value merges the two into one tester.
+     */
     sessionId?: string;
     captureConsole?: boolean;
     captureNetwork?: boolean;
     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>`.
+ *
+ * There is deliberately NO Math.random fallback. The previous generator's ~10^6
+ * space is exactly what this replaces, and a fallback reintroducing it would be
+ * the branch that actually runs on the oldest phone in the room. Both paths here
+ * are Web Crypto: randomUUID where it exists, getRandomValues otherwise — and
+ * getRandomValues has been in every browser that can run this app for a decade.
+ * If neither exists we throw rather than guess, because a weak id is a SILENT
+ * merge of two testers' streams, and no id at all is merely un-attributed.
+ */
+export declare function generateClientSessionId(): string;
+/** The slice of Storage this needs — so the rule below is testable without a DOM. */
+export interface SessionIdStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
 }
+/**
+ * The key the relay groups this tab's events by — one TESTER.
+ *
+ * `sessionStorage`, not `localStorage`, and the choice is load-bearing on both
+ * ends: it is per TAB (so one QR scan is one tester even though the tab opens a
+ * second connection for assets) and it DIES WITH THE TAB (so the grouping is
+ * bounded by construction rather than by a rule someone has to remember, and
+ * cannot outlive the session's terminal window).
+ *
+ * A stored value that misses the current grammar is OVERWRITTEN, not migrated:
+ * it was minted at the entropy this replaces. The rewrite happens here at mount,
+ * before the first batch, so no id is ever renumbered mid-run.
+ */
+export declare function resolveClientSessionId(storage: SessionIdStorage | undefined): string;
 export declare function HarnessProvider(props: HarnessProviderProps): ReactNode;

package/dist/client/HarnessProvider.js

@@ -8,6 +8,7 @@
 // accident. The relay URL and session id default to what the preview loop sets,
 // but both are overridable for the production review-service path later.
 import { useEffect } from "react";
+import { CLIENT_SESSION_ID_RE } from "../shared/events.js";
 function defaultRelayUrl() {
     if (typeof window === "undefined")
         return "ws://localhost:7331";
@@ -16,19 +17,56 @@ function defaultRelayUrl() {
     // so one cloudflared tunnel carries both. The relay CLI serves this path.
     return `${proto}://${window.location.host}/__harness`;
 }
+const SESSION_STORAGE_KEY = "__vincentt_harness_session";
+/**
+ * 128 bits of CSPRNG, hex, as `s2_<32 hex>`.
+ *
+ * There is deliberately NO Math.random fallback. The previous generator's ~10^6
+ * space is exactly what this replaces, and a fallback reintroducing it would be
+ * the branch that actually runs on the oldest phone in the room. Both paths here
+ * are Web Crypto: randomUUID where it exists, getRandomValues otherwise — and
+ * getRandomValues has been in every browser that can run this app for a decade.
+ * If neither exists we throw rather than guess, because a weak id is a SILENT
+ * merge of two testers' streams, and no id at all is merely un-attributed.
+ */
+export function generateClientSessionId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return `s2_${c.randomUUID().replace(/-/g, "")}`;
+    if (c?.getRandomValues) {
+        const bytes = c.getRandomValues(new Uint8Array(16));
+        let hex = "";
+        for (const b of bytes)
+            hex += b.toString(16).padStart(2, "0");
+        return `s2_${hex}`;
+    }
+    throw new Error("harness: Web Crypto unavailable; cannot mint a session id");
+}
+/**
+ * The key the relay groups this tab's events by — one TESTER.
+ *
+ * `sessionStorage`, not `localStorage`, and the choice is load-bearing on both
+ * ends: it is per TAB (so one QR scan is one tester even though the tab opens a
+ * second connection for assets) and it DIES WITH THE TAB (so the grouping is
+ * bounded by construction rather than by a rule someone has to remember, and
+ * cannot outlive the session's terminal window).
+ *
+ * A stored value that misses the current grammar is OVERWRITTEN, not migrated:
+ * it was minted at the entropy this replaces. The rewrite happens here at mount,
+ * before the first batch, so no id is ever renumbered mid-run.
+ */
+export function resolveClientSessionId(storage) {
+    const existing = storage?.getItem(SESSION_STORAGE_KEY);
+    if (existing && CLIENT_SESSION_ID_RE.test(existing))
+        return existing;
+    const id = generateClientSessionId();
+    storage?.setItem(SESSION_STORAGE_KEY, id);
+    return id;
+}
 function defaultSessionId() {
     if (typeof window === "undefined")
         return "server";
-    const key = "__vincentt_harness_session";
-    const existing = window.sessionStorage?.getItem(key);
-    if (existing)
-        return existing;
-    // Per-load id; not security-sensitive, just needs to be distinct enough that
-    // two phones on one relay don't collide. No Math.random dependency in the
-    // pure layer — this imperative shell may use it.
-    const id = `s_${Date.now().toString(36)}_${Math.floor(Math.random() * 1e6).toString(36)}`;
-    window.sessionStorage?.setItem(key, id);
-    return id;
+    return resolveClientSessionId(window.sessionStorage);
 }
 const DEV = typeof import.meta !== "undefined" &&
     import.meta.env?.DEV;
@@ -53,19 +91,40 @@ 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 }) => {
                 if (cancelled)
                     return;
-                unmountFeedback = mountFeedbackButton({ sessionId: props.sessionId });
+                // The SAME resolved key the instrumentation sends, not the bare prop.
+                // The prop is undefined for every app that does not set it — i.e. the
+                // default — so passing it through left every real annotation
+                // un-attributed while the tests, which build the input by hand, never
+                // exercised this line.
+                unmountFeedback = mountFeedbackButton({
+                    sessionId: props.sessionId ?? defaultSessionId(),
+                });
+            });
+        }
+        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;