@tangle-network/browser-agent-driver 0.33.2 → 0.34.0

package/dist/types/actions.d.ts

@@ -0,0 +1,241 @@
+export interface ClickAction {
+    action: 'click';
+    selector: string;
+}
+export interface TypeAction {
+    action: 'type';
+    selector: string;
+    text: string;
+}
+export interface ScrollAction {
+    action: 'scroll';
+    direction: 'up' | 'down';
+    /** Scroll distance in pixels (default: 500) */
+    amount?: number;
+    /** Optional selector for scrolling a specific container (default: viewport) */
+    selector?: string;
+}
+export interface NavigateAction {
+    action: 'navigate';
+    url: string;
+}
+export interface WaitAction {
+    action: 'wait';
+    ms: number;
+}
+export interface CompleteAction {
+    action: 'complete';
+    result: string;
+}
+export interface PressAction {
+    action: 'press';
+    selector: string;
+    key: string;
+}
+export interface HoverAction {
+    action: 'hover';
+    selector: string;
+}
+export interface SelectAction {
+    action: 'select';
+    selector: string;
+    value: string;
+}
+export interface EvaluateAction {
+    action: 'evaluate';
+    criteria: string;
+}
+export interface RunScriptAction {
+    action: 'runScript';
+    /** JavaScript expression to evaluate in page context */
+    script: string;
+}
+/**
+ * Extract a numbered, text-rich index of elements matching a CSS
+ * selector. Returns the visible textContent + tag + key attributes + a stable
+ * selector for each match. The agent then picks elements by index in the next
+ * turn (e.g., complete with `result: extracted[3].text`).
+ *
+ * The agent gets a broad selector (e.g. `'p, span, dd, code'`) and reads the
+ * actual text content of every match. Pick-by-content is more reliable than
+ * selector-by-name on pages where data lives in `<dl>/<dt>/<dd>/<code>/<pre>`
+ * or inside obscure wrapper divs.
+ *
+ * Example payload for npm weekly downloads:
+ *   {
+ *     action: 'extractWithIndex',
+ *     query: 'p, span, strong',
+ *     contains: 'downloads',
+ *   }
+ *
+ * Optional `contains` filters matches to only those containing the substring
+ * (case-insensitive). Without `contains`, all matches are returned (capped at
+ * 80 to keep the response readable).
+ */
+export interface ExtractWithIndexAction {
+    action: 'extractWithIndex';
+    /** CSS selector — broad selectors are fine, the response includes full text per match */
+    query: string;
+    /** Optional substring filter (case-insensitive) applied to textContent */
+    contains?: string;
+}
+export interface VerifyPreviewAction {
+    action: 'verifyPreview';
+}
+export interface AbortAction {
+    action: 'abort';
+    reason: string;
+}
+/**
+ * Multi-field form fill — fill N fields, select N dropdowns, and check N
+ * checkboxes in a SINGLE action. Replaces the click+type+click+type pattern
+ * that takes one turn per field.
+ *
+ * Example payload for a 5-field form:
+ *   {
+ *     action: 'fill',
+ *     fields: { '@t1': 'Jordan', '@t2': 'Rivera', '@t3': 'jordan@example.com' },
+ *     selects: { '@s1': 'WA' },
+ *     checks: ['@c1', '@c2'],
+ *   }
+ *
+ * Each entry runs in order. Failures bail with the first error and report
+ * which field failed so the agent can recover by switching to single-step
+ * actions on the next turn.
+ */
+export interface BatchFillAction {
+    action: 'fill';
+    /** Map of @ref → text value to type into each field */
+    fields?: Record<string, string>;
+    /** Map of @ref → option value or label for select dropdowns */
+    selects?: Record<string, string>;
+    /** Array of @refs to check (checkboxes / radios) */
+    checks?: string[];
+}
+/**
+ * Sequential clicks on a known set of refs. For multi-step UI navigation
+ * where the agent has identified the click chain ahead of time (e.g., open
+ * menu → click submenu → click item).
+ *
+ * Each click runs in order with an optional interval. Failures bail with
+ * the first error.
+ */
+export interface ClickSequenceAction {
+    action: 'clickSequence';
+    /** Array of @refs to click in order */
+    refs: string[];
+    /** Optional wait between clicks in ms (default: 100) */
+    intervalMs?: number;
+}
+export interface ClickAtAction {
+    action: 'clickAt';
+    /** X coordinate in virtual screen space (0-1024) */
+    x: number;
+    /** Y coordinate in virtual screen space (0-768) */
+    y: number;
+}
+export interface TypeAtAction {
+    action: 'typeAt';
+    /** X coordinate in virtual screen space (0-1024) */
+    x: number;
+    /** Y coordinate in virtual screen space (0-768) */
+    y: number;
+    /** Text to type after clicking */
+    text: string;
+}
+export interface ClickLabelAction {
+    action: 'clickLabel';
+    /** Label number from the SoM overlay (e.g., 3 for element [3]) */
+    label: number;
+}
+export interface TypeLabelAction {
+    action: 'typeLabel';
+    /** Label number from the SoM overlay */
+    label: number;
+    /** Text to type after clicking */
+    text: string;
+}
+/**
+ * Invoke a named macro defined in `skills/macros/<name>.json`. The macro
+ * expands into a sequence of existing primitive actions. The driver
+ * executes each step in order; the first failure aborts the macro and its
+ * error is surfaced as the macro's ActionResult error.
+ *
+ * Macros are flat (cannot call other macros) to keep dispatch bounded and
+ * to avoid cycles. They receive arguments via `args`, which is substituted
+ * into `${paramName}` placeholders in each step's string fields.
+ */
+export interface MacroAction {
+    action: 'macro';
+    /** Macro name, matches a registered MacroDefinition */
+    name: string;
+    /** Arguments to interpolate into the macro's steps. Optional when the
+     *  macro has no declared parameters. */
+    args?: Record<string, string>;
+}
+/**
+ * Mid-run parallel fan-out. Spawns N sub-agents in fresh tabs,
+ * each with its own URL + goal, collects the results as structured
+ * feedback. Used when the agent sees "10 candidates, investigate each
+ * in parallel" — search result fan-out, roster screening, N-way
+ * comparison shopping, etc.
+ *
+ * Each sub-goal runs in an isolated tab sharing the parent context
+ * (cookies, localStorage) but not the parent page's live state. Results
+ * are merged and injected back as agent feedback so the outer goal
+ * continues with the enriched data.
+ */
+export interface FanOutAction {
+    action: 'fanOut';
+    /**
+     * Explicit sub-goals. Use when each branch needs a different URL
+     * or fundamentally different instruction. Mutually exclusive with
+     * the (baseUrl, goalTemplate, items) shorthand below.
+     */
+    subGoals?: Array<{
+        /** Starting URL for this branch. */
+        url: string;
+        /** Natural-language goal for this branch. */
+        goal: string;
+        /** Human-readable label rendered in the overlay + feedback. */
+        label?: string;
+        /** Max turns for this sub-agent. Default: 8. */
+        maxTurns?: number;
+    }>;
+    /**
+     * Shorthand for batch-shaped fanOuts. Lets the agent emit a tiny JSON
+     * object (one baseUrl, one template, an array of string items) that
+     * the runtime expands into full subGoals. This is the PREFERRED shape
+     * for N>3 branches — it keeps the LLM's JSON output minimal and
+     * escape-free, which meaningfully improves reliability (long nested
+     * subGoals arrays cause JSON parse failures in practice).
+     *
+     * Example:
+     *   {
+     *     "action": "fanOut",
+     *     "baseUrl": "https://sanctionssearch.ofac.treas.gov/",
+     *     "goalTemplate": "Screen {item} on OFAC SDN. Report CLEARED / POSITIVE MATCH with program / NEEDS REVIEW.",
+     *     "items": ["SMITH JOHN", "MADURO NICOLAS", "AL-ASSAD BASHAR"]
+     *   }
+     *
+     * Expanded to:
+     *   subGoals: [
+     *     { url: baseUrl, goal: "Screen SMITH JOHN on OFAC SDN. ...", label: "SMITH JOHN" },
+     *     { url: baseUrl, goal: "Screen MADURO NICOLAS on OFAC SDN. ...", label: "MADURO NICOLAS" },
+     *     ...
+     *   ]
+     *
+     * `{item}` in goalTemplate is replaced with each array entry verbatim.
+     * The label is the item itself.
+     */
+    baseUrl?: string;
+    goalTemplate?: string;
+    items?: string[];
+    /**
+     * Optional guidance on how to combine sub-results when they return.
+     * Default: serialize as a JSON array with {label, verdict} entries.
+     */
+    summarize?: string;
+}
+export type Action = ClickAction | TypeAction | PressAction | HoverAction | SelectAction | ScrollAction | NavigateAction | WaitAction | EvaluateAction | RunScriptAction | ExtractWithIndexAction | VerifyPreviewAction | CompleteAction | AbortAction | BatchFillAction | ClickSequenceAction | ClickAtAction | TypeAtAction | ClickLabelAction | TypeLabelAction | MacroAction | FanOutAction;
+//# sourceMappingURL=actions.d.ts.map

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

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

