@reticlehq/browser 2.13.1 → 3.1.0

package/dist/dom/source.d.ts

@@ -1,53 +0,0 @@
-/**
- * Where an element is defined in the codebase.
- *
- * This is the single most valuable thing Reticle can hand an agent that has to fix what Reticle just
- * found. Locating the right FILE is what turns a report into an edit; without it the agent pays for a
- * search loop that the instrumentation already knows the answer to.
- *
- * Two lookups, because the callers have very different cost budgets:
- *
- *   sourceFromDom  — reads the babel-stamped `data-reticle-source` off the nearest ancestor. One
- *                    native upward walk, bounded by tree depth. Safe to call per element on paths
- *                    that describe many elements at once (query results, snapshots).
- *   sourceFor      — prefers a framework adapter's answer (which knows the component that RENDERED
- *                    the element, not just the nearest stamped host) and falls back to the DOM. The
- *                    adapter path walks the fiber tree, so this belongs on single-element paths
- *                    (inspect, act, review) and not in a loop.
- *
- * Both report source independently of how the element is ANCHORED. Anchor answers "how do I find this
- * again", source answers "where is it written" — collapsing the two once meant that adding a
- * data-testid, which Reticle's own docs recommend, silently removed the source pointer.
- */
-export interface SourceLocation {
-    file: string;
-    line: number;
-}
-/** Parse a `data-reticle-source="file:line:column"` value into `{ file, line }` (column dropped). */
-export declare function parseSourceAttr(value: string | null): SourceLocation | undefined;
-/** The nearest babel-stamped source at or above this element. Cheap enough to call in bulk. */
-export declare function sourceFromDom(el: Element): SourceLocation | undefined;
-/** Best source for the element: the framework adapter's, else the nearest babel-stamped attribute. */
-export declare function sourceFor(el: Element, adapterSource: SourceLocation | undefined): SourceLocation | undefined;
-/**
- * Does ANY element in this document carry a source stamp?
- *
- * The difference between "this element has no stamp" and "the stamping loader is not running at
- * all" — two answers that look identical from a single missing `source` field, and that call for
- * completely different next actions. The first is ordinary: not every element sits under a stamped
- * host. The second means "fix at file:line", the single most-cited reason to reach for Reticle over
- * a generic DOM tool, is silently unavailable for the whole session — and it has been discovered by
- * reading the adapter's source rather than from anything Reticle said.
- *
- * One `querySelector`, which stops at the first hit, so this is cheap enough to answer on a
- * single-element path like inspect. It is only consulted when a source is already missing.
- */
-export declare function documentHasSourceStamps(doc: Document): boolean;
-/**
- * `file:line` — the form an agent can act on directly.
- *
- * Deliberately a single compact string rather than an object: it costs a couple of dozen bytes on a
- * descriptor that may repeat hundreds of times in one response, and every consumer of it is either
- * opening an editor or printing it.
- */
-export declare function formatSource(source: SourceLocation | undefined): string | undefined;

package/dist/dom/source.js

