@vincentt-xr/harness 1.2.0 → 1.4.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

@@ -9,6 +9,7 @@
 // but both are overridable for the production review-service path later.
 import { useEffect } from "react";
 import { CLIENT_SESSION_ID_RE } from "../shared/events.js";
+import { isFramed } from "./previewOrigin.js";
 function defaultRelayUrl() {
     if (typeof window === "undefined")
         return "ws://localhost:7331";
@@ -90,13 +91,53 @@ 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 decides whether the module is fetched at all — as does the
+        // framing check hoisted into `mountFeedback` below.
+        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;
+            // THE FRAMING CHECK RUNS BEFORE THE IMPORT, not only inside the mount.
+            // `mountFeedbackButton` gates itself too (defence in depth), but that gate
+            // runs after the module has already been fetched and evaluated — so the
+            // annotation module, which carries an unauthenticated same-origin write
+            // path, was being loaded inside the framed document that now holds a
+            // camera delegation. Nothing was appended and no chip rendered, so there
+            // was no redress target; the code was simply present. Hoisting the check
+            // here closes that outright rather than mitigating it.
+            if (isFramed())
+                return;
             void import("./annotate.js").then(({ mountFeedbackButton }) => {
                 if (cancelled)
                     return;
@@ -110,16 +151,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;