@reticlehq/browser 2.0.0

package/dist/registry/capabilities.js

@@ -0,0 +1,48 @@
+/** Self-describing capability registry — the testable surface the app advertises. */
+// Persist on a global so the registry survives HMR module re-evaluation (matches __reticleAdapters).
+const globalStore = globalThis;
+function empty() {
+    return { testids: [], signals: [], stores: [], flows: [] };
+}
+const capabilities = (globalStore.__reticleCapabilities ??= empty());
+function mergeUnique(into, add) {
+    if (add === undefined)
+        return;
+    for (const v of add)
+        if (!into.includes(v))
+            into.push(v);
+}
+/** Called by the host app via reticle.describe(). Merges (idempotent), never replaces wholesale. */
+export function registerCapabilities(input) {
+    mergeUnique(capabilities.testids, input.testids);
+    mergeUnique(capabilities.signals, input.signals);
+    mergeUnique(capabilities.stores, input.stores);
+    if (input.flows !== undefined) {
+        for (const flow of input.flows) {
+            const existing = capabilities.flows.find((f) => f.name === flow.name);
+            if (existing === undefined) {
+                capabilities.flows.push({ name: flow.name, steps: [...flow.steps] });
+            }
+            else {
+                existing.steps = [...flow.steps]; // last writer wins for a named flow
+            }
+        }
+    }
+}
+/** Snapshot copy of the registered capabilities (defensive — never hand out the live arrays). */
+export function getCapabilities() {
+    return {
+        testids: [...capabilities.testids],
+        signals: [...capabilities.signals],
+        stores: [...capabilities.stores],
+        flows: capabilities.flows.map((f) => ({ name: f.name, steps: [...f.steps] })),
+    };
+}
+/** Whether the app has advertised any capabilities (used in the HELLO flag). */
+export function hasCapabilities() {
+    return (capabilities.testids.length > 0 ||
+        capabilities.signals.length > 0 ||
+        capabilities.stores.length > 0 ||
+        capabilities.flows.length > 0);
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/registry/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/registry/capabilities.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAsBrF,qGAAqG;AACrG,MAAM,WAAW,GAAG,UAAiE,CAAC;AAEtF,SAAS,KAAK;IACZ,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,YAAY,GAAiB,CAAC,WAAW,CAAC,qBAAqB,KAAK,KAAK,EAAE,CAAC,CAAC;AAEnF,SAAS,WAAW,CAAC,IAAc,EAAE,GAAkC;IACrE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO;IAC9B,KAAK,MAAM,CAAC,IAAI,GAAG;QAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,oBAAoB,CAAC,KAAwB;IAC3D,WAAW,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACjD,WAAW,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACjD,WAAW,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC/B,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC;YACtE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACvE,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,oCAAoC;YACxE,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,OAAO,EAAE,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC;QAClC,OAAO,EAAE,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC;QAClC,MAAM,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC;QAChC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;KAC9E,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,eAAe;IAC7B,OAAO,CACL,YAAY,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QAC/B,YAAY,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QAC/B,YAAY,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAC9B,YAAY,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAC9B,CAAC;AACJ,CAAC"}

package/dist/registry/commit-and-signal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * P5b — pair a mutation with its signal so the two can't drift. The lighter alternative to a
+ * Zustand middleware: one call runs the mutation, then emits the signal exactly once, and returns
+ * the mutation's value. If `mutate` throws, the mutation never happened — so the signal is NOT
+ * emitted and the error propagates unchanged (no try/finally, which would wrongly emit on throw).
+ */
+import type { ReticleEmitter } from './emitter.js';
+export declare function commitAndSignal<T>(emitter: ReticleEmitter, mutate: () => T, name: string, data?: Record<string, unknown>): T;
+//# sourceMappingURL=commit-and-signal.d.ts.map

package/dist/registry/commit-and-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-and-signal.d.ts","sourceRoot":"","sources":["../../src/registry/commit-and-signal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,MAAM,CAAC,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,CAAC,CAIH"}

package/dist/registry/commit-and-signal.js

@@ -0,0 +1,12 @@
+/**
+ * P5b — pair a mutation with its signal so the two can't drift. The lighter alternative to a
+ * Zustand middleware: one call runs the mutation, then emits the signal exactly once, and returns
+ * the mutation's value. If `mutate` throws, the mutation never happened — so the signal is NOT
+ * emitted and the error propagates unchanged (no try/finally, which would wrongly emit on throw).
+ */
+export function commitAndSignal(emitter, mutate, name, data) {
+    const result = mutate(); // throws here? then signal below is never reached — by design.
+    emitter.signal(name, data);
+    return result;
+}
+//# sourceMappingURL=commit-and-signal.js.map

package/dist/registry/commit-and-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-and-signal.js","sourceRoot":"","sources":["../../src/registry/commit-and-signal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,UAAU,eAAe,CAC7B,OAAuB,EACvB,MAAe,EACf,IAAY,EACZ,IAA8B;IAE9B,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,+DAA+D;IACxF,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/registry/domains.d.ts

@@ -0,0 +1,15 @@
+/**
+ * P5c — self-registering domains. Instead of one hand-maintained flat-map of the whole testable
+ * surface, each app domain co-locates its `{ testids, signals, stores }` and calls
+ * `registerReticleDomain(...)`; the capability registry assembles itself from every domain. Thin
+ * adapter over `registerCapabilities`, so merge/dedupe (and HMR persistence) are reused, not
+ * reinvented — later calls accumulate as a union, empty domains are a no-op.
+ */
+/** A co-located domain bundle (one `reticle.ts` per app domain). */
+export interface ReticleDomain {
+    testids?: readonly string[];
+    signals?: readonly string[];
+    stores?: readonly string[];
+}
+export declare function registerReticleDomain(domain: ReticleDomain): void;
+//# sourceMappingURL=domains.d.ts.map

package/dist/registry/domains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../../src/registry/domains.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAMjE"}

package/dist/registry/domains.js

@@ -0,0 +1,19 @@
+/**
+ * P5c — self-registering domains. Instead of one hand-maintained flat-map of the whole testable
+ * surface, each app domain co-locates its `{ testids, signals, stores }` and calls
+ * `registerReticleDomain(...)`; the capability registry assembles itself from every domain. Thin
+ * adapter over `registerCapabilities`, so merge/dedupe (and HMR persistence) are reused, not
+ * reinvented — later calls accumulate as a union, empty domains are a no-op.
+ */
+import { registerCapabilities } from './capabilities.js';
+export function registerReticleDomain(domain) {
+    const input = {};
+    if (domain.testids !== undefined)
+        input.testids = [...domain.testids];
+    if (domain.signals !== undefined)
+        input.signals = [...domain.signals];
+    if (domain.stores !== undefined)
+        input.stores = [...domain.stores];
+    registerCapabilities(input);
+}
+//# sourceMappingURL=domains.js.map

package/dist/registry/domains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domains.js","sourceRoot":"","sources":["../../src/registry/domains.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,oBAAoB,EAA0B,MAAM,mBAAmB,CAAC;AASjF,MAAM,UAAU,qBAAqB,CAAC,MAAqB;IACzD,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACtE,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACtE,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACnE,oBAAoB,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}