@@ -1,74 +0,0 @@
-/**
- * Where an element is defined in the codebase.
- *
- * This is the single most valuable thing Reticle can hand an agent that has to fix what Reticle just
- * found. Locating the right FILE is what turns a report into an edit; without it the agent pays for a
- * search loop that the instrumentation already knows the answer to.
- *
- * Two lookups, because the callers have very different cost budgets:
- *
- *   sourceFromDom  — reads the babel-stamped `data-reticle-source` off the nearest ancestor. One
- *                    native upward walk, bounded by tree depth. Safe to call per element on paths
- *                    that describe many elements at once (query results, snapshots).
- *   sourceFor      — prefers a framework adapter's answer (which knows the component that RENDERED
- *                    the element, not just the nearest stamped host) and falls back to the DOM. The
- *                    adapter path walks the fiber tree, so this belongs on single-element paths
- *                    (inspect, act, review) and not in a loop.
- *
- * Both report source independently of how the element is ANCHORED. Anchor answers "how do I find this
- * again", source answers "where is it written" — collapsing the two once meant that adding a
- * data-testid, which Reticle's own docs recommend, silently removed the source pointer.
- */
-import { DATA_RETICLE_SOURCE_ATTR } from '@reticlehq/core';
-/** Stamped by @reticlehq/babel-plugin / @reticlehq/vite-plugin in dev as `file:line:column`. */
-const SOURCE_ATTR = DATA_RETICLE_SOURCE_ATTR;
-/** Parse a `data-reticle-source="file:line:column"` value into `{ file, line }` (column dropped). */
-export function parseSourceAttr(value) {
-    if (null === value)
-        return undefined;
-    const m = /^(.*):(\d+):(\d+)$/.exec(value);
-    if (null === m)
-        return undefined;
-    const file = m[1];
-    const line = Number(m[2]);
-    if (file === undefined || 0 === file.length || !Number.isFinite(line))
-        return undefined;
-    return { file, line };
-}
-/** The nearest babel-stamped source at or above this element. Cheap enough to call in bulk. */
-export function sourceFromDom(el) {
-    const host = el.closest(`[${SOURCE_ATTR}]`);
-    return host !== null ? parseSourceAttr(host.getAttribute(SOURCE_ATTR)) : undefined;
-}
-/** Best source for the element: the framework adapter's, else the nearest babel-stamped attribute. */
-export function sourceFor(el, adapterSource) {
-    if (adapterSource !== undefined)
-        return { file: adapterSource.file, line: adapterSource.line };
-    return sourceFromDom(el);
-}
-/**
- * Does ANY element in this document carry a source stamp?
- *
- * The difference between "this element has no stamp" and "the stamping loader is not running at
- * all" — two answers that look identical from a single missing `source` field, and that call for
- * completely different next actions. The first is ordinary: not every element sits under a stamped
- * host. The second means "fix at file:line", the single most-cited reason to reach for Reticle over
- * a generic DOM tool, is silently unavailable for the whole session — and it has been discovered by
- * reading the adapter's source rather than from anything Reticle said.
- *
- * One `querySelector`, which stops at the first hit, so this is cheap enough to answer on a
- * single-element path like inspect. It is only consulted when a source is already missing.
- */
-export function documentHasSourceStamps(doc) {
-    return doc.querySelector(`[${SOURCE_ATTR}]`) !== null;
-}
-/**
- * `file:line` — the form an agent can act on directly.
- *
- * Deliberately a single compact string rather than an object: it costs a couple of dozen bytes on a
- * descriptor that may repeat hundreds of times in one response, and every consumer of it is either
- * opening an editor or printing it.
- */
-export function formatSource(source) {
-    return source === undefined ? undefined : `${source.file}:${String(source.line)}`;
-}

package/dist/observers/network-body.d.ts

@@ -1,35 +0,0 @@
-/**
- * Is this response body still arriving after the request itself resolved?
- *
- * STRUCTURAL, not a content-type allowlist. The first version listed `x-component|x-ndjson|
- * application/stream` — which is to say "Next.js RSC, plus two guesses". It closed the exact defect
- * it was written against and left every other streamed response as invisible as before: a chunked
- * `application/json` from a token API, a streamed HTML document, an export assembled server-side.
- * Fixing one app's symptom and calling the class solved is how a false green comes back wearing
- * different clothes.
- *
- * The real signal is on the wire: a response with a BODY and no `content-length` is being sent
- * chunked, which is the definition of "the server is still writing". `content-length` present means
- * the size was known up front and the body cannot grow.
- *
- * Deliberately independent of content type, with one exception above for streams that never end.
- */
-export declare function isStreamingBody(contentType: string | null, contentLength: string | null): boolean;
-/**
- * Resolve with the body text, or `undefined` if it takes too long.
- *
- * The app is already awaiting our patched fetch, so any unbounded read here is a hang in the host app.
- * Losing an observation is always preferable to freezing the page being observed.
- */
-export declare function withBodyDeadline(read: Promise<string>): Promise<string | undefined>;
-export declare function isCapturableType(contentType: string | null): boolean;
-/**
- * Redact + cap a body for the agent transcript. JSON is parsed and run through the same
- * sanitizeForTransport redaction used for state (sensitive keys -> [REDACTED]); every other text body
- * (and JSON that didn't parse) goes through redactText so form/plain-text credentials can't leak.
- * Returns the (possibly truncated) body plus whether it was cut.
- */
-export declare function projectBody(rawText: string, contentType: string | null): {
-    body: string;
-    truncated: boolean;
-};

package/dist/observers/network-body.js

