autokap 1.0.6 → 1.0.8

package/assets/skill/references/interactive-demo.md

@@ -0,0 +1,225 @@
+# Interactive Demo Workflow Reference
+
+Use this reference when the user wants an embeddable product demo driven by
+captured DOM states plus deterministic local interactions, not just static
+screenshots or clips.
+
+## When to use interactive demos
+
+Choose this mode when:
+
+- the output should feel clickable and alive on a landing page or docs page
+- the user wants to recreate a focused product loop, not the entire app
+- 2-6 distinct base states are enough and the rest can be reconstructed locally
+- the main value comes from local UI reactions such as switching tabs, opening
+  a panel, swapping a preview, or editing small bits of content
+
+Prefer plain screenshots or clips when the user only needs static visuals or a
+linear recording.
+
+## Core mental model
+
+For interactive demos, the captured DOM is only the substrate. The quality of
+the result depends on the interaction model:
+
+1. what the viewer can click or edit
+2. which parts of the UI react immediately
+3. which changes need a new captured state vs local reconstruction
+
+Do not start from "capture every page". Start from the feature loop the user
+wants to showcase, then capture only what is needed to support that loop.
+
+## What to capture vs what to reconstruct
+
+Use this decision rule:
+
+- whole page or route changes: create another `CAPTURE_DOM` base state
+- one focused shell matters more than the whole page: use `CAPTURE_DOM` with a
+  `selector`
+- modal / popover / dropdown / sheet: use `CAPTURE_FRAGMENT`
+- local text / class / visible-state changes: use player API or bindings
+- repeated editable content: use templates / repeaters / model bindings
+- complex app-specific logic: use custom interaction `code` as the last resort
+
+Default bias:
+
+- fewer base states
+- more local reconstruction
+- a small number of meaningful viewer interactions
+- focus on the central product experience
+
+## Required authored markers
+
+### Viewer interaction markers
+
+Add `data-ak-interact="<name>"` to every element the viewer should operate in
+the published demo.
+
+```tsx
+<button data-ak-interact="open-chat">Open chat</button>
+<button data-ak-interact="settings-link">Settings</button>
+```
+
+Use kebab-case names and keep the marker set intentionally small.
+
+### Fragment markers
+
+Add `data-ak-fragment="<name>"` on the root of every modal/popover/dropdown
+subtree that should be captured separately.
+
+Use `data-ak-mount` when mounting behavior matters:
+
+- `inline`
+- `overlay`
+- `portal:<target-name>`
+
+Add `data-ak-mount-target="<target-name>"` when a portal mount location is
+required.
+
+### Model / behavior markers
+
+Prefer authored markers before custom code:
+
+- `data-ak-model="<path>"`
+- `data-ak-bind="..."`
+- `data-ak-action="..."`
+- `data-ak-template="<name>"`
+- `data-ak-behavior="tabs|popover|slider|..."` for standard widget hints
+
+These give the player enough structure to replay many standard UI behaviors
+without bespoke JavaScript.
+
+## Capture flow
+
+### Base states
+
+Set `mediaMode: "dom"` and `artifactPlan: { "mediaMode": "dom" }`, then use
+normal deterministic opcodes to reach each captured state.
+
+Use `CAPTURE_DOM` for:
+
+- the full page
+- or a focused shell via `selector`
+
+Good focused-shell selectors:
+
+- `[data-ak="studio-shell"]`
+- `[data-ak="pricing-calculator"]`
+- `[data-ak="dashboard-hero"]`
+
+Avoid targeting tiny leaf nodes.
+
+### Fragments
+
+Use `CAPTURE_FRAGMENT` when only a local subtree changes.
+
+Preferred pattern:
+
+1. use visible UI to open the fragment
+2. `WAIT_FOR` the fragment root
+3. capture it with `CAPTURE_FRAGMENT`
+
+Fallback pattern:
+
+Add a hidden fragment trigger button when the fragment is not reachable through
+visible UI.
+
+## Fragment variants
+
+Capture the same fragment under multiple `variantName`s when an interaction only
+swaps a subtree in place, for example:
+
+- preview background changes
+- before / after toggle
+- local layout switch
+
+Rules:
+
+- capture the baseline first
+- keep variant names kebab-case
+- keep the same fragment root selector across variants
+- use variants only for structurally related subtree swaps
+
+## Interaction script
+
+The interaction script lives in `config.interactiveDemo.script`.
+
+Each interaction has only four required fields:
+
+- `state`
+- `selector`
+- `trigger`
+- `code`
+
+Canonical shape:
+
+```json
+{
+  "state": "dashboard",
+  "selector": "[data-ak-interact='open-chat']",
+  "trigger": "click",
+  "code": "await api.navigate('dashboard-chat-open', 'fade');"
+}
+```
+
+Use `[data-ak-interact='...']` selectors by default.
+
+Supported triggers:
+
+- `click`
+- `hover`
+- `submit`
+
+## Player API
+
+The interaction `code` receives:
+
+- `doc`
+- `iframe`
+- `api`
+- `state`
+- `target`
+
+Prefer the player API before raw DOM mutation:
+
+- `api.navigate(...)`
+- `api.delay(...)`
+- `api.query(...)`
+- `api.setText(...)`
+- `api.toggleClass(...)`
+- `api.setValue(...)`
+- `api.show(...)` / `api.hide(...)`
+- `api.model.*`
+- `api.template.*`
+- `api.fragment.show / hide / swap / toggle / current / variants`
+
+Use raw DOM access only when the built-in helpers and declarative markers are
+not expressive enough.
+
+## Common failure modes
+
+- treating a custom dropdown like a native `<select>`
+- not preserving active-state markers such as `aria-selected` or `data-state`
+- capturing the trigger but not the controlled surface
+- using unstable selectors like utility classes or text selectors
+- forgetting that portal UI lives outside the main subtree
+- capturing before the controlled DOM has actually settled
+- trying to reconstruct canvas/WebGL internals directly from DOM capture
+- over-capturing every page instead of focusing on the feature loop
+
+## Preview and publish
+
+After a run, the user previews the demo at:
+
+`/projects/<projectId>/presets/<presetId>/preview`
+
+The public URL is:
+
+`/demo/<presetId>`
+
+The embed snippet is:
+
+```html
+<div data-ak-demo="<presetId>"></div>
+<script src="https://autokap.app/api/v1/loader.js" defer></script>
+```

