autokap 1.0.6 → 1.0.8

package/dist/execution-types.js

@@ -0,0 +1,65 @@
+/**
+ * Capture Agent — IR Types
+ *
+ * All types for the compiled execution model:
+ * preset (natural language) -> ExecutionProgram (typed IR) -> deterministic runtime
+ */
+/** Sentinel value that resolves to the current variant's locale or theme at runtime */
+export const VARIANT_PLACEHOLDER = '$variant';
+// ── Opcode kinds ────────────────────────────────────────────────────
+export const OPCODE_KINDS = [
+    'NAVIGATE',
+    'DISMISS_OVERLAYS',
+    'ASSERT_ROUTE',
+    'ASSERT_SURFACE',
+    'CLICK',
+    'TYPE',
+    'PRESS_KEY',
+    'WAIT_FOR',
+    'SET_LOCALE',
+    'SET_THEME',
+    'SCROLL',
+    'CAPTURE_SCREENSHOT',
+    'CAPTURE_DOM',
+    'CAPTURE_FRAGMENT',
+    'BEGIN_CLIP',
+    'END_CLIP',
+    'HOVER',
+    'SELECT_OPTION',
+    'CHECK',
+    'DOUBLE_CLICK',
+    'CLONE_ELEMENT',
+    'INJECT_MOCK_DATA',
+    'REMOVE_ELEMENT',
+    'SET_ATTRIBUTE',
+];
+/**
+ * Soft opcodes are non-blocking — if their action or postcondition fails at
+ * runtime, the runner returns `status: 'skipped'` instead of aborting the
+ * variant. The circuit breaker is not ticked. Used by mock data injection so
+ * a missing template selector logs a warning and the capture proceeds.
+ */
+export const SOFT_OPCODE_KINDS = new Set([
+    'CLONE_ELEMENT',
+    'INJECT_MOCK_DATA',
+    'REMOVE_ELEMENT',
+    'SET_ATTRIBUTE',
+]);
+export function isSoftOpcodeKind(kind) {
+    return SOFT_OPCODE_KINDS.has(kind);
+}
+export const DEFAULT_RECOVERY_POLICY = {
+    retries: 2,
+    useSelectorMemory: true,
+    useAltInteraction: true,
+    allowReload: false,
+    allowHealer: true,
+};
+// ── Artifact spec ───────────────────────────────────────────────────
+export const MEDIA_MODES = ['screenshot', 'clip', 'dom'];
+export const DEFAULT_CIRCUIT_BREAKER = {
+    maxPerOpcode: 3,
+    maxPerPage: 5,
+    maxPerRun: 10,
+};
+//# sourceMappingURL=execution-types.js.map

package/dist/fonts-loader.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SF Pro font loader for native SVG mockup rendering.
+ *
+ * Parses the woff2 base64 data URIs from sf-pro-fonts.ts / sf-pro-symbols.ts
+ * with fontkit and caches the parsed Font instances at module level. Used by
+ * src/svg-text.ts and the SVG status bar / browser bar generators to render
+ * text as native `<path>` elements (no Playwright required).
+ */
+import type { Font } from 'fontkit';
+export type SfFontId = 'text-regular' | 'text-semibold' | 'text-bold' | 'display-regular' | 'display-semibold' | 'display-bold' | 'symbols';
+/** Get a parsed Font instance for the requested SF Pro variant. Cached. */
+export declare function getFont(id: SfFontId): Font;
+/** Resolve an SF font id from a CSS-like family + weight pair. */
+export declare function resolveFontId(family: 'text' | 'display', weight?: number | 'bold' | 'semibold' | 'regular' | 'medium' | 'normal'): SfFontId;

package/dist/fonts-loader.js

