import { ReactNode } from 'react';

/**
 * Screenshot capture for WebAgent — feeds the LLM a visual snapshot of
 * the page alongside the indexed DOM dump. Disabled by default; opt in
 * via `WebAgentConfig.screenshot`.
 *
 * Two modes:
 *   - `viewport`   — only what the user can see right now (1 image).
 *   - `full-page`  — the entire scroll height, split into N segments
 *                    when taller than `maxSegmentHeight`. Each segment
 *                    becomes its own image, capped by `maxImages`.
 *
 * Implementation: dynamic-imports `html2canvas` so users who don't
 * enable screenshots pay zero bundle cost. When a host turns the
 * feature on without installing the peer, capture silently no-ops and
 * the agent continues with text-only input.
 */
type ScreenshotMode = 'viewport' | 'full-page';
interface ScreenshotConfig {
    /** Default capture mode. Default `'viewport'`. */
    mode?: ScreenshotMode;
    /** Max pixel height per image segment. Full-page captures taller than
     *  this split into multiple images. Default 4000. */
    maxSegmentHeight?: number;
    /** Hard cap on the number of images sent per turn (after splitting).
     *  Default 3 — keeps token cost predictable. */
    maxImages?: number;
    /** JPEG quality 0–1. Default 0.75 (sweet spot for legibility vs. size). */
    quality?: number;
    /** Downscale factor — 1 = full resolution, 0.5 = half. Lower = cheaper
     *  tokens but blurrier text. Default 0.75. */
    scale?: number;
    /**
     * Override the capture function entirely. Host returns one image
     * (viewport mode) or many (full-page mode), each as a data URL or
     * remote URL the LLM can fetch. When provided, html2canvas is not
     * loaded.
     */
    capture?: (mode: ScreenshotMode) => Promise<string[]>;
}
/**
 * Capture screenshot(s) of the current page according to `cfg`. Returns
 * an empty array when the host didn't install html2canvas (and didn't
 * provide a custom `capture`) — the agent loop continues without images.
 */
declare function captureScreenshots(cfg: ScreenshotConfig): Promise<string[]>;

/**
 * Types shared across the Plan module — todos artifact, markdown artifact,
 * planning input/output. The shape is deliberately conservative: every
 * artifact is in-memory by default; hosts that want persistence wire a
 * storage adapter (`{ load, save }`) at construction time.
 */

/**
 * A single planned step. The webagent reads this list as its master plan
 * for the run; `replace` / `remove` mutations happen via the per-turn
 * envelope, not the artifact API (so the LLM cannot mutate it freely from
 * arbitrary tool calls).
 */
interface TodoItem {
    /** Stable id assigned by Plan on create — `t1`, `t2`, ... */
    id: string;
    /**
     * Coarse classification of what this todo does. The webagent loop uses
     * this hint to know whether a turn should be a navigate-only turn vs a
     * narrate turn. Non-exhaustive — hosts can introduce custom intents.
     */
    intent: 'navigate' | 'narrate' | 'click' | 'fill' | 'ask' | 'finish' | string;
    /** Human-readable description — what the user will perceive happen. */
    description: string;
    /**
     * Predicted turn index this todo will land on, starting at 1. Lets the
     * webagent recognise when the plan and reality diverge (a navigate todo
     * planned for turn 1 should be the only action of turn 1).
     */
    expected_turn?: number;
}
/** Output of one planning call. `task_summary` is shown to the user when
 *  `announcePlan` is on; `todos` is the master list the loop executes. */
interface TaskPlan {
    task_summary: string;
    todos: TodoItem[];
}
/** What the planner needs to know to write a good plan. */
interface PlanInput {
    /** The user's original task text. */
    task: string;
    /** Optional sitemap so the planner knows which pages exist. */
    sitemap?: SitemapConfig;
    /** Optional brand context (productName / voice / constraints). */
    brand?: BrandPrompt;
    /** Optional persona so plan task_summary speaks in the right voice. */
    persona?: PersonaInput;
    /** BCP-47 locale hint for `task_summary` language. */
    locale?: string;
    /** User selection (Dwell / drag) at invocation time. */
    selection?: SelectionContext;
    /** Free-form host context (recent history, current page, etc). */
    hostContext?: string;
    /**
     * v0.2.0 streaming hook — called synchronously for each new chunk of
     * `task_summary` chars as the LLM types it. When the host wires this
     * through, the planning announce can appear live in the subtitle bar
     * instead of one post-parse blast. Optional; omitting it keeps the
     * call non-visibly-streaming (the LLM body still uses `stream: true`
     * so the proxy doesn't buffer via cache-ttl, just no UI surfacing).
     */
    onSummaryDelta?: (delta: string) => void;
}
/** An in-memory markdown document. Not used by the webagent — exposed for
 *  hosts that want LLM-mediated authoring of meeting notes, drafts, etc. */
interface MarkdownDoc {
    /** Stable id assigned by Plan on create — `m1`, `m2`, ... */
    id: string;
    title: string;
    content: string;
    /** ms epoch — set on create + every edit. */
    updatedAt: number;
}
/**
 * Optional storage adapter. Same shape as ImmersiveTranslate's cache —
 * `load()` runs once at construct time and seeds in-memory state;
 * `save()` runs after every mutation. Hosts can plug IndexedDB,
 * localStorage, or a server endpoint behind this interface.
 */
interface PlanStorageAdapter {
    load(): Promise<PlanSnapshot | null> | PlanSnapshot | null;
    save(snapshot: PlanSnapshot): Promise<void> | void;
}
interface PlanSnapshot {
    todos: TodoItem[];
    markdownDocs: MarkdownDoc[];
}

interface BrandPrompt {
    productName?: string;
    voice?: string;
    constraints?: string[];
}
/** Persona — tells the agent who it speaks AS. Without this the agent
 *  narrates in third-person observer voice. */
interface PersonaConfig {
    /** First-person identity statement. Required. */
    identity: string;
    /** Voice / tone notes. */
    voice?: string;
    /** Hard rules the persona must never break. */
    constraints?: string[];
}
type PersonaInput = string | PersonaConfig;
interface PromptContext {
    locale?: string;
    agentName: string;
    siteName?: string;
    sitemap?: SitemapConfig;
    session: AgentSession;
    pageContext: string;
    selection?: SelectionContext;
    brand?: BrandPrompt;
    persona?: PersonaInput;
    appendSystemPrompt?: string;
    previousUrl?: string;
    /** When true, render the CoT-mode prompt (no procedural rules, schema
     *  enforces structure). When false, render the classic narrator prompt. */
    cotMode?: boolean;
    /** Pre-rendered tool reference (name + description + JSON Schema) for
     *  every action exposed this turn. Pushed into the `# Tools` section
     *  of the system prompt so the model sees the tool catalogue in one
     *  place rather than buried inside the agent_turn tool description. */
    toolReference?: string;
}
type SystemPromptOverride = string | ((ctx: PromptContext, defaultPrompt: string) => string);

/**
 * Sitemap — tree/graph structure for agent navigation on multi-page sites.
 *
 * Why a tree?
 *   Flat sitemap[] doesn't scale past ~10 pages. Agent has to scan everything
 *   to figure out what's reachable. Tree gives:
 *     - hierarchy (parent → children) → agent can drill down step-by-step
 *     - per-node metadata (auth requirements, available actions, sub-routes)
 *     - LLM-friendly serialization (indented outline matches how LLMs reason)
 *
 * Static-only in v1. Host writes it in config. Runtime learning deferred to v2.
 */
interface SitemapNode {
    /**
     * Display title for the page. Goes into prompts and palette search results.
     */
    title: string;
    /**
     * One-line description. Agent uses this to match "I want to do X" intent
     * against the right page.
     */
    description?: string;
    /**
     * Child routes. Key is the path segment (relative to this node).
     * Use `:id` / `:slug` for dynamic segments — agent knows it's a parameter.
     */
    children?: Record<string, SitemapNode>;
    /**
     * Verbs the user can perform on this page. Agent uses these to plan.
     * Examples: ['view', 'edit', 'export', 'delete', 'refund', 'ship']
     */
    actions?: string[];
    /**
     * If true, agent must ensure user is logged in (likely navigate to /login
     * first) before visiting. The login flow itself uses DOM operations (click
     * the login button, fill the form) — dddk does NOT handle OAuth.
     */
    requiresAuth?: boolean;
    /**
     * If true, requires elevated permission. Agent should explain this to user
     * before attempting.
     */
    requiresAdmin?: boolean;
    /**
     * Hidden from the LLM prompt (still navigable, just not advertised). Useful
     * for internal-only routes.
     */
    hidden?: boolean;
    /**
     * Free-form notes the host wants the agent to remember about this page.
     * e.g., "Pagination is server-driven — use the [Next] button, not URL ?page=N"
     */
    notes?: string;
    /**
     * Optional keywords the agent should match user intent against. Saves a
     * prompt token vs putting everything in description.
     */
    keywords?: string[];
}
interface SitemapResolution {
    /** Concrete URL path with parameters substituted. */
    path: string;
    /** The matched node. */
    node: SitemapNode;
    /** Parameters extracted from / supplied for the path. */
    params: Record<string, string>;
}

/**
 * LLM Provider interface — implement once, providers slot in.
 * See ../../docs/03-llm-providers.md for the full design.
 */
interface LLMProvider {
    readonly name: string;
    complete(opts: CompleteOptions): Promise<CompleteResult>;
}
interface CompleteOptions {
    messages: LLMMessage[];
    tools?: ToolDefinition[];
    temperature?: number;
    maxTokens?: number;
    model?: string;
    signal?: AbortSignal;
    /**
     * Reasoning intensity. Provider-specific mapping:
     *   - OpenAI reasoning / gpt-5+ models → `reasoning_effort`
     *       'off' → 'minimal'
     *   - Gemini 2.5+ models → `generationConfig.thinkingConfig.thinkingBudget`
     *       'off' → 0
     *       'minimal' / 'low' → 64 / 512
     *       'medium' / 'high' → 1024 / 4096
     *   - Other / non-reasoning models → field is ignored
     *
     * Use `'off'` for short, deterministic tasks (inline text edits,
     * translation, classification) — saves cost and prevents the model
     * from leaking chain-of-thought into the response.
     */
    thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high';
    /**
     * Force the model to respond with a JSON object that parses cleanly.
     *   - OpenAI → `response_format: { type: 'json_object' }`
     *   - Gemini → `generationConfig.responseMimeType = 'application/json'`
     * Providers that don't support structured output ignore this; the prompt
     * itself should still say "Reply with JSON only" as a fallback.
     */
    jsonMode?: boolean;
    /**
     * Force which tool the model must call.
     *   - `'auto'` (default) — model picks zero or one tool
     *   - `'required'` — model must call exactly one tool (any tool in `tools`)
     *   - `{ name: 'foo' }` — model must call the named tool
     *
     * Used by the WebAgent's CoT mode to force the wrapping `agent_turn`
     * tool every turn. Providers that don't support targeted tool_choice
     * fall back to `'required'` or `'auto'`.
     */
    toolChoice?: 'auto' | 'required' | {
        name: string;
    };
}
interface CompleteResult {
    content: string;
    toolCalls?: ToolCall[];
    usage?: {
        promptTokens: number;
        completionTokens: number;
    };
    finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter';
    /**
     * Streaming-only timing. Present when the call went through
     * `streamComplete()` and the stream produced at least one delta. All
     * values are epoch ms (`Date.now()`).
     *   - `startedAt`     — first call to `produce()`
     *   - `firstDeltaAt`  — first non-empty text delta (TTFT = this - startedAt)
     *   - `endedAt`       — terminal chunk (last delta or finish)
     * Non-streaming `complete()` calls omit this field.
     */
    streamMetrics?: {
        startedAt: number;
        firstDeltaAt?: number;
        endedAt: number;
    };
}
type LLMRole = 'system' | 'user' | 'assistant' | 'tool';
interface LLMMessage {
    role: LLMRole;
    content: string | ContentPart[];
    /** Set when role = 'tool' — the call this message answers. */
    toolCallId?: string;
    /** Set when role = 'assistant' — tool calls emitted in this turn. */
    toolCalls?: ToolCall[];
    /** Display name (optional, for multi-agent traces). */
    name?: string;
}
type ContentPart = {
    type: 'text';
    text: string;
} | {
    type: 'image';
    image: string;
};
interface ToolDefinition {
    name: string;
    description: string;
    parameters: Record<string, unknown>;
}
interface ToolCall {
    id: string;
    name: string;
    arguments: Record<string, unknown>;
}

/**
 * LLMRouter — pick a provider per role.
 *
 * 4 roles:
 *   - `webagent` — main agent loop (text-only)
 *   - `vision`   — webagent with images / screenshot context. Falls back to webagent.
 *   - `utility`  — short single-shot calls (inline AI / voice cleanup / etc). Falls back to webagent.
 *   - `plan`     — pre-loop planner. Falls back to webagent.
 *
 * Legacy field names (`webagentWithSelection`, `inline`, `voiceCleanup`)
 * are still accepted as fallback sources so existing host configs keep
 * working; prefer the new names for new code.
 */

interface LLMRouter {
    /** Required. Default LLM for the webagent loop. All other roles fall back here. */
    webagent: LLMProvider;
    /** Used when the agent has images / screenshots to reason about. */
    vision?: LLMProvider;
    /** Short single-shot calls — inline AI, voice cleanup, immersive translate. */
    utility?: LLMProvider;
    /** Pre-loop planner. */
    plan?: LLMProvider;
    /** v0.2.0. TaskAgent — conversational + tool calling. */
    task?: LLMProvider;
    /** @deprecated — use `vision`. */
    webagentWithSelection?: LLMProvider;
    /** @deprecated — use `utility`. */
    inline?: LLMProvider;
    /** @deprecated — use `utility`. */
    voiceCleanup?: LLMProvider;
}
type LLMSource = LLMProvider | LLMRouter;

type ActionFailureReason = 'not_found' | 'not_visible' | 'not_interactive' | 'timeout' | 'navigation' | 'cancelled' | 'user_declined'
/**
 * the target is in scope the agent can read but
 * not act on — typically a cross-origin iframe or popup. The agent
 * narrates the boundary to the user and may offer to hand off.
 */
 | 'cross_origin'
/**
 * the route the agent navigated to requires
 * authentication; user must sign in before the agent can proceed.
 */
 | 'auth_required' | 'unknown';
type ActionResult<T = unknown> = {
    ok: true;
    data?: T;
} | {
    ok: false;
    reason: ActionFailureReason;
    message?: string;
};
interface ActionContext {
    session: AgentSession;
    signal: AbortSignal;
    /**
     * Resolve a selector argument (e.g. `selector`, `target`) to a live
     * element. Accepts either:
     *   - A numeric index from the DOM dump (`"3"` or `"[3]"`) — looked
     *     up in the per-turn index map. This is the preferred form.
     *   - A CSS selector string — passed to `document.querySelector`.
     *
     * Returns `null` when neither resolves. Action handlers use this
     * helper instead of calling `document.querySelector` directly so
     * the indexed-tree contract works uniformly.
     */
    resolveTarget(target: string | number): Element | null;
    /**
     * Visual / UX hints forwarded from `WebAgentConfig`. Actions read these
     * to apply human-paced overlays (synthetic cursor, link-click vs push-
     * state navigate, …) without each handler needing access to the full
     * config object.
     *
     * @since v0.2.0
     */
    uiHints?: {
        cursorTrail?: boolean;
        preferClickLinkOverNavigate?: boolean;
    };
}
interface ActionDefinition<P = unknown, R = unknown> {
    name: string;
    description: string;
    /** JSON Schema for params. */
    parameters: Record<string, unknown>;
    handler: (params: P, ctx: ActionContext) => Promise<ActionResult<R>>;
    /**
     * If true (or a predicate returning true), the agent pauses before
     * invoking and emits a `confirm` event that the host must `decide()`
     * on. Use for destructive / external-side-effect actions (delete,
     * send email, place order, transfer money). The webagent also
     * auto-marks any action whose name matches a destructive-pattern
     * regex (see `WebAgentConfig.destructivePatterns`); per-action
     * `requireConfirmation: false` can opt out of the pattern match.
     */
    requireConfirmation?: boolean | ((params: P, ctx: ActionContext) => boolean | Promise<boolean>);
    /** Override the confirmation prompt. Return undefined to fall through
     *  to host-level / SDK-default copy. */
    confirmationMessage?: (params: P) => string | undefined;
}
interface SelectionContext {
    text?: string;
    images?: string[];
    bbox?: {
        x: number;
        y: number;
        width: number;
        height: number;
    };
    /** CSS selectors / DOM paths the user clicked or multi-selected. */
    elements?: string[];
}
interface ToolHandle {
    /** Unregister this tool. After this returns, the next agent step
     *  no longer sees the action. Idempotent — calling twice is fine. */
    remove(): void;
}
/**
 * Names the context provider supplies — they map to the slots the
 * runtime asks for when building a per-turn context. SDK ships
 * defaults for each; hosts can replace any
 * single slot without re-implementing the others.
 */
type ContextRole = 'url' | 'page_summary' | 'dom' | 'screenshot' | 'history' | 'selection';
interface ContextRequest {
    /** The agent's signal for the current turn (so providers can bail
     *  cheaply when the host cancels). */
    signal: AbortSignal;
    /** Most recent user task / sub-task the agent is operating on. */
    task?: string;
}
/**
 * Pluggable producer for one slot of per-turn context. Returns a
 * string the runtime can splice into the prompt, or `null` to skip
 * the slot entirely (e.g. DOM dump bails on a cross-origin
 * iframe). Async — providers commonly snapshot from the live DOM
 * or call back to the host.
 */
type ContextProvider = (req: ContextRequest) => string | null | Promise<string | null>;
interface ContextProviderHandle {
    /** Unregister this context provider. Restores whatever was set
     *  previously for this role (SDK default if no prior override).
     *  Idempotent. */
    remove(): void;
}
interface AgentSession {
    id: string;
    turns: AgentTurn[];
    status: AgentStatus;
    currentPage: string;
    startedAt: number;
    updatedAt: number;
    /** Master plan produced by `WebAgentConfig.planner` at run start, if
     *  any. The webagent's per-turn envelope reads `todos` from here; the
     *  loop mutates via `todo_adjust` (remove / replace operations only). */
    plan?: TaskPlan;
}
type AgentStatus = 'idle' | 'thinking' | 'executing' | 'waiting' | 'navigating' | 'done' | 'failed';
/** Discriminated union of everything that can land in `session.turns[]`. */
type AgentTurn = UserTurn | AgentStepTurn | AgentFinalTurn;
interface UserTurn {
    kind: 'user';
    ts: number;
    text: string;
    selection?: SelectionContext;
}
interface AgentStepTurn {
    kind: 'agent_step';
    ts: number;
    /** Free-form text the model emitted *before* picking the tool (streaming). */
    preText?: string;
    toolCall: {
        name: string;
        arguments: Record<string, unknown>;
    };
    toolCallId: string;
    result: ActionResult;
}
interface AgentFinalTurn {
    kind: 'agent_final';
    ts: number;
    text: string;
}
type AgentEvent = {
    kind: 'thinking';
} | {
    kind: 'text-delta';
    delta: string;
} | {
    kind: 'tool-start';
    name: string;
    args: Record<string, unknown>;
    targetSelector?: string;
    toolCallId: string;
} | {
    kind: 'tool-end';
    name: string;
    result: ActionResult;
    toolCallId: string;
}
/** Fired right BEFORE the SPA router is invoked. The page is still
 *  the old one; the host should show a "loading" indicator until
 *  `navigated` arrives. */
 | {
    kind: 'navigating';
    from: string;
    to: string;
}
/** Fired AFTER the router Promise resolved AND the DOM has settled.
 *  The page is now the new one and safe to introspect. */
 | {
    kind: 'navigated';
    from: string;
    to: string;
} | {
    kind: 'confirm';
    actionName: string;
    args: Record<string, unknown>;
    message: string;
    decide: (approved: boolean) => void;
} | {
    kind: 'final';
} | {
    kind: 'error';
    error: Error;
    retrying: boolean;
};
type OverlayType = 'highlight' | 'border' | 'spotlight' | 'inject';
interface OverlayItem {
    id: string;
    type: OverlayType;
    selector: string;
    color?: string;
    label?: string;
    text?: string;
    position?: 'before' | 'after';
}
type PiecePlacement = 'center' | 'inline' | 'dock';
interface SitemapEntry {
    path: string;
    description: string;
    aliases?: string[];
}
type SitemapConfig = SitemapEntry[] | SitemapNode;
interface RunOptions {
    /** What the user had selected when they invoked the agent. */
    selection?: SelectionContext;
    /**
     * Force a fresh session even if a live session exists within the
     * continuity window. Set this when the host's UX is "new conversation
     * button pressed" — default behavior (false) appends to the existing
     * session as a follow-up.
     */
    freshSession?: boolean;
}
/**
 * Behaviour when the agent loop finishes (CoT `actions: []` /
 * classic-mode no-tool-call turn / maxSteps cap). Without an
 * `onLoopEnd` the subtitle bar disappears the moment the loop ends,
 * which reads as broken — there's no signal that the work completed.
 *
 *  - `silent`   — legacy: subtitle just disappears.
 *  - `text`     — stream a final closing line (e.g. "✓ Done") then
 *                 dismiss after `autoHide` ms.
 *  - `feedback` — closing line + Space (satisfied) / double-tap (not) /
 *                 Esc (skipped) gestures, emitted as `agent_feedback`
 *                 on the intent stream.
 *  - `ask_user` — option picker (e.g. 1-5 rating); the chosen value
 *                 flows into `agent_feedback.summary`.
 *
 * SDK default: `{ kind: 'text', text: i18n('agent.done'), autoHide: 3000 }`.
 * Hosts opt into `feedback` / `ask_user` for post-run satisfaction signal.
 */
type OnLoopEnd = {
    kind: 'silent';
} | {
    kind: 'text';
    text: string;
    autoHide?: number;
} | {
    kind: 'feedback';
    text: string;
} | {
    kind: 'ask_user';
    question: string;
    options: Array<{
        value: string;
        label: string;
    }>;
};
interface WebAgentConfig {
    /** LLM source — single `LLMProvider` or `LLMRouter` (per-role). */
    llm: LLMSource;
    locale?: string;
    /**
     * Optional pre-loop planning callback. When set, the webagent makes a
     * single planning call BEFORE entering the turn loop, expects a
     * `TaskPlan` ({ task_summary, todos[] }), stores it on the session,
     * and switches the per-turn envelope to the planned variant
     * (turn_planning + todo_adjust + actions instead of memory +
     * todos_remaining + actions). Typical wiring is `(input) =>
     * dddk.plan.makeTodos(input)` so the Plan module's strategic
     * appendSystemPrompt drives the plan shape.
     */
    planner?: (input: PlanInput) => Promise<TaskPlan>;
    /** When true (and `planner` is set), the resulting `task_summary` is
     *  announced to the user via a subtitle bar narrate before the loop
     *  begins. Default false — silent execution. */
    announcePlan?: boolean;
    /**
     * Cap the size of the DOM snapshot fed to the planner. Default 8000
     * chars — enough for a typical page's nav + headings + above-fold
     * content. The planner ALWAYS reads the current DOM (it needs to
     * know which page it's on and what nav links are reachable); this
     * just caps how much it sees. The webagent's per-turn DOM uses
     * `domMaxLength` (default 40000) separately so the loop's eyes
     * stay sharper than the planner's one-shot.
     */
    plannerDomMaxLength?: number;
    /** Hard cap on tool-call iterations per task. Default 30. */
    maxSteps?: number;
    /** Consecutive LLM-call failures before bailing. Default 3. */
    maxErrors?: number;
    /** Single LLM call hard timeout (ms). Default 60_000. */
    llmTimeoutMs?: number;
    /** Reasoning intensity (provider-specific). Default 'off'. */
    thinking?: 'off' | 'low' | 'medium' | 'high';
    /** System prompt override — string hard-replaces; function composes. */
    systemPrompt?: SystemPromptOverride;
    /** Structured brand context layered into the default prompt. */
    brand?: BrandPrompt;
    /**
     * First-person identity for the agent — who it IS and on whose behalf
     * it speaks. Without this, the agent narrates the page in third-person
     * observer voice ("the site states X"); with it, the agent speaks as
     * the site's representative ("we offer X").
     *
     * Default: `undefined` (no persona section in the prompt).
     *
     * Pass a string for a quick identity line, or a structured
     * `PersonaConfig` for separate voice / constraint fields:
     *
     *   persona: "You are the dotdotduck assistant, speaking on behalf
     *             of perhapxin. Use 'we' for what perhapxin does."
     *
     *   persona: {
     *     identity: "You are Acme's support assistant...",
     *     voice: "Warm, decisive, never speculative.",
     *     constraints: ["Never promise refunds without confirming with the team."],
     *   }
     */
    persona?: PersonaInput;
    /** Plain text appended after the default prompt. */
    appendSystemPrompt?: string;
    sitemap?: SitemapConfig;
    agentName?: string;
    siteName?: string;
    customActions?: ActionDefinition[];
    /**
     * Per-action description overrides — applied at tool-build time so the
     * model sees host-customised wording without the SDK shipping rules for
     * every host. Keyed by action name (e.g. `'navigate'`, `'open_palette'`,
     * `'border'`).
     *
     * - `description` — hard replace; the SDK default is dropped entirely.
     * - `appendDescription` — appended after the SDK default with a newline.
     *
     * If both are set, `description` wins. Unknown action names are
     * ignored. Applies to BOTH CoT mode (where the override lands in the
     * system prompt's `# Tools` section) and classic mode (where it lands
     * on the OpenAI tool definition).
     */
    actionOverrides?: Record<string, {
        description?: string;
        appendDescription?: string;
    }>;
    /** sessionStorage key. Default 'webagent.session'. */
    sessionStorageKey?: string;
    /**
     * Inject a shared `AgentSession` instead of letting the agent
     * create + persist its own. Use to share conversation history +
     * memory across multiple WebAgent instances (e.g. different
     * personas per route) so cross-page continuity survives even when
     * the active agent changes. The agent reads + appends to the same
     * object; it does NOT replace the reference on continuity expiry
     * — that's the host's job (via `dddk.sessions.reset(name)`).
     *
     * When set, the agent skips the lazy `createSession` step and the
     * `loadSession` lookup. The host (or `dddk.sessions`) becomes
     * solely responsible for the session's lifecycle. v0.2.
     */
    session?: AgentSession;
    /** Override default tool list (advanced). */
    toolDefinitions?: ToolDefinition[];
    /**
     * Multi-turn continuity. After a turn ends, follow-ups within this
     * window append to the current session as user turns. Older than this
     * and the next `runStream()` starts a fresh session.
     *
     * Default `0` (OFF) — most webagent usage is one-shot ("how do I X?",
     * answer, done); carrying prior turns into a new ask causes the LLM
     * to conflate unrelated questions. Hosts building conversational
     * agents (chat-style follow-ups) opt in by setting e.g.
     * `5 * 60 * 1000`. Cross-PAGE continuity (SPA navigation mid-run)
     * is independent and always on.
     */
    sessionContinuityMs?: number;
    /**
     * Continuity scope — `'time'` (default) honors `sessionContinuityMs`;
     * `'palette'` ends continuity when the palette closes (host signals
     * via `dddk.agent.endContinuity()`).
     */
    sessionScope?: 'time' | 'palette';
    /**
     * Custom destructive-action patterns. An action whose name matches
     * any of these regexes auto-gates on `confirm`. Overrides built-in
     * defaults; pass an empty array to disable the default list and
     * rely only on per-action `requireConfirmation`.
     */
    destructivePatterns?: RegExp[];
    /**
     * When true, no tool call ever pauses for user confirmation — including
     * actions whose `requireConfirmation` is explicitly true. Use on sites
     * where the agent's surface is non-destructive (demos / docs / read-only
     * exploration) and the confirm-pause feels like friction.
     *
     * Per-action `requireConfirmation: true` is still respected for the
     * default destructive-pattern auto-gate when this flag is unset.
     */
    disableConfirmations?: boolean;
    /**
     * Opt the agent in to the `present_surface` tool — lets the model
     * render a PieceSurface (image+text cards, option grids, etc.) and
     * await the user's pick.
     *
     * Default `false` because rich surfaces can leak host-private UI to
     * the model's planning context (the agent decides what image src to
     * use, what option labels to show). Enable when the host wants
     * recommendation-style flows and trusts the brand / persona / prompt
     * to keep the model on-rails.
     *
     * The host MUST ALSO call `agent.setSurfaceMounter(fn)` to wire the
     * actual mounting code — otherwise `present_surface` returns a
     * `not_wired` error and the model falls back to manual narration.
     */
    allowPresent?: boolean;
    /**
     * Force every turn through a structured CoT envelope. The model is
     * required to call a single `agent_turn` tool whose args contain
     * `memory`, `next_goal`, and an ordered `actions[]` of narrations +
     * tool calls. The runtime parses the envelope and dispatches actions
     * in order — fixing the "border-then-skip" failure mode where the
     * classic per-turn-one-tool-call loop can short-circuit early.
     *
     * Default: `false` (classic streaming loop). When `true`, this also
     * disables the per-turn-pause pacing rules in the prompt — pause is
     * runtime-managed (auto-pause after each narration) rather than
     * model-managed.
     */
    cotMode?: boolean;
    /**
     * Override the confirmation copy shown when a `requireConfirmation`
     * action is about to run. Receives the action name + its params and
     * the agent's locale. Return a string to use it; return `undefined`
     * to fall back to the SDK's built-in copy.
     *
     * The SDK ships en + zh-TW. Use this for `ja` / `es` / `fr` etc., or
     * when you want host-branded wording ("Approve the transfer? Press
     * space to confirm").
     *
     *   buildConfirmMessage: (action, params, locale) => {
     *     if (locale === 'ja') {
     *       if (action === 'navigate') return `${params.path} に移動します — スペースキーで確認`;
     *       return undefined;  // fall back to default English for the rest
     *     }
     *     return undefined;
     *   }
     *
     * Per-action `ActionDefinition.confirmationMessage(params)` still
     * wins when set — that override is action-scoped and runs first.
     */
    buildConfirmMessage?: (actionName: string, params: Record<string, unknown>, locale: string) => string | undefined;
    /**
     * Subtraction filter applied to every visible element the DOM reader
     * considers. Return `false` to drop the element + its subtree from
     * the dump. Use this to keep the agent focused on the host's main
     * content area: filter out site chrome (nav / footer / cookie banner)
     * the agent should never narrate.
     *
     *   domFilter: (el) => !el.matches('nav.global-nav, footer, [data-cookie]')
     *
     * Default: include everything visible.
     */
    domFilter?: (el: Element) => boolean;
    /**
     * Hard cap on the DOM dump size sent to the LLM each turn (in
     * characters). Default ~12000 — large enough to capture a typical
     * marketing / pricing / docs page in full; small enough to keep the
     * per-turn token cost predictable. Hosts with denser pages can bump
     * this; hosts on a budget can shrink it. The reader truncates with a
     * `[...truncated]` marker rather than blowing the budget silently.
     */
    domMaxLength?: number;
    /**
     * Cross-tab session sync via BroadcastChannel + localStorage mirror.
     * Default `false`.
     */
    crossTabSync?: boolean;
    /**
     * Subtitle-bar hint shown when the agent calls `pause` without a
     * `note` argument. The SDK ships an English default — set this in
     * the host's UI language for a localised experience.
     */
    defaultPauseNote?: string;
    /**
     * Hard cap on how many session turns get serialised into each LLM
     * prompt. When the session has more, the oldest turns are dropped
     * and only the most recent `maxTurnsInPrompt` are sent (the system
     * prompt is always kept). Default: undefined (no cap).
     */
    maxTurnsInPrompt?: number;
    /**
     * Token budget for the per-turn LLM prompt. When the assembled
     * prompt exceeds this estimate, the SDK drops the OLDEST turns
     * first and keeps the most recent ones — the system prompt and the
     * env-block / latest-user message are always preserved.
     *
     * The estimate is a coarse char-count → token approximation
     * (mixed CJK + English ~ 3.5 chars per token); not a strict
     * count. Set it well below your model's true context window so
     * there's headroom for the model's own response.
     *
     * Default: undefined (no cap).
     */
    maxPromptTokens?: number;
    /**
     * Attach a screenshot of the current page to every LLM turn alongside
     * the indexed DOM dump. Disabled by default — text-only mode is faster,
     * cheaper, and sufficient for most narration tasks. Turn on when the
     * page has visual content the DOM dump can't convey (charts, custom
     * canvases, complex visual layouts the agent should comment on).
     *
     * Two modes:
     *   - `'viewport'`  — one image of what the user currently sees.
     *   - `'full-page'` — the full scroll height, auto-split into multiple
     *                     images when taller than `maxSegmentHeight`.
     *
     * Requires the `html2canvas` peer dependency (`pnpm add html2canvas`)
     * unless you provide a custom `capture` function. When neither is
     * available the agent runs text-only without erroring.
     */
    screenshot?: boolean | ScreenshotConfig;
    /**
     * What happens when the agent loop ends. See `OnLoopEnd` for the
     * union; SDK default is `{ kind: 'text', text: i18n('agent.done'),
     * autoHide: 3000 }` so the subtitle bar doesn't just vanish.
     *
     * Pass `{ kind: 'silent' }` for the legacy "subtitle disappears"
     * behaviour; pass `{ kind: 'feedback', text: ... }` to collect a
     * satisfied / not-satisfied signal via `agent_feedback`.
     */
    onLoopEnd?: OnLoopEnd;
    /**
     * Names of built-in actions to NOT expose to the agent. The default
     * builtin set is intentionally broad (navigate / scroll_to / wait /
     * click / fill_input / select_option / clear_input / border / pause /
     * ask_user / ask_user_choice) so any host works out of the box —
     * but most sites only need a subset. Listing names here removes them
     * from the agent's tool list entirely, which:
     *   1. Shrinks the schema the LLM has to read each turn (fewer tokens).
     *   2. Removes "wrong tool" failure modes (the agent can't pick a tool
     *      that isn't relevant to your site).
     *
     * Example: a marketing demo with no `<select>` elements and a one-shot
     * Q&A style (agent never asks the user) would pass
     * `['pause', 'wait', 'select_option', 'clear_input', 'ask_user', 'ask_user_choice']`.
     *
     * Hosts can still re-add specific actions (or custom ones) via
     * `customActions`, which run AFTER this filter.
     *
     * @deprecated Since v0.2.0. Use `excludeTools` for the same effect,
     * and `disableAutoPauseAfterNarrate` to control the runtime-level
     * pause behaviour. This field stays accepted as an alias to
     * `excludeTools` for one minor version, then is removed in v0.3.0.
     */
    disableBuiltinActions?: string[];
    /**
     * Names of built-in or registered actions to hide from the agent's
     * tool catalog. Equivalent to the older `disableBuiltinActions` —
     * the rename clarifies that the field only filters the LLM-visible
     * catalog, NOT the runtime auto-pause behavior (see
     * `disableAutoPauseAfterNarrate` for that).
     *
     * If both `disableBuiltinActions` and `excludeTools` are set, the
     * union is applied.
     *
     * @since v0.2.0
     */
    excludeTools?: string[];
    /**
     * Stop the runtime from auto-inserting a `pause` after every narrate
     * action in CoT mode. The default behavior is "narrate → pause →
     * wait for Space → next action". Disabling this collapses narrates
     * into a single uninterrupted stream — suitable for hosts whose
     * sites are read-only or whose users expect a chat-style experience
     * with no per-step gating.
     *
     * Note: this is NOT the same as putting `'pause'` in `excludeTools`.
     * `excludeTools: ['pause']` only stops the LLM from calling pause
     * explicitly; the runtime still inserts auto-pauses after narrates.
     * Setting `disableAutoPauseAfterNarrate: true` is what actually
     * removes the gating.
     *
     * Default: `false`.
     *
     * @since v0.2.0
     */
    disableAutoPauseAfterNarrate?: boolean;
    /**
     * Enable the streaming `agent_turn` envelope path (v0.2.0)
     * 1.9). When `true`, the runtime parses tool-call args incrementally
     * as the LLM streams them, so `narrate` strings start appearing in
     * the subtitle bar as the LLM types them — instead of waiting for
     * the entire envelope to complete, then replaying via a local
     * typewriter.
     *
     * Currently EXPERIMENTAL. Requires provider-side support for
     * incremental tool-call args streaming (the bundled
     * `OpenAIProvider` will gain this in a follow-up; until then setting
     * this flag is a no-op for OpenAI). Other providers fall back to the
     * non-streaming path automatically.
     *
     * Default: `false`.
     *
     * @since v0.2.0
     * @experimental
     */
    enableStreamingEnvelope?: boolean;
    /**
     * Synthetic cursor overlay for click actions (v0.2.0 — ROADMAP).
     *
     * When `true`, every `click` action renders a small arrow cursor that
     * slides from its last position to the target element (~360ms), plays
     * a brief tap animation, THEN calls `el.click()`. The actual DOM
     * event is still fired by `el.click()` — the cursor is purely visual.
     *
     * The point is human-paced feedback so users (and demo viewers) see
     * the agent operate the page like a person, rather than buttons
     * getting pressed by an invisible ghost. Respects
     * `prefers-reduced-motion`.
     *
     * Default: `false`. Recommended `true` for marketing demos / screen
     * recordings; either toggle is fine in production.
     */
    cursorTrail?: boolean;
    /**
     * Prefer clicking an `<a href>` over `history.pushState` when the
     * `navigate` action runs (v0.2.0 — ROADMAP).
     *
     * When `true`, before falling back to `history.pushState(target)`,
     * `navigate` looks for a visible `<a href="${target}">` on the page
     * and (if `cursorTrail` is also enabled) glides the cursor to it +
     * fires `.click()`. Behaviour collapses to the original push-state
     * fallback if no matching link exists.
     *
     * Why: directly mutating history feels jarring on demo videos —
     * the SPA route flips but the user never sees "the agent clicked
     * nav". Click-the-link first surfaces the navigation as a real
     * user action.
     *
     * Default: `false` (keep v0.1.x behaviour). Pair with `cursorTrail`
     * for the full effect.
     */
    preferClickLinkOverNavigate?: boolean;
}

