@vincentt-xr/harness 0.4.0 → 1.1.0

package/dist/client/HarnessProvider.d.ts

@@ -12,10 +12,52 @@ 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.
+     */
+    feedback?: 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;
@@ -52,9 +90,27 @@ export function HarnessProvider(props) {
                 captureTrace: props.captureTrace,
             });
         });
+        let unmountFeedback;
+        if (props.feedback !== false) {
+            // 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;
+                // 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(),
+                });
+            });
+        }
         return () => {
             cancelled = true;
             teardown?.();
+            unmountFeedback?.();
         };
         // Instrumentation is installed once for the provider's lifetime; option
         // changes mid-session are not a supported case.

package/dist/client/annotate.d.ts

@@ -0,0 +1,34 @@
+import type { AnnotationInput, AnnotationSpec } from "../shared/events.js";
+/**
+ * Capture the current frame as a PNG data URL. Prefers the largest <canvas> (the
+ * AR/three.js surface); returns an empty-ish 1x1 PNG if there is none.
+ *
+ * Caveat: reading a WebGL canvas requires it to have been created with
+ * `preserveDrawingBuffer: true`, or the read can come back blank. r3f/three set
+ * this via `gl={{ preserveDrawingBuffer: true }}`. DOM-only content isn't captured
+ * here (that needs html2canvas, deliberately not a dependency).
+ */
+export declare function captureScreenshot(): string;
+export interface SendAnnotationOptions {
+    /** Relay HTTP base (default: `<origin>/__harness`). */
+    relayHttpUrl?: string;
+}
+/** POST an annotation to the relay. Resolves with the relay-assigned id + seq. */
+export declare function sendAnnotation(input: AnnotationInput, opts?: SendAnnotationOptions): Promise<{
+    id: string;
+    seq: number;
+}>;
+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;
+}
+/**
+ * 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.
+ */
+export declare function mountFeedbackButton(opts?: FeedbackButtonOptions): () => void;

package/dist/client/annotate.js

@@ -0,0 +1,104 @@
+// 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,
+// 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.
+/** Default relay HTTP base: the same origin the app is served on + the harness path. */
+function defaultRelayHttpUrl() {
+    return `${window.location.origin}/__harness`;
+}
+/**
+ * Capture the current frame as a PNG data URL. Prefers the largest <canvas> (the
+ * AR/three.js surface); returns an empty-ish 1x1 PNG if there is none.
+ *
+ * Caveat: reading a WebGL canvas requires it to have been created with
+ * `preserveDrawingBuffer: true`, or the read can come back blank. r3f/three set
+ * this via `gl={{ preserveDrawingBuffer: true }}`. DOM-only content isn't captured
+ * here (that needs html2canvas, deliberately not a dependency).
+ */
+export function captureScreenshot() {
+    const canvases = Array.from(document.querySelectorAll("canvas"));
+    const biggest = canvases.sort((a, b) => b.width * b.height - a.width * a.height)[0];
+    if (biggest) {
+        try {
+            return biggest.toDataURL("image/png");
+        }
+        catch {
+            // Tainted canvas (cross-origin texture without CORS) — fall through.
+        }
+    }
+    const fallback = document.createElement("canvas");
+    fallback.width = fallback.height = 1;
+    return fallback.toDataURL("image/png");
+}
+/** POST an annotation to the relay. Resolves with the relay-assigned id + seq. */
+export async function sendAnnotation(input, opts = {}) {
+    const base = opts.relayHttpUrl ?? defaultRelayHttpUrl();
+    const res = await fetch(`${base}/annotation`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input),
+    });
+    if (!res.ok)
+        throw new Error(`annotation POST failed: ${res.status}`);
+    return (await res.json());
+}
+/**
+ * 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.
+ */
+export function mountFeedbackButton(opts = {}) {
+    if (typeof document === "undefined")
+        return () => undefined;
+    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",
+        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)",
+        cursor: "pointer",
+    });
+    const setBusy = (busy, label) => {
+        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() === "")
+            return;
+        setBusy(true, "Sending…");
+        try {
+            const screenshot = captureScreenshot();
+            const input = {
+                message: message.trim(),
+                screenshot,
+                spec: opts.spec ?? {},
+                sessionId: opts.sessionId,
+            };
+            await sendAnnotation(input, { relayHttpUrl: opts.relayHttpUrl });
+            setBusy(false, "Sent ✓");
+            window.setTimeout(() => setBusy(false), 1500);
+        }
+        catch (err) {
+            setBusy(false, "Failed — retry");
+            console.error("[harness] annotation send failed:", err);
+        }
+    });
+    document.body.appendChild(btn);
+    return () => btn.remove();
+}