@@ -1,168 +0,0 @@
-/**
- * Response/request BODY projection for the network observer.
- *
- * Split out of network.ts, which had grown to hold URL redaction, body projection, fetch, XHR, SSE,
- * WebSocket and sendBeacon at once. This module owns exactly one question: given a body, what is safe
- * and affordable to report?
- */
-import { REDACTED_VALUE } from '@reticlehq/core';
-import { isSensitiveKey, safeStringify, scrubKnownSecrets } from '../security/serialization.js';
-import { nativeClearTimeout, nativeSetTimeout } from '../timers/native-timers.js';
-/** Only text-like bodies are worth capturing; binary (images/fonts/octet-stream) is skipped. */
-const CAPTURABLE_CONTENT = /application\/json|text\/|application\/xml|x-www-form-urlencoded|graphql/i;
-/**
- * Content types that are STREAMS, never complete bodies.
- *
- * `text/event-stream` matches `text/` in CAPTURABLE_CONTENT, and body capture awaited
- * `res.clone.text` BEFORE returning the response to the app. A clone of a stream only settles when
- * the stream ends — and an SSE stream does not end — so the app's `await fetch...)` never resolved.
- * Enabling body capture silently hung every streaming endpoint (SSE, and the chunked `application/json`
- * every token-streaming model API uses), leaving a permanently loading UI with no reason to suspect the
- * observability SDK. Never read these; the frame observer covers SSE properly.
- */
-const STREAMING_CONTENT = /event-stream|x-ndjson|application\/stream/i;
-/**
- * Content types that stay OPEN by design — watching them would make every first settle pay the full
- * watch bound for a stream doing exactly its job. Real SSE is covered by the EventSource observer.
- */
-const ENDLESS_BY_DESIGN = /event-stream/i;
-/**
- * Is this response body still arriving after the request itself resolved?
- *
- * STRUCTURAL, not a content-type allowlist. The first version listed `x-component|x-ndjson|
- * application/stream` — which is to say "Next.js RSC, plus two guesses". It closed the exact defect
- * it was written against and left every other streamed response as invisible as before: a chunked
- * `application/json` from a token API, a streamed HTML document, an export assembled server-side.
- * Fixing one app's symptom and calling the class solved is how a false green comes back wearing
- * different clothes.
- *
- * The real signal is on the wire: a response with a BODY and no `content-length` is being sent
- * chunked, which is the definition of "the server is still writing". `content-length` present means
- * the size was known up front and the body cannot grow.
- *
- * Deliberately independent of content type, with one exception above for streams that never end.
- */
-export function isStreamingBody(contentType, contentLength) {
-    if (contentType !== null && ENDLESS_BY_DESIGN.test(contentType))
-        return false;
-    return null === contentLength;
-}
-/**
- * Longest the SDK will wait on a response-body clone before emitting without it.
- *
- * Two layers protect the app. `text/event-stream` and friends are skipped outright, which covers the
- * common streaming case at zero cost. This deadline is the backstop for a body that streams WITHOUT
- * announcing it in its content type — chunked `application/json` from a token-streaming API. Gating on
- * `content-length` instead was tried and rejected: plenty of complete responses omit it (gzip, HTTP/2),
- * so that would silently stop capturing bodies for ordinary apps. A bounded half-second on a rare path
- * beats an unbounded hang, and beats losing capture everywhere.
- */
-const BODY_READ_TIMEOUT_MS = 500;
-/**
- * Resolve with the body text, or `undefined` if it takes too long.
- *
- * The app is already awaiting our patched fetch, so any unbounded read here is a hang in the host app.
- * Losing an observation is always preferable to freezing the page being observed.
- */
-export async function withBodyDeadline(read) {
-    // The timer is CLEARED on the winning path. Left uncleared, every captured body leaves a live timer
-    // and a retained closure behind — harmless individually, but `boundedFrame` in this same package
-    // already races-with-cleanup correctly, so not reusing that shape was an oversight rather than a
-    // choice. It also keeps test workers from being held open by pending handles.
-    let timer;
-    try {
-        return await Promise.race([
-            read,
-            new Promise((resolve) => {
-                timer = nativeSetTimeout(() => resolve(undefined), BODY_READ_TIMEOUT_MS);
-            }),
-        ]);
-    }
-    finally {
-        if (timer !== undefined)
-            nativeClearTimeout(timer);
-    }
-}
-export function isCapturableType(contentType) {
-    if (null === contentType)
-        return false;
-    if (STREAMING_CONTENT.test(contentType))
-        return false;
-    return CAPTURABLE_CONTENT.test(contentType);
-}
-/**
- * Per-body character cap. Bodies ride the same ring buffer as the DOM/route/console timeline, so an
- * uncapped body could evict the whole behavioral history; the small cap keeps a few large responses
- * from starving the timeline (the separate-budget concern in the scalability audit).
- */
-const MAX_BODY_CHARS = 8192;
-/**
- * Hard bound on how much of a body is ever PARSED or SCANNED, independent of how much is reported.
- *
- * Only twice the output cap, and that ceiling is measured rather than guessed. The redaction pass uses
- * `[A-Za-z0-9_.-]+` followed by a delimiter, which backtracks quadratically on a long run without one.
- * Timed on this machine: 8 KB → 36 ms, 16 KB → 136 ms, 64 KB → 2067 ms. A first attempt at 8× the
- * output cap therefore still froze the main thread for seconds, so the bound is set where the cost
- * stays bounded AND redaction keeps enough context to catch a secret straddling the reported edge.
- * Scanning far past the output cap is wasted work in any case — only 8 KB is ever reported.
- */
-const MAX_BODY_SCAN_CHARS = MAX_BODY_CHARS * 2;
-/**
- * An `Authorization: Bearer …` / `Basic …` credential. The token side requires credential shape — 16+
- * chars AND at least one digit or symbol — so ordinary prose ("Basic subscription includes…", "Bearer
- * capacity exceeded") is NOT mangled, only actual opaque tokens are.
- */
-const AUTH_SCHEME_TOKEN = /\b(Bearer|Basic)\s+(?=[A-Za-z0-9._~+/=-]{16,})(?=[A-Za-z0-9._~+/=-]*[\d._~+/=-])[A-Za-z0-9._~+/=-]+/gi;
-/**
- * Redact credentials in ANY text body (form-urlencoded, text/plain, xml, or JSON that failed to parse).
- * sanitizeForTransport only redacts KEYS inside a parsed object, so a `password=secret` form post or a
- * `Bearer <token>` string would otherwise ship verbatim. Redacts the value of any `key=value` / `key: value`
- * pair whose key is sensitive, plus credential-shaped auth-scheme tokens.
- */
-function redactText(text) {
-    return (text
-        // Auth-scheme tokens FIRST: `Authorization: Bearer <token>` — the key/value rule below would
-        // otherwise consume just "Bearer" as Authorization's value (it stops at whitespace) and leave the
-        // token behind, so the scheme rule must run before it.
-        .replace(AUTH_SCHEME_TOKEN, (_m, scheme) => `${scheme} ${REDACTED_VALUE}`)
-        .replace(/([A-Za-z0-9_.-]+)(\s*[=:]\s*"?)([^&\s,;"}]+)/g, (match, key, sep) => isSensitiveKey(key) ? `${key}${sep}${REDACTED_VALUE}` : match));
-}
-/**
- * Redact + cap a body for the agent transcript. JSON is parsed and run through the same
- * sanitizeForTransport redaction used for state (sensitive keys -> [REDACTED]); every other text body
- * (and JSON that didn't parse) goes through redactText so form/plain-text credentials can't leak.
- * Returns the (possibly truncated) body plus whether it was cut.
- */
-export function projectBody(rawText, contentType) {
-    // Bound the INPUT before any parsing or scanning. The cap used to be applied only at the end, so a
-    // large body was JSON.parsed in full, deep-walked, re-stringified, and swept by two global regexes
-    // before all but 8 KB of the result was thrown away — seconds of synchronous main-thread work for a
-    // fixed-size output. A 30 MB CSV export or a big HTML error page froze the app, which is the same
-    // class of host-app damage as the streaming hang, with the SDK still the cause.
-    //
-    // The slice is generous (a multiple of the output cap) so redaction still sees enough context to
-    // recognise a secret that straddles the boundary, while the work stays bounded regardless of body size.
-    const oversized = rawText.length > MAX_BODY_SCAN_CHARS;
-    const text = oversized ? rawText.slice(0, MAX_BODY_SCAN_CHARS) : rawText;
-    let out;
-    if (contentType !== null && /json|graphql/i.test(contentType)) {
-        try {
-            // safeStringify already sanitizes internally — the extra sanitizeForTransport here re-walked
-            // every captured JSON body a second time (~21% of the per-response cost) for an identical result.
-            out = safeStringify(JSON.parse(text));
-        }
-        catch {
-            out = redactText(text); // looked like JSON but wasn't — still redact key/value + auth tokens
-        }
-    }
-    else {
-        out = redactText(text);
-    }
-    // Key-based redaction can't see a secret sitting in a VALUE under a benign key — scan the projected
-    // text for high-confidence secret shapes (JWTs, provider keys) as a backstop, JSON or not.
-    out = scrubKnownSecrets(out);
-    // Truncated if the projection overflows the cap OR the input itself was clipped above — a body the
-    // SDK never fully read must not be reported as complete.
-    const truncated = oversized || out.length > MAX_BODY_CHARS;
-    return { body: out.length > MAX_BODY_CHARS ? out.slice(0, MAX_BODY_CHARS) : out, truncated };
-}