/**
 * Structured CoT turn — per-turn schema that wraps the model's response
 * in a single `agent_turn` tool call with strict JSON schema.
 *
 * Schema property order matters for streaming: `actions` is always emitted
 * BEFORE `is_final` so the model fully commits to the work plan before
 * declaring the task complete.
 */

interface CotToolRef {
    name: string;
    description: string;
    parameters: Record<string, unknown>;
}

/**
 * Action execution — runs an action handler with the right side effects.
 *
 * Two built-ins handled here intercept the registry to yield user
 * interaction back to the host:
 *   - `ask_user`        — free-text question
 *   - `ask_user_choice` — picker
 *
 * `navigate` is also special-cased: the action handler itself only
 * returns metadata (the path); the agent runtime emits a `navigated`
 * event and the host's router moves the page. This file is the right
 * place to wire that bridge.
 */

interface AskUserPayload {
    question: string;
    resolve: (answer: string) => void;
}
interface AskUserChoicePayload {
    question: string;
    options: string[];
    allowFreeText: boolean;
    resolve: (answer: string) => void;
}
/**
 * `pause` is its own envelope (NOT an ask_user) so hosts can render it
 * differently — typically by attaching a "press space to continue"
 * hint to the running streaming subtitle bar, rather than replacing
 * the bar with a confirmation dialog. The text the agent just streamed
 * must stay visible while the user reads.
 */
interface PausePayload {
    hint: string;
    resolve: (answer: string) => void;
}
/**
 * Surface presentation — agent emits a PieceSurface (image+text card,
 * option group, etc.) and waits for the user to pick or cancel. The
 * host renders into a PlacementSlot and resolves with the chosen
 * option's value (or null on cancel).
 *
 * Only fires when the host has opted in via `WebAgentConfig.allowPresent`
 * AND has wired the surface mounter via `setSurfaceMounter`.
 */
interface PresentSurfacePayload {
    /** Piece tree the host renders. The agent built it; the host trusts
     *  its catalog won't include unsafe pieces (Slot's `render` fn etc.). */
    surface: unknown;
    /** Where on screen to render. Subset of PlacementSlot — agent isn't
     *  given access to fab / banner / toast since those have semantics
     *  the agent shouldn't be allowed to choose. */
    placement: 'subtitle' | 'modal' | 'dock' | 'inline';
    /** Resolves with the chosen option's value, or null on cancel. */
    resolve: (pick: {
        value: string | null;
        cancelled: boolean;
    }) => void;
}

/**
 * WebAgent — DOM-grounded narrator agent.
 *
 * Public surface: constructor / configure (via setter helpers) / runStream
 * / continueStream / resumeStream / session lifecycle / handler setters.
 *
 * Loop bodies, message assembly, and `__dddkDebug` writes live under
 * ./runtime so this file stays focused on state + public API. The runtime
 * modules consume the agent through `@internal` accessors below.
 */

/**
 * Per-LLM-call performance sample emitted to the orchestrator after each
 * streaming call. The orchestrator decorates with `runId` and forwards as
 * an `agent_llm_call` IntentEvent for the analytics dashboard.
 */
interface LlmCallInfo {
    role: 'webagent' | 'vision';
    /** Time-to-first-token in ms (request issued → first non-empty delta). */
    ttftMs: number;
    /** Total stream wall-time in ms (request issued → final chunk). */
    durationMs: number;
    /** Provider-reported output tokens (if available). */
    outputTokens?: number;
    /** Provider-reported input tokens (if available). */
    inputTokens?: number;
    /** Resolved model id, when the provider exposes it. */
    model?: string;
}
type ResolvedConfig = WebAgentConfig & Required<Pick<WebAgentConfig, 'locale' | 'maxSteps' | 'maxErrors' | 'llmTimeoutMs' | 'agentName' | 'sessionStorageKey' | 'sessionContinuityMs' | 'sessionScope'>>;
declare class WebAgent {
    /** @internal */ config: ResolvedConfig;
    /** @internal */ actions: Map<string, ActionDefinition>;
    /** @internal */ session: AgentSession | null;
    /**
     * True when the host injected a `session` via config — disables
     * the agent's own auto-create / auto-load + auto-persist paths
     * because the session is owned upstream (typically `dddk.sessions`).
     * @internal
     */
    private sessionInjected;
    /** @internal */ currentSelection: SelectionContext | null;
    /** @internal */ currentIndexMap: Map<string, Element>;
    /** @internal */ navigateBridge: ((path: string) => void | Promise<void>) | null;
    /** @internal */ llmCallListener: ((info: LlmCallInfo) => void) | null;
    /** @internal */ askUserHandler: ((payload: AskUserPayload) => void) | null;
    /** @internal */ askUserChoiceHandler: ((payload: AskUserChoicePayload) => void) | null;
    /** @internal */ pauseHandler: ((payload: PausePayload) => void) | null;
    /** @internal */ surfaceMounter: ((payload: PresentSurfacePayload) => void) | null;
    private currentAbort;
    private pendingResolvers;
    private pendingOrder;
    private broadcastChannel;
    private crossTabKey;
    private pendingCounter;
    private destructivePatterns;
    /** Host signalled "end continuity now" — next runStream() starts fresh. */
    private continuityEnded;
    constructor(config: WebAgentConfig);
    /**
     * Context provider registry — one slot per `ContextRole`. SDK
     * ships defaults (wired in v0.2.0); hosts can replace
     * a single slot without re-implementing the others. v0.2.0.
     */
    /** @internal */ contextProviders: Map<ContextRole, ContextProvider>;
    /**
     * Register a tool. Returns a `ToolHandle` so the host can later
     * `handle.remove()` to unregister — useful when a feature module
     * is unmounted and its tool should disappear with it.
     *
     * Backward compat: the return value was `void` in v0.1; the
     * `ToolHandle` shape is additive so existing callers ignoring the
     * return keep working unchanged.
     *
     * Live semantics: the in-flight step finishes on its frozen action
     * snapshot, the next step / turn sees the new entry. There is no
     * "this turn must not see the new tool" guarantee — the action
     * map is read at each step boundary.
     */
    registerAction(action: ActionDefinition): ToolHandle;
    /** Alias for `registerAction` — symmetric with `registerContextProvider`
     *  + matches the "tool" wording the host-facing docs use. */
    registerTool(tool: ActionDefinition): ToolHandle;
    /**
     * Explicit unregister by name. Returns `true` when an action was
     * actually removed. Hosts who don't keep the `ToolHandle` around
     * can call this instead. v0.2.0.
     */
    unregisterAction(name: string): boolean;
    /**
     * Replace the producer for one context slot (`url`, `page_summary`,
     * `dom`, `screenshot`, `history`, `selection`). Returns a
     * `ContextProviderHandle` that restores the previous binding on
     * `remove()`. SDK defaults are installed lazily in v0.2.0;
     * registering here before defaults are wired still works — the
     * registered provider replaces the SDK default at lookup time.
     */
    registerContextProvider(role: ContextRole, provider: ContextProvider): ContextProviderHandle;
    /**
     * Drop a registered provider for `role`. Returns `true` when one
     * was removed. After removal, the SDK default (when present)
     * applies at lookup time. v0.2.0.
     */
    unregisterContextProvider(role: ContextRole): boolean;
    /** Update the locale used for confirmation copy + system-prompt output
     *  language hint. The currently-running turn keeps its prompt; the next
     *  turn picks up the new locale. */
    setLocale(locale: string): void;
    /** Set by the orchestrator — called when the agent picks `navigate`.
     *  Hosts may return a Promise (most SPA routers do); the webagent
     *  awaits it before declaring the navigation complete. */
    setNavigateBridge(fn: (path: string) => void | Promise<void>): void;
    /** Orchestrator wires this to emit `agent_llm_call` IntentEvents. */
    setLlmCallListener(fn: (info: LlmCallInfo) => void): void;
    getSession(): AgentSession | null;
    clearSession(): void;
    /**
     * Resolve a tool-call selector argument to a live element. Accepts
     * either a numeric index from the latest indexed DOM dump (`3` /
     * `"3"` / `"[3]"` / `"↓3"`) or a CSS selector string. Returns null
     * for invalid CSS, unknown indexes, or pre-DOM (SSR) environments.
     */
    resolveSelector(target: string | number): Element | null;
    isRunning(): boolean;
    /** End the continuity window now — next runStream() starts fresh. */
    endContinuity(): void;
    stop(): void;
    /**
     * Soft stop the loop while keeping the session "live" so the next
     * runStream(task) appends to it as a follow-up turn instead of starting
     * fresh. Use when the user interrupts the agent to deliver a NEW prompt
     * mid-task (palette open, voice hold) — naturally a continuation even
     * if the prior task was abandoned.
     *
     * Differs from `stop()`: status is set to `waiting` (which counts as
     * live in `isSessionLive`) instead of `idle`, so a host with
     * `sessionContinuityMs: 0` still gets continuity across the intentional
     * interrupt.
     */
    interruptForFollowup(): void;
    destroy(): void;
    /** Resolve the oldest pending host interaction (ask_user / ask_user_choice). */
    respond(answer: string | Record<string, unknown>): void;
    /**
     * Run a fresh task. If a session is still live within the continuity
     * window AND `opts.freshSession` is not set, the task is appended as
     * a follow-up user turn to the existing session instead.
     */
    runStream(task: string, opts?: RunOptions): AsyncIterable<AgentEvent>;
    /** Force-append as a follow-up turn (no continuity check). */
    continueStream(task: string, opts?: RunOptions): AsyncIterable<AgentEvent>;
    /**
     * Resume a saved session — used by the host's onMount when the page
     * reloaded mid-task or after SPA nav. Reads `loadSession()` first; if
     * the loaded session has a non-terminal status AND its `currentPage`
     * differs from the current URL, the loop picks back up.
     */
    resumeStream(): AsyncIterable<AgentEvent>;
    /** Orchestrator wires the UI route for ask_user. */
    setAskUserHandler(fn: (payload: AskUserPayload) => void): void;
    setAskUserChoiceHandler(fn: (payload: AskUserChoicePayload) => void): void;
    /** Orchestrator wires the UI route for the `pause` tool. Default
     *  behaviour (no handler set) falls back to the ask_user envelope. */
    setPauseHandler(fn: (payload: PausePayload) => void): void;
    /** Orchestrator wires the host mounter for `present_surface`. The
     *  mounter receives a PieceSurface + placement and renders the surface,
     *  calling `resolve({ value, cancelled })` once the user picks or
     *  dismisses. Only consulted when `allowPresent: true`. */
    setSurfaceMounter(fn: (payload: PresentSurfacePayload) => void): void;
    private startLoop;
    /** @internal */ get sessionRef(): AgentSession | null;
    /** @internal */ get configRef(): ResolvedConfig;
    /** @internal */ get actionsRef(): Map<string, ActionDefinition>;
    /** @internal */ get currentSelectionRef(): SelectionContext | null;
    /** @internal */ get navigateBridgeRef(): ((path: string) => void | Promise<void>) | null;
    /** @internal */ get llmCallListenerRef(): ((info: LlmCallInfo) => void) | null;
    /** @internal */ get askUserHandlerRef(): ((payload: AskUserPayload) => void) | null;
    /** @internal */ get askUserChoiceHandlerRef(): ((payload: AskUserChoicePayload) => void) | null;
    /** @internal */ get pauseHandlerRef(): ((payload: PausePayload) => void) | null;
    /** @internal */ get surfaceMounterRef(): ((payload: PresentSurfacePayload) => void) | null;
    /** @internal */
    setStatusInternal(status: AgentStatus): void;
    /** @internal */
    persistSessionInternal(): void;
    /** @internal */
    registerPendingResolverInternal(resolver: (raw: string) => void): string;
    /** @internal */
    needsConfirmationInternal(toolCall: ToolCall, matched: ActionDefinition | undefined, signal: AbortSignal): Promise<boolean>;
    /**
     * Resolve the effective description for an action, applying any
     * `actionOverrides` entry. Hard `description` wins over
     * `appendDescription`; both unset returns the SDK default verbatim.
     * Centralised so CoT (`buildCotToolRefs`) and classic (`buildToolDefinitions`)
     * paths can't drift in override behaviour.
     * @internal
     */
    resolveActionDescription(action: ActionDefinition): string;
    /**
     * Build the CoT tool reference list once per turn. Skipped from the
     * model's reference:
     *   - `pause` — CoT auto-pauses after every narrate; exposing the tool
     *     invites double-pauses.
     *   - `border` — element framing is done structurally via `narrate.about`
     *     (runtime auto-borders). Exposing the standalone tool creates two
     *     ways to do the same thing and the model picks inconsistently.
     *
     * Actions still live in `this.actions` so internal dispatch
     * (narrate.about, legacy executeLoop, host customActions) keeps working.
     * @internal
     */
    buildCotToolRefs(): CotToolRef[];
    /** @internal */
    buildToolDefinitions(): ToolDefinition[];
}

/**
 * Streaming envelope parser — scanner-based.
 *
 * The previous state-machine version bailed permanently the first time a
 * field's value spanned two SSE fragments (the readers returned `null` on
 * "incomplete" but the dispatcher treated null as a permanent failure).
 * In practice that meant nano — which emits the JSON char-by-char — bailed
 * on the very first long string (memory), so streaming "looked" enabled
 * but every turn fell back to JSON-parse-when-done.
 *
 * This rewrite is a forward-only buffer scanner. Every call to `feed()`:
 *
 *   1. Appends the new chars to `buf`.
 *   2. Walks the outer envelope object at depth=1, looking for `"<key>":`
 *      pairs we haven't emitted yet.
 *   3. For each known top-level key (memory / turn_planning / todo_adjust
 *      / todos_remaining / is_final), tries to read its value. If the
 *      value isn't fully in `buf` yet, leaves it alone — next `feed()`
 *      will see it grown and try again.
 *   4. For `actions`, scans the array element-by-element:
 *      - For each new partial action object (`{...` open, no `}` close
 *        yet), emits `narrate_delta` chars from inside its `"narrate":"..."`
 *        field as they arrive — that's the LIVE subtitle stream.
 *      - When the object's `}` lands, JSON.parse the slice, emit
 *        `action_start` + `about_complete` + `narrate_complete` +
 *        `tool_args_complete` synchronously, and advance past it.
 *   5. When the outer envelope's `}` lands, emits `envelope_complete`.
 *
 * There is NO bail. Malformed JSON triggers a single bail at the action
 * parse site and surfaces as `null` from `feed()` so the loop can fall
 * back to the JSON-parse path; otherwise the scanner is fully resumable.
 *
 * Performance: each `feed()` only re-scans from `scanPos` (cached
 * position), so cost is linear in TOTAL stream length even though the
 * full `buf` grows.
 */
type EnvelopeStreamEvent = {
    kind: 'memory_complete';
    value: string;
} | {
    kind: 'turn_planning_complete';
    value: {
        evaluation_previous_goal: string;
        next_goal: string;
    };
} | {
    kind: 'todo_adjust_complete';
    value: unknown;
} | {
    kind: 'todos_remaining_complete';
    value: string[];
} | {
    kind: 'action_start';
    index: number;
} | {
    kind: 'about_complete';
    index: number;
    value: string;
} | {
    kind: 'narrate_delta';
    index: number;
    delta: string;
} | {
    kind: 'narrate_complete';
    index: number;
    full: string;
} | {
    kind: 'tool_args_complete';
    index: number;
    tool: string;
    args: Record<string, unknown>;
} | {
    kind: 'is_final_complete';
    value: boolean;
} | {
    kind: 'envelope_complete';
};
declare class StreamingEnvelopeParser {
    private buf;
    private envelopeOpenedAt;
    private envelopeClosed;
    private envelopeCompleteEmitted;
    private bailed;
    private readonly emittedKeys;
    private actionsArrayOpenAt;
    private actionsArrayClosed;
    private nextActionIdx;
    private actionsScanCursor;
    private partialActionStart;
    private partialActionStarted;
    private partialNarrateEmittedLen;
    feed(delta: string): EnvelopeStreamEvent[] | null;
    finish(): EnvelopeStreamEvent[] | null;
    hasBailed(): boolean;
    private scan;
    private tryEmitTopLevelKey;
    /**
     * Walk the actions array. Emits action_start + per-field events for
     * each new complete action. While an action is still streaming open,
     * scans inside its narrate field and emits narrate_delta chars as
     * they arrive.
     */
    private scanActions;
    /**
     * For the partial action object at `pos`, look for `"narrate":"..."`
     * inside it and emit narrate_delta for any chars we haven't yet.
     *
     * Doesn't matter if we mis-find narrate boundaries inside other fields
     * — the readBalancedAt path is brace-aware, so when the full action
     * arrives we'll JSON.parse correctly and any over/under streaming
     * gets reconciled via the `partialNarrateEmittedLen` accounting (see
     * the action-complete path above).
     */
    private streamPartialNarrate;
    private findFirstNonWhitespace;
    private skipWhitespaceAndCommas;
    /**
     * Find `"<key>":` at depth=1 (i.e. directly inside the envelope's outer
     * `{`). Returns the position right after the `:` (with whitespace
     * skipped), or -1 if not found yet. Depth-aware so we don't match
     * keys-with-the-same-name nested inside object/array values.
     */
    private locateTopLevelValueStart;
    private findOuterCloseBrace;
    private readStringAt;
    private readBalancedAt;
    private readBoolAt;
}

/**
 * Visual overlays — highlight / border / spotlight / inject text on the page.
 * All overlay elements are tagged with data-webagent-overlay for easy cleanup.
 *
 * Repositioning: overlays auto-track their target element via a shared
 * MutationObserver + ResizeObserver + scroll listener. When the target's
 * bounding box changes (sticky-header reflow, scroll, virtualised list,
 * animation), the overlay repositions in-place rather than going stale.
 *
 * Auto-clear: overlays are wiped on `popstate` (history navigation) and
 * `beforeunload` (full page reload). dddk's orchestrator also clears them
 * on agent `done` / `error` for belt-and-braces cleanup.
 */

declare function highlight(target: Element | string, color?: string, label?: string): string;
declare function border(target: Element | string, color?: string, label?: string): string;
declare function spotlight(target: Element | string): string;
declare function inject(selector: string, text: string, position?: 'before' | 'after'): string;
declare function removeOverlay(id: string): void;
declare function clearOverlays(): void;
declare function listOverlays(): OverlayItem[];

/**
 * DOM Reader — indexed tabbed-tree serialiser.
 *
 * Every addressable element (interactive control, section-level
 * container, heading, image, code block) gets a monotonic numeric
 * index. The agent calls tools with that index directly
 * (`click("[3]")` / `border("[5]")`) — no CSS selectors, no
 * `:nth-of-type(4)`, no string-matching guesswork. The runtime keeps
 * an index→Element map for one turn and resolves indices on the next
 * tool dispatch.
 *
 * What gets indexed:
 *   - INTERACTIVE_TAGS — A, BUTTON, INPUT, SELECT, TEXTAREA, LABEL,
 *     SUMMARY, plus ANY element with an interactive ARIA role
 *     (button / link / tab / menuitem / option / checkbox / radio /
 *     switch / combobox / textbox / slider / spinbutton) or a
 *     keyboard-focusable tabindex with an accessible label.
 *   - HEADING_TAGS — H1..H6.
 *   - SECTION_TAGS — SECTION, ARTICLE, ASIDE, FIELDSET, MAIN, NAV,
 *     HEADER, FOOTER, HGROUP, TABLE, TR, FORM, DETAILS, DL, DIALOG.
 *     These also bump indentation so the tree shape is visible.
 *   - MEDIA_TAGS — IMG (emits alt text or filename hint).
 *   - PRE_TAGS — PRE (preserves newlines, capped).
 *
 * What gets emitted as flat content lines (no index):
 *   - NAMED_CONTENT_TAGS — P, LI, TD, TH, DT, DD, BLOCKQUOTE,
 *     FIGCAPTION, CAPTION, LEGEND, OUTPUT, METER, PROGRESS.
 *
 * What gets dropped entirely:
 *   - SKIP_TAGS — SCRIPT, STYLE, NOSCRIPT, TEMPLATE, IFRAME, SVG,
 *     CANVAS, SOURCE, TRACK, HEAD, META, LINK.
 *   - Elements with `class="dddk-skip"` or `data-dddk-skip` (host
 *     structural opt-out — site chrome, etc.).
 *   - Elements failing `isVisible` (display:none / visibility:hidden
 *     / zero box) — `display: contents` is a SPECIAL CASE: the wrapper
 *     has no box but children render, so we descend without depth bump.
 *
 * Output shape:
 *
 *   URL: https://example.com/commercial
 *   TITLE: Commercial — example
 *
 *   [1]<a href="/">Home</a>
 *   [2]<a href="/commercial">Commercial</a>
 *   [3]<section>
 *     <h1>Commercial cooperation</h1>
 *     <p>AGPL covers most teams …</p>
 *     [4]<section>
 *       01 · COMMERCIAL LICENSE
 *       <h2>Using dotdotduck in closed-source products</h2>
 *       <p>AGPL-3.0 requires …</p>
 *       <td>Personal</td>
 *       <td>Solo dev / <US$100K</td>
 *       <td>Free</td>
 *
 * Indentation is one tab per logical container (`<section>`,
 * `<article>`, `<aside>`, `<fieldset>`). Other wrappers (`<div>`,
 * `<span>`) don't add indentation — they're noise.
 *
 * Filtering opt-outs (and opt-ins) for hosts:
 *   - Element with class `dddk-skip` or attribute `data-dddk-skip`
 *     drops that element AND its subtree.
 *   - The `WebAgentConfig.domFilter` function applies on top of the
 *     class-based skip.
 */
interface DomReadOptions {
    maxLength?: number;
    includeInvisible?: boolean;
    scope?: HTMLElement;
    /**
     * Host-supplied subtraction filter. Called for every visible element
     * the walker considers; return `false` to drop the element AND its
     * subtree.
     *
     * Composes on top of the built-in class-based skip (elements with
     * `class="dddk-skip"` or `data-dddk-skip` are always dropped — hosts
     * use those for fast structural opt-outs without writing a function).
     */
    filter?: (el: Element) => boolean;
}
interface IndexedDomResult {
    /** Tab-indented text dump for the LLM. */
    text: string;
    /** Map from emitted stable ID → live DOM element. Tool handlers look
     *  up here when the LLM passes an `[id]` reference as the target.
     *  IDs are short alphanumeric hashes (e.g. `e4f3a`) computed from the
     *  element's tag + role + sibling position + first 30 chars of text,
     *  so the same element keeps the same ID across turns — fixing the
     *  cross-turn drift where `[5]` in turn N pointed at a different
     *  element than `[5]` in turn N+1. */
    indexMap: Map<string, Element>;
    /** Total bytes emitted (post-truncation). */
    bytes: number;
}
/**
 * Build the indexed-tabbed-tree dump + the index→element map for the
 * current document. Called once per agent turn — the map only needs to
 * live until the next tool dispatch, after which a fresh readDOM
 * overwrites it.
 */
declare function readDOM(opts?: DomReadOptions): IndexedDomResult;