@@ -0,0 +1,55 @@
+/**
+ * SF Pro font loader for native SVG mockup rendering.
+ *
+ * Parses the woff2 base64 data URIs from sf-pro-fonts.ts / sf-pro-symbols.ts
+ * with fontkit and caches the parsed Font instances at module level. Used by
+ * src/svg-text.ts and the SVG status bar / browser bar generators to render
+ * text as native `<path>` elements (no Playwright required).
+ */
+import * as fontkit from 'fontkit';
+import { SF_PRO_TEXT_REGULAR, SF_PRO_TEXT_SEMIBOLD, SF_PRO_DISPLAY_REGULAR, SF_PRO_DISPLAY_SEMIBOLD, } from './sf-pro-fonts.js';
+import { SF_PRO_SYMBOLS } from './sf-pro-symbols.js';
+const FONT_DATA = {
+    // SF Pro "Bold" maps to "Semibold" in our subset (we don't ship a separate
+    // bold weight). Native macOS uses semibold for menu bar app names anyway.
+    'text-regular': SF_PRO_TEXT_REGULAR,
+    'text-semibold': SF_PRO_TEXT_SEMIBOLD,
+    'text-bold': SF_PRO_TEXT_SEMIBOLD,
+    'display-regular': SF_PRO_DISPLAY_REGULAR,
+    'display-semibold': SF_PRO_DISPLAY_SEMIBOLD,
+    'display-bold': SF_PRO_DISPLAY_SEMIBOLD,
+    symbols: SF_PRO_SYMBOLS,
+};
+const cache = new Map();
+function dataUriToBuffer(dataUri) {
+    const comma = dataUri.indexOf(',');
+    if (comma === -1) {
+        throw new Error('invalid font data URI');
+    }
+    const base64 = dataUri.slice(comma + 1);
+    return Buffer.from(base64, 'base64');
+}
+/** Get a parsed Font instance for the requested SF Pro variant. Cached. */
+export function getFont(id) {
+    const cached = cache.get(id);
+    if (cached)
+        return cached;
+    const buf = dataUriToBuffer(FONT_DATA[id]);
+    const parsed = fontkit.create(buf);
+    // fontkit.create can return a FontCollection, but our subsets are all
+    // single fonts.
+    if ('fonts' in parsed) {
+        throw new Error(`unexpected font collection for ${id}`);
+    }
+    cache.set(id, parsed);
+    return parsed;
+}
+/** Resolve an SF font id from a CSS-like family + weight pair. */
+export function resolveFontId(family, weight = 400) {
+    const isBoldish = weight === 'bold' ||
+        weight === 'semibold' ||
+        (typeof weight === 'number' && weight >= 600);
+    const suffix = isBoldish ? 'semibold' : 'regular';
+    return `${family}-${suffix}`;
+}
+//# sourceMappingURL=fonts-loader.js.map