package/dist/registry/emitter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The injected-emitter pattern (P5a): host-app components depend on a tiny structural interface
+ * instead of importing the SDK directly. The real emitter proxies to the connected `reticle`
+ * singleton; when Reticle isn't connected (or isn't loaded) every call is a SAFE NO-OP — so nothing
+ * breaks in production or before `reticle.connect()`, and `@reticlehq/browser` stays out of the prod bundle.
+ */
+/** Structural emitter the host app's components depend on. */
+export interface ReticleEmitter {
+    signal(name: string, data?: Record<string, unknown>): void;
+    state(name: string, value: unknown): void;
+}
+/** The subset of the reticle singleton an emitter proxies to (lets tests inject a fake). */
+export interface EmitterTarget {
+    signal(name: string, data?: Record<string, unknown>): void;
+    state(name: string, value: unknown): void;
+    /** Discriminator the emitter reads per call to decide forward-vs-no-op. */
+    readonly connected: boolean;
+}
+export interface CreateReticleEmitterOptions {
+    /** Override the proxy target (tests / advanced embedding). Defaults to the reticle singleton. */
+    target?: EmitterTarget;
+}
+/**
+ * Create an emitter. Reads `target.connected` on EVERY call (not at creation) so an emitter
+ * made at module load — before `reticle.connect()` — starts working the moment Reticle connects.
+ */
+export declare function createReticleEmitter(options?: CreateReticleEmitterOptions): ReticleEmitter;
+//# sourceMappingURL=emitter.d.ts.map

