@anuma/sdk 1.0.0 → 1.1.1

package/dist/tools/index.d.ts

@@ -1,24 +1,80 @@
+type LlmapiChatCompletionTool = {
+    [key: string]: unknown;
+};
+
+type ToolExecutionErrorType = "parse" | "timeout" | "execution";
+type ToolExecutionResult = {
+    result?: unknown;
+    error?: string;
+    /** Distinguishes parse errors, timeouts, and execution failures. */
+    errorType?: ToolExecutionErrorType;
+};
+
 /**
- * Google Calendar tool definition for the chat system.
- * This tool allows the LLM to list events from the user's Google Calendar.
+ * Tool executor function type
  */
+type ToolExecutor = (args: Record<string, unknown>) => Promise<unknown> | unknown;
 /**
- * Tool configuration type that extends the SDK's tool type with executor support.
- * The SDK runtime supports these properties even though the base types don't include them.
- *
- * Note: Client tools use "arguments" internally. The SDK converts this to "parameters"
- * when sending to the API (see serverTools.ts mergeTools function).
+ * Tool configuration with optional executor
  */
-interface ToolConfig {
-    type: 'function';
-    function: {
-        name: string;
-        description: string;
-        arguments: Record<string, unknown>;
-    };
-    executor?: (args: Record<string, unknown>) => Promise<unknown> | unknown;
-    autoExecute?: boolean;
-}
+type ToolConfig = LlmapiChatCompletionTool & {
+    /**
+     * Function to execute when the tool is called.
+     * If provided, the tool will be executed automatically when the LLM calls it.
+     * If not provided, an onToolCall event will be emitted instead.
+     */
+    executor?: ToolExecutor;
+    /**
+     * Whether to skip sending the tool result back to the model as a continuation.
+     * When true, the tool is executed but its result is not fed back to the model.
+     * Useful for display-only tools (charts, weather cards) that render client-side
+     * and don't need a model follow-up.
+     */
+    skipContinuation?: boolean;
+    /**
+     * Whether to remove this tool from the tools list after it has been
+     * successfully executed. This prevents smaller models from calling
+     * the same tool repeatedly in continuation requests.
+     *
+     * Only applies when the tool has an executor. The tool is kept if
+     * execution fails, allowing the model to retry.
+     */
+    removeAfterExecution?: boolean;
+    /**
+     * Timeout in milliseconds for this tool's executor.
+     * Overrides the default 30-second timeout.
+     * Set to `Infinity` to disable the timeout (e.g. for interactive tools
+     * that wait for user input).
+     * @default 30000
+     */
+    executorTimeout?: number;
+    /**
+     * When PII redaction is active, de-anonymize this tool's call arguments
+     * (restore original values for any `[CATEGORY_n]` placeholders) BEFORE the
+     * executor runs, using the same redactor that redacted the request this turn.
+     * Opt in only for tools that act on data that stays on the device — e.g.
+     * `memory_vault_save`, which must persist the real value, not a placeholder.
+     * Leave off for tools that forward arguments off-device (connectors), so PII
+     * stays redacted on the wire.
+     * @default false
+     */
+    deAnonymizeArgs?: boolean;
+    /**
+     * Tool names that this tool depends on. When multiple tools are called in
+     * the same response, tools with `dependsOn` will wait for the named tools
+     * to finish executing before starting.
+     *
+     * Example: `display_slides` depends on `create_file` because it reads
+     * files from IndexedDB that `create_file` writes.
+     */
+    dependsOn?: string[];
+};
+
+/**
+ * Google Calendar tool definition for the chat system.
+ * This tool allows the LLM to list events from the user's Google Calendar.
+ */
+
 interface ListEventsArgs {
     timeMin?: string;
     timeMax?: string;
@@ -70,6 +126,377 @@ declare function createGoogleCalendarUpdateEventTool(getAccessToken: () => strin
  */
 declare function createChatTools(getAccessToken: () => string | null, requestCalendarAccess: () => Promise<string>): ToolConfig[];
 
+/**
+ * Generic factories for creating client-side UI interaction tools.
+ *
+ * These factories handle the boilerplate of wiring tool executors to the
+ * UIInteractionProvider lifecycle (ID generation, context injection,
+ * promise resolution). Apps provide the tool schema and any custom logic.
+ */
+
+/**
+ * Minimal context interface required by tool factories.
+ * Matches the methods provided by UIInteractionProvider.
+ */
+type UIInteractionContext = {
+    createInteraction: (id: string, type: string, data: unknown) => Promise<unknown>;
+    createDisplayInteraction: (id: string, displayType: string, data: unknown, result: unknown, toolVersion?: number, replacesInteractionId?: string) => void;
+};
+/**
+ * Options for context injection, following the same getter pattern
+ * as createGoogleCalendarTool and createDriveTools.
+ */
+type CreateUIToolsOptions = {
+    /** Returns the current UIInteractionContext (or null if unavailable) */
+    getContext: () => UIInteractionContext | null;
+    /** Returns the ID of the last message in the conversation (used for anchoring) */
+    getLastMessageId?: () => string | undefined;
+};
+/**
+ * Configuration for an interactive tool that waits for user input.
+ */
+type InteractiveToolConfig = {
+    /** Tool name as called by the LLM (e.g. "prompt_user_choice") */
+    name: string;
+    /** Tool description shown to the LLM */
+    description: string;
+    /** JSON Schema for tool parameters */
+    parameters: Record<string, unknown>;
+    /** Interaction type string used by the provider (e.g. "choice", "form") */
+    interactionType: string;
+    /** Optional validation of LLM-provided args. Return false to cancel. */
+    validate?: (args: Record<string, unknown>) => boolean;
+    /** Transform args before storing as interaction data */
+    mapArgs?: (args: Record<string, unknown>) => Record<string, unknown>;
+    /** Transform the user's result before returning to the LLM */
+    mapResult?: (result: Record<string, unknown>, args: Record<string, unknown>) => unknown;
+};
+/**
+ * Migration map for a display tool.
+ * Keys are "fromVersion->toVersion" strings (e.g. "1->2").
+ * Each function receives the stored result at fromVersion and returns the
+ * result upgraded to toVersion.
+ *
+ * @example
+ * ```typescript
+ * migrations: {
+ *   "1->2": (old) => ({ ...old, newField: old.legacyField ?? defaultValue }),
+ * }
+ * ```
+ */
+type DisplayToolMigrations = {
+    [key: `${number}->${number}`]: (data: unknown) => unknown;
+};
+/**
+ * Configuration for a display-only tool that renders data without blocking.
+ */
+type DisplayToolConfig<TArgs = Record<string, unknown>, TResult = unknown> = {
+    /** Tool name as called by the LLM (e.g. "display_weather") */
+    name: string;
+    /** Tool description shown to the LLM */
+    description: string;
+    /** JSON Schema for tool parameters */
+    parameters: Record<string, unknown>;
+    /** Display type string used to dispatch rendering (e.g. "weather") */
+    displayType: string;
+    /** Execute function that fetches/computes the display data */
+    execute: (args: TArgs) => Promise<TResult> | TResult;
+    /**
+     * Schema version for the result format. Increment when the result shape
+     * changes in a backward-incompatible way. Default: 1.
+     */
+    version?: number;
+    /**
+     * Migration functions keyed by "fromVersion->toVersion".
+     * Used to upgrade stored results to the current version on restore.
+     */
+    migrations?: DisplayToolMigrations;
+    /**
+     * Optional callback that returns the interaction ID this display should replace.
+     * When set, only the specified interaction is removed instead of all interactions
+     * of the same displayType. Useful for updating a specific app instance.
+     */
+    getReplacesInteractionId?: (args: TArgs) => string | undefined;
+};
+/**
+ * Migrate a stored display result from an older version to the current version.
+ *
+ * Runs the migration chain step-by-step: fromVersion → fromVersion+1 → … → toVersion.
+ * Steps with no registered migration function are skipped (result passes through unchanged).
+ * Returns the original result unchanged if fromVersion >= toVersion.
+ *
+ * @example
+ * ```typescript
+ * const migrated = migrateDisplayResult(storedResult, 1, 3, {
+ *   "1->2": (v1) => ({ ...v1, added: v1.old ?? 0 }),
+ *   "2->3": (v2) => ({ ...v2, renamed: v2.added }),
+ * });
+ * ```
+ */
+declare function migrateDisplayResult(result: unknown, fromVersion: number, toVersion: number, migrations: DisplayToolMigrations): unknown;
+/**
+ * Create an interactive tool that waits for user input.
+ *
+ * When the LLM calls this tool, it creates a pending interaction in
+ * the UIInteractionProvider and returns a Promise that resolves when
+ * the user responds via the UI.
+ *
+ * @example
+ * ```typescript
+ * const choiceTool = createInteractiveTool(
+ *   { getContext: () => uiInteraction, getLastMessageId: () => lastMsgId },
+ *   {
+ *     name: "prompt_user_choice",
+ *     description: "Present choices to the user",
+ *     parameters: { type: "object", properties: { ... } },
+ *     interactionType: "choice",
+ *     validate: (args) => args.title && args.options?.length >= 2,
+ *   }
+ * );
+ * ```
+ */
+declare function createInteractiveTool(options: CreateUIToolsOptions, config: InteractiveToolConfig): ToolConfig;
+/**
+ * Create a display-only tool that renders data without blocking.
+ *
+ * When the LLM calls this tool, it executes the provided function,
+ * stores the result as a resolved display interaction for rendering,
+ * and immediately returns the data to the LLM.
+ *
+ * @example
+ * ```typescript
+ * const weatherTool = createDisplayTool(
+ *   { getContext: () => uiInteraction, getLastMessageId: () => lastMsgId },
+ *   {
+ *     name: "display_weather",
+ *     description: "Show weather for a location",
+ *     parameters: { type: "object", properties: { location: { type: "string" } } },
+ *     displayType: "weather",
+ *     execute: async (args) => fetchWeatherData(args.location),
+ *   }
+ * );
+ * ```
+ */
+declare function createDisplayTool<TArgs = Record<string, unknown>, TResult = unknown>(options: CreateUIToolsOptions, config: DisplayToolConfig<TArgs, TResult>): ToolConfig;
+
+/**
+ * Chart display tool factory.
+ *
+ * Creates a client-side tool that renders bar, line, area, and pie charts
+ * inline in the chat. The tool validates the LLM-provided data and passes
+ * it through for rendering by the ChartCard component.
+ */
+
+type ChartDataPoint = Record<string, string | number>;
+type DisplayChartResult = {
+    chartType: "bar" | "line" | "area" | "pie";
+    title?: string;
+    data: ChartDataPoint[];
+    dataKeys: string[];
+    xAxisKey?: string;
+    colors?: Record<string, string>;
+} | {
+    error: string;
+};
+/**
+ * Create a display_chart tool that renders charts inline in the chat.
+ *
+ * @example
+ * ```typescript
+ * import { createChartTool } from "@anuma/sdk/tools";
+ *
+ * const chartTool = createChartTool({
+ *   getContext: () => uiInteraction,
+ *   getLastMessageId: () => lastMsgId,
+ * });
+ * ```
+ */
+declare function createChartTool(options: CreateUIToolsOptions): ToolConfig;
+
+type DisplayPhoneCallOfferResult = {
+    recipientName: string;
+    phoneNumber: string;
+    objective: string;
+    suggestedQuestions?: string[];
+    contextSummary?: string;
+} | {
+    error: string;
+};
+declare function createPhoneCallOfferTool(options: CreateUIToolsOptions): ToolConfig;
+
+type DisplayConnectorResult = {
+    connectorId: string;
+    reason?: string;
+} | {
+    error: string;
+};
+declare function createConnectorOfferTool(options: CreateUIToolsOptions): ToolConfig;
+
+/**
+ * Choice interaction tool factory.
+ *
+ * Creates a client-side tool that presents an interactive choice picker
+ * inline in the chat. The tool blocks until the user selects an option.
+ */
+
+type ChoiceOption = {
+    /** Unique identifier for this option */
+    value: string;
+    /** Display text for this option */
+    label: string;
+    /** Optional description or additional info */
+    description?: string;
+};
+/**
+ * Create a prompt_user_choice tool that renders an interactive choice picker.
+ *
+ * When the LLM calls this tool, it presents a set of options to the user
+ * inline in the chat. Execution blocks until the user makes a selection,
+ * then the result is returned to the LLM.
+ *
+ * @example
+ * ```typescript
+ * import { createChoiceTool } from "@anuma/sdk/tools";
+ *
+ * const choiceTool = createChoiceTool({
+ *   getContext: () => uiInteraction,
+ *   getLastMessageId: () => lastMsgId,
+ * });
+ * ```
+ */
+declare function createChoiceTool(options: CreateUIToolsOptions): ToolConfig;
+
+/**
+ * Form interaction tool factory.
+ *
+ * Creates a client-side tool that renders an interactive form inline in
+ * the chat. The tool blocks until the user fills out and submits the form.
+ */
+
+type FormFieldType = "text" | "textarea" | "select" | "toggle" | "date" | "slider";
+type FormFieldOption = {
+    value: string;
+    label: string;
+};
+type FormField = {
+    /** Unique field identifier (used as key in result) */
+    name: string;
+    /** Display label for the field */
+    label: string;
+    /** Field type */
+    type: FormFieldType;
+    /** Optional help text shown below the label */
+    description?: string;
+    /** Placeholder text for text/textarea/select fields */
+    placeholder?: string;
+    /** Options for select fields */
+    options?: FormFieldOption[];
+    /** Default value */
+    defaultValue?: string | boolean | number;
+    /** Minimum value for slider fields */
+    min?: number;
+    /** Maximum value for slider fields */
+    max?: number;
+    /** Step increment for slider fields */
+    step?: number;
+};
+/**
+ * Create a prompt_user_form tool that renders an interactive form.
+ *
+ * When the LLM calls this tool, it presents a form with various field types
+ * to the user inline in the chat. Execution blocks until the user submits,
+ * then all field values are returned to the LLM at once.
+ *
+ * @example
+ * ```typescript
+ * import { createFormTool } from "@anuma/sdk/tools";
+ *
+ * const formTool = createFormTool({
+ *   getContext: () => uiInteraction,
+ *   getLastMessageId: () => lastMsgId,
+ * });
+ * ```
+ */
+declare function createFormTool(options: CreateUIToolsOptions): ToolConfig;
+
+/**
+ * Weather display tool factory.
+ *
+ * Creates a client-side tool that fetches weather data from the Open-Meteo
+ * API and renders it as a visual card inline in the chat.
+ */
+
+type ForecastDay = {
+    date: string;
+    weatherCode: number;
+    temperatureMax: number;
+    temperatureMin: number;
+};
+type DisplayWeatherResult = {
+    location: string;
+    country?: string;
+    temperature: number;
+    apparentTemperature: number;
+    humidity: number;
+    windSpeed: number;
+    weatherCode: number;
+    isDay: boolean;
+    useFahrenheit: boolean;
+    forecast?: ForecastDay[];
+    _meta?: {
+        location: string;
+    };
+} | {
+    error: string;
+    _meta?: {
+        location: string;
+    };
+};
+interface CreateWeatherToolOptions {
+    /**
+     * Detect whether to fetch Fahrenheit/mph instead of Celsius/km/h.
+     * Defaults to checking `navigator.language` for US/LR/MM regions.
+     */
+    detectUseFahrenheit?: () => boolean;
+    /** Called when a fetch error occurs (after retry). */
+    onError?: (error: Error, ctx: {
+        location: string;
+    }) => void;
+    /** Timeout in milliseconds for fetch requests. Defaults to 10000. */
+    timeoutMs?: number;
+    /**
+     * Override the Open-Meteo geocoding API base URL.
+     * Defaults to `https://geocoding-api.open-meteo.com/v1`.
+     */
+    geocodingBaseUrl?: string;
+    /**
+     * Override the Open-Meteo forecast API base URL.
+     * Defaults to `https://api.open-meteo.com/v1`.
+     */
+    forecastBaseUrl?: string;
+}
+/**
+ * Create a display_weather tool that fetches and renders weather data.
+ *
+ * When the LLM calls this tool, it geocodes the location, fetches current
+ * weather and a 7-day forecast from Open-Meteo, and renders it as a card.
+ * The result is not sent back to the LLM (`skipContinuation: true`).
+ *
+ * Units are auto-detected from `navigator.language` (US/LR/MM → Fahrenheit
+ * + mph). Override with `weatherOptions.detectUseFahrenheit`.
+ *
+ * @example
+ * ```typescript
+ * import { createWeatherTool } from "@anuma/sdk/tools";
+ *
+ * const weatherTool = createWeatherTool(
+ *   { getContext: () => uiInteraction, getLastMessageId: () => lastMsgId },
+ *   { onError: (err, { location }) => logError("weather", err, { location }) }
+ * );
+ * ```
+ */
+declare function createWeatherTool(options: CreateUIToolsOptions, weatherOptions?: CreateWeatherToolOptions): ToolConfig;
+
 /**
  * Google Drive tool definition for the chat system.
  * This tool allows the LLM to search files in the user's Google Drive.
@@ -113,9 +540,2297 @@ interface GetFileContentArgs {
  * Creates the Google Drive get file content tool
  */
 declare function createGoogleDriveGetContentTool(getAccessToken: () => string | null, requestDriveAccess: () => Promise<string>): ToolConfig;
+interface CreateFileArgs {
+    name: string;
+    content: string;
+    mimeType?: string;
+}
+/**
+ * Creates the Google Drive create-file tool.
+ */
+declare function createGoogleDriveCreateFileTool(getAccessToken: () => string | null, requestDriveAccess: () => Promise<string>): ToolConfig;
+interface UpdateFileArgs {
+    fileId: string;
+    content: string;
+    mimeType?: string;
+}
+/**
+ * Creates the Google Drive update-file tool.
+ */
+declare function createGoogleDriveUpdateFileTool(getAccessToken: () => string | null, requestDriveAccess: () => Promise<string>): ToolConfig;
 /**
  * Creates all Google Drive tools with the provided token context.
  */
 declare function createDriveTools(getAccessToken: () => string | null, requestDriveAccess: () => Promise<string>): ToolConfig[];
 
-export { type CalendarEvent, type CreateEventArgs, type DriveFile, type GetFileContentArgs, type ListEventsArgs, type ListRecentFilesArgs, type SearchFilesArgs, type ToolConfig, type UpdateEventArgs, createChatTools, createDriveTools, createGoogleCalendarCreateEventTool, createGoogleCalendarTool, createGoogleCalendarUpdateEventTool, createGoogleDriveGetContentTool, createGoogleDriveListRecentTool, createGoogleDriveSearchTool };
+/**
+ * Notion MCP tool definitions for the chat system.
+ *
+ * These tools communicate with Notion's hosted MCP server using the
+ * Model Context Protocol (JSON-RPC 2.0). The MCP server handles all
+ * Notion API interactions - we just forward tool calls to it.
+ *
+ * MCP Server: https://mcp.notion.com/mcp (Streamable HTTP)
+ * Fallback: https://mcp.notion.com/sse (Server-Sent Events)
+ *
+ * @see https://developers.notion.com/guides/mcp/build-mcp-client
+ * @see https://modelcontextprotocol.io
+ */
+
+interface NotionSearchArgs {
+    query: string;
+    query_type?: "internal" | "user";
+    filters?: Record<string, unknown>;
+}
+interface NotionFetchArgs {
+    id: string;
+    include_transcript?: boolean;
+    include_discussions?: boolean;
+}
+interface NotionCreatePagesArgs {
+    pages: Array<{
+        properties: Record<string, unknown>;
+        content: string;
+    }>;
+    parent?: Record<string, unknown>;
+}
+interface NotionUpdatePageArgs {
+    data: {
+        page_id: string;
+        command: string;
+        properties?: Record<string, unknown>;
+        new_str?: string;
+        selection_with_ellipsis?: string;
+        allow_deleting_content?: boolean;
+    };
+}
+interface NotionMovePagesArgs {
+    page_or_database_ids: string[];
+    new_parent: Record<string, unknown>;
+}
+/**
+ * MCP Tool: notion-search
+ * Semantic search over Notion workspace and connected sources, or user search
+ */
+declare function createNotionSearchTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-fetch
+ * Retrieves details about a Notion entity (page or database) by URL or ID
+ */
+declare function createNotionFetchTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-create-pages
+ * Creates one or more Notion pages with properties and content
+ */
+declare function createNotionCreatePagesTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-update-page
+ * Update a page's properties or content using command-based operations
+ */
+declare function createNotionUpdatePageTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-move-pages
+ * Move one or more pages/databases to a new parent
+ */
+declare function createNotionMovePagesTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-duplicate-page
+ * Duplicate a Notion page (completes asynchronously)
+ */
+declare function createNotionDuplicatePageTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-create-database
+ * Create a new Notion database with a properties schema
+ */
+declare function createNotionCreateDatabaseTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-update-data-source
+ * Update a data source's properties, name, or other attributes
+ */
+declare function createNotionUpdateDataSourceTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-create-comment
+ * Add a comment to a page, specific content, or reply to a discussion
+ */
+declare function createNotionCreateCommentTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-get-comments
+ * Get comments and discussions from a Notion page
+ */
+declare function createNotionGetCommentsTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-get-users
+ * List users in the workspace, get a specific user, or get self
+ */
+declare function createNotionGetUsersTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * MCP Tool: notion-get-teams
+ * Retrieve teams (teamspaces) in the workspace
+ */
+declare function createNotionGetTeamsTool(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig;
+/**
+ * Create all Notion MCP tools
+ *
+ * Returns tools that communicate with Notion's hosted MCP server.
+ * The MCP server handles all Notion API interactions.
+ */
+declare function createNotionTools(getAccessToken: () => string | null, requestNotionAccess: () => Promise<string>): ToolConfig[];
+/**
+ * Get the MCP endpoints for direct access
+ */
+declare function getMCPEndpoints(): {
+    http: string;
+    sse: string;
+};
+/**
+ * Call any MCP tool directly (for advanced use cases)
+ */
+declare function callNotionMCPTool<T>(accessToken: string, toolName: string, args: Record<string, unknown>): Promise<T>;
+
+/**
+ * GitHub tools for the chat system.
+ *
+ * Two tools:
+ * 1. github_get_authenticated_user — discover the user's identity and orgs
+ * 2. github_api — make any authenticated GitHub REST API call
+ *
+ * This lets the LLM use its training knowledge of the GitHub API directly,
+ * instead of us defining individual tools for every endpoint.
+ */
+
+/**
+ * Create GitHub tools for the chat system.
+ *
+ * @param getAccessToken - Returns the current GitHub access token (or null)
+ * @param requestGitHubAccess - Triggers the OAuth flow and returns a token
+ */
+declare function createGitHubTools(getAccessToken: () => string | null, requestGitHubAccess: () => Promise<string>): ToolConfig[];
+
+/**
+ * Token-getter factory shared by every connector tool factory.
+ *
+ * Wraps a portal client's `mintConnectorToken(provider)` call in a
+ * per-instance access-token cache. The returned closure is the
+ * `getAccessToken: () => string | null` argument every tool factory takes.
+ *
+ * Cache rules (per-instance):
+ * - First call mints; subsequent calls return the cached token until
+ *   `(expiresAt - refreshBeforeMs) <= now`, then re-mints.
+ * - On mint failure (`MintResult.ok === false`), the cache is left untouched;
+ *   the failure is forwarded to `onNotConnected` (when applicable) or
+ *   surfaced as `null` so the tool factory can emit a connector error.
+ * - A thrown mint call (portal unreachable, all retries exhausted) is
+ *   swallowed and surfaced as `null` too — the closure's documented
+ *   contract is `() => Promise<string | null>`, and letting a network
+ *   error bubble would crash the tool executor instead of letting it
+ *   emit the canonical `__anuma_connector_error_v1` result.
+ *
+ * Two tool calls in the same request reuse the same `PortalClient` instance,
+ * and so share this cache — that's where the "2 calls = 1 mint" caching
+ * guarantee in the runtime spec comes from.
+ */
+/** Discriminated union returned by `mintConnectorToken`. */
+type ConnectorMintResult = {
+    ok: true;
+    accessToken: string;
+    expiresAt: number;
+} | {
+    ok: false;
+    error: ConnectorMintError;
+};
+/** Error variants from the mint endpoint, mirrored on `@anuma/agent-runtime`. */
+type ConnectorMintError = {
+    code: "connector_not_connected";
+    provider: string;
+    connectUrl: string;
+} | {
+    code: "scope_not_covered";
+    provider: string;
+    missingScopes: string[];
+    connectUrl: string;
+} | {
+    code: "insufficient_scope";
+    required: string;
+} | {
+    code: "upstream_unavailable";
+    retryAfterMs?: number;
+} | {
+    code: "unknown";
+    message: string;
+};
+/**
+ * Minimal portal-client surface this helper depends on.
+ *
+ * `@anuma/agent-runtime` exposes a richer `PortalClient` that satisfies this
+ * shape. Keeping the SDK-side dependency structural avoids pulling the
+ * runtime package into every SDK consumer.
+ */
+interface ConnectorTokenSource {
+    mintConnectorToken(provider: string): Promise<ConnectorMintResult>;
+}
+interface ConnectorTokenGetterOpts {
+    /** How early to refresh before expiry. @default 30_000 (30 s) */
+    refreshBeforeMs?: number;
+    /**
+     * Called when mint returns `connector_not_connected` or `scope_not_covered`.
+     * The default returns `null`, letting tool factories emit a structured
+     * connector error via `buildConnectorErrorResult`. Interactive surfaces
+     * (browser, mobile) can override to drive a connect UI and return a fresh
+     * token once the user finishes.
+     */
+    onNotConnected?: (err: ConnectorMintError) => Promise<string | null>;
+    /** Defaults to `Date.now`; injected for tests. */
+    now?: () => number;
+}
+/**
+ * Build a `() => Promise<string | null>` closure that mints + caches an
+ * upstream access token for the given logical provider.
+ *
+ * The closure is consumed verbatim by tool factories such as `createGmailTools`
+ * and `createDriveTools` — those factories expect a synchronous getter today,
+ * but Promise-returning getters are tolerated because tool executors are
+ * already async. (PR 7 in the plan shrinks the existing factories to call
+ * `await getToken()` internally.)
+ */
+declare function createConnectorTokenGetter(client: ConnectorTokenSource, provider: string, opts?: ConnectorTokenGetterOpts): () => Promise<string | null>;
+
+/**
+ * Canonical connector-error contract emitted by every connector tool factory.
+ *
+ * When the portal mint endpoint returns a 412 or 403, the tool factory does
+ * NOT throw — it returns the JSON string produced by `buildConnectorErrorResult`
+ * as the tool result. The post-loop parser in `@anuma/agent-runtime` walks the
+ * resulting tool-role messages and lifts any payload bearing the
+ * `__anuma_connector_error_v1` marker into a structured `ToolError[]` the
+ * caller can render alongside the LLM reply.
+ *
+ * The double-underscore + version suffix in the marker name keeps it
+ * collision-resistant against any tool that legitimately returns JSON
+ * containing the word "error".
+ */
+/** Recognized connector error codes. */
+type ConnectorErrorCode = "connector_not_connected" | "scope_not_covered" | "insufficient_scope" | "upstream_unavailable";
+/** Marker key that distinguishes a connector error from any other tool JSON. */
+declare const CONNECTOR_ERROR_MARKER: "__anuma_connector_error_v1";
+/**
+ * Optional extras emitted alongside the core fields. Kept loose so the
+ * helper signature stays small and tool factories can opt into the
+ * fields they have available.
+ */
+interface ConnectorErrorExtras {
+    /** For `scope_not_covered`: scopes still missing from the user's grant. */
+    missingScopes?: string[];
+    /** For `insufficient_scope`: the required scope identifier. */
+    required?: string;
+}
+/**
+ * Build the canonical connector-error JSON string. Every connector tool
+ * factory uses this helper so the marker convention is impossible to forget.
+ *
+ * Note: omitted optional fields are emitted as `undefined`, which
+ * `JSON.stringify` drops, leaving the key absent — matching the shape the
+ * post-loop parser expects.
+ *
+ * @param code       One of the recognized {@link ConnectorErrorCode} values.
+ * @param provider   Logical provider name (`"gmail"`, `"gdrive"`, etc.).
+ * @param connectUrl Optional connect URL surfaced to the user via the LLM reply.
+ * @param extras     Optional `missingScopes` / `required` fields lifted by the
+ *                   runtime parser into `ToolErrorInfo`.
+ */
+declare function buildConnectorErrorResult(code: ConnectorErrorCode, provider: string, connectUrl?: string, extras?: ConnectorErrorExtras): string;
+
+/**
+ * Gmail tool factory for the chat system.
+ *
+ * Mirrors the shape of {@link "./googleDrive".createDriveTools}: the caller
+ * supplies a token getter and an interactive `requestAccess` fallback,
+ * and the factory returns a record of `ToolConfig` entries the chat loop
+ * can run. The token getter is expected to be one returned by
+ * `createConnectorTokenGetter`, but any `() => Promise<string | null>`
+ * compatible function works.
+ *
+ * Tool catalogue (matches portal scope `connector:gmail:*`):
+ * - `gmail_search_messages` — list message IDs + snippets matching a query
+ * - `gmail_get_message`     — fetch headers + plaintext body for a single message
+ * - `gmail_create_draft`    — create a draft message in the user's mailbox (does not send)
+ * - `gmail_send_message`    — send a message via the user's mailbox
+ *
+ * Error contract: when the upstream Gmail API or the portal mint endpoint
+ * signals a connector-level failure (412 missing connector, 412 scope not
+ * covered, 401 token unusable), the tool returns the canonical
+ * `__anuma_connector_error_v1` JSON shape produced by
+ * `buildConnectorErrorResult`. The agent-runtime post-loop parser lifts
+ * these into `AgentResponse.toolErrors`. Tool executors never throw on
+ * these paths — the LLM is expected to surface the connect URL to the user.
+ */
+
+/** Async getter returned by `createConnectorTokenGetter`. */
+type GmailTokenGetter = () => Promise<string | null>;
+/**
+ * Fallback used when no token is currently available. Server agents pass an
+ * implementation that throws (no interactive OAuth is possible). Browser
+ * surfaces pass a function that drives the connect flow and resolves with a
+ * fresh token (or `null` if the user declined).
+ */
+type GmailRequestAccess = () => Promise<string | null>;
+interface GmailSearchArgs {
+    query: string;
+    maxResults?: number;
+}
+interface GmailGetMessageArgs {
+    messageId: string;
+    format?: "metadata" | "full";
+}
+interface GmailSendMessageArgs {
+    to: string;
+    subject: string;
+    body: string;
+    cc?: string;
+    bcc?: string;
+}
+interface GmailMessageSummary {
+    id: string;
+    threadId: string;
+    snippet?: string;
+}
+interface GmailMessageDetail {
+    id: string;
+    threadId: string;
+    from?: string;
+    to?: string;
+    subject?: string;
+    date?: string;
+    snippet?: string;
+    body?: string;
+}
+/**
+ * Pull the structured error out of a `ConnectorMintError`. Unused in v1 — the
+ * `onNotConnected` opt is the place to translate `ConnectorMintError`. Exported
+ * so future tool factories can share the helper without duplicating the
+ * code → error-string mapping.
+ *
+ * @param err      The mint error returned by the portal client.
+ * @param provider Logical provider name (`"gmail"`, `"gdrive"`, ...) used for
+ *                 error variants that don't carry their own provider field
+ *                 (`insufficient_scope`, `upstream_unavailable`, `unknown`).
+ *                 Required so non-Gmail tool factories don't emit
+ *                 `provider: "gmail"` by accident.
+ */
+declare function connectorMintErrorToToolResult(err: ConnectorMintError, provider: string): string;
+/**
+ * Build the Gmail tool set wired to the supplied token getter.
+ *
+ * The returned record keys (`gmail_search_messages`, `gmail_get_message`,
+ * `gmail_create_draft`, `gmail_send_message`) match the underlying tool names
+ * so callers can forward a subset by destructuring.
+ *
+ * @param getToken     Async getter — typically `createConnectorTokenGetter(portal, "gmail")`.
+ * @param requestAccess Fallback called when `getToken()` returns null.
+ *                      Server agents pass `async () => { throw ... }`; browser
+ *                      surfaces drive a connect flow and resolve with the
+ *                      fresh token (or `null` on user cancel).
+ */
+declare function createGmailTools(getToken: GmailTokenGetter, requestAccess: GmailRequestAccess): Record<string, ToolConfig>;
+
+/**
+ * X (Twitter) tool factory for the chat system.
+ *
+ * Unlike the other connector tools, the X tools never call api.x.com directly:
+ * api.x.com returns no CORS headers, so a browser can't fetch it. Instead the
+ * caller supplies an {@link XProxyCaller} that POSTs to the portal's
+ * `POST {portalBaseUrl}/api/v1/connectors/x/proxy` endpoint (authed with the
+ * user's Privy bearer, NOT an X token). The portal mints the X token
+ * server-side and returns the upstream status + JSON verbatim. The SDK stays
+ * transport-agnostic: it builds the same upstream paths + query objects it
+ * always has and hands them to the injected caller.
+ *
+ * Tool catalogue (matches portal scope `connector:x:*`):
+ * - `x_get_me`       -- fetch the authenticated user's profile
+ * - `x_get_my_posts` -- fetch the authenticated user's recent posts
+ *
+ * Error contract: when the proxy reports an auth failure (401, 403) the tool
+ * returns the canonical `__anuma_connector_error_v1` JSON shape produced by
+ * `buildConnectorErrorResult`. Tool executors never throw on these paths.
+ */
+
+/**
+ * Calls the portal X proxy with an upstream X API path and optional query, and
+ * resolves to the upstream status + parsed JSON. Consumers wire this to
+ * `POST {portalBaseUrl}/api/v1/connectors/x/proxy` with the user's Privy bearer
+ * and a JSON body `{ path, query }`; the portal mints the X token server-side.
+ */
+type XProxyCaller = (path: string, query?: Record<string, string | number>) => Promise<{
+    status: number;
+    json: unknown;
+}>;
+interface XGetMeArgs {
+    includePublicMetrics?: boolean;
+}
+interface XGetMyPostsArgs {
+    maxResults?: number;
+}
+/**
+ * Build the X tool set wired to the supplied proxy caller.
+ *
+ * The returned record keys (`x_get_me`, `x_get_my_posts`) match the underlying
+ * tool names so callers can forward a subset by destructuring.
+ *
+ * @param callProxy POSTs an upstream X path + query through the portal X proxy
+ *   (`/api/v1/connectors/x/proxy`) and resolves to `{ status, json }`. The X
+ *   token never reaches the browser -- the portal mints it server-side.
+ */
+declare function createXTools(callProxy: XProxyCaller): Record<string, ToolConfig>;
+
+/**
+ * Dropbox tool factory for the chat system.
+ *
+ * Mirrors the shape of {@link "./gmail".createGmailTools}: the caller supplies a
+ * token getter and an interactive `requestAccess` fallback, and the factory
+ * returns a record of `ToolConfig` entries the chat loop can run. The token
+ * getter is expected to be one returned by `createConnectorTokenGetter`, but any
+ * `() => Promise<string | null>` compatible function works.
+ *
+ * Dropbox API v2 sends CORS headers, so — unlike X or Slack — these tools call
+ * the API DIRECTLY with the minted token; no portal proxy caller is needed.
+ *
+ * Tool catalogue (all read-only, matches portal scope `connector:dropbox:read`):
+ * - `dropbox_list_folders`     — list entries under a folder path
+ * - `dropbox_get_file_content` — download a file's content as text
+ * - `dropbox_search`           — search files/folders by name/content
+ *
+ * Error contract: on a connector-level auth failure (401/403, or no usable
+ * token) the tool returns the canonical `__anuma_connector_error_v1` JSON shape
+ * produced by `buildConnectorErrorResult`. Tool executors never throw on these
+ * paths — the LLM is expected to surface the connect URL to the user.
+ */
+
+/** Async getter returned by `createConnectorTokenGetter`. */
+type DropboxTokenGetter = () => Promise<string | null>;
+/**
+ * Fallback used when no token is currently available. Server agents pass an
+ * implementation that throws (no interactive OAuth is possible). Browser
+ * surfaces pass a function that drives the connect flow and resolves with a
+ * fresh token (or `null` if the user declined).
+ */
+type DropboxRequestAccess = () => Promise<string | null>;
+/**
+ * Build the Dropbox tool set wired to the supplied token getter.
+ *
+ * The returned record keys (`dropbox_list_folders`, `dropbox_get_file_content`,
+ * `dropbox_search`) match the underlying tool names so callers can forward a
+ * subset by destructuring.
+ *
+ * @param getToken     Async getter — typically `createConnectorTokenGetter(portal, "dropbox")`.
+ * @param requestAccess Fallback called when `getToken()` returns null.
+ *                      Server agents pass `async () => { throw ... }`; browser
+ *                      surfaces drive a connect flow and resolve with the fresh
+ *                      token (or `null` on user cancel).
+ */
+declare function createDropboxTools(getToken: DropboxTokenGetter, requestAccess: DropboxRequestAccess): Record<string, ToolConfig>;
+
+/**
+ * Slack tool factory for the chat system.
+ *
+ * Like the X tools, the Slack tools never call slack.com directly: the Web API
+ * returns no CORS headers, so a browser can't fetch it. The caller supplies a
+ * {@link SlackProxyCaller} that GETs the portal's Slack proxy (authed with the
+ * user's Privy bearer, NOT a Slack token). The portal mints the Slack token
+ * server-side and returns the upstream status + JSON verbatim. The SDK stays
+ * transport-agnostic: it builds the same upstream method paths + query objects
+ * and hands them to the injected caller.
+ *
+ * Slack auth quirk: the Web API answers HTTP 200 even on auth failures, putting
+ * the real outcome in `{ ok: false, error: "invalid_auth" | ... }`. So we map
+ * the auth-shaped `error` codes (and the usual 401/403 statuses) to the
+ * canonical connector error, not just the HTTP status.
+ *
+ * Tool catalogue. The Slack Marketplace forbids the message-search scope, so
+ * there's no server-side message-search API to call: `slack_search_messages`
+ * scans recent history via `conversations.history` instead. Slack throttles
+ * conversations.history/.replies to ~1 req/min for distributed apps, so the read
+ * tools stay bounded — search fans out across only a handful of channels and
+ * reads only recent messages.
+ * - `slack_get_me`              -- the authenticated user's profile
+ * - `slack_list_channels`       -- channels in the workspace
+ * - `slack_search_messages`     -- text-search recent messages across channels + DMs
+ * - `slack_list_users`          -- workspace members
+ * - `slack_get_channel_history` -- recent messages in a channel (rate-limited)
+ * - `slack_get_thread_replies`  -- replies in a thread (rate-limited)
+ * - `slack_post_message`        -- post a message (WRITE)
+ *
+ * Error contract: on an auth failure the tool returns the canonical
+ * `__anuma_connector_error_v1` JSON shape from `buildConnectorErrorResult`.
+ * Tool executors never throw on these paths.
+ */
+
+/**
+ * Calls the portal Slack proxy with an upstream Slack Web API method path,
+ * optional query, and optional body, and resolves to the upstream status +
+ * parsed JSON. Consumers wire this to the portal's Slack proxy with the user's
+ * Privy bearer; the portal mints the Slack token server-side. Paths are method
+ * names (e.g. `/conversations.list`); read params go in `query`. Write methods
+ * (e.g. `/chat.postMessage`) pass a `body` — the portal classifies the path as a
+ * write and POSTs the body upstream.
+ */
+type SlackProxyCaller = (path: string, query?: Record<string, string | number>, body?: unknown) => Promise<{
+    status: number;
+    json: unknown;
+}>;
+interface SlackListChannelsArgs {
+    limit?: number;
+}
+interface SlackSearchMessagesArgs {
+    query: string;
+    count?: number;
+    /** Restrict the search to a single channel (id or name). Omit to fan out across channels. */
+    channel?: string;
+}
+interface SlackListUsersArgs {
+    limit?: number;
+}
+interface SlackGetChannelHistoryArgs {
+    channel: string;
+    limit?: number;
+}
+interface SlackGetThreadRepliesArgs {
+    channel: string;
+    ts: string;
+    limit?: number;
+}
+interface SlackPostMessageArgs {
+    channel: string;
+    text: string;
+    thread_ts?: string;
+}
+/**
+ * Build the Slack tool set wired to the supplied proxy caller.
+ *
+ * The returned record keys match the underlying tool names so callers can
+ * forward a subset by destructuring.
+ *
+ * @param callProxy GETs an upstream Slack method path + query through the portal
+ *   Slack proxy and resolves to `{ status, json }`. The Slack token never
+ *   reaches the browser -- the portal mints it server-side.
+ */
+declare function createSlackTools(callProxy: SlackProxyCaller): Record<string, ToolConfig>;
+
+/**
+ * Design audit for app-generation output.
+ *
+ * Inspects App.js + App.css and reports inconsistencies in the design
+ * system: raw hex colors outside the :root token block, CSS variables
+ * declared but never used, missing :focus-visible rules on interactive
+ * elements, icon-only buttons without aria-labels, images without alt
+ * text, heading order anti-patterns, inline styles with hardcoded
+ * colors. The audit does not prescribe what design choices to make —
+ * it only checks that whatever the model picked is applied coherently.
+ *
+ * Returned as a structured AuditResult so the model (or a host) can
+ * read it programmatically: each issue has a path, line, severity,
+ * type, and human-readable message. The model is expected to call this
+ * after substantial changes and patch the actionable issues.
+ */
+type AuditSeverity = "error" | "warn" | "info";
+type AuditIssueType = "no-design-tokens" | "raw-color" | "inline-style-with-color" | "unused-token" | "missing-focus-state" | "focus-not-keyed" | "low-contrast" | "off-scale-spacing" | "orphaned-class" | "missing-aria-label" | "missing-alt" | "heading-order";
+interface AuditIssue {
+    /** Where the issue surfaced — error / warn / info. */
+    severity: AuditSeverity;
+    /** Filename (e.g. "App.js" or "App.css"). */
+    path: string;
+    /** 1-based line number. Absent for whole-file issues. */
+    line?: number;
+    /** Machine-readable issue type for grouping or filtering. */
+    type: AuditIssueType;
+    /** Human-readable explanation suitable for showing to an LLM or a developer. */
+    message: string;
+}
+interface AuditTokens {
+    /** CSS variable names classified as color tokens (e.g. ["--bg", "--accent"]). */
+    colors: string[];
+    /** Typography tokens (e.g. ["--font-display"]). */
+    fonts: string[];
+    /** All other tokens (spacing, radii, shadows, etc.). */
+    other: string[];
+}
+interface AuditResult {
+    /** 0-100 score: 100 = clean, 0 = severe issues. Errors -10 each, warns -5, infos -1, floored at 0. */
+    score: number;
+    /** Design tokens discovered in :root. */
+    tokens: AuditTokens;
+    /** Issues found, sorted: errors first, then warns, then infos; within each, by path + line. */
+    issues: AuditIssue[];
+}
+/**
+ * Audit a generated app's design coherence. Pure function — no I/O.
+ *
+ * @param files Map of filename → content. Looks at "App.js" (or "App.jsx")
+ *              and "App.css". Other files are ignored.
+ */
+declare function auditDesign(files: Record<string, string>): AuditResult;
+
+/**
+ * Parent ↔ iframe bridge for `window.app.complete`.
+ *
+ * Generated apps (built via `createAppGenerationTools`) call
+ * `window.app.complete(prompt)` to reach an LLM at runtime — see the
+ * AI CAPABILITIES section of `buildAppSystemPrompt`. The transport is
+ * a host concern: hosts decide which model, which auth, which endpoint.
+ * This module ships the standard postMessage protocol so hosts don't
+ * have to design their own:
+ *
+ *   PARENT (host's chat app):
+ *     installs `createAppCompleteBridge({ complete })`, which listens
+ *     for `anuma:app:complete:connect` announcements from preview
+ *     iframes and answers each one with a private {@link MessagePort}.
+ *     Prompts then arrive only over that port and the host's async
+ *     `complete(prompt)` is called per request.
+ *
+ *   IFRAME (preview HTML where the generated app runs):
+ *     installs the shim via `installAppCompleteIframeShim()` (or by
+ *     inlining `APP_COMPLETE_IFRAME_SHIM_SCRIPT`). The shim sets
+ *     `window.app.complete` to a function that — on first use —
+ *     handshakes with the host to obtain a port, then sends each
+ *     prompt over that port and resolves with the response.
+ *
+ * Why a port handshake rather than posting the prompt straight up the
+ * frame tree: the preview can't read its ancestors' origins
+ * (cross-origin reads throw), so to *find* the host bridge it broadcasts
+ * a connect announcement to every ancestor with targetOrigin "*". That
+ * announcement carries no prompt — just a correlation id — so a frame
+ * sitting between the preview and the host (a bundler/CDN frame, an
+ * analytics or ad wrapper) sees only a content-free ping. The host
+ * answers by transferring one end of a {@link MessageChannel} back to
+ * the requesting frame; all prompt traffic flows over that entangled
+ * port, which no other frame can observe. The prompt is therefore never
+ * broadcast, even in nested-iframe topologies.
+ *
+ * The protocol is intentionally minimal — a connect announcement, a
+ * connect-ack that carries the port, then request/response messages
+ * (each with an id to correlate them) over the port. Sandbox-friendly:
+ * the iframe never reaches outside its origin, the parent never lets the
+ * iframe pick the backend, and `MessageChannel` works in sandboxed /
+ * srcdoc previews whose origin is opaque ("null").
+ *
+ * @example Parent-side wiring:
+ * ```ts
+ * import { createAppCompleteBridge } from "@anuma/sdk/tools";
+ *
+ * const bridge = createAppCompleteBridge({
+ *   // Restrict who can drive complete() — required (or pass `source`).
+ *   allowedOrigins: ["https://preview.example"],
+ *   complete: async (prompt) => {
+ *     const res = await fetch("/api/complete", {
+ *       method: "POST",
+ *       headers: { "Content-Type": "application/json" },
+ *       body: JSON.stringify({ prompt }),
+ *     });
+ *     return await res.text();
+ *   },
+ * });
+ * // when the preview is unmounted:
+ * bridge.dispose();
+ * ```
+ *
+ * @example Iframe-side wiring (preview HTML):
+ * ```html
+ * <script>${APP_COMPLETE_IFRAME_SHIM_SCRIPT}</script>
+ * <!-- now window.app.complete is available to the React app -->
+ * ```
+ */
+/** Announcement broadcast from iframe → ancestors so the host bridge can
+ *  find the preview frame. Carries only a correlation id (no prompt), so
+ *  posting it up the ancestor chain with targetOrigin "*" discloses
+ *  nothing sensitive to intermediate frames. */
+declare const APP_COMPLETE_CONNECT_TYPE = "anuma:app:complete:connect";
+/** Reply from parent → iframe acknowledging a connect. The transferred
+ *  {@link MessagePort} (in the message's `ports`) is the private channel
+ *  the iframe uses for all subsequent prompt traffic. */
+declare const APP_COMPLETE_CONNECT_ACK_TYPE = "anuma:app:complete:connect-ack";
+/** Tagged request from iframe → parent, sent over the entangled
+ *  {@link MessagePort} (never via window postMessage). Carries the prompt
+ *  and a correlation id so the parent can route the reply to the right
+ *  pending promise. */
+declare const APP_COMPLETE_REQUEST_TYPE = "anuma:app:complete:request";
+/** Tagged response from parent → iframe, sent back over the same
+ *  {@link MessagePort}. Either `result` (string) or `error` (string) is
+ *  populated. */
+declare const APP_COMPLETE_RESPONSE_TYPE = "anuma:app:complete:response";
+interface AppCompleteBridgeOptions {
+    /** Host's implementation. Receives the prompt string and resolves
+     *  with the response. May throw / reject; the error message is
+     *  forwarded to the iframe. */
+    complete: (prompt: string) => Promise<string>;
+    /** Origin to send the connect-ack (and its transferred port) to. When
+     *  unset, the ack is targeted at the requesting frame's own
+     *  `event.origin` so a document that later replaces the source window
+     *  can't capture the channel — falling back to "*" only for opaque
+     *  origins (sandboxed / srcdoc iframes, which serialize to "null" and
+     *  can't be targeted by string). Note the "*" fallback cannot protect a
+     *  null-origin preview against a same-window navigation race; pin a known
+     *  origin here (or front the preview with a real origin) when that matters.
+     *  Set explicitly to pin a known origin in production. */
+    targetOrigin?: string;
+    /** Filter connect announcements by source window. When set, connects
+     *  from any other window are ignored. Useful when the parent embeds
+     *  multiple iframes and wants to route them differently. */
+    source?: Window;
+    /** Restrict accepted `event.origin` values for connect announcements.
+     *  Connects from any other origin are silently dropped — so a cross-origin
+     *  script that gains a window handle can't open a channel and burn quota.
+     *  Use the host's own origin (or the preview's, for cross-origin previews);
+     *  for srcdoc/sandboxed previews whose origin is "null", prefer `source`.
+     *  The single-element sentinel `["*"]` opts into accepting every origin
+     *  (logs a one-time warning). Omitting both this and `source` throws — the
+     *  bridge will not silently default to wide-open. */
+    allowedOrigins?: readonly string[];
+}
+interface AppCompleteBridge {
+    /** Remove the message listener and close every open channel. Call when
+     *  the preview is unmounted. */
+    dispose(): void;
+}
+/**
+ * Install a parent-side bridge that answers `window.app.complete`
+ * calls from one or more preview iframes. Returns a handle whose
+ * `dispose()` removes the listener and closes open channels.
+ *
+ * @throws if neither `allowedOrigins` nor `source` is provided. The bridge
+ * runs the host's `complete()` (which holds the API key/quota) for callers, so
+ * it refuses to default to accepting every origin — pass `allowedOrigins`
+ * and/or `source`, or opt in explicitly with `allowedOrigins: ["*"]`.
+ */
+declare function createAppCompleteBridge(options: AppCompleteBridgeOptions): AppCompleteBridge;
+/** Default timeout (ms) for `window.app.complete` calls inside the
+ *  iframe shim. Covers the connect handshake plus the LLM completion —
+ *  long enough for slow completions, short enough to surface a hung or
+ *  absent parent bridge (e.g. unmounted preview). Hosts can override by
+ *  setting `window.APP_COMPLETE_TIMEOUT_MS` in the iframe before the
+ *  first call. */
+declare const APP_COMPLETE_DEFAULT_TIMEOUT_MS = 60000;
+/**
+ * Inline JavaScript source that installs `window.app.complete` in an
+ * iframe. On first use it handshakes with the host bridge to obtain a
+ * private {@link MessagePort}, then sends each prompt over that port.
+ * Drop into a `<script>` tag of a preview HTML to enable in-app LLM
+ * calls.
+ *
+ * Confidentiality: prompts are sent only over the entangled port, never
+ * broadcast up the frame tree. The only thing posted to ancestor frames is
+ * a content-free connect announcement (used to locate the host bridge), so
+ * an intermediate frame that merely *reads* messages can't see prompts —
+ * the passive-disclosure leak this transport was designed to close.
+ *
+ * What the default does NOT defend against: an actively-malicious ancestor
+ * frame. The connect announcement (and its correlation id) is broadcast to
+ * every ancestor, so such a frame can race a forged connect-ack carrying its
+ * own port; if it wins, that port becomes the channel and it then reads
+ * every prompt. The iframe cannot read an ancestor's origin to tell the real
+ * host from an impostor, so closing this active path needs a trust anchor:
+ * set `window.APP_COMPLETE_PARENT_ORIGIN` to the host's origin before the
+ * first call and the shim accepts a connect-ack only from that origin (pair
+ * it with `allowedOrigins` on the bridge). Strongly recommended whenever an
+ * untrusted cross-origin frame can sit between the preview and the host.
+ *
+ * No-ops when there's no parent window (e.g. when the HTML is opened
+ * directly via `file://` rather than embedded in an iframe). In that
+ * case, hosts can provide their own `window.app.complete` stub or
+ * leave it unset.
+ *
+ * Each call has a {@link APP_COMPLETE_DEFAULT_TIMEOUT_MS} ms timeout
+ * (overridable via `window.APP_COMPLETE_TIMEOUT_MS`); on timeout the promise
+ * rejects and its pending state is cleaned up, so a disposed or absent parent
+ * bridge can't leave the app frozen. A timeout on the established channel also
+ * drops it, so the next call re-handshakes — recovering if the bridge was torn
+ * down and a new one has since mounted.
+ */
+declare const APP_COMPLETE_IFRAME_SHIM_SCRIPT: string;
+/**
+ * Programmatic variant of `APP_COMPLETE_IFRAME_SHIM_SCRIPT` — call once
+ * from inside an iframe (typically the first thing the preview HTML
+ * executes) to install `window.app.complete`. Equivalent to inlining
+ * the script string in a `<script>` tag.
+ */
+declare function installAppCompleteIframeShim(): void;
+
+/**
+ * Standalone HTML export for app-generation outputs.
+ *
+ * The app-generation tools produce three files — App.js, App.css, and
+ * package.json — that together describe a React app. `exportAppToHtml`
+ * compiles them into a single self-contained HTML file that runs
+ * anywhere via `file://`: it inlines App.css, strips local imports
+ * from App.js, maps package.json deps to esm.sh CDN URLs, and wires
+ * up React UMD + Babel standalone for in-browser JSX compilation.
+ *
+ * Useful for letting end users download what the model built, or for
+ * embedding generated apps in iframes without a bundler. Hosts that
+ * provide their own preview infrastructure (e.g. a hosted iframe with
+ * a custom shim for `window.app.complete`) can pass `windowAppShim`
+ * to inject their bridge in place of the default offline stub.
+ *
+ * @example Single-file download for an end-user:
+ * ```ts
+ * import { exportAppToHtml } from "@anuma/sdk/tools";
+ *
+ * const html = exportAppToHtml({
+ *   files: {
+ *     "App.js": await storage.getFile(convId, "App.js"),
+ *     "App.css": await storage.getFile(convId, "App.css"),
+ *     "package.json": await storage.getFile(convId, "package.json"),
+ *   },
+ *   title: "My Generated App",
+ * });
+ * // Browser:
+ * const blob = new Blob([html], { type: "text/html" });
+ * const url = URL.createObjectURL(blob);
+ * Object.assign(document.createElement("a"), { href: url, download: "app.html" }).click();
+ * ```
+ *
+ * @example iframe preview with a parent-side LLM bridge:
+ * ```ts
+ * import { exportAppToHtml, APP_COMPLETE_IFRAME_SHIM_SCRIPT } from "@anuma/sdk/tools";
+ *
+ * const html = exportAppToHtml({
+ *   files: { ... },
+ *   windowAppShim: APP_COMPLETE_IFRAME_SHIM_SCRIPT,
+ * });
+ * previewIframe.srcdoc = html;
+ * ```
+ */
+/**
+ * Inline JS that buffers any `error` / `unhandledrejection` event on the
+ * window and, if `#root` is still empty after the React app has had time
+ * to mount, paints a visible error banner into the page. Without this,
+ * an unhandled import or render error leaves the user staring at the
+ * body background color with no indication of what went wrong (the
+ * exact failure mode we just shipped: ESM `LayoutKanban` did not
+ * exist; React never mounted; preview was a blank navy rectangle).
+ *
+ * Buffer-then-check pattern: errors are recorded as they fire, but the
+ * overlay only paints when `#root.childNodes.length === 0` after a
+ * load+grace window. That means errors thrown by a successfully-
+ * mounted app (e.g. user clicks a button that throws) never trigger
+ * the overlay — they belong in the console and the app handles its
+ * own UI. The grace covers Babel-standalone compilation time + ESM
+ * resolver round-trips, which empirically takes 1-3s.
+ *
+ * Written in ES5 with no fancy syntax — runs in a plain `<script>`
+ * (not module mode), so even very old browsers parse it.
+ */
+declare const RUNTIME_ERROR_OVERLAY_SCRIPT = "// Runtime error overlay \u2014 surfaces a visible banner when the app fails\n// to mount. See RUNTIME_ERROR_OVERLAY_SCRIPT docstring for design.\n(function () {\n  var errors = [];\n  function record(label, message) {\n    errors.push(label + \": \" + message);\n  }\n  window.addEventListener(\"error\", function (e) {\n    record(\"Error\", (e.error && e.error.message) || e.message || String(e));\n  });\n  window.addEventListener(\"unhandledrejection\", function (e) {\n    var msg = (e.reason && (e.reason.message || String(e.reason))) || \"unknown\";\n    record(\"Unhandled rejection\", msg);\n  });\n  function paint() {\n    var root = document.getElementById(\"root\");\n    if (!root) return;\n    if (root.childNodes.length > 0) return;\n    if (errors.length === 0) return;\n    var box = document.createElement(\"div\");\n    box.setAttribute(\"data-anuma-error-overlay\", \"\");\n    box.style.cssText = \"position:fixed;inset:0;background:#1a0c0c;color:#ffb4b4;font:14px/1.5 ui-monospace,Menlo,monospace;padding:24px;overflow:auto;z-index:99999\";\n    var h = document.createElement(\"h2\");\n    h.textContent = \"Runtime error \u2014 the React app did not mount\";\n    h.style.cssText = \"color:#ff8080;margin:0 0 16px;font-size:16px;font-weight:600\";\n    box.appendChild(h);\n    for (var i = 0; i < errors.length; i++) {\n      var p = document.createElement(\"p\");\n      p.textContent = errors[i];\n      p.style.cssText = \"margin:0 0 10px;white-space:pre-wrap;font-family:inherit\";\n      box.appendChild(p);\n    }\n    var hint = document.createElement(\"p\");\n    hint.textContent = \"Common causes: an imported export name that doesn't exist in the package, a syntax error in App.js, a missing dependency in package.json, or a network failure loading a CDN module.\";\n    hint.style.cssText = \"margin:18px 0 0;color:#a08080;font-size:12px;line-height:1.55\";\n    box.appendChild(hint);\n    root.appendChild(box);\n  }\n  function schedule() {\n    setTimeout(paint, 3000);\n  }\n  if (document.readyState === \"complete\") {\n    schedule();\n  } else {\n    window.addEventListener(\"load\", schedule);\n  }\n})();";
+/**
+ * Baseline CSS that defines what the model can assume about the preview
+ * environment — applied before `App.css` in both `exportAppToHtml`'s
+ * standalone output and the chat host's Sandpack iframe template.
+ *
+ * Why this exists: the model writes CSS targeting component classes
+ * (`.app-shell`, `.card`) but rarely resets the surrounding `html` /
+ * `body` chrome. In environments without a preflight (Sandpack's bare
+ * iframe), browser defaults leak through — the visible symptom is the
+ * 8 px `body` margin everyone notices, but the same root cause produces
+ * `content-box` sizing surprises, Times-serif fallback on stray text
+ * outside styled wrappers, and `<img>` baseline gaps. Tailwind's
+ * preflight solves it at scale in environments that bundle Tailwind;
+ * we provide the minimal equivalent for environments that don't.
+ *
+ * Design rules:
+ *
+ *   - Only fix actual leaks (rules that surface as visible bugs).
+ *     Don't ship a maximal reset like normalize.css — every entry here
+ *     should be defensible as "the model would have to fight this
+ *     default anyway."
+ *   - Loaded BEFORE the model's `App.css`. CSS specificity ties go to
+ *     the later-loaded rule, so the model's CSS still wins on every
+ *     property it sets. The baseline only provides defaults for what
+ *     the model didn't set.
+ *   - Stays in sync between `exportAppToHtml` (standalone download)
+ *     and the host's Sandpack template (chat preview). Single source
+ *     of truth so the two environments render identically.
+ */
+declare const APP_PREVIEW_BASELINE_CSS = "*, *::before, *::after { box-sizing: border-box; }\nhtml, body, #root { margin: 0; padding: 0; min-height: 100%; }\nbody {\n  font-family: system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n  line-height: 1.5;\n  -webkit-text-size-adjust: 100%;\n}\nimg, picture, video, canvas, svg { display: block; max-width: 100%; }\nbutton, input, select, textarea { font: inherit; }";
+/** Stub for `window.app.complete` that returns canned responses based on
+ *  keyword detection. Used when no real LLM backend is available — keeps
+ *  the visual preview interactive enough to demo. The default value of
+ *  `ExportAppOptions.windowAppShim`. */
+declare const APP_COMPLETE_STUB_SCRIPT = "// Offline stub for window.app.complete \u2014 returns canned responses so the\n// preview is interactive without a real backend. Replace by passing\n// windowAppShim to exportAppToHtml (e.g. APP_COMPLETE_IFRAME_SHIM_SCRIPT\n// for parent-iframe postMessage bridging) or by overwriting at runtime.\nwindow.app = window.app || {};\nwindow.app.complete = async function (prompt) {\n  console.info(\"[stub] window.app.complete called:\", String(prompt).slice(0, 120));\n  await new Promise((r) => setTimeout(r, 400));\n  var p = String(prompt || \"\").toLowerCase();\n  if (p.includes(\"correct\") || p.includes(\"grade\") || p.includes(\"evaluate\")) {\n    return \"\u2713 Correct \u2014 that's the right answer. (stub response)\";\n  }\n  if (p.includes(\"explain\") || p.includes(\"why\") || p.includes(\"how\")) {\n    return \"Here's an explanation: this is a stub response. Wire window.app.complete to a real LLM to see actual reasoning.\";\n  }\n  if (p.includes(\"summarize\") || p.includes(\"summary\")) {\n    return \"Summary: (stub response \u2014 connect to a real backend for real summaries.)\";\n  }\n  return \"Stub AI response. Replace window.app.complete with a real backend bridge to enable real generations.\";\n};";
+interface ExportAppOptions {
+    /** Map of file path → file content. Must include `App.js` (or `App.jsx`).
+     *  Optional: `App.css`, `package.json`. Other files are ignored — the
+     *  output is single-file. */
+    files: Record<string, string>;
+    /** `<title>` for the page. Defaults to `"App"`. */
+    title?: string;
+    /** Include the Tailwind Play CDN `<script>`. Defaults to `true`. Set
+     *  to `false` if the generated app uses only the inlined App.css. */
+    tailwind?: boolean;
+    /** JS source installed before the React app boots — typically sets up
+     *  `window.app.complete` (and any related helpers). Defaults to
+     *  {@link APP_COMPLETE_STUB_SCRIPT}, an offline canned-response stub.
+     *  Pass {@link APP_COMPLETE_IFRAME_SHIM_SCRIPT} for an iframe embed
+     *  with a parent-side bridge, or `""` to omit entirely. */
+    windowAppShim?: string;
+}
+/**
+ * Compile an app-generation output (App.js + App.css + package.json) into
+ * a single self-contained HTML file. See module docstring for examples.
+ *
+ * Loader strategy: native ESM via `<script type="importmap">` resolves
+ * every package name (react, react-dom/client, plus whatever's in
+ * package.json) to an esm.sh URL. Babel-standalone runs the App.js
+ * source as `<script type="text/babel" data-type="module">` so JSX is
+ * compiled to JS but imports stay as ES-module imports — the browser
+ * resolves them through the importmap. No window globals, no UMD
+ * sequencing, no per-package compatibility wrappers.
+ */
+declare function exportAppToHtml(options: ExportAppOptions): string;
+
+/**
+ * App Builder agent persona prompt — canonical source for the SDK.
+ *
+ * Mirrors the `SENTINEL_PROMPT` / `HAVEN_PROMPT` pattern: the prompt lives in
+ * code and the SDK owns it. Imported as the App Builder persona by hosts that
+ * wire `createAppGenerationTools` directly, and attached to the
+ * `app-generation` tool set's `systemPrompt` so it rides in with semantic tool
+ * selection.
+ *
+ * Lives in its own dependency-free module (no `@babel/parser` etc.) so the
+ * lib/server layer can import the string without pulling in the heavy
+ * app-generation runtime — see `BUILT_IN_TOOL_SETS` in
+ * `src/lib/tools/serverTools.ts`.
+ *
+ * Pair with the tools returned by `createAppGenerationTools` — `create_file`,
+ * `patch_file`, `read_file`, `delete_file`, `list_files`, `audit_design`,
+ * `critique_design`, `verify_app`.
+ *
+ * The workflow this prompt mandates (create → critique → patch → audit →
+ * patch → verify) needs 7–8 tool rounds on a substantial turn. Hosts capping
+ * `maxToolRounds` below 8 starve the trailing `verify_app` step.
+ */
+declare const APP_BUILDER_PROMPT = "App Builder tools (create_file, patch_file, and the rest described below) are available this turn, but they are OPTIONAL \u2014 having them does not mean you should build anything.\n\nBuild ONLY when the user gives an explicit instruction to build, create, generate, or change an app, tool, or UI \u2014 e.g. \"build a todo app\", \"make a snake game\", \"add a footer to the app\", \"change the background to blue\". A bare app name or feature reference is NOT a build instruction: if the user just says \"todo app\", \"a snake game\", or \"qr code\", or asks a question about an app, do NOT generate anything \u2014 reply normally, or ask what they'd like you to build. The same holds for greetings, questions, stories, explanations, advice, or code that isn't a runnable app: respond normally and do not create files. When it's unclear whether the user actually wants an app built, ask instead of building.\n\nOnce the user HAS given an explicit build instruction, you are in App Builder mode: you produce polished, production-quality React apps that feel designed \u2014 not generic.\n\nDESIGN: on the initial build, before writing code, briefly state (2-3 sentences) what you want this app to feel like \u2014 name the specific fonts, the palette in hex, and one signature detail. Be concrete: \"Fraunces display + Inter body + JetBrains Mono metadata, terracotta #b75432 accent on bone #f3efe6, paper-grain texture via inline SVG noise\" is the kind of specificity that anchors the build. Default to nothing: don't pick \"safe modern productivity\" unless the brief literally asks for utilitarian. On later turns, state a design brief only when the change is visual (a restyle, new theme, or new UI); for a logic, data, or behavior-only change, skip the brief and just make the change.\n\nWORKFLOW:\n1. NEVER output code as text or markdown. ALWAYS use tools.\n2. Initial build: state your design brief, then create_file with a \"files\" array writing ALL files in one call. The preview renders automatically.\n3. patch_file requires read_file for that path earlier in the conversation (or create_file in the same conversation, which counts). read_file output is numbered \"42: <text>\" \u2014 the prefix is display-only; never copy it into \"find\". Each \"find\" must match exactly one location \u2014 include 2-3 lines of surrounding context. Pass multiple patches per call to change distinct locations.\n4. Prefer patch_file for changes to existing files \u2014 surgical, reviewable, preserves surrounding code. Reserve create_file overwrites for substantial restructuring. Inserts: find the line before, replace with that line + the new line. Deletes: empty replace.\n5. After substantial changes, call critique_design first (taste, hierarchy, distinctiveness, weakest decision) and then audit_design (mechanical: tokens, focus states, aria-labels, alt, heading order). Patch what each surfaces. critique catches taste issues no checklist would; audit catches mechanics you'd miss. Run both; act on both.\n6. Before declaring done, call verify_app. The host's preview runtime reports whether your app actually mounted and surfaces any errors it captured \u2014 hallucinated imports, syntax the bundler rejected, undefined components, runtime crashes. If `rendered` is false or `errors` is non-empty, fix every error before the next message. If the response includes a `note` that verify_app isn't wired in this host, skip \u2014 audit + critique are your feedback in that case.\n7. Keep responses to a sentence or two. Exception: when responding to critique_design, write a substantive paragraph per rubric question.\n\nSTRUCTURE:\n- App.js: default-export React component. For non-trivial apps, define small co-located helpers (Header, CardList, Card, EditDialog, \u2026) above the default export rather than one giant App.\n- App.css: all styles, imported in App.js. No inline style objects.\n- package.json: list ALL imported packages including react. No CDN script tags. Versions are auto-pinned.\n- Do NOT create index.js or index.html (auto-generated).\n\nSTATE & PERSISTENCE:\n- The code runs in the user's browser \u2014 standard browser APIs available (localStorage, URL hash, Date, fetch).\n- Persist user-created data (todos, cards, notes, settings) with localStorage so it survives refresh. Use a versioned key (\"kanban.v1\") and JSON.parse inside try/catch on read.\n- Treat persisted data as untrusted and possibly stale: a saved record may predate a field you just added (a timestamp, id, or setting), so default-fill or skip missing fields on read \u2014 never assume a loaded record has every field the current code expects. Bump the key version when the shape changes.\n- Lift state to App when multiple children need it; keep it local otherwise. Extract non-trivial logic into custom hooks (useTodos, useTimer).\n- useReducer for state shapes with several interrelated fields (cards + columns + filters + drag state).\n\nFILE & IMAGE UPLOAD:\n- Picker: `<input type=\"file\" accept=\"image/*\" multiple>` (vary accept by use case: `.csv,text/csv`, `.txt,.md,text/plain`, etc.).\n- Drag-and-drop: call `e.preventDefault()` in onDragOver (otherwise drop never fires); read files from `event.dataTransfer.files`. Drop and picker should coexist.\n- Previews: `<img src={URL.createObjectURL(file)} />`. Call `URL.revokeObjectURL` on unmount or before replacing \u2014 otherwise the browser leaks memory.\n- localStorage cannot hold large binary. Persist only metadata for big files; re-upload on next visit (or use IndexedDB if you really need durable binary storage).\n- Validate size and type before processing; reject files larger than the app can hold in memory.\n\nAI CAPABILITIES \u2014 `window.app.complete(prompt: string): Promise<string>` is available in this environment. Build for the real call.\n- When the app's core purpose is conversation, generation, grading, recommendation, or any natural-language task, this IS the implementation \u2014 call it. NEVER fake it: no hardcoded or canned replies, no random or `setTimeout` \"thinking\", no demo-mode stub. A chat app, tutor, or assistant that doesn't call `window.app.complete` is wrong, not a placeholder.\n- Don't force it where it isn't needed \u2014 a calculator, todo list, or timer has no reason to call it. Match the implementation to what the app actually does.\n- Async: wrap in try/catch, show a loading state, and disable dependent inputs while waiting. Surface failures gracefully (\"Couldn't reach the AI \u2014 try again\").\n- Structure prompts with clear sections (Role / Context / Task / Format) and pass the relevant state (e.g. the running conversation) as context. Render the response as untrusted text: `white-space: pre-wrap`, never dangerouslySetInnerHTML.\n- Skip the call only when the answer is genuinely static \u2014 no language or reasoning needed. Cache repeated prompts in component state when sensible.\n\nCODE QUALITY \u2014 write as a senior engineer would:\n- Handle edge cases (empty inputs, division by zero, invalid data). Show helpful error states, not crashes.\n- Never let formatting throw during render: guard `new Date(x)` / `Intl` / `toLocaleString` / `.toFixed` against missing or invalid values (e.g. `Number.isNaN(d.getTime())`) and return a fallback \u2014 one bad value from storage or state must not blank the whole app.\n- Semantic HTML: real headings, labels, buttons (not divs with onClick), form elements.\n- Accessible: aria-labels on icon buttons, focus-visible styles, keyboard navigable.\n- Extract into custom hooks or helpers when a component grows past ~80 lines.\n\nSTYLING \u2014 Tailwind is the CHASSIS, custom CSS carries the IDENTITY:\n- Tailwind (via Play CDN) for layout, spacing, state (hover/focus), responsive prefixes \u2014 uniform structure.\n- App.css carries the identity: @import the Google Fonts, declare CSS custom properties (--bg, --panel, --card, --ink, --muted, --accent, --hairline, --radius, --radius-sm, --shadow-card, --shadow-card-hi) in :root, gradients/textures/signature animations Tailwind can't express. Reference tokens from Tailwind via arbitrary values (`className=\"bg-[var(--bg)]\"`) when needed. A well-designed app has 60-200 lines of App.css \u2014 not zero.\n- Modern CSS is how apps stop reading as generic-AI-output: `color-mix(in oklab, var(--accent) 14%, transparent)` for tinting, `oklch()` / `oklab()` for perceptually-uniform color, `:has()`, `conic-gradient` / `radial-gradient`, `backdrop-filter`, `@container` queries, inline SVG `feTurbulence` for texture.\n- Don't pull additional CSS frameworks. Tailwind + custom CSS is enough.\n\nVISUAL DESIGN \u2014 every app should look like a real product, not a wireframe:\n- Let the chosen aesthetic drive every decision. \"Editorial\" wants italic display type and restrained color; \"retro arcade\" wants chunky shadows and saturated gradients. No safe-modern defaults.\n- Atmospheric depth: subtle radial wash, paper grain (inline SVG noise), warm/cool tint \u2014 every canvas should feel like a designed space, not a #fff rectangle.\n- Three shadow tiers (rest / hover / active). Pair drop shadows with inset highlights (`box-shadow: 0 1px 0 rgba(255,255,255,.9) inset, 0 6px 14px -10px ...`) for tactile feel.\n- Typography hierarchy: display font for headlines (italic accents on key words via `<em>`), body font for content, mono for metadata/labels \u2014 different families telegraph different information types.\n- Interactive polish: hover/active/focus on every clickable element, 200-300ms cubic-bezier transitions, keyboard shortcuts where natural (Esc to cancel, Cmd/Ctrl+Enter to commit), focus-visible rings keyed to the accent.\n- Light/dark mode if reasonable: a single CSS variable inversion under `[data-theme=\"dark\"]`.\n- Customization affordance for multi-session apps: small \"Tweaks\" panel with theme / density / accent. Skip for throwaway demos.\n- Responsive: Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) and `@media` in App.css. Mobile-first.";
+
+/** Strip leading slash and collapse traversal segments so paths are always clean relative paths. */
+declare function normalizePath(p: string): string;
+
+/**
+ * App generation tools for multi-file app development.
+ *
+ * Provides create_file, patch_file, delete_file, read_file, and list_files
+ * tool configurations, plus the system prompt that drives LLM behavior.
+ * The tools operate on a pluggable storage backend so consumers can wire
+ * them to IndexedDB, an in-memory Map, a database, or any other
+ * persistence layer.
+ *
+ * App preview rendering is automatic: every successful create_file /
+ * patch_file / delete_file invokes the host's optional `displayApp`
+ * callback so the chat UI refreshes the same preview card in place. There
+ * is no standalone `display_app` tool — mirrors the slide pipeline, where
+ * `add_slide` and `patch_slides` self-render via `displaySlides`.
+ *
+ * @example
+ * ```typescript
+ * import { createAppGenerationTools, buildAppSystemPrompt } from "@anuma/sdk/tools";
+ *
+ * const tools = createAppGenerationTools({
+ *   getConversationId: () => currentConversationId,
+ *   storage: myStorageAdapter,
+ * });
+ * ```
+ */
+
+/** Minimal file record returned by storage operations. */
+interface AppFileRecord {
+    path: string;
+    content: string;
+}
+/**
+ * Pluggable storage backend for app files.
+ * Consumers provide an implementation backed by IndexedDB, a Map, etc.
+ */
+interface AppFileStorage {
+    getFile: (conversationId: string, path: string) => Promise<AppFileRecord | null>;
+    getFiles: (conversationId: string) => Promise<AppFileRecord[]>;
+    putFile: (conversationId: string, path: string, content: string) => Promise<void>;
+    putFiles: (conversationId: string, files: Array<{
+        path: string;
+        content: string;
+    }>) => Promise<void>;
+    deleteFile: (conversationId: string, path: string) => Promise<void>;
+}
+
+/**
+ * Truncate file content for inclusion in tool results.
+ * Keeps the first and last portions so the LLM has both the beginning
+ * (imports, declarations) and end (exports, closing tags) of the file.
+ */
+declare function truncateContent(content: string): string;
+/** Numbered slice of file content surrounding a point of interest. */
+interface FileSnippet {
+    startLine: number;
+    endLine: number;
+    content: string;
+}
+/** Result of fuzzy-locating where a failed `find` was probably targeting.
+ *  `high` confidence means a non-noisy line matched; `low` means only a
+ *  generic markup line (e.g. SVG header) matched and the snippet would
+ *  likely mislead the model. */
+interface AnchorMatch {
+    line: number;
+    confidence: "high" | "low";
+}
+/** Reason a single patch did not apply. */
+type PatchFailureReason = "empty_find" | "not_found" | "ambiguous";
+/** Details for a patch that did not apply, indexed against the input array.
+ *  `matchLines` is populated only for `reason: "ambiguous"` — the 1-based
+ *  line numbers where the find string starts in the file. */
+interface PatchFailure {
+    index: number;
+    find: string;
+    reason: PatchFailureReason;
+    matchLines?: number[];
+}
+/**
+ * Apply find/replace patches to a string atomically.
+ *
+ * Either all patches apply, or none do — when any patch fails (no match,
+ * empty find, or ambiguous match), the returned `content` equals the input
+ * and `appliedCount` is 0. This prevents committing partial edits to disk
+ * (e.g. a rename that succeeds in some call sites but not others).
+ *
+ * A `find` must match the file exactly once. Multiple matches surface as
+ * `reason: "ambiguous"` so the model can disambiguate by adding context
+ * rather than silently editing the first occurrence.
+ *
+ * Before declaring a `find` unmatched, the function tries two fallbacks:
+ *   1. unescaping JSON whitespace literals (`\\n`, `\\t`, `\\r` as
+ *      two-character backslash sequences → real newline/tab/CR);
+ *   2. stripping leading "42: " line-number prefixes when every line of
+ *      the find carries one (the model may have copied numbered output
+ *      from read_file or a failure snippet verbatim).
+ * Ambiguity is checked against whichever variant matches.
+ *
+ * Returned `failed` includes the full `find` string and its index in the
+ * input array so the caller can map failures back to the original patches
+ * without ambiguity.
+ */
+declare function applyPatches(content: string, patches: Array<{
+    find: string;
+    replace: string;
+}>): {
+    content: string;
+    appliedCount: number;
+    failed: PatchFailure[];
+};
+/** Tool names for app file operations (create, patch, delete, read, list,
+ *  audit, critique, verify). */
+declare const APP_FILE_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * In-memory `AppFileStorage` backed by a `Map<string, string>`.
+ *
+ * Useful for server-side consumers (Cloudflare Workers, Node.js) that manage
+ * their own persistence. The `conversationId` parameter is ignored — all
+ * operations target the single internal map.
+ *
+ * @example
+ * ```typescript
+ * const storage = new MapFileStorage();
+ * const tools = createAppGenerationTools({
+ *   getConversationId: () => "task-1",
+ *   storage,
+ * });
+ * // After tool execution, read the files:
+ * const files = storage.getAll(); // Map<string, string>
+ * ```
+ */
+declare class MapFileStorage implements AppFileStorage {
+    private files;
+    constructor(initial?: Map<string, string>);
+    getFile(_conversationId: string, path: string): Promise<AppFileRecord | null>;
+    getFiles(_conversationId: string): Promise<AppFileRecord[]>;
+    putFile(_conversationId: string, path: string, content: string): Promise<void>;
+    putFiles(_conversationId: string, files: Array<{
+        path: string;
+        content: string;
+    }>): Promise<void>;
+    deleteFile(_conversationId: string, path: string): Promise<void>;
+    /** Direct access to the underlying map. */
+    getAll(): Map<string, string>;
+    /** Number of files stored. */
+    get size(): number;
+    /** Serialize to JSON for persistence (e.g. Durable Object storage). */
+    serialize(): string;
+    /** Restore from a previously serialized JSON string. */
+    static deserialize(json: string | undefined | null): MapFileStorage;
+}
+declare const CREATE_FILE_SCHEMA: {
+    readonly name: "create_file";
+    readonly description: "Build a complete, standalone interactive app from scratch — a calculator, a game, a todo list, a dashboard, a simulation, or another self-contained interactive tool. Writes files into the in-chat app project; the live preview renders automatically. Pass every file (App.js, App.css, package.json, ...) in a single call.\n\ncreate_file creates new files and can also overwrite existing ones for substantial restructures. For overwrites, you must have called read_file for the path earlier in this conversation (or created it via create_file in the same conversation) — the tool refuses otherwise. For incremental changes, prefer patch_file: it's easier to review and preserves surrounding code unchanged.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly files: {
+                readonly type: "array";
+                readonly description: "Files to write. Each item: {\"path\": \"App.js\", \"content\": \"...\"}";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly path: {
+                            readonly type: "string";
+                        };
+                        readonly content: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: readonly ["path", "content"];
+                };
+            };
+        };
+        readonly required: readonly ["files"];
+    };
+};
+declare const PATCH_FILE_SCHEMA: {
+    readonly name: "patch_file";
+    readonly description: "Edit, modify, or update an existing file in the app project via find-and-replace. Use this instead of create_file when changing a few lines of an existing app — small edits, fixes, or component updates.\n\nREQUIRED: you must call read_file (or create_file) for this path earlier in the conversation before calling patch_file. The tool refuses otherwise — you cannot patch a file whose current content you have not seen.\n\nPass a \"patches\" array of {find, replace} objects. Each \"find\" string must:\n  - match the file exactly, character for character;\n  - match EXACTLY ONE location — if your find appears multiple times, the patch is rejected as ambiguous. Include 2-3 lines of surrounding context to make it unique;\n  - NOT include the \"<n>: \" line-number prefix from read_file output.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "File path to patch";
+            };
+            readonly patches: {
+                readonly type: "array";
+                readonly description: "Array of find/replace operations";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly find: {
+                            readonly type: "string";
+                            readonly description: "Exact string to find in the file";
+                        };
+                        readonly replace: {
+                            readonly type: "string";
+                            readonly description: "Replacement string";
+                        };
+                    };
+                    readonly required: readonly ["find", "replace"];
+                };
+            };
+        };
+        readonly required: readonly ["path", "patches"];
+    };
+};
+declare const DELETE_FILE_SCHEMA: {
+    readonly name: "delete_file";
+    readonly description: "Deletes a file from the app project.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "File path to delete";
+            };
+        };
+        readonly required: readonly ["path"];
+    };
+};
+declare const READ_FILE_SCHEMA: {
+    readonly name: "read_file";
+    readonly description: "Reads the content of a file from the app project. Required before patch_file on any file whose content you have not just written via create_file. Returned content has \"<lineNumber>: \" prefixes for navigation — do not copy those prefixes into a patch_file \"find\" string.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "File path to read";
+            };
+        };
+        readonly required: readonly ["path"];
+    };
+};
+declare const LIST_FILES_SCHEMA: {
+    readonly name: "list_files";
+    readonly description: "Lists all files in the app project. Returns file paths and sizes. Use this to understand the current project structure.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly required: readonly [];
+    };
+};
+declare const AUDIT_DESIGN_SCHEMA: {
+    readonly name: "audit_design";
+    readonly description: "Inspect the current app's design coherence. Reports raw hex colors outside :root (should be tokens), CSS variables declared but unused, missing :focus-visible rules on interactive elements, icon-only buttons without aria-label, images without alt, heading-level skips, and inline styles with hardcoded colors. Returns a 0-100 score and a list of issues with line numbers. Call this after substantial changes to verify the design system is intact, then patch the actionable issues.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly required: readonly [];
+    };
+};
+declare const CRITIQUE_DESIGN_SCHEMA: {
+    readonly name: "critique_design";
+    readonly description: "Step back and look at what you just made. Returns App.js + App.css plus a rubric of open-ended questions for you to answer honestly in your next response — about intent, hierarchy, distinctiveness, coherence, and what's weakest. This is not a checklist of rules; it's an occasion to apply taste. After answering, patch the 2-3 weakest items you identified. Call this after the initial build and after substantial design changes — complementary to audit_design (which catches mechanical/accessibility issues), where critique_design catches taste and composition.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly required: readonly [];
+    };
+};
+declare const VERIFY_APP_SCHEMA: {
+    readonly name: "verify_app";
+    readonly description: "Ask the host runtime whether the current app actually mounts. The host's bundler / preview iframe (e.g. Sandpack in a chat UI) is already compiling and running your code; this tool collects whatever errors that runtime captured — hallucinated imports, syntax the bundler rejects, undefined components, runtime crashes — and returns them. Use this after substantial changes and before declaring done. If `rendered` is false or `errors` is non-empty, fix every error before doing anything else. If the host did not wire a runtime verifier, the tool returns `{ rendered: true, errors: [] }` with a `note` explaining — degrade to audit_design + critique_design in that case.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly required: readonly [];
+    };
+};
+/** Default open-ended questions for `critique_design`. Each is designed to
+ *  extract the model's own judgment rather than enforce a property — the
+ *  model brings the taste, the rubric only supplies the occasion. */
+declare const DEFAULT_DESIGN_CRITIQUE_RUBRIC: readonly string[];
+/**
+ * Result returned by the host's `verifyApp` hook (and surfaced as the
+ * `verify_app` tool's response to the model). Same shape regardless of
+ * how the host implements verification — Sandpack error state, an
+ * iframe error listener, a headless browser in a benchmark, etc.
+ *
+ * `rendered`: did the React app actually mount in the host's runtime?
+ *   True when the preview is showing content; false when the runtime
+ *   reported a fatal failure or never mounted within the host's wait
+ *   window.
+ *
+ * `errors`: human-readable error messages captured by the runtime. One
+ *   per distinct error. Order is host-defined; usually chronological.
+ *
+ * `note`: optional explanation when the result is degenerate — host
+ *   didn't wire the hook, hook is wired but the preview isn't mounted
+ *   yet, etc. Lets the model interpret the result correctly without
+ *   silently treating "no errors" as success.
+ */
+interface VerifyAppResult {
+    rendered: boolean;
+    errors: string[];
+    note?: string;
+}
+/**
+ * Event emitted after a successful file mutation. Hosts subscribe via
+ * the `onFileChange` option to {@link createAppGenerationTools} and
+ * attach versioning (isomorphic-git, sqlite-history, etc.), audit
+ * logs, analytics, or whatever else benefits from a per-mutation hook.
+ *
+ * Read operations (`read_file`, `list_files`) do not emit — they
+ * don't mutate state.
+ *
+ * Batch `create_file` calls fan out to one event per file, with each
+ * file getting `type: "created"` or `type: "modified"` depending on
+ * whether it existed before the write.
+ */
+type FileChangeEvent = {
+    type: "created";
+    conversationId: string;
+    path: string;
+    content: string;
+    tool: "create_file";
+} | {
+    type: "modified";
+    conversationId: string;
+    path: string;
+    before: string;
+    after: string;
+    tool: "create_file" | "patch_file";
+} | {
+    type: "deleted";
+    conversationId: string;
+    path: string;
+    before: string;
+    tool: "delete_file";
+};
+interface CreateAppGenerationToolsOptions {
+    /** Returns the current conversation ID (may be null before first message). */
+    getConversationId: () => string | null;
+    /** Storage backend for file operations. */
+    storage: AppFileStorage;
+    /** Optional error logger. Falls back to console.error. */
+    logError?: (message: string, error?: Error) => void;
+    /**
+     * Optional host callback that renders / refreshes the app preview in
+     * the chat UI. When provided, it's invoked automatically after every
+     * successful create_file / patch_file / delete_file — the model
+     * never needs to call a separate display tool. Mirrors the
+     * `displaySlides` pattern in `createSlideTools`.
+     *
+     * The callback receives `{ title?, replaces_interaction_id? }` and
+     * should return `{ interaction_id, title? }` so subsequent calls can
+     * thread `replaces_interaction_id` and fold updates onto the same card.
+     */
+    displayApp?: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+    /**
+     * Optional host callback that runs the generated app in whatever
+     * runtime the host has available (Sandpack iframe in a chat UI, a
+     * headless browser in a benchmark, etc.) and reports back whether
+     * the app mounted plus any errors the runtime captured.
+     *
+     * When wired, the SDK exposes a `verify_app` tool the model can call
+     * after substantial changes; the tool's executor invokes this hook
+     * and returns the result to the model. When NOT wired, the tool
+     * still exists but returns `{ rendered: true, errors: [], note: … }`
+     * so the model degrades gracefully to audit/critique-only feedback.
+     *
+     * Same host-hook pattern as `displayApp` and `onFileChange` — the
+     * SDK never executes anything itself.
+     */
+    verifyApp?: () => Promise<VerifyAppResult>;
+    /**
+     * Optional host callback fired after every successful file mutation
+     * (`create_file`, `patch_file`, `delete_file`). See
+     * {@link FileChangeEvent} for the event shape.
+     *
+     * Use this to attach versioning, audit logs, or analytics from the
+     * host side without wrapping the storage adapter. The callback is
+     * `await`ed but a thrown error is logged and swallowed — a host
+     * subsystem failure should not fail the underlying tool.
+     *
+     * Read tools (`read_file`, `list_files`) and failed mutations
+     * (validation errors, patch ambiguity, syntax errors) do not emit.
+     */
+    onFileChange?: (event: FileChangeEvent) => Promise<void> | void;
+    /**
+     * Override the open-ended rubric returned by `critique_design`. Each
+     * string is a question the model is expected to answer in its next
+     * response about the current App.js + App.css. Defaults to
+     * {@link DEFAULT_DESIGN_CRITIQUE_RUBRIC} — six questions covering
+     * intent, hierarchy, distinctiveness, coherence, the weakest decision,
+     * and what to cut. Pass a custom rubric to steer the kind of critique
+     * the model performs (e.g. brand-specific concerns).
+     */
+    designCritiqueRubric?: readonly string[];
+    /**
+     * Cap on the number of distinct conversations whose per-conversation
+     * state (read-before-write tracking, patch-failure tallies, display
+     * cache) is retained in memory. When a new conversation pushes the
+     * count over the cap, the oldest entry is evicted (FIFO by first
+     * touch).
+     *
+     * Defaults to {@link DEFAULT_MAX_CONVERSATIONS}. The factory is
+     * typically long-lived in a server process, so this prevents the
+     * maps from growing unboundedly as conversations churn. An evicted
+     * conversation that comes back will need to call `read_file` again
+     * before `patch_file` — same as a cold start.
+     *
+     * Set to a positive integer; non-positive values fall back to the
+     * default.
+     */
+    maxConversations?: number;
+}
+/** Default cap for {@link CreateAppGenerationToolsOptions.maxConversations}. */
+declare const DEFAULT_MAX_CONVERSATIONS = 1000;
+/**
+ * Creates the suite of app generation tools (create_file, patch_file, delete_file,
+ * read_file, list_files, audit_design, critique_design, verify_app) backed by
+ * the provided storage adapter.
+ *
+ * Give the tool loop running these at least 8 tool rounds per turn
+ * (`maxToolRounds` in `runToolLoop` / `useChat`). The workflow the App Builder
+ * prompt mandates — re-orient, create, critique, patch, audit, patch, verify —
+ * takes 7–8 rounds on a substantial turn; a smaller budget silently starves
+ * the trailing `verify_app` call, so the host's runtime verification never runs.
+ */
+declare function createAppGenerationTools({ getConversationId, storage, logError, displayApp, verifyApp, onFileChange, designCritiqueRubric, maxConversations, }: CreateAppGenerationToolsOptions): ToolConfig[];
+
+/**
+ * Returns the {@link APP_BUILDER_PROMPT} constant. Thin function wrapper
+ * kept for callers that import a builder rather than a string constant
+ * (e.g. existing test setups). The prompt itself is now a static
+ * constant — there is no per-call assembly.
+ */
+declare function buildAppSystemPrompt(): string;
+/**
+ * Build a compact manifest of the conversation's current app files, for
+ * injection into each turn's context as a system message.
+ *
+ * This is the anchor of the *turn envelope* pattern, which keeps per-request
+ * token cost flat across arbitrarily long edit sessions. The files in
+ * storage — not the conversation — are the durable state: every prior change
+ * is already encoded in them, so old tool traffic adds cost without adding
+ * information. Hosts that resend tool history across turns pay per-turn cost
+ * that grows linearly with turn count (quadratic total); hosts using the
+ * envelope pay a cost bounded by app size, the same at request 5 and
+ * request 100.
+ *
+ * The envelope recipe, per change request:
+ *   1. system: `APP_BUILDER_PROMPT`
+ *   2. system: this manifest (rebuilt from storage each turn)
+ *   3. the last few user/assistant TEXT exchanges (drop all tool messages)
+ *   4. the new user request
+ *
+ * In-turn tool traffic stays within the turn; `maxToolRounds` bounds the
+ * rounds and `maxTurnTokens` (on `runToolLoop`) gives a hard ceiling. The
+ * model re-reads the files it wants to edit (`read_file` results are
+ * truncation-bounded), so per-turn cost is a function of app size and the
+ * text window — never of how many turns came before.
+ *
+ * The manifest deliberately lists paths and sizes only, no content: the
+ * read-before-write contract tracks what the model has actually seen via
+ * `read_file`/`create_file`, and inlined-but-unread content would invite
+ * patches against text the gate can't vouch for.
+ */
+declare function buildAppFileManifest(opts: {
+    storage: AppFileStorage;
+    conversationId: string;
+}): Promise<string>;
+
+/**
+ * Typed catalog of Google Fonts that SlideElement.fontFamily can reference.
+ *
+ * The model sees this library in the plan_deck tool result and can reach for
+ * any entry as a per-element `fontFamily` override — e.g. pair the deck's
+ * theme body (Inter) with a dramatic Abril Fatface hero title on the cover,
+ * or a short Caveat script accent under a pull quote.
+ *
+ * Invariants:
+ *  - Every font in FONT_PRESETS (heading or body) is also in FONT_LIBRARY.
+ *    Tests enforce this so the theme default pairings always resolve.
+ *  - The renderer loads only the fonts actually used by a given deck via
+ *    buildFontsUrl(), so per-element overrides are zero-cost when unused.
+ *
+ * Why typed data and not strings: as with layouts + palettes, a structured
+ * catalog lets us (a) validate fontFamily at write time (reject typos
+ * before they hit the renderer), (b) render a compact, role-grouped prompt
+ * block, and (c) derive the Google Fonts URL deterministically.
+ */
+type FontCategory = "display" | "serif-body" | "sans-body" | "mono" | "accent";
+interface FontSpec {
+    /** Exact Google Fonts family name — used verbatim as TextElement.fontFamily. */
+    name: string;
+    /** Role bucket — display (hero), body (reading), mono (chrome), accent (sparingly). */
+    category: FontCategory;
+    /** One-line feel/usage hint shown to the model next to the name. */
+    feel: string;
+    /**
+     * Semicolon-separated weight list for the Google Fonts CSS2 URL, e.g.
+     * "400;500;700". Empty string means the family is single-weight (no
+     * :wght@ segment in the slug).
+     */
+    weights: string;
+}
+declare const FONT_LIBRARY: FontSpec[];
+/** Look up a font by exact Google Fonts family name. Returns null if unknown. */
+declare function getFontByName(name: string): FontSpec | null;
+/** Validate a fontFamily value against the library. Returns true if accepted. */
+declare function isKnownFont(name: string): boolean;
+/**
+ * Build the Google Fonts CSS2 URL for a set of font families. Takes known
+ * library names (resolved with each font's own weight list) and optional
+ * extra slugs (for Material Symbols etc.). Returns a single URL with
+ * display=swap. Unknown names are silently skipped — callers that care
+ * should validate with `isKnownFont` first.
+ */
+declare function buildFontsUrl(names: string[], extraSlugs?: string[]): string;
+
+/**
+ * Anuma JSX AST — the in-memory model for slides and app mockups.
+ *
+ * Every artifact is a tree of `AnumaNode` values rooted at an `<Anuma.Deck>`
+ * (slides) or `<Anuma.Screen>` (apps — Stage 6+). There are no typed
+ * per-tag interfaces; the tree is tag-agnostic. Consumers walk the tree
+ * and dispatch on `node.tag`.
+ *
+ * Vocabulary (checked at parse time):
+ * - Containers: `<Anuma.Deck>`, `<Anuma.Slide>`, `<Anuma.Group>`.
+ * - Leaves: `<Anuma.Text>`, `<Anuma.Image>`, `<Anuma.Rect>`, `<Anuma.Circle>`,
+ *   `<Anuma.Line>`, `<Anuma.Icon>`.
+ *
+ * All coordinates are container-relative pixels — the slide canvas is
+ * 960×540 px, any child's `x`/`y`/`w`/`h` are pixels measured from the
+ * parent's top-left. Containers may opt into a flex layout with
+ * `layout="row" | "column"` plus `gap` / `padding` / `justify` / `align`;
+ * children inside a flex container skip `x`/`y` and flow instead.
+ *
+ * Numeric attrs are JSX expressions (`x={96}`), strings are quoted
+ * literals, booleans use `{true}`/`{false}` (or bare `hidden` for true).
+ * Dynamic expressions (`{someVar}`) are rejected in this version.
+ *
+ * @module tools/slides/jsx
+ */
+/** Scalar value an attribute can hold. */
+type AttrScalar$1 = string | number | boolean;
+/**
+ * An object-valued attribute — used primarily for `style={{}}`. Keys are
+ * CSS property names in camelCase (`fontSize`, `borderRadius`, …); values
+ * are scalars.
+ */
+type AttrObject$1 = Record<string, AttrScalar$1>;
+type AttrValue = AttrScalar$1 | AttrObject$1;
+type AnumaChild = AnumaNode | string;
+/**
+ * A node in the Anuma tree. `tag` is the local name after `Anuma.` (e.g.
+ * `"Text"`, `"Slide"`). Children are other nodes for containers, or a
+ * single string (the body text) for `<Anuma.Text>`.
+ */
+interface AnumaNode {
+    tag: string;
+    attrs: Record<string, AttrValue>;
+    children: AnumaChild[];
+}
+declare class AnumaJsxError extends Error {
+    readonly line?: number;
+    readonly column?: number;
+    constructor(message: string, loc?: {
+        line: number;
+        column: number;
+    } | null);
+}
+/**
+ * `Anuma.*` primitives — things that aren't native HTML concepts. Kept
+ * deliberately small; general content uses raw HTML.
+ *
+ * - Deck / Slide / Screen: layout containers with canvas semantics.
+ * - Text / Image / Icon / Group: preserved for slide templates and LLM
+ *   fluency (with theme-token bindings on Text). Safe to mix with HTML.
+ * - Rect / Circle / Line: SVG shape abstractions.
+ */
+declare const ANUMA_TAGS: readonly ["Deck", "Slide", "Screen", "Group", "Text", "Span", "Image", "Rect", "Circle", "Line", "Icon"];
+type KnownTag = (typeof ANUMA_TAGS)[number];
+/**
+ * Parse a JSX source string into an AnumaNode tree.
+ *
+ * `strict` mode (opt-in, defaults to `false`) enables checks that catch
+ * model-emitted JSX with the wrong convention before it lands in the deck:
+ * top-level visual-styling props on text elements (which the renderer
+ * silently ignores → invisible output). Stored decks load with strict off
+ * — any deck previously built before the strict check existed might carry
+ * non-conforming JSX, and we don't want a tightened validator to retro-
+ * actively break every tool call on that deck. Callers that parse
+ * model-submitted JSX (`add_slide`, `insert_slide`, `replace_slide`,
+ * `replace_element`, `insert_element`) pass `strict: true`.
+ */
+declare function parseJsx(source: string, options?: {
+    strict?: boolean;
+}): AnumaNode;
+/** True when a tag is an Anuma primitive (capitalized local name). */
+declare function isAnumaTag(tag: string): boolean;
+/** True when a tag is a plain HTML element from the allowlist. */
+declare function isHtmlTag(tag: string): boolean;
+interface SerializeOptions {
+    /** Indent per level (default two spaces). */
+    indent?: string;
+    /** Max single-line width before attrs break onto multiple lines (default 100). */
+    maxLineWidth?: number;
+}
+declare function serializeJsx(node: AnumaNode, options?: SerializeOptions): string;
+/** Return `attrs.id` as a string, or undefined. */
+declare function getId(node: AnumaNode): string | undefined;
+/**
+ * Walk the tree depth-first. Visitor sees `(node, parent)` — parent is
+ * `null` for the root. Return `false` from the visitor to skip descending
+ * into a node's children.
+ */
+declare function walk(root: AnumaNode, visitor: (node: AnumaNode, parent: AnumaNode | null) => void | false): void;
+/** Find the first node whose `attrs.id` matches `id`. */
+declare function findById(root: AnumaNode, id: string): AnumaNode | null;
+/** Find the parent of the node with matching id (null if root or missing). */
+declare function findParentOfId(root: AnumaNode, id: string): AnumaNode | null;
+/**
+ * Replace the first node with matching id in the tree. Mutates `root` in
+ * place. Returns true on success.
+ */
+declare function replaceById(root: AnumaNode, id: string, next: AnumaNode): boolean;
+/**
+ * Insert `node` into `parent.children`. If `afterId` is provided, the new
+ * node is inserted immediately after the matched sibling; otherwise it is
+ * appended to the end.
+ */
+declare function insertChild(parent: AnumaNode, node: AnumaNode, afterId?: string): void;
+/**
+ * Insert `node` immediately after the node with matching id anywhere in
+ * the tree. Returns true on success.
+ */
+declare function insertAfterId(root: AnumaNode, afterId: string, node: AnumaNode): boolean;
+/** Remove the node with matching id. Mutates `root`. Returns true on success. */
+declare function removeById(root: AnumaNode, id: string): boolean;
+/** Shallow-merge attrs onto `node`. Ignores prototype-pollution keys. */
+declare function updateAttrs(node: AnumaNode, patch: Record<string, unknown>): void;
+/** Read a string attr, returning undefined if absent or wrong type. */
+declare function getStringAttr(node: AnumaNode, name: string): string | undefined;
+/** Read a number attr, returning undefined if absent or wrong type. */
+declare function getNumberAttr(node: AnumaNode, name: string): number | undefined;
+
+/**
+ * Backwards-compat for slide decks generated before the JSX migration.
+ *
+ * Older decks were persisted as JSON with a typed `SlideDeck` shape:
+ *
+ *   {
+ *     version: 2,
+ *     theme: { fontPreset, colors: { background, slideBg, ... } },
+ *     slides: [{
+ *       id, background?,
+ *       elements: [{ kind: 'text'|'image'|'shape'|'icon', id, x, y, w, h, ... }],
+ *     }],
+ *   }
+ *
+ * Coordinates were percent-of-canvas (0..100). The new runtime stores
+ * decks as `<Anuma.Deck>` JSX with pixel coordinates on a 960×540 slide.
+ *
+ * This module converts legacy JSON → an `AnumaNode` tree so consumers
+ * can load old decks transparently and (if they want) re-serialise as
+ * JSX to migrate the persisted form forward.
+ */
+
+interface LegacyTheme {
+    fontPreset?: string;
+    colors?: {
+        background?: string;
+        slideBg?: string;
+        surfaceSecondary?: string;
+        textPrimary?: string;
+        textSecondary?: string;
+        textMuted?: string;
+        accent?: string;
+        card?: string;
+        border?: string;
+    };
+}
+interface LegacyBaseElement {
+    id?: string;
+    x?: number;
+    y?: number;
+    w?: number;
+    h?: number;
+    rotation?: number;
+}
+interface LegacyTextElement extends LegacyBaseElement {
+    kind: "text";
+    text?: string;
+    fontSize?: number;
+    fontRole?: "heading" | "body";
+    fontWeight?: number;
+    color?: string;
+    align?: "left" | "center" | "right";
+    lineHeight?: number;
+    letterSpacing?: number;
+    fontStyle?: "italic" | "normal";
+    textTransform?: "uppercase" | "none";
+    fontFamily?: string;
+}
+interface LegacyImageElement extends LegacyBaseElement {
+    kind: "image";
+    src?: string;
+    cornerRadius?: number;
+}
+interface LegacyShapeElement extends LegacyBaseElement {
+    kind: "shape";
+    shape?: "rect" | "circle" | "line";
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    cornerRadius?: number;
+}
+interface LegacyIconElement extends LegacyBaseElement {
+    kind: "icon";
+    name?: string;
+    color?: string;
+    fontSize?: number;
+}
+type LegacyElement = LegacyTextElement | LegacyImageElement | LegacyShapeElement | LegacyIconElement;
+interface LegacySlide {
+    id?: string;
+    background?: string;
+    elements?: LegacyElement[];
+}
+/** Legacy persisted deck shape. `version: 2` was the only version that ever shipped. */
+interface LegacyDeckJson {
+    version?: number;
+    theme?: LegacyTheme;
+    slides?: LegacySlide[];
+}
+/**
+ * Detect whether `raw` looks like a legacy JSON deck. Cheap structural
+ * check — used by callers that want to branch between `parseJsx` and
+ * the legacy converter without throwing on every JSX parse attempt.
+ *
+ * Accepts a string (JSON-encoded) or a parsed object.
+ */
+declare function isLegacyDeckJson(raw: unknown): raw is LegacyDeckJson;
+/**
+ * Convert a legacy JSON deck (string or already-parsed object) into a
+ * fresh `<Anuma.Deck>` AnumaNode tree. Returns null if the input
+ * doesn't parse as JSON or doesn't look like the legacy shape.
+ *
+ * Defensive defaults match the constants in the deleted
+ * `legacy-slide-types.ts`: undefined colors fall back to the original
+ * dark theme, undefined elements get sensible numeric defaults so
+ * partially-corrupted decks still render.
+ */
+declare function convertLegacyDeckJson(raw: unknown): AnumaNode | null;
+
+/**
+ * Slide deck tools for LLM-driven presentation generation.
+ *
+ * Provides plan_deck, add_slide, read_slides, and patch_slides tool
+ * configurations, along with the type system, coordinate helpers, font
+ * presets, and system prompt that drive the slide generation flow.
+ *
+ * Slide decks are stored as a JSX document (rooted at `<Anuma.Deck>`) in
+ * a file named `slides.jsx` via the shared `AppFileStorage` interface. The
+ * LLM initializes an empty deck with `plan_deck`, appends slides one at a
+ * time via `add_slide`, and applies incremental edits with `patch_slides`.
+ * All positions use container-relative pixels on a 960×540 slide canvas.
+ *
+ * When a `displaySlides` callback is supplied to `createSlideTools`, the
+ * deck-display UI interaction is emitted automatically from inside
+ * `plan_deck`, `add_slide`, and `patch_slides` — no separate display
+ * tool needed. The SDK tracks the interaction_id internally so per-slide
+ * appends update the same viewer in-place.
+ *
+ * @example
+ * ```typescript
+ * import { createSlideTools, buildSlideSystemPrompt } from "@anuma/sdk/tools";
+ *
+ * const slideTools = createSlideTools({
+ *   getConversationId,
+ *   storage,
+ *   displaySlides: async (args) => ({ ...args, displayType: "slides" }),
+ * });
+ *
+ * await sendMessage({
+ *   messages: [...],
+ *   tools: slideTools,
+ *   systemPrompt: buildSlideSystemPrompt(),
+ * });
+ * ```
+ *
+ * @module tools/slides
+ */
+
+declare const SLIDE_CANVAS_WIDTH = 960;
+declare const SLIDE_CANVAS_HEIGHT = 540;
+declare const THEME_ATTRS: readonly ["background", "slideBg", "surfaceSecondary", "textPrimary", "textSecondary", "textMuted", "accent", "card", "border"];
+type ThemeAttr = (typeof THEME_ATTRS)[number];
+interface FontPreset {
+    heading: string;
+    body: string;
+    /** Semicolon-separated weights, e.g. "400;500;700". */
+    weights: string;
+    /** Google Fonts family slug (for building a stylesheet URL). */
+    slug: string;
+}
+declare const FONT_PRESETS: Record<string, FontPreset>;
+/** Layout modes a container (Deck/Slide/Group) may opt into. */
+declare const LAYOUT_MODES: readonly ["absolute", "row", "column"];
+type LayoutMode = (typeof LAYOUT_MODES)[number];
+declare const READ_SLIDES_SCHEMA: {
+    readonly name: "read_slides";
+    readonly description: "Get the current slide deck. Defaults to a compact summary — slide ids, layout names, element ids per slide, and short text previews — typically 5-10× smaller than the full deck JSX. Use the summary to LOCATE the slide(s) you want to edit, then call patch_slides with the ids you found. When you need to see a slide's full JSX (e.g. to copy an existing style block, or to inspect element geometry before patching), pass slideIds: [\"s4\"] and read_slides will include the full JSX of just those slides alongside the summary. Do NOT request slideIds you don't need to read — every slide you list pays full token cost.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly slideIds: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Optional list of slide ids to return in full JSX form (alongside the summary). Use sparingly — only ask for slides you must inspect to write a patch. Omit entirely for the cheap summary-only response.";
+            };
+        };
+    };
+};
+declare const PATCH_SLIDES_SCHEMA: {
+    readonly name: "patch_slides";
+    readonly description: "Apply patch operations to an existing slide deck — change a slide's text, swap a layout, update the theme, or add and remove slides. Pair with read_slides when the user wants to change something in their deck.\n\nThe deck re-renders inline automatically after each patch; pass replaces_interaction_id from a previous add_slide/patch_slides result to update the same deck viewer in-place (otherwise a new viewer is created).\n\nOperations (set 'action' and the fields noted):\n- update_element: { slideId, elementId, attrs?, text? } — surgically patch ONE element WITHOUT rewriting it. Use 'attrs' for x/y/w/h moves and style tweaks (deep-merges; passing { style: { fontSize: 24 } } keeps every other style key intact). Use 'text' to rename or rewrite the element's text body — only the child string changes, every attr and style key is preserved exactly. Either field works alone or together. PREFER THIS for any edit that doesn't change the element's tag. Renames, recolors, moves, resizes all belong here. ~10× fewer output tokens than replace_element and you can't accidentally degrade the original styling.\n- replace_element: { slideId, elementId, jsx } — replace a matched element with a new content-element JSX fragment. Use ONLY when the element's TAG changes (e.g. swapping a <Anuma.Text> for an <Anuma.Image>). For text rename / styling changes / position changes use update_element instead — replace_element forces you to rewrite every attr from scratch and is the easiest place to silently lose design-system styling.\n- insert_element: { slideId, jsx, afterElementId? } — insert a new content-element JSX fragment. Appends to the end when afterElementId is omitted.\n- remove_element: { slideId, elementId }.\n- replace_slide: { slideId, jsx } — replace an entire <Anuma.Slide> with a new JSX fragment (root must be <Anuma.Slide>).\n- insert_slide: { jsx, layout, afterSlideId? } — insert a new <Anuma.Slide>. 'layout' is REQUIRED: pass the compound \"<composition>--<system>\" name pattern used by the existing slides. The executor validates the slide's slot content against the recipe and REJECTS the op if layout is missing — same contract as add_slide. To match the deck visually: call read_slides with slideIds:[an existing slide id] to copy its element structure, then keep the same \"--<system>\" suffix in the layout name. Appends to the end when afterSlideId is omitted.\n- remove_slide: { slideId }.\n- update_theme: { set: { fontPreset?, colors? } } — structured partial patch for theme metadata (no tree shape to rewrite).";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly replaces_interaction_id: {
+                readonly type: "string";
+                readonly description: "interaction_id from a previous add_slide or patch_slides result. Pass this to update the existing deck viewer in-place instead of creating a new one.";
+            };
+            readonly operations: {
+                readonly type: "array";
+                readonly description: "Array of operations to apply in order";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly action: {
+                            readonly type: "string";
+                            readonly enum: readonly ["update_element", "replace_element", "insert_element", "remove_element", "replace_slide", "insert_slide", "remove_slide", "update_theme"];
+                            readonly description: "The operation to perform";
+                        };
+                        readonly slideId: {
+                            readonly type: "string";
+                            readonly description: "Target slide id";
+                        };
+                        readonly elementId: {
+                            readonly type: "string";
+                            readonly description: "Target element id (for update_element, replace_element, and remove_element)";
+                        };
+                        readonly attrs: {
+                            readonly type: "object";
+                            readonly properties: {};
+                            readonly additionalProperties: true;
+                            readonly description: "For update_element: partial attrs to merge onto the existing element (e.g. { x: 100, y: 60 } moves it). When 'style' is an object, its keys merge with the existing style — other style keys are preserved.";
+                        };
+                        readonly text: {
+                            readonly type: "string";
+                            readonly description: "For update_element: replace the element's text body. Only the child string changes; every attr and style key is preserved. Use this for renames and copy-rewrites — replace_element rewrites the whole element from scratch and is the easiest way to drop the recipe's design-system styling. Pass alongside attrs to combine a text edit with a position/style nudge.";
+                        };
+                        readonly jsx: {
+                            readonly type: "string";
+                            readonly description: "JSX fragment: an <Anuma.Slide> for slide ops, or a single content element (<Anuma.Text>, <Anuma.Image>, <Anuma.Rect>, <Anuma.Circle>, <Anuma.Line>, <Anuma.Icon>, <Anuma.Group>) for element ops.";
+                        };
+                        readonly afterSlideId: {
+                            readonly type: "string";
+                            readonly description: "Insert new slide after this id. Omit to append at the end.";
+                        };
+                        readonly layout: {
+                            readonly type: "string";
+                            readonly description: "For insert_slide: the compound \"<composition>--<system>\" layout name (same form as add_slide). Always pass this so insert_slide can validate the new slide's slot structure against the recipe and reject off-template JSX.";
+                        };
+                        readonly afterElementId: {
+                            readonly type: "string";
+                            readonly description: "Insert new element after this id within the target slide. Omit to append at the end.";
+                        };
+                        readonly set: {
+                            readonly type: "object";
+                            readonly properties: {};
+                            readonly additionalProperties: true;
+                            readonly description: "For update_theme: partial theme fields to merge (fontPreset, colors).";
+                        };
+                    };
+                    readonly required: readonly ["action"];
+                };
+            };
+        };
+        readonly required: readonly ["operations"];
+    };
+};
+declare const PLAN_DECK_SCHEMA: {
+    readonly name: "plan_deck";
+    readonly description: "Create a new slide deck or presentation — use when the user asks to make, build, generate, or start a new slide deck, slideshow, PowerPoint, or Keynote presentation.\n\nCall this FIRST — once — to set up the theme, title, slide count, and layout pool. You pick:\n  - title: presentation title (shown above the deck in the UI)\n  - fontPreset: one of the font-preset keys\n  - paletteName: the register name from the palette table (e.g. \"warm editorial\", \"techno dark\")\n  - slideCount: how many slides the deck will have (commit to a concrete number)\n  - layouts: the subset of compound \"<composition>--<system>\" layout names from the LAYOUT CATALOG you intend to use across the deck. Each subsequent add_slide call must pick from this list, and every name must share the same \"--<system>\" suffix.\n  - accent: a 6-digit hex — the brand accent color for the deck. Set it to a hex that fits this deck's specific brand or topic. Skip ONLY for genuinely brand-ambiguous topics.\n\nThe result contains the full <Anuma.*> element recipes ONLY for the layouts you named in `layouts`, plus <Anuma.*> tag schemas, coordinate-system notes, and the palette hex values — everything you need for the add_slide calls that follow. Naming a tight subset keeps the context small and keeps the deck visually coherent.\n\nAfter plan_deck, call add_slide ONCE PER SLIDE, in order, passing the slide as a <Anuma.Slide> JSX fragment, until you've appended slideCount slides. Each add_slide call reports how many slides remain, so you can track progress.\n\nFor editing an existing deck (read_slides + patch_slides flow), do NOT call plan_deck.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly title: {
+                readonly type: "string";
+                readonly description: "Title of the presentation (shown above the deck in the UI).";
+            };
+            readonly fontPreset: {
+                readonly type: "string";
+                readonly description: "Font preset key (default, editorial, geometric, humanist, bold, elegant, clean, techno)";
+            };
+            readonly paletteName: {
+                readonly type: "string";
+                readonly description: "Palette register name from the CHOOSING A PALETTE table. Copy exactly (e.g. 'warm editorial').";
+            };
+            readonly slideCount: {
+                readonly type: "integer";
+                readonly minimum: 3;
+                readonly maximum: 19;
+                readonly description: "How many slides this deck will have. Pick a number between 3 and 19 based on the user's ask and the topic's depth. You will then call add_slide exactly this many times.";
+            };
+            readonly layouts: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly minItems: 1;
+                readonly description: "Compound layout names (from the LAYOUT CATALOG) you plan to use across this deck. Pick a small, well-matched subset — typically 3–8 layouts for a deck of 10 slides. Each name must be of the form '<composition>--<system>' (e.g. 'cover-split-portrait--editorial-warm'); every entry must share the same '--<system>' suffix so the deck stays in one visual identity. Each add_slide call must use a layout from this list; picking a layout outside it is rejected.";
+            };
+            readonly accent: {
+                readonly type: "string";
+                readonly pattern: "^#[0-9A-Fa-f]{6}$";
+                readonly description: "Brand accent color as a 6-digit hex. Almost every deck should set this. Pick a hex that fits this deck's specific brand or topic — what a designer would pick for THIS deck, not a generic industry default. Omit only when the topic is genuinely brand-ambiguous (internal status update, generic example).";
+            };
+        };
+        readonly required: readonly ["title", "fontPreset", "paletteName", "slideCount", "layouts"];
+    };
+};
+declare const ADD_SLIDE_SCHEMA: {
+    readonly name: "add_slide";
+    readonly description: "Append ONE slide to the deck as a <Anuma.Slide> JSX fragment. Call this once per slide after plan_deck, in order, until you've added slideCount slides. The deck re-renders inline after each add_slide so the viewer updates in-place.\n\nThe response reports: (a) how many slides remain to reach the planned slideCount, (b) which layouts you've used so far and how many times.\n\nBATCHING: Prefer to emit ALL add_slide calls in a single assistant turn (as parallel tool calls) once plan_deck has returned. The deck plan already tells you the layouts and slideCount, so you can design every slide up-front and call add_slide N times in one turn. This cuts the number of LLM round-trips from N+1 to 2. Parallel calls don't see each other's per-call layout-usage feedback inside the same turn — that's fine because the layout subset is fixed at plan_deck time. Only fall back to serial calls if you genuinely need to react to each result before designing the next slide.\n\nExample slideJsx:\n  <Anuma.Slide id=\"cover\">\n    <Anuma.Text id=\"title\" x={96} y={216} w={768} h={108} fontSize={58} fontRole=\"heading\" fontWeight={700} color=\"textPrimary\" align=\"center\">Welcome</Anuma.Text>\n  </Anuma.Slide>\n\nEach composition recipe already defines its own chrome (header/footer slots) — copy the recipe verbatim and fill the role-tagged slots; do not invent a separate \"header pattern\".";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly slideIndex: {
+                readonly type: "integer";
+                readonly description: "1-based position of this slide in the deck (1 = cover, slideCount = last). REQUIRED when emitting multiple add_slide calls in parallel in one turn (the recommended pattern) — without it the parallel calls land in non-deterministic order. Resubmitting with the same slideIndex overwrites the slide at that position; omit only for serial single-slide flows.";
+                readonly minimum: 1;
+            };
+            readonly layout: {
+                readonly type: "string";
+                readonly description: "Name of the layout you're using for this slide — must be an exact compound '<composition>--<system>' name from the LAYOUT CATALOG (e.g. 'cover-split-portrait--editorial-warm'). Rejected with a helpful error if unknown.";
+            };
+            readonly slideJsx: {
+                readonly type: "string";
+                readonly description: "JSX fragment whose root is <Anuma.Slide id=\"...\">…</Anuma.Slide>. Numeric attributes use JSX expressions ({10}), string attrs are quoted.";
+            };
+        };
+        readonly required: readonly ["layout", "slideJsx"];
+    };
+};
+/** Canonical storage path for the slide deck, relative to a conversation. */
+declare const SLIDES_FILE_PATH = "slides.jsx";
+interface CreateSlideToolsOptions {
+    /** Returns the current conversation ID (may be null before first message). */
+    getConversationId: () => string | null;
+    /** Storage backend for slides.jsx — only getFile/putFile are required. */
+    storage: Pick<AppFileStorage, "getFile" | "putFile">;
+    /** Optional error logger. Defaults to a no-op. */
+    logError?: (message: string, error?: Error) => void;
+    /**
+     * Set to true when the host has bound an image-generation tool (e.g.
+     * AnumaMediaMCP-anuma_create_image) to the same loop as these slide
+     * tools. plan_deck's recipe text adapts: when false (the default),
+     * the recipe tells the model the only valid path is attached:N or
+     * removing the element; when true, anuma_create_image is advertised as
+     * an option. Avoids leaking a tool name the model can't actually call.
+     */
+    hasImageGenerator?: boolean;
+    /**
+     * Host-supplied hook that emits a deck-display UI interaction. Called
+     * automatically from inside `plan_deck`, `add_slide`, and `patch_slides`;
+     * its return value is merged into the tool result so the model (and the
+     * chat UI) see the `interaction_id`. Receives `{ title, replaces_interaction_id }`.
+     *
+     * The SDK tracks the interaction_id internally per conversation so
+     * per-slide appends update the same viewer — the model does not need
+     * to thread the id through its tool arguments.
+     *
+     * Omit in headless/test environments that don't need a UI anchor — in
+     * that case the tool results just omit `interaction_id`.
+     */
+    displaySlides?: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+/**
+ * Create the slide deck tool suite: `plan_deck`, `add_slide`, `read_slides`,
+ * and `patch_slides`.
+ *
+ * New decks flow: plan_deck (once) → add_slide (once per slide, in order).
+ * Existing deck edits: read_slides → patch_slides.
+ *
+ * When `displaySlides` is provided, `plan_deck`, `add_slide`, and
+ * `patch_slides` all emit the deck-display UI interaction as part of
+ * their result. No standalone `display_slides` tool — the write and the
+ * display anchor are a single step, and the SDK tracks the interaction
+ * id per conversation so per-slide appends update the same viewer
+ * in-place.
+ *
+ * Backed by the provided storage adapter. No dependency on the
+ * app-generation `create_file` tool — `plan_deck` initializes slides.jsx
+ * and `add_slide` appends to it directly.
+ */
+/**
+ * Return shape of {@link createSlideTools}: the tool array plus a
+ * `clearConversation(id)` method to release per-conversation state. Call
+ * the method when a conversation ends (session close, timeout, etc.) —
+ * otherwise `deckStateByConv` and `writeLockByConv` grow unbounded over
+ * the server process lifetime.
+ *
+ * The return is still array-iterable, so existing `tools: slideTools`
+ * spreads keep working without destructuring.
+ */
+type SlideToolSet = ToolConfig[] & {
+    clearConversation: (conversationId: string) => void;
+};
+declare function createSlideTools({ getConversationId, storage, logError, displaySlides, hasImageGenerator, }: CreateSlideToolsOptions): SlideToolSet;
+/**
+ * Build the slide mode system prompt — slim initialize + per-slide flow.
+ *
+ * Instructs the LLM to call plan_deck once (picks title + palette +
+ * fontPreset, initializes an empty slides.jsx, returns the full layout
+ * recipes + element-type schemas + palette hex values),
+ * then call add_slide once per slide to append. Per-slide rounds keep
+ * each tool-call stream small so slow / reasoning-heavy models can finish
+ * within portal per-provider timeout ceilings.
+ */
+interface BuildSlideSystemPromptOptions {
+    /**
+     * Set to true when the host has bound an image-generation tool (e.g.
+     * AnumaMediaMCP-anuma_create_image) to the same loop. The IMAGES
+     * section adapts: when false (the default) it tells the model the
+     * only valid path is attached:N or removing the element; when true,
+     * anuma_create_image is advertised as an option. Mirrors the same flag
+     * on `CreateSlideToolsOptions` — host should pass the same value to both.
+     */
+    hasImageGenerator?: boolean;
+}
+declare function buildSlideSystemPrompt(options?: BuildSlideSystemPromptOptions): string;
+
+/**
+ * Document Builder persona prompt — canonical source for the SDK.
+ *
+ * Mirrors {@link APP_BUILDER_PROMPT}: the prompt lives in code, the SDK owns
+ * it, and it is attached to the `documents` tool set's `systemPrompt` so it
+ * rides in with semantic tool selection (and is otherwise absent, keeping
+ * borderline turns unbiased).
+ *
+ * Lives in its own dependency-free module (no `@babel/parser` etc.) so the
+ * lib/server layer can import the string without pulling in the document
+ * runtime — see `BUILT_IN_TOOL_SETS` in `src/lib/tools/serverTools.ts`.
+ *
+ * Pair with the tools returned by {@link createDocumentTools} —
+ * `create_document`, `read_document`, `patch_document`.
+ *
+ * @module tools/document/documentBuilderPrompt
+ */
+declare const DOCUMENT_BUILDER_PROMPT = "Document tools (create_document, read_document, patch_document) are available this turn, but they are OPTIONAL \u2014 having them does not mean you should produce a document.\n\nUse them ONLY when the user explicitly asks you to draft, write, compose, or generate a document \u2014 a contract, agreement, NDA, letter, cover letter, memo, essay, report, brief, proposal, or resume \u2014 e.g. \"draft me a service agreement\", \"write a cover letter for this job\", \"make a one-page memo about X\". A bare topic, a question, a request for an explanation, or a request for a slide deck or an interactive app is NOT a document instruction: respond normally and do not call these tools. When it's unclear whether the user wants a finished document, ask instead.\n\nWhen you DO author a document, the document body goes entirely into the tool \u2014 NEVER write the document text as chat prose. The tool renders your source to a real, paginated PDF and attaches it to your reply automatically. AFTER the tool returns, briefly confirm in ONE short sentence what you made (e.g. \"Drafted a cover letter for the product manager role \u2014 see the attached PDF.\"). Do not restate the document's contents.\n\nAUTHORING \u2014 write the \"source\" as a single @react-pdf/renderer JSX expression (this is react-pdf, NOT HTML and NOT a slide deck):\n- Root is exactly one <Document> with at least one <Page>. Its only children are <Page> elements. Add more <Page> elements for longer documents \u2014 react-pdf also paginates overflow automatically.\n- Inside a <Page>: use <View> as flex containers and <Text> for ALL text. Raw text is only allowed inside <Text> (and <Link>); a <View> or <Page> may not contain bare text.\n- <Text> may nest <Text>, <Link>, or <Note> for inline styling, hyperlinks, and (rarely) a PDF comment annotation. A <Link> src must be an ordinary web link \u2014 http(s), mailto, tel, or a relative/anchor link; javascript:/data:/file: links are rejected. <Image> is self-closing and its src MUST be an inline \"data:\" URI \u2014 remote image URLs are rejected for privacy. Vector primitives (<Rect>/<Circle>/<Path>/etc.) must live inside an <Svg>.\n- Styling is react-pdf style objects only: style={{ marginTop: 12, fontSize: 11, fontFamily: \"Times-Roman\", flexDirection: \"column\" }}. Flexbox only \u2014 there is NO CSS grid, float, or box-shadow. Use camelCase react-pdf keys (margin/padding, flex*, width/height, color/backgroundColor, border*, text*, etc.).\n- fontFamily must be a built-in PDF font: Helvetica, Times-Roman, or Courier (with -Bold / -Oblique / -Italic / -BoldOblique variants), or Symbol / ZapfDingbats. Custom fonts are not supported.\n- LITERAL VALUES ONLY: no variables, no JS expressions, no .map(), no event handlers (onClick, \u2026), no spreads. Every attribute is a literal string, number, boolean, or a style object of literals.\n\nA minimal example:\n\n<Document>\n  <Page size=\"A4\" style={{ paddingVertical: 56, paddingHorizontal: 64, fontFamily: \"Times-Roman\", fontSize: 11, lineHeight: 1.5 }}>\n    <Text style={{ fontSize: 18, fontFamily: \"Times-Bold\", marginBottom: 16, textAlign: \"center\" }}>MUTUAL NON-DISCLOSURE AGREEMENT</Text>\n    <Text style={{ marginBottom: 10 }}>This Mutual Non-Disclosure Agreement (the \"Agreement\") is entered into as of the date of last signature below.</Text>\n    <View style={{ marginTop: 14 }}>\n      <Text style={{ fontFamily: \"Times-Bold\", marginBottom: 4 }}>1. Confidential Information</Text>\n      <Text>Each party may disclose certain confidential and proprietary information to the other party.</Text>\n    </View>\n  </Page>\n</Document>\n\nWORKFLOW:\n1. To create or fully restructure a document, call create_document with the complete source.\n2. To revise an existing document, call read_document first (its output is line-numbered \"42: <text>\" \u2014 the prefix is display-only, never copy it into a \"find\"), then patch_document with small find/replace edits. Each \"find\" must match exactly one location; add 2-3 lines of surrounding context if needed. Prefer patching over rewriting.\n3. To attach several separate documents in one reply, call create_document multiple times with distinct documentId slugs (e.g. \"nda\", \"cover-letter\"). Each renders to its own PDF.\n4. If a tool reports a DSL error (with line:col) or a render failure, fix the source and retry \u2014 do not give up or fall back to writing the document as chat text.";
+/**
+ * The Document Builder system prompt. A function (not just the constant) to
+ * match {@link buildAppSystemPrompt} and leave room for future
+ * host-configurable variants.
+ *
+ * @category Document Tools
+ */
+declare function buildDocumentSystemPrompt(): string;
+
+/**
+ * Document DSL — the validated, literal-only `@react-pdf/renderer` subset the
+ * model authors when drafting a document artifact (contract, letter, memo,
+ * essay, report, …).
+ *
+ * The model emits a single JSX expression rooted at `<Document>`, using the
+ * react-pdf primitive vocabulary (`<Page>`, `<View>`, `<Text>`, `<Image>`, …)
+ * plus inline `style={{}}` objects. We parse it into a tag-agnostic
+ * {@link DocNode} tree with `@babel/parser` and enforce a strict allowlist:
+ * only react-pdf render tags, only react-pdf style keys, only literal scalar
+ * attribute values. No executable code ever runs — the web renderer maps the
+ * validated tree onto real react-pdf components (see the web `render.tsx`),
+ * which is what makes this safe on the main thread.
+ *
+ * This is a deliberate sibling of `tools/slides/jsx.ts`: same parse strategy
+ * and literal-only attribute discipline, but the tag reader accepts the
+ * react-pdf bare-capitalized vocabulary (`<Document>`, `<Page>`) instead of
+ * the slides `<Anuma.*>` namespace, and the allowlists/structural rules are
+ * document/react-pdf specific.
+ *
+ * @module tools/document/dsl
+ */
+/** Scalar value an attribute can hold. */
+type AttrScalar = string | number | boolean;
+/** An object-valued attribute — used primarily for `style={{}}`. */
+type AttrObject = Record<string, AttrScalar>;
+/** @category Document DSL */
+type DocAttrValue = AttrScalar | AttrObject;
+/** @category Document DSL */
+type DocChild = DocNode | string;
+/**
+ * A node in the document tree. `tag` is the react-pdf component name (e.g.
+ * `"Document"`, `"Page"`, `"Text"`). Children are nested nodes for containers,
+ * or strings (the displayed text) for text-bearing tags.
+ *
+ * @category Document DSL
+ */
+interface DocNode {
+    tag: string;
+    attrs: Record<string, DocAttrValue>;
+    children: DocChild[];
+}
+/**
+ * Thrown when the document DSL violates a parse or structural rule. Carries
+ * the source line/column when available so the model can self-correct.
+ *
+ * @category Document DSL
+ */
+declare class DocDslError extends Error {
+    readonly line?: number;
+    readonly column?: number;
+    constructor(message: string, loc?: {
+        line: number;
+        column: number;
+    } | null);
+}
+/**
+ * Every `@react-pdf/renderer` component the document DSL permits. Bare
+ * capitalized identifiers (unlike slides, which namespaces under `Anuma.*`).
+ *
+ * Deliberately excluded: `Font` (imperative `Font.register` API, not a render
+ * tag) and `Canvas` (requires a `paint` function prop, which the literal-only
+ * DSL cannot express).
+ */
+declare const PDF_TAGS: readonly ["Document", "Page", "View", "Text", "Link", "Note", "Image", "Svg", "G", "Line", "Rect", "Circle", "Ellipse", "Polygon", "Polyline", "Path", "Tspan", "Defs", "ClipPath", "Stop", "LinearGradient", "RadialGradient"];
+/** @category Document DSL */
+type PdfTag = (typeof PDF_TAGS)[number];
+/**
+ * Parse and validate a document DSL source string into a {@link DocNode} tree.
+ *
+ * Throws {@link DocDslError} on any violation: invalid JSX, a non-`<Document>`
+ * root, an unknown tag, a forbidden/dynamic attribute, an unknown style key,
+ * or a structural rule break (e.g. `<Document>` containing a non-`<Page>`,
+ * raw text outside `<Text>`, or a leaf tag with children).
+ *
+ * @category Document DSL
+ */
+declare function parseDocumentDsl(source: string): DocNode;
+/** True iff `tag` is a permitted react-pdf document tag. */
+declare function isPdfTag(tag: string): boolean;
+/** The full list of permitted react-pdf document tags (for prompts/tests). */
+declare function pdfTags(): readonly string[];
+/** The full set of permitted react-pdf style keys (for prompts/tests). */
+declare function pdfStyleKeys(): readonly string[];
+
+/**
+ * Document generation tools — `create_document`, `read_document`,
+ * `patch_document`.
+ *
+ * The model authors a document as a single `@react-pdf/renderer` DSL source
+ * file (see {@link module:tools/document/dsl}). Each document is stored as one
+ * file per conversation in the shared {@link AppFileStorage}; the host's
+ * `displayDocument` callback renders it to a vector PDF and attaches it to the
+ * assistant message (the web app does this on the main thread — see the web
+ * `useDocumentPdfExport`). The callback is mandatory: the PDF is the tools'
+ * entire user-visible output, so hosts that cannot render (e.g. React Native,
+ * which has no `@react-pdf/renderer`) get no document tools at all rather
+ * than a tool that silently claims success (#659). To revise, the model reads
+ * the current source and applies find/replace patches.
+ *
+ * This is a single-file sibling of {@link createAppGenerationTools}: it reuses
+ * that module's pure patch engine (`applyPatches`, `snippetForFailedPatch`,
+ * `snippetAroundLine`) and the read-before-write contract, but validates
+ * content with {@link parseDocumentDsl} (react-pdf
+ * DSL) rather than the JS/JSX syntax checker, and has no multi-file batch.
+ *
+ * Multiple distinct documents per conversation are supported via an optional
+ * `documentId` (default `"document"`), each backed by its own `<id>.jsx` file
+ * and rendered to its own PDF chip — so a single response can attach one or
+ * several documents.
+ *
+ * @module tools/document
+ */
+
+/** Default document identifier when the model omits `documentId`. */
+declare const DEFAULT_DOCUMENT_ID = "document";
+/** Tool names this module owns — for host filtering / set membership. */
+declare const DOCUMENT_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Map a `documentId` to its storage path. The id is run through
+ * {@link normalizeDocumentId}, which slug-validates it (throwing on anything
+ * outside `[a-z0-9][a-z0-9-]{0,63}`), so the returned storage key stays
+ * filesystem-safe and cannot traverse outside the conversation directory —
+ * including when a host calls this public helper directly on untrusted input.
+ */
+declare function documentPath(documentId: string): string;
+declare const CREATE_DOCUMENT_SCHEMA: {
+    readonly name: "create_document";
+    readonly description: "Author a formatted, paginated document the user can read and download as a PDF — a contract, agreement, letter, cover letter, memo, essay, report, brief, proposal, resume, or similar. Use this whenever the user asks to draft, write, compose, or generate a document. The document renders to a real PDF and attaches to your reply automatically — never write the document body as chat prose.\n\nThis is NOT for slide decks/presentations (use the deck tools) or interactive apps (use the app tools).\n\nWrite the \"source\" as a single @react-pdf/renderer JSX expression: a <Document> root containing one or more <Page> elements, with <View>/<Text> for layout and prose, using react-pdf style objects (flexbox only — no CSS grid/float). To revise a document later, prefer read_document + patch_document over rewriting the whole thing with create_document.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly title: {
+                readonly type: "string";
+                readonly description: "Short human-readable document title (used for the PDF filename / attachment label).";
+            };
+            readonly source: {
+                readonly type: "string";
+                readonly description: "The complete @react-pdf/renderer DSL: one <Document> root with <Page> children. Literal values only — no variables, expressions, or event handlers.";
+            };
+            readonly documentId: {
+                readonly type: "string";
+                readonly description: "Optional slug identifying which document to operate on (e.g. \"nda\", \"offer-letter\"). Omit for the default document. Use distinct ids to attach several separate documents in one response.";
+            };
+        };
+        readonly required: readonly ["source"];
+    };
+};
+declare const READ_DOCUMENT_SCHEMA: {
+    readonly name: "read_document";
+    readonly description: "Read the current document source (the @react-pdf/renderer DSL) with \"<n>: \" line-number prefixes, to plan an edit. Required before patch_document. Do not copy the line-number prefixes into a patch \"find\" string.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly documentId: {
+                readonly type: "string";
+                readonly description: "Optional slug identifying which document to operate on (e.g. \"nda\", \"offer-letter\"). Omit for the default document. Use distinct ids to attach several separate documents in one response.";
+            };
+        };
+        readonly required: readonly [];
+    };
+};
+declare const PATCH_DOCUMENT_SCHEMA: {
+    readonly name: "patch_document";
+    readonly description: "Edit, revise, amend, or reword an existing document via find-and-replace on its source, then re-render the PDF. Use this for incremental changes (\"make it more formal\", \"add a confidentiality clause\") instead of rewriting with create_document.\n\nREQUIRED: call read_document for this document earlier in the conversation first — the tool refuses otherwise.\n\nPass a \"patches\" array of {find, replace}. Each \"find\" must match the source exactly, character for character, at EXACTLY ONE location (add 2-3 lines of surrounding context if it would otherwise be ambiguous), and must NOT include the \"<n>: \" line-number prefix from read_document.";
+    readonly arguments: {
+        readonly type: "object";
+        readonly properties: {
+            readonly patches: {
+                readonly type: "array";
+                readonly description: "Array of find/replace operations applied atomically.";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly find: {
+                            readonly type: "string";
+                            readonly description: "Exact string to find in the document source";
+                        };
+                        readonly replace: {
+                            readonly type: "string";
+                            readonly description: "Replacement string";
+                        };
+                    };
+                    readonly required: readonly ["find", "replace"];
+                };
+            };
+            readonly documentId: {
+                readonly type: "string";
+                readonly description: "Optional slug identifying which document to operate on (e.g. \"nda\", \"offer-letter\"). Omit for the default document. Use distinct ids to attach several separate documents in one response.";
+            };
+        };
+        readonly required: readonly ["patches"];
+    };
+};
+interface CreateDocumentToolsOptions {
+    /** Returns the current conversation ID (may be null before the first message). */
+    getConversationId: () => string | null;
+    /** Storage backend for the document source file. */
+    storage: Pick<AppFileStorage, "getFile" | "putFile">;
+    /** Optional error logger. Falls back to console.error. */
+    logError?: (message: string, error?: Error) => void;
+    /**
+     * Host callback that renders the just-written document to a PDF and
+     * attaches it to the assistant message (web: render on the main thread via
+     * `@react-pdf/renderer`, write to encrypted OPFS, append the media id to the
+     * message's `fileIds`). Invoked automatically after every successful
+     * `create_document` / `patch_document` — the model never calls a separate
+     * display tool.
+     *
+     * REQUIRED: the rendered PDF is the tools' entire deliverable, so a host
+     * that cannot render must not offer them. Without this callback the tools
+     * used to persist the source and report `success: true` anyway — the model
+     * told the user the PDF was attached, nothing rendered, no error surfaced,
+     * and the turn was still billed (#659). If a plain-JS host omits it at
+     * runtime, {@link createDocumentTools} returns no tools (and logs) so the
+     * model honestly reports it cannot produce a PDF instead.
+     *
+     * Receives `{ documentId, path, title? }`. Unlike `displayApp`/`displaySlides`,
+     * a THROW here is NOT swallowed: a render failure becomes a tool-error result
+     * so the model can fix an unrenderable document and retry. Any object it
+     * returns is spread into the tool result to ADD fields (e.g. a media id);
+     * the tool's own status fields (`success`, `documentId`, `applied`) always
+     * take precedence and cannot be overwritten by the callback.
+     */
+    displayDocument: (args: Record<string, unknown>) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+    /** Cap on per-conversation in-memory state (read-tracking, patch tallies). */
+    maxConversations?: number;
+}
+/** Default cap for {@link CreateDocumentToolsOptions.maxConversations}. */
+declare const DEFAULT_MAX_DOCUMENT_CONVERSATIONS = 1000;
+/**
+ * Create the document tool set (`create_document`, `read_document`,
+ * `patch_document`) backed by the provided storage adapter and host render
+ * callback. The write tools do NOT skip continuation: their results are small
+ * (`{ success, documentId }` — never the source), so feeding them back is cheap
+ * and lets the model add a brief confirmation ("Drafted your cover letter — see
+ * the attached PDF.") after the chip renders. Render/validation failures also
+ * feed back as tool errors, so the model can recover.
+ *
+ * Returns an EMPTY array (and logs via `logError`) if `displayDocument` is
+ * missing at runtime: with no renderer there is nothing a user can ever see
+ * or download, so offering the tools would only let the model burn a billed
+ * turn on a `create_document` call that reports `success: true` while
+ * producing nothing (#659). With no tools offered, the model tells the user
+ * it cannot produce a PDF on this platform — before any document turn is
+ * billed.
+ *
+ * @category Document Tools
+ */
+declare function createDocumentTools({ getConversationId, storage, logError, displayDocument, maxConversations, }: CreateDocumentToolsOptions): ToolConfig[];
+
+export { ADD_SLIDE_SCHEMA, APP_BUILDER_PROMPT, APP_COMPLETE_CONNECT_ACK_TYPE, APP_COMPLETE_CONNECT_TYPE, APP_COMPLETE_DEFAULT_TIMEOUT_MS, APP_COMPLETE_IFRAME_SHIM_SCRIPT, APP_COMPLETE_REQUEST_TYPE, APP_COMPLETE_RESPONSE_TYPE, APP_COMPLETE_STUB_SCRIPT, APP_FILE_TOOL_NAMES, APP_PREVIEW_BASELINE_CSS, AUDIT_DESIGN_SCHEMA, type AnchorMatch, type AnumaChild, AnumaJsxError, type AnumaNode, type AppCompleteBridge, type AppCompleteBridgeOptions, type AppFileRecord, type AppFileStorage, type AttrValue, type AuditIssue, type AuditIssueType, type AuditResult, type AuditSeverity, type AuditTokens, type BuildSlideSystemPromptOptions, CONNECTOR_ERROR_MARKER, CREATE_DOCUMENT_SCHEMA, CREATE_FILE_SCHEMA, CRITIQUE_DESIGN_SCHEMA, type CalendarEvent, type ChartDataPoint, type ChoiceOption, type ConnectorErrorCode, type ConnectorMintError, type ConnectorMintResult, type ConnectorTokenGetterOpts, type ConnectorTokenSource, type CreateAppGenerationToolsOptions, type CreateDocumentToolsOptions, type CreateEventArgs, type CreateFileArgs, type CreateSlideToolsOptions, type CreateUIToolsOptions, type CreateWeatherToolOptions, DEFAULT_DESIGN_CRITIQUE_RUBRIC, DEFAULT_DOCUMENT_ID, DEFAULT_MAX_CONVERSATIONS, DEFAULT_MAX_DOCUMENT_CONVERSATIONS, DELETE_FILE_SCHEMA, DOCUMENT_BUILDER_PROMPT, DOCUMENT_TOOL_NAMES, type DisplayChartResult, type DisplayConnectorResult, type DisplayPhoneCallOfferResult, type DisplayToolConfig, type DisplayToolMigrations, type DisplayWeatherResult, type DocAttrValue, type DocChild, DocDslError, type DocNode, type DriveFile, type DropboxRequestAccess, type DropboxTokenGetter, type ExportAppOptions, FONT_LIBRARY, FONT_PRESETS, type FileChangeEvent, type FileSnippet, type FontCategory, type FontPreset, type FontSpec, type ForecastDay, type FormField, type FormFieldOption, type FormFieldType, type GetFileContentArgs, type GmailGetMessageArgs, type GmailMessageDetail, type GmailMessageSummary, type GmailRequestAccess, type GmailSearchArgs, type GmailSendMessageArgs, type GmailTokenGetter, type InteractiveToolConfig, type KnownTag, LAYOUT_MODES, LIST_FILES_SCHEMA, type LayoutMode, type LegacyDeckJson, type ListEventsArgs, type ListRecentFilesArgs, MapFileStorage, type NotionCreatePagesArgs, type NotionFetchArgs, type NotionMovePagesArgs, type NotionSearchArgs, type NotionUpdatePageArgs, PATCH_DOCUMENT_SCHEMA, PATCH_FILE_SCHEMA, PATCH_SLIDES_SCHEMA, PLAN_DECK_SCHEMA, type PatchFailure, type PatchFailureReason, type PdfTag, READ_DOCUMENT_SCHEMA, READ_FILE_SCHEMA, READ_SLIDES_SCHEMA, RUNTIME_ERROR_OVERLAY_SCRIPT, SLIDES_FILE_PATH, SLIDE_CANVAS_HEIGHT, SLIDE_CANVAS_WIDTH, type SearchFilesArgs, type SlackGetChannelHistoryArgs, type SlackGetThreadRepliesArgs, type SlackListChannelsArgs, type SlackListUsersArgs, type SlackPostMessageArgs, type SlackProxyCaller, type SlackSearchMessagesArgs, type SlideToolSet, THEME_ATTRS, type ThemeAttr, type ToolConfig, type ToolExecutionErrorType, type ToolExecutionResult, type UIInteractionContext, type UpdateEventArgs, type UpdateFileArgs, VERIFY_APP_SCHEMA, type VerifyAppResult, type XGetMeArgs, type XGetMyPostsArgs, type XProxyCaller, applyPatches, auditDesign, buildAppFileManifest, buildAppSystemPrompt, buildConnectorErrorResult, buildDocumentSystemPrompt, buildFontsUrl, buildSlideSystemPrompt, callNotionMCPTool, connectorMintErrorToToolResult, convertLegacyDeckJson, createAppCompleteBridge, createAppGenerationTools, createChartTool, createChatTools, createChoiceTool, createConnectorOfferTool, createConnectorTokenGetter, createDisplayTool, createDocumentTools, createDriveTools, createDropboxTools, createFormTool, createGitHubTools, createGmailTools, createGoogleCalendarCreateEventTool, createGoogleCalendarTool, createGoogleCalendarUpdateEventTool, createGoogleDriveCreateFileTool, createGoogleDriveGetContentTool, createGoogleDriveListRecentTool, createGoogleDriveSearchTool, createGoogleDriveUpdateFileTool, createInteractiveTool, createNotionCreateCommentTool, createNotionCreateDatabaseTool, createNotionCreatePagesTool, createNotionDuplicatePageTool, createNotionFetchTool, createNotionGetCommentsTool, createNotionGetTeamsTool, createNotionGetUsersTool, createNotionMovePagesTool, createNotionSearchTool, createNotionTools, createNotionUpdateDataSourceTool, createNotionUpdatePageTool, createPhoneCallOfferTool, createSlackTools, createSlideTools, createWeatherTool, createXTools, documentPath, exportAppToHtml, findById, findParentOfId, getFontByName, getId, getMCPEndpoints, getNumberAttr, getStringAttr, insertAfterId, insertChild, installAppCompleteIframeShim, isAnumaTag, isHtmlTag, isKnownFont, isLegacyDeckJson, isPdfTag, migrateDisplayResult, normalizePath, parseDocumentDsl, parseJsx, pdfStyleKeys, pdfTags, removeById, replaceById, serializeJsx, truncateContent, updateAttrs, walk };