package/dist/observers/network-redact.d.ts

@@ -1,20 +0,0 @@
-/**
- * Redact credential-bearing values so they don't leak into the agent transcript / flow / run
- * artifacts: query params (`?access_token=…`, signed-URL keys) via the shared `isSensitiveKey` regex,
- * AND path-embedded tokens (`/reset/<token>`, `/invite/<token>`) that live in the path, not the query.
- * The hash is preserved and the URL is returned byte-for-byte when nothing matched.
- */
-export declare function redactUrl(raw: string): string;
-/**
- * Displayed URL plus, when redaction rewrote it, the raw request for graders.
- *
- * `url` is what the agent reads. `urlRaw` exists only so `urlContains` can still match a public
- * path segment that the heuristic rewrote (`/auth/token/refresh-context`). Omitted when nothing
- * changed, so an ordinary request pays nothing.
- */
-export declare function netUrlFields(raw: string): {
-    url: string;
-} | {
-    url: string;
-    urlRaw: string;
-};

package/dist/observers/network-redact.js

@@ -1,80 +0,0 @@
-import { REDACTED_VALUE, URL_RAW } from '@reticlehq/core';
-import { isSensitiveKey } from '../security/serialization.js';
-/** A path segment name that is typically followed by a single-use secret token in the NEXT segment. */
-const SENSITIVE_PATH_SEGMENT = /^(reset|verify|verification|confirm|activate|invite|magic|magiclink|token|key|oauth|unsubscribe|password)$/i;
-/** Only mask a following segment that looks token-like — short ids/words (`reset/form`) are left alone. */
-const PATH_TOKEN_MIN_LENGTH = 12;
-/**
- * Redact credential-bearing values so they don't leak into the agent transcript / flow / run
- * artifacts: query params (`?access_token=…`, signed-URL keys) via the shared `isSensitiveKey` regex,
- * AND path-embedded tokens (`/reset/<token>`, `/invite/<token>`) that live in the path, not the query.
- * The hash is preserved and the URL is returned byte-for-byte when nothing matched.
- */
-export function redactUrl(raw) {
-    const hashStart = raw.indexOf('#');
-    const hash = -1 === hashStart ? '' : raw.slice(hashStart);
-    const beforeHash = -1 === hashStart ? raw : raw.slice(0, hashStart);
-    const queryStart = beforeHash.indexOf('?');
-    const pathPart = -1 === queryStart ? beforeHash : beforeHash.slice(0, queryStart);
-    const query = -1 === queryStart ? '' : beforeHash.slice(queryStart + 1);
-    let changed = false;
-    // Credentials in the authority (`scheme://user:pass@host`) never belong in a transcript.
-    // Match to the LAST `@` before the path (`[^/]*@`, greedy), not the first — a password containing
-    // `@` (`user:p@ss@host`) otherwise left its tail (`ss@host`) in the clear.
-    let authority = pathPart;
-    const userinfo = /^([a-z][a-z0-9+.-]*:\/\/)[^/]*@/i.exec(pathPart);
-    if (userinfo !== null) {
-        authority = `${userinfo[1] ?? ''}${REDACTED_VALUE}@${pathPart.slice(userinfo[0].length)}`;
-        changed = true;
-    }
-    let newQuery = query;
-    if (query !== '') {
-        const params = new URLSearchParams(query);
-        let queryChanged = false;
-        for (const key of [...params.keys()]) {
-            if (isSensitiveKey(key)) {
-                params.set(key, REDACTED_VALUE);
-                queryChanged = true;
-            }
-        }
-        if (queryChanged) {
-            newQuery = params.toString();
-            changed = true;
-        }
-    }
-    const segments = authority.split('/');
-    for (let i = 0; i + 1 < segments.length; i++) {
-        const name = segments[i];
-        const next = segments[i + 1];
-        if (name !== undefined &&
-            next !== undefined &&
-            next.length >= PATH_TOKEN_MIN_LENGTH &&
-            SENSITIVE_PATH_SEGMENT.test(name)) {
-            segments[i + 1] = REDACTED_VALUE;
-            changed = true;
-        }
-    }
-    // OAuth implicit flow puts the access_token in the FRAGMENT (`#access_token=…`), and hash-routers carry
-    // `?token=…` in the hash — redact sensitive params there too, leaving plain anchors (`#section`) alone.
-    let newHash = hash;
-    if (hash.length > 1) {
-        newHash = hash.replace(/([A-Za-z0-9_.-]+)=([^&\s]+)/g, (m, key) => isSensitiveKey(key) ? `${key}=${REDACTED_VALUE}` : m);
-        if (newHash !== hash)
-            changed = true;
-    }
-    if (!changed)
-        return raw;
-    const queryOut = -1 === queryStart ? '' : `?${newQuery}`;
-    return `${segments.join('/')}${queryOut}${newHash}`;
-}
-/**
- * Displayed URL plus, when redaction rewrote it, the raw request for graders.
- *
- * `url` is what the agent reads. `urlRaw` exists only so `urlContains` can still match a public
- * path segment that the heuristic rewrote (`/auth/token/refresh-context`). Omitted when nothing
- * changed, so an ordinary request pays nothing.
- */
-export function netUrlFields(raw) {
-    const url = redactUrl(raw);
-    return url === raw ? { url } : { url, [URL_RAW]: raw };
-}