package/dist/registry/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/registry/emitter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3C;AAED,4FAA4F;AAC5F,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,2BAA2B;IAC1C,iGAAiG;IACjG,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,2BAAgC,GAAG,cAAc,CAY9F"}

package/dist/registry/emitter.js

@@ -0,0 +1,27 @@
+/**
+ * The injected-emitter pattern (P5a): host-app components depend on a tiny structural interface
+ * instead of importing the SDK directly. The real emitter proxies to the connected `reticle`
+ * singleton; when Reticle isn't connected (or isn't loaded) every call is a SAFE NO-OP — so nothing
+ * breaks in production or before `reticle.connect()`, and `@reticlehq/browser` stays out of the prod bundle.
+ */
+import { reticle } from '../index.js';
+/**
+ * Create an emitter. Reads `target.connected` on EVERY call (not at creation) so an emitter
+ * made at module load — before `reticle.connect()` — starts working the moment Reticle connects.
+ */
+export function createReticleEmitter(options = {}) {
+    const target = options.target ?? reticle;
+    return {
+        signal(name, data = {}) {
+            if (!target.connected)
+                return;
+            target.signal(name, data);
+        },
+        state(name, value) {
+            if (!target.connected)
+                return;
+            target.state(name, value);
+        },
+    };
+}
+//# sourceMappingURL=emitter.js.map

package/dist/registry/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../../src/registry/emitter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAqBtC;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAuC,EAAE;IAC5E,MAAM,MAAM,GAAkB,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC;IACxD,OAAO;QACL,MAAM,CAAC,IAAY,EAAE,OAAgC,EAAE;YACrD,IAAI,CAAC,MAAM,CAAC,SAAS;gBAAE,OAAO;YAC9B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC;QACD,KAAK,CAAC,IAAY,EAAE,KAAc;YAChC,IAAI,CAAC,MAAM,CAAC,SAAS;gBAAE,OAAO;YAC9B,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/registry/stores.d.ts

@@ -0,0 +1,9 @@
+/** Store registry — lets the agent pull live framework/store state on demand. */
+export type StoreGetter = () => unknown;
+/** App calls this once per store: registerStore('workspace', () => useWorkspace.getState()). */
+export declare function registerStore(name: string, getter: StoreGetter): void;
+export declare function unregisterStore(name: string): void;
+export declare function storeNames(): string[];
+/** Read one store (by name) or all of them. Each getter is isolated: a throw becomes an error string. */
+export declare function readStores(only?: string): Record<string, unknown>;
+//# sourceMappingURL=stores.d.ts.map

package/dist/registry/stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../../src/registry/stores.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC;AAMxC,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAErE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,wBAAgB,UAAU,IAAI,MAAM,EAAE,CAErC;AAED,yGAAyG;AACzG,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWjE"}

package/dist/registry/stores.js