package/assets/skill/references/mock-data.md

@@ -0,0 +1,178 @@
+# Mock Data Injection Reference
+
+Use this reference when the user enables mock data generation or when a target
+capture would otherwise show empty tables, empty lists, empty charts, or other
+unhelpful placeholder states.
+
+## When to use it
+
+Use mock data when:
+
+- the page would otherwise render an empty state
+- the marketing value depends on populated cards, rows, charts, or metrics
+- the user explicitly enabled "Generate mock data"
+
+Do not use it just because the feature exists. If the real page already renders
+stable, attractive data, prefer the real state.
+
+## Core model
+
+Mock data injection has two complementary delivery mechanisms and the runtime
+applies both when they are wired:
+
+### Clone
+
+Clone a DOM template element, then write slot values into the cloned
+descendants.
+
+Best for:
+
+- tables
+- card grids
+- simple lists
+- badge rows
+
+### Trigger
+
+Write JSON into a hidden input and click a hidden button the app exposes. The
+component reads the payload and re-renders through normal app state.
+
+Best for:
+
+- charts
+- calendars
+- maps
+- library-owned DOM
+- anything likely to re-render and overwrite a clone
+
+## Default rule
+
+For modern React/Vue/Svelte apps, wire **both** clone and trigger whenever
+possible.
+
+Use only one mechanism when:
+
+- the page is pure server-rendered HTML with no client-side state: clone-only
+- the widget has no useful DOM template to clone: trigger-only
+
+## Critical slot rule
+
+Every variable UI element must be represented as a slot.
+
+Commonly missed slots:
+
+- dates
+- counts
+- status badges
+- labels that look static
+- type icons or icon variants
+- prices
+- ratings
+- role / owner / modified-at metadata
+- chart legends and series labels
+
+Rule of thumb:
+
+Walk through each JSX expression, ternary, and conditional class. If that value
+could differ across items, it should be a slot.
+
+## Step 1 — add authored markers
+
+Tag:
+
+- the clone template
+- the clone container
+- every variable child node
+- the hidden trigger input/button pair
+
+Example:
+
+```tsx
+<div data-ak="preset-card-grid">
+  {cards.map((card) => (
+    <article key={card.id} data-ak="preset-card">
+      <h3 data-ak="preset-card-title">{card.name}</h3>
+      <span data-ak="preset-card-type">{card.mediaMode}</span>
+      <span data-ak="preset-card-variant-count">{card.variantCount}</span>
+    </article>
+  ))}
+</div>
+
+<input type="hidden" data-ak-fill-input="preset-cards" />
+<button
+  type="button"
+  style={{ display: "none" }}
+  data-ak-fill-trigger="preset-cards"
+  onClick={(e) => {
+    const input = e.currentTarget.previousElementSibling as HTMLInputElement;
+    try {
+      const parsed = JSON.parse(input.value);
+      if (Array.isArray(parsed)) setCards(parsed);
+    } catch {
+      // ignore malformed payloads
+    }
+  }}
+/>
+```
+
+## Step 2 — declare `mockDataInjection.groups`
+
+Declare groups at the top level of the preset config, not inside `program`.
+
+Each group needs:
+
+- `name`
+- `description`
+- `slots[]`
+- `defaultValues[]`
+
+Keep values realistic for the user's domain. Seed 5-10 rows when that makes
+sense.
+
+## Step 3 — emit `INJECT_MOCK_DATA`
+
+Place each `INJECT_MOCK_DATA` opcode:
+
+- after the relevant `WAIT_FOR`
+- before the relevant `CAPTURE_SCREENSHOT`
+
+Wire both clone and trigger fields whenever possible:
+
+- `containerSelector`
+- `templateSelector`
+- `slotMappings[]`
+- `inputSelector`
+- `triggerSelector`
+
+Always keep the opcode non-blocking:
+
+```json
+{
+  "postcondition": { "type": "always" },
+  "recovery": {
+    "retries": 0,
+    "useSelectorMemory": false,
+    "useAltInteraction": false,
+    "allowReload": false,
+    "allowHealer": false
+  }
+}
+```
+
+## Implementation rules
+
+- `slotMappings[].selector` is relative to the cloned template item
+- `removeTemplate: true` when the original template should disappear
+- `replaceExisting: true` on the group when placeholder content should be wiped
+- use `attribute` only when the value belongs in an attribute such as `src`
+- a group counts as applied if at least one delivery mechanism succeeds
+
+## When not to use `INJECT_MOCK_DATA`
+
+Use lower-level DOM mutation opcodes instead when the change is narrow:
+
+- `CLONE_ELEMENT`
+- `REMOVE_ELEMENT`
+- `SET_ATTRIBUTE`
+
+Reserve `INJECT_MOCK_DATA` for real structured seed-data scenarios.