package/dist/presenter/presenter-brand.d.ts

@@ -1,22 +0,0 @@
-/**
- * The artwork constants are annotated `: string` deliberately.
- *
- * Without the annotation TypeScript infers a literal type, and every one of these SVG and HTML
- * strings is copied verbatim into the emitted `.d.ts` as its own type. That duplicated the artwork
- * into the published package twice over: this file's declarations alone were 16KB of a 900KB
- * budget, carrying type information nobody can use - no caller cares about the literal type of a
- * `<path d=...>`.
- */
-/**
- * Brand marks, inlined. The SDK is bundled into someone else's page: it cannot read
- * `assets/logo/*.svg` from disk at runtime and must never fetch from our own domain, so the mark
- * lives here as a string (same precedent as SEND_ICON in presenter-controls.ts).
- * Minified - editor metadata, clip paths, masks and sub-0.01 precision stripped - and painted
- * with `currentColor` so the mark tracks --reticle-fg instead of hardcoding the export's #FAFAFA.
- */
-/** Accessible name of the HUD. */
-export declare const BRAND_NAME = "Reticle";
-/** Mark alone (shown in the FAB and compact toolbar). */
-export declare const MARK_SVG: string;
-/** Collapsed FAB control - Reticle mark only. */
-export declare const FAB_TOGGLE_HTML: string;