package/dist/types/actions.js

@@ -0,0 +1,5 @@
+// ============================================================================
+// Actions - What the agent can do
+// ============================================================================
+export {};
+//# sourceMappingURL=actions.js.map

package/dist/types/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/types/actions.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kCAAkC;AAClC,+EAA+E"}

package/dist/types/config.d.ts

@@ -0,0 +1,211 @@
+import type { Action } from './actions.js';
+import type { ReplayConfig } from '../runner/replay/contracts.js';
+export interface AgentConfig {
+    /** LLM provider: 'openai' (default), 'anthropic', 'google', 'cli-bridge', 'codex-cli', 'claude-code', 'sandbox-backend', or 'zai-coding-plan' */
+    provider?: 'openai' | 'anthropic' | 'google' | 'cli-bridge' | 'codex-cli' | 'claude-code' | 'sandbox-backend' | 'zai-coding-plan';
+    /** LLM model (default: gpt-5.4) */
+    model?: string;
+    /** Enable adaptive model routing for decide() (default: false) */
+    adaptiveModelRouting?: boolean;
+    /** Fast navigation model used when adaptive routing is enabled */
+    navModel?: string;
+    /** Provider for navModel (defaults to provider) */
+    navProvider?: 'openai' | 'anthropic' | 'google' | 'cli-bridge' | 'codex-cli' | 'claude-code' | 'sandbox-backend' | 'zai-coding-plan';
+    /** Per-role model overrides. Each role falls back to the main model/provider. */
+    models?: {
+        /** Planner — needs best reasoning. Default: main model. */
+        planner?: {
+            model: string;
+            provider?: string;
+        };
+        /** Executor — follows plans, can be cheap. Default: navModel or main model. */
+        executor?: {
+            model: string;
+            provider?: string;
+        };
+        /** Verifier — structured yes/no. Default: navModel or main model. */
+        verifier?: {
+            model: string;
+            provider?: string;
+        };
+        /** Supervisor — strategic recovery. Default: main model. */
+        supervisor?: {
+            model: string;
+            provider?: string;
+        };
+    };
+    /** API key (defaults to OPENAI_API_KEY) */
+    apiKey?: string;
+    /** Custom API base URL (for LiteLLM, local models, etc.) */
+    baseUrl?: string;
+    /** Native sidecar backend type when using provider='sandbox-backend' */
+    sandboxBackendType?: string;
+    /** Optional sidecar backend profile/preset identifier */
+    sandboxBackendProfile?: string;
+    /** Optional native backend model provider (mainly for opencode) */
+    sandboxBackendProvider?: string;
+    /** Optional override for the default browser-agent system prompt */
+    systemPrompt?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Enable vision/multimodal (screenshots sent to LLM). Default: true */
+    vision?: boolean;
+    /** Vision policy: always, never, or auto-escalate on ambiguous/stalled states */
+    visionStrategy?: 'always' | 'never' | 'auto';
+    /** Observation mode — 'dom' (default), 'vision', or 'hybrid' */
+    observationMode?: 'dom' | 'vision' | 'hybrid';
+    /**
+     * Force `streamingInput: 'always'` on the `claude-code` provider (default:
+     * false). The Claude Code SDK omits image parts unless streaming input is
+     * enabled, so a `completeVision` round-trip through `claude-code` silently
+     * drops its screenshots without this. Set ONLY by the vision-judge wiring
+     * (`buildVisionModels`), whose Brains exist solely to send images — every
+     * other claude-code path is left on the default single-shot prompt and is
+     * unaffected. Ignored for non-`claude-code` providers.
+     */
+    claudeCodeStreamingInput?: boolean;
+    /** Max conversation history turns to keep (default: 10) */
+    maxHistoryTurns?: number;
+    /** Number of retries on transient failures (default: 3) */
+    retries?: number;
+    /** Delay between retries in ms (default: 1000) */
+    retryDelayMs?: number;
+    /** Minimum quality score (1-10) for auto-evaluate on complete. 0 = skip. */
+    qualityThreshold?: number;
+    /** Timeout per LLM request in ms (default: 60000) */
+    llmTimeoutMs?: number;
+    /** Use a lower-token prompt/snapshot strategy on the first turn */
+    compactFirstTurn?: boolean;
+    /** Verify goal completion before accepting 'complete' action (default: true) */
+    goalVerification?: boolean;
+    /** Enable trajectory scoring when selecting reference traces (default: false) */
+    traceScoring?: boolean;
+    /** Retention window for trajectory scoring in days (default: 30) */
+    traceTtlDays?: number;
+    /** Optional micro-planning: execute small follow-up actions within a turn */
+    microPlan?: MicroPlanConfig;
+    /**
+     * Plan-then-execute. When true, BrowserAgent.run() makes a single
+     * `Brain.plan()` LLM call up front, then executes the plan steps
+     * deterministically without re-entering the LLM until verification fails.
+     * On the first plan deviation, the runner falls back to the existing
+     * per-action observe→decide→execute loop with a [REPLAN] hint injected.
+     *
+     * Default: false (per-action loop only). Set to true to enable the planner.
+     * Disable via BAD_PLANNER=0 env override.
+     */
+    plannerEnabled?: boolean;
+    /**
+     * Planner routing policy. `always` uses the planner whenever plannerEnabled
+     * is true. `auto` routes extraction-style tasks through the per-action
+     * observe→act loop.
+     */
+    plannerMode?: 'always' | 'auto';
+    /** Extra wait before the planner's initial observe, in ms. Default: 0. */
+    initialObserveSettleMs?: number;
+    /**
+     * ZERO-LLM workflow replay. When `enabled`, a strict-matched prior successful
+     * trajectory is re-executed verbatim against the live page before the normal
+     * loop; a self-heal abort falls through to per-action mode. OPT-IN (default
+     * off / `--replay`) per experiment discipline. See src/runner/replay.
+     */
+    replay?: ReplayConfig;
+    /** Optional scout that ranks ambiguous link choices before the actor decides */
+    scout?: ScoutConfig;
+    /** Optional supervisor that can intervene when the run is hard-stalled */
+    supervisor?: SupervisorConfig;
+    /** Runtime observability artifacts (console/network/trace) */
+    observability?: ObservabilityConfig;
+    /** Enable DeFi/crypto app awareness in the brain (auto-set when wallet mode is active) */
+    walletMode?: boolean;
+    /** Wallet address (hex, with 0x prefix) — used for RPC interception calldata matching */
+    walletAddress?: string;
+    /** CAPTCHA solving using LLM vision (screenshot + model identifies tiles to click) */
+    captcha?: {
+        enabled?: boolean;
+        /** Max solve attempts per encounter (default: 5) */
+        maxAttempts?: number;
+    };
+    /** Parallel tab execution for compound goals */
+    parallelTabs?: {
+        /** Enable goal decomposition + parallel tab execution (default: false) */
+        enabled?: boolean;
+        /** Max parallel tabs (default: 3) */
+        maxTabs?: number;
+    };
+    /** Override token budget (used internally by parallel runner to split budget) */
+    tokenBudget?: number;
+}
+export interface ObservabilityConfig {
+    /** Enable runtime observability artifacts (default: true) */
+    enabled?: boolean;
+    /** Capture browser console warnings/errors and page errors (default: true) */
+    captureConsole?: boolean;
+    /** Capture failed requests and HTTP 4xx/5xx responses (default: true) */
+    captureNetwork?: boolean;
+    /** Trace capture policy (default: 'on-failure') */
+    tracePolicy?: 'off' | 'on-failure' | 'always';
+    /** Max console/page error entries persisted per test (default: 200) */
+    maxConsoleEntries?: number;
+    /** Max network entries persisted per test (default: 200) */
+    maxNetworkEntries?: number;
+}
+export interface MicroPlanConfig {
+    /** Enable multi-action micro plans (default: false) */
+    enabled?: boolean;
+    /** Max actions to execute in one turn including primary action (default: 2) */
+    maxActionsPerTurn?: number;
+}
+export interface ScoutConfig {
+    /** Enable scout recommendations on ambiguous link/result pages */
+    enabled?: boolean;
+    /** Optional model override for scout reasoning */
+    model?: string;
+    /** Optional provider override for scout model */
+    provider?: 'openai' | 'anthropic' | 'google' | 'cli-bridge' | 'codex-cli' | 'claude-code' | 'sandbox-backend' | 'zai-coding-plan';
+    /** Allow the scout to inspect the current screenshot when available */
+    useVision?: boolean;
+    /** Max ranked candidates sent to the scout */
+    maxCandidates?: number;
+    /** Skip scout when the top deterministic score is already above this threshold */
+    minTopScore?: number;
+    /** Skip scout when the top-vs-second score gap is wider than this threshold */
+    maxScoreGap?: number;
+    /** Enable a top-2 read-only challenger on ambiguous visible-link pages */
+    readOnlyTop2Challenger?: boolean;
+}
+export interface SupervisorConfig {
+    /** Enable supervisor interventions (default: true in config defaults) */
+    enabled?: boolean;
+    /** Optional model override for supervisor reasoning */
+    model?: string;
+    /** Optional provider override for supervisor model */
+    provider?: 'openai' | 'anthropic' | 'google' | 'cli-bridge' | 'codex-cli' | 'claude-code' | 'sandbox-backend' | 'zai-coding-plan';
+    /** Allow the supervisor to inspect the current screenshot when available */
+    useVision?: boolean;
+    /** Minimum completed turns before supervisor can intervene */
+    minTurnsBeforeInvoke?: number;
+    /** Cooldown turns between supervisor interventions */
+    cooldownTurns?: number;
+    /** Hard cap on interventions per run */
+    maxInterventions?: number;
+    /** Number of recent turns used to determine hard-stall conditions */
+    hardStallWindow?: number;
+}
+export interface SupervisorSignal {
+    severity: 'none' | 'soft' | 'hard';
+    reasons: string[];
+    repeatedActionCount: number;
+    unchangedTurns: number;
+    errorTurns: number;
+    verificationFailures: number;
+}
+export interface SupervisorDirective {
+    decision: 'none' | 'inject_feedback' | 'force_action' | 'abort';
+    feedback?: string;
+    action?: Action;
+    reason?: string;
+    confidence?: number;
+    raw?: string;
+}
+//# sourceMappingURL=config.d.ts.map

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

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