package/dist/hybrid-navigator.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Hybrid Navigator — Uses the screenshot agent for navigation (Phase 1),
+ * then exports the session for video recording (Phase 2).
+ *
+ * This wrapper around `runAgent()` provides:
+ * - Agent-driven navigation with full self-healing
+ * - Session export (storageState + sessionStorage + scroll position)
+ * - Post-transfer auth detection (silent re-auth wait)
+ * - Lightweight selector pre-validation for clip plans
+ * - Fresh observation capture on recording browser
+ */
+import { Browser } from './browser.js';
+import { type VariantStateDetection } from './video-variant-state.js';
+import type { BrowserStorageState, BrowserSessionStorageState, CapturePageIdentity, ExecutedAction, InteractiveElement, LoginCredentials, StepUsage, VerificationResult, VideoPlan, VideoObservationSnapshot, VideoPageSignals, VideoStep } from './types.js';
+export interface NavigationResult {
+    success: boolean;
+    finalUrl: string;
+    scrollPosition: {
+        x: number;
+        y: number;
+    };
+    storageState?: BrowserStorageState;
+    sessionStorage?: BrowserSessionStorageState;
+    observationSummary?: string;
+    observationSnapshot?: VideoObservationSnapshot;
+    coherenceKey?: string;
+    interactiveElements?: InteractiveElement[];
+    pageIdentity?: CapturePageIdentity | null;
+    actions?: ExecutedAction[];
+    replayableActions?: ExecutedAction[];
+    verification?: VerificationResult | null;
+    verificationMode?: VerificationResult['mode'];
+    exactStartStateVerified: boolean;
+    detectedLang?: string | null;
+    detectedTheme?: 'light' | 'dark' | null;
+    pageSignals?: VideoPageSignals;
+    variantState?: VariantStateDetection;
+    error?: string;
+    usage: StepUsage[];
+}
+export interface NavigateWithAgentConfig {
+    /** Target URL — can be relative (e.g. "/docs") if baseUrl is provided. */
+    url: string;
+    /** Base URL of the project (e.g. "https://example.com"). Used to resolve relative urls. */
+    baseUrl?: string;
+    navigationPrompt: string;
+    /**
+     * When provided (two-part mode), this describes the RECORDED interaction separately
+     * from the navigation. The navigation agent only needs to know what will be recorded
+     * to stop at the right pre-recording state — it must NOT perform the recorded actions.
+     */
+    recordingScript?: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    outputScale?: number;
+    lang?: string;
+    theme?: 'light' | 'dark';
+    credentials?: LoginCredentials;
+    langInstructions?: string;
+    themeInstructions?: string;
+    navigationInstructions?: string;
+    model: string;
+    apiKey: string;
+    maxIterations?: number;
+    abortSignal?: AbortSignal;
+    onLog?: (entry: {
+        level: 'info' | 'action' | 'success' | 'error' | 'ai';
+        message: string;
+        timestamp: number;
+    }) => void;
+    onScreenshot?: (base64: string) => void;
+}
+export interface SelectorValidationResult {
+    valid: boolean;
+    missingSelectors: Array<{
+        stepIndex: number;
+        step: VideoStep;
+        selector: string;
+    }>;
+}
+export interface FreshObservationConfig {
+    url: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    outputScale?: number;
+    lang?: string;
+    theme?: 'light' | 'dark';
+    storageState?: BrowserStorageState;
+    sessionStorage?: BrowserSessionStorageState;
+    scrollPosition?: {
+        x: number;
+        y: number;
+    };
+    abortSignal?: AbortSignal;
+}
+/**
+ * Phase 1: Use the screenshot agent to navigate to a target state.
+ * Exports the full session (cookies, localStorage, sessionStorage, scroll)
+ * for reuse in the video recording phase.
+ */
+export declare function navigateWithAgent(config: NavigateWithAgentConfig): Promise<NavigationResult>;
+/**
+ * Capture a fresh observation from a browser that already has the session loaded.
+ * Use this on Browser B (recording browser) AFTER navigation, not the stale
+ * observation from Browser A (agent browser).
+ */
+export declare function captureFreshObservation(browser: Browser): Promise<string>;
+/**
+ * Capture a fresh observation by opening a temporary pool browser with the
+ * exported session. Closes the browser automatically.
+ */
+export declare function captureFreshObservationFromSession(config: FreshObservationConfig): Promise<string>;
+/**
+ * After transferring session to a new browser context, detect if the page
+ * ended up in a logged-out state (e.g., due to IndexedDB/in-memory JWT loss).
+ * If detected, waits for silent re-auth to complete.
+ *
+ * Returns true if auth is confirmed or no auth issues detected.
+ */
+export declare function waitForAuthStabilization(browser: Browser, options?: {
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+/**
+ * Validate selectors in a plan that can be checked on the current page.
+ *
+ * Only validates selectors up to the first page-mutating step (click, hover,
+ * type, select_option, key). After such a step the DOM changes and later
+ * selectors cannot be verified without actually executing the plan.
+ */
+export declare function validatePlanSelectors(browser: Browser, plan: VideoPlan): Promise<SelectorValidationResult>;
+export declare function buildNavigationPrompt(resolvedUrl: string, config: NavigateWithAgentConfig): string;