package/dist/presenter/presenter-effects.d.ts

@@ -1,13 +0,0 @@
-/**
- * Synthetic-cursor + click effects - the visible "the agent is acting here" motion. Pure DOM helpers
- * extracted from presenter.ts so the controller stays under the size cap; each is a no-op when its
- * element is absent (the panel may not be mounted). Behavior is unchanged from the inlined methods.
- */
-/** Fly the synthetic cursor to a viewport point and show it. */
-export declare function moveCursor(cursor: HTMLElement | undefined, x: number, y: number): void;
-/** Briefly draw the green focus ring around an element's box, then fade it. */
-export declare function ringAround(ring: HTMLElement | undefined, rect: DOMRect): void;
-/** Spawn a one-shot click ripple at a viewport point (self-removing). */
-export declare function spawnRipple(root: HTMLElement | undefined, x: number, y: number): void;
-/** Pace for the human so an action is watchable, not instant. */
-export declare function pace(ms: number): Promise<void>;

package/dist/presenter/presenter-hud-chrome.d.ts

@@ -1,17 +0,0 @@
-/** Shared polished-black surfaces used across HUD chrome panels. */
-export declare const HUD_SURFACE_CLASS = "reticle-hud-surface";
-/** Layered near-black base — no embedded image assets. */
-export declare const HUD_SURFACE_FILL: string;
-export declare const HUD_SURFACE_PAINT: string;
-export declare const HUD_DROP_SHADOW: string;
-export declare const HUD_CHROME_CSS: string;
-/** Inset well for the activity log — sits inside the chat card. */
-export declare const HUD_LOG_WELL_CLASS = "reticle-hud-log-well";
-/**
- * The activity feed sits ON the panel, not in a black box cut out of it.
- *
- * The inset well was a second surface inside a surface - two borders, two backgrounds - and it made
- * the panel read as a container rather than as one card. It also grew and shrank with its content,
- * so the panel resized on every row; the height is fixed now and the feed scrolls inside it.
- */
-export declare const HUD_LOG_WELL_CSS: string;

