@vincentt-xr/harness 1.1.0 → 1.3.0

package/dist/client/HarnessProvider.d.ts

@@ -24,10 +24,17 @@ export interface HarnessProviderProps {
     captureNetwork?: boolean;
     captureTrace?: boolean;
     /**
-     * Mount the floating "Send feedback" button (the reverse-channel capture
-     * overlay). Defaults to `enabled` — on in preview, gone in production.
+     * 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;
+    /**
+     * Mount the in-app Share control (the desktop-to-phone QR handoff overlay).
+     * Defaults to `enabled` — on in preview, tree-shaken out of production.
+     */
+    share?: boolean;
 }
 /**
  * 128 bits of CSPRNG, hex, as `s2_<32 hex>`.

package/dist/client/HarnessProvider.js

@@ -90,10 +90,42 @@ export function HarnessProvider(props) {
                 captureTrace: props.captureTrace,
             });
         });
+        let unmountShare;
         let unmountFeedback;
-        if (props.feedback !== false) {
-            // 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;
@@ -111,6 +143,7 @@ export function HarnessProvider(props) {
             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.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;