/**
 * workflow actions.
 *
 * The agent needs hooks for the common patterns that show up when it
 * operates real product UIs:
 *
 *   - 2.5  `validate_form`        — after fill_input, read back the
 *                                   browser's constraint validation or
 *                                   the page's own `aria-invalid` /
 *                                   `.error` markers to know if the
 *                                   submission will be accepted.
 *   - 2.7  `wait_until`           — poll a CSS selector (or its visible
 *                                   state) up to a timeout. Used for
 *                                   modal close / async result render /
 *                                   spinner disappearance.
 *   - 2.8  `detect_login_wall`    — after navigation, check whether the
 *                                   destination looks like a sign-in
 *                                   wall (URL pattern, form fields,
 *                                   visible OAuth buttons). Emits the
 *                                   `auth_required` failure reason so
 *                                   the agent surfaces a sign-in request
 *                                   instead of clicking on Google's
 *                                   button on the user's behalf.
 *
 * These are deliberately small — composable primitives the LLM picks
 * one-at-a-time, not a multi-step transaction macro. The "multi-step
 * skill pattern" (2.6) lives at the Skill SDK layer, not as a single
 * tool call.
 */

interface ValidateFormParams {
    selector: string;
}
declare const validateForm: ActionDefinition<ValidateFormParams>;
interface WaitUntilParams {
    selector: string;
    /** `present` (default) / `visible` / `absent` */
    state?: 'present' | 'visible' | 'absent';
    /** Poll cap in ms. Hard ceiling 30s — long-running waits should be
     *  modelled as multi-turn (yield + come back) not single-action poll. */
    timeout?: number;
}
declare const waitUntil: ActionDefinition<WaitUntilParams>;
/**
 * Opt-in workflow actions. NOT pushed into the default `builtinActions`
 * list — host registers explicitly so the agent's prompt catalog stays
 * focused on actions the host actually uses.
 *
 *   import { workflowActions } from '@perhapxin/dddk/agent';
 *   new WebAgent({ ..., customActions: workflowActions });
 *
 * Or cherry-pick:
 *
 *   import { validateForm, waitUntil } from '@perhapxin/dddk/agent';
 *   new WebAgent({ ..., customActions: [validateForm] });
 */
declare const workflowActions: ActionDefinition[];

/**
 * Built-in actions — the narrator's hands. Visual overlays are first-class
 * here (border / highlight / spotlight) because the agent's job is to point
 * at things and then talk about them.
 *
 * The `show_subtitle` action was removed deliberately — between tool calls
 * the model emits free-form text which streams into the subtitle bar. There
 * is no `done` tool either; the loop ends when the model emits a turn with
 * no tool call (finish_reason=stop).
 */

/** ROADMAP 4.7: escalate to a human operator. Host wires the actual
 *  handoff (live chat, ticket, email) in their `escalate_to_human`
 *  action override; the bundled definition is a typed stub that emits
 *  the `agent_escalated` intent for analytics.
 *  Opt-in: NOT in `builtinActions`. Host registers via `customActions`. */
declare const escalateToHuman: ActionDefinition<{
    reason: string;
    context?: string;
}>;
/** ROADMAP 3.1: typed intent emission from agent. Lets the agent flag
 *  notable moments in a run for the host's analytics ("user explicitly
 *  asked about pricing", "agent recommended product X").
 *  Opt-in: NOT in `builtinActions`. Host registers via `customActions`. */
declare const trackIntent: ActionDefinition<{
    kind: string;
    payload?: Record<string, unknown>;
}>;
/**
 * The five actions every webagent host needs. Installed by default.
 *  - `narrate`: speak to the user (CoT envelope native; plain-protocol fallback)
 *  - `navigate`: route changes
 *  - `click`: interactive elements
 *  - `border`: visual pointing (also auto-synthesized by narrate's `about`)
 *  - `scroll_to`: paginated content
 *
 * `border` is bundled with narrate intentionally — narrate-with-about
 * synthesizes a border call, so the primitive must exist in the
 * registry for that synthesis to resolve. Hosts who never want to
 * point at things can still `excludeTools: ['border']`.
 */
declare const coreActions: ActionDefinition[];
/**
 * Form / input + richer pointer interactions. Opt in when the agent
 * needs to type, pick from selects, double-click, long-press, drag,
 * or hold keys. Off by default to keep the prompt slim on read-only
 * marketing / docs surfaces.
 *
 *  - `fill_input` / `select_option` / `clear_input`: text fields + selects
 *  - `press_key`: single keypress (Enter / Escape / Tab / Cmd+S chord)
 *  - `hold_key`: key down for N ms (hold-to-zoom, hold-Ctrl-to-multi-select)
 *  - `double_click`: open / expand / rename — anything bound to `dblclick`
 *  - `long_press`: context menus, drag handles, mobile long-press
 *  - `drag`: from element A to element B (sortable lists, kanban, sliders)
 */
declare const formActions: ActionDefinition[];
/**
 * Control-flow actions — waiting, pausing, asking the user. Opt in
 * for conversational agents. Auto-pause-after-narrate is independent
 * (controlled by `disableAutoPauseAfterNarrate`).
 */
declare const flowActions: ActionDefinition[];
/**
 * Less-common visual / escalation actions. `highlight` is a paint
 * overlay (vs `border`'s frame) — was historically dropped from
 * default because the LLM couldn't reliably pick one. `track_intent`
 * is for hosts wiring custom analytics tunnels. `escalate_to_human`
 * is for support flows. `present_surface` is registered separately
 * via `allowPresent` + `setSurfaceMounter`.
 */
declare const extraActions: ActionDefinition[];
/**
 * Union of all bundles EXCEPT `present_surface` (which needs explicit
 * `allowPresent` + a mounter). Pass to `customActions` to restore
 * pre-v0.2 "install everything" behaviour.
 */
declare const builtinActions: ActionDefinition[];

/**
 * form widget adapter registry.
 *
 * Real product forms wrap their inputs in UI-library widgets:
 * react-select, antd Select, MUI Autocomplete, headless-ui Listbox,
 * Chakra DatePicker. The actual <input> behind the widget is hidden
 * or proxied through a custom handler, so the SDK's `fill_input` /
 * `select_option` defaults (set .value + dispatch input event) don't
 * actually update the widget's internal state.
 *
 * This registry lets a host plug in matchers + fillers for the
 * widget libraries their product actually uses. The runtime walks
 * registered widgets in priority order BEFORE the default fill path;
 * first match wins.
 *
 *   import { registerFormWidget } from '@perhapxin/dddk';
 *   registerFormWidget({
 *     id: 'react-select',
 *     priority: 100,
 *     match: (el) => el.closest('.react-select__control') != null,
 *     fill: async (el, value, ctx) => {
 *       const control = el.closest('.react-select__control')!;
 *       control.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
 *       await ctx.wait(60);
 *       const opt = [...document.querySelectorAll('.react-select__option')]
 *         .find((o) => o.textContent?.trim() === value);
 *       opt?.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
 *       return opt != null;
 *     },
 *   });
 *
 * The default fallback (set .value + dispatch input) is unchanged for
 * vanilla <input> / <textarea> / <select> — only non-trivial widgets
 * need adapters.
 */
interface FormWidgetFillContext {
    /** Polite delay between DOM events. Always use this, not setTimeout,
     *  so the agent's abort signal can interrupt long fills. */
    wait(ms: number): Promise<void>;
    /** Async fill triggered by an agent — for sub-fill on dependent fields. */
    signal: AbortSignal;
}
interface FormWidgetAdapter {
    /** Stable id — same string overwrites prior registration. */
    id: string;
    /** Higher priority wins when multiple match. Default 0. */
    priority?: number;
    /** Predicate: does this adapter own this input element? */
    match(el: Element): boolean;
    /** Fill the widget. Return true if the value landed. */
    fill(el: Element, value: string, ctx: FormWidgetFillContext): Promise<boolean>;
}
declare function registerFormWidget(adapter: FormWidgetAdapter): void;
declare function unregisterFormWidget(id: string): boolean;
declare function listFormWidgets(): FormWidgetAdapter[];
/**
 * Find the first registered adapter that matches `el` (by priority),
 * or null if no custom widget applies — caller falls back to the default
 * `.value + input event` path.
 */
declare function findFormWidget(el: Element): FormWidgetAdapter | null;

/**
 * Default destructive-action pattern list.
 *
 * Any tool whose name matches one of these regexes is auto-gated on a
 * `confirm` event before its handler runs. Hosts can override via
 * `WebAgentConfig.destructivePatterns`; per-action
 * `requireConfirmation: false` opts a single action out of the pattern
 * match even when its name would match.
 *
 * The list captures the verbs that show up across CRUD apps, billing
 * surfaces, comms, and account lifecycle — actions whose effect a user
 * cannot trivially undo by clicking around.
 */
declare const DEFAULT_DESTRUCTIVE_PATTERNS: RegExp[];

/**
 * @perhapxin/dddk — Public types
 * See ../docs/01-architecture.md for the full design.
 */
/**
 * BCP-47-ish language tag — `'en'`, `'zh-TW'`, `'ja-JP'`, `'es'`, etc.
 *
 * dddk's bundled UI strings (subtitle button labels, dock hints, inline-AI
 * action labels) ship `'en'` + `'zh-TW'` translations as defaults; unknown
 * tags fall back to `'en'`. Hosts add their own languages by passing an
 * `i18n` dict that maps the tag to a translation object — see
 * `DotDotDuckConfig.i18n` and `I18nDict`. There is no compile-time lock
 * on the value: any string a real product would use is accepted.
 */
type Locale = string;
type SubtitleType = 'voice' | 'selection' | 'agent' | 'post' | 'info';
interface SubtitleShowOptions {
    text: string;
    type: SubtitleType;
    onAccept?: () => void;
    onReject?: () => void;
    onCancel?: () => void;
    onCopy?: () => void;
    hints?: string;
    autoHide?: number;
    /**
     * Maximum characters shown per page before paging kicks in. When `text`
     * exceeds this length the subtitle is split on sentence boundaries
     * (`.` / `。` / `!` / `?` / newlines) into pages and the user advances
     * with Space. The accept / reject callbacks fire on the LAST page —
     * earlier pages just advance. Set to `0` to disable paging entirely
     * (render the whole text in one shot). Default `220` — about three
     * lines on the standard subtitle bar.
     */
    maxCharsPerPage?: number;
    /**
     * When `true`, the subtitle bar refuses every dismissal except the
     * explicit accept / reject gestures (Space / double-tap Space) wired
     * via `onAccept` / `onReject`. The × close button is hidden, Esc is
     * ignored, click-outside is ignored, and any-key dismiss is disabled.
     *
     * Use for cases where the host MUST collect a user signal before the
     * bar can go — the end-of-loop feedback closure is the canonical
     * example. Don't use for normal action subtitles; users expect Esc
     * to work as an escape valve everywhere else.
     *
     * Default `false`.
     */
    persistent?: boolean;
}
/**
 * Options for the multi-choice subtitle (`Subtitle.showChoice(...)`).
 *
 * Renders the question + an ordered list of options. Each option can be
 * picked by clicking, by pressing the digit `1..N`, or — when voice is
 * active — by speaking the option text. Esc cancels.
 *
 * `allowFreeText` (default `true`) appends a trailing free-text input
 * after the options so the user can answer outside the predefined
 * choices. On submit the typed value is delivered to `onChoose` with
 * `index === -1` so the caller can distinguish free-text answers from
 * canonical picks.
 */
interface SubtitleChoiceOptions {
    /** The prompt itself — naturally spoken sentence. */
    question: string;
    /** The selectable choices. 2–4 canonical options + optional "Other" slot. */
    options: string[];
    /** Default `true`. When false, no free-text input is shown. */
    allowFreeText?: boolean;
    /** Placeholder shown in the free-text input. Default localised. */
    freeTextLabel?: string;
    /**
     * Fires when the user makes a pick. `index` is the position in
     * `options` (0-based) for canonical picks, OR `-1` for a free-text
     * answer (in which case `value` is the typed string).
     */
    onChoose: (value: string, index: number) => void;
    /** Esc / backdrop dismiss. */
    onCancel?: () => void;
    /** Auto-hide timeout in ms. Default: stays until interacted with. */
    autoHide?: number;
}
type DddkEventName = keyof DddkEventMap;
/**
 * Unified intent event — emitted on every user decision / activation that
 * carries product-analytics meaning. Subscribe once via `dddk.on('intent', ...)`
 * and feed straight into your analytics pipeline.
 */
type IntentEvent = {
    kind: 'palette_activated';
    itemId: string;
    arg?: string;
    selectionText?: string;
    attachmentsCount: number;
    timestamp: number;
} | {
    kind: 'agent_asked';
    question: string;
    timestamp: number;
} | {
    kind: 'agent_answered';
    question?: string;
    answer: string;
    via: 'gesture' | 'voice' | 'text' | 'mobile-button';
    latencyMs?: number;
    timestamp: number;
}
/**
 * One emit per LLM streaming call inside an agent run. Carries
 * per-call speed metrics for the dashboard:
 *   - `ttftMs`     time-to-first-token (request sent → first delta)
 *   - `durationMs` total stream wall-time (request sent → last delta)
 *   - `outputTokens` provider-reported output token count (when available)
 *   - `inputTokens`  provider-reported input token count
 *   - `tokensPerSec` outputTokens × 1000 / durationMs (host-computed; 0 if missing)
 * `runId` joins back to the agent run. `model` is the resolved provider
 * model id when available, otherwise omitted.
 */
 | {
    kind: 'agent_llm_call';
    runId: string;
    role: 'webagent' | 'vision';
    ttftMs: number;
    durationMs: number;
    outputTokens?: number;
    inputTokens?: number;
    tokensPerSec?: number;
    model?: string;
    timestamp: number;
} | {
    kind: 'confirm_action';
    actionName: string;
    params: Record<string, unknown>;
    approved: boolean;
    timestamp: number;
} | {
    kind: 'voice_captured';
    text: string;
    cleanedText?: string;
    timestamp: number;
} | {
    kind: 'selection_used';
    selectionText: string;
    selectorHint?: string;
    itemId: string;
    timestamp: number;
} | {
    kind: 'skill_started';
    skillId: string;
    timestamp: number;
} | {
    kind: 'skill_finished';
    skillId: string;
    timestamp: number;
}
/**
 * Fired when an agent run begins (user submitted a query, either
 * fresh or as a follow-up). `runId` ties every downstream intent in
 * the same run together so dashboards can group by run without
 * relying on time-windowing.
 */
 | {
    kind: 'agent_run_started';
    runId: string;
    task: string;
    sessionId: string;
    timestamp: number;
}
/**
 * Fired when an agent run terminates cleanly (the loop ended on its
 * own — empty actions / no tool call). Pairs with `agent_run_started`
 * via `runId`.
 */
 | {
    kind: 'agent_run_completed';
    runId: string;
    sessionId: string;
    turnCount: number;
    timestamp: number;
}
/**
 * Fired when the user explicitly halts a running agent (× button on
 * the bar, Esc, double-tap Space reject, palette open mid-run,
 * long-press voice mid-run). `reason` names which path triggered the
 * stop so dashboards can distinguish "user changed their mind" from
 * "user got frustrated".
 */
 | {
    kind: 'agent_run_stopped';
    runId: string;
    sessionId: string;
    reason: 'close' | 'esc' | 'reject' | 'palette' | 'voice' | 'unknown';
    timestamp: number;
}
/**
 * Fired after every CoT-mode narration when the runtime's auto-pause
 * resolves. `decision: 'continue'` = user pressed Space; `'stop'` =
 * user double-tapped Space to reject. Lets dashboards see WHERE in
 * the run the user got bored / chose to stop.
 */
 | {
    kind: 'agent_pause_decision';
    runId: string;
    decision: 'continue' | 'stop';
    timestamp: number;
}
/**
 * v0.2.0. Emitted when a tool handler returns
 * `{ ok: false }` (or throws — `reason: 'unknown'`, message in
 * `message`). Fills the visibility gap where the lifecycle's
 * `agent_tool_start` / `agent_tool_end` events fire on the host
 * emitter but never landed in the intent stream — dashboards
 * couldn't see which tools failed, why, or how often. `runId`
 * joins back to `agent_run_started`.
 */
 | {
    kind: 'agent_tool_failed';
    runId: string;
    name: string;
    reason: ActionFailureReason;
    message?: string;
    timestamp: number;
}
/**
 * End-of-loop closure response. `satisfied: true` = Space accept;
 * `false` = double-tap reject; `null` = picker selection (value in
 * `summary`). `runId` joins back to `agent_run_started`; `skillId` set
 * when a skill triggered the run.
 */
 | {
    kind: 'agent_feedback';
    runId?: string;
    skillId?: string;
    satisfied: boolean | null;
    summary: string;
    timestamp: number;
}
/**
 * Host-defined event emitted via the public
 * `dddk.track(name, props?)` API. Goes through the same intent
 * stream as the typed events; downstream sinks treat it like any
 * other intent.
 */
 | {
    kind: 'custom_track';
    name: string;
    props: Record<string, unknown>;
    timestamp: number;
}
/**
 * Fired when the agent explicitly hands off to
 * a human operator via the `escalate_to_human` action. `runId`
 * ties back to the originating run.
 */
 | {
    kind: 'agent_escalated';
    runId?: string;
    reason: string;
    context?: string;
    timestamp: number;
};
interface DddkEventMap {
    palette_open: {
        selection: string;
    };
    voice_start: void;
    voice_end: {
        text: string;
    };
    gesture_accept: void;
    gesture_reject: void;
    gesture_escape: void;
    pointer_ring_show: {
        selector: string;
    };
    pointer_ring_hide: void;
    pointer_lock: {
        selector: string;
        element: HTMLElement;
    };
    pointer_lasso: {
        elements: HTMLElement[];
        bounds: DOMRect;
        screenshot?: string;
    };
    skill_start: {
        skillId: string;
    };
    skill_step: {
        skillId: string;
        stepIndex: number;
    };
    skill_done: {
        skillId: string;
    };
    surface: {
        surface: unknown;
        placement: SurfacePlacement;
    };
    agent_start: {
        task: string;
    };
    /** Emitted at every LLM call boundary (between tool dispatches). */
    agent_thinking: void;
    /** Emitted right before a tool's handler runs. */
    agent_tool_start: {
        name: string;
        args: Record<string, unknown>;
        targetSelector?: string;
    };
    /** Emitted after a tool's handler returns. */
    agent_tool_end: {
        name: string;
        result: ActionResult;
    };
    /** Emitted when the agent run completed naturally (no more tool calls). */
    agent_final: void;
    /** Emitted when the agent run failed terminally. */
    agent_error: {
        error: Error;
    };
    intent: IntentEvent;
}
type DddkEventHandler<E extends DddkEventName> = (payload: DddkEventMap[E]) => void;
/**
 * Synchronous key/value storage adapter. dddk depends on synchronous reads
 * for first-paint scenarios (theme, language, preferences) — async-only stores
 * cannot be plugged in directly. Wrap them with an in-memory hydration layer
 * (read once at startup, persist async behind the scenes).
 */
interface StorageAdapter$1 {
    get(key: string): string | null;
    set(key: string, value: string): void;
    remove(key: string): void;
}
type I18nDict = Record<string, Record<string, string>>;

/**
 * Skill preferences — declarative per-skill settings.
 *
 * When a skill declares preferences, dddk:
 *   1. Refuses to run the skill until all `required: true` prefs are filled.
 *   2. Auto-renders a setup form (as a Surface) the first time.
 *   3. Stores values keyed by skill id via the dddk StorageAdapter.
 *   4. Provides `ctx.getPreferences<T>()` inside the skill handler.
 */

type PreferenceKind = 'text' | 'password' | 'number' | 'checkbox' | 'select';
interface PreferenceField {
    name: string;
    title: string;
    kind: PreferenceKind;
    description?: string;
    required?: boolean;
    default?: unknown;
    placeholder?: string;
    /** For 'select' kind. */
    options?: Array<{
        value: string;
        label: string;
    }>;
}
interface PreferenceSchema {
    skillId: string;
    fields: PreferenceField[];
}
interface PreferenceContext {
    get<T = Record<string, unknown>>(): T;
    set(values: Record<string, unknown>): void;
    isComplete(): boolean;
    missingRequired(): PreferenceField[];
}
declare class PreferenceStore {
    private storage;
    private locale?;
    constructor(storage: StorageAdapter$1, locale?: string | undefined);
    private keyOf;
    read(skillId: string): Record<string, unknown>;
    write(skillId: string, values: Record<string, unknown>): void;
    remove(skillId: string): void;
    contextFor(schema: PreferenceSchema): PreferenceContext;
    /** Build a Surface (flat envelope shape) representing the setup form. */
    buildSetupSurface(schema: PreferenceSchema): {
        version: 'v0.10';
        updateComponents: {
            surfaceId: string;
            catalogId: string;
            components: Array<Record<string, unknown>>;
        };
        updateDataModel: {
            data: Record<string, unknown>;
        };
    };
}

/**
 * Skill type definitions — 4 kinds: Script / Prompt / Action / Surface
 * See ../../docs/05-skills-sdk.md for the full design.
 */
interface ScriptStep {
    page?: string;
    subtitle?: string;
    action?: (tools: SkillTools) => void | Promise<void>;
    waitForUser?: boolean;
}
interface SkillTools {
    navigate(path: string): void;
    highlight(selector: string, color?: string, label?: string): string;
    border(selector: string, color?: string, label?: string): string;
    spotlight(selector: string): string;
    inject(selector: string, text: string, position?: 'before' | 'after'): string;
    subtitle(text: string): void;
    clearOverlays(): void;
    ask(question: string): Promise<string>;
    wait(ms: number): Promise<void>;
    llm?(prompt: string): Promise<string>;
    runSkill?(id: string, vars?: Record<string, string>): Promise<void>;
    /**
     * Show an ad-hoc Surface (form / dialog / picker) mid-script and await the
     * user's submission. Resolves with the form data when the host calls
     * `dddk.submitSurface(data)`, or `null` if the user cancels via
     * `dddk.cancelSurface()` / Esc.
     *
     * The surface argument is a `PieceSurface` (root PieceNode + optional data).
     * `placement` defaults to `'modal'` (full-screen popup); use `'subtitle'`
     * for the subtitle bar, `'dock'` for a persistent side panel.
     */
    surface(surface: unknown, opts?: {
        placement?: SurfacePlacement;
    }): Promise<Record<string, unknown> | null>;
}
/**
 * Surface placement (revised 2026-05-22).
 *
 * - `palette`  — render inside an active PanelSkill's content area
 * - `subtitle` — render in the existing subtitle bar (lightest, ignorable)
 * - `dock`     — persistent side panel, user can minimize/close
 * - `modal`    — full-screen popup with backdrop (canonical "popup", supports forms)
 */
type SurfacePlacement = 'palette' | 'subtitle' | 'dock' | 'modal';
interface BaseSkill {
    id: string;
    name: string;
    description?: string;
    icon?: string;
    /** Hide from palette listing (still callable). */
    hidden?: boolean;
    /** Function returning whether this skill is currently visible to the user. */
    visible?: (ctx: {
        user?: unknown;
    }) => boolean;
    /**
     * Declarative preferences. If any `required: true` field is unfilled,
     * dddk auto-renders a setup Surface form before dispatching the skill.
     * See ./preferences.ts
     */
    preferences?: Array<PreferenceField>;
}
interface ScriptSkill extends BaseSkill {
    type: 'script';
    steps: ScriptStep[];
}
interface PromptSkill extends BaseSkill {
    type: 'prompt';
    /** System prompt or prompt template. Use `{{var}}` placeholders. */
    prompt: string;
    variables?: Record<string, string>;
}
interface ActionSkillContext {
    palette: {
        close(): void;
        replace(items: Array<{
            id: string;
            name: string;
            handler: () => void;
        }>): void;
    };
    subtitle: {
        show(opts: {
            text: string;
            type?: string;
            autoHide?: number;
        }): void;
        hide(): void;
    };
    storage: {
        get<T = string>(key: string): T | null;
        set(key: string, value: unknown): void;
    };
    /** Read this skill's declared preferences (empty object if no schema). */
    getPreferences<T = Record<string, unknown>>(): T;
    llm?(prompt: string): Promise<string>;
    agent?(task: string): void;
    navigate(path: string): void;
}
interface ActionSkill extends BaseSkill {
    type: 'action';
    handler: (ctx: ActionSkillContext) => void | Promise<void>;
}
interface SurfaceSkillContext extends ActionSkillContext {
}
interface SurfaceSkill extends BaseSkill {
    type: 'surface';
    build: (ctx: SurfaceSkillContext) => Promise<unknown>;
    onSubmit?: (data: Record<string, unknown>, ctx: SurfaceSkillContext) => Promise<unknown> | unknown;
}
interface PanelSkillContext extends ActionSkillContext {
    /** Render a new PieceSurface into the panel area. */
    render(surface: unknown): void;
    /** Pop this panel skill off the navigation stack. */
    back(): void;
    /** Update the input box's placeholder. */
    setPlaceholder(text: string): void;
}
interface PanelSkill extends BaseSkill {
    type: 'panel';
    /**
     * `palette`  — keep slash-command routing + ask-AI fallback; free-text goes
     *              to onInput. Best for search / recommend / qa / classify.
     * `takeover` — input is purely passed to onInput. No command parsing.
     *              Best for chat / continuous webagent.
     */
    inputMode: 'palette' | 'takeover';
    /** Custom placeholder for the input box while in this skill. */
    inputPlaceholder?: string;
    /** Called once when the skill is entered (empty input). */
    onEnter?: (ctx: PanelSkillContext) => Promise<unknown> | unknown;
    /** Called on every input change (debounced by the palette renderer). */
    onInput: (text: string, ctx: PanelSkillContext) => Promise<unknown> | unknown;
    /** Called when the user submits (Enter). Optional; many panels use onInput live. */
    onSubmit?: (text: string, ctx: PanelSkillContext) => Promise<unknown> | unknown;
    /** Called when the user activates a piece action inside the panel. */
    onAction?: (action: string, data: unknown, ctx: PanelSkillContext) => Promise<unknown> | unknown;
    /** Called when the skill is popped from the stack. */
    onLeave?: () => Promise<void> | void;
}
type Skill = ScriptSkill | PromptSkill | ActionSkill | SurfaceSkill | PanelSkill;

/**
 * Prompt registry — one place to see, override, and localise every LLM
 * system prompt the SDK ships.
 *
 * Motivation. Before this file, prompts lived inline in ~10 subsystem
 * modules (webagent narrator, planner, InlineAgent, markdown-edit,
 * immersive-translate, voice-cleanup, Dwell classifier, task runner).
 * A host that wanted "Japanese prompts" or "no persona line" had to
 * spelunk each module. The registry consolidates all defaults behind
 * stable IDs and gives hosts three levers:
 *
 *   - `override(id, locale, render)` — full replace for one locale.
 *   - `append(id, render)`           — extra content stitched on the end.
 *   - `list()` / `has(id)`           — introspection.
 *
 * Locale fallback. `render(id, ctx, locale)` prefers a locale-specific
 * override, falls back to the `'en'` override, then to the SDK-registered
 * default. So a host can localise EN + zh-TW + ja without touching the
 * defaults for locales they don't care about.
 *
 * Non-goals. The registry does NOT parse or execute the prompt; it just
 * assembles the string. Runtime message plumbing (system role, temp,
 * tool schemas) stays in the subsystem callsites.
 */
/**
 * A prompt renderer. Receives an arbitrary context object (subsystem-
 * specific — e.g. the WebAgent narrator gets `PromptContext` with brand
 * + persona + sitemap; the InlineAgent gets nothing) and the effective
 * locale. Returns the full system prompt string.
 */
type PromptRender<Ctx = unknown> = (ctx: Ctx, locale: string) => string;
declare class PromptRegistry {
    private defaults;
    private overrides;
    private appenders;
    /**
     * Register the SDK-shipped default for a prompt id. Called at module
     * init by the subsystem that owns the prompt (see `./defaults.ts`).
     * Hosts typically don't call this — they use `override()` instead.
     */
    registerDefault<Ctx = unknown>(id: string, render: PromptRender<Ctx>): void;
    /**
     * Replace the SDK default for one locale. Later calls with the same
     * `(id, locale)` win — hosts can rebind at runtime (e.g. after the
     * user changes site language).
     *
     * @example
     *   dddk.prompts.override('inline-edit.system', 'ja', () => `あなたは…`);
     */
    override<Ctx = unknown>(id: string, locale: string, render: PromptRender<Ctx>): void;
    /**
     * Append extra content on the end of the resolved prompt. Runs for
     * every locale — good for site-wide reminders ("always cite sources",
     * "never mention pricing") that shouldn't require re-writing the
     * whole prompt. Multiple `append()` calls stack in registration order.
     */
    append<Ctx = unknown>(id: string, extra: PromptRender<Ctx>): void;
    /**
     * Resolve a prompt id to its final string. Order of preference:
     *   1. `override(id, locale)` — exact locale match
     *   2. `override(id, 'en')`   — English fallback
     *   3. `registerDefault(id)`  — SDK default
     * All matching `append()` extras are joined on with double-newlines.
     */
    render<Ctx = unknown>(id: string, ctx?: Ctx, locale?: string): string;
    /** Is there any renderer (default or override) for this id? */
    has(id: string): boolean;
    /** All registered ids, sorted for stable output. */
    list(): string[];
    /**
     * Drop all overrides + appenders for one id. Does NOT touch the
     * default — that stays as the SDK shipped it. Useful for test setup /
     * "reset to defaults" UI in a host tuning tool.
     */
    reset(id: string): void;
}

/**
 * GestureManager — unified space-based gesture system.
 * See ../../docs/02-space-gesture.md for the full design.
 *
 * Detects:
 *   - Single space tap (<150ms hold, 350ms gap) → accept
 *   - Double space tap (two taps <350ms) → reject
 *   - Long space press (>150ms) → voice start
 *   - Tab → accept next line (when subtitle showing)
 *   - Escape → dismiss
 *   - Ctrl+K / Cmd+K → command palette
 *   - Ctrl+Space (in input) → accept while typing
 *
 * Space is ONLY intercepted when shouldIntercept() returns true
 * (i.e. there's a pending UI awaiting user response).
 */