package/dist/presenter/presenter-log.d.ts

@@ -1,64 +0,0 @@
-import { PresenterMode } from '@reticlehq/core';
-/** Activity-log entry kinds (presenter-only UI; never a wire string). */
-export declare const LOG_KIND: {
-    readonly READ: "read";
-    readonly ACT: "act";
-    readonly NARRATION: "narration";
-    readonly HUMAN: "human";
-};
-export type LogKind = (typeof LOG_KIND)[keyof typeof LOG_KIND];
-/** Act-row outcome glyph keys (presenter-only UI). */
-export declare const LOG_RESULT: {
-    readonly PASS: "pass";
-    readonly FAIL: "fail";
-};
-export type LogResult = (typeof LOG_RESULT)[keyof typeof LOG_RESULT];
-/** HUD chip copy keyed by presenter mode (UI text, browser-local - not a wire string). */
-export declare const CHIP_LABEL: Record<PresenterMode, string>;
-export declare const DATA_RETICLE_LOG = "data-reticle-log";
-/**
- * The attribute on ONE log line's timestamp. Deliberately not `data-reticle-log-ts`: that name is
- * the overlay-level SETTING (show timestamps y/n) and the overlay root carries it, so a bare
- * `[data-reticle-log-ts]{opacity:.85}` here matched the overlay itself and made the entire HUD -
- * chat panel included - 85% transparent, with the page legible straight through it.
- */
-export declare const LOG_TIME_ATTR = "data-reticle-log-time";
-/** CSS for the log feed (injected with the rest of the presenter stylesheet; vars inherit from the card). */
-export declare const LOG_CSS: string;
-/**
- * Pin the feed to its newest row.
- *
- * Called on append AND when the chat is opened, because a hidden panel has no layout: rows added
- * while it was minimised could not scroll it, so opening it showed the OLDEST row and the latest
- * activity - the reason to open it - was somewhere below the fold.
- */
-export declare function scrollLogToLatest(container: HTMLElement): void;
-/**
- * Pin the feed to its newest row once the panel has actually laid out.
- *
- * A single frame is not enough on open: the rows carry `content-visibility:auto`, so their real
- * heights arrive after the first paint and `scrollHeight` keeps growing under a scroll that has
- * already happened - the feed landed a third of the way down instead of at the end. Two frames
- * plus one settle pass costs nothing and lands on the last row.
- */
-export declare function settleLogAtLatest(container: HTMLElement): void;
-/** Handle returned from logRow/Presenter.log so the caller can stamp the outcome glyph later. */
-export interface LogHandle {
-    result(r: LogResult): void;
-}
-/** Clamp a logMax option to a sane positive integer, falling back to the default. */
-export declare function clampLogMax(n: number | undefined): number;
-/**
- * Pure, human-readable duration ("3s", "47s", "2m", "1h 4m") - no clock read, so it stays
- * deterministic in tests. Used for both the per-row timestamp (time since session start) and the
- * live "idle · {duration} since last action" heartbeat. Sub-second reads as "0s".
- */
-export declare function humanDuration(ms: number): string;
-/** Per-row timestamp: time since the session's first row, human-readable (e.g. "2m", not "+132.4s"). */
-export declare function formatElapsed(ms: number): string;
-/**
- * Build a log row from text (already trimmed) + a +elapsed timestamp, append it to the container,
- * prune to logMax, auto-scroll to newest, and return a handle to stamp the outcome glyph later.
- * Uses createElement/textContent (never innerHTML) so arbitrary narration text can't inject markup.
- */
-export declare function appendLogRow(container: HTMLElement, kind: LogKind, text: string, ts: string, logMax: number): LogHandle;