autokap 1.1.4 → 1.1.6

package/dist/v2/schema.js

@@ -1,295 +0,0 @@
-/**
- * Capture Agent — Zod Validation Schemas
- *
- * Validates ExecutionProgram at compile output (server) and CLI input boundaries.
- */
-import { z } from 'zod';
-// ── Postcondition ───────────────────────────────────────────────────
-export const PostconditionSpecSchema = z.object({
-    type: z.enum([
-        'route_matches',
-        'element_visible',
-        'element_absent',
-        'text_contains',
-        'overlay_dismissed',
-        'screenshot_stable',
-        'any_change',
-        'always',
-    ]),
-    pattern: z.string().optional(),
-    selector: z.string().optional(),
-    text: z.string().optional(),
-    threshold: z.number().min(0).max(1).optional(),
-    waitMs: z.number().int().positive().optional(),
-}).superRefine((value, ctx) => {
-    if (value.type === 'route_matches' && !value.pattern) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: 'route_matches postconditions require `pattern`',
-            path: ['pattern'],
-        });
-    }
-    if (['element_visible', 'element_absent', 'text_contains'].includes(value.type) && !value.selector) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `${value.type} postconditions require \`selector\``,
-            path: ['selector'],
-        });
-    }
-    if (value.type === 'text_contains' && !value.text) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: 'text_contains postconditions require `text`',
-            path: ['text'],
-        });
-    }
-});
-// ── Recovery policy ─────────────────────────────────────────────────
-export const RecoveryPolicySchema = z.object({
-    retries: z.number().int().min(0).max(10),
-    useSelectorMemory: z.boolean(),
-    useAltInteraction: z.boolean(),
-    allowReload: z.boolean(),
-    allowHealer: z.boolean(),
-});
-// ── Opcode base fields ──────────────────────────────────────────────
-const opcodeBase = {
-    description: z.string().min(1),
-    postcondition: PostconditionSpecSchema,
-    recovery: RecoveryPolicySchema,
-    timeoutMs: z.number().int().positive(),
-    maxFailures: z.number().int().positive(),
-};
-// ── Individual opcode schemas ───────────────────────────────────────
-const NavigateOpcodeSchema = z.object({
-    kind: z.literal('NAVIGATE'),
-    ...opcodeBase,
-    url: z.string().min(1),
-});
-const DismissOverlaysOpcodeSchema = z.object({
-    kind: z.literal('DISMISS_OVERLAYS'),
-    ...opcodeBase,
-});
-const AssertRouteOpcodeSchema = z.object({
-    kind: z.literal('ASSERT_ROUTE'),
-    ...opcodeBase,
-    urlPattern: z.string().min(1),
-});
-const AssertSurfaceOpcodeSchema = z.object({
-    kind: z.literal('ASSERT_SURFACE'),
-    ...opcodeBase,
-    selectors: z.array(z.string().min(1)).min(1),
-    matchAll: z.boolean(),
-});
-const SemanticTargetSchema = z.object({
-    text: z.string().optional(),
-    role: z.string().optional(),
-    label: z.string().optional(),
-    near: z.string().optional(),
-    placeholder: z.string().optional(),
-    exact: z.boolean().optional(),
-}).refine((value) => Boolean(value.text || value.role || value.label || value.near || value.placeholder), 'semantic targets need at least one identifying field');
-const ClickOpcodeSchema = z.object({
-    kind: z.literal('CLICK'),
-    ...opcodeBase,
-    selector: z.string().min(1),
-    target: SemanticTargetSchema.optional(),
-    fingerprint: z.string().optional(),
-    selectorAlternates: z.array(z.string().min(1)).optional(),
-});
-const TypeOpcodeSchema = z.object({
-    kind: z.literal('TYPE'),
-    ...opcodeBase,
-    selector: z.string().min(1),
-    target: SemanticTargetSchema.optional(),
-    text: z.string(),
-    clearFirst: z.boolean(),
-    fingerprint: z.string().optional(),
-    selectorAlternates: z.array(z.string().min(1)).optional(),
-});
-const PressKeyOpcodeSchema = z.object({
-    kind: z.literal('PRESS_KEY'),
-    ...opcodeBase,
-    key: z.string().min(1),
-});
-const WaitForOpcodeSchema = z.object({
-    kind: z.literal('WAIT_FOR'),
-    ...opcodeBase,
-    selector: z.string().min(1).optional(),
-    target: SemanticTargetSchema.optional(),
-    state: z.enum(['visible', 'attached']),
-}).superRefine((value, ctx) => {
-    if (!value.selector && !value.target) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: 'WAIT_FOR requires either `selector` or `target`',
-            path: ['selector'],
-        });
-    }
-});
-const storageHintSchema = z.object({
-    storage: z.enum(['localStorage', 'sessionStorage']),
-    key: z.string().min(1),
-    value: z.string(),
-});
-const SetLocaleOpcodeSchema = z.object({
-    kind: z.literal('SET_LOCALE'),
-    ...opcodeBase,
-    locale: z.string().min(1),
-    method: z.enum(['browser_context', 'ui_interaction', 'storage']),
-    selector: z.string().optional(),
-    storageHints: z.array(storageHintSchema).optional(),
-}).superRefine((value, ctx) => {
-    if (value.method === 'ui_interaction' && !value.selector) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: 'SET_LOCALE with `ui_interaction` requires `selector`',
-            path: ['selector'],
-        });
-    }
-    if (value.method === 'storage' && (!value.storageHints || value.storageHints.length === 0)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: 'SET_LOCALE with `storage` requires at least one `storageHints` entry',
-            path: ['storageHints'],
-        });
-    }
-});
-const SetThemeOpcodeSchema = z.object({
-    kind: z.literal('SET_THEME'),
-    ...opcodeBase,
-    theme: z.enum(['light', 'dark']),
-    method: z.enum(['color_scheme', 'ui_interaction', 'storage']),
-    selector: z.string().optional(),
-    storageHints: z.array(storageHintSchema).optional(),
-}).superRefine((value, ctx) => {
-    if (value.method === 'ui_interaction' && !value.selector) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: 'SET_THEME with `ui_interaction` requires `selector`',
-            path: ['selector'],
-        });
-    }
-    if (value.method === 'storage' && (!value.storageHints || value.storageHints.length === 0)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: 'SET_THEME with `storage` requires at least one `storageHints` entry',
-            path: ['storageHints'],
-        });
-    }
-});
-const ScrollOpcodeSchema = z.object({
-    kind: z.literal('SCROLL'),
-    ...opcodeBase,
-    direction: z.enum(['up', 'down', 'left', 'right']),
-    amount: z.number().int().positive().optional(),
-    targetSelector: z.string().optional(),
-    target: SemanticTargetSchema.optional(),
-});
-const CaptureScreenshotOpcodeSchema = z.object({
-    kind: z.literal('CAPTURE_SCREENSHOT'),
-    ...opcodeBase,
-    captureId: z.string().optional(),
-    captureName: z.string().optional(),
-    elementSelector: z.string().optional(),
-});
-const BeginClipOpcodeSchema = z.object({
-    kind: z.literal('BEGIN_CLIP'),
-    ...opcodeBase,
-    clipId: z.string().optional(),
-    clipName: z.string().optional(),
-});
-const EndClipOpcodeSchema = z.object({
-    kind: z.literal('END_CLIP'),
-    ...opcodeBase,
-    clipId: z.string().optional(),
-    clipName: z.string().optional(),
-});
-// ── Discriminated union ─────────────────────────────────────────────
-export const ExecutionOpcodeSchema = z.discriminatedUnion('kind', [
-    NavigateOpcodeSchema,
-    DismissOverlaysOpcodeSchema,
-    AssertRouteOpcodeSchema,
-    AssertSurfaceOpcodeSchema,
-    ClickOpcodeSchema,
-    TypeOpcodeSchema,
-    PressKeyOpcodeSchema,
-    WaitForOpcodeSchema,
-    SetLocaleOpcodeSchema,
-    SetThemeOpcodeSchema,
-    ScrollOpcodeSchema,
-    CaptureScreenshotOpcodeSchema,
-    BeginClipOpcodeSchema,
-    EndClipOpcodeSchema,
-]);
-// ── Variant & precondition ──────────────────────────────────────────
-export const VariantSpecSchema = z.object({
-    id: z.string().min(1),
-    viewport: z.object({
-        width: z.number().int().positive(),
-        height: z.number().int().positive(),
-    }),
-    deviceScaleFactor: z.number().positive().optional(),
-    locale: z.string().optional(),
-    theme: z.enum(['light', 'dark']).optional(),
-    targetId: z.string().optional(),
-    targetLabel: z.string().optional(),
-    deviceFrame: z.string().optional(),
-});
-const cookieSchema = z.object({
-    name: z.string().min(1),
-    value: z.string(),
-    domain: z.string().min(1),
-    path: z.string().optional(),
-});
-export const PreconditionSpecSchema = z.object({
-    auth: z.enum(['authenticated', 'anonymous', 'any']),
-    credentialsId: z.string().optional(),
-    storageState: z.any().optional(),
-    sessionStorage: z.record(z.string(), z.record(z.string(), z.string())).optional(),
-    cookies: z.array(cookieSchema).optional(),
-});
-// ── Artifact spec ───────────────────────────────────────────────────
-export const ArtifactSpecSchema = z.object({
-    mediaMode: z.enum(['screenshot', 'clip']),
-    format: z.object({
-        clipFormat: z.enum(['gif', 'mp4', 'both']).optional(),
-        screenshotFormat: z.enum(['png', 'jpeg']).optional(),
-    }).optional(),
-    cursorTheme: z.enum(['minimal', 'macos', 'windows']).optional(),
-    applyMockup: z.boolean().optional(),
-    applyStatusBar: z.boolean().optional(),
-});
-// ── Full program ────────────────────────────────────────────────────
-export const ExecutionProgramSchema = z.object({
-    presetId: z.string().min(1),
-    programVersion: z.number().int().positive(),
-    mediaMode: z.enum(['screenshot', 'clip']),
-    baseUrl: z.string().url(),
-    variants: z.array(VariantSpecSchema).min(1),
-    preconditions: PreconditionSpecSchema,
-    steps: z.array(ExecutionOpcodeSchema).min(1),
-    artifactPlan: ArtifactSpecSchema,
-    compileFingerprint: z.string().min(1),
-    compiledAt: z.string().datetime(),
-    compiledWith: z.string().optional(),
-});
-// ── Healer patch ────────────────────────────────────────────────────
-export const HealerPatchSchema = z.object({
-    opcodeIndex: z.number().int().min(0),
-    originalOpcode: ExecutionOpcodeSchema,
-    replacementOpcodes: z.array(ExecutionOpcodeSchema).min(1).max(3),
-    reason: z.string().min(1),
-    patchedAt: z.string().datetime(),
-});
-// ── Typed parse helpers ─────────────────────────────────────────────
-export function parseProgram(data) {
-    return ExecutionProgramSchema.parse(data);
-}
-export function parseOpcode(data) {
-    return ExecutionOpcodeSchema.parse(data);
-}
-export function safeParseProgramResult(data) {
-    return ExecutionProgramSchema.safeParse(data);
-}
-//# sourceMappingURL=schema.js.map