interface GestureCallbacks {
    onAccept: () => void;
    onReject: () => void;
    onAcceptLine: () => void;
    onVoiceStart: (selection: string, images: string[]) => void;
    onVoiceEnd: () => void;
    onPaletteToggle: (selection: string) => void;
    onEscape: () => void;
}
interface GestureManagerOptions {
    callbacks: GestureCallbacks;
    /** Function called on every space keydown to decide whether to intercept. */
    shouldIntercept?: () => boolean;
    /** Legacy: use 'ctrl' for backwards-compat with old Ctrl-based UI. Default 'space'. */
    gestureKey?: 'space' | 'ctrl';
    /**
     * How long the user must hold the gesture key before voice_start fires.
     * Default 250ms. Lower = more responsive but easier to mis-trigger on
     * fast prose typing; higher = less mis-trigger but voice feels laggy.
     */
    holdThresholdMs?: number;
    /**
     * Window for "two taps in this many ms → reject" detection. Default
     * 350ms. Raise if users with slower fingers can't reliably double-tap;
     * lower for power users who want reject to fire snappier.
     */
    doubleTapWindowMs?: number;
}
declare class GestureManager {
    private callbacks;
    private shouldIntercept;
    private gestureKey;
    private holdThresholdMs;
    private doubleTapWindowMs;
    private holdTimer;
    private tapTimer;
    private lastTapAt;
    private isHolding;
    /**
     * Set on space-keydown inside an input field. If user releases before the
     * hold threshold, we insert the missing space character manually (since we
     * preventDefault'd the keydown to keep voice-hold possible). If the hold
     * threshold fires, voice triggers without any space being inserted —
     * which is the desired behavior for "long-press to dictate".
     */
    private pendingSpaceInput;
    /**
     * Disposer for the per-hold reactive guard that watches the focused
     * input for unexpected value changes during voice. Set when voice
     * triggers, called from `handleKeyUp` when the user releases. The
     * guard's job is to revert any character the OS-level IME slips into
     * the input despite `readOnly = true` — bullet-proofing against Edge
     * + Microsoft Bopomofo, which on some builds writes one stray space
     * AFTER readOnly is set (in-flight queued keystroke from the 250ms
     * detection window).
     */
    private holdRevertDispose;
    private cleanups;
    /** Set by host when a suggestion/subtitle/surface is visible. Enables accept/reject/tab. */
    hasSuggestion: boolean;
    constructor(opts: GestureManagerOptions);
    start(): void;
    destroy(): void;
    /**
     * Read currently selected text (live, from DOM/input). Always queried
     * at the moment of the gesture — no cached state. Previously we kept
     * a `lastSelection` mirror updated by selectionchange / mouseup, but
     * that cache survived SPA navigation and leaked the previous page's
     * selection into the next page's first Ctrl+K. The fix is to never
     * cache: if the browser has live selection at gesture time, use it;
     * otherwise the gesture has no selection context.
     */
    captureSelection(): string;
    captureImages(): string[];
    private handleKeyDown;
    private handleKeyUp;
    private matchesGestureKey;
    private cancelHold;
    private readSelection;
}

/**
 * HeatRank — frequency × recency scoring for palette items, recent files,
 * snippet suggestions, etc.
 *
 * Algorithm: each "visit" adds a unit boost that decays exponentially over
 * `halfLifeMs`. Total score = sum of decayed visit weights.
 *   score(now) = Σ (0.5 ^ ((now - visitedAt) / halfLifeMs))
 *
 * Sorted descending → most-recently-and-frequently-used items float to top.
 *
 * Storage is opaque — caller passes a `read/write` adapter. Default uses
 * an in-process Map (lost on reload). For persistence, wire to the dddk Cache.
 */
interface HeatRankAdapter {
    read(scope: string): Record<string, number[]>;
    write(scope: string, data: Record<string, number[]>): void;
}
interface HeatRankOptions {
    /** Identifier scoping ranks (e.g. 'palette', 'recent-files'). */
    scope?: string;
    /** Time in ms for visit weight to halve. Default 7 days. */
    halfLifeMs?: number;
    /** Cap on visits kept per item — prevents unbounded growth. Default 20. */
    maxVisitsPerItem?: number;
    /** Adapter for persistence. Defaults to in-memory. */
    adapter?: HeatRankAdapter;
}
declare class HeatRank {
    private scope;
    private halfLifeMs;
    private maxVisitsPerItem;
    private adapter;
    constructor(opts?: HeatRankOptions);
    /** Record a usage event for the given id. */
    visit(id: string): void;
    /** Current score for one id. */
    score(id: string, now?: number): number;
    /** Sort items in descending score. Items not yet visited go last (via fallbackCompare). */
    sort<T>(items: T[], idOf: (item: T) => string, fallbackCompare?: (a: T, b: T) => number): T[];
    /** Drop scoring data for one item. */
    forget(id: string): void;
    /** Drop all scoring data in this scope. */
    reset(): void;
}

/**
 * Pieces — dddk's UI primitive system.
 *
 * Like HTML elements, but a curated set covering common SaaS UI patterns,
 * plus a `Slot` escape hatch for host-supplied components.
 *
 * Two ways to author the same UI:
 *   1. Direct API:  Pieces.Card({ children: [Pieces.Heading({ text: 'Hi' })] })
 *   2. Flat envelope (id-keyed component list): { component: 'Card', children: [{ component: 'Heading', text: 'Hi' }] }
 *
 * Both paths resolve through the same PieceRenderer with the same catalog.
 */

/** Discriminated piece — `kind` selects the catalog entry. */
interface PieceNode {
    kind: string;
    /** Optional id, used to address nodes for partial updates. */
    id?: string;
    /** Optional binding path (JSON Pointer or simple key) into the data model. */
    bind?: string;
    /** Catalog-specific props. */
    [key: string]: unknown;
}
interface PieceContext {
    /** Reactive data model (mutated by inputs, read by `bind`). */
    data: Record<string, unknown>;
    /** Update a bound value. */
    setBinding(path: string, value: unknown): void;
    /** Fire a named action — e.g. 'submit', 'cancel', or any custom string. */
    trigger(actionName: string, payload?: unknown): void;
    /** Render a child PieceNode (recursive). */
    render(node: PieceNode): ReactNode;
}
interface PieceDefinition<P = Record<string, unknown>> {
    kind: string;
    /**
     * Render function. Returns React node OR a DOM element factory for
     * non-React hosts (advanced — most users return JSX).
     */
    render(props: P & PieceNode, ctx: PieceContext): ReactNode;
    /**
     * Optional JSON Schema for props — useful when an LLM agent authors the
     * piece from an envelope (the schema gives the LLM a contract).
     */
    propsSchema?: Record<string, unknown>;
    /**
     * Optional display metadata for tooling (palette previews, docs).
     */
    meta?: {
        category: 'layout' | 'content' | 'data' | 'input' | 'action' | 'feedback' | 'slot';
        description?: string;
    };
}
declare class PieceCatalog {
    private pieces;
    constructor(initial?: PieceDefinition[]);
    register(piece: PieceDefinition): void;
    get(kind: string): PieceDefinition | undefined;
    list(): PieceDefinition[];
    /**
     * Merge another catalog into this one. Host's custom catalog wins on
     * conflict — lets enterprises extend / override built-ins.
     */
    extend(other: PieceCatalog | PieceDefinition[]): void;
}
/**
 * A complete UI surface — root piece + optional initial data model.
 * Output of a skill, palette command, or external envelope translation.
 */
interface PieceSurface {
    root: PieceNode;
    data?: Record<string, unknown>;
}

/**
 * ActionPanel — typed action system for palette items.
 *
 * Each palette result can carry multiple actions:
 *  - primary (⏎)         — the first action, runs on Enter
 *  - secondary (Ctrl+⏎)  — the second action
 *  - others (Ctrl+K)     — opens a sub-panel listing the rest
 *
 * Actions are typed so the palette renders the right icon and handles the
 * right side-effect (copy, open URL, navigate, run skill, …) without each
 * command author re-implementing them.
 */
type PaletteAction = CopyAction | InsertAction | OpenUrlAction | NavigateAction | AgentTaskAction | RenderSurfaceAction | RunSkillAction | CustomAction;
interface ActionShared {
    /** Display title shown in the panel. */
    title: string;
    /** Optional icon (emoji or icon name). */
    icon?: string;
    /** Keyboard shortcut hint — display only, doesn't bind. */
    shortcut?: string;
    /** Mark as destructive — renders red, requires confirmation by default. */
    destructive?: boolean;
}
interface CopyAction extends ActionShared {
    kind: 'copy';
    content: string;
    /** True to redact from clipboard history hooks. Default false. */
    concealed?: boolean;
}
interface InsertAction extends ActionShared {
    kind: 'insert';
    /** Text to insert into the active input / contenteditable on the page. */
    text: string;
}
interface OpenUrlAction extends ActionShared {
    kind: 'open-url';
    url: string;
    /** Open in same tab vs new (default 'new'). */
    target?: 'self' | 'new';
}
interface NavigateAction extends ActionShared {
    kind: 'navigate';
    /** SPA path — host's `onNavigate` is invoked. */
    path: string;
}
interface AgentTaskAction extends ActionShared {
    kind: 'agent-task';
    task: string;
}
interface RenderSurfaceAction extends ActionShared {
    kind: 'render-surface';
    surface: unknown;
    placement?: SurfacePlacement;
}
interface RunSkillAction extends ActionShared {
    kind: 'run-skill';
    skillId: string;
    vars?: Record<string, string>;
}
interface CustomAction extends ActionShared {
    kind: 'custom';
    /** Arbitrary handler — escape hatch for things outside the typed kinds. */
    onActivate: (ctx: ActionRunContext) => void | Promise<void>;
}
interface ActionRunContext {
    navigate(path: string): void;
    startAgent(task: string): void;
    runSkill(skillId: string, vars?: Record<string, string>): void;
    emitSurface(surface: unknown, placement?: SurfacePlacement): void;
}

/**
 * Type / interface contracts shared across the CommandPalette implementation.
 * Public types are re-exported via `./index.ts` so external import paths
 * (`@perhapxin/dddk` and `./triggers/command-palette`) keep working.
 */
/**
 * Prefix spec — three forms:
 *  - bare string ('ask:')
 *  - array of strings (['ask:', '@ai', '/'])  — any one triggers
 *  - object with separate match (what triggers) and label (what's shown)
 *
 * Convention: symbol prefixes — use `/`, `@`, `#` only.
 * Text prefixes — host decides freely (e.g. `ask:`, `search:`, `d1:`).
 */
type PaletteItemPrefix = string | string[] | {
    match: string | string[];
    label?: string;
};
/**
 * Agent-tool exposure spec — opt-in only.
 *
 * When a palette item declares `agentTool`, DotDotDuck auto-registers it as
 * a webagent custom action so the agent can invoke it. Predefined default
 * is NOT to expose (safer + more controllable).
 *
 * webagent's tool surface should stay narrow — only this opt-in mechanism +
 * the built-in DOM actions. Business features live in palette skills or as
 * clickable UI on the page.
 */
interface PaletteAgentTool {
    /** What the agent sees as the tool's purpose. */
    description: string;
    /** JSON Schema for the tool's params — typically `{ arg: string }`. */
    parameters: Record<string, unknown>;
    /** True for destructive ops — agent will prompt user before invoking. */
    requireConfirmation?: boolean;
}
interface PaletteItem {
    id: string;
    name: string;
    description?: string;
    /**
     * Extra stacked lines rendered BELOW the name (a multi-line row), letting the
     * host decide how many lines appear on the right of each item — e.g. a book
     * row: name on line 1, blurb on line 2, "author · publisher · $price" on
     * line 3. When set, the row uses a vertical text column instead of the
     * inline `name — description` layout. Each entry is one line (plain text,
     * escaped). `description` is ignored for layout when `lines` is present.
     * Style via `[data-dddk-ui="palette-item-line"]` (and `...-line-0/1/...`).
     */
    lines?: string[];
    /**
     * Search-action row: hidden in the empty state, and PINNED TO THE TOP of the
     * results the moment the user types anything (regardless of fuzzy match). The
     * live query is substituted into `name`/`description` wherever the token `{q}`
     * appears, and the handler receives the raw query as its `arg`. Use for a
     * "search for «query»" entry that routes to a full results page. Grouped under
     * its `section` like any item, so it leads that section.
     */
    searchAction?: boolean;
    icon?: string;
    /**
     * Thumbnail image URL for the row (e.g. a book cover, product shot, avatar).
     * When set, it is rendered as an `<img>` in the icon slot instead of the glyph
     * `icon`, so hosts can build rich rows (cover + title + meta) without a custom
     * renderer. The URL is attribute-escaped; the host controls it (same trust
     * boundary as `icon`). Style via `[data-dddk-ui="palette-item-image"]`.
     */
    image?: string;
    keywords?: string[];
    section?: string;
    shortcut?: string;
    /**
     * Prefix routing — when the palette input starts with this prefix, only items
     * matching this prefix are shown, and the post-prefix text is passed as `arg`.
     *
     * See {@link PaletteItemPrefix} for the three accepted forms.
     */
    prefix?: PaletteItemPrefix;
    /**
     * If true and `prefix` is set, the item shows AS THE TOP RESULT whenever the
     * input starts with that prefix, even without matching the rest of `name`.
     * Use this for "open-ended" prefixes like `ask ai:`.
     */
    prefixAcceptsAnyArg?: boolean;
    /**
     * If true, this item appears as a fallback when the user's query matches
     * no other item. Pair with `prefixAcceptsAnyArg` so the raw query becomes
     * the action arg.
     */
    fallback?: boolean;
    /**
     * Optional typed action list. If provided, the palette renders a primary
     * action (⏎), secondary (Ctrl+⏎), and a sub-panel for the rest (Ctrl+K).
     * If omitted, the item uses the bare `handler` callback below.
     */
    actions?: PaletteAction[];
    /**
     * Opt-in agent exposure — set to make this command callable by webagent.
     * See {@link PaletteAgentTool}.
     */
    agentTool?: PaletteAgentTool;
    /**
     * Optional detail-view renderer — when this item is highlighted, the palette
     * renders a right pane containing this PieceSurface. Receives the current
     * prefix arg (if any).
     */
    detail?: (arg?: string) => PieceSurface | Promise<PieceSurface>;
    /**
     * Browse mode — dynamic resource expansion under a prefix. When set with
     * `prefix`, the SDK calls this on every keystroke once the prefix matches
     * the input. Return the list of resources under this prefix; the SDK
     * fuzzy-filters them by the post-prefix arg.
     *
     * Use for resource-type prefixes like `order:`, `customer:`, `aig:`,
     * `docs:`. Each returned PaletteItem renders as a row whose handler runs
     * when the user picks it (typically `goto(...)` or `p.showResult(...)`).
     *
     * Sync only — host should cache fetches and call browse() against the
     * cached list. For async / pagination, wire it through showResult on the
     * parent item instead.
     */
    browse?: (arg: string) => PaletteItem[];
    /**
     * Section heading used for items returned by `browse`. Defaults to the
     * parent item's section, falling back to the prefix string. Override
     * when the parent lives in 'Tips' but children should display under
     * a resource-specific heading like 'Docs' or 'AI Gateways'.
     */
    browseSection?: string;
    /**
     * Search-only — when true, this item is hidden from the empty state and
     * from partial-prefix attempts, but still participates in free-text fuzzy
     * search. Use for "deep destinations" you want findable by keyword but
     * not cluttering the default list — e.g. each doc chapter registered as
     * a flat row so typing `react` surfaces `docs › dddk › React adapter`.
     */
    searchOnly?: boolean;
    /**
     * Optional category for the chip-row filter. When the palette is
     * configured with `categories: [...]`, clicking a chip narrows the
     * list to items whose `category` matches that chip's `id`. Items
     * without a category appear under the implicit "All" chip only.
     */
    category?: string;
    handler?: (palette: PaletteHandle, arg?: string) => void | Promise<void>;
}
/**
 * Category chip rendered below the palette input. Clicking one narrows
 * the list to `PaletteItem`s whose `category` field equals `id`.
 */
interface PaletteCategory {
    /** Stable id matched against `PaletteItem.category`. */
    id: string;
    /** Human-readable label rendered on the chip. */
    label: string;
}
interface PaletteHandle {
    close(): void;
    replace(items: PaletteItem[]): void;
    get input(): string;
    setInput(value: string): void;
    /** User-context captured at palette open: selection text + queued image attachments. */
    context: PaletteContext;
    /** Render a result in-place below the input, replacing the item list. */
    showResult(surface: ResultSurface): void;
    /** Switch back to the regular item list. */
    clearResult(): void;
    /**
     * Hijack the top input box so the sub-tool can use it as ITS OWN input —
     * useful when the tool is a chat panel / dataset search / per-tool prompt
     * that shouldn't double up with another text box. The override clears
     * automatically when the palette closes or the user Esc-backs out of the
     * current sub-menu.
     *
     * Example (chat panel inside a sub-menu):
     *   handle.setInputContext({
     *     placeholder: 'Type a message…',
     *     hideList: true,
     *     onSubmit: (text) => sendChat(text),
     *   });
     */
    setInputContext(ctx: {
        placeholder?: string;
        onSubmit: (value: string, handle: PaletteHandle) => void;
        /** Fires on every keystroke. Use for live-filter panels. */
        onInput?: (value: string, handle: PaletteHandle) => void;
        clearOnSubmit?: boolean;
        hideList?: boolean;
    }): void;
    clearInputContext(): void;
}
/**
 * A streamed result fragment. The palette content-frame renderer
 * processes one of these per yield from an `AsyncIterable<ResultChunk>`:
 *
 *   - `{ delta }`         — append plain text to the running buffer
 *   - `{ text }`          — REPLACE the running text (LLM snapshot-mode streams)
 *   - `{ html, append? }` — set / append innerHTML (default REPLACE)
 *   - `{ node, append? }` — replace / append a DOM node directly
 *   - `{ clear: true }`   — wipe the content frame mid-stream (rare; for retries)
 */
type ResultChunk = {
    delta: string;
} | {
    text: string;
} | {
    html: string;
    append?: boolean;
} | {
    node: Node;
    append?: boolean;
} | {
    clear: true;
};
/**
 * Streamed result handle — the host mounts an HTMLElement and gets back
 * the same root inside a callback to mutate as data arrives. This is
 * the natural shape for chat / progressive LLM rendering / partial-node
 * updates where the host owns the DOM structure and only specific
 * sub-trees stream.
 *
 *   p.showResult({
 *     mount: container,
 *     stream: async (root) => {
 *       const reply = root.querySelector('.reply')!;
 *       for await (const c of llm.streamComplete()) reply.textContent = c.text;
 *     },
 *   });
 */
interface StreamingResultSurface {
    /** Element shown in the content frame. */
    mount: HTMLElement;
    /** Called AFTER `mount` is in the DOM. Mutate `root` (which === mount). */
    stream: (root: HTMLElement) => void | Promise<void>;
}
/** What a palette handler can hand back to be rendered in result-mode. */
type ResultSurface = string | HTMLElement | AsyncIterable<string | ResultChunk> | StreamingResultSurface | (() => Promise<string | HTMLElement | AsyncIterable<string | ResultChunk> | StreamingResultSurface>);
/** Locale-aware string: either `"plain"` or `{ en: "...", 'zh-TW': "..." }`. */
type LocalizedText = string | Record<string, string>;
interface QAPaletteItem {
    id: string;
    question: LocalizedText;
    answer: LocalizedText;
    description?: LocalizedText;
    category?: string;
    /** Free-form metadata the host wants threaded through `renderAnswer`. */
    meta?: Record<string, unknown>;
}
interface QAItemsOpts {
    /** Active UI locale. Used to pick the right string from each LocalizedText.
     *  Default `'en'`. Re-call `addQAItems` with a new locale to refresh labels. */
    locale?: string;
    /** Palette section heading. Default `'QA'`. */
    section?: string;
    /** Item-row icon. Default `'?'`. */
    icon?: string;
    /** Prefix for the item id (`addItem` is id-keyed). Default `'qa-'`. */
    idPrefix?: string;
    /** Override the right-pane renderer. Default renders the answer as a Body piece. */
    renderAnswer?: (ctx: {
        question: string;
        answer: string;
        meta?: Record<string, unknown>;
    }) => PieceSurface;
}
/**
 * Image attachment queued in the palette context — user added via the
 * camera icon (file picker or screenshot). Skill / agent handlers read
 * `palette.context.attachments` to pass these along to the LLM.
 */
interface PaletteAttachment {
    id: string;
    kind: 'image';
    blob: Blob;
    thumbnailUrl: string;
    source: 'upload' | 'screenshot';
    filename?: string;
    /** Page URL the attachment was captured / referenced on (screenshots set
     *  this to `window.location.href`). Forwarded to webagent so the agent
     *  knows which page the user is asking about. */
    sourceUrl?: string;
}
/**
 * State the palette carries about the current user — text they had
 * selected when they opened it, images they attached via the camera icon.
 * Skill / agent handlers receive this via the palette handle.
 */
interface PaletteContext {
    selectionText: string;
    selectionElement?: string;
    attachments: PaletteAttachment[];
}
/**
 * Camera button at the right of the palette input.
 *
 * Modes:
 *   - `'upload'`     — opens a file picker. `capture: true` on mobile opens the
 *                      camera directly.
 *   - `'screenshot'` — hides the palette, shows a crosshair overlay, the user
 *                      drags a rectangle on the visible page, and the host's
 *                      `captureRect()` turns that rect into an image blob.
 *                      No OS share-screen prompt, no tab picker.
 *
 * Both modes deliver the result through `onCapture`.
 */
interface CameraOptions {
    /** What the icon does. */
    mode: 'upload' | 'screenshot';
    /** Receives the captured / chosen image. */
    onCapture: (file: File | Blob, source: 'upload' | 'screenshot') => void;
    /**
     * Upload mode only — file picker accept filter. Default `image/*`.
     * Mobile: include `capture: true` for direct camera access.
     */
    accept?: string;
    /** Upload mode only — open camera directly on mobile. Default false. */
    capture?: boolean;
    /** Tooltip on hover. Default "Attach image". */
    title?: string;
    /**
     * Screenshot mode only — pixel capture function. dddk renders the region-
     * selection overlay and hands you the rect (in viewport coords); you turn
     * the underlying DOM region into a Blob. Typical implementation uses
     * `html2canvas` or `modern-screenshot` in the host bundle.
     *
     * Return `null` if capture fails (no fallback fires — the user can try
     * again or cancel).
     *
     * If omitted in screenshot mode, the camera button warns and does nothing.
     */
    captureRect?: (rect: {
        x: number;
        y: number;
        width: number;
        height: number;
    }) => Promise<Blob | null>;
}
interface CommandPaletteOptions {
    initialItems?: PaletteItem[];
    /** Locale for the bundled chrome strings (placeholder, footer hints).
     *  `en` / `zh-TW` ship bundled — anything else falls back to `en`.
     *  Hosts wanting native labels in another language pass `placeholder`
     *  explicitly or override via `setLocale()` at runtime. */
    locale?: string;
    placeholder?: string;
    /** Optional page-text search; returns elements to jump to. */
    searchPage?: (query: string) => Array<{
        text: string;
        element: HTMLElement;
    }>;
    /**
     * Optional HeatRank — if provided, palette items sort by usage frecency
     * (descending) AFTER the prefix/fuzzy filter. visit() is called on activate.
     */
    heatRank?: HeatRank;
    /**
     * Optional PieceCatalog — used to render PaletteItem.detail in the right pane.
     * Defaults to createBuiltinCatalog() lazily on first use.
     */
    pieceCatalog?: PieceCatalog;
    /**
     * When the palette opens with any chip-bar context (selection text, a
     * pinned DOM element, image attachments), automatically promote the
     * registered `fallback` (Ask AI) row to the TOP of the list and place
     * the keyboard cursor on it — so pressing Enter immediately routes the
     * captured context to the agent. Default `true`: most products that pin
     * context to the palette do so precisely because the user wants AI to
     * act on it. Set `false` if your palette uses context for navigation /
     * search and the fallback should stay at the bottom like normal.
     */
    contextPromotesFallback?: boolean;
    /**
     * Show a camera icon at the right edge of the input. Default `undefined`
     * (no icon). Set this to enable image attach — host handles the resulting
     * file/blob via `onCapture`.
     */
    camera?: CameraOptions;
    /**
     * Show a circular submit/send button at the right edge of the input. Clicking
     * it (or pressing Enter) submits the current query — firing the registered
     * fallback item (e.g. "Ask AI") with the typed text, or activating the focused
     * row. Default `undefined` (no button).
     */
    submitButton?: boolean;
    /**
     * Optional chip-row rendered below the input. When provided, the
     * palette inserts an "All" chip and then one chip per entry; clicking
     * a chip narrows the list to items whose `category` matches its id.
     */
    categories?: PaletteCategory[];
    /** Label for the implicit "All" chip. Defaults to "All". */
    allCategoriesLabel?: string;
    /**
     * Fired whenever a palette item is activated (clicked / Enter). Used by
     * the orchestrator to emit a unified `intent` event.
     */
    onActivate?: (info: {
        itemId: string;
        arg?: string;
        selectionText?: string;
        attachmentsCount: number;
    }) => void;
}

/**
 * Chip-bar rendering + pinned-context bookkeeping. The CommandPalette class
 * owns the state slots (`contextSelectionText`, `contextAttachments`,
 * `pinnedContextEl` …) and forwards to these helpers via a small host
 * adapter so this file can stay state-free (modulo the host it operates on).
 *
 * Why an adapter instead of importing CommandPalette directly: avoids a
 * circular import (CommandPalette imports this file) and keeps the helper's
 * surface explicit.
 */

type SelectionKind = 'dom' | 'text';

/**
 * CommandPalette — Ctrl/⌘+K input overlay rendered into the DOM.
 *
 * This file is the shell: lifecycle (open/close), DOM scaffolding (render),
 * keyboard handling, list rendering, and the public class surface. The
 * sub-files in this folder own:
 *   - styles.ts      — injected CSS + shared `UI_ATTR` / `STYLE_ID`
 *   - types.ts       — all public type / interface contracts
 *   - prefix.ts      — prefix routing helpers (pure functions)
 *   - fuzzy.ts       — fuzzy filter + match-highlight
 *   - chip-bar.ts    — chip strip + pinned-context lifecycle
 *   - qa.ts          — locale-resolved QA item registration
 *   - screenshot.ts  — drag-rect screenshot overlay
 */

