@cairnvibe/sdk 0.2.13 → 0.4.0

package/dist/cursor-overlay.js

@@ -0,0 +1,126 @@
+"use strict";
+// A visible, animated synthetic cursor that glides to whatever element the
+// agent is about to act on, and genuinely arrives — before anything actually
+// happens on screen — rather than a click just occurring with no visible
+// lead-up. Real, watchable proof of what the agent resolved, the same way
+// watching a person's own mouse move tells you where they're about to click
+// before it happens; matches this SDK's own "verified, not trusted"
+// discipline in a form a user can literally see, not just read.
+//
+// Purely additive and deliberately decoupled from highlightElement
+// (element-ladder.ts) — that function's own scroll+glow behavior is
+// unchanged and still called by every site that used it before. This module
+// only adds the moving cursor itself; a caller awaits moveCursorTo(el)
+// before firing the real action so the cursor is seen arriving first, never
+// after the fact — see verb-executor.ts's own call sites for the exact
+// sequencing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.moveCursorTo = moveCursorTo;
+exports.hideCursor = hideCursor;
+const CURSOR_ID = "cairn-cursor";
+const MOVE_MS = 550;
+const ARRIVE_PAUSE_MS = 160;
+// The CSS side already disables the cursor's transition/animation under
+// prefers-reduced-motion (see #cairn-cursor in the injected <style> block),
+// which makes it jump instead of glide — but without this, the real delay
+// before the action fires would stay the full ~710ms even though there's
+// nothing left to watch. Mirrors the visual change with a real timing one.
+const REDUCED_MOVE_MS = 60;
+const REDUCED_ARRIVE_PAUSE_MS = 40;
+function prefersReducedMotion() {
+    return (typeof window !== "undefined" &&
+        typeof window.matchMedia === "function" &&
+        window.matchMedia("(prefers-reduced-motion: reduce)").matches);
+}
+// Module-scope, not per-call — the whole point is a SINGLE cursor that
+// glides from wherever it last was, the way a real mouse never teleports
+// between two unrelated screen positions.
+let lastX = null;
+let lastY = null;
+function ensureCursorEl() {
+    if (typeof document === "undefined" || !document.body)
+        return null;
+    let el = document.getElementById(CURSOR_ID);
+    if (el)
+        return el;
+    el = document.createElement("div");
+    el.id = CURSOR_ID;
+    el.setAttribute("aria-hidden", "true");
+    // A simple filled pointer shape — matches the widget's own ember accent,
+    // with a thin dark stroke so it reads clearly on light AND dark pages
+    // (the host app's own background is never something this SDK controls).
+    el.innerHTML =
+        '<svg width="22" height="22" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg">' +
+            '<path d="M2 1.5 L2 18.2 L6.3 14.4 L9.1 20.6 L11.7 19.4 L8.9 13.3 L14.6 13.1 Z" fill="#E07A3F" stroke="#1B1815" stroke-width="1.1" stroke-linejoin="round"/>' +
+            "</svg>";
+    el.style.cssText =
+        "position:fixed;left:0;top:0;z-index:2147483001;pointer-events:none;opacity:0;transition:opacity 180ms ease;will-change:transform;filter:drop-shadow(0 3px 6px rgba(0,0,0,0.35));";
+    document.body.appendChild(el);
+    return el;
+}
+/**
+ * Animates the synthetic cursor to `el`'s center and resolves once it has
+ * genuinely arrived (plus a brief real hover pause) — callers await this
+ * BEFORE performing the real action, so the cursor is seen gliding there
+ * first. Deliberately timer-driven (`window.setTimeout`), not
+ * `transitionend`/`Element.animate().finished`-driven — this repo's test
+ * environment is plain Node, not a real browser (see waitForDomSettle's own
+ * doc comment for the same discipline), and a fixed, known duration is what
+ * makes this testable with fake timers instead of needing real animation-
+ * completion events that a headless/no-DOM environment may never fire.
+ *
+ * SSR/no-DOM safe — same defensive guard `waitForDomSettle` already uses —
+ * so a caller never needs its own environment check before calling this.
+ */
+function moveCursorTo(el) {
+    if (typeof document === "undefined" || typeof window === "undefined" || typeof el.getBoundingClientRect !== "function") {
+        return Promise.resolve();
+    }
+    const cursor = ensureCursorEl();
+    if (!cursor)
+        return Promise.resolve();
+    const rect = el.getBoundingClientRect();
+    const x = rect.left + rect.width / 2;
+    const y = rect.top + rect.height / 2;
+    if (lastX === null || lastY === null) {
+        // The very first move of the session starts from the widget's own
+        // corner (bottom-right, where the FAB lives) instead of materializing
+        // at (0,0) — reads as "coming from Cairn," not appearing from nowhere.
+        lastX = window.innerWidth - 40;
+        lastY = window.innerHeight - 40;
+        cursor.style.transform = `translate(${lastX}px, ${lastY}px)`;
+    }
+    const reduced = prefersReducedMotion();
+    const moveMs = reduced ? REDUCED_MOVE_MS : MOVE_MS;
+    const arrivePauseMs = reduced ? REDUCED_ARRIVE_PAUSE_MS : ARRIVE_PAUSE_MS;
+    cursor.style.transition = `transform ${moveMs}ms cubic-bezier(.4,0,.2,1), opacity 180ms ease`;
+    cursor.style.opacity = "1";
+    // Forces a style flush so the browser animates FROM the current position
+    // TO the new one instead of jumping straight there — reading a layout
+    // property is the standard, harmless way to force this without a real
+    // animation API (which, per this function's own doc comment, this
+    // deliberately avoids depending on for its completion signal anyway).
+    void cursor.offsetHeight;
+    cursor.style.transform = `translate(${x}px, ${y}px)`;
+    lastX = x;
+    lastY = y;
+    return new Promise((resolve) => {
+        window.setTimeout(() => {
+            cursor.classList.add("cairn-cursor-hover");
+            window.setTimeout(() => {
+                cursor.classList.remove("cairn-cursor-hover");
+                resolve();
+            }, arrivePauseMs);
+        }, moveMs);
+    });
+}
+/** Fades the synthetic cursor out — called once the widget itself closes or
+ * unmounts, so it doesn't sit visible on screen after the conversation
+ * ends. Safe to call even if the cursor was never created. */
+function hideCursor() {
+    if (typeof document === "undefined")
+        return;
+    const el = document.getElementById(CURSOR_ID);
+    if (el)
+        el.style.opacity = "0";
+}

