@project-ava-supernova/core 0.2.71

package/dist/desktop/screen-key.d.ts

@@ -0,0 +1,54 @@
+/** An image-based screen key: 32×32 grayscale + its 64-bit average hash. */
+export interface ImageScreenKey {
+    kind: 'img';
+    /** Hex-encoded 64-bit aHash (16 hex chars). */
+    hash: string;
+    /** Base64 of the raw grayscale bytes, row-major, w*h long. */
+    gray: string;
+    w: number;
+    h: number;
+}
+/** A textual fallback key for vision-off hosts: app + normalized task. */
+export interface CtxScreenKey {
+    kind: 'ctx';
+    ctx: string;
+}
+export type ScreenKey = ImageScreenKey | CtxScreenKey;
+/** Default match thresholds — tuned for 32×32 thumbnails. */
+export declare const HAMMING_MAX = 12;
+export declare const SSIM_MIN = 0.82;
+/** Build an image key from raw grayscale bytes (row-major, w*h long). */
+export declare function imageKey(gray: Uint8Array | number[], w: number, h: number): ImageScreenKey;
+/** Build the vision-off fallback key. Normalized so identical contexts match. */
+export declare function ctxKey(app: string | undefined, task: string): CtxScreenKey;
+/**
+ * 64-bit average hash: mean-pool the image into an 8×8 grid, then each cell
+ * contributes one bit (above overall mean = 1). Survives small pixel noise;
+ * collapses under layout changes — exactly the prefilter we want.
+ */
+export declare function averageHash(gray: Uint8Array, w: number, h: number): string;
+/** Hamming distance between two hex-encoded hashes (bit differences). */
+export declare function hamming(hashA: string, hashB: string): number;
+/**
+ * Global SSIM over two equal-size grayscale images. The standard formula with
+ * the usual stabilisation constants (K1=0.01, K2=0.03, L=255), computed over
+ * the whole thumbnail — at 32×32 a windowed SSIM adds cost, not signal.
+ * Returns 1 for identical images, → 0 as structure diverges.
+ */
+export declare function computeSsim(a: Uint8Array, b: Uint8Array): number;
+/**
+ * Match a current key against stored candidates. Image keys: Hamming
+ * prefilter (cheap) then SSIM (real) — best SSIM wins if it clears the
+ * threshold. Ctx keys: exact match. Cross-kind never matches. Returns the
+ * winning candidate index + score, or null.
+ */
+export declare function matchScreen(current: ScreenKey, candidates: ScreenKey[], opts?: {
+    hammingMax?: number;
+    ssimMin?: number;
+}): {
+    index: number;
+    score: number;
+} | null;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(b64: string): Uint8Array;
+//# sourceMappingURL=screen-key.d.ts.map

package/dist/desktop/screen-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-key.d.ts","sourceRoot":"","sources":["../../src/desktop/screen-key.ts"],"names":[],"mappings":"AAmBA,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,KAAK,CAAC;IACZ,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,YAAY,CAAC;AAEtD,6DAA6D;AAC7D,eAAO,MAAM,WAAW,KAAK,CAAC;AAC9B,eAAO,MAAM,QAAQ,OAAO,CAAC;AAI7B,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,cAAc,CAU1F;AAED,iFAAiF;AACjF,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAI1E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA8B1E;AAED,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAoBhE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,EAClB,UAAU,EAAE,SAAS,EAAE,EACvB,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAsBzC;AAMD,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAUvD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAcrD"}

package/dist/desktop/screen-key.js