declare class CommandPalette {
    /**
     * `rootItems` is the canonical list — what `addItem` / `removeItem` operate
     * on. It survives sub-menu navigation. `items` is the *currently displayed*
     * set; when a handler calls `handle.replace([...])`, the previous `items` is
     * pushed onto `subMenuStack` and `items` becomes the new set. Esc pops back
     * one level; if the stack is empty, Esc closes the palette. Re-opening via
     * `open()` always resets `items` to `rootItems.slice()`.
     */
    private rootItems;
    private detailRenderToken;
    private items;
    private subMenuStack;
    private placeholder;
    /** True while the palette is embedded inline in a host (vs the Ctrl/⌘+K modal). */
    private inlineMounted;
    /** Saved inline surface refs while a modal (Ctrl/⌘+K) is opened on top of it. */
    private suspendedInline;
    /** Locale for the bundled chrome strings. Read at construction; can
     *  be flipped at runtime via `setLocale()` — the next render picks
     *  up the new strings (footer hints + placeholder). */
    private locale;
    private searchPage?;
    private contextPromotesFallback;
    private root;
    private input;
    private list;
    private filtered;
    private cursor;
    private currentArg;
    private listeners;
    private heatRank?;
    private pieceCatalog?;
    private detailHost;
    private categoryBarHost;
    private categories;
    private allCategoriesLabel;
    private activeCategoryId;
    private camera?;
    private submitButton?;
    private onActivate?;
    private contextSelectionText;
    private contextSelectionElement?;
    private contextSelectionKind;
    private contextAttachments;
    /**
     * Host-supplied pinned context. Set by `setPinnedContext()` and consumed
     * on each `open()`. Used by modules like Dwell that pin an element
     * BEFORE the palette opens — when the palette eventually opens, this is
     * what its chipbar surfaces.
     *
     * `pinnedContextEl` stores the ELEMENT REFERENCE directly (not a CSS
     * selector). At open time we check `el.isConnected && document.contains(el)`
     * — if the element has been unmounted (SPA route change, list virtualised,
     * etc.) the pin is auto-invalidated WITHOUT having to trust any selector
     * lookup. Structural selectors (`body>main>section:nth-child(3)`) match
     * different content on different pages; element references can't.
     */
    private pinnedContextEl;
    private pinnedContextText;
    private pinnedContextKind;
    private resultHost;
    private listSplit;
    private resultMode;
    private chipBarHost;
    private inputContext;
    constructor(opts?: CommandPaletteOptions);
    /**
     * Replace the category chip set. Pass an empty array to remove the
     * chip row entirely. Active category resets to "All".
     */
    setCategories(categories: PaletteCategory[], allLabel?: string): void;
    /** Runtime toggle of the camera icon's mode (upload ↔ screenshot). */
    setCameraMode(mode: 'upload' | 'screenshot'): void;
    isOpen(): boolean;
    /** Update the locale for the bundled chrome strings (placeholder,
     *  footer hints). Next palette open picks up the new strings. The
     *  open-right-now palette is patched in place too. */
    setLocale(locale: string): void;
    /** Produce the current footer HTML — kbd hints + touch hints + brand
     *  mark. Kept as a pure builder so it can be used both for the initial
     *  mount (before `this.root` is set) and for later refreshes triggered
     *  by locale / esc-mode / result-mode changes. Both paths converge on
     *  the same output; drift here becomes drift users see. */
    private buildFooterHTML;
    /** Rebuild the footer to match the current locale + state. Wipes and
     *  re-writes the whole strip — the brand mark on the right is
     *  intentionally re-rendered every call so a partial repaint can't
     *  leave it lopped off. */
    private refreshFooter;
    toggle(initialSelection?: string): void;
    /** Programmatically set the palette's search input value (and refilter
     *  the visible list). Used by hosts driving the palette from outside —
     *  e.g. the webagent's `open_palette({ initialInput })` tool seeds a
     *  prefix command like `docs:` so the user lands on the right sub-list. */
    setInputValue(value: string): void;
    open(initialSelection?: string, opts?: {
        focusInput?: boolean;
    }): void;
    close(): void;
    /**
     * Mount the palette INLINE inside a host element, persistently visible —
     * no backdrop, no outside-click dismissal. It shares the exact same items,
     * filtering, keyboard navigation and row rendering as the Ctrl/⌘+K modal,
     * so the host writes ONE set of palette items and gets both surfaces.
     * While inline-mounted, `open()` / `toggle()` (e.g. Ctrl+K) just focus the
     * embedded input instead of spawning the modal.
     *
     * Returns a teardown function — call it when the host element unmounts
     * (e.g. SPA route change) to detach the palette and its listeners.
     */
    mountInline(host: HTMLElement, opts?: {
        placeholder?: string;
        focus?: boolean;
    }): () => void;
    /**
     * Pin a DOM element (or a free-text snippet) as context for the NEXT
     * palette open. Detection is done at open time by re-reading the live
     * DOM — we don't snapshot a copy of the text here. If the selector
     * stops resolving (page navigation, element removed, scroll-virtualised
     * list) the context auto-clears with no work from the host.
     *
     * The `text` argument is kept only as a fallback for `kind: 'text'`
     * pins where there is no element to read from (rare).
     */
    setPinnedContext(text: string, elementOrSelector?: Element | string | null, opts?: {
        kind?: SelectionKind;
    }): void;
    clearPinnedContext(): void;
    /**
     * Read-only snapshot of the sticky pinned context. Unlike `context`, this
     * survives palette `close()` — useful for `dddk.startAgent()` called from a
     * palette handler. The text is read live from the pinned element when
     * possible so navigation invalidates stale pins.
     */
    get pinnedContext(): {
        text: string;
        element?: string;
        kind: SelectionKind;
    };
    private captureContextOnOpen;
    private clearContext;
    /** Public: add an image attachment to the palette context. */
    addAttachment(att: Omit<PaletteAttachment, 'id'>): PaletteAttachment;
    removeAttachment(id: string): void;
    clearAttachments(): void;
    /** Read-only snapshot of the current context. */
    get context(): PaletteContext;
    showResult(surface: ResultSurface): Promise<void>;
    clearResult(): void;
    /**
     * True when the palette is open AND in a state where Esc has its own
     * meaning (back out of result-mode / pop a sub-menu). External
     * keyboard handlers (orchestrator's GestureManager Esc) should defer
     * to the palette in that case — otherwise the global "Esc closes the
     * whole palette" rule kills the back-step the user expected.
     */
    hasInternalEsc(): boolean;
    /** Snapshot of the currently-registered root items. Read-only — use
     *  `addItem` / `removeItem` / `setItems` to mutate. */
    getItems(): readonly PaletteItem[];
    /** Replace the canonical root-level items. Public hosts use this for full
     *  re-registration; if the palette is open at a sub-menu level, the change
     *  takes effect on next open. */
    setItems(items: PaletteItem[]): void;
    /**
     * Add or replace a palette item. If an item with the same `id` is already
     * registered, the new one REPLACES it in-place (preserving its position
     * in the list). This is what makes the i18n re-registration pattern work:
     *
     *   onLocaleChange((loc) => {
     *     palette.addItem({ id: 'theme', name: t(loc, 'theme.name'), ... });
     *     // ↑ replaces the previous 'theme' item, HeatRank usage carries over.
     *   });
     *
     * For full-replace registration, use `setItems()` instead.
     */
    addItem(item: PaletteItem): void;
    removeItem(id: string): void;
    /**
     * Register a batch of FAQ-style items so the user can browse the
     * answer right inside the palette — arrow keys land on a question,
     * the detail pane auto-renders the answer. Replaces the old
     * `toolbox/qa` module for UI flows.
     *
     * Each item's `question` / `answer` accepts a plain string OR a
     * locale-keyed dict (`{ en, 'zh-TW', ja, … }`). The palette resolves
     * the right string at registration time via `opts.locale` (falls back
     * to `en` then the first defined locale). Re-call on locale change
     * to refresh labels — same id replaces in place.
     *
     * The agent-tool counterpart lives at `dddk.tools.registerQA(...)` —
     * use that one to let the LLM look up answers itself.
     */
    addQAItems(items: QAPaletteItem[], opts?: QAItemsOpts): void;
    private render;
    private get chipBarHostAdapter();
    private renderChipBar;
    private onInputKey;
    setInputContext(ctx: {
        placeholder?: string;
        onSubmit: (value: string, handle: PaletteHandle) => void;
        /** Fires on every keystroke. Use for live-filter panels. */
        onInput?: (value: string, handle: PaletteHandle) => void;
        /** Clear the input after onSubmit fires. Default true. */
        clearOnSubmit?: boolean;
        /** Hide the list / typeahead while in this context. Default false. */
        hideList?: boolean;
    }): void;
    clearInputContext(): void;
    /** Circular submit/send button at the right edge of the input row. */
    private buildSubmitButton;
    /**
     * Submit the current query — same effect as pressing Enter. Routes to the
     * active input-context's onSubmit, else fires the single registered fallback
     * (e.g. Ask AI) with the typed text, else activates the focused row.
     */
    private submitInput;
    private buildCameraButton;
    private openUpload;
    /** See `./screenshot.ts` for the drag-rect overlay implementation. */
    private openScreenshot;
    private refilter;
    /** True when the chip bar has any user-pinned context attached. */
    private hasChipContext;
    /**
     * Render or refresh the category chip row. Hidden when no categories
     * were configured. Active chip is highlighted via `data-active="true"`.
     */
    private renderCategoryBar;
    /**
     * Render the filtered item list. Each `<li>` carries a `data-idx` matching
     * its index in `this.filtered`, so:
     *  - hover does NOT rebuild the DOM — it just toggles `data-active` on the
     *    existing nodes. (Critical: rebuilding the `<li>` during a press
     *    destroys the click target and the click bubbles to the `<ul>` instead,
     *    making items appear unclickable.)
     *  - the click handler reads `data-idx` from the row at click-time, so it
     *    survives any re-renders triggered by other events.
     *
     * If `tipsItems` is present we also prepend a `Tips` section showing the
     * prefixes the user can type to filter (ask: / find: / go: hints at the top).
     */
    private renderList;
    /** Set the highlighted row without re-rendering. */
    private setCursor;
    private move;
    /** Render the right detail pane if the active item provides `detail()`. */
    private renderDetailFor;
    /**
     * Public — activate a palette item by id. Returns true if found and
     * fired, false if no matching item is currently in the filtered list
     * (e.g. caller passed a sub-menu id before opening the parent).
     *
     * Used by host-registered "semantic" webagent tools that wrap multi-
     * level palette flows: the tool can `open()` the palette, await a
     * frame, `activateById('parent')` to expand the sub-menu, await, then
     * `activateById('child')` to commit. Saves the agent from having to
     * model the palette as a 2-step click sequence.
     */
    activateById(id: string): boolean;
    private activate;
    private buildHandle;
}

/**
 * Spotter — pointer follow + deictic lock + region lasso.
 * See ../../docs/04-spotter.md for the full design.
 */
type SpotterState = 'idle' | 'ring' | 'lock' | 'lasso';
interface SpotterOptions {
    ringDelay?: number;
    enableLasso?: boolean;
    enableRing?: boolean;
    /** Elements with this selector are ignored (e.g. dddk's own UI). */
    ignoreSelector?: string;
    onRingShow?: (info: {
        selector: string;
        element: HTMLElement;
        rect: DOMRect;
    }) => void;
    onRingHide?: () => void;
    onLock?: (info: {
        selector: string;
        element: HTMLElement;
    }) => void;
    onLassoComplete?: (info: {
        elements: HTMLElement[];
        bounds: DOMRect;
    }) => void;
}
declare class Spotter {
    private state;
    private opts;
    private hoverTimer;
    private lastHoverElement;
    private lastHoverPos;
    private ringEl;
    private lassoEl;
    private lassoStart;
    private lockedElement;
    private cleanups;
    constructor(opts?: SpotterOptions);
    start(): void;
    destroy(): void;
    getState(): SpotterState;
    /**
     * Called by GestureManager when user starts a long-press while
     * something is hovered. If ring is shown → lock. Otherwise → just signal voice mode.
     */
    lockCurrent(): {
        selector: string;
        element: HTMLElement;
    } | null;
    /** Start drawing a lasso from current pointer position. */
    beginLasso(startX: number, startY: number): void;
    updateLasso(x: number, y: number): void;
    endLasso(commit: boolean): {
        elements: HTMLElement[];
        bounds: DOMRect;
    } | null;
    unlock(): void;
    private handleMove;
    private showRing;
    private hideRing;
    private collectLassoElements;
    private shouldIgnore;
}

/**
 * SkillRegistry — register / lookup / match skills by id or `/command`.
 */

declare class SkillRegistry {
    private skills;
    constructor(initial?: Skill[]);
    register(skill: Skill): void;
    unregister(id: string): void;
    get(id: string): Skill | undefined;
    list(): Skill[];
    listAll(): Skill[];
    /** Match palette input like `/introduce` or `/translate en` to a skill id. */
    match(input: string): Skill | undefined;
    /** Extract args after the skill name. e.g. `/translate en` → 'en' */
    parseArgs(input: string): string;
    /** Resolve `{{var}}` placeholders in a PromptSkill template. */
    resolvePrompt(skill: PromptSkill, vars?: Record<string, string>): string;
}

/**
 * PanelRuntime — runtime support for `PanelSkill`.
 *
 * Renders a "top input + bottom panel" overlay separate from the regular
 * CommandPalette. Manages a navigation stack so Esc/Backspace pop frames
 * instead of closing entirely. Breadcrumbs at the top let users jump back
 * any level.
 *
 * This is a minimal DOM implementation — the goal is to make PanelSkill
 * executable end-to-end. Hosts wanting deep UI customization can replace it
 * by listening to `panel_enter` / `panel_input` / `panel_action` events.
 */

interface PanelRuntimeHost {
    /** Called when user submits an action — usually a button click in the rendered surface. */
    llm?: (prompt: string) => Promise<string>;
    navigate: (path: string) => void;
    /** Render a PieceSurface into a host-provided DOM container. */
    renderPiece?: (container: HTMLElement, surface: unknown, onAction: (action: string, data: unknown) => void) => void;
}
interface PanelRuntimeOptions {
    host: PanelRuntimeHost;
    /** Debounce ms for onInput. Default 200ms. */
    inputDebounceMs?: number;
}
declare class PanelRuntime {
    private stack;
    private overlay;
    private inputEl;
    private breadcrumbEl;
    private contentEl;
    private inputTimer;
    private host;
    private debounceMs;
    constructor(opts: PanelRuntimeOptions);
    /** Push a panel skill onto the stack and render. */
    enter(skill: PanelSkill): Promise<void>;
    /** Pop the top frame. Closes the overlay if stack empties. */
    back(): Promise<void>;
    /** Close everything. */
    close(): Promise<void>;
    isOpen(): boolean;
    stackDepth(): number;
    private mount;
    private unmount;
    private renderShell;
    private renderSurface;
    private clearContent;
    private fallbackRender;
    private renderNode;
    private handleInput;
    private handleKeyDown;
    private handleAction;
    private makeContext;
}

/**
 * Placement slots — the canonical screen positions every transient
 * dddk UI piece routes through.
 *
 * Slot names match `SurfacePlacement` from `skills/types` so callers
 * who already chose a placement (PanelSkill, SurfaceSkill, Proactive)
 * can pass it through unchanged.
 *
 * Apply with `applyPlacement(el, 'subtitle')` — the CSS selectors are
 * `[data-dddk-slot=...]`. The `Placements` class gives ergonomic
 * mount/unmount helpers.
 */
type PlacementSlot = 'subtitle' | 'indicator' | 'palette' | 'dock' | 'modal' | 'banner' | 'fab' | 'toast';
/**
 * Mount handle returned by `Placements.mount()` — unmount with `.unmount()`,
 * swap content with `.update(html)`.
 */
interface PlacementHandle {
    readonly el: HTMLElement;
    readonly slot: PlacementSlot;
    update(html: string): void;
    unmount(): void;
}
/**
 * Convenience class for hosts that want to drop custom content into a
 * placement slot without writing the boilerplate. Owns one element per
 * mount; multiple mounts into the same slot stack as siblings (the CSS
 * does not enforce single-occupancy — callers decide).
 *
 *   const handle = dddk.placement.mount('subtitle', `<div>Hi</div>`);
 *   // ... later:
 *   handle.unmount();
 */
declare class Placements {
    mount(slot: PlacementSlot, content: string | HTMLElement): PlacementHandle;
}

/**
 * PinnedPanel — a corner-anchored frame whose body is a `PieceSurface`.
 *
 * The frame owns: placement (one of the four screen corners), the close
 * button, the optional title / subtitle / footer chrome, animation, and
 * dismiss lifecycle. Everything inside is rendered by `PieceDomRenderer`
 * — the same renderer that powers the palette detail pane — so layout
 * (`Card` / `Stack` / `Grid` / `Tabs`), inputs (`Checkbox` / `Button` /
 * `TextField` / `Switch` …), data (`Listing` / `Metric` / `ProgressBar`)
 * and `Slot` host-supplied content all work out of the box.
 *
 *   const handle = dddk.panel.create({
 *     id: 'getting-started',
 *     placement: 'bottom-right',
 *     title: 'The Basics',
 *     subtitle: 'Setup the basics to get your team started',
 *     surface: {
 *       root: {
 *         kind: 'Stack', gap: 10, children: [
 *           { kind: 'ProgressBar', bind: '/progress' },
 *           { kind: 'Checkbox', bind: '/tasks/create',  label: 'Create your first project' },
 *           { kind: 'Button',    text: 'Create',  variant: 'primary', action: 'create' },
 *           { kind: 'Checkbox', bind: '/tasks/invite',  label: 'Invite your team' },
 *         ],
 *       },
 *       data: { progress: 0, tasks: {} },
 *     },
 *     onAction: (name, payload, data) => { ... },
 *     onDataChange: (data) => { ... },
 *   });
 *
 *   handle.setData({ progress: 50, tasks: { create: true } });
 *   handle.unmount();
 */

type PinnedPanelPlacement = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
interface PinnedPanelSpec {
    /** Stable id — re-creating with the same id replaces the existing panel. */
    id: string;
    /** Title rendered in the panel header. Hide the header by setting both
     *  `title` and `subtitle` to empty / undefined. */
    title?: string;
    subtitle?: string;
    /** Default `bottom-right`. */
    placement?: PinnedPanelPlacement;
    /** Body — any Pieces tree. See `PieceDomRenderer` for the catalog. */
    surface: PieceSurface;
    /** Renders a small × button in the header. Default `true`. */
    dismissible?: boolean;
    /** Footer caption (e.g. "Powered by Acme"). */
    footer?: string;
    /** Host can swap the piece catalog (e.g. to register custom kinds). */
    catalog?: PieceCatalog;
    /** Fired by Button / IconButton / Link clicks inside the surface. */
    onAction?: (name: string, payload: unknown, data: Record<string, unknown>) => void;
    /** Fired on every input change inside the surface. */
    onDataChange?: (data: Record<string, unknown>) => void;
    /** Fired when the user dismisses via the × button. */
    onDismiss?: (handle: PinnedPanelHandle) => void;
}
interface PinnedPanelHandle {
    readonly id: string;
    /** Mount / show the panel. Idempotent. */
    show(): void;
    /** Hide and detach from the DOM (panel can be re-shown). */
    hide(): void;
    /** Whether the panel is currently in the DOM. */
    isVisible(): boolean;
    /** Replace any subset of the spec — the panel re-renders in place. */
    update(patch: Partial<Omit<PinnedPanelSpec, 'id'>>): void;
    /** Read the current data model from the surface. */
    getData(): Record<string, unknown>;
    /** Replace the data model wholesale. */
    setData(data: Record<string, unknown>): void;
    /** Permanently remove and forget this panel. */
    unmount(): void;
}
/**
 * Owns the active set of pinned panels keyed by id. Re-creating with the
 * same id replaces the existing panel so the registry stays clean.
 */
declare class PinnedPanelRegistry {
    private panels;
    create(spec: PinnedPanelSpec, opts?: {
        showImmediately?: boolean;
    }): PinnedPanelHandle;
    get(id: string): PinnedPanelHandle | undefined;
    clear(): void;
}

/**
 * Tool registry — host-friendly API for exposing arbitrary capabilities
 * (QA, search, recommend, custom domain ops) to the webagent.
 *
 * What this gives you:
 *   - `dddk.tools.register({...})` — register any ActionDefinition; the
 *     webagent picks it up on next build, and if the agent is already
 *     running, the new tool is added live via `agent.registerAction(...)`.
 *   - `dddk.tools.registerQA({items, description?})` — convenience
 *     wrapper that takes a list of FAQ items, spins up a `dddk/toolbox/qa`
 *     instance internally, and exposes it as a `<id>_lookup` tool the
 *     LLM can call (e.g. agent decides on its own "I should look this
 *     up in the company FAQ first").
 *   - `dddk.tools.unregister(id)` — remove a tool.
 *   - `dddk.tools.list()` — read the current set (for debugging).
 *
 * Design notes:
 *   - QA / search / recommend are NOT palette panel demos. They are
 *     tools the agent uses automatically when it reasons. Putting them
 *     in the palette as standalone surfaces forces the user to pick
 *     which tool to use; registering them as agent tools lets the LLM
 *     decide.
 *   - The host can also provide per-turn context via the WebAgent
 *     config's `brand` + `appendSystemPrompt` fields — that's
 *     orthogonal to tools.
 */

interface ToolSpec extends ActionDefinition {
    /** Optional human label shown in `tools.list()` output. */
    label?: string;
}
interface QAToolItem {
    id: string;
    question: string;
    answer: string;
    category?: string;
    lang?: string;
}
interface RegisterQAOpts {
    /** Tool id. Default `'qa_lookup'`. Becomes the agent-visible action
     *  name (must be alphanumeric + underscore, no slashes/dots). */
    id?: string;
    /** FAQ entries. Host can pass mixed-language items; the QA module
     *  auto-detects per-item. */
    items: QAToolItem[];
    /** Override description the LLM sees. Default tells the agent this
     *  is the canonical "look something up in the company knowledge
     *  base" tool. */
    description?: string;
    /** topK returned to the LLM. Default 3. */
    topK?: number;
}
/** Search-tool registration — wires `dddk/toolbox/search` as a tool. */
interface RegisterSearchOpts<TRow> {
    /** Tool id. Default `'search_catalog'`. */
    id?: string;
    /** Default description: "search the product catalog by free text". */
    description?: string;
    /** Items the search index holds (products, articles, …). */
    items: TRow[];
    /** Map each row to `{ id, fields, meta? }`. The `fields` keys become
     *  searchable text per-row; `fields` values can be strings or string
     *  arrays. */
    toDoc: (row: TRow) => {
        id: string;
        fields: Record<string, string | string[]>;
        meta?: Record<string, unknown>;
    };
    /** Per-field weight + tf-saturation. Default: weight 1.0, sat 7. */
    fieldWeights?: Record<string, number>;
    /** topK returned. Default 5. */
    topK?: number;
}
/** Recommender-tool registration — wires `dddk/toolbox/recommend`. */
interface RegisterRecommendOpts<TRow> {
    /** Tool id prefix. Default `'recommend'` → produces actions
     *  `recommend_for_customer`, `recommend_similar`. */
    id?: string;
    /** Description for the `for_customer` variant. */
    forCustomerDescription?: string;
    /** Description for the `similar` variant. */
    similarDescription?: string;
    /** Catalog items. */
    items: TRow[];
    toDoc: (row: TRow) => {
        id: string;
        fields: Record<string, string | string[]>;
        meta?: Record<string, unknown>;
    };
    /** Customer ID for preference scoping. Default `'anon'`. */
    customerId?: string;
    /** topK returned. Default 5. */
    topK?: number;
}
/**
 * Internal — the orchestrator instantiates this and exposes a subset
 * as `dddk.tools`. Holds the buffer of registered tools so the
 * WebAgent picks them up at build-time AND can be added at runtime.
 */
declare class ToolsRegistry {
    private tools;
    /** Set by the orchestrator after WebAgent is built so runtime
     *  registrations land in the live agent immediately. */
    private liveAgent;
    attachAgent(agent: WebAgent): void;
    detachAgent(): void;
    /** All currently-registered tools — passed to WebAgent at build time. */
    snapshot(): ActionDefinition[];
    register(spec: ToolSpec): void;
    unregister(id: string): boolean;
    list(): ToolSpec[];
    /**
     *
     * Wait for any in-flight agent turn to complete, so the very next
     * turn observes whatever tools have just been registered. Without
     * this, mid-flight `register(...)` calls only apply to subsequent
     * turns — the in-flight turn finishes with the snapshot it started
     * with, which is correct but surprises hosts.
     *
     * If no agent is attached or no run is in flight, resolves
     * immediately. Otherwise resolves when the current run reaches idle.
     *
     * Implementation note: WebAgent doesn't expose a public event
     * emitter, so this poll-until-idle approach is the lowest-coupling
     * way to wire the same semantics. Poll interval is 100ms — agent
     * turn boundaries are typically 1-3s on `gpt-5.4-nano`, so the
     * loop tops out at ~30 polls per turn.
     */
    flush(): Promise<void>;
    /**
     * Wire a FAQ dataset as a webagent tool. The LLM sees one action
     * (`qa_lookup` by default) that takes a `question: string` and gets
     * back the top matched entries. Lets the agent decide on its own
     * "the user is asking about refunds, let me check the FAQ" without
     * the host having to wire each FAQ entry as a separate tool.
     */
    registerQA(opts: RegisterQAOpts): void;
    /**
     * Wire a catalog as a search tool. The LLM sees `search_catalog(query)`
     * and can call it to find products / articles / records by free text.
     * Backed by `dddk/toolbox/search` with per-field BM25.
     */
    registerSearch<TRow>(opts: RegisterSearchOpts<TRow>): void;
    /**
     * Wire a recommender as TWO tools — `recommend_for_customer` (no
     * input, returns personalised top-K) and `recommend_similar` (given
     * a product id, returns similar items). The recommender uses the
     * same catalog as the search builder and learns from
     * `recordPreference(productId, response)` calls — the LLM can hand
     * the user's ♥/✕ choices back to the recommender by calling
     * `record_preference` (third tool registered here).
     */
    registerRecommend<TRow>(opts: RegisterRecommendOpts<TRow>): void;
}

/**
 * Subtitle bar — DOM-rendered, CSS-variable themed. Shell file: public
 * class surface + state. Implementation in sibling modules (streaming /
 * choice / indicator / paging / markdown / styles / dismiss / touch).
 * See ../../../docs/07-subtitle-ui.md for the full design.
 */

declare class Subtitle {
    /** @internal */ _el: HTMLDivElement | null;
    /** @internal */ _indicator: HTMLDivElement | null;
    /** @internal */ _autoHideTimer: ReturnType<typeof setTimeout> | null;
    /** @internal */ _currentOpts: SubtitleShowOptions | null;
    /** @internal */ _delegatedHandler: ((e: Event) => void) | null;
    /** @internal Document keydown teardown for multi-choice mode. */
    _choiceTeardown: (() => void) | null;
    /** @internal Click-anywhere / any-key dismiss teardown. */
    _dismissTeardown: (() => void) | null;
    /** @internal */ _locale: string;
    /** @internal Indicator request queued while a subtitle is visible;
     *  materialises on hide(). Subtitle + indicator are mutually exclusive. */
    _pendingIndicator: {
        state: 'listening' | 'processing' | 'done';
        label?: string;
    } | null;
    /** @internal Multi-page state for a single `show()` call. */
    _pages: string[] | null;
    /** @internal */ _pageIdx: number;
    /** @internal Host hook for "user explicitly closed the bar". */
    _closeHandler: (() => void) | null;
    /** @internal Live Text node the streaming bar appends into. */
    _streamingTextNode: Text | null;
    /** @internal */ _streamingCursor: HTMLSpanElement | null;
    /** @internal Untranscribed tail held for sentence-boundary TTS flush. */
    _streamingTtsBuffer: string;
    /** @internal Raw accumulated streaming text (for replaceStreamed). */
    _streamingFullText: string;
    /** @internal Pause-hint callbacks — invokeAccept = advance, invokeReject = stop. */
    _streamingPauseAccept: (() => void) | null;
    /** @internal */ _streamingPauseReject: (() => void) | null;
    /** @internal Override for the "running" indicator label after accept/reject. */
    _runningLabel: string | null;
    /** @internal Orchestrator hook — flips GestureManager.hasSuggestion so
     *  space-tap on a proactive prompt isn't a no-op. */
    _onVisibilityChange?: (visible: boolean) => void;
    /** @internal Fire-and-forget TTS hook — failures swallowed (no audio
     *  is strictly better than blocking the visual subtitle). */
    _ttsProvider?: (text: string, opts: {
        locale: string;
        type: SubtitleType;
    }) => void;
    /** @internal Duck-face avatar URL — when set, `_wrapBarShell` prepends
     *  an <img> at the left edge of the bar so the subtitle reads as
     *  coming from the mascot. Off by default (host opt-in). */
    _avatarUrl: string | null;
    constructor(opts?: {
        locale?: string;
    });
    setLocale(locale: string): void;
    setVisibilityListener(fn: (visible: boolean) => void): void;
    setTTSProvider(fn: typeof this._ttsProvider | null): void;
    /** Set the mascot-avatar URL that renders at the left edge of the
     *  subtitle bar. Passes `null` to hide. Hosts that don't want the
     *  avatar can skip this call entirely — default is off. */
    setAvatarUrl(url: string | null): void;
    /** Hook for × button + outside dismiss — orchestrator typically
     *  stops the agent loop here. */
    setCloseHandler(fn: (() => void) | null): void;
    show(opts: SubtitleShowOptions): void;
    update(text: string): void;
    appendStreamed(delta: string): void;
    replaceStreamed(text: string): void;
    finalizeStreamed(opts?: {
        autoHide?: number;
    }): void;
    clearStreamed(): void;
    isStreaming(): boolean;
    applyStreamingPauseHint(opts: {
        hint: string;
        rejectHint?: string;
        onAccept: () => void;
        onReject: () => void;
    }): void;
    clearStreamingPauseHint(): void;
    showChoice(opts: SubtitleChoiceOptions): void;
    hide(): void;
    isVisible(): boolean;
    /** Gesture entry points — single space → invokeAccept, double tap →
     *  invokeReject, Esc → invokeCancel. Without these the bar would
     *  only respond to clicks. */
    invokeAccept(): boolean;
    invokeReject(): boolean;
    invokeCancel(): boolean;
    /** Override the "running" indicator label; `null` falls back to the
     *  locale-aware default ("處理中…" / "Working…"). */
    setRunningLabel(label: string | null): void;
    showIndicator(state: 'listening' | 'processing' | 'done', label?: string): void;
    hideIndicator(): void;
    /** @internal Wrap inner HTML in the shell — pinned × button + a
     *  `bar-scroll` container that can max-height-cap + scroll without
     *  losing the close button. Persistent opts skip the ×. */
    _wrapBarShell(innerHtml: string): string;
    /** @internal */
    _closeLabel(): string;
    /** @internal Idempotent — safe to call after any wrapBarShell render. */
    _wireClose(): void;
    /** @internal */
    _handleCloseClick(): void;
    /** @internal Touch devices use the bar's tap-gesture instead of the
     *  ✓/✕ buttons (redundant + heavy on small screens). Copy stays —
     *  no gesture equivalent. Monochrome glyphs only — no emoji. */
    _renderButtons(opts: SubtitleShowOptions): string;
    /** @internal Single delegated click listener (vs per-button) so no
     *  dangling listeners accumulate when innerHTML is replaced mid-life. */
    _wireButtons(opts: SubtitleShowOptions): void;
}

declare class TypedEmitter {
    private handlers;
    on<E extends DddkEventName>(event: E, handler: DddkEventHandler<E>): void;
    off<E extends DddkEventName>(event: E, handler: DddkEventHandler<E>): void;
    emit<E extends DddkEventName>(event: E, payload: DddkEventMap[E]): void;
    clear(): void;
}

/** Memory v1 — three-tier hybrid memory for the webagent. */
type CoreFieldType = 'string' | 'array' | 'object' | 'number' | 'boolean';
type CoreMemorySchema = Record<string, CoreFieldType>;
interface CoreMemoryConfig {
    /** Field shape the LLM may write into. When omitted, free-form key-value. */
    schema?: CoreMemorySchema;
    /** Where to keep the core block. Defaults to `localStorage`. */
    storage?: 'localStorage' | 'sessionStorage' | 'memory';
    /** Max stored byte budget. Writes that exceed are dropped + warned. */
    maxBytes?: number;
}
interface EpisodicMemoryConfig {
    enabled?: boolean;
    /** Ring-buffer cap of stored session summaries. */
    maxEntries?: number;
    /** How many summaries to load into the prompt per new run. */
    replayTopK?: number;
    /** Selection heuristic. `keyword` does cheap token overlap; `recency` is order. */
    relevance?: 'recency' | 'keyword';
    storage?: 'localStorage' | 'sessionStorage' | 'memory';
}
interface EpisodicEntry {
    id: string;
    summary: string;
    tags?: string[];
    timestamp: number;
    turnCount?: number;
    taskSummary?: string;
}
interface SemanticMemoryEntry {
    id: string;
    content: string;
    tags?: string[];
    metadata?: Record<string, unknown>;
    timestamp: number;
}
/** Host-implemented backend for tier-3 semantic memory (vector store /
 *  knowledge graph / whatever). dddk wires the agent's call site but does
 *  NOT embed or persist — that's the host's job. */
interface MemoryProvider {
    remember(entry: Omit<SemanticMemoryEntry, 'id' | 'timestamp'>): Promise<string>;
    recall(query: string, opts?: {
        topK?: number;
        tags?: string[];
    }): Promise<SemanticMemoryEntry[]>;
    forget(id: string): Promise<void>;
    list?(opts?: {
        tags?: string[];
        limit?: number;
    }): Promise<SemanticMemoryEntry[]>;
}
interface SemanticMemoryConfig {
    provider: MemoryProvider;
    /** `explicit` — only writes when user marks important or the agent tool
     *  call asks. `auto` — writes a candidate every turn (off by default). */
    writeMode?: 'explicit' | 'auto';
}
interface MemoryPrivacyConfig {
    /** Surface a one-off opt-in UI before the first write. */
    requireConsent?: boolean;
    /** Cleanup horizon. Older episodic entries are dropped on next read. */
    retentionDays?: number;
    /** Regex set that blocks matching text from being written. */
    excludePatterns?: RegExp[];
}
interface MemoryConfig {
    core?: CoreMemoryConfig;
    episodic?: EpisodicMemoryConfig;
    semantic?: SemanticMemoryConfig;
    privacy?: MemoryPrivacyConfig;
}

