@cairnvibe/sdk 0.1.0

package/dist/dashboard.js

@@ -0,0 +1,60 @@
+"use strict";
+// Server-side aggregation of the element-ladder misses the client already
+// logs to localStorage (see element-ladder.ts). Opt-in: the Copilot widget
+// only reports here if `reportMissesEndpoint` is set. Same
+// build-a-handler-function shape as `createCopilotHandler` in server.ts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMissesStore = createMissesStore;
+exports.summarizeMisses = summarizeMisses;
+exports.createMissesHandler = createMissesHandler;
+/** In-memory store — fine for a demo or a single-instance deployment. Swap for a real one via the same interface. */
+function createMissesStore() {
+    const records = [];
+    return {
+        report(context) {
+            records.push({ ...context, at: new Date().toISOString() });
+        },
+        list() {
+            return [...records];
+        },
+        clear() {
+            records.length = 0;
+        },
+    };
+}
+function summarizeMisses(records) {
+    const groups = new Map();
+    for (const r of records) {
+        const key = `${r.route}::${r.attempted}`;
+        const existing = groups.get(key);
+        if (existing) {
+            existing.count += 1;
+            if (r.at > existing.lastSeen)
+                existing.lastSeen = r.at;
+        }
+        else {
+            groups.set(key, { attempted: r.attempted, route: r.route, count: 1, lastSeen: r.at });
+        }
+    }
+    return Array.from(groups.values()).sort((a, b) => b.count - a.count);
+}
+function isValidMissReport(body) {
+    if (typeof body !== "object" || body === null)
+        return false;
+    const candidate = body;
+    return typeof candidate.attempted === "string" && typeof candidate.route === "string";
+}
+function createMissesHandler(store) {
+    return {
+        async post(body) {
+            if (!isValidMissReport(body)) {
+                return { status: 400, body: { error: "invalid miss report" } };
+            }
+            store.report(body);
+            return { status: 200, body: { ok: true } };
+        },
+        async get() {
+            return { status: 200, body: summarizeMisses(store.list()) };
+        },
+    };
+}

package/dist/element-ladder.d.ts

@@ -0,0 +1,7 @@
+export declare function findElement(target: string): HTMLElement | null;
+export declare function highlightElement(el: HTMLElement, glowMs?: number): void;
+export interface MissContext {
+    attempted: string;
+    route: string;
+}
+export declare function logMiss(context: MissContext): void;

package/dist/element-ladder.js

@@ -0,0 +1,60 @@
+"use strict";
+// The 4-step Element Ladder (BUILD_PLAN.md invariant #3): a lookup failure
+// must degrade to explain-only, never guess and click the wrong thing.
+//
+//   1. data-ai="..."     — exact, authoritative
+//   2. aria-label / role — accessible-name fallback
+//   3. visible text      — last resort, exact then substring match
+//   4. FAIL               — caller degrades to explain + logs the miss
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findElement = findElement;
+exports.highlightElement = highlightElement;
+exports.logMiss = logMiss;
+function findElement(target) {
+    if (typeof document === "undefined")
+        return null;
+    const byDataAi = document.querySelector(`[data-ai="${cssEscape(target)}"]`);
+    if (byDataAi)
+        return byDataAi;
+    const byAriaLabel = document.querySelector(`[aria-label="${cssEscape(target)}"]`);
+    if (byAriaLabel)
+        return byAriaLabel;
+    const byRole = document.querySelector(`[role="${cssEscape(target)}"]`);
+    if (byRole)
+        return byRole;
+    const candidates = document.querySelectorAll("button, a, [role='button'], input[type='submit'], input[type='button']");
+    const normalizedTarget = normalize(target);
+    for (const el of Array.from(candidates)) {
+        if (normalize(el.textContent ?? "") === normalizedTarget)
+            return el;
+    }
+    for (const el of Array.from(candidates)) {
+        if (normalize(el.textContent ?? "").includes(normalizedTarget))
+            return el;
+    }
+    return null;
+}
+function highlightElement(el, glowMs = 4000) {
+    el.scrollIntoView({ behavior: "smooth", block: "center" });
+    el.classList.add("cairn-glow");
+    window.setTimeout(() => el.classList.remove("cairn-glow"), glowMs);
+}
+const MISS_LOG_KEY = "cairn:misses";
+const MISS_LOG_LIMIT = 200;
+function logMiss(context) {
+    try {
+        const existingRaw = window.localStorage.getItem(MISS_LOG_KEY);
+        const existing = existingRaw ? JSON.parse(existingRaw) : [];
+        existing.push({ ...context, at: new Date().toISOString() });
+        window.localStorage.setItem(MISS_LOG_KEY, JSON.stringify(existing.slice(-MISS_LOG_LIMIT)));
+    }
+    catch {
+        // localStorage unavailable (SSR, private mode, quota) — never let logging break the UI.
+    }
+}
+function normalize(s) {
+    return s.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function cssEscape(s) {
+    return s.replace(/["\\]/g, "\\$&");
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export interface CopilotProps {
+    /** Reserved for a future client-side manifest fetch. Not required — the server handler owns the manifest. */
+    manifest?: string;
+    /** Where the widget posts questions. Defaults to "/api/copilot". */
+    endpoint?: string;
+    /** Action ids this deployment actually wired up for the "do" verb. */
+    registeredActions?: string[];
+    /** Called when the model returns a valid "do" verb for a registered action. */
+    onDo?: (action: string, target?: string) => void;
+    /** If set, a lookup miss is also POSTed here so failures can be aggregated server-side. */
+    reportMissesEndpoint?: string;
+    /**
+     * If set, shows a mic button that records audio and POSTs it here for
+     * transcription — re-sent every ~2s while recording so the field fills in
+     * progressively. Hidden automatically if the browser has no mic access.
+     */
+    transcribeEndpoint?: string;
+    /** If set, the widget speaks each explain/highlight answer aloud (Deepgram TTS via `@cairnvibe/sdk/speak-server`). */
+    speakEndpoint?: string;
+    /**
+     * If set, shows a "start conversation" control that opens a live
+     * WebSocket to a `@cairnvibe/sdk/realtime-server` relay (run via
+     * `cairn-realtime`) for a real-time voice conversation: streaming
+     * transcription, verbs executed as soon as they're resolved, and the
+     * answer spoken back — all without you touching the keyboard.
+     */
+    realtimeUrl?: string;
+    /** 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;