@@ -0,0 +1,187 @@
+// Screen fingerprinting (Phase 3A) — "have I seen this screen before?"
+// without a model. The host captures a small grayscale thumbnail (32×32) of
+// the virtual desktop; this module turns it into a comparable key:
+//
+//   - aHash (64-bit average hash) — cheap equality prefilter via Hamming
+//     distance, so matching against hundreds of stored keys costs microseconds.
+//   - SSIM (structural similarity) — the real comparison, run only on the few
+//     candidates that survive the prefilter.
+//
+// Adapted from UI-Voyager's GRSD state-matching (Tencent Hunyuan, arXiv
+// 2603.24533): SSIM on grayscale thumbnails is how fork-points pair a failed
+// action with a later success ON THE SAME SCREEN.
+//
+// Consent: the thumbnail is a downscaled screenshot, so hosts must only
+// capture it when the user's vision setting allows capture at all. With
+// vision off, keying degrades honestly to a textual context key (app+task) —
+// see `ctxKey`. Everything here is pure data-in/data-out: no fs, no OS calls,
+// unit-testable on any platform.
+/** Default match thresholds — tuned for 32×32 thumbnails. */
+export const HAMMING_MAX = 12; // of 64 bits; generous prefilter
+export const SSIM_MIN = 0.82; // structural agreement required to call it "the same screen"
+// ── Key construction ────────────────────────────────────────────────────────
+/** Build an image key from raw grayscale bytes (row-major, w*h long). */
+export function imageKey(gray, w, h) {
+    const bytes = gray instanceof Uint8Array ? gray : Uint8Array.from(gray);
+    if (bytes.length !== w * h)
+        throw new Error(`imageKey: expected ${w * h} bytes, got ${bytes.length}`);
+    return {
+        kind: 'img',
+        hash: averageHash(bytes, w, h),
+        gray: bytesToBase64(bytes),
+        w,
+        h,
+    };
+}
+/** Build the vision-off fallback key. Normalized so identical contexts match. */
+export function ctxKey(app, task) {
+    const a = (app || 'unknown').toLowerCase().trim();
+    const t = task.toLowerCase().replace(/\s+/g, ' ').trim().slice(0, 80);
+    return { kind: 'ctx', ctx: `${a}|${t}` };
+}
+/**
+ * 64-bit average hash: mean-pool the image into an 8×8 grid, then each cell
+ * contributes one bit (above overall mean = 1). Survives small pixel noise;
+ * collapses under layout changes — exactly the prefilter we want.
+ */
+export function averageHash(gray, w, h) {
+    const GRID = 8;
+    const cells = new Float64Array(GRID * GRID);
+    const cellW = w / GRID;
+    const cellH = h / GRID;
+    for (let gy = 0; gy < GRID; gy++) {
+        for (let gx = 0; gx < GRID; gx++) {
+            let sum = 0;
+            let n = 0;
+            const x0 = Math.floor(gx * cellW), x1 = Math.max(x0 + 1, Math.floor((gx + 1) * cellW));
+            const y0 = Math.floor(gy * cellH), y1 = Math.max(y0 + 1, Math.floor((gy + 1) * cellH));
+            for (let y = y0; y < y1 && y < h; y++) {
+                for (let x = x0; x < x1 && x < w; x++) {
+                    sum += gray[y * w + x];
+                    n++;
+                }
+            }
+            cells[gy * GRID + gx] = n > 0 ? sum / n : 0;
+        }
+    }
+    const mean = cells.reduce((s, v) => s + v, 0) / cells.length;
+    let hex = '';
+    for (let i = 0; i < 64; i += 4) {
+        let nibble = 0;
+        for (let b = 0; b < 4; b++) {
+            nibble = (nibble << 1) | (cells[i + b] > mean ? 1 : 0);
+        }
+        hex += nibble.toString(16);
+    }
+    return hex;
+}
+/** Hamming distance between two hex-encoded hashes (bit differences). */
+export function hamming(hashA, hashB) {
+    if (hashA.length !== hashB.length)
+        return Number.MAX_SAFE_INTEGER;
+    let dist = 0;
+    for (let i = 0; i < hashA.length; i++) {
+        let x = parseInt(hashA[i], 16) ^ parseInt(hashB[i], 16);
+        while (x) {
+            dist += x & 1;
+            x >>= 1;
+        }
+    }
+    return dist;
+}
+/**
+ * Global SSIM over two equal-size grayscale images. The standard formula with
+ * the usual stabilisation constants (K1=0.01, K2=0.03, L=255), computed over
+ * the whole thumbnail — at 32×32 a windowed SSIM adds cost, not signal.
+ * Returns 1 for identical images, → 0 as structure diverges.
+ */
+export function computeSsim(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    const n = a.length;
+    let meanA = 0, meanB = 0;
+    for (let i = 0; i < n; i++) {
+        meanA += a[i];
+        meanB += b[i];
+    }
+    meanA /= n;
+    meanB /= n;
+    let varA = 0, varB = 0, cov = 0;
+    for (let i = 0; i < n; i++) {
+        const da = a[i] - meanA;
+        const db = b[i] - meanB;
+        varA += da * da;
+        varB += db * db;
+        cov += da * db;
+    }
+    varA /= n - 1;
+    varB /= n - 1;
+    cov /= n - 1;
+    const L = 255;
+    const c1 = (0.01 * L) ** 2;
+    const c2 = (0.03 * L) ** 2;
+    return ((2 * meanA * meanB + c1) * (2 * cov + c2)) /
+        ((meanA * meanA + meanB * meanB + c1) * (varA + varB + c2));
+}
+/**
+ * Match a current key against stored candidates. Image keys: Hamming
+ * prefilter (cheap) then SSIM (real) — best SSIM wins if it clears the
+ * threshold. Ctx keys: exact match. Cross-kind never matches. Returns the
+ * winning candidate index + score, or null.
+ */
+export function matchScreen(current, candidates, opts = {}) {
+    const hMax = opts.hammingMax ?? HAMMING_MAX;
+    const sMin = opts.ssimMin ?? SSIM_MIN;
+    if (current.kind === 'ctx') {
+        const idx = candidates.findIndex(c => c.kind === 'ctx' && c.ctx === current.ctx);
+        return idx >= 0 ? { index: idx, score: 1 } : null;
+    }
+    const curGray = base64ToBytes(current.gray);
+    let best = null;
+    for (let i = 0; i < candidates.length; i++) {
+        const cand = candidates[i];
+        if (cand.kind !== 'img')
+            continue;
+        if (cand.w !== current.w || cand.h !== current.h)
+            continue;
+        if (hamming(current.hash, cand.hash) > hMax)
+            continue; // prefilter
+        const score = computeSsim(curGray, base64ToBytes(cand.gray));
+        if (score >= sMin && (!best || score > best.score)) {
+            best = { index: i, score };
+        }
+    }
+    return best;
+}
+// ── Base64 helpers (no Buffer dependency — webview/node agnostic) ──────────
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+export function bytesToBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i], b1 = bytes[i + 1], b2 = bytes[i + 2];
+        out += B64[b0 >> 2];
+        out += B64[((b0 & 3) << 4) | ((b1 ?? 0) >> 4)];
+        out += i + 1 < bytes.length ? B64[(((b1 ?? 0) & 15) << 2) | ((b2 ?? 0) >> 6)] : '=';
+        out += i + 2 < bytes.length ? B64[(b2 ?? 0) & 63] : '=';
+    }
+    return out;
+}
+export function base64ToBytes(b64) {
+    const clean = b64.replace(/=+$/, '');
+    const out = new Uint8Array(Math.floor((clean.length * 3) / 4));
+    let o = 0;
+    for (let i = 0; i < clean.length; i += 4) {
+        const n = (B64.indexOf(clean[i]) << 18)
+            | (B64.indexOf(clean[i + 1] ?? 'A') << 12)
+            | (B64.indexOf(clean[i + 2] ?? 'A') << 6)
+            | B64.indexOf(clean[i + 3] ?? 'A');
+        if (o < out.length)
+            out[o++] = (n >> 16) & 255;
+        if (o < out.length)
+            out[o++] = (n >> 8) & 255;
+        if (o < out.length)
+            out[o++] = n & 255;
+    }
+    return out;
+}
+//# sourceMappingURL=screen-key.js.map

