@vincentt-xr/harness 1.2.0 → 1.3.0

package/dist/client/HarnessProvider.d.ts

@@ -24,11 +24,10 @@ export interface HarnessProviderProps {
     captureNetwork?: boolean;
     captureTrace?: boolean;
     /**
-     * Mount the floating "Send feedback" button (the reverse-channel capture
-     * 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.
+     * Mount the Send-feedback chip (the reverse-channel capture overlay) into the
+     * shared top-right cluster. Defaults to `enabled` — on in preview, tree-shaken
+     * out of production. It is the phone's only way to speak, and f12's central
+     * scenario is unreachable without it.
      */
     feedback?: boolean;
     /**

package/dist/client/HarnessProvider.js

@@ -90,13 +90,42 @@ export function HarnessProvider(props) {
                 captureTrace: props.captureTrace,
             });
         });
+        let unmountShare;
         let unmountFeedback;
-        // 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.
+        // SHARE MOUNTS FIRST, AND THE ORDER IS SEQUENCED, NOT RACED.
+        //
+        // Insertion order into the cluster IS flex order, and Share is the cluster's
+        // established first member — a new control must take the adjacent slot
+        // without moving it. Two independent `import(...).then(...)` chains resolve
+        // in whatever order the loader finishes them, so leaving these parallel puts
+        // the cluster's layout at the mercy of module-fetch timing. Feedback is
+        // therefore mounted from INSIDE Share's continuation.
+        //
+        // Both remain separate dynamic imports, which is what lets a production
+        // build drop each overlay (and `qrcode`, reached only from share.js). The
+        // share import is also written FIRST in this file, so the ordering is legible
+        // to a reader (and to a source-level assertion) and not only to the runtime.
+        //
+        // Share defaults to `enabled`. Feedback defaults to `enabled` too (opt OUT
+        // with `feedback={false}`); the chip gates itself on the origin at mount, so
+        // the flag only decides whether the module is fetched at all.
+        if (props.share !== false) {
+            void import("./share.js").then(({ mountShareButton }) => {
+                if (cancelled)
+                    return;
+                unmountShare = mountShareButton({});
+                // Only now — so Share holds slot one even when its module resolves last.
+                mountFeedback();
+            });
+        }
+        else {
+            // No Share at all: feedback is the cluster's only member, so there is no
+            // order to preserve and nothing to wait for.
+            mountFeedback();
+        }
+        function mountFeedback() {
+            if (props.feedback === false)
+                return;
             void import("./annotate.js").then(({ mountFeedbackButton }) => {
                 if (cancelled)
                     return;
@@ -110,16 +139,6 @@ 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?.();

package/dist/client/annotate.d.ts

@@ -1,3 +1,4 @@
+import { type FramingView } from "./previewOrigin.js";
 import type { AnnotationInput, AnnotationSpec } from "../shared/events.js";
 /**
  * Capture the current frame as a PNG data URL. Prefers the largest <canvas> (the
@@ -18,17 +19,85 @@ export declare function sendAnnotation(input: AnnotationInput, opts?: SendAnnota
     id: string;
     seq: number;
 }>;
+/** The counter's current value. Exported for tests; not part of the app surface. */
+export declare function getConsecutiveFailures(): number;
+/**
+ * ANY failed POST increments — non-2xx, network error, abort alike. The device
+ * cannot distinguish a dead tunnel from a dead relay from a dead preview, and
+ * must not try.
+ */
+export declare function recordSendFailure(): number;
+/**
+ * A successful POST resets to 0, UNCONDITIONALLY. One send getting through proves
+ * the channel is alive, so the next failure is a first failure again.
+ *
+ * Nothing else calls this. Not the panel closing, not the chip being tapped, not
+ * a timer, not a visibility change — see the module comment.
+ */
+export declare function recordSendSuccess(): void;
+/** Test-only: restore the module counter to its initial state. */
+export declare function __resetFailureCounterForTests(): void;
+/** At 2+ consecutive failures the channel is gone, not having a bad moment. */
+export declare function isStranded(): boolean;
 export interface FeedbackButtonOptions extends SendAnnotationOptions {
     sessionId?: string;
-    /** Collect the creator's message. Default: window.prompt. */
-    promptMessage?: () => string | null | Promise<string | null>;
     /** Override the captured spec (strokes/pins/labels). Default: empty. */
     spec?: AnnotationSpec;
+    /** Injectable for tests. Defaults to `window.matchMedia`. */
+    matchMedia?: typeof window.matchMedia;
+    /** Injectable for tests. Defaults to `window.location`. */
+    location?: Pick<Location, "origin" | "protocol" | "hostname">;
+    /** Injectable for tests. Defaults to the real POST. */
+    send?: (input: AnnotationInput) => Promise<unknown>;
+    /** Injectable for tests. Defaults to `captureScreenshot`. */
+    capture?: () => string;
+    /** Injectable for tests. Defaults to the real `window` (self/top identity). */
+    view?: FramingView;
 }
 /**
- * Mount a minimal floating "Send feedback" button. On click it collects a message,
- * captures the frame, and sends the annotation. Returns an unmount function. This
- * is the smallest useful Send action; a richer draw-on-frame overlay can replace
- * the capture/prompt without changing the wire contract.
+ * Is the feedback chip shown? The MIRROR of Share's rule, because the two are
+ * opposite handoffs. Share is `!isPhone(mm) && isPreviewOrigin(loc)`; feedback
+ * keeps the origin arm and DROPS the phone veto, because a phone is the device
+ * this control exists for. So the gate is the origin arm alone:
+ *
+ * | context                       | Share  | feedback |
+ * |-------------------------------|--------|----------|
+ * | coarse-pointer / narrow       | absent | PRESENT  |
+ * | desktop                       | present| present  |
+ * | real preview origin           | req'd  | req'd    |
+ * | plain localhost / LAN         | absent | ABSENT — no relay reachable |
+ *
+ * `matchMedia` is NOT a parameter: no viewport class can change this answer, and
+ * taking one would imply a veto that does not exist. Never rendered disabled or
+ * explained-away — on localhost nothing is appended at all.
+ */
+export declare function shouldShowFeedback(loc: Pick<Location, "protocol" | "hostname">): boolean;
+/**
+ * Mount the icon-only Send-feedback chip into the shared cluster and wire its
+ * composing panel.
+ *
+ * The show-gate is evaluated ONCE, here at mount. If it fails, nothing is
+ * appended to the DOM (no disabled state) and the returned unmount is a no-op.
+ *
+ * Share mounts first from HarnessProvider, and insertion order IS flex order, so
+ * appending here always leaves Share as the cluster's first member.
+ *
+ * THE FRAMED VETO (f13 `D-Feedback-does-not-mount-in-the-frame`, security
+ * MUST-FIX 5). Send POSTs to a route whose own comment states it is
+ * "unauthenticated and reachable by anyone holding the capability URL", and the
+ * write lands in the creator's coding-agent context. Inside a frame that control
+ * is positioned by the embedder's CSS on a page the creator did not choose to
+ * load it on, so a UI-redress lure (drag-and-paste into the textarea, a
+ * "click twice to continue" chain) reaches a text-injection channel needing no
+ * browser permission grant at all — the class of harm the frame's absent `allow`
+ * was built to stop, arriving through a door `allow` does not cover.
+ *
+ * THE MOUNT is gated, not the visibility. A hidden-but-mounted chip still holds
+ * the write path, and a hidden control is exactly what an overlay attack wants.
+ * Nothing is appended; there is no disabled state to re-enable.
+ *
+ * The cost is small and known: a creator viewing their own preview framed in
+ * their own console cannot Send from inside the frame. It is their own agent and
+ * the terminal is where they are already talking to it.
  */
 export declare function mountFeedbackButton(opts?: FeedbackButtonOptions): () => void;

package/dist/client/annotate.js

@@ -1,12 +1,22 @@
 // The in-app capture overlay's Send action — the client half of the reverse
-// channel. It captures the current frame, packages the creator's message + spec,
+// channel. It captures the current frame, packages the viewer's message + spec,
 // and POSTs it to the relay over the same tunnel the app is served on. The relay
 // (see the CLI's relay/annotations) stamps + persists it and unblocks a waiting
 // `vincentt feedback --wait`.
 //
 // Loaded via dynamic import from HarnessProvider (like the instrumentation), so a
 // production build never ships it. DOM-only, no React.
+//
+// THE DEVICE IS TOLD ABOUT ITS OWN SEND AND NOTHING ELSE. The reader may be a
+// client or a stranger, so no string on this surface may name the agent, the
+// developer, the creator, a queue depth, a read receipt, a send history, the
+// project/org/folder, or the state of the creator's machine. `Can't reach the
+// preview.` is legal precisely because it is a fact about THIS DEVICE'S OWN
+// failed request — the only thing the device actually observed.
 import { getClusterContainer, releaseClusterContainer } from "./cluster.js";
+// From the dependency-free leaf, NOT from share.ts — importing share.ts here
+// would statically pull `qrcode` into the feedback chip's chunk.
+import { isFramed, isPreviewOrigin } from "./previewOrigin.js";
 /** Default relay HTTP base: the same origin the app is served on + the harness path. */
 function defaultRelayHttpUrl() {
     return `${window.location.origin}/__harness`;
@@ -47,60 +57,446 @@ export async function sendAnnotation(input, opts = {}) {
         throw new Error(`annotation POST failed: ${res.status}`);
     return (await res.json());
 }
+// ── The two-strike counter ──────────────────────────────────────────────────
+//
+// Module-scoped, because the evidence it holds is "this page's sends", not "this
+// panel's sends" — a counter reset by closing the panel would strand nobody and
+// warn nobody. It dies with the page, which is the one acceptable reset: a
+// reloaded page has genuinely lost its evidence.
+let consecutiveFailures = 0;
+/** The counter's current value. Exported for tests; not part of the app surface. */
+export function getConsecutiveFailures() {
+    return consecutiveFailures;
+}
 /**
- * Mount a minimal floating "Send feedback" button. On click it collects a message,
- * captures the frame, and sends the annotation. Returns an unmount function. This
- * is the smallest useful Send action; a richer draw-on-frame overlay can replace
- * the capture/prompt without changing the wire contract.
+ * ANY failed POST increments — non-2xx, network error, abort alike. The device
+ * cannot distinguish a dead tunnel from a dead relay from a dead preview, and
+ * must not try.
+ */
+export function recordSendFailure() {
+    consecutiveFailures += 1;
+    return consecutiveFailures;
+}
+/**
+ * A successful POST resets to 0, UNCONDITIONALLY. One send getting through proves
+ * the channel is alive, so the next failure is a first failure again.
+ *
+ * Nothing else calls this. Not the panel closing, not the chip being tapped, not
+ * a timer, not a visibility change — see the module comment.
+ */
+export function recordSendSuccess() {
+    consecutiveFailures = 0;
+}
+/** Test-only: restore the module counter to its initial state. */
+export function __resetFailureCounterForTests() {
+    consecutiveFailures = 0;
+}
+/** At 2+ consecutive failures the channel is gone, not having a bad moment. */
+export function isStranded() {
+    return consecutiveFailures >= 2;
+}
+// ── Copy ────────────────────────────────────────────────────────────────────
+const PANEL_HEADING = "What should change here?";
+const CAPTURE_NOTE = "This screen is attached.";
+const SEND_LABEL = "Send";
+const CHIP_LABEL = "Send feedback";
+const SENDING_LABEL = "Sending…";
+const SENT_LABEL = "Sent ✓";
+const FAILED_LABEL = "Failed — retry";
+// f3's 410-page construction with the phrase that does not apply here removed:
+// the tester is not asking for a new link, they are reporting that sending is
+// broken. Names no cause, offers no button that cannot work, invites no account.
+const STRANDED_LINES = ["Can't reach the preview.", "Ask whoever shared this link."];
+const SENT_REVERT_MS = 1500;
+// A pencil glyph, ~18px, `currentColor` so it inherits the chip's `#f5f2ef`.
+// Icon-only: the chip's meaning is carried by aria-label + title, never a visible
+// text label (which is what the shipped gradient pill used).
+const PENCIL_GLYPH_SVG = `<svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" focusable="false"><path d="M3 17.25V21h3.75L17.81 9.94l-3.75-3.75L3 17.25Zm2 .83 9.06-9.06.92.92L5.92 19H5v-.92ZM20.71 5.63l-2.34-2.34a1 1 0 0 0-1.41 0l-1.83 1.83 3.75 3.75 1.83-1.83a1 1 0 0 0 0-1.41Z"/></svg>`;
+// Chip chrome — the SAME constants as share.ts's Share chip. The two chips sit in
+// one 8px cluster on the creator's own screen; they differ only in glyph.
+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 SANS = "-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif";
+/**
+ * Is the feedback chip shown? The MIRROR of Share's rule, because the two are
+ * opposite handoffs. Share is `!isPhone(mm) && isPreviewOrigin(loc)`; feedback
+ * keeps the origin arm and DROPS the phone veto, because a phone is the device
+ * this control exists for. So the gate is the origin arm alone:
+ *
+ * | context                       | Share  | feedback |
+ * |-------------------------------|--------|----------|
+ * | coarse-pointer / narrow       | absent | PRESENT  |
+ * | desktop                       | present| present  |
+ * | real preview origin           | req'd  | req'd    |
+ * | plain localhost / LAN         | absent | ABSENT — no relay reachable |
+ *
+ * `matchMedia` is NOT a parameter: no viewport class can change this answer, and
+ * taking one would imply a veto that does not exist. Never rendered disabled or
+ * explained-away — on localhost nothing is appended at all.
+ */
+export function shouldShowFeedback(loc) {
+    return isPreviewOrigin(loc);
+}
+/**
+ * Mount the icon-only Send-feedback chip into the shared cluster and wire its
+ * composing panel.
+ *
+ * The show-gate is evaluated ONCE, here at mount. If it fails, nothing is
+ * appended to the DOM (no disabled state) and the returned unmount is a no-op.
+ *
+ * Share mounts first from HarnessProvider, and insertion order IS flex order, so
+ * appending here always leaves Share as the cluster's first member.
+ *
+ * THE FRAMED VETO (f13 `D-Feedback-does-not-mount-in-the-frame`, security
+ * MUST-FIX 5). Send POSTs to a route whose own comment states it is
+ * "unauthenticated and reachable by anyone holding the capability URL", and the
+ * write lands in the creator's coding-agent context. Inside a frame that control
+ * is positioned by the embedder's CSS on a page the creator did not choose to
+ * load it on, so a UI-redress lure (drag-and-paste into the textarea, a
+ * "click twice to continue" chain) reaches a text-injection channel needing no
+ * browser permission grant at all — the class of harm the frame's absent `allow`
+ * was built to stop, arriving through a door `allow` does not cover.
+ *
+ * THE MOUNT is gated, not the visibility. A hidden-but-mounted chip still holds
+ * the write path, and a hidden control is exactly what an overlay attack wants.
+ * Nothing is appended; there is no disabled state to re-enable.
+ *
+ * The cost is small and known: a creator viewing their own preview framed in
+ * their own console cannot Send from inside the frame. It is their own agent and
+ * the terminal is where they are already talking to it.
  */
 export function mountFeedbackButton(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;
+    if (isFramed(opts.view))
+        return () => undefined;
+    if (!shouldShowFeedback(location))
+        return () => undefined;
+    const send = opts.send ??
+        ((input) => sendAnnotation(input, { relayHttpUrl: opts.relayHttpUrl }));
+    const capture = opts.capture ?? captureScreenshot;
+    const container = getClusterContainer();
+    let released = false;
+    // The typed text lives HERE, outside the panel, so it survives every panel
+    // close and every failure. The words are the expensive part; a tester who must
+    // retype them will not.
+    let draft = "";
+    let revertTimer;
     const btn = document.createElement("button");
-    btn.textContent = "Send feedback";
+    btn.type = "button";
+    btn.setAttribute("aria-label", CHIP_LABEL);
+    btn.title = CHIP_LABEL;
+    btn.setAttribute("aria-haspopup", "dialog");
+    btn.setAttribute("aria-controls", "vt-feedback-panel");
+    btn.setAttribute("aria-expanded", "false");
+    btn.innerHTML = PENCIL_GLYPH_SVG;
     Object.assign(btn.style, {
-        padding: "10px 14px",
+        width: "36px",
+        height: "36px",
+        padding: "0",
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
         borderRadius: "10px",
-        border: "none",
-        background: "linear-gradient(135deg,#7c3aed,#2563eb)",
-        color: "#fff",
-        font: "600 13px/1 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif",
-        boxShadow: "0 4px 16px rgba(0,0,0,.25)",
+        border: `1px solid ${IDLE_BORDER}`,
+        background: IDLE_BG,
+        color: "#f5f2ef",
+        boxShadow: "0 1px 4px rgba(0,0,0,.5)",
         cursor: "pointer",
+        transition: "background 100ms, border-color 100ms",
     });
-    const setBusy = (busy, label) => {
+    const applyIdle = () => {
+        btn.style.background = IDLE_BG;
+        btn.style.borderColor = IDLE_BORDER;
+    };
+    const applyActive = () => {
+        btn.style.background = ACTIVE_BG;
+        btn.style.borderColor = ACTIVE_BORDER;
+    };
+    /**
+     * The chip's three widened text states. `Sending…` and `Sent ✓` are transient;
+     * `Failed — retry` does NOT auto-revert — a creator holding the phone at arm's
+     * length looks back seconds later.
+     */
+    const setChipText = (text) => {
+        if (text == null) {
+            btn.innerHTML = PENCIL_GLYPH_SVG;
+            btn.style.width = "36px";
+            btn.style.padding = "0";
+            return;
+        }
+        btn.textContent = text;
+        btn.style.width = "auto";
+        btn.style.padding = "0 10px";
+        btn.style.font = `600 13px/1 ${SANS}`;
+    };
+    const setBusy = (busy) => {
         btn.disabled = busy;
-        btn.textContent = label ?? "Send feedback";
         btn.style.opacity = busy ? "0.6" : "1";
     };
-    btn.addEventListener("click", async () => {
-        const getMsg = opts.promptMessage ?? (() => window.prompt("Feedback for the agent:"));
-        const message = await getMsg();
-        if (message == null || message.trim() === "")
+    let panel = null;
+    let field = 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 closePanel = (returnFocus) => {
+        if (!panel)
+            return;
+        // Preserve whatever is typed. Closing the panel is NOT a reset of anything.
+        if (field)
+            draft = field.value;
+        panel.remove();
+        panel = null;
+        field = 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 buildPanel = () => {
+        const pop = document.createElement("div");
+        pop.id = "vt-feedback-panel";
+        pop.setAttribute("role", "dialog");
+        pop.setAttribute("aria-label", PANEL_HEADING);
+        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",
+        });
+        // The stranded line, ABOVE the preserved text, at 2+ consecutive failures.
+        // It does not escalate further and there is no third state.
+        if (isStranded()) {
+            const stranded = document.createElement("div");
+            stranded.className = "vt-fb-stranded";
+            for (const line of STRANDED_LINES) {
+                const p = document.createElement("div");
+                p.textContent = line;
+                stranded.appendChild(p);
+            }
+            Object.assign(stranded.style, {
+                font: `500 13px/1.45 ${SANS}`,
+                color: "#f5f2ef",
+                margin: "0 0 12px",
+            });
+            pop.appendChild(stranded);
+        }
+        const heading = document.createElement("div");
+        heading.className = "vt-fb-heading";
+        heading.textContent = PANEL_HEADING;
+        Object.assign(heading.style, {
+            font: `600 14px/1.35 ${SANS}`,
+            color: "#f5f2ef",
+            margin: "0 0 8px",
+        });
+        const input = document.createElement("textarea");
+        input.className = "vt-fb-field";
+        input.rows = 3;
+        input.value = draft;
+        input.setAttribute("aria-label", PANEL_HEADING);
+        Object.assign(input.style, {
+            width: "100%",
+            font: `400 13px/1.45 ${SANS}`,
+            color: "#f5f2ef",
+            background: "rgba(255,255,255,.06)",
+            border: "1px solid rgba(255,255,255,.10)",
+            borderRadius: "8px",
+            padding: "8px 10px",
+            boxSizing: "border-box",
+            resize: "vertical",
+        });
+        // States the capture as a fact, once. No thumbnail — it is the screen they
+        // are looking at.
+        const note = document.createElement("div");
+        note.className = "vt-fb-note";
+        note.textContent = CAPTURE_NOTE;
+        Object.assign(note.style, {
+            font: `400 12px/1.45 ${SANS}`,
+            color: "#b8b2a9",
+            margin: "8px 0 10px",
+        });
+        const sendBtn = document.createElement("button");
+        sendBtn.type = "button";
+        sendBtn.className = "vt-fb-send";
+        sendBtn.textContent = SEND_LABEL;
+        Object.assign(sendBtn.style, {
+            width: "100%",
+            padding: "8px 12px",
+            borderRadius: "8px",
+            border: "1px solid rgba(255,255,255,.14)",
+            background: "rgba(255,255,255,.06)",
+            color: "#f5f2ef",
+            font: `600 13px/1 ${SANS}`,
+            cursor: "pointer",
+            boxSizing: "border-box",
+        });
+        // Disabled until the field is non-empty — and ONLY for that reason. A
+        // stranded tester's Send stays enabled: a channel that has come back will
+        // simply succeed and clear the counter.
+        const syncSendEnabled = () => {
+            const empty = input.value.trim() === "";
+            sendBtn.disabled = empty;
+            sendBtn.style.opacity = empty ? "0.5" : "1";
+            sendBtn.style.cursor = empty ? "default" : "pointer";
+        };
+        syncSendEnabled();
+        input.addEventListener("input", () => {
+            draft = input.value;
+            syncSendEnabled();
+        });
+        sendBtn.addEventListener("click", () => void submit());
+        pop.append(heading, input, note, sendBtn);
+        field = input;
+        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)";
+            requestAnimationFrame(() => {
+                pop.style.opacity = "1";
+                pop.style.transform = "translateY(0) scale(1)";
+            });
+        }
+        return pop;
+    };
+    const openPanel = () => {
+        if (panel)
             return;
-        setBusy(true, "Sending…");
+        // Tapping the chip out of a Failed state opens the panel with the text
+        // preserved. It does NOT clear the counter.
+        if (revertTimer !== undefined) {
+            clearTimeout(revertTimer);
+            revertTimer = undefined;
+        }
+        setChipText(null);
+        panel = buildPanel();
+        container.appendChild(panel);
+        btn.setAttribute("aria-expanded", "true");
+        applyActive();
+        field?.focus();
+        outsideHandler = (e) => {
+            const target = e.target;
+            if (!target)
+                return;
+            if (panel && (panel.contains(target) || btn.contains(target)))
+                return;
+            closePanel(false);
+        };
+        document.addEventListener("mousedown", outsideHandler, true);
+        keyHandler = (e) => {
+            if (e.key === "Escape") {
+                e.stopPropagation();
+                closePanel(true);
+            }
+        };
+        document.addEventListener("keydown", keyHandler);
+    };
+    async function submit() {
+        const message = draft.trim();
+        if (message === "")
+            return;
+        closePanel(false);
+        setChipText(SENDING_LABEL);
+        setBusy(true);
         try {
-            const screenshot = captureScreenshot();
             const input = {
-                message: message.trim(),
-                screenshot,
+                message,
+                screenshot: capture(),
                 spec: opts.spec ?? {},
                 sessionId: opts.sessionId,
             };
-            await sendAnnotation(input, { relayHttpUrl: opts.relayHttpUrl });
-            setBusy(false, "Sent ✓");
-            window.setTimeout(() => setBusy(false), 1500);
+            await send(input);
+            recordSendSuccess();
+            draft = "";
+            setBusy(false);
+            setChipText(SENT_LABEL);
+            revertTimer = window.setTimeout(() => {
+                revertTimer = undefined;
+                setChipText(null);
+            }, SENT_REVERT_MS);
         }
-        catch (err) {
-            setBusy(false, "Failed — retry");
-            console.error("[harness] annotation send failed:", err);
+        catch {
+            // Any non-2xx, and any network/abort error. The draft is untouched.
+            recordSendFailure();
+            setBusy(false);
+            setChipText(FAILED_LABEL);
+            // Deliberately NOT logged: the message is viewer-authored, and a console
+            // line would put it in the creator's scrollback and their agent's context.
         }
+    }
+    btn.addEventListener("mouseenter", () => {
+        if (panel)
+            return; // active state wins over hover
+        btn.style.background = HOVER_BG;
+        btn.style.borderColor = HOVER_BORDER;
+    });
+    btn.addEventListener("mouseleave", () => {
+        if (panel)
+            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";
     });
-    // 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);
+    btn.addEventListener("click", () => {
+        if (panel)
+            closePanel(false);
+        else
+            openPanel();
+    });
+    container.appendChild(btn);
     return () => {
+        if (revertTimer !== undefined) {
+            clearTimeout(revertTimer);
+            revertTimer = undefined;
+        }
+        closePanel(false);
         btn.remove();
-        releaseClusterContainer();
+        if (!released) {
+            released = true;
+            releaseClusterContainer();
+        }
     };
 }

package/dist/client/index.d.ts

@@ -1,7 +1,8 @@
 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 { 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,7 @@
 // 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 { 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,10 @@
-/**
- * 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"];
+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

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 { 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

package/dist/shared/events.d.ts

@@ -129,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[];
@@ -171,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.2.0",
+  "version": "1.3.0",
   "description": "Vincentt AR dev-loop harness - in-app diagnostics provider + wire contract",
   "license": "UNLICENSED",
   "type": "module",