package/dist/v2/selector-resolver.d.ts

@@ -1,34 +0,0 @@
-/**
- * Capture Agent — Selector Resolver
- *
- * Progressive selector resolution for opcodes that target elements:
- * 1. Primary selector from compiled program
- * 2. AKTree fingerprint match
- * 3. Selector memory candidates (from Supabase)
- * 4. Fuzzy text match on AKTree nodes
- */
-import type { RuntimeAdapter } from './types.js';
-export interface ResolvedSelector {
-    selector: string;
-    strategy: 'primary' | 'fingerprint' | 'memory' | 'fuzzy_text' | 'alternate';
-    confidence: 'high' | 'medium' | 'low';
-}
-export interface SelectorResolverOptions {
-    /** Primary selector from the compiled opcode */
-    primary: string;
-    /** AKTree fingerprint for fuzzy matching */
-    fingerprint?: string;
-    /** Alternative selectors from the compiled opcode */
-    alternates?: string[];
-    /** Selector memory map: stepSignature -> known-good selectors */
-    selectorMemory?: Record<string, string[]>;
-    /** Step signature for memory lookup */
-    stepSignature?: string;
-    /** Human-readable description of the target element (for fuzzy matching) */
-    description?: string;
-}
-/**
- * Resolves a selector by trying multiple strategies in order.
- * Returns the first working selector, or null if nothing matches.
- */
-export declare function resolveSelector(adapter: RuntimeAdapter, options: SelectorResolverOptions): Promise<ResolvedSelector | null>;