package/dist/abort.d.ts

@@ -0,0 +1,5 @@
+export declare function createAbortError(message: string): Error;
+export declare function getAbortMessage(signal: AbortSignal | undefined, fallback: string): string;
+export declare function throwIfAborted(signal: AbortSignal | undefined, fallback?: string): void;
+export declare function isAbortError(error: unknown): boolean;
+export declare function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/abort.js

@@ -0,0 +1,44 @@
+export function createAbortError(message) {
+    const error = new Error(message);
+    error.name = 'AbortError';
+    return error;
+}
+export function getAbortMessage(signal, fallback) {
+    const reason = signal?.reason;
+    if (reason instanceof Error && reason.message)
+        return reason.message;
+    if (typeof reason === 'string' && reason.trim().length > 0)
+        return reason;
+    return fallback;
+}
+export function throwIfAborted(signal, fallback = 'Operation cancelled.') {
+    if (!signal?.aborted)
+        return;
+    throw createAbortError(getAbortMessage(signal, fallback));
+}
+export function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+export async function sleepWithAbort(ms, signal) {
+    if (!signal) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+        return;
+    }
+    throwIfAborted(signal);
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            cleanup();
+            reject(createAbortError(getAbortMessage(signal, 'Operation cancelled.')));
+        };
+        const cleanup = () => {
+            signal.removeEventListener('abort', onAbort);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=abort.js.map

package/dist/action-verifier.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Capture Agent — Action Verifier
+ *
+ * Post-action validation: diff AKTree before/after an action
+ * to detect whether the action had a real effect or was intercepted.
+ */
+import type { RuntimeAdapter } from './execution-types.js';
+export interface ActionVerification {
+    /** Whether the action caused a detectable change */
+    hadEffect: boolean;
+    /** What changed */
+    changes: ActionChange[];
+    /** Summary for logging */
+    summary: string;
+}
+export type ActionChangeKind = 'url_changed' | 'tree_structure_changed' | 'node_appeared' | 'node_disappeared' | 'overlay_changed' | 'no_change';
+export interface ActionChange {
+    kind: ActionChangeKind;
+    detail: string;
+}
+/**
+ * Captures AKTree state before and after an action to detect changes.
+ */
+export declare class ActionVerifier {
+    private beforeTree;
+    private beforeUrl;
+    captureBeforeState(adapter: RuntimeAdapter): Promise<void>;
+    verifyAfterAction(adapter: RuntimeAdapter): Promise<ActionVerification>;
+}

package/dist/action-verifier.js

@@ -0,0 +1,133 @@
+/**
+ * Capture Agent — Action Verifier
+ *
+ * Post-action validation: diff AKTree before/after an action
+ * to detect whether the action had a real effect or was intercepted.
+ */
+/**
+ * Captures AKTree state before and after an action to detect changes.
+ */
+export class ActionVerifier {
+    beforeTree = null;
+    beforeUrl = null;
+    async captureBeforeState(adapter) {
+        try {
+            this.beforeTree = await adapter.getAKTree();
+        }
+        catch {
+            this.beforeTree = null;
+        }
+        try {
+            this.beforeUrl = await adapter.getCurrentUrl();
+        }
+        catch {
+            this.beforeUrl = null;
+        }
+    }
+    async verifyAfterAction(adapter) {
+        if (!this.beforeTree || !this.beforeUrl) {
+            return {
+                hadEffect: true, // assume effect if no before state
+                changes: [],
+                summary: 'no before state captured, assuming action had effect',
+            };
+        }
+        let afterUrl;
+        let afterTree;
+        try {
+            [afterUrl, afterTree] = await Promise.all([
+                adapter.getCurrentUrl(),
+                adapter.getAKTree(),
+            ]);
+        }
+        catch {
+            this.beforeTree = null;
+            this.beforeUrl = null;
+            return {
+                hadEffect: true,
+                changes: [],
+                summary: 'after state unavailable, skipping AKTree effect verification',
+            };
+        }
+        const changes = [];
+        // 1. URL change
+        if (afterUrl !== this.beforeUrl) {
+            changes.push({
+                kind: 'url_changed',
+                detail: `${this.beforeUrl} -> ${afterUrl}`,
+            });
+        }
+        // 2. Overlay changes
+        const beforeOverlayCount = this.beforeTree.overlays.length;
+        const afterOverlayCount = afterTree.overlays.length;
+        if (beforeOverlayCount !== afterOverlayCount) {
+            changes.push({
+                kind: 'overlay_changed',
+                detail: `overlays: ${beforeOverlayCount} -> ${afterOverlayCount}`,
+            });
+        }
+        // 3. Tree structure diff (node count at top level)
+        const beforeNodes = countVisibleNodes(this.beforeTree.root);
+        const afterNodes = countVisibleNodes(afterTree.root);
+        if (Math.abs(beforeNodes - afterNodes) > 2) {
+            changes.push({
+                kind: 'tree_structure_changed',
+                detail: `visible nodes: ${beforeNodes} -> ${afterNodes}`,
+            });
+        }
+        // 4. Check for new visible interactive nodes (e.g., modal appeared)
+        const beforeIds = collectVisibleInteractiveIds(this.beforeTree.root);
+        const afterIds = collectVisibleInteractiveIds(afterTree.root);
+        const appeared = afterIds.filter(id => !beforeIds.includes(id));
+        const disappeared = beforeIds.filter(id => !afterIds.includes(id));
+        if (appeared.length > 0) {
+            changes.push({
+                kind: 'node_appeared',
+                detail: `${appeared.length} new interactive node(s)`,
+            });
+        }
+        if (disappeared.length > 0) {
+            changes.push({
+                kind: 'node_disappeared',
+                detail: `${disappeared.length} interactive node(s) gone`,
+            });
+        }
+        // 5. Check page title change
+        if (this.beforeTree.page.title !== afterTree.page.title) {
+            changes.push({
+                kind: 'tree_structure_changed',
+                detail: `title: "${this.beforeTree.page.title}" -> "${afterTree.page.title}"`,
+            });
+        }
+        // If no changes detected at all
+        if (changes.length === 0) {
+            changes.push({ kind: 'no_change', detail: 'no detectable changes in URL, tree, or overlays' });
+        }
+        const hadEffect = changes.some(c => c.kind !== 'no_change');
+        const summary = changes.map(c => `${c.kind}: ${c.detail}`).join('; ');
+        // Reset state
+        this.beforeTree = null;
+        this.beforeUrl = null;
+        return { hadEffect, changes, summary };
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+function countVisibleNodes(node) {
+    let count = node.visible ? 1 : 0;
+    for (const child of node.children) {
+        count += countVisibleNodes(child);
+    }
+    return count;
+}
+function collectVisibleInteractiveIds(node) {
+    const ids = [];
+    function walk(n) {
+        if (n.visible && n.interactive) {
+            ids.push(n.id);
+        }
+        n.children.forEach(walk);
+    }
+    walk(node);
+    return ids;
+}
+//# sourceMappingURL=action-verifier.js.map

package/dist/agent-action-recovery.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Action recovery, guard inference, and login detection utilities for the capture agent.
+ * Extracted from agent.ts — these are pure functions with no closure dependencies.
+ */
+import type { ExecutedAction, ActionType } from './types.js';
+export declare const META_ACTIONS: Set<ActionType>;
+export declare const BOOTSTRAP_ACTIONS: Set<ActionType>;
+export declare const REPLAYABLE_ACTIONS: ReadonlyArray<ActionType>;
+export declare function isNoEffectAction(action: ExecutedAction): boolean;
+export declare function isBootstrapStabilizationAction(action: ExecutedAction): boolean;
+export declare function hasMeaningfulBrowserAction(actionHistory: ExecutedAction[]): boolean;
+export declare function buildRecoveryActionSignature(action: ExecutedAction): string;
+export declare function isExplicitLoginAction(action: ExecutedAction): boolean;
+export declare function hasRecentExplicitLoginAction(previousActions: ExecutedAction[]): boolean;
+export declare function isLoginAction(action: ExecutedAction, previousActions?: ExecutedAction[]): boolean;
+export declare function compactReplayActions(recordedActions: ExecutedAction[], params?: {
+    currentUrl?: string;
+    targetUrl?: string;
+    currentViewport?: {
+        width: number;
+        height: number;
+    } | null;
+    isAuthenticated?: boolean;
+    ignoreRecordedViewport?: boolean;
+}): ExecutedAction[];
+export declare function countRecentNoEffectActions(actionHistory: ExecutedAction[]): number;
+export declare function shouldTriggerRecovery(actionHistory: ExecutedAction[]): boolean;
+export declare function inferPrematureGiveUpCorrection(params: {
+    reason: string;
+    actionHistory: ExecutedAction[];
+    lastVerificationFailure?: string;
+    iteration: number;
+    maxIterations: number;
+}): string | null;
+export declare function inferSearchScrollLoopGuard(params: {
+    actionHistory: ExecutedAction[];
+    action: ActionType;
+    args: Record<string, unknown>;
+}): string | null;
+export declare function inferRepeatedActionGuard(params: {
+    actionHistory: ExecutedAction[];
+    action: ActionType;
+    args: Record<string, unknown>;
+    currentUrl?: string;
+}): string | null;