package/dist/element-ladder.d.ts

@@ -1,4 +1,41 @@
 export declare function findElement(target: string, liveElements?: Map<string, HTMLElement>): HTMLElement | null;
+/**
+ * Phase 3 step 4 (see DEVELOPMENT.md/the plan file) — CODA's own point:
+ * the Executor gets real local retry latitude for a genuinely MECHANICAL
+ * miss (a re-render replaced the DOM node the frozen liveElements snapshot
+ * pointed at; an animation/async render hadn't settled yet) before a
+ * failure escalates all the way to the Critic/a replan. Deliberately NOT
+ * a second LLM call — the Executor stays opinion-free, exactly re-running
+ * the SAME real lookup (which, past the liveElements-map check, already
+ * queries the LIVE DOM directly — a stale snapshot doesn't matter to that
+ * part) after a short real wait. A target that's genuinely not on the
+ * page still fails after `attempts`, surfacing as a real miss — this
+ * never silently invents success.
+ */
+export declare function findElementWithRetry(target: string, liveElements?: Map<string, HTMLElement>, attempts?: number, delayMs?: number): Promise<HTMLElement | null>;
+/**
+ * Real, live-found bug this closes: a `fill`/`click` step reported itself
+ * "done" the instant its DOM event was dispatched — but the app's own
+ * reaction to that event (a filtered search-results grid re-rendering, a
+ * cart count updating) can be an unbounded-latency async round trip (a
+ * Next.js App Router `router.push` re-fetching a server component, for
+ * example — not a fixed debounce with a known delay to just sleep past).
+ * A `read` step immediately after saw STALE content and the agent
+ * confidently reported findings that didn't match what the page actually,
+ * eventually, showed — confirmed live: typing "book" into a search box,
+ * then reading the still-unfiltered product grid a moment later, and
+ * reporting a match ("Novel: The Long Way") the REAL, since-filtered page
+ * went on to show zero results for.
+ *
+ * Waits for real DOM mutations instead of guessing a sleep duration: if
+ * nothing starts mutating within `initialWaitMs`, resolves immediately
+ * (the action had no async effect at all — no reason to add latency to
+ * the common case); once mutations start, waits for `quietMs` of no
+ * further mutations before considering the page settled; a hard
+ * `timeoutMs` ceiling means a page that never stops mutating (an
+ * animation, a polling widget) can't stall the agent loop forever.
+ */
+export declare function waitForDomSettle(initialWaitMs?: number, quietMs?: number, timeoutMs?: number): Promise<void>;
 export declare function highlightElement(el: HTMLElement, glowMs?: number): void;
 /**
  * Sets a real form field's value AND makes the framework that owns it (React,
@@ -15,6 +52,40 @@ export declare function fillElement(el: HTMLElement, value: string): boolean;
  * bounds a live element's label (this is what the agent loop "observes"
  * after a read step, so it needs the same payload/privacy discipline). */
 export declare function readElement(el: HTMLElement): string;