package/dist/v2/selector-resolver.js

@@ -1,181 +0,0 @@
-/**
- * Capture Agent — Selector Resolver
- *
- * Progressive selector resolution for opcodes that target elements:
- * 1. Primary selector from compiled program
- * 2. AKTree fingerprint match
- * 3. Selector memory candidates (from Supabase)
- * 4. Fuzzy text match on AKTree nodes
- */
-/**
- * Resolves a selector by trying multiple strategies in order.
- * Returns the first working selector, or null if nothing matches.
- */
-export async function resolveSelector(adapter, options) {
-    const tree = await adapter.getAKTree();
-    // 1. Try primary selector
-    if (await selectorExists(adapter, options.primary)) {
-        return { selector: options.primary, strategy: 'primary', confidence: 'high' };
-    }
-    // 2. Try alternate selectors
-    if (options.alternates) {
-        for (const alt of options.alternates) {
-            if (await selectorExists(adapter, alt)) {
-                return { selector: alt, strategy: 'alternate', confidence: 'high' };
-            }
-        }
-    }
-    // 3. Try fingerprint match in AKTree
-    if (options.fingerprint) {
-        const match = findNodeByFingerprint(tree, options.fingerprint);
-        if (match) {
-            return { selector: match, strategy: 'fingerprint', confidence: 'medium' };
-        }
-    }
-    // 4. Try selector memory
-    if (options.selectorMemory && options.stepSignature) {
-        const candidates = options.selectorMemory[options.stepSignature];
-        if (candidates) {
-            for (const candidate of candidates) {
-                if (await selectorExists(adapter, candidate)) {
-                    return { selector: candidate, strategy: 'memory', confidence: 'medium' };
-                }
-            }
-        }
-    }
-    // 5. Try fuzzy text match
-    if (options.description) {
-        const match = findNodeByFuzzyText(tree, options.description);
-        if (match) {
-            return { selector: match, strategy: 'fuzzy_text', confidence: 'low' };
-        }
-    }
-    return null;
-}
-// ── Helpers ─────────────────────────────────────────────────────────
-async function selectorExists(adapter, selector) {
-    try {
-        const found = await adapter.waitFor({
-            selector,
-            state: 'attached',
-            timeoutMs: 2000,
-        });
-        return found;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Finds an AKTree node whose sourceRef/attributes match a fingerprint string.
- * Returns a CSS selector that can be used to interact with the element.
- */
-function findNodeByFingerprint(tree, fingerprint) {
-    const parts = fingerprint.split(':');
-    // Fingerprint format: "type:label:context" e.g. "button:submit:login-form"
-    const [expectedType, expectedLabel, expectedContext] = parts;
-    let bestMatch = null;
-    let bestScore = 0;
-    function walk(node) {
-        if (!node.visible || !node.interactive) {
-            node.children.forEach(walk);
-            return;
-        }
-        let score = 0;
-        // Match type
-        if (expectedType && node.type === expectedType)
-            score += 3;
-        // Match label (fuzzy)
-        if (expectedLabel) {
-            const nodeLabelLower = node.label.toLowerCase();
-            const expectedLabelLower = expectedLabel.toLowerCase();
-            if (nodeLabelLower === expectedLabelLower)
-                score += 5;
-            else if (nodeLabelLower.includes(expectedLabelLower))
-                score += 3;
-            else if (expectedLabelLower.includes(nodeLabelLower))
-                score += 1;
-        }
-        // Match context (check sourceRef)
-        if (expectedContext && node.sourceRef.toLowerCase().includes(expectedContext.toLowerCase())) {
-            score += 2;
-        }
-        if (score > bestScore) {
-            bestScore = score;
-            bestMatch = node;
-        }
-        node.children.forEach(walk);
-    }
-    walk(tree.root);
-    if (bestMatch && bestScore >= 4) {
-        return buildSelectorFromNode(bestMatch);
-    }
-    return null;
-}
-/**
- * Finds a visible interactive node by fuzzy text matching against the description.
- */
-function findNodeByFuzzyText(tree, description) {
-    const descTokens = tokenize(description);
-    if (descTokens.length === 0)
-        return null;
-    let bestMatch = null;
-    let bestOverlap = 0;
-    function walk(node) {
-        if (!node.visible || !node.interactive) {
-            node.children.forEach(walk);
-            return;
-        }
-        const nodeTokens = tokenize(node.label);
-        const overlap = countOverlap(descTokens, nodeTokens);
-        if (overlap > bestOverlap) {
-            bestOverlap = overlap;
-            bestMatch = node;
-        }
-        node.children.forEach(walk);
-    }
-    walk(tree.root);
-    // Require at least 2 token overlap or >50% match
-    if (bestMatch && (bestOverlap >= 2 || bestOverlap / descTokens.length > 0.5)) {
-        return buildSelectorFromNode(bestMatch);
-    }
-    return null;
-}
-function buildSelectorFromNode(node) {
-    // Try to build the most specific selector from node attributes
-    const ref = node.sourceRef;
-    // Extract data-testid
-    const testIdMatch = ref.match(/data-testid="([^"]+)"/);
-    if (testIdMatch)
-        return `[data-testid="${testIdMatch[1]}"]`;
-    // Extract id
-    const idMatch = ref.match(/ id="([^"]+)"/);
-    if (idMatch)
-        return `#${idMatch[1]}`;
-    // Extract tag + role + text
-    const tagMatch = ref.match(/^<(\w+)/);
-    const tag = tagMatch?.[1] ?? '*';
-    const role = node.attributes['role'];
-    if (role) {
-        return `${tag}[role="${role}"]`;
-    }
-    // Fallback: use AKNode id as a CSS selector via data attribute
-    if (node.id) {
-        return `[data-ak-id="${node.id}"]`;
-    }
-    return `${tag}:has-text("${escapeText(node.label.slice(0, 50))}")`;
-}
-function tokenize(text) {
-    return text
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter(t => t.length >= 2);
-}
-function countOverlap(a, b) {
-    const setB = new Set(b);
-    return a.filter(t => setB.has(t)).length;
-}
-function escapeText(text) {
-    return text.replace(/"/g, '\\"').replace(/\n/g, ' ');
-}
-//# sourceMappingURL=selector-resolver.js.map

package/dist/v2/semantic-resolver.d.ts

@@ -1,35 +0,0 @@
-/**
- * Capture Agent — Semantic Target Resolver
- *
- * Resolves a SemanticTarget to a concrete Playwright locator.
- * This is the core mechanism that allows opcodes to work WITHOUT CSS selectors.
- *
- * Resolution cascade:
- * 1. CSS selector (if provided, fast path)
- * 2. Playwright semantic locators (getByRole, getByText, getByLabel, getByPlaceholder)
- * 3. Selector alternates
- * 4. Composite: role + name + near (for disambiguation)
- *
- * All resolution happens via Playwright's built-in locator API — no AKTree needed.
- */
-import type { Page, Locator } from 'playwright';
-import type { SemanticTarget } from './types.js';
-export interface ResolvedTarget {
-    locator: Locator;
-    method: 'selector' | 'role' | 'text' | 'label' | 'placeholder' | 'alternate' | 'composite';
-}
-export interface ResolveOptions {
-    /** Primary CSS selector */
-    selector?: string;
-    /** Semantic target description */
-    target?: SemanticTarget;
-    /** Fallback selectors */
-    selectorAlternates?: string[];
-    /** Timeout for visibility check (ms). Default: 3000 */
-    timeoutMs?: number;
-}
-/**
- * Resolves an element on the page using the best available method.
- * Returns the first visible locator found, or null if nothing matches.
- */
-export declare function resolveTarget(page: Page, options: ResolveOptions): Promise<ResolvedTarget | null>;