interface DotDotDuckConfig {
    locale?: Locale;
    agentName?: string;
    siteName?: string;
    /**
     * LLM source — single `LLMProvider` (same model everywhere) or `LLMRouter`
     * (per-role). Required for any agent functionality; if omitted, palette
     * commands without LLM still work but `startAgent()` will no-op with a
     * subtitle warning, and Voice / SelectionTools will reject construction.
     */
    llm?: LLMSource;
    /** Skills available in palette and via /command syntax. */
    skills?: Skill[];
    /** 3-tier hybrid memory (core / episodic / semantic). All tiers opt-in.
     *  When set, agent context is augmented with the relevant memory blocks
     *  on every new run. */
    memory?: MemoryConfig;
    /** Palette commands. dddk ships ZERO built-in commands; host adds all. */
    paletteCommands?: PaletteItem[];
    /**
     * WebAgent config (excluding `llm`, which lives at top level on this config).
     * Use `brand` + `appendSystemPrompt` to layer domain knowledge onto the
     * default prompt — see docs/13-prompt-design.md for the API.
     * dddk creates the WebAgent instance internally and intercepts its events
     * so that subtitles / surface / ask_user all flow through dddk's UI layer.
     */
    webAgent?: Omit<WebAgentConfig, 'llm' | 'customActions'> & {
        customActions?: WebAgentConfig['customActions'];
    };
    /**
     * Per-entry webagent behavior.
     *
     * The same webagent is used from three entry points:
     *   - voice     — push-to-talk / continuous listen
     *   - selection — user selects text then asks AI
     *   - palette   — palette "Ask AI" free-text input
     *
     * Each entry can be either `one_shot` (ask → answer → close) or
     * `continuous` (stays open as a panel, can chain more turns).
     *
     * `voice.keepListening: true` is the "walkie-talkie" mode — mic auto-reopens
     * after the agent finishes responding.
     *
     * Defaults: voice / selection one_shot, palette continuous.
     */
    webAgentEntries?: {
        voice?: {
            mode?: 'one_shot' | 'continuous';
            keepListening?: boolean;
        };
        selection?: {
            mode?: 'one_shot' | 'continuous';
        };
        palette?: {
            mode?: 'one_shot' | 'continuous';
        };
    };
    /**
     * Inject persistent context into the agent at each turn. Host queries their
     * own backend (CRM / customer DB / long-term memory) and returns system
     * messages to prepend. Toolbox keeps only session-level context internally.
     */
    webAgentContextProvider?: (turn: {
        customerId?: string;
        text: string;
        sessionId?: string;
    }) => Promise<Array<{
        role: 'system' | 'assistant' | 'user';
        content: string;
    }>> | Array<{
        role: 'system' | 'assistant' | 'user';
        content: string;
    }>;
    /**
     * Voice input config. Default: `{ enabled: true }`. Set `enabled: false`
     * to disable the hold-space STT gesture (palette / spotter still work).
     * Can be flipped at runtime via `dddk.setVoiceEnabled(bool)`.
     */
    voice?: {
        enabled?: boolean;
    };
    /**
     * DOM-grounded agent config. Default: `{ enabled: true }` when `llm` is
     * set; effectively off when `llm` is unset.
     *
     * Set `enabled: false` to keep the LLM (for inline AI / voice cleanup /
     * other roles) but completely disable the agent loop — `startAgent()`
     * no-ops with an info subtitle, palette plain-text Enter does NOT fire
     * the agent, and skills that emit `agent` calls log a warning. Use this
     * when you want dddk's palette / voice / Dwell pieces but explicitly
     * NOT the autonomous "let the agent click things on the page" pathway.
     *
     * Can be flipped at runtime via `dddk.setAgentEnabled(bool)`.
     */
    agent?: {
        enabled?: boolean;
    };
    /** Per-host storage (for clipboard history, recent commands, etc.). Defaults to localStorage. */
    storage?: StorageAdapter$1;
    /** Host route navigation callback (for SPA-friendly nav). Hosts whose
     *  router returns a Promise (e.g. SvelteKit's `goto(path)`) should
     *  return that Promise so the agent knows when the page render
     *  completes before reading the new DOM. */
    onNavigate?: (path: string) => void | Promise<void>;
    /**
     * Custom renderer for PanelSkill surfaces. When a PanelSkill calls
     * `ctx.render(surface)`, the runtime hands the surface to this
     * function which paints it into the panel content area. Use this to
     * support host-defined surface shapes (rich HTML, framework components,
     * piece schemas). When omitted, the runtime renders nothing — the
     * skill is responsible for any DOM via other side-effects.
     *
     * The `onAction(actionName, data)` callback wires user gestures
     * (clicks on `[data-dddk-action]` elements) back to the skill's
     * `onAction` handler.
     */
    panelRenderPiece?: (container: HTMLElement, surface: unknown, onAction: (action: string, data: unknown) => void) => void;
    /** Override gesture key (legacy 'ctrl' for migration). Default 'space'. */
    gestureKey?: 'space' | 'ctrl';
    /**
     * How long the user must hold the gesture key before voice triggers.
     * Default 250ms — snappy enough that the gesture feels live, clear of
     * the natural fast-typing space-tap range (~80-200ms). Bump if your
     * audience types prose fast and hits accidental voice triggers; lower
     * if you want the gesture to feel even more instant.
     */
    holdThresholdMs?: number;
    /**
     * Window for "second tap counts as double-tap reject" detection.
     * Default 350ms. Two space taps inside this window → onReject;
     * outside → second tap is just a fresh single-tap. Useful to tune for
     * users with slower fingers (raise) or to fire reject more eagerly
     * (lower).
     */
    doubleTapWindowMs?: number;
    /** Locale dictionary override. */
    i18n?: I18nDict;
    /**
     * Camera icon at the right of the palette input — lets users attach an image
     * (uploaded file or page screenshot) to their next query.
     *   - omit / undefined: no camera button (default)
     *   - `false`: explicitly off (same as omit, but type-clear)
     *   - object: enable with this config (see {@link CameraOptions})
     */
    camera?: CameraOptions | false;
    /** Show a circular submit/send button at the right edge of the palette input. */
    submitButton?: boolean;
    /**
     * Optional chip row rendered below the palette input. Each `PaletteItem`
     * with a `category` field that matches a chip's `id` shows when that
     * chip is active. An implicit "All" chip is prepended automatically.
     */
    paletteCategories?: PaletteCategory[];
    /** Label for the implicit "All" chip. Defaults to "All". */
    paletteAllCategoriesLabel?: string;
    /**
     * Override the indicator labels shown in the subtitle bar. All fields
     * optional — leave undefined to use the bundled locale-aware defaults.
     *
     *  - `running`: shown immediately after the user taps Space accept /
     *    reject on an agent confirm prompt, while the next LLM call is
     *    in flight. Defaults: `'Agent 執行中…'` (zh-TW) / `'Agent running…'`.
     *  - `processing`: shown by the SDK's `dddk.subtitle.showIndicator
     *    ('processing')` calls (immersive-translate progress, voice
     *    transcription, etc.) when no explicit label is passed.
     *  - `listening`: STT-active indicator label.
     *
     * Pass strings or per-locale records:
     *   indicators: { running: 'Working on it…' }
     *   indicators: { running: { en: 'Working…', 'zh-TW': '處理中…' } }
     */
    indicators?: {
        running?: string | Record<string, string>;
        processing?: string | Record<string, string>;
        listening?: string | Record<string, string>;
    };
    /**
     * Auto-hide policy for the streaming subtitle bar AFTER the agent's
     * final paragraph has fully streamed in (`AgentEvent kind: 'final'`).
     * Pass:
     *  - `0` or omit — uses the SDK default (12s).
     *  - milliseconds — auto-hide after this many ms once finalized.
     *
     * Errors that abort the run get a separate `error` slot — same
     * config shape if you pass an object.
     */
    agentSubtitleAutoHideMs?: number | {
        summary?: number;
        error?: number;
    };
}

/**
 * Agent lifecycle — owns building the WebAgent, the per-turn event
 * pump, confirm routing, loop-closure rendering, and all stop / resume
 * paths.
 *
 * Stateless helper class: receives the `DotDotDuck` host on construction
 * and reads / writes its internal `_*` fields. Wrapping these inside a
 * class keeps the file boundary stable without leaking a second public
 * type into the SDK surface.
 */

declare class AgentLifecycle {
    private readonly host;
    constructor(host: DotDotDuck);
    /**
     * Kick the webagent. `selection` defaults to whatever was captured at the
     * last palette open — pass `{ selection: null }` to force no selection
     * context, or pass an explicit `SelectionContext` to override.
     */
    startAgent(task: string, options?: {
        selection?: SelectionContext | null;
    }): void;
    runAgentStream(task: string, opts?: {
        selection?: SelectionContext;
    }): void;
    private beginAgentRun;
    endAgentRunCompleted(): void;
    endAgentRunStopped(reason: 'close' | 'esc' | 'reject' | 'palette' | 'voice' | 'unknown'): void;
    /** Resume a saved session — used by the host's onMount after a full
     *  page reload. If there's no saved session or it's in a terminal
     *  state, no-ops. Otherwise pumps the stream into the dddk UI as if
     *  the loop had never been interrupted. */
    resumeAgent(): void;
    /**
     * Fire the same "accept" gesture that single-tap Space fires on
     * desktop — emits `gesture_accept`, advances script skills waiting
     * on it, advances streaming pause hints, accepts confirm dialogs,
     * etc. Use this from a mobile FAB tap or any host-built "next"
     * button so touch users get the full Space-equivalent pipeline,
     * not just `subtitle.invokeAccept()` (which alone misses script
     * skills + intent analytics).
     */
    triggerAccept(): void;
    /**
     * Fire the same "reject" gesture that double-tap Space fires on
     * desktop — emits `gesture_reject`, exits script skills, rejects
     * confirms, or stops an in-flight agent. Use this from a mobile
     * double-tap on the FAB / subtitle bar.
     */
    triggerReject(): void;
    /**
     * Cross-cutting "stop the agent now" handler. Reasons:
     *   - `close`: user clicked the × on the subtitle bar
     *   - `esc`: Escape key while agent was running
     *   - `palette`: user opened the command palette (which means they
     *     want to send a new prompt)
     *   - `reject`: user double-tapped Space to reject
     *   - `voice`: user long-pressed Space to start a new voice prompt
     *
     * Surfaces a brief "stopped — say something new" subtitle so the user
     * knows their gesture worked and the agent is safely halted. Skipped
     * if the agent wasn't running (avoids "stopped" flashing on idle).
     */
    handleUserStopAgent(reason: 'close' | 'esc' | 'palette' | 'reject' | 'voice'): void;
    /** Read a host-supplied indicator label override (`config.indicators
     *  .processing` / `.listening`). Accepts string or per-locale map. */
    private resolveIndicatorOverride;
    /** Pull the auto-hide ms for agent summary / error subtitles out of
     *  config. Returns 0 (sticky) when the host didn't configure it. */
    private resolveAgentAutoHide;
    buildAgent(): WebAgent;
    /**
     * Consume the agent's AsyncIterable<AgentEvent> stream and route each
     * event to its dddk UI slot:
     *
     *   thinking     → showIndicator('processing')
     *   text-delta   → subtitle.appendStreamed(delta) (cancels the indicator)
     *   tool-start   → frame target element, hide indicator
     *   tool-end     → no-op (next text-delta or next tool-start carries the visual)
     *   confirm      → subtitle.show with onAccept / onReject calling decide()
     *   navigated    → clear overlays (the bridge already moved the router)
     *   final        → finalizeStreamed with autoHide
     *   error        → subtitle.show error
     *
     * The async `for await` loop runs in the background — the host's
     * `startAgent()` returns synchronously, and event handlers on the
     * orchestrator (gestures, palette, voice) keep firing throughout.
     */
    pumpAgentStream(stream: AsyncIterable<AgentEvent>): Promise<void>;
    /**
     * Resolve the active `onLoopEnd` config — host override, or the SDK
     * default of a temperate "✓ Done" line. Returning `{kind: 'silent'}`
     * means legacy "subtitle disappears" behaviour.
     */
    private resolveLoopEnd;
    /**
     * Render the configured loop closure when the agent loop ends. Sits
     * between `finalizeStreamed` and `endAgentRunCompleted` in
     * pumpAgentStream.
     *
     * Each kind maps onto an existing subtitle surface:
     *   text     → subtitle.show with autoHide; no gesture wiring.
     *   feedback → subtitle.show with onAccept/onReject/onCancel, emits
     *              `agent_feedback` with satisfied = true / false / null.
     *   ask_user → subtitle.showChoice; the picked value flows into
     *              `agent_feedback.summary`.
     *   silent   → no-op; legacy "subtitle disappears" behavior.
     */
    private renderLoopClosure;
    /**
     * Route a `confirm` event to the subtitle bar with Space-accept /
     * double-tap-reject wiring. The agent is awaiting `decide()` — we
     * resolve it from the user's gesture.
     */
    private routeConfirm;
    /**
     * Collect palette commands that have opted into agent exposure
     * (via `agentTool: {...}`), turn them into WebAgent customActions.
     */
    collectPaletteTools(): NonNullable<WebAgentConfig['customActions']>;
    /** Normalize palette id → safe action name (a-z0-9_). */
    private toolNameOf;
}

/**
 * `dddk.sessions` — named session registry.
 *
 * Hosts wiring multiple agents (different personas per route, an
 * admin agent vs a docs agent, WebAgent + TaskAgent on the same
 * page) need a shared place to hold `AgentSession` objects so the
 * agents can read + append to the same conversation history. The
 * registry mediates: agents inject the session by reference, the
 * registry owns the lifecycle (create, reset, persist, clear).
 *
 * Persistence is OPT-IN per session via `persistKey` so the agent
 * pattern from v0.1 (one session, one localStorage key) keeps
 * working. Sessions without a `persistKey` live in memory only.
 *
 * v0.2.0.
 */

declare class SessionsRegistry {
    private map;
    /** Track persistKey per name so reset / clear can update storage. */
    private persistKeys;
    /**
     * Fetch (or create-on-first-call) a named session. If `persistKey`
     * is provided AND a saved session exists under that key, it's
     * loaded once and cached; subsequent calls return the same in-memory
     * object so multiple agents share by reference.
     */
    get(name: string, opts?: {
        persistKey?: string;
        currentPage?: string;
    }): AgentSession;
    /** True when the registry has a session under this name. */
    has(name: string): boolean;
    /** All registered session names. */
    list(): string[];
    /**
     * Replace the session under `name` with a fresh one. All agents
     * holding a reference to the OLD session keep that reference —
     * they should call `dddk.sessions.get(name)` again to pick up the
     * new object. This is the "user explicitly started a new
     * conversation" path.
     */
    reset(name: string, opts?: {
        currentPage?: string;
    }): AgentSession;
    /** Persist the cached session under `name`. No-op for in-memory sessions. */
    persist(name: string): void;
    /**
     * Remove the session from the registry. If it was persisted, also
     * wipes the underlying storage entry. Agents holding a reference
     * to the prior object see no change until they re-fetch via
     * `get(name)`.
     */
    clear(name: string): void;
    /** Drop every session from the registry (memory + storage). */
    clearAll(): void;
}

/**
 * `dddk.agents` — named agent registry + active-agent slot.
 *
 * Hosts wiring multiple agents (different prompts / sitemaps /
 * personas per route) register each one by name; the orchestrator
 * routes the "current" agent's calls (palette commands, voice
 * captures, dwell selections) through whatever the host has set
 * active. Switching active on a route change preserves cross-page
 * continuity when the agents share a session via `dddk.sessions`.
 *
 * Holds WebAgent instances today; TaskAgent slots in via the same
 * interface
 *
 * v0.2.0.
 */

declare class AgentsRegistry {
    private map;
    private activeName;
    /**
     * Register an agent under `name`. If `name` is already registered
     * the previous entry is replaced; the previous agent's `destroy()`
     * is NOT called automatically — host owns the lifecycle.
     *
     * The first register call also becomes the active agent unless
     * another was already set.
     */
    register(name: string, agent: WebAgent): void;
    /**
     * Remove an agent from the registry. If it was the active one,
     * clears the active slot (host must `setActive` again).
     */
    unregister(name: string): void;
    /** Lookup by name. Returns `undefined` when not registered. */
    get(name: string): WebAgent | undefined;
    /** True when the registry has an agent under this name. */
    has(name: string): boolean;
    /** All registered agent names. */
    list(): string[];
    /**
     * Make `name` the active agent. Throws when no agent is registered
     * under that name — silently swallowing would mask host config
     * bugs that are otherwise hard to spot.
     */
    setActive(name: string): void;
    /** Currently-active agent. `null` when nothing is registered. */
    getActive(): WebAgent | null;
    /** Name of the active agent, or `null` if unset. */
    getActiveName(): string | null;
}

/**
 * Skill dispatch — looks up a skill by id / slash command, gates on
 * preferences, then routes by skill type (script / prompt / action /
 * surface / panel). Also owns the ad-hoc surface tools (`showSurface
 * AndAwait` / `submitSurface` / `cancelSurface`) used by ScriptSkill
 * steps and host code.
 *
 * Wrapped as a helper class taking the `DotDotDuck` host so it can
 * reach into `_prefs`, `_pendingSurface`, etc., without leaking a
 * second public type into the SDK surface.
 */

declare class SkillDispatcher {
    private readonly host;
    constructor(host: DotDotDuck);
    runSkill(idOrCommand: string, vars?: Record<string, string>): Promise<void>;
    private runScriptSkill;
    /**
     * Resolves on the next user gesture:
     *   - `'accept'`  → single space tap or accept-button click
     *   - `'escape'`  → Esc key
     *   - `'reject'`  → double space tap (treated as exit by ScriptSkill)
     *
     * Callers can branch on the outcome to advance vs. bail out of a
     * multi-step flow.
     */
    private waitForAcceptOrEscape;
    buildSkillTools(): SkillTools;
    /**
     * Show a Surface and await the host's submission. Used by skill tools and
     * any host code that wants the same "emit → user fills → resolve" pattern.
     */
    showSurfaceAndAwait(surface: unknown, placement?: SurfacePlacement): Promise<Record<string, unknown> | null>;
    /**
     * Host calls this when the user submits the active Surface form. Routes
     * to whichever subsystem opened the surface:
     *   - If a ScriptSkill called `tools.surface(...)` → resolves that promise
     *   - If webagent was awaiting a host interaction → resumes the agent loop
     * (Both can be pending at once in theory — we resolve both for safety.)
     */
    submitSurface(data: Record<string, unknown>): void;
    /** Host calls this when the user cancels the Surface (Esc / backdrop click). */
    cancelSurface(): void;
    buildActionContext(skillId?: string): ActionSkillContext;
    buildPaletteItems(): PaletteItem[];
}

/**
 * Highlight overlay — frame any DOM element with the same outline Dwell
 * uses on long-press selection.
 *
 * Self-contained module: owns `highlightedEl` + `highlightDismissTimer`
 * state. The orchestrator forwards `highlightElement` / `clearHighlight`
 * to a single instance held on the class.
 *
 * Frame style shares the `[data-dddk-dwell-target]` attribute defined
 * in `dwell/styles.ts` so only one element is framed at a time and
 * theming flows through `--dddk-dwell-frame-*` CSS vars.
 */
declare class HighlightOverlay {
    private highlightedEl;
    private highlightDismissTimer;
    /**
     * Frame an element with the same outline Dwell uses on long-press.
     * Replaces any existing highlight (only one frame at a time).
     *
     * @returns true if the element was found and framed
     */
    highlightElement(target: string | HTMLElement, opts?: {
        autoDismiss?: number;
        scroll?: boolean;
    }): boolean;
    /** Remove any active highlight frame. */
    clearHighlight(): void;
}

/**
 * Per-run intent bookkeeping.
 *
 * A "run" is one user query and everything that follows it — narrations,
 * tool calls, confirms, pauses, until the loop ends (final / stopped).
 * We give it an id at start time and buffer every intent emitted while
 * it's active. Hosts call `exportAgentRun()` to get the whole thing
 * (session + intents) as one JSON blob.
 */

declare class IntentBuffer {
    private _currentRunId;
    private _currentRunIntents;
    /**
     * Active skill id while a skill is running. Set on skill_started and
     * cleared on skill_finished. Read by `renderLoopClosure` so the
     * `agent_feedback` IntentEvent can attribute satisfaction back to the
     * skill that triggered the run — enables per-skill quality breakdown
     * on the dashboard without after-the-fact time-window heuristics.
     */
    currentSkillId: string | null;
    get currentRunId(): string | null;
    get currentRunIntents(): IntentEvent[];
    /** Emit + buffer. Routes through the host's TypedEmitter, then appends
     *  to the active run if any. */
    emitIntent(emitter: TypedEmitter, event: IntentEvent): void;
    beginAgentRun(emitter: TypedEmitter, task: string, sessionId: string): void;
    endAgentRunCompleted(emitter: TypedEmitter, sessionId: string, turnCount: number): void;
    endAgentRunStopped(emitter: TypedEmitter, sessionId: string, reason: 'close' | 'esc' | 'reject' | 'palette' | 'voice' | 'unknown'): void;
    /**
     * Snapshot the current (or most-recent) agent run as a single JSON
     * blob — session turns + every intent emitted during the run. Useful
     * for shipping a complete query record to a dashboard / DB after the
     * loop ends. Returns `null` if no session is provided.
     */
    exportAgentRun(session: AgentSession | null | undefined): {
        runId: string;
        sessionId: string;
        session: AgentSession;
        intents: IntentEvent[];
        exportedAt: number;
    } | null;
}

/** Tier 1 — structured user profile, always in context. < maxBytes. */
declare class CoreMemory {
    private data;
    private schema?;
    private storage;
    private maxBytes;
    constructor(cfg?: CoreMemoryConfig);
    private load;
    private persist;
    private validateField;
    get(key: string): unknown;
    set(key: string, value: unknown): boolean;
    remove(key: string): void;
    snapshot(): Record<string, unknown>;
    clear(): void;
    /** Render as a system-prompt block. Empty string when no entries. */
    toPromptBlock(): string;
}

/** Tier 2 — ring buffer of past session summaries. */
declare class EpisodicMemory {
    private entries;
    private maxEntries;
    private replayTopK;
    private relevance;
    private storage;
    private retentionDays;
    constructor(cfg?: EpisodicMemoryConfig, retentionDays?: number);
    private load;
    private persist;
    private pruneExpired;
    add(entry: Omit<EpisodicEntry, 'id' | 'timestamp'> & {
        id?: string;
        timestamp?: number;
    }): EpisodicEntry;
    list(): EpisodicEntry[];
    remove(id: string): void;
    topK(query: string | null, k: number): EpisodicEntry[];
    clear(): void;
    /** Render as a system-prompt block. Empty string when no replays. */
    toPromptBlock(query?: string | null): string;
}

/** Tier 3 — thin wrapper over a host-provided MemoryProvider. dddk does
 *  NOT embed or persist; the host's provider owns infra. */
declare class SemanticMemory {
    private provider;
    readonly writeMode: 'explicit' | 'auto';
    constructor(cfg: SemanticMemoryConfig);
    recall(query: string, opts?: {
        topK?: number;
        tags?: string[];
    }): Promise<SemanticMemoryEntry[]>;
    remember(entry: Omit<SemanticMemoryEntry, 'id' | 'timestamp'>): Promise<string>;
    forget(id: string): Promise<void>;
    list(opts?: {
        tags?: string[];
        limit?: number;
    }): Promise<SemanticMemoryEntry[]>;
    toPromptBlock(recalled: SemanticMemoryEntry[]): string;
}

interface StorageAdapter {
    open(name: string): Promise<void>;
    get<T = unknown>(key: string): Promise<T | undefined>;
    set(key: string, value: unknown): Promise<void>;
    delete(key: string): Promise<void>;
    iterate(prefix: string): AsyncIterable<[string, unknown]>;
    close(): Promise<void>;
}
type StorageKind = 'memory' | 'indexeddb' | 'localstorage' | StorageAdapter;

type Drawer = {
    id: string;
    text: string;
    ts: number;
    wing?: string;
    room?: string;
    meta?: Record<string, unknown>;
};
type DrawerMemoryOpts = {
    customerId: string;
    storage?: StorageKind;
    /**
     * Optional host-supplied tokeniser. Receives the drawer text, returns
     * the feature list used for BM25 recall. Default handles 200+ languages
     * out of the box (no per-locale packs). See `dddk/utils/text`.
     */
    extractFeatures?: (text: string) => string[];
    sync?: {
        bootstrap?: () => Promise<{
            drawers: Drawer[];
        }>;
        pushChange?: (change: {
            op: 'add' | 'remove';
            drawer?: Drawer;
            id?: string;
        }) => Promise<void>;
    };
};
type DrawerSearchOpts = {
    topK?: number;
    scope?: {
        wing?: string;
        room?: string;
    };
    recencyBoost?: boolean;
};
declare class DrawerMemory {
    private customerId;
    private storage;
    private drawers;
    private features;
    private opened;
    private opts;
    private extract;
    constructor(opts: DrawerMemoryOpts);
    init(): Promise<void>;
    private indexDrawer;
    wing(name: string): WingScope;
    addDrawer(d: Omit<Drawer, 'id'> & {
        id?: string;
    }): Promise<Drawer>;
    removeDrawer(id: string): Promise<void>;
    search(query: string, opts?: DrawerSearchOpts): Promise<Drawer[]>;
    recent(opts?: {
        wing?: string;
        room?: string;
        days?: number;
        limit?: number;
    }): Drawer[];
    private persist;
    dispose(): Promise<void>;
}
declare class WingScope {
    private mem;
    name: string;
    constructor(mem: DrawerMemory, name: string);
    room(name: string): RoomScope;
    search(q: string, opts?: DrawerSearchOpts): Promise<Drawer[]>;
    recent(opts?: {
        days?: number;
        limit?: number;
    }): Drawer[];
}
declare class RoomScope {
    private mem;
    wing: string;
    room: string;
    constructor(mem: DrawerMemory, wing: string, room: string);
    addDrawer(d: {
        text: string;
        ts?: number;
        meta?: Record<string, unknown>;
    }): Promise<Drawer>;
    search(q: string, opts?: DrawerSearchOpts): Promise<Drawer[]>;
}
declare function createDrawerMemory(opts: DrawerMemoryOpts): DrawerMemory;

interface UnifiedMemoryConfig extends MemoryConfig {
    /** Drawer subsystem opts. Omit to skip the drawer backend entirely. */
    drawer?: DrawerMemoryOpts;
}
interface RememberOpts {
    /** Routing hint. `auto` (default) picks based on shape. */
    tier?: 'auto' | 'core' | 'drawer' | 'episodic';
    /** Drawer-only metadata. */
    wing?: string;
    room?: string;
    meta?: Record<string, unknown>;
    /** Core-only: which field to set when tier=core (or auto routing decides). */
    coreField?: string;
}
interface RecallResult {
    source: 'core' | 'drawer' | 'episodic' | 'semantic';
    text: string;
    ts?: number;
    meta?: Record<string, unknown>;
    score?: number;
}
declare class UnifiedMemory {
    readonly structured: Memory;
    readonly drawer: DrawerMemory | null;
    constructor(cfg?: UnifiedMemoryConfig);
    init(): Promise<void>;
    isPII(text: string): boolean;
    /**
     * Write a memory. Routing:
     *   - `tier: 'core'` + `coreField` → CoreMemory.set(field, text)
     *   - `tier: 'drawer'` (or auto when long-form) → DrawerMemory.addDrawer
     *   - `tier: 'episodic'` → no-op here (use endSession to commit one)
     *   - `tier: 'auto'` (default) → core if a coreField is supplied, else drawer
     */
    remember(text: string, opts?: RememberOpts): Promise<void>;
    /**
     * Read memory. Pulls from BOTH backends and merges by best-effort score.
     * For backward compatibility, hosts that just want a system-prompt block
     * can call `buildContext(query)` instead — same shape as the v0.1 Memory.
     */
    recall(query: string, opts?: {
        limit?: number;
    }): Promise<RecallResult[]>;
    /** Build the system-prompt context block. Delegates to structured Memory,
     *  then appends recent drawer entries if a drawer is configured. */
    buildContext(userQuery: string): Promise<string>;
    endSession(input: {
        summary: string;
        taskSummary?: string;
        tags?: string[];
        turnCount?: number;
    }): EpisodicEntry | null;
    clear(): void;
    dispose(): Promise<void>;
}
declare function createUnifiedMemory(cfg?: UnifiedMemoryConfig): UnifiedMemory;

/** Memory v1 — three-tier hybrid memory for the webagent.
 *
 *   core      — structured user profile, always in context
 *   episodic  — ring buffer of past session summaries
 *   semantic  — host-provided long-term recall (vector / KG / etc)
 *
 * All tiers are opt-in. A bare `new DotDotDuck({})` has memory disabled.
 *
 * The legacy verbatim-drawer store (formerly `Memory`) is still available
 * as `DrawerMemory` from `@perhapxin/dddk/agent` — they serve different
 * use cases and can coexist.
 */

declare class Memory {
    readonly core: CoreMemory | null;
    readonly episodic: EpisodicMemory | null;
    readonly semantic: SemanticMemory | null;
    private privacy;
    constructor(cfg?: MemoryConfig);
    /** Check if `text` would be blocked by PII patterns. */
    isPII(text: string): boolean;
    /** Build the system-prompt context block for a new agent run. Runs
     *  semantic recall against `userQuery` when wired. Empty string when
     *  no tier has content. */
    buildContext(userQuery: string): Promise<string>;
    /** Called when a session ends. Writes a short episodic summary if the
     *  tier is on. Caller supplies the summary text — hosts that want an
     *  LLM-generated summary should produce it before calling. */
    endSession(input: {
        summary: string;
        taskSummary?: string;
        tags?: string[];
        turnCount?: number;
    }): EpisodicEntry | null;
    /** Wipe all tiers. */
    clear(): void;
}

