@vincentt-xr/harness 1.2.0 → 1.4.0

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/channel.d.ts

@@ -0,0 +1,47 @@
+import { type AnnouncedPreset, type ConsoleSetMediaSourceMessage, type HarnessAnnounceMessage } from "../shared/channel.js";
+import { type FramingView } from "./previewOrigin.js";
+/** The minimum of `window` this needs, so the whole module is testable without a DOM. */
+export interface ChannelWindow {
+    parent: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    } | null;
+    addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+}
+export interface ChannelOptions {
+    /** The presets this app can play. Announced verbatim after validation. */
+    presets: AnnouncedPreset[];
+    /** Applied when the console names a preset. The app owns the swap; the console never does. */
+    onSetMediaSource: (presetId: string) => void;
+    /** The console origins commands may come from. Injected; defaults to the production set. */
+    allowedOrigins?: readonly string[];
+    /** Injectable for tests. Defaults to `window`. */
+    view?: ChannelWindow;
+    /** Injectable for tests. Defaults to `window`'s own handles. */
+    framing?: FramingView;
+}
+/**
+ * The announce, built from a preset list.
+ *
+ * Exported so a test can assert the payload's exact shape without a window, and
+ * so `url` never being on the wire is checkable at the boundary that produces it.
+ */
+export declare function buildAnnounce(presets: AnnouncedPreset[]): HarnessAnnounceMessage;
+/**
+ * Is this a command this app acts on?
+ *
+ * Shape check only — the origin is checked separately and BOTH must pass. Any
+ * other `type` on a well-formed envelope is ignored, which is what keeps `ack`,
+ * `error`, `log`, `count`, `re-announce` and `request` from becoming reachable
+ * by a console that decides to send one.
+ */
+export declare function isSetMediaSourceCommand(data: unknown): data is ConsoleSetMediaSourceMessage;
+/**
+ * Open the app's side of the channel. Returns a teardown.
+ *
+ * UNFRAMED IS A NO-OP. With no console around the app there is nothing to
+ * announce to and no chrome to command it, and the app keeps its own in-page
+ * controls instead. Nothing is posted and no listener is installed — the same
+ * absent-rather-than-inert rule the cluster controls follow.
+ */
+export declare function openConsoleChannel(opts: ChannelOptions): () => void;