package/dist/types/config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.js.map

package/dist/types/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":""}

package/dist/types/design-audit.d.ts

@@ -0,0 +1,92 @@
+export interface DesignFinding {
+    category: 'visual-bug' | 'layout' | 'contrast' | 'alignment' | 'spacing' | 'typography' | 'accessibility' | 'ux';
+    severity: 'critical' | 'major' | 'minor';
+    description: string;
+    location: string;
+    suggestion: string;
+    /** CSS selector targeting the element to fix */
+    cssSelector?: string;
+    /** Concrete CSS property:value fix */
+    cssFix?: string;
+    /** 1-10: how much this hurts the user experience */
+    impact?: number;
+    /** 1-10: how hard the fix is (1 = trivial CSS change, 10 = architectural rework) */
+    effort?: number;
+    /** Scope of the fix's effect — page-specific, section-specific, component-level, or design-system-wide */
+    blast?: 'page' | 'section' | 'component' | 'system';
+    /** Computed: (impact * blastWeight) / effort. Higher = fix this first. */
+    roi?: number;
+    /** Number of audited pages where this finding (or its dedupe-equivalent) appears */
+    pageCount?: number;
+    /**
+     * Layer 2 — raw LLM-emitted patches, if any. Untyped here to keep the v1
+     * shape free of audit-internal types. The Layer 2 parser in
+     * src/design/audit/patches/parse.ts validates and converts to typed Patches
+     * before they land on the canonical AuditResult.
+     */
+    rawPatches?: unknown[];
+}
+export interface DesignSystemScore {
+    layout: number;
+    typography: number;
+    color: number;
+    spacing: number;
+    components: number;
+    interactions: number;
+    accessibility: number;
+    polish: number;
+}
+export interface DesignEvolveResult {
+    /** Initial audit score */
+    beforeScore: number;
+    /** Score after applying fixes */
+    afterScore: number;
+    /** Score delta (positive = improvement) */
+    delta: number;
+    /** Rounds of fix-reaudit cycles completed */
+    rounds: number;
+    /** Fixes that were applied */
+    appliedFixes: Array<{
+        cssSelector: string;
+        cssFix: string;
+        finding: string;
+    }>;
+    /** Fixes that were generated but not applied */
+    skippedFixes: Array<{
+        cssSelector: string;
+        cssFix: string;
+        reason: string;
+    }>;
+    /** Per-round scores for convergence tracking */
+    scoreHistory: number[];
+    /** Generated CSS override stylesheet */
+    cssOverride: string;
+}
+export interface FlowAuditResult {
+    flow: string;
+    steps: number;
+    reachedGoal: boolean;
+    findings: DesignFinding[];
+    screenshots: string[];
+    score: number;
+    error?: string;
+}
+export interface DesignAuditReport {
+    timestamp: string;
+    flows: FlowAuditResult[];
+    summary: {
+        healthScore: number;
+        totalFindings: number;
+        critical: number;
+        major: number;
+        minor: number;
+    };
+}
+export interface AuditFlow {
+    name: string;
+    startUrl: string;
+    goal: string;
+    checkpoints: string[];
+    maxTurns?: number;
+}
+//# sourceMappingURL=design-audit.d.ts.map

package/dist/types/design-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-audit.d.ts","sourceRoot":"","sources":["../../src/types/design-audit.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,eAAe,GAAG,IAAI,CAAC;IACjH,QAAQ,EAAE,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0GAA0G;IAC1G,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpD,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,YAAY,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9E,gDAAgD;IAChD,YAAY,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7E,gDAAgD;IAChD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,OAAO,EAAE;QACP,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/types/design-audit.js

@@ -0,0 +1,5 @@
+// ============================================================================
+// Design Audit Types
+// ============================================================================
+export {};
+//# sourceMappingURL=design-audit.js.map

package/dist/types/design-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-audit.js","sourceRoot":"","sources":["../../src/types/design-audit.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E"}