declare class DotDotDuck {
    readonly skills: SkillRegistry;
    /** @internal */
    _panelRuntime: PanelRuntime | null;
    readonly subtitle: Subtitle;
    readonly palette: CommandPalette;
    readonly spotter: Spotter;
    /**
     * Mount custom DOM into one of the canonical screen slots
     * (`subtitle` / `indicator` / `palette` / `dock` / `modal` / `banner`
     * / `fab` / `toast`). The slot's position, z-index, and max-width are
     * already defined by the shared placement stylesheet — hosts only
     * style the content, not the chrome.
     *
     *   const h = dddk.placement.mount('banner', '<div>Maintenance at 10pm</div>');
     *   // ... later:
     *   h.unmount();
     */
    readonly placement: Placements;
    /**
     * Pinned-panel registry — small persistent cards anchored to one of
     * the four screen corners. Use for onboarding checklists, "powered by"
     * widgets, multi-step forms.
     *
     *   const h = dddk.panel.create({
     *     id: 'getting-started',
     *     title: 'The Basics',
     *     items: [
     *       { kind: 'task', id: 'a', label: 'Create your first project' },
     *       { kind: 'task', id: 'b', label: 'Invite your team' },
     *     ],
     *     onSubmit: (data) => analytics.track('onboarding.done', data.values),
     *   });
     *   h.complete('a');
     *   h.unmount();
     */
    readonly panel: PinnedPanelRegistry;
    /**
     * Tool registry — host registers capabilities (QA / search / recommend /
     * custom domain actions) and the webagent picks them up automatically.
     * The LLM sees each tool's name + description + JSON-schema parameters,
     * decides when to call them, and the result feeds back into the loop.
     *
     *   dddk.tools.register({ name, description, parameters, handler });
     *   dddk.tools.registerQA({ items: customerFAQ });
     *   dddk.tools.unregister('qa_lookup');
     *   dddk.tools.list();
     *
     * Tools registered BEFORE the webagent is first invoked land in the
     * initial customActions set. Tools registered AFTER are injected into
     * the live agent via `agent.registerAction()`, so order doesn't matter.
     * Details + the QA convenience helper live in `tools-registry.ts`.
     */
    readonly tools: ToolsRegistry;
    /**
     * Prompt registry — one place to see, override, and localise every
     * LLM system prompt the SDK ships (WebAgent narrator, planner,
     * InlineAgent, translate, voice-cleanup, Dwell classifier, etc.).
     *
     *   dddk.prompts.list();                                              // enumerate ids
     *   dddk.prompts.override('inline-edit.system', 'ja', () => `…`);     // localise
     *   dddk.prompts.append('webagent-narrator.system', () => 'Always cite sources.');
     *
     * Uses the process-wide singleton so subsystems that don't hold a
     * DotDotDuck reference (module-level module inits) can still register
     * defaults. Hosts are expected to reach for this same registry via
     * `dddk.prompts` for the more discoverable API.
     */
    readonly prompts: PromptRegistry;
    /** @internal */ _config: DotDotDuckConfig;
    /** @internal */ _gestures?: GestureManager;
    /** @internal */ _emitter: TypedEmitter;
    /** @internal */ _storage: StorageAdapter$1;
    /** @internal */ _prefs: PreferenceStore;
    /** @internal */ _pendingPrefs: {
        skillId: string;
        resolve: () => void;
        reject: () => void;
    } | null;
    /**
     * Ad-hoc Surface awaiting host submission. Lifecycle:
     *   1. ScriptSkill step calls `tools.surface(...)` → emits `surface` event
     *   2. Host renders + collects user input
     *   3. Host calls `dddk.submitSurface(data)` or `dddk.cancelSurface()`
     *   4. The promise returned to the skill resolves with data (or null)
     * @internal
     */
    _pendingSurface: {
        resolve: (data: Record<string, unknown> | null) => void;
    } | null;
    /** @internal */ _agentInstance: WebAgent | null;
    /**
     * Named session registry — `dddk.sessions`. Hosts use this to share
     * a single `AgentSession` across multiple agents (one persona per
     * route, etc.) so cross-page conversation history + memory carry
     * over even when the active agent changes. v0.2.0.
     */
    readonly sessions: SessionsRegistry;
    /**
     * Named agent registry — `dddk.agents`. Hosts register multiple
     * `WebAgent` instances by name + designate which one is "active"
     * (the one palette / voice / dwell routes to). Singleton
     * `dddk.getAgent()` keeps working — it returns the active agent
     * when the registry is in use, otherwise the lazy-built one.
     * v0.2.0.
     */
    readonly agents: AgentsRegistry;
    /** @internal */ _voiceEnabled: boolean;
    /** @internal */ _agentEnabled: boolean;
    /** @internal */ _currentSelection: SelectionContext | null;
    /** @internal */ readonly _highlight: HighlightOverlay;
    /** @internal */ readonly _intentBuffer: IntentBuffer;
    /** @internal */ readonly _lifecycle: AgentLifecycle;
    /** @internal */ readonly _dispatcher: SkillDispatcher;
    readonly memory: Memory | null;
    constructor(config?: DotDotDuckConfig);
    /**
     * Update the active locale at runtime. Used by hosts that flip
     * `en` / `zh-TW` via an in-page toggle (no full reload). Updates the
     * orchestrator's own copy plus owned components (`subtitle`). Sibling
     * modules the host owns (`InlineAgent`, `VoiceModule`, …) need their
     * own `setLocale` call from the host.
     */
    setLocale(locale: Locale): void;
    mount(): void;
    destroy(): void;
    on<E extends DddkEventName>(event: E, handler: DddkEventHandler<E>): void;
    off<E extends DddkEventName>(event: E, handler: DddkEventHandler<E>): void;
    runSkill(idOrCommand: string, vars?: Record<string, string>): Promise<void>;
    /** Emit a structured intent event. Public so other modules can push too. */
    emitIntent(event: IntentEvent): void;
    /**
     *
     * Public host-facing `track(name, props?)` API. Mirrors the standard
     * product-analytics surface — engineers recognise this from existing
     * tooling. Routes through the same intent stream as the SDK's typed
     * events; downstream sinks see one canonical pipe.
     *
     * `name` should be snake_case past-tense ("order_completed",
     * "checkout_started") — describes what happened, not what to do.
     *
     * @example
     * ```ts
     * dddk.track('order_completed', { order_id, value: 49.99, items: 3 });
     * dddk.track('survey_dismissed');
     * ```
     */
    track(name: string, props?: Record<string, unknown>): void;
    /**
     * Frame an element with the same outline Dwell uses on long-press.
     * Replaces any existing highlight (only one frame at a time).
     *
     * @returns true if the element was found and framed
     */
    highlightElement(target: string | HTMLElement, opts?: {
        autoDismiss?: number;
        scroll?: boolean;
    }): boolean;
    /** Remove any active highlight frame. */
    clearHighlight(): void;
    /**
     * Lazy-initialize the PanelRuntime. The runtime is a separate DOM overlay
     * from the regular CommandPalette — it handles `PanelSkill` execution
     * (top input + bottom panel + navigation stack).
     * @internal
     */
    _ensurePanelRuntime(): PanelRuntime;
    /** Check whether a PanelSkill is currently active. */
    isPanelOpen(): boolean;
    /**
     * Programmatically fire `voice_start` — same event the long-press gesture
     * emits. Mobile FAB long-press, custom triggers (e.g. host's own header
     * button bound via `MobileTrigger.bindTrigger`), or any other entry point
     * can call this to enter voice mode without simulating keyboard events.
     */
    triggerVoiceStart(): void;
    /** Fire `voice_end` to match a prior `triggerVoiceStart`. */
    triggerVoiceEnd(): void;
    /** Programmatically close any active panel skill (Esc equivalent for host). */
    closePanel(): Promise<void>;
    /**
     * Kick the webagent. `selection` defaults to whatever was captured at the
     * last palette open — pass `{ selection: null }` to force no selection
     * context, or pass an explicit `SelectionContext` to override.
     */
    startAgent(task: string, options?: {
        selection?: SelectionContext | null;
    }): void;
    /**
     * Snapshot the current (or most-recent) agent run as a single JSON
     * blob — session turns + every intent emitted during the run. Useful
     * for shipping a complete query record to a dashboard / DB after the
     * loop ends. Returns `null` if no agent has ever run in this session.
     */
    exportAgentRun(): ReturnType<IntentBuffer['exportAgentRun']>;
    /** Resume a saved session — used by the host's onMount after a full
     *  page reload. If there's no saved session or it's in a terminal
     *  state, no-ops. Otherwise pumps the stream into the dddk UI as if
     *  the loop had never been interrupted. */
    resumeAgent(): void;
    /** Tell the agent that its continuity window should close now (used
     *  for `sessionScope: 'palette'` hosts when the palette closes). */
    endAgentContinuity(): void;
    /** Wipe any saved agent session — the next `runStream()` starts
     *  fresh. Hosts call this after a full page reload to drop an
     *  abandoned conversation from the previous load. */
    clearAgentSession(): void;
    /** Stop a running agent and clear its on-screen UI. Safe to call
     *  when the agent is idle (no-ops). Use this when the host wants to
     *  cancel mid-task — e.g. the user clicked an in-app link / sidebar
     *  entry, signalling they're moving on regardless of where the
     *  agent thinks it is. */
    stopAgent(): void;
    /**
     * Fire the same "accept" gesture that single-tap Space fires on
     * desktop — emits `gesture_accept`, advances script skills waiting
     * on it, advances streaming pause hints, accepts confirm dialogs,
     * etc. Use this from a mobile FAB tap or any host-built "next"
     * button so touch users get the full Space-equivalent pipeline,
     * not just `subtitle.invokeAccept()` (which alone misses script
     * skills + intent analytics).
     */
    triggerAccept(): void;
    /**
     * Fire the same "reject" gesture that double-tap Space fires on
     * desktop — emits `gesture_reject`, exits script skills, rejects
     * confirms, or stops an in-flight agent. Use this from a mobile
     * double-tap on the FAB / subtitle bar.
     */
    triggerReject(): void;
    /** Runtime toggle for voice (hold-space STT gesture). */
    setVoiceEnabled(enabled: boolean): void;
    isVoiceEnabled(): boolean;
    /**
     * Runtime toggle for the DOM-grounded agent loop. When `false`,
     * `startAgent()` no-ops with a subtitle hint, palette plain-text Enter
     * does NOT fire the agent, and any in-flight run stops cleanly. Other
     * subsystems that use the LLM router (inline AI, voice cleanup, …)
     * keep working.
     */
    setAgentEnabled(enabled: boolean): void;
    isAgentEnabled(): boolean;
    /**
     * Active WebAgent. With multi-instance wiring (v0.2.0),
     * this returns whichever agent the host put in `dddk.agents` and
     * called `setActive(name)` on; falls back to the lazy-built
     * singleton from `startAgent` for hosts that haven't adopted the
     * registry. `null` when no agent is configured.
     */
    getAgent(): WebAgent | null;
    /** Forward a user response to the agent (for ask_user / surface form submits). */
    respondToAgent(answer: string | Record<string, unknown>): void;
    /**
     * Called by host after the user submits a preferences setup surface.
     * Persists the values and resumes the skill that triggered it.
     */
    submitPreferences(values: Record<string, unknown>): void;
    cancelPreferences(): void;
    /**
     * Show a Surface and await the host's submission. Used by skill tools and
     * any host code that wants the same "emit → user fills → resolve" pattern.
     */
    showSurfaceAndAwait(surface: unknown, placement?: SurfacePlacement): Promise<Record<string, unknown> | null>;
    /**
     * Host calls this when the user submits the active Surface form. Routes
     * to whichever subsystem opened the surface:
     *   - If a ScriptSkill called `tools.surface(...)` → resolves that promise
     *   - If webagent was awaiting a host interaction → resumes the agent loop
     * (Both can be pending at once in theory — we resolve both for safety.)
     */
    submitSurface(data: Record<string, unknown>): void;
    /** Host calls this when the user cancels the Surface (Esc / backdrop click). */
    cancelSurface(): void;
    /** @internal */
    _navigate(path: string): void;
    /**
     * Capture rich selection context from the current Window.Selection plus
     * spotter's lock state. Best-effort — missing bits stay undefined.
     * @internal
     */
    _captureSelection(text: string): SelectionContext;
    /** @internal */
    _t(key: string, fallback: string): string;
    /** @internal — used by AgentLifecycle.buildAgent to collect palette tools. */
    _collectPaletteTools(): NonNullable<WebAgentConfig['customActions']>;
}

/**
 * InlineAgent scope registry.
 *
 * A "scope" is a per-region override of the root InlineAgent config: a
 * different action set, a different LLM, a different system prompt, a
 * different menu layout. Hosts attach scopes by CSS selector; when the
 * user makes a selection inside a matching element, the InlineAgent
 * resolves the innermost matching scope and uses its config instead of
 * the root config.
 *
 * Resolution flow per selection:
 *   1. If the host set a `scopeResolver` callback AND it returns a
 *      non-null config, that config wins (callback bypass).
 *   2. Else walk UP from the selection's anchor element. The FIRST
 *      ancestor that matches any registered selector is the innermost
 *      scope — its config wins.
 *   3. If nothing matches, the root config applies as before.
 *
 * Live registry — `attachScope` / `setScopeResolver` may be called at
 * any time. The next selection sees the new registration; an in-flight
 * menu doesn't change underneath the user.
 */

/**
 * Per-scope override. Every field is optional — what the scope doesn't
 * set inherits from the root InlineAgent config.
 */
interface InlineScopeConfig {
    /**
     * Replace the action set for selections inside this scope. When set,
     * the root's actions are NOT included — use `appendActions` instead
     * if you want to extend rather than replace.
     */
    actions?: InlineAction[];
    /**
     * Append these actions AFTER the root actions (or after `actions`
     * if this scope also sets that). Stacks cleanly with `disabledActions`
     * for "root actions minus some, plus my new ones".
     */
    appendActions?: InlineAction[];
    /**
     * Drop root actions by id. Only meaningful when this scope doesn't
     * set its own `actions` (because that already replaces the root set).
     */
    disabledActions?: string[];
    /** Override the LLM used for runs initiated from this scope. */
    llm?: LLMSource;
    /**
     * Replace the system prompt for runs from this scope. Use
     * `appendSystemPrompt` if you want to keep the base prompt and add
     * a tone / domain hint.
     */
    systemPrompt?: string;
    /**
     * Append text to the base system prompt. The base is whatever was
     * effective WITHOUT the scope — either root's `systemPrompt` or the
     * SDK default if root didn't set one. Combined: `${base}\n\n${append}`.
     */
    appendSystemPrompt?: string;
    /** Override menu layout (single-column / two-column / toolbar). */
    layout?: 'single-column' | 'two-column' | 'toolbar';
    /** Override two-column header labels. */
    columnLabels?: {
        col1?: string;
        col2?: string;
    };
    /** Override translate-target language list. */
    translateTargets?: Array<{
        code: string;
        label: string;
    }>;
    /**
     * Override the tool-call layer. Setting this enables a tool-call
     * loop for this scope even if the root has no tools; pass empty
     * array to explicitly disable tools for this scope.
     */
    tools?: ActionDefinition[];
}
/** Handle returned by `attachScope`; lets the host unregister later. */
interface ScopeHandle {
    /** Remove this scope from the registry. Idempotent. */
    remove(): void;
}
/**
 * Callback fallback for cases CSS selectors can't express (e.g.
 * "selections longer than 1000 chars use the long-form scope" or
 * "any element inside a Shadow DOM uses the shadow scope"). Return
 * `null` to fall through to selector matching.
 */
type ScopeResolver = (selection: {
    text: string;
    element: HTMLElement;
}) => InlineScopeConfig | null;

/**
 * InlineAgent — inline AI menu for text inside editable surfaces
 * (`<input>`, `<textarea>`, `[contenteditable]`).
 *
 * UX:
 *   1. User selects text inside an editable.
 *   2. A small floating menu pops next to the selection (top-right).
 *   3. Menu stays visible while the selection is active. Scroll repositions
 *      it; the menu does NOT auto-hide on idle.
 *   4. User picks an action (mouse OR keyboard — Ctrl/Cmd+. opens the menu
 *      programmatically, arrows + Enter navigate).
 *   5. Selected text is replaced with the LLM's result.
 *
 * Actions are host-customizable:
 *   - `actions` config replaces the default set
 *   - `addAction` / `removeAction` / `updateAction` at runtime
 *   - Per-action `build()` returns the LLM instruction dynamically — used by
 *     the default Translate action to pick a target language via sub-menu.
 *
 * Output cleanup: a wrapper system prompt forces the LLM to return ONLY
 * the result between `<<<RESULT>>>` markers. We strip everything else.
 * Avoids "thinking out loud" / preamble leaking into the editable.
 */

interface InlineAgentConfig {
    llm: LLMSource;
    /**
     * Replace the entire default action set. When provided, defaults are
     * NOT included. Use `appendActions` if you want to keep defaults +
     * add your own, or `disabledActions` to drop specific defaults.
     */
    actions?: InlineAction[];
    /**
     * Append your actions AFTER the (filtered) defaults. Combine with
     * `disabledActions` to keep some defaults, drop others, add your own.
     */
    appendActions?: InlineAction[];
    /**
     * Drop these default actions by id. Useful when you want most of the
     * defaults but not, say, "translate". Default ids: translate / improve /
     * fix / shorter / longer / tone / explain.
     */
    disabledActions?: string[];
    /**
     * Menu layout:
     *  - `'single-column'` (default): one column, all actions stacked.
     *  - `'two-column'`: two columns side-by-side. Each action's `row` (1 | 2)
     *    decides which column it belongs to. Optional `rowLabel` on each
     *    action surfaces a small header above the first action of that row.
     *  - `'toolbar'`: a horizontal, icon-only formatting bar (AFFiNE / Notion
     *    style) anchored ABOVE the selection, horizontally centred. No header.
     *    Each action renders as a square icon button — its `label` becomes the
     *    `title` / `aria-label` (no visible text). Use `group` to draw a thin
     *    divider between adjacent actions of different groups (e.g. format /
     *    block / AI). Use `kind: 'dropdown'` + `items` to collapse a cluster
     *    (turn-into, AI rewrite/translate/summarise) behind a single button
     *    that opens a vertical sub-menu on click.
     *
     * Two-column is the recommended layout for note-taking / editor hosts
     * that want one column of formatting actions (Bold / Italic / H1 / Color)
     * and another of AI actions (Translate / Improve / …).
     */
    layout?: 'single-column' | 'two-column' | 'toolbar';
    /** Optional headers shown above column 1 / column 2 in `two-column` layout. */
    columnLabels?: {
        col1?: string;
        col2?: string;
    };
    /**
     * Locale for built-in i18n labels. Default `'en'`. SDK ships `'en'` and
     * `'zh-TW'` translations; any other value falls back to `'en'` so the
     * UI never breaks. Hosts that want native labels (`'ja'`, `'es'`, …)
     * pass `actions` / `appendActions` with their own translated labels.
     */
    locale?: string;
    /** Languages offered when the user picks Translate. Default: en / zh-TW / ja. */
    translateTargets?: Array<{
        code: string;
        label: string;
    }>;
    /** Auto-hide after this many ms with no selection change. `0` = never (default). */
    hideAfterMs?: number;
    /** CSS selector — never trigger inside elements matching this. */
    ignoreSelector?: string;
    /**
     * Keyboard shortcut to open the menu when text is selected. Default `mod+.`
     * Format: `mod+<key>` where `mod` = Ctrl on Win/Linux, Cmd on Mac.
     * Alternative modifiers: `alt+<key>`, `shift+<key>`, combinations like
     * `mod+alt+<key>`.
     */
    shortcut?: string;
    /**
     * Default `displayAs` for actions that don't set their own. Overrides
     * the per-action default ('inline-diff' for rewrites, 'subtitle' for
     * explain). Set to `'replace'` to restore the pre-0.3 instant-splice
     * behaviour globally without editing every action's config.
     */
    defaultDisplayAs?: 'replace' | 'subtitle' | 'confirm' | 'inline-diff';
    /**
     * Override the system prompt sent to the LLM for inline edits. The
     * default is universal (works for any input language — the LLM detects
     * + replies in the same language) and enforces a strict JSON output
     * shape (`{ replacement: string }`) so the host can splice the result
     * back deterministically. Set this only if you need fully custom edit
     * semantics — your prompt MUST still produce the same JSON shape or
     * the splice will fail.
     */
    systemPrompt?: string;
    /**
     * Opt-in: type a prefix anywhere in an editable surface to fire an LLM
     * call with the rest of the text as instruction. Default OFF — has to
     * be enabled explicitly because it hijacks the input.
     *
     * Example: with `prefix: '/inline ai '` and `submitOn: 'enter'`, the
     * user types `/inline ai write me a haiku about ducks` and presses
     * Enter — the editable's whole value is replaced with the LLM result.
     *
     * Submit semantics:
     *  - `'enter'` (default): plain Enter submits. Newlines in textareas
     *    are NOT possible while a prefix is active.
     *  - `'mod-enter'`: Cmd/Ctrl+Enter submits, Enter still adds a newline.
     *  - `'double-newline'`: two consecutive `\n` submit (typing two Enters).
     */
    prefixTrigger?: {
        enabled: boolean;
        prefix?: string;
        minChars?: number;
        submitOn?: 'enter' | 'mod-enter' | 'double-newline';
        /** Show a "AI will replace this" confirmation step before commit. */
        confirmBeforeReplace?: boolean;
    };
    /**
     * Optional tool-call layer for inline-agent actions. **Default OFF.**
     *
     * When this array is non-empty the inline agent switches from a
     * single-shot LLM call to a small tool-call loop. The LLM can call
     * any tool listed here BEFORE producing the final `{ replacement }`
     * JSON — useful for "look up the customer in the CRM before
     * rewriting", "fetch the glossary term before translating", or any
     * other host-side data fetch that should ground the answer.
     *
     * Tools follow webagent's `ActionDefinition` shape so anything you
     * can hand to WebAgent works here unchanged. The loop stops as soon
     * as the LLM produces content without a tool call, or after
     * `maxToolRounds` rounds (safety cap).
     *
     * Leave undefined / empty to keep the original single-shot behaviour
     * — no tool calls, no extra latency.
     */
    tools?: ActionDefinition[];
    /**
     * When `true` and `tools` is non-empty, the inline agent uses
     * `dddk.subtitle` to narrate progress during the tool loop ("Looking
     * up customer record…", "Done — applying the rewrite"). Requires
     * `attachTo(dddk)` so the agent has a Subtitle handle. **Default false.**
     */
    enableSubtitle?: boolean;
    /**
     * Safety cap on the tool-call loop. Default `3`. Hosts with chained
     * lookups (search → fetch → verify) may want 4-5.
     */
    maxToolRounds?: number;
}
interface InlineActionHandlerCtx {
    text: string;
    target: HTMLElement;
    selection: {
        start: number;
        end: number;
    };
    agent: InlineAgent;
}
interface InlineAction {
    id: string;
    /** Visible label. Pass an `{ en, 'zh-TW' }` object for i18n. */
    label: string | {
        en: string;
        'zh-TW': string;
    };
    icon?: string;
    /** Which column this action lives in when `layout: 'two-column'`. Default 1. Ignored in single-column. */
    row?: 1 | 2;
    /**
     * `layout: 'toolbar'` only. A group key for visual clustering. A thin
     * vertical divider is drawn between two adjacent toolbar buttons whose
     * `group` differs — e.g. tag format actions `'format'`, block actions
     * `'block'`, AI actions `'ai'` to get three visually separated clusters.
     * Ignored in single / two-column layouts.
     */
    group?: string;
    /**
     * Action kind. Default `'button'` — runs the action directly.
     * `'dropdown'` (toolbar layout) renders the button with a small chevron;
     * clicking it opens a vertical sub-menu of `items` instead of running an
     * action. Each item is itself an `InlineAction` and runs through the
     * normal handler / build / instruction flow when picked.
     */
    kind?: 'button' | 'dropdown';
    /**
     * Sub-menu entries for a `kind: 'dropdown'` action. Each item runs through
     * the same `runAction` pipeline (handler > build > instruction) when the
     * user picks it. Lets a host fold a "Turn into" menu (H1 / H2 / bullet /
     * quote, each with a `handler` that reformats the block) or an "AI" menu
     * (rewrite / translate / summarise, each with an `instruction`) behind one
     * toolbar button so the bar stays compact.
     */
    items?: InlineAction[];
    /**
     * Where to put the LLM result.
     *  - `'replace'` (default): splice the result back over the user's
     *    selection immediately. The canonical inline edit (Translate,
     *    Rewrite, Fix grammar, …).
     *  - `'subtitle'`: don't touch the editable. Show the result in the
     *    subtitle bar — the right behaviour for actions like Explain /
     *    Summarise / Define where the user wants info, not to destroy
     *    their original text.
     *  - `'confirm'`: show the result in the subtitle bar with accept /
     *    reject buttons. ONLY on accept do we splice it back. Use this
     *    for risky / opinionated edits where the user wants to preview
     *    before commit. Space accepts, double-tap Space rejects (same as
     *    every other subtitle action prompt).
     *  - `'inline-diff'`: anchor a strikethrough-old → new diff panel under
     *    the selection. Streams tokens into the panel; on accept splices into
     *    the editable, on `insert-after` inserts as new text just after the
     *    selection (use for translation), on copy writes to clipboard. The
     *    panel carries a follow-up composer so the user can keep refining
     *    ("make it shorter", "more formal") with full chat history grounded
     *    on the original selection. Reject aborts the in-flight stream.
     */
    displayAs?: 'replace' | 'subtitle' | 'confirm' | 'inline-diff';
    /**
     * Static LLM instruction. Either set this OR `build` OR `handler`.
     * Precedence: `handler` > `build` > `instruction`.
     */
    instruction?: string;
    /**
     * Dynamic instruction. Use this when you need to ask the user for more
     * info first (e.g. Translate sub-menu picks a target language). Return
     * `null` to cancel without running the LLM.
     */
    build?: (ctx: {
        text: string;
        agent: InlineAgent;
    }) => Promise<string | null> | string | null;
    /**
     * Custom handler — runs INSTEAD of the LLM round-trip. Use for non-AI
     * actions like "wrap selection in **bold**", "insert markdown table",
     * "change color via document.execCommand". When defined, the LLM is
     * not called. The handler can read selection text + boundary indices
     * and mutate the editable directly.
     */
    handler?: (ctx: InlineActionHandlerCtx) => void | Promise<void>;
}
declare class InlineAgent {
    private cfg;
    private llm;
    private actions;
    private menu;
    private menuList;
    private subMenu;
    private currentEditable;
    private currentSelection;
    private currentRect;
    private hideTimer;
    private cleanups;
    private dddk;
    private cursor;
    private enabled;
    /** IME composing flag — `selectionchange` fires mid-composition for CJK
     *  input. We suppress menu show/hide while composing to avoid flicker.
     *  Set on `compositionstart`, cleared on `compositionend`. */
    private isComposing;
    /** Parsed shortcut spec (`{ ctrl, alt, shift, key }`) or `null`. */
    private shortcutSpec;
    /** In-flight run token — drops stale LLM results when the user fires a
     *  second action before the first finishes. */
    private runToken;
    /** Prefix-trigger state: tracks whether the focused editable is currently
     *  in "prefix mode" (text starts with the configured prefix). */
    private prefixActive;
    /** Scope registry: per-selector config overrides set via `attachScope`. */
    private scopes;
    /** Optional callback fallback for cases selectors can't express. */
    private scopeResolver?;
    /** Snapshot of the scope that matched the current selection's anchor
     *  element. `null` means "no scope matched, use root config". Refreshed
     *  in `handleSelectionChange`, frozen for the lifetime of the menu so
     *  an in-flight action sees the same scope as the menu that opened it. */
    private activeScopeConfig;
    /** Monotonic id for scope entries. */
    private scopeIdCounter;
    constructor(config: InlineAgentConfig);
    /**
     * Switch the menu / dialog locale at runtime. Pass any BCP-47-ish tag —
     * the bundled `en` / `zh-TW` translations are picked when they match;
     * other tags fall back to `en`.
     */
    setLocale(locale: string): void;
    private t;
    private buildDefaultActions;
    attachTo(dddk: DotDotDuck): void;
    destroy(): void;
    /** Append a new action to the bottom of the menu. */
    addAction(action: InlineAction): void;
    /** Remove an action by id. */
    removeAction(id: string): void;
    /** Partial update of an existing action's fields. */
    updateAction(id: string, patch: Partial<InlineAction>): void;
    /** Replace the entire action list. */
    setActions(actions: InlineAction[]): void;
    /**
     * Register a per-region override. Any selection whose anchor element
     * matches `selector` (or has an ancestor that does) will use
     * `config` instead of the root InlineAgent config. Innermost match
     * wins when scopes nest.
     *
     * Returns a handle whose `remove()` unregisters the scope.
     *
     * ```ts
     * const handle = inline.attachScope('[data-region="docs-comment"]', {
     *   actions: [translate, friendlyRewrite],
     *   appendSystemPrompt: 'Tone: friendly, customer-facing.',
     * });
     * // …later
     * handle.remove();
     * ```
     */
    attachScope(selector: string, config: InlineScopeConfig): ScopeHandle;
    /**
     * Set a callback fallback for cases CSS selectors can't express. The
     * resolver runs BEFORE selector matching — if it returns a non-null
     * config, that wins. Return `null` to fall through to selectors.
     */
    setScopeResolver(resolver: ScopeResolver | undefined): void;
    /**
     * Compute the effective config for the current selection. Merges the
     * matched scope (if any) onto the root config. Called from menu
     * builders + `runAction` so a single resolved view is reused.
     */
    private active;
    /** Toggle module on/off without unmounting. */
    setEnabled(on: boolean): void;
    isEnabled(): boolean;
    private handleSelectionChange;
    private showMenu;
    private repositionMenu;
    private mountMenu;
    private refreshMenu;
    private renderActions;
    private renderToolbar;
    private buildToolbarButton;
    /**
     * Open a vertical sub-menu under a toolbar dropdown button. Reuses the
     * `.ia-submenu` shell + click-away / Esc handling. Picking an item runs
     * it through the normal `runAction` pipeline and closes the dropdown.
     */
    private openDropdown;
    private renderSingleColumn;
    private renderTwoColumn;
    private buildActionRow;
    private paintActive;
    private hide;
    /** Hide ONLY if there's currently no selection. Used after outside clicks
     *  to avoid hiding while user is mid-drag re-selecting. */
    private maybeHide;
    private handleKey;
    private pickFromSubmenu;
    private runAction;
    /**
     * Stream tokens from the LLM straight into the target — character by
     * character into an input/textarea (mode=replace) or into the live
     * subtitle bar (mode=subtitle/confirm). Watches for the
     * `<<<REPLACEMENT>>>` start marker so we don't emit any preamble the
     * model leaks, and stops at `<<<END>>>` so trailing tokens don't
     * contaminate. Returns the final concatenated replacement string —
     * mode=confirm uses it to build the accept/reject UI after streaming.
     */
    private consumeStream;
    /** Splice text into an input / textarea at a known cursor position
     *  and update the cursor. Uses the React-aware native value setter so
     *  controlled inputs see the change. */
    private insertAtCursor;
    /**
     * Mini tool-call loop used when the host configured `tools` on
     * `InlineAgentConfig`. The LLM may call any tool any number of
     * times (up to `maxToolRounds`) before producing the final
     * `{ replacement }` JSON. Optional subtitle narration surfaces
     * the agent's progress so the user knows what's being looked up
     * before their text changes.
     */
    private runWithTools;
    /**
     * Suffix appended to the system prompt when tools are configured —
     * tells the LLM the loop shape (call tools first, then return the
     * final JSON) without rewriting the entire base prompt.
     */
    private toolSystemSuffix;
    /**
     * inline-diff mode. Mount the diff panel anchored under the selection,
     * stream tokens into it, then await the user's accept / insert-after /
     * copy / reject decision. Follow-up rounds keep the panel open and
     * stream a refined result grounded on the original selection.
     *
     * Reject (button / Escape / dispose) aborts the in-flight stream via a
     * per-stream AbortController — the upstream provider sees the disconnect
     * and stops generating tokens (cooperative cancel).
     */
    private runInlineDiff;
    private applyResult;
    /**
     * Keyboard shortcut handler — opens the menu for the current selection
     * even if `selectionchange` didn't fire (e.g. user is typing and wants
     * AI without re-selecting). When triggered with no active selection,
     * we fall back to selecting the focused word OR opening the menu
     * anchored at the caret with `prefixActive=false`.
     */
    private handleShortcut;
    /**
     * Prefix-trigger input handler. When `prefixTrigger.enabled` is true,
     * we watch every focused editable for text starting with the configured
     * prefix (default `/inline ai `). When detected, we mark `prefixActive`
     * so the next Enter (or mod+Enter / double newline) submits.
     *
     * The detection runs on every `input` event so it captures both typing
     * and paste. We do NOT auto-submit on typing — only on the configured
     * submit gesture, so the user can edit their prompt mid-typing.
     */
    private handlePrefixInput;
    private makePrefixSubmitter;
    private runPrefixSubmit;
    private getSelectionRect;
}