+/**
+ * Chooses a real `<option>` by its visible text — never a raw internal
+ * `value` the model could never actually see. Native `<select>` gets the
+ * direct path (set `.value` to the matching option's own value, then fire
+ * the same input/change pair fillElement uses so React notices). A custom
+ * listbox/combobox (role="listbox"/"option" — Radix, Headless UI, etc.)
+ * has no real `<option>` to set, so the fallback clicks the matching
+ * option-shaped descendant instead, the same "do the real user gesture"
+ * principle the do/click cases already follow.
+ */
+export declare function selectOption(el: HTMLElement, visibleText: string): boolean;
+/**
+ * A real multi-point pointer-event sequence — pointerdown on `from`'s
+ * center, several pointermove steps toward `to`'s center, pointerup on
+ * `to` — the same technique a real mouse drag produces, for canvas/kanban/
+ * sortable-list libraries (react-dnd, dnd-kit, n8n's own node canvas) that
+ * listen for pointer events rather than a single synthetic "drop". Mouse
+ * events are fired alongside (same coordinates) for the older libraries
+ * that still only listen for those. jsdom's getBoundingClientRect returns
+ * all-zero rects with no real layout engine — fine here, since what matters
+ * for a test is that the sequence fires with consistent coordinates, not
+ * that they reflect real pixels.
+ */
+export declare function dragElement(from: HTMLElement, to: HTMLElement, steps?: number): void;
+/**
+ * Presses one real key on a target element — focuses it first (a real
+ * keypress always lands on whatever's focused; a component that reacts to
+ * Escape/Enter/arrows almost always keys off document-level or its own
+ * focus-scoped listener, so focus has to be real before the event fires).
+ * Fires keydown/keyup (and keypress only for the handful of keys that
+ * still expect one — Enter/Tab — matching a real browser's own behavior,
+ * which no longer fires keypress for pure navigation keys like arrows).
+ */
+export declare function pressKey(el: HTMLElement, key: string): void;
 export interface MissContext {
     attempted: string;
     route: string;

package/dist/element-ladder.js

@@ -12,9 +12,14 @@
 //   4. FAIL               — caller degrades to explain + logs the miss
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findElement = findElement;
+exports.findElementWithRetry = findElementWithRetry;
+exports.waitForDomSettle = waitForDomSettle;
 exports.highlightElement = highlightElement;
 exports.fillElement = fillElement;
 exports.readElement = readElement;
+exports.selectOption = selectOption;
+exports.dragElement = dragElement;
+exports.pressKey = pressKey;
 exports.logMiss = logMiss;
 function findElement(target, liveElements) {
     const live = liveElements?.get(target);
@@ -43,6 +48,89 @@ function findElement(target, liveElements) {
     }
     return null;
 }
+/**
+ * Phase 3 step 4 (see DEVELOPMENT.md/the plan file) — CODA's own point:
+ * the Executor gets real local retry latitude for a genuinely MECHANICAL
+ * miss (a re-render replaced the DOM node the frozen liveElements snapshot
+ * pointed at; an animation/async render hadn't settled yet) before a
+ * failure escalates all the way to the Critic/a replan. Deliberately NOT
+ * a second LLM call — the Executor stays opinion-free, exactly re-running
+ * the SAME real lookup (which, past the liveElements-map check, already
+ * queries the LIVE DOM directly — a stale snapshot doesn't matter to that
+ * part) after a short real wait. A target that's genuinely not on the
+ * page still fails after `attempts`, surfacing as a real miss — this
+ * never silently invents success.
+ */
+async function findElementWithRetry(target, liveElements, attempts = 2, delayMs = 300) {
+    for (let i = 0; i < attempts; i++) {
+        const el = findElement(target, liveElements);
+        if (el)
+            return el;
+        if (i < attempts - 1)
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    return null;
+}
+/**
+ * Real, live-found bug this closes: a `fill`/`click` step reported itself
+ * "done" the instant its DOM event was dispatched — but the app's own
+ * reaction to that event (a filtered search-results grid re-rendering, a
+ * cart count updating) can be an unbounded-latency async round trip (a
+ * Next.js App Router `router.push` re-fetching a server component, for
+ * example — not a fixed debounce with a known delay to just sleep past).
+ * A `read` step immediately after saw STALE content and the agent
+ * confidently reported findings that didn't match what the page actually,
+ * eventually, showed — confirmed live: typing "book" into a search box,
+ * then reading the still-unfiltered product grid a moment later, and
+ * reporting a match ("Novel: The Long Way") the REAL, since-filtered page
+ * went on to show zero results for.
+ *
+ * Waits for real DOM mutations instead of guessing a sleep duration: if
+ * nothing starts mutating within `initialWaitMs`, resolves immediately
+ * (the action had no async effect at all — no reason to add latency to
+ * the common case); once mutations start, waits for `quietMs` of no
+ * further mutations before considering the page settled; a hard
+ * `timeoutMs` ceiling means a page that never stops mutating (an
+ * animation, a polling widget) can't stall the agent loop forever.
+ */
+function waitForDomSettle(initialWaitMs = 100, quietMs = 200, timeoutMs = 1500) {
+    return new Promise((resolve) => {
+        // Real gap this closes: some callers stub a partial `document` (real
+        // tests in this repo do exactly that for other reasons — a fake
+        // WebMCP-tool document, for instance) without the rest of the DOM API
+        // surface — checking `document` alone isn't enough to guarantee
+        // MutationObserver (or document.body) actually exist too.
+        if (typeof document === "undefined" || typeof MutationObserver === "undefined" || !document.body) {
+            resolve();
+            return;
+        }
+        let settled = false;
+        let sawMutation = false;
+        let quietTimer = null;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            observer.disconnect();
+            if (quietTimer)
+                clearTimeout(quietTimer);
+            clearTimeout(hardCap);
+            resolve();
+        };
+        const observer = new MutationObserver(() => {
+            sawMutation = true;
+            if (quietTimer)
+                clearTimeout(quietTimer);
+            quietTimer = setTimeout(finish, quietMs);
+        });
+        observer.observe(document.body, { childList: true, subtree: true, characterData: true, attributes: true });
+        const hardCap = setTimeout(finish, timeoutMs);
+        setTimeout(() => {
+            if (!sawMutation)
+                finish(); // the action had no async effect — nothing to wait for
+        }, initialWaitMs);
+    });
+}
 function highlightElement(el, glowMs = 4000) {
     el.scrollIntoView({ behavior: "smooth", block: "center" });
     el.classList.add("cairn-glow");
@@ -87,6 +175,86 @@ function readElement(el) {
     const trimmed = raw.replace(/\s+/g, " ").trim();
     return trimmed.length > 500 ? `${trimmed.slice(0, 499)}…` : trimmed || "(empty)";
 }
+/**
+ * Chooses a real `<option>` by its visible text — never a raw internal
+ * `value` the model could never actually see. Native `<select>` gets the
+ * direct path (set `.value` to the matching option's own value, then fire
+ * the same input/change pair fillElement uses so React notices). A custom
+ * listbox/combobox (role="listbox"/"option" — Radix, Headless UI, etc.)
+ * has no real `<option>` to set, so the fallback clicks the matching
+ * option-shaped descendant instead, the same "do the real user gesture"
+ * principle the do/click cases already follow.
+ */
+function selectOption(el, visibleText) {
+    if (el.tagName === "SELECT") {
+        const select = el;
+        const match = Array.from(select.options).find((o) => normalize(o.textContent ?? "") === normalize(visibleText)) ?? Array.from(select.options).find((o) => normalize(o.textContent ?? "").includes(normalize(visibleText)));
+        if (!match)
+            return false;
+        select.value = match.value;
+        select.dispatchEvent(new Event("input", { bubbles: true }));
+        select.dispatchEvent(new Event("change", { bubbles: true }));
+        return true;
+    }
+    const candidates = el.querySelectorAll('[role="option"], option, li, [role="menuitem"]');
+    const match = Array.from(candidates).find((c) => normalize(c.textContent ?? "") === normalize(visibleText)) ?? Array.from(candidates).find((c) => normalize(c.textContent ?? "").includes(normalize(visibleText)));
+    if (!match)
+        return false;
+    match.click();
+    return true;
+}
+/**
+ * A real multi-point pointer-event sequence — pointerdown on `from`'s
+ * center, several pointermove steps toward `to`'s center, pointerup on
+ * `to` — the same technique a real mouse drag produces, for canvas/kanban/
+ * sortable-list libraries (react-dnd, dnd-kit, n8n's own node canvas) that
+ * listen for pointer events rather than a single synthetic "drop". Mouse
+ * events are fired alongside (same coordinates) for the older libraries
+ * that still only listen for those. jsdom's getBoundingClientRect returns
+ * all-zero rects with no real layout engine — fine here, since what matters
+ * for a test is that the sequence fires with consistent coordinates, not
+ * that they reflect real pixels.
+ */
+function dragElement(from, to, steps = 5) {
+    const fromRect = from.getBoundingClientRect();
+    const toRect = to.getBoundingClientRect();
+    const fromX = fromRect.left + fromRect.width / 2;
+    const fromY = fromRect.top + fromRect.height / 2;
+    const toX = toRect.left + toRect.width / 2;
+    const toY = toRect.top + toRect.height / 2;
+    const fire = (target, type, x, y) => {
+        const opts = { bubbles: true, cancelable: true, clientX: x, clientY: y, view: typeof window !== "undefined" ? window : undefined };
+        if (typeof PointerEvent !== "undefined")
+            target.dispatchEvent(new PointerEvent(type.replace("mouse", "pointer"), opts));
+        target.dispatchEvent(new MouseEvent(type, opts));
+    };
+    fire(from, "mousedown", fromX, fromY);
+    for (let i = 1; i <= steps; i++) {
+        const x = fromX + ((toX - fromX) * i) / steps;
+        const y = fromY + ((toY - fromY) * i) / steps;
+        fire(i === steps ? to : from, "mousemove", x, y);
+    }
+    fire(to, "mouseup", toX, toY);
+}
+const KEYS_WITH_PRINTABLE_CHAR = new Set(["Enter", "Tab"]);
+/**
+ * Presses one real key on a target element — focuses it first (a real
+ * keypress always lands on whatever's focused; a component that reacts to
+ * Escape/Enter/arrows almost always keys off document-level or its own
+ * focus-scoped listener, so focus has to be real before the event fires).
+ * Fires keydown/keyup (and keypress only for the handful of keys that
+ * still expect one — Enter/Tab — matching a real browser's own behavior,
+ * which no longer fires keypress for pure navigation keys like arrows).
+ */
+function pressKey(el, key) {
+    if (typeof el.focus === "function")
+        el.focus();
+    const opts = { bubbles: true, cancelable: true, key };
+    el.dispatchEvent(new KeyboardEvent("keydown", opts));
+    if (KEYS_WITH_PRINTABLE_CHAR.has(key))
+        el.dispatchEvent(new KeyboardEvent("keypress", opts));
+    el.dispatchEvent(new KeyboardEvent("keyup", opts));
+}
 const MISS_LOG_KEY = "cairn:misses";
 const MISS_LOG_LIMIT = 200;
 function logMiss(context) {

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type HistoryTurn as HistoryEntry } from "@cairnvibe/core";
 export interface CopilotProps {
     /** Reserved for a future client-side manifest fetch. Not required — the server handler owns the manifest. */
     manifest?: string;
@@ -17,6 +18,45 @@ export interface CopilotProps {
     transcribeEndpoint?: string;
     /** If set, the widget speaks each explain/highlight answer aloud (Deepgram TTS via `@cairnvibe/sdk/speak-server`). */
     speakEndpoint?: string;
+    /**
+     * Phase 5 step 4 — whatever opaque id the CUSTOMER's own app already
+     * has for this end user (their own login id, or any other stable
+     * string they choose) — this SDK invents no identity of its own, same
+     * discipline as the realtime relay's own "context" message scopeId.
+     * Sent on every typed-transport request when set; the server only ever
+     * seeds/records real cross-session memory when BOTH this and a
+     * `memory` store are configured (`createCopilotHandler`'s own
+     * `memory` option) — omitting this keeps every request exactly as
+     * memory-less as before this existed, regardless of server config.
+     */
+    scopeId?: string;
+    /**
+     * Architecture Pillar 4 — if set (alongside `criticEndpoint`), the typed/
+     * HTTP loop gets the same real Planner the realtime relay already has:
+     * a task breakdown for a compound goal, and a genuinely separate Critic
+     * pass over each continuing step's real result (packages/sdk/src/
+     * server.ts's `createPlanHandler`/`createCriticHandler`). Omitting
+     * either endpoint keeps the typed loop exactly as it was — click/fill/
+     * read/call_tool executed and folded into history, ended by a terminal
+     * verb or the iteration cap — with zero Planner/Critic overhead, same
+     * opt-in discipline as speakEndpoint/transcribeEndpoint.
+     */
+    planEndpoint?: string;
+    /** See `planEndpoint` — both must be set for the typed loop's Planner/Critic wiring to activate. */
+    criticEndpoint?: string;
+    /**
+     * Architecture Pillar 3 (Skill half) — if set (alongside `planEndpoint`/
+     * `criticEndpoint`), the typed loop saves whatever real, Critic-
+     * verified facts a turn collects (`packages/sdk/src/server.ts`'s
+     * `createSkillSaveHandler`) once the turn concludes — the same
+     * Formulator mechanism the realtime relay already has. Retrieval (a
+     * matching Skill's full instructions surfacing to the Planner) needs no
+     * separate client wiring — it's already part of what `planEndpoint`'s
+     * own server-side handler does once a `SkillStore` is configured there.
+     * Omitting this keeps the typed loop exactly as it was — no Skills are
+     * ever saved, zero overhead.
+     */
+    skillsSaveEndpoint?: string;
     /**
      * If set, shows a "start conversation" control that opens a live
      * WebSocket to a `@cairnvibe/sdk/realtime-server` relay (run via
@@ -28,4 +68,42 @@ export interface CopilotProps {
     /** Display name for the agent, shown in the widget's header and button labels. Defaults to "Cairn". */
     persona?: string;
 }
-export declare function Copilot({ endpoint, registeredActions, onDo, reportMissesEndpoint, transcribeEndpoint, speakEndpoint, realtimeUrl, persona, }: CopilotProps): import("react").JSX.Element;
+export declare function Copilot({ endpoint, registeredActions, onDo, reportMissesEndpoint, transcribeEndpoint, speakEndpoint, scopeId, planEndpoint, criticEndpoint, skillsSaveEndpoint, realtimeUrl, persona, }: CopilotProps): import("react").JSX.Element;
+export declare const CONVERSATION_STORAGE_KEY = "cairn:conversation:v1";
+export interface PersistedConversation {
+    transcript: {
+        id: number;
+        role: "user" | "agent";
+        text: string;
+    }[];
+    lastQuestion: string | null;
+    answer: string | null;
+    open: boolean;
+}
+/**
+ * Real, live-reported bug this closes: a host app's own mutation handler
+ * calling a real `window.location.reload()` — a common, entirely valid
+ * pattern; this SDK's own demo app uses it after several real actions,
+ * e.g. moving a kanban card — tears down the ENTIRE React tree, this
+ * widget included. Every bit of conversation state (the visible
+ * transcript, the current exchange, even whether the panel was open)
+ * reset to nothing, making a real, in-progress conversation look like it
+ * had simply ended the instant a host page happened to reload — even
+ * though nothing about the CONVERSATION itself was actually over.
+ * `sessionStorage`, not `localStorage`, is deliberate: it survives
+ * exactly a reload/navigation within the same tab — the real scope of
+ * "this conversation" — and clears itself once the tab/window actually
+ * closes, never lingering into an unrelated later visit the way
+ * `localStorage` would.
+ */
+export declare function loadPersistedConversation(): PersistedConversation | null;
+export declare function savePersistedConversation(data: PersistedConversation): void;
+/**
+ * Rebuilds a real seed for `historyRef` (what gets sent to the model on
+ * the NEXT typed turn) from a restored transcript — deliberately derived
+ * from the same, already-persisted `transcript` rather than separately
+ * persisting `historyRef`'s own shape: one real source of truth for "what
+ * was actually said," not two that could quietly drift apart. Capped the
+ * same way every other history array in this file already is.
+ */
+export declare function reconstructHistoryFromPersisted(persisted: PersistedConversation | null): HistoryEntry[];