@@ -0,0 +1,30 @@
+import { sanitizeForTransport } from '../security/serialization.js';
+// Persist on a global so registrations survive HMR re-evaluation (see adapters.ts / feedback #7).
+const globalStore = globalThis;
+const stores = (globalStore.__reticleStores ??= new Map());
+/** App calls this once per store: registerStore('workspace', () => useWorkspace.getState()). */
+export function registerStore(name, getter) {
+    stores.set(name, getter);
+}
+export function unregisterStore(name) {
+    stores.delete(name);
+}
+export function storeNames() {
+    return [...stores.keys()];
+}
+/** Read one store (by name) or all of them. Each getter is isolated: a throw becomes an error string. */
+export function readStores(only) {
+    const out = {};
+    for (const [name, getter] of stores) {
+        if (only !== undefined && name !== only)
+            continue;
+        try {
+            out[name] = sanitizeForTransport(getter());
+        }
+        catch (error) {
+            out[name] = { __error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=stores.js.map

package/dist/registry/stores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.js","sourceRoot":"","sources":["../../src/registry/stores.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAKpE,kGAAkG;AAClG,MAAM,WAAW,GAAG,UAAuE,CAAC;AAC5F,MAAM,MAAM,GAA6B,CAAC,WAAW,CAAC,eAAe,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC;AAErF,gGAAgG;AAChG,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,MAAmB;IAC7D,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;AAC5B,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACpC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI;YAAE,SAAS;QAClD,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,GAAG,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAClF,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/reticle-presenter-helpers.d.ts

@@ -0,0 +1,19 @@
+import { PresenterMode } from '@reticlehq/core';
+/** Coerce an unknown arg to a string, falling back to `fallback` (default empty) when it isn't one. */
+export declare function str(value: unknown, fallback?: string): string;
+/** A short human label for a ref ("button \"Save\"") for the presenter HUD. */
+export declare function refLabel(refId: string): string;
+/**
+ * Classify a browser command into the presenter intent the human watcher sees. Exhaustive
+ * over the ReticleCommand names that actually reach the browser. CLOCK/NARRATE are control/meta
+ * (neither a page read nor an act) -> IDLE so they don't paint a misleading chip. NARRATE never
+ * reaches #presentBefore anyway (it returns early in #handleCommand) and must not clear the mode.
+ */
+export declare function modeForCommand(commandName: string): PresenterMode;
+/**
+ * Human-legible status for a read command — now WITH the target (which testid/value/ref/store), so
+ * the watcher sees "Finding [testid=row-3700]" instead of a meaningless repeating "Finding an
+ * element". Falls back to the bare verb when no target is in the args.
+ */
+export declare function presentStatus(commandName: string, args?: Record<string, unknown>): string;
+//# sourceMappingURL=reticle-presenter-helpers.d.ts.map

package/dist/reticle-presenter-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reticle-presenter-helpers.d.ts","sourceRoot":"","sources":["../src/reticle-presenter-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIhE,uGAAuG;AACvG,wBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,MAAM,CAEzD;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK9C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAgBjE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAyB7F"}

package/dist/reticle-presenter-helpers.js

@@ -0,0 +1,81 @@
+import { ReticleCommand, PresenterMode } from '@reticlehq/core';
+import { refs } from './dom/refs.js';
+import { describe } from './dom/a11y.js';
+/** Coerce an unknown arg to a string, falling back to `fallback` (default empty) when it isn't one. */
+export function str(value, fallback = '') {
+    return typeof value === 'string' ? value : fallback;
+}
+/** A short human label for a ref ("button \"Save\"") for the presenter HUD. */
+export function refLabel(refId) {
+    const el = refs.resolve(refId);
+    if (!(el instanceof Element))
+        return refId;
+    const d = describe(el);
+    return d.name.length > 0 ? `${d.role} "${d.name}"` : `${d.role} (${refId})`;
+}
+/**
+ * Classify a browser command into the presenter intent the human watcher sees. Exhaustive
+ * over the ReticleCommand names that actually reach the browser. CLOCK/NARRATE are control/meta
+ * (neither a page read nor an act) -> IDLE so they don't paint a misleading chip. NARRATE never
+ * reaches #presentBefore anyway (it returns early in #handleCommand) and must not clear the mode.
+ */
+export function modeForCommand(commandName) {
+    switch (commandName) {
+        case ReticleCommand.ACT:
+        case ReticleCommand.ACT_SEQUENCE:
+            return PresenterMode.ACTING;
+        case ReticleCommand.SNAPSHOT:
+        case ReticleCommand.QUERY:
+        case ReticleCommand.MATCH:
+        case ReticleCommand.INSPECT:
+        case ReticleCommand.ANIMATIONS:
+        case ReticleCommand.STATE_READ:
+        case ReticleCommand.CAPABILITIES:
+            return PresenterMode.READING;
+        default:
+            return PresenterMode.IDLE;
+    }
+}
+/**
+ * Human-legible status for a read command — now WITH the target (which testid/value/ref/store), so
+ * the watcher sees "Finding [testid=row-3700]" instead of a meaningless repeating "Finding an
+ * element". Falls back to the bare verb when no target is in the args.
+ */
+export function presentStatus(commandName, args = {}) {
+    switch (commandName) {
+        case ReticleCommand.SNAPSHOT:
+            return 'Looking at the page';
+        case ReticleCommand.QUERY:
+        case ReticleCommand.MATCH: {
+            const q = commandName === ReticleCommand.MATCH ? (args['query'] ?? {}) : args;
+            const target = queryTarget(q);
+            return target !== undefined ? `Finding ${target}` : 'Finding an element';
+        }
+        case ReticleCommand.INSPECT: {
+            const ref = str(args['ref']);
+            return ref !== undefined ? `Inspecting ${refLabel(ref)}` : 'Inspecting an element';
+        }
+        case ReticleCommand.ANIMATIONS:
+            return 'Reading animations';
+        case ReticleCommand.STATE_READ: {
+            const store = str(args['store']);
+            return store !== undefined ? `Reading state: ${store}` : 'Reading state';
+        }
+        case ReticleCommand.CAPABILITIES:
+            return 'Reading capabilities';
+        default:
+            return commandName;
+    }
+}
+/** Compact "what we're looking for" from a query's args (testid/value/name/role/text/label). */
+function queryTarget(q) {
+    const testid = str(q['testid']) ?? (str(q['by']) === 'testid' ? str(q['value']) : undefined);
+    if (testid !== undefined)
+        return `[testid=${testid}]`;
+    const name = str(q['name']);
+    const value = str(q['value']) ?? str(q['text']) ?? str(q['label']) ?? str(q['role']);
+    if (value !== undefined)
+        return name !== undefined ? `"${value}" (${name})` : `"${value}"`;
+    return name !== undefined ? `"${name}"` : undefined;
+}
+//# sourceMappingURL=reticle-presenter-helpers.js.map

package/dist/reticle-presenter-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reticle-presenter-helpers.js","sourceRoot":"","sources":["../src/reticle-presenter-helpers.ts"],"names":[],"mappings":"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"}

package/dist/reticle.d.ts

@@ -0,0 +1,113 @@
+import { RETICLE_URL_PARAM } from '@reticlehq/core';
+import { type CapabilitiesInput } from './registry/capabilities.js';
+export interface ReticleConnectOptions {
+    /** WS endpoint of the local bridge. Defaults to ws://localhost:<port><path>. */
+    url?: string;
+    /** Human-friendly session label so the agent can target the right tab. */
+    session?: string;
+    /**
+     * Stable project identity, normally stamped by the build plugin (e.g. "acme-web-9f3c1d"). Lets the
+     * agent scope to the right app even when its dev server boots on an unexpected port. Optional.
+     */
+    projectId?: string;
+    /** Browser/bridge pairing token. Required when either endpoint is non-localhost. */
+    token?: string;
+    /** Explicitly allow Reticle on a non-localhost page or bridge. Requires token. */
+    allowNonLocalhost?: boolean;
+    /**
+     * Escape hatch for the production backstop. Reticle is dev-only and refuses to connect when the
+     * build reports NODE_ENV=production (an SSR healthcheck or a prod bundle opened locally would
+     * otherwise activate). The real fix is to gate the import behind `import.meta.env.DEV` so it's
+     * tree-shaken out; this flag only exists for the rare intentional prod diagnostic.
+     */
+    allowInProduction?: boolean;
+    /** Show a small in-page status chip (connection + event count). */
+    overlay?: boolean;
+    /** Presenter mode: glow border, animated cursor, click/hover effects, narration HUD. */
+    present?: boolean;
+    /** Per-action pacing (ms) in presenter mode so a human can follow. Default 450. */
+    pace?: number;
+    /** Min ms each narration line stays visible before the next replaces it (presenter). Default 3000. */
+    narrationDwellMs?: number;
+    /**
+     * Border behavior in presenter mode: 'session' (default) persists the border for the whole
+     * session; 'busy' restores the fade-after-idle behavior.
+     */
+    border?: 'session' | 'busy';
+    /** Max accumulated activity-log rows before the oldest are pruned (presenter). Default 50. */
+    logMax?: number;
+    /**
+     * Mount the floating human-recorder toolbar (Record/Stop/Annotate).
+     * Default off — purely additive, dev-only.
+     */
+    recorder?: boolean;
+    /**
+     * Mount the "Flag a bug" annotator: the human clicks an element that looks wrong, types what's
+     * wrong, and Reticle emits a HUMAN_MARK the agent drains via reticle_review. Defaults to ON with the
+     * presenter (it's the human's side of the look→act→assert loop); pass `annotate: false` to suppress.
+     */
+    annotate?: boolean;
+    /** Live-control: overridable ended-border fade delay (native timer). Default 4000. */
+    endedFadeMs?: number;
+    /** Session auto-end after this much agent idle (presenter). Default 5min; agent-tunable via reticle_session. */
+    idleEndMs?: number;
+}
+/**
+ * Runtime backstop for the dev-only SDK: block connecting when the build reports production, unless
+ * explicitly overridden. Pure so it's testable; connect() reads NODE_ENV safely (process may be absent
+ * in a raw browser). This is defense-in-depth — the primary guard is the consumer gating the import
+ * behind `import.meta.env.DEV` so the SDK is dead-code-eliminated from prod bundles entirely.
+ */
+export declare function shouldBlockProduction(nodeEnv: string | undefined, allowInProduction: boolean): boolean;
+export declare function connectionPolicy(pageHostname: string, bridgeUrl: string, allowNonLocalhost: boolean, token: string | undefined): {
+    allowed: boolean;
+    reason?: string;
+};
+/**
+ * Resolve the session label. An absent label or the `auto` sentinel yields a fresh per-tab id (via
+ * the injected generator) so multi-tab / new-tab routes never collide; any other label is used
+ * verbatim so tabs can intentionally share a session. `gen` is injected to keep this clock-free.
+ */
+export declare function resolveSessionLabel(option: string | undefined, gen: () => string): string;
+export { RETICLE_URL_PARAM };
+/**
+ * Extract Reticle identity overrides from a `location.search` string. Pure (takes the string, not the
+ * window) so it's testable without a DOM. Explicit connect() options still win over these.
+ */
+export declare function reticleParamsFromSearch(search: string): {
+    session?: string;
+    projectId?: string;
+};
+/**
+ * Resolve the session + project identity for a connection: an explicit, non-`auto` option wins;
+ * otherwise a launcher-stamped URL param is used; otherwise undefined (caller generates a per-tab id).
+ * Crucially `auto` is treated like "unset" so an app that passes the auto sentinel still lets a pooled
+ * launcher correlate the lease via __reticle_session. Pure for testability.
+ */
+export declare function resolveConnectIdentity(options: {
+    session?: string;
+    projectId?: string;
+}, search: string): {
+    session: string | undefined;
+    projectId: string | undefined;
+};
+/**
+ * The browser-side orchestrator. Wires observers -> events -> bridge, and bridge
+ * commands -> handlers. Embedded in the host app (dev only).
+ */
+export declare class Reticle {
+    #private;
+    connect(options?: ReticleConnectOptions): void;
+    /** Whether the in-page SDK is connected to the bridge (read by createReticleEmitter, P5a). */
+    get connected(): boolean;
+    /** Surface an arbitrary app-domain observation the DOM can't express (plan/03 §7). */
+    signal(name: string, data?: Record<string, unknown>): void;
+    /** Report a framework/store state change the agent can observe and assert on. */
+    state(name: string, value: unknown): void;
+    /** Advertise the app's testable surface so the agent learns it without reading source. */
+    describe(input: CapabilitiesInput): void;
+    /** Live-control: end the session programmatically from the host app (drives the panel to ended). */
+    endSession(): void;
+    disconnect(): void;
+}
+//# sourceMappingURL=reticle.d.ts.map

package/dist/reticle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reticle.d.ts","sourceRoot":"","sources":["../src/reticle.ts"],"names":[],"mappings":"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"}