package/dist/desktop/screen-key.js.map

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

package/dist/desktop/types.d.ts

@@ -0,0 +1,141 @@
+import type { RiskClass } from './safety.js';
+export type GroundingSource = 'uia' | 'playwright' | 'omniparser' | 'merged';
+export type ConfidenceLevel = 'high' | 'medium' | 'low';
+export interface ScreenElement {
+    /** Stable ID from the grounding source (UIA RuntimeId, DOM selector, OmniParser index) */
+    id: string;
+    /** Element kind — button, textbox, link, menuitem, icon, text, etc. */
+    kind: string;
+    /** Display name / accessible name / caption */
+    name: string;
+    /** Bounding box as normalised [x, y, width, height] (0–1 range) */
+    bbox?: [number, number, number, number];
+    /** CSS selector (Playwright-sourced elements only) */
+    selector?: string;
+    /** Which grounding tier produced this element */
+    source: GroundingSource;
+    /** Whether the element is interactable (clickable, typeable) */
+    interactable: boolean;
+    /** Another window is physically covering this element — a click would hit
+     *  the covering window instead. Clear the occlusion (minimize_all / focus)
+     *  before targeting it. */
+    occluded?: boolean;
+    /** Which surface produced this element: an open context menu / dropdown,
+     *  the desktop's icon list, or a regular app window. */
+    surface?: 'menu' | 'desktop-icon' | 'app';
+    /** Whether this element contains sensitive content (password field, API key, etc.) */
+    sensitive: boolean;
+}
+/** Scout's output — what's visible on screen right now. */
+export interface ScreenState {
+    /** ISO timestamp when the screen was captured */
+    capturedAt: string;
+    /** Primary grounding source for this state */
+    groundingSource: GroundingSource;
+    /** How much Scout trusts this snapshot */
+    confidence: ConfidenceLevel;
+    /** Structured elements visible on screen */
+    elements: ScreenElement[];
+    /** The active window/app name */
+    activeApp?: string;
+    /** The active page URL (for Playwright-sourced states) */
+    activeUrl?: string;
+    /** The page title */
+    activeTitle?: string;
+    /** Anything Planner should know — partial tree, loading, obstruction */
+    notes?: string;
+}
+export type ActionKind = 'click' | 'double_click' | 'right_click' | 'type' | 'key' | 'scroll' | 'drag' | 'minimize_all' | 'navigate' | 'launch' | 'wait' | 'observe_more' | 'stuck' | 'done';
+import type { ScreenKey } from './screen-key.js';
+/** Planner's output — the single next action. */
+export interface ProposedAction {
+    /** Exactly one action per step */
+    kind: ActionKind;
+    /** Element ID from ScreenState that this action targets (null for non-targeted actions) */
+    target?: string;
+    /** Action-specific parameters */
+    params?: Record<string, unknown>;
+    /** Risk classification per the safety ontology */
+    riskClass: RiskClass;
+    /** Planner's reasoning for this action (for audit, not for Actor) */
+    reasoning: string;
+    /** One-sentence prediction of what the screen should look like after this action */
+    expectedPostState: string;
+    /**
+     * Where the impetus for this action came from (anti-prompt-injection spine):
+     * 'user' — carries out something the USER asked for in the task;
+     * 'observed' — prompted by text READ OFF THE SCREEN (a page/email/dialog
+     * saying "click X to continue"). Observed-origin mutative actions force a
+     * fresh confirm even in Drive, with a "this came from the page, not you"
+     * banner. Primary signal: the Planner self-declares; a conductor heuristic
+     * backstops it. Never the only guard — the irreversible floor stands.
+     */
+    origin?: 'user' | 'observed';
+}
+/** Actor's output — what happened when the action ran. */
+export interface ExecutionResult {
+    /** Whether the action executed successfully */
+    ok: boolean;
+    /** Error message if ok=false */
+    error?: string;
+    /** Wall-clock time from action start to result */
+    latencyMs: number;
+    /** Observable side effects — popup, URL change, focus shift */
+    sideEffects?: string[];
+}
+export type VerificationStatus = 'verified' | 'deviated' | 'rollback_needed';
+/** Verifier's output — did the action land? */
+export interface VerificationResult {
+    /** Whether post-state matches Planner's prediction */
+    status: VerificationStatus;
+    /** Evidence — "Compose window visible, subject field focused" */
+    detail: string;
+    /** Description of what happened instead (for 'deviated' or 'rollback_needed') */
+    deviation?: string;
+}
+/** Narrator's output — user-facing + audit record. */
+export interface UserUpdate {
+    /** One-line past-tense summary for the user: "Opened Gmail." */
+    line: string;
+    /** Full structured audit record */
+    audit: {
+        step: number;
+        action: ProposedAction;
+        result: ExecutionResult;
+        verification: VerificationResult;
+        timestamp: string;
+    };
+}
+/** One complete step in a trajectory. */
+export interface TrajectoryStep {
+    stepNumber: number;
+    screenState: ScreenState;
+    proposedAction: ProposedAction;
+    executionResult: ExecutionResult;
+    verificationResult: VerificationResult;
+    userUpdate: UserUpdate;
+    /** Phase 3: fingerprint of the screen this step acted on — SSIM thumbnail
+     *  key when the vision setting allows capture, textual app+task key when
+     *  not. What fork-point learning pairs failures/corrections by. */
+    screenKey?: ScreenKey;
+    tokensConsumed: {
+        scout: number;
+        planner: number;
+        actor: number;
+        verifier: number;
+        narrator: number;
+        omniParser: number;
+    };
+}
+/** A complete trajectory from start to finish. */
+export interface Trajectory {
+    id: string;
+    task: string;
+    startedAt: string;
+    endedAt?: string;
+    steps: TrajectoryStep[];
+    whitelist: string[];
+    permissionLevel: 'watch' | 'drive';
+    outcome: 'completed' | 'stopped' | 'stuck' | 'budget_exceeded' | 'error';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/desktop/types.d.ts.map

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

package/dist/desktop/types.js

@@ -0,0 +1,8 @@
+// ─── Desktop Automation Types ──────────────────────────────────────────────
+//
+// Typed schemas for inter-persona data flow during a desktop automation
+// trajectory. Each persona produces one of these; the next persona consumes
+// the previous one(s). This is the single source of truth — prototypes,
+// sidecar, and IDE all import from here.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/desktop/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/desktop/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,EAAE;AACF,wEAAwE;AACxE,4EAA4E;AAC5E,wEAAwE;AACxE,yCAAyC"}

package/dist/docs/adapter.d.ts

@@ -0,0 +1,71 @@
+import type { DocBlock, DocPage, SidebarNode, Surface, FactsBlock } from './types.js';
+import type { ToolFact } from './data/tools.js';
+import type { ProviderFact } from './data/providers.js';
+import type { ModeFact } from './data/modes.js';
+import type { PersonaFact } from './data/personas.js';
+import type { PermissionModeFact } from './data/permissions.js';
+import type { ShortcutFact } from './data/shortcuts.js';
+import type { ProductSurface } from './data/capabilities.js';
+/**
+ * Optional per-page extras a renderer can surface alongside the body:
+ *  - `deeper`: rendered "Show me the details" blocks shown behind an expander,
+ *     so one page serves newcomers and power users.
+ *  - `badges`: the product surfaces this page applies to (derived from its
+ *     `requires`). Undefined means it works everywhere — no badge needed.
+ */
+export interface PageExtras<Out> {
+    deeper?: Out[];
+    badges?: ProductSurface[];
+}
+/** Which product surfaces to badge a page with — undefined when it works everywhere. */
+export declare function pageBadges(page: DocPage): ProductSurface[] | undefined;
+/**
+ * A surface renderer produces a value of type `Out` for each block. For React surfaces
+ * Out is `ReactNode`; for the extension webview Out is `string` (HTML).
+ */
+export interface RendererAdapter<Out> {
+    paragraph(text: string): Out;
+    heading(level: 2 | 3 | 4, text: string, anchor?: string): Out;
+    list(items: string[], ordered: boolean): Out;
+    code(text: string, language: string): Out;
+    callout(text: string, variant: 'note' | 'warning' | 'tip'): Out;
+    link(text: string, href: string, external: boolean): Out;
+    table(headers: string[], rows: string[][]): Out;
+    tools(items: ToolFact[], filter: FactsBlock & {
+        kind: 'tools';
+    }): Out;
+    providers(items: ProviderFact[], filter: FactsBlock & {
+        kind: 'providers';
+    }): Out;
+    modes(items: ModeFact[]): Out;
+    personas(items: PersonaFact[], filter: FactsBlock & {
+        kind: 'personas';
+    }): Out;
+    permissions(items: PermissionModeFact[]): Out;
+    shortcuts(items: ShortcutFact[], filter: FactsBlock & {
+        kind: 'shortcuts';
+    }): Out;
+    /**
+     * Assemble a list of rendered blocks into a page container. `extras` carries
+     * the optional "Show me the details" depth and the surface badges; renderers
+     * that don't yet support them can ignore the param (it's optional).
+     */
+    page(title: string, blocks: Out[], anchor: string, extras?: PageExtras<Out>): Out;
+    /** Assemble a list of rendered pages into the top-level document. */
+    document(pages: Out[], sidebar: SidebarNode[], surface: Surface): Out;
+}
+/**
+ * Walk a single page's body blocks and drive the adapter. Pure function —
+ * no surface primitives leak in here.
+ */
+export declare function renderPage<Out>(page: DocPage, adapter: RendererAdapter<Out>, data: FactsData): Out;
+export declare function renderBlock<Out>(block: DocBlock, adapter: RendererAdapter<Out>, data: FactsData): Out;
+export interface FactsData {
+    tools: ToolFact[];
+    providers: ProviderFact[];
+    modes: ModeFact[];
+    personas: PersonaFact[];
+    permissions: PermissionModeFact[];
+    shortcuts: ShortcutFact[];
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/docs/adapter.d.ts.map

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

package/dist/docs/adapter.js

@@ -0,0 +1,75 @@
+// Surface adapter contract. The website, extension, and IDE each implement this interface
+// with their own primitives (Tailwind JSX for web, inline-styled JSX for IDE, HTML string
+// builder for the extension webview). Keeping this contract in core guarantees all three
+// surfaces render the same blocks in the same order from the same data.
+import { commonSurfaces } from './data/capabilities.js';
+/** Which product surfaces to badge a page with — undefined when it works everywhere. */
+export function pageBadges(page) {
+    if (!page.requires || page.requires.length === 0)
+        return undefined;
+    return commonSurfaces(page.requires);
+}
+/**
+ * Walk a single page's body blocks and drive the adapter. Pure function —
+ * no surface primitives leak in here.
+ */
+export function renderPage(page, adapter, data) {
+    const blocks = page.body.map(block => renderBlock(block, adapter, data));
+    const deeper = page.deeper && page.deeper.length
+        ? page.deeper.map(block => renderBlock(block, adapter, data))
+        : undefined;
+    return adapter.page(page.title, blocks, anchorFromId(page.id), { deeper, badges: pageBadges(page) });
+}
+export function renderBlock(block, adapter, data) {
+    switch (block.type) {
+        case 'paragraph': return adapter.paragraph(block.text);
+        case 'heading': return adapter.heading(block.level, block.text, block.anchor);
+        case 'list': return adapter.list(block.items, block.ordered);
+        case 'code': return adapter.code(block.text, block.language);
+        case 'callout': return adapter.callout(block.text, block.variant);
+        case 'link': return adapter.link(block.text, block.href, block.external ?? false);
+        case 'table': return adapter.table(block.headers, block.rows);
+        case 'facts': return renderFacts(block, adapter, data);
+    }
+}
+function renderFacts(block, adapter, data) {
+    switch (block.kind) {
+        case 'tools':
+            return adapter.tools(filterTools(data.tools, block.filter), block);
+        case 'providers':
+            return adapter.providers(filterProviders(data.providers, block.filter), block);
+        case 'modes':
+            return adapter.modes(data.modes);
+        case 'personas':
+            return adapter.personas(filterPersonas(data.personas, block.filter), block);
+        case 'permissions':
+            return adapter.permissions(data.permissions);
+        case 'shortcuts':
+            return adapter.shortcuts(filterShortcuts(data.shortcuts, block.filter), block);
+    }
+}
+function filterTools(items, filter) {
+    if (!filter)
+        return items;
+    return items.filter(t => (!filter.category || t.category === filter.category) &&
+        (!filter.risk || t.risk === filter.risk));
+}
+function filterProviders(items, filter) {
+    if (!filter?.kind)
+        return items;
+    return items.filter(p => p.kind === filter.kind);
+}
+function filterPersonas(items, filter) {
+    if (!filter?.mode)
+        return items;
+    return items.filter(p => p.mode === filter.mode);
+}
+function filterShortcuts(items, filter) {
+    if (!filter?.surface)
+        return items;
+    return items.filter(s => s.surfaces.includes(filter.surface));
+}
+function anchorFromId(id) {
+    return id.replace(/\./g, '-');
+}
+//# sourceMappingURL=adapter.js.map

package/dist/docs/adapter.js.map

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

package/dist/docs/content/concepts.d.ts

@@ -0,0 +1,3 @@
+import type { DocPage } from '../types.js';
+export declare const CONCEPT_PAGES: DocPage[];
+//# sourceMappingURL=concepts.d.ts.map

package/dist/docs/content/concepts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concepts.d.ts","sourceRoot":"","sources":["../../../src/docs/content/concepts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAI3C,eAAO,MAAM,aAAa,EAAE,OAAO,EAuTlC,CAAC"}