/**
 * TaskAgent types. Plain-protocol agent — conversation + host-defined
 * tool calling, NO DOM dump, NO CoT envelope. Lives beside WebAgent
 * and InlineAgent as the third agent kind. v0.2.0.
 */

/** A tool the TaskAgent can call. Same shape as a webagent action so
 *  hosts can reuse definitions across both agents. */
type TaskTool = ActionDefinition;
interface TaskAgentConfig {
    /** LLM provider or router. Must support tool-calling. */
    llm: LLMSource;
    /**
     * System prompt the LLM sees on every turn. Should describe the
     * agent's job (Q&A, customer service, knowledge lookup) and the
     * tools available. Tools are also appended programmatically — your
     * prompt doesn't need to enumerate them.
     */
    systemPrompt: string;
    /**
     * Tools the LLM can call. Empty array is fine (pure Q&A bot). Each
     * tool's `handler` receives the parsed arguments and returns the
     * result the LLM sees in the next turn.
     */
    tools?: TaskTool[];
    /**
     * Inject a shared `AgentSession` so this TaskAgent's history is
     * visible to other TaskAgents (or — in v0.3 — to a WebAgent
     * sharing the same session). Defaults to a fresh session per
     * agent.
     */
    session?: AgentSession;
    /**
     * Cap on the tool-call loop within a single `ask()`. Default 4.
     * Hosts with chained lookups (search → fetch → verify → answer)
     * may bump to 6. The cap is a safety net — most asks resolve in 1-2
     * rounds.
     */
    maxToolRounds?: number;
    /**
     * Narrate progress to the subtitle bar between tool calls
     * ("Looking up customer record…"). Requires `attachTo(dddk)`.
     * Default `false`.
     */
    enableSubtitle?: boolean;
    /** Locale for built-in narration strings. Default `'en'`. */
    locale?: string;
    /** Per-turn LLM call timeout. Default 30s. */
    llmTimeoutMs?: number;
}
interface TaskRunOptions {
    /** Override the configured maxToolRounds for this single call. */
    maxToolRounds?: number;
    /** Abort signal — the loop bails ASAP when triggered. */
    signal?: AbortSignal;
}
/**
 * One emit from `streamAsk` — incremental text delta, optional
 * tool-call markers, and a `done` flag on the terminal chunk.
 * v0.2.0.
 */
interface TaskAgentStreamChunk {
    /** Newly added text since the previous chunk. Empty between
     *  rounds (when a tool call is mid-execution). */
    delta: string;
    /** Snapshot of accumulated assistant text so far. */
    text: string;
    /** True only on the terminal chunk. After this the iterator
     *  ends; hosts driving a typewriter UI flush their buffer here. */
    done: boolean;
    /** Emitted right before a tool handler is invoked. `text` won't
     *  grow until the tool returns and the next LLM round produces
     *  more text. Hosts use this to surface "looking up…" indicators. */
    toolCallStart?: {
        name: string;
    };
    /** Emitted after a tool handler resolves. `ok` reflects whether
     *  the handler returned an `{ ok: true }`-shape result OR threw. */
    toolCallEnd?: {
        name: string;
        ok: boolean;
    };
}
/** Minimum the TaskAgent needs from a DotDotDuck handle. Avoids a
 *  circular import on the orchestrator type. */
interface TaskAgentDddkHandle {
    subtitle?: {
        show(opts: {
            text: string;
            type: 'agent' | 'info' | 'narration' | 'system';
            autoHide?: number;
        }): void;
        finalizeStreamed?(opts: {
            autoHide: number;
        }): void;
    };
}

/**
 * TaskAgent — conversation + host-defined tool calling.
 *
 * The third agent kind, alongside WebAgent (DOM-grounded page
 * operation) and InlineAgent (in-place text edits). TaskAgent has
 * no DOM dependency, no CoT envelope, no Space-gating — it's a
 * straight chat + tool-call loop. Plumbing for things hosts
 * actually build: customer-service Q&A, knowledge lookup,
 * back-end-call agents.
 *
 *   const taskAgent = new TaskAgent({
 *     llm: nano,
 *     systemPrompt: 'Answer Acme Co. support questions.',
 *     tools: [{
 *       name: 'lookup_order',
 *       description: 'Order status by id.',
 *       parameters: { type: 'object', properties: { id: { type: 'string' } } },
 *       handler: async ({ id }) => fetch(`/api/orders/${id}`).then((r) => r.json()),
 *     }],
 *   });
 *   taskAgent.attachTo(dddk);
 *   const reply = await taskAgent.ask('Where is order #12345?');
 *
 * Session sharing: pass `session` to share conversation history with
 * another TaskAgent. Cross-type sharing with WebAgent works at the
 * Session.turns[] level but the re-serialisation cost is non-trivial
 * — it's tracked as a v0.3 item.
 */

declare class TaskAgent {
    private cfg;
    private tools;
    private session;
    /** Whether session was injected — if true, we don't auto-replace. */
    private sessionInjected;
    private dddk;
    constructor(config: TaskAgentConfig);
    /** Inject a DotDotDuck-like handle so subtitle narration works
     *  when `enableSubtitle` is on. Same shape WebAgent / InlineAgent
     *  use; the import-light type is on purpose to avoid circular deps. */
    attachTo(dddk: TaskAgentDddkHandle): void;
    /** Read-only view of the current session — useful for inspection +
     *  for wiring the session into a sibling TaskAgent. */
    getSession(): AgentSession;
    /**
     * Swap the session out. Useful when host wants to reset
     * conversation history mid-flight, or hand the agent a freshly
     * registry-issued session. Returns the previous session in case
     * the host wants to archive it.
     */
    setSession(session: AgentSession): AgentSession;
    /** Toggle whether to narrate progress in the subtitle bar. */
    setEnableSubtitle(on: boolean): void;
    /** Register a new tool the LLM can call. Returns a handle whose
     *  `remove()` unregisters it. Mid-loop registrations land in the
     *  next LLM call within the same ask(); in-flight LLM calls keep
     *  the snapshot they were made with. */
    registerTool(tool: TaskTool): {
        remove(): void;
    };
    /** Unregister a tool by name. Returns true when one was removed. */
    unregisterTool(name: string): boolean;
    /**
     * Ask the agent — single-shot conversational turn. Appends the
     * task as a user turn to the session, runs the tool-call loop
     * until the LLM produces text (or the round cap fires), appends
     * the assistant's reply, returns the text.
     *
     * If the loop hits `maxToolRounds` without a text-only reply, the
     * partial content from the last LLM call is returned (may be
     * empty). Hosts who want to differentiate use the streaming
     * variant — TBD in a follow-up.
     */
    ask(task: string, opts?: TaskRunOptions): Promise<string>;
    /**
     * Streaming variant of `ask`. Yields `TaskAgentStreamChunk`s as
     * the LLM types. Tool-call rounds emit empty `delta` chunks with
     * `toolCallStart` / `toolCallEnd` markers so the host can drive
     * a typewriter UI + "looking up…" indicator with a single loop.
     *
     * Falls back to non-streaming `complete` when the provider doesn't
     * implement `streamComplete` — the final reply lands in one chunk
     * instead of incrementally. Callers get the same iterator shape
     * either way.
     */
    streamAsk(task: string, opts?: TaskRunOptions): AsyncIterable<TaskAgentStreamChunk>;
}

/**
 * Default `url` context provider.
 *
 * Emits the current path + query + hash, one line. The runtime
 * splices this into the per-turn prompt's location context.
 *
 * Hosts override via `webagent.registerContextProvider('url', fn)` —
 * useful when a SPA represents routes outside `location.pathname`
 * (e.g. fragment-only routing, query-encoded view state).
 */

declare const defaultUrlProvider: ContextProvider;

/**
 * Default `page_summary` context provider.
 *
 * Emits `<title>` + `<meta name="description">` content, one line
 * each. The runtime uses this so the LLM knows what the page is
 * "for" without scanning the whole DOM.
 *
 * Hosts override when the page's real summary lives in app state
 * (e.g. a single-page editor where `<title>` is generic and the
 * actual document title is in a React store).
 */

declare const defaultPageSummaryProvider: ContextProvider;

/**
 * Default `dom` context provider.
 *
 * Wraps the SDK's `readDOM` — same logic the runtime calls inline
 * today. Hosts who want different DOM serialization (filtered scope,
 * smaller token budget, custom indexing rules) override via
 * `webagent.registerContextProvider('dom', fn)`.
 *
 * Caveat: the runtime's internal `currentIndexMap` (the map from
 * `[3]`-style indices back to live elements for selector resolution)
 * is owned by the runtime's direct `readDOM` call, NOT by this
 * provider. Currently the runtime continues to use its own
 * `readDOM` invocation for that path; the provider is consulted
 * only where the runtime is being migrated. A host that overrides
 * the dom provider AND wants the runtime to actually consult it
 * will need to wait for the upcoming runtime patch (tracked in
 * docs/v0.2.0-task-agent-and-multi-instance.md).
 *
 * For now the provider is useful for:
 *   - Inspecting what the runtime would land in the prompt
 *     (`agent.contextProviders.get('dom')?.(req)`).
 *   - Composing with other tools (e.g. you want to ship the DOM
 *     dump to an audit log alongside the agent prompt).
 */

declare const defaultDomProvider: ContextProvider;

/**
 * Default `screenshot` context provider.
 *
 * Returns the viewport as a data-URL PNG. Lazy-resolves
 * `captureScreenshots` from the SDK's screenshot module so this
 * file doesn't pull the html2canvas peer dep until a host actually
 * asks for a screenshot.
 *
 * Returns `null` when:
 *   - There's no `document` (SSR / Node).
 *   - `html2canvas` is missing (silent — matches the runtime's
 *     existing screenshot-config behavior).
 *
 * Hosts override when the page is canvas / WebGL based and the
 * default rasterizer can't capture it — e.g. they already have a
 * scene-graph snapshot and just want to hand it off as a data URL.
 */

declare const defaultScreenshotProvider: ContextProvider;

/**
 * Default `history` context provider.
 *
 * Pulls recent paths from `window.history` — best-effort only. The
 * History API doesn't expose the actual stack to JS, so this
 * provider returns the current entry plus whatever sessionStorage
 * trail the SDK may have stamped during earlier navigations.
 *
 * Hosts with a real router (React Router, Vue Router, SvelteKit)
 * override to surface the actual app-level route history, including
 * route NAMES (not just paths) — `webagent.registerContextProvider('history', fn)`.
 */

/**
 * Default trail tracker: hosts that don't push to the trail get an
 * empty list. The orchestrator's navigation handler can wire calls
 * to `recordNavigation(path)` to keep the trail filled.
 */
declare function recordNavigation(path: string): void;
declare const defaultHistoryProvider: ContextProvider;

/**
 * Default `selection` context provider.
 *
 * Returns the live `window.getSelection()` text (if any) so the
 * agent can ground its next action on what the user just
 * highlighted. The runtime independently captures Dwell-anchored
 * selections; this provider is the OS-level selection fallback.
 *
 * Hosts override when the editable layer is non-standard — e.g. a
 * canvas-based editor that maintains its own selection model.
 */

declare const defaultSelectionProvider: ContextProvider;

/**
 * Default context providers for the six `ContextRole` slots WebAgent
 * recognises. SDK installs these into `webagent.contextProviders`
 * lazily in the constructor; hosts replace any single slot via
 * `webagent.registerContextProvider(role, fn)` — the registration
 * automatically restores the SDK default on `handle.remove()`.
 *
 * v0.2.0.
 */

/**
 * Lookup table — `getDefaultContextProvider('url')` returns the
 * SDK default for that slot. Use this when you want to compose with
 * the default (e.g. wrap it with extra logging) rather than replace
 * it outright.
 */
declare const DEFAULT_CONTEXT_PROVIDERS: Readonly<Record<ContextRole, ContextProvider>>;
declare function getDefaultContextProvider(role: ContextRole): ContextProvider;

/**
 * AgentCursor — visible big cursor that shows what the agent is about to do.
 *
 * When the agent is about to click / type / scroll, a large floating cursor
 * smoothly travels to the target element and pauses for `preClickPauseMs`
 * before the action fires. The user sees what's about to happen in time to
 * cancel.
 *
 * This is purely a visualization layer — it does not drive actions. It
 * subscribes to the `before_action` event webagent emits before every
 * action handler runs.
 *
 * Usage:
 *   const cursor = new AgentCursor({ preClickPauseMs: 250 });
 *   cursor.attachTo(dddk);
 *
 * To disable mid-run:
 *   cursor.setEnabled(false);
 */

interface AgentCursorConfig {
    /** Pause (ms) between cursor arriving on target and action firing. Default 250. */
    preClickPauseMs?: number;
    /** Cursor size in px. Default 32. */
    size?: number;
    /** Tint of the cursor stroke. Default uses CSS var or accent fallback. */
    color?: string;
    /** Travel duration (ms) between targets. Default 350. */
    travelMs?: number;
    /** Disabled by default? Default false (enabled). */
    enabled?: boolean;
}
declare class AgentCursor {
    private cfg;
    private cursorEl;
    private cleanups;
    private enabled;
    /** Resolves the pause promise — webagent's action handler awaits this gate. */
    private pendingPause;
    constructor(config?: AgentCursorConfig);
    attachTo(dddk: DotDotDuck): void;
    setEnabled(enabled: boolean): void;
    destroy(): void;
    private mount;
    private moveTo;
    private hide;
    private flashTarget;
    private wait;
}

/**
 * Sitemap traversal + LLM-friendly serialization helpers.
 */

/**
 * Render the sitemap as an indented outline an LLM can read efficiently.
 * Marks auth-gated pages, lists actions, shows dynamic segments as ":param".
 *
 * Example output:
 *   /                    Home — landing page
 *     /orders            Orders — list of orders
 *       actions: view, export, filter
 *       /:id             Order detail [auth]
 *         actions: refund, ship, cancel
 *       /new             New order [auth]
 *     /billing           Billing [auth]
 */
declare function serializeSitemap(root: SitemapNode, options?: {
    rootPath?: string;
}): string;
/**
 * Resolve a concrete URL path against the sitemap.
 * Supports `:param` segments matching any value.
 */
declare function resolvePath(root: SitemapNode, targetPath: string): SitemapResolution | null;
/**
 * Find nodes whose `title`, `description`, or `keywords` fuzzy-match a query.
 * Returns sorted by path depth (shallower first).
 */
declare function searchSitemap(root: SitemapNode, query: string): SitemapResolution[];
/** List all auth-gated paths in the tree (so agent can warn/login first). */
declare function listAuthGatedPaths(root: SitemapNode): string[];
/**
 * Template — a starter SaaS sitemap structure. Host copies + customizes.
 * Covers most common shape: marketing root, auth gate, dashboard, settings,
 * a resource list+detail+new pattern, billing.
 */
declare const SAAS_SITEMAP_TEMPLATE: SitemapNode;

/**
 * Multilingual sitemap helper.
 *
 * Hosts that ship a multi-language UI (English + Chinese + Japanese, …)
 * usually want a user typing in any of those languages to find the same
 * page. The sitemap that powers the agent's navigation tool only carries
 * ONE `description` field per route, but it ALSO supports `aliases`.
 *
 * This helper takes a flat nav-target list plus an i18n dict, and
 * produces `SitemapEntry[]` where each entry's `description` is in the
 * host's primary locale and `aliases` carries every OTHER locale's label
 * for the same route. Result: the agent + palette match on any language
 * the host has translated for.
 *
 * Usage:
 *
 *   import { buildSitemap } from '@perhapxin/dddk/agent';
 *
 *   const NAV = [
 *     { path: '/',     i18nKey: 'nav.home',  aliases: ['landing'] },
 *     { path: '/docs', i18nKey: 'nav.docs' },
 *   ];
 *
 *   const sitemap = buildSitemap(NAV, {
 *     primaryLocale: 'zh-TW',
 *     allLocales: ['en', 'zh-TW', 'ja'],
 *     i18n: {
 *       en:      { 'nav.home': 'Home',     'nav.docs': 'Documentation' },
 *       'zh-TW': { 'nav.home': '首頁',     'nav.docs': '文件' },
 *       ja:      { 'nav.home': 'ホーム',   'nav.docs': 'ドキュメント' },
 *     },
 *   });
 *   //  [
 *   //    { path: '/',     description: '首頁',  aliases: ['Home', 'ホーム', 'landing'] },
 *   //    { path: '/docs', description: '文件',  aliases: ['Documentation', 'ドキュメント'] },
 *   //  ]
 *
 * Re-call on locale change to reshuffle which locale becomes the
 * primary description — `WebAgent` reads `sitemap` once per turn, so
 * the new sitemap takes effect on the next agent run.
 */

interface NavTarget {
    /** URL path or route id (forwarded to `SitemapEntry.path` verbatim). */
    path: string;
    /**
     * Lookup key into each locale dict. Resolves to the route's short
     * label in each locale (the same string the sidebar / palette show).
     */
    i18nKey: string;
    /**
     * Optional lookup key for the LLM-facing description — a longer
     * sentence that tells the agent what the page actually contains.
     * Without this, the agent only sees the nav label (e.g. "Commercial")
     * and can confuse it with same-named elements on other pages.
     *
     * Defaults to `${i18nKey}.desc` — hosts can just add that key to
     * their dict to opt in.
     */
    descI18nKey?: string;
    /** Extra aliases — domain synonyms, abbreviations, slang. Merged into
     *  the final `aliases` list regardless of locale. */
    aliases?: string[];
}
interface BuildSitemapOpts {
    /**
     * Locale whose label becomes `SitemapEntry.description`. Pick the
     * locale you expect the user's first message to be in (usually `dddk`'s
     * current `locale` config). Other locales' labels go into `aliases`.
     */
    primaryLocale: string;
    /** Every locale to materialise — including `primaryLocale`. */
    allLocales: string[];
    /**
     * Locale-keyed i18n dict. Each inner dict maps `i18nKey` → translated
     * label. Missing translations are skipped (the alias just doesn't get
     * added for that locale) — no warning.
     */
    i18n: Record<string, Record<string, string>>;
}
declare function buildSitemap(targets: NavTarget[], opts: BuildSitemapOpts): SitemapEntry[];

/**
 * Runtime sitemap learning — extend a static sitemap with pages the agent
 * (or user) actually visits.
 *
 * Why: static sitemap covers known routes. But real apps have routes the
 * author forgot, or dynamic /:id pages with many instances. Learner observes
 * navigation events + DOM read summaries and augments the tree incrementally.
 *
 * Storage is host-supplied (any sync K/V — typically wrap dddk Cache).
 *
 * NOT enabled by default — host opts in:
 *   const learner = new SitemapLearner({ base: SAAS_SITEMAP_TEMPLATE, storage });
 *   learner.observePath(location.pathname, { title: document.title, ... });
 *   const augmented = learner.materialize();
 *   new WebAgent({ sitemap: augmented, ... });
 */

interface SitemapLearnerStorage {
    get(key: string): string | null;
    set(key: string, value: string): void;
}
interface SitemapLearnerOptions {
    /** Base static sitemap. Learned data merges on top. */
    base: SitemapNode;
    /** Persistent storage (use dddk Cache or any K/V). */
    storage: SitemapLearnerStorage;
    /** Storage key. Default 'webagent.sitemap.learned'. */
    storageKey?: string;
    /** Cap on learned children per parent — prevents unbounded tree growth. Default 50. */
    maxLearnedPerParent?: number;
    /** Treat segments matching this as dynamic (collapse to :param). Default UUIDs / numeric ids. */
    isDynamicSegment?: (segment: string) => boolean;
}
interface LearnedNode {
    title?: string;
    description?: string;
    actions?: string[];
    visitCount: number;
    lastVisited: number;
}
type LearnedTree = Record<string, LearnedNode>;
declare class SitemapLearner {
    private opts;
    private learned;
    constructor(opts: SitemapLearnerOptions);
    /**
     * Record a page visit. Path is normalized (dynamic segments → :param).
     * Optional `info` gets merged into the learned node (title / actions etc.).
     */
    observePath(path: string, info?: {
        title?: string;
        description?: string;
        actions?: string[];
    }): void;
    /**
     * Produce an augmented sitemap merging base + learned data.
     * Learned nodes that already exist in base just merge metadata.
     * Learned nodes that DON'T exist in base get added as new children.
     */
    materialize(): SitemapNode;
    /** Drop all learned data — keep static base. */
    reset(): void;
    /** Read raw learned tree (for inspection / export). */
    inspect(): LearnedTree;
    private normalizePath;
    private mergePath;
    private read;
    private write;
}

/**
 * Todos artifact — in-memory CRUD for `TodoItem`s. Owned by a `Plan`
 * instance; the webagent reads the list to drive the loop and mutates
 * via the per-turn envelope's `todo_adjust` field (not by calling these
 * methods directly — runtime translates envelope ops to these calls).
 *
 * Mutations bump `version` and call the optional `onChange` hook so
 * persistence + UI subscribers can react. ids are short stable strings
 * (`t1`, `t2`, ...) — predictable so model output can reference them.
 */

interface TodosArtifactOptions {
    /** Optional change hook. Fires after every mutation with the new list. */
    onChange?: (items: TodoItem[]) => void;
    /** Seed items — used when restoring from a storage adapter. */
    initial?: TodoItem[];
    /** ID counter seed — used when restoring from a storage adapter. */
    initialIdCounter?: number;
}
declare class TodosArtifact {
    private items;
    private idCounter;
    private readonly onChange?;
    constructor(opts?: TodosArtifactOptions);
    /** Returns a defensive copy so mutations don't leak. */
    list(): TodoItem[];
    get(id: string): TodoItem | null;
    /** Create one item, returning the assigned id. */
    create(item: Omit<TodoItem, 'id'>): TodoItem;
    /** Bulk-create — used by `Plan.makeTodos()` after a planning call. */
    createMany(items: Array<Omit<TodoItem, 'id'>>): TodoItem[];
    /** Partial update — id-preserving. Returns the new item or null if id
     *  not found. The webagent uses this for `todo_adjust.replace`. */
    edit(id: string, patch: Partial<Omit<TodoItem, 'id'>>): TodoItem | null;
    /** Drop one item by id. Returns true if removed, false if not found. */
    delete(id: string): boolean;
    /** Replace the entire list — used when a fresh `Plan.makeTodos()` is
     *  triggered mid-session and the host wants a hard reset. */
    reset(items?: TodoItem[]): void;
    /** For storage adapter — id counter must survive reload so future
     *  `create()` calls don't collide with pre-existing ids. */
    serialize(): {
        items: TodoItem[];
        idCounter: number;
    };
    private notify;
}

/**
 * Markdown artifact — in-memory CRUD for `MarkdownDoc`s. Not used by the
 * webagent loop; exposed so hosts can build LLM-mediated authoring
 * surfaces (meeting notes, drafts, KB articles) on top of the same
 * Plan instance / storage adapter.
 *
 * Two edit paths:
 *   - `edit(id, content)` — direct overwrite (host-driven, no LLM)
 *   - `editWithInstruction(id, instruction)` — LLM-mediated rewrite; uses
 *     the Plan instance's LLM. Returns the new doc.
 *
 * `id` scheme matches `TodosArtifact` — short stable `m1`, `m2`, ...
 */

interface MarkdownArtifactOptions {
    /** LLM provider used for `editWithInstruction`. Optional — without it
     *  the LLM-mediated edit method throws. Direct `edit()` always works. */
    llm?: LLMProvider;
    /** Optional change hook. Fires after every mutation with the new list. */
    onChange?: (docs: MarkdownDoc[]) => void;
    /** Seed docs — used when restoring from a storage adapter. */
    initial?: MarkdownDoc[];
    initialIdCounter?: number;
}
declare class MarkdownArtifact {
    private docs;
    private idCounter;
    private readonly llm?;
    private readonly onChange?;
    constructor(opts?: MarkdownArtifactOptions);
    list(): MarkdownDoc[];
    read(id: string): MarkdownDoc | null;
    create(input: {
        title: string;
        content: string;
    }): MarkdownDoc;
    /** Direct overwrite — host knows what content to write. */
    edit(id: string, patch: Partial<{
        title: string;
        content: string;
    }>): MarkdownDoc | null;
    /** LLM-mediated rewrite — pass an instruction, the model returns new
     *  content. Throws if no LLM was configured. */
    editWithInstruction(id: string, instruction: string): Promise<MarkdownDoc | null>;
    delete(id: string): boolean;
    serialize(): {
        docs: MarkdownDoc[];
        idCounter: number;
    };
    private notify;
}

/**
 * Plan — structured-artifact module. Owns two in-memory artifacts:
 *
 *   - `todos`     — `TodoItem[]` consumed by the webagent loop as its
 *                   master plan; mutated mid-loop via per-turn envelope
 *                   ops (the runtime translates envelope `todo_adjust`
 *                   to `todos.delete` / `todos.edit` here).
 *   - `markdown`  — `MarkdownDoc[]` for host-driven authoring surfaces
 *                   (meeting notes, drafts). Not used by the webagent.
 *
 * One LLM-mediated entry point lives here directly: `makeTodos(input)` —
 * a single planning call that produces a `TaskPlan` and seeds `todos`.
 * Hosts wire this into `webagent.planner` so the webagent runs a planning
 * pass before entering the turn loop.
 *
 * Two attach points:
 *   - `attachTo(dddk)` — exposes `dddk.plan` so anywhere in the host
 *     can read the artifacts or call CRUD without holding the instance
 *     reference. Same pattern as ImmersiveTranslate / Dwell.
 *   - `webagent.planner: (input) => plan.makeTodos(input)` — callback
 *     pattern, so the webagent has no hard dep on the Plan class.
 *
 * Storage: in-memory by default. Pass `storage` (an object with
 * `load()` / `save()`) to persist across reloads — same shape as
 * ImmersiveTranslate's cache option.
 */

interface PlanConfig {
    /** LLM source for the planning call AND markdown LLM edits. Single
     *  provider OR a router — when a router, the `plan` role is used and
     *  falls back to `webagent` if not registered. */
    llm: LLMSource;
    /** Extra strategic context appended to the SDK base planning prompt —
     *  sitemap mental model, tour playbook, route-routing logic. Same idea
     *  as `WebAgentConfig.appendSystemPrompt` but for the planning layer. */
    appendSystemPrompt?: string;
    /** Hard-replace the SDK planning prompt entirely. Rare — most hosts
     *  just use `appendSystemPrompt`. */
    systemPrompt?: string;
    /** Display name shown to the user / used in the planner self-intro. */
    agentName?: string;
    /** Optional storage adapter for cross-reload persistence. */
    storage?: PlanStorageAdapter;
}
declare class Plan {
    readonly todos: TodosArtifact;
    readonly markdown: MarkdownArtifact;
    private readonly config;
    private readonly storage?;
    private hydrated;
    constructor(config: PlanConfig);
    /**
     * Wire to the orchestrator so callers can do `dddk.plan.todos.list()`
     * without holding the Plan reference. Idempotent — re-attaching
     * replaces the previous binding.
     */
    attachTo(dddk: DotDotDuck): void;
    /**
     * One planning call → produces a TaskPlan and seeds `todos`.
     * Wire this into `webagent.planner` so the webagent runs a planning
     * pass before the turn loop.
     */
    makeTodos(input: PlanInput & {
        /**
         * v0.2.0 streaming hook: invoked synchronously for each new character
         * of the `task_summary` field AS the LLM types it. Lets the host
         * stream the announcement into a subtitle bar instead of getting one
         * monolithic post-parse blast. Optional — when omitted, the planning
         * call still streams under the hood (so the LLM proxy doesn't buffer
         * via Cloudflare AI-Gateway cache) but the host sees the same final
         * `TaskPlan` it always did.
         */
        onSummaryDelta?: (delta: string) => void;
    }): Promise<TaskPlan>;
    /** Snapshot current state — used by storage adapter + host inspection. */
    snapshot(): PlanSnapshot;
    private hydrate;
    private persist;
}

export { type ActionContext, type ActionDefinition, type ActionFailureReason, type ActionResult, AgentCursor, type AgentCursorConfig, type AgentEvent, type AgentFinalTurn, type AgentSession, type AgentStatus, type AgentStepTurn, type AgentTurn, type BrandPrompt, type BuildSitemapOpts, type ContextProvider, type ContextProviderHandle, type ContextRequest, type ContextRole, type CoreFieldType, CoreMemory, type CoreMemoryConfig, type CoreMemorySchema, DEFAULT_CONTEXT_PROVIDERS, DEFAULT_DESTRUCTIVE_PATTERNS, type DomReadOptions, type Drawer, DrawerMemory, type DrawerMemoryOpts, type DrawerSearchOpts, type EnvelopeStreamEvent, type EpisodicEntry, EpisodicMemory, type EpisodicMemoryConfig, type FormWidgetAdapter, type FormWidgetFillContext, type InlineAction, InlineAgent, type InlineAgentConfig, type InlineScopeConfig, MarkdownArtifact, type MarkdownDoc, Memory, type MemoryConfig, type MemoryPrivacyConfig, type MemoryProvider, type NavTarget, type OverlayItem, type OverlayType, type PiecePlacement, Plan, type PlanConfig, type PlanInput, type PlanSnapshot, type PlanStorageAdapter, type PromptContext, type RecallResult, type RememberOpts, type RunOptions, SAAS_SITEMAP_TEMPLATE, type ScopeHandle, type ScopeResolver, type ScreenshotConfig, type ScreenshotMode, type SelectionContext, SemanticMemory, type SemanticMemoryConfig, type SemanticMemoryEntry, type SitemapConfig, type SitemapEntry, SitemapLearner, type SitemapLearnerOptions, type SitemapLearnerStorage, type SitemapNode, type SitemapResolution, StreamingEnvelopeParser, type SystemPromptOverride, TaskAgent, type TaskAgentConfig, type TaskPlan, type TaskRunOptions, type TaskTool, type TodoItem, TodosArtifact, type ToolHandle, UnifiedMemory, type UnifiedMemoryConfig, type UserTurn, WebAgent, type WebAgentConfig, border, buildSitemap, builtinActions, captureScreenshots, clearOverlays, coreActions, createDrawerMemory, createUnifiedMemory, defaultDomProvider, defaultHistoryProvider, defaultPageSummaryProvider, defaultScreenshotProvider, defaultSelectionProvider, defaultUrlProvider, escalateToHuman, extraActions, findFormWidget, flowActions, formActions, getDefaultContextProvider, highlight, inject, listAuthGatedPaths, listFormWidgets, listOverlays, readDOM, recordNavigation, registerFormWidget, removeOverlay, resolvePath, searchSitemap, serializeSitemap, spotlight, trackIntent, unregisterFormWidget, validateForm, waitUntil, workflowActions };