@cairnvibe/sdk 0.2.13 → 0.3.0

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[];