package/dist/client/index.d.ts

@@ -1,3 +1,5 @@
 export { HarnessProvider } from "./HarnessProvider.js";
 export type { HarnessProviderProps } from "./HarnessProvider.js";
+export { sendAnnotation, captureScreenshot, mountFeedbackButton, type SendAnnotationOptions, type FeedbackButtonOptions, } from "./annotate.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,3 +3,4 @@
 // 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";

package/dist/shared/events.d.ts

@@ -1,5 +1,30 @@
 /** Monotonic-ish wall-clock ms since epoch, stamped by the client at capture. */
 export type Timestamp = number;
+/**
+ * The grammar of the client's session id — the key the relay groups a TESTER by.
+ *
+ * It lives here, in the file all three parts import, for the same reason
+ * VIEWER_LABEL_RE lives beside the codec that produces the label: the party that
+ * mints the value and the party that validates it must not be able to disagree
+ * about its shape. The client writes this shape; the relay accepts this shape and
+ * nothing else, with no sanitize-and-keep branch.
+ *
+ * `s2_` is generation two. Generation one was `s_<base36 time>_<base36 rand>` over
+ * ~10^6 of Math.random, which grouped a RUN. Grouping a TESTER makes a collision a
+ * silent merge of two people's streams, so the space is now 128 bits and the
+ * prefix is what lets a relay tell the two generations apart on sight.
+ */
+export declare const CLIENT_SESSION_ID_RE: RegExp;
+/**
+ * A relay-assigned tester id: `t1`, `t2`, … Minted on the CREATOR'S machine and
+ * never on the wire from the device — it is a local relabeling of a key the
+ * device supplied, which is what keeps the platform free of a correlator (B22).
+ *
+ * No leading zero. Ids are counted from 1 and never zero-padded, so `t01` is a
+ * string the registry cannot have produced; accepting it at the filter boundary
+ * would admit a second spelling for a value with one canonical form.
+ */
+export declare const TESTER_ID_RE: RegExp;
 /** Kinds of thing the diagnostics limb observes. */
 export type DiagEventKind = "log" | "network" | "trace";
 interface DiagEventBase {
@@ -62,17 +87,127 @@ export interface ClientToRelay {
 }
 /** What the MCP server asks the relay for. `since` is an exclusive seq cursor. */
 export interface RelayQuery {
-    sessionId?: string;
     kind?: DiagEventKind;
     since?: number;
     /** Cap the returned count (newest-biased); relay clamps to its buffer size. */
     limit?: number;
+    /**
+     * Filter to one TESTER — one browser tab, recognised across refreshes. This is
+     * the filter that answers "it breaks on their phone but not mine", because it
+     * survives the reload the tester does first.
+     *
+     * A malformed id filters to NOTHING rather than being ignored: silently
+     * widening a filter shows the creator several testers' events under a heading
+     * naming one.
+     */
+    tester?: string;
+    /**
+     * Filter to one viewer — one CONNECTION (2.8), not an identity (B22). The
+     * sub-coordinate below the tester: a single tab opens several of these under
+     * HTTP/1.1, so this narrows to one of them and is for connection-level
+     * debugging rather than for "whose phone".
+     */
+    viewer?: string;
 }
 export interface RelayResult {
     events: DiagEvent[];
+    /**
+     * `eventViewers[i]` is the label that produced `events[i]`, or undefined when
+     * the relay could not attribute it.
+     *
+     * It rides ALONGSIDE the events rather than on them because a viewer label is
+     * a fact about the CONNECTION that carried an observation, not a property of
+     * the observation — putting it on the event would make it look like something
+     * the device reported about itself, which is the identity promotion B22
+     * forbids.
+     */
+    eventViewers?: (string | undefined)[];
+    /**
+     * `eventTesters[i]` is the tester that produced `events[i]`, or undefined when
+     * the relay could not attribute it (the pre-mount window, a crashed app, a
+     * non-app request, or a session past the cap).
+     *
+     * Rides alongside for the same reason as `eventViewers`: which tester an
+     * observation came from is a fact about the CONNECTION that carried it, not a
+     * property of the observation.
+     */
+    eventTesters?: (string | undefined)[];
     /** Highest seq the relay currently holds, so the caller can advance `since`. */
     latestSeq: number;
-    /** Sessions the relay has seen events for (so the agent can disambiguate). */
-    sessions: string[];
+    /**
+     * Tester ids the relay has assigned, in arrival order. Every member matches
+     * TESTER_ID_RE.
+     *
+     * This REPLACED a `sessions` array that carried the raw client-supplied key to
+     * the terminal and to MCP tool output. That was a viewer-controlled string
+     * with no validation reaching the creator's coding agent — do not reintroduce
+     * it. The raw key is an opaque map key inside the relay and nothing else.
+     */
+    testers: string[];
+    /**
+     * Viewer labels the relay has seen. Labels churn — a reconnecting device gets
+     * a NEW label and the old one is never reused — so the caller needs the live
+     * set rather than remembering one.
+     */
+    viewers: string[];
+}
+/** A freehand stroke over the frame, in normalized [0,1] frame coordinates. */
+export interface AnnotationStroke {
+    points: {
+        x: number;
+        y: number;
+    }[];
+    color?: string;
+}
+/** A point marker on the frame, in normalized [0,1] frame coordinates. */
+export interface AnnotationPin {
+    x: number;
+    y: number;
+    label?: string;
+}
+/** The drawn overlay accompanying an annotation. All fields optional — a bare
+ *  message with a screenshot is a valid annotation. */
+export interface AnnotationSpec {
+    strokes?: AnnotationStroke[];
+    pins?: AnnotationPin[];
+    labels?: string[];
+    note?: string;
+}
+/** Client → relay POST body (`POST /__harness/annotation`). The relay stamps the
+ *  id, receipt time, project binding, and on-disk screenshot path. */
+export interface AnnotationInput {
+    /** The creator's message to the agent. */
+    message: string;
+    /** Annotated frame as a data URL (image/png). */
+    screenshot: string;
+    spec?: AnnotationSpec;
+    /**
+     * The client's session key, so the annotation can be correlated with the diag
+     * events from the same tab. Client-supplied and therefore hostile input: the
+     * relay REPLACES it with the tester id it resolves to, or drops it. It is
+     * never persisted or forwarded verbatim — this record reaches an agent.
+     */
+    sessionId?: string;
+}
+/** A persisted annotation the agent consumes (via `vincentt feedback --wait`). */
+export interface Annotation {
+    /** Short relay-assigned id (e.g. "a7f3"). */
+    id: string;
+    /** Monotonic per-project cursor; a consumer polls "after this seq". */
+    seq: number;
+    /** Receipt time, stamped by the relay (not the browser). */
+    createdAt: Timestamp;
+    /** The bound project directory this annotation belongs to. */
+    projectDir: string;
+    /** The creator's message to the agent. */
+    message: string;
+    /** Absolute path to the full-res annotated screenshot on disk. */
+    screenshotPath: string;
+    spec: AnnotationSpec;
+    /**
+     * The TESTER this annotation came from, or absent when the relay could not
+     * attribute it. Never the raw client key — see AnnotationInput.sessionId.
+     */
+    sessionId?: string;
 }
 export {};

package/dist/shared/events.js

@@ -3,4 +3,28 @@
 // server (which serves them to the agent). All three import THIS file, so the
 // three can never drift on the shape of an event. Nothing here imports React,
 // node, or MCP — it is pure data.
-export {};
+/**
+ * The grammar of the client's session id — the key the relay groups a TESTER by.
+ *
+ * It lives here, in the file all three parts import, for the same reason
+ * VIEWER_LABEL_RE lives beside the codec that produces the label: the party that
+ * mints the value and the party that validates it must not be able to disagree
+ * about its shape. The client writes this shape; the relay accepts this shape and
+ * nothing else, with no sanitize-and-keep branch.
+ *
+ * `s2_` is generation two. Generation one was `s_<base36 time>_<base36 rand>` over
+ * ~10^6 of Math.random, which grouped a RUN. Grouping a TESTER makes a collision a
+ * silent merge of two people's streams, so the space is now 128 bits and the
+ * prefix is what lets a relay tell the two generations apart on sight.
+ */
+export const CLIENT_SESSION_ID_RE = /^s2_[0-9a-f]{32}$/;
+/**
+ * A relay-assigned tester id: `t1`, `t2`, … Minted on the CREATOR'S machine and
+ * never on the wire from the device — it is a local relabeling of a key the
+ * device supplied, which is what keeps the platform free of a correlator (B22).
+ *
+ * No leading zero. Ids are counted from 1 and never zero-padded, so `t01` is a
+ * string the registry cannot have produced; accepting it at the filter boundary
+ * would admit a second spelling for a value with one canonical form.
+ */
+export const TESTER_ID_RE = /^t[1-9][0-9]{0,2}$/;

package/dist/tunnel/cbor.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The CBOR SUBSET, Node half. It mirrors `api/internal/edge/cbor.go` decision
+ * for decision, because two implementations of one wire format that were
+ * written independently are two implementations that drift.
+ *
+ * It decodes CONTROL payloads only — OPEN and HEAD. It NEVER touches a DATA
+ * payload.
+ *
+ * It is hand-written rather than a library for the same reason the Go one is: a
+ * general CBOR library's allocation behavior on hostile input would be someone
+ * else's decision, and the limits below are the whole point.
+ *
+ * Everything indefinite-length, every tag, every float, every byte string and
+ * every negative integer is REFUSED — not because they are dangerous in
+ * themselves, but because the encoder we own never emits them, so accepting
+ * them would only widen the input this parser has to be correct about.
+ */
+/**
+ * VIEWER_LABEL_RE is the SAME regex the edge assigns against, and this client
+ * RE-VALIDATES rather than trusting the edge. That is closure (c) of the three
+ * that keep viewer-supplied bytes out of the creator's agent's context: the
+ * label flows viewerLabel -> the relay ring-buffer key -> CLI terminal output
+ * and MCP tool output, which is a terminal/log-injection path INTO the agent,
+ * and a Go-only check would pass on a client that trusted the edge.
+ */
+export declare const VIEWER_LABEL_RE: RegExp;
+export declare function parseViewerLabel(s: string): string | null;
+/**
+ * UA_CLASSES is the CLOSED ENUM OF SIX, mirroring the Go edge. `unknown` is the
+ * TOTAL fallback. This client validates the class it receives against this set
+ * before stamping the relay handshake, so an unmatched or forged class becomes
+ * `unknown` rather than an echo.
+ */
+export declare const UA_CLASSES: readonly ["ios_safari", "android_chrome", "desktop_chrome", "desktop_safari", "desktop_firefox", "unknown"];
+export type UAClass = (typeof UA_CLASSES)[number];
+export declare function parseUAClass(s: string): UAClass;
+export interface OpenPayload {
+    viewerLabel: string;
+    method: string;
+    path: string;
+    headers: [string, string][];
+    upgrade?: string;
+}
+export interface HeadPayload {
+    status: number;
+    headers: [string, string][];
+}
+/**
+ * `viewer_gone` is the ONE non-terminal kind: the other three mean the session
+ * is ending, this one means a viewer's connection closed while the session
+ * continues. It is also the only kind carrying a second key.
+ */
+export type ControlKind = "revoke" | "expiring" | "superseded" | "viewer_gone";
+/** A decoded CONTROL payload. `viewerLabel` is present only on `viewer_gone`. */
+export interface ControlPayload {
+    kind: ControlKind;
+    viewerLabel?: string;
+}
+export declare function decodeOpen(b: Uint8Array): OpenPayload;
+export declare function decodeHead(b: Uint8Array): HeadPayload;
+/**
+ * The map arity is asserted AGAINST THE KIND, so a payload claiming `revoke`
+ * with a trailing label is refused as malformed rather than quietly accepted
+ * with the extra key ignored.
+ */
+export declare function decodeControl(b: Uint8Array): ControlPayload;
+/** Canonical key order: viewerLabel, method, path, headers, [upgrade]. */
+export declare function encodeOpen(p: OpenPayload): Uint8Array;
+/** Canonical key order: status, headers. */
+export declare function encodeHead(p: HeadPayload): Uint8Array;
+export declare function encodeControl(kind: ControlKind, viewerLabel?: string): Uint8Array;