@blinkk/root-cms 3.0.2 → 3.0.3

package/dist/cli/docs.d.ts

@@ -0,0 +1,49 @@
+export interface DocsGetOptions {
+    /** Doc mode: "draft" or "published". */
+    mode?: string;
+    /** Whether to output raw firestore data. */
+    raw?: boolean;
+}
+export interface DocsSetOptions {
+    /** Doc mode: "draft" or "published". */
+    mode?: string;
+}
+export interface DocsDownloadOptions {
+    /** Doc mode: "draft" or "published". */
+    mode?: string;
+}
+export interface DocsUploadOptions {
+    /** Doc mode: "draft" or "published". */
+    mode?: string;
+}
+/**
+ * Fetches a single doc and outputs it as JSON.
+ * If an output path is provided, writes to a file. Otherwise, writes to stdout.
+ *
+ * Usage:
+ *   root-cms docs.get <docId> [outputPath] [--mode draft] [--raw]
+ */
+export declare function docsGet(docId: string, outputPath: string | undefined, options: DocsGetOptions): Promise<void>;
+/**
+ * Sets a single doc's data from a JSON file or stdin.
+ * If a filepath is provided, reads from the file. Otherwise, reads from stdin.
+ *
+ * Usage:
+ *   root-cms docs.set <docId> [filepath] [--mode draft]
+ *   cat data.json | root-cms docs.set Pages/home
+ */
+export declare function docsSet(docId: string, filepath: string | undefined, options: DocsSetOptions): Promise<void>;
+/**
+ * Downloads all docs in a collection to a local directory.
+ *
+ * Usage:
+ *   root-cms docs.download <collection> [outputDir] [--mode draft]
+ */
+export declare function docsDownload(collectionId: string, outputDirArg: string | undefined, options: DocsDownloadOptions): Promise<void>;
+/**
+ * Uploads docs from a local directory to a collection.
+ *
+ * Usage:
+ *   root-cms docs.upload <collection> <dir> [--mode draft]
+ */
+export declare function docsUpload(collectionId: string, dir: string, options: DocsUploadOptions): Promise<void>;

package/dist/cli/export.d.ts

@@ -0,0 +1,11 @@
+export interface ExportOptions {
+    /** Filter to specific content. */
+    filter?: string;
+    /** Site id to export (overrides root config). */
+    site?: string;
+    /** Firestore database id. */
+    database?: string;
+    /** GCP project id (overrides root config). */
+    project?: string;
+}
+export declare function exportData(options: ExportOptions): Promise<void>;

package/dist/cli/generate-types.d.ts

@@ -0,0 +1,6 @@
+import { Schema } from '../core/schema.js';
+export declare function generateTypes(): Promise<void>;
+/**
+ * Generates a root-cms.d.ts file from the .schema.ts files in the project.
+ */
+export declare function generateSchemaDts(outputPath: string, schemas: Record<string, Schema>): Promise<void>;

package/dist/cli/import.d.ts

@@ -0,0 +1,13 @@
+export interface ImportOptions {
+    /** Directory to import from. */
+    dir?: string;
+    /** Filter to specific content. */
+    filter?: string;
+    /** Site id to import to (overrides root config). */
+    site?: string;
+    /** Firestore database id. */
+    database?: string;
+    /** GCP project id (overrides root config). */
+    project?: string;
+}
+export declare function importData(options: ImportOptions): Promise<void>;

package/dist/cli/init-firebase.d.ts

@@ -0,0 +1,7 @@
+export interface InitFirebaseOptions {
+    /** GCP project id. */
+    project?: string;
+    /** Adds an ADMIN to the security rules. */
+    admin?: string;
+}
+export declare function initFirebase(options: InitFirebaseOptions): Promise<void>;

package/dist/cli/utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parses a comma-separated filter string into include and exclude patterns.
+ * Exclude patterns are prefixed with "!".
+ */
+export declare function parseFilters(filterStr?: string): {
+    includes: string[];
+    excludes: string[];
+};
+export type PathStatus = 'INCLUDE' | 'TRAVERSE' | 'SKIP' | 'EXCLUDE';
+/**
+ * Determines the status of a path against a set of include and exclude patterns.
+ *
+ * - `EXCLUDE`: Path matches an exclude pattern.
+ * - `INCLUDE`: Path matches an include pattern fully.
+ * - `TRAVERSE`: Path is a parent of an include pattern (partial match).
+ * - `SKIP`: Path does not match any include pattern and is not a parent of one.
+ */
+export declare function getPathStatus(path: string, includes: string[], excludes: string[]): PathStatus;
+/**
+ * Recursively converts Firestore types to JSON-serializable format.
+ */
+export declare function convertForExport(obj: any): any;
+export type LimitFunction = <T>(fn: () => Promise<T>) => Promise<T>;
+/**
+ * Creates a concurrency limiter.
+ */
+export declare function pLimit(concurrency: number): LimitFunction;

package/dist/cli.js

@@ -1,11 +1,11 @@
 import {
   generateTypes
-} from "./chunk-XLX37FRL.js";
+} from "./chunk-TEKMLYXS.js";
 import {
   RootCMSClient,
   getCmsPlugin,
   unmarshalData
-} from "./chunk-2BSW7SIH.js";
+} from "./chunk-N4K6ICFR.js";
 import "./chunk-MLKGABMK.js";
 
 // cli/cli.ts
@@ -13,9 +13,9 @@ import { Command } from "commander";
 import { bgGreen, black } from "kleur/colors";
 
 // cli/docs.ts
-import fs from "fs";
-import path from "path";
-import * as readline from "readline";
+import fs from "node:fs";
+import path from "node:path";
+import * as readline from "node:readline";
 import { loadRootConfig } from "@blinkk/root/node";
 import { Timestamp, GeoPoint } from "firebase-admin/firestore";
 
@@ -332,8 +332,8 @@ function convertFirestoreTypes(obj, db) {
 }
 
 // cli/export.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs2 from "node:fs";
+import path2 from "node:path";
 import { loadRootConfig as loadRootConfig2 } from "@blinkk/root/node";
 async function exportData(options) {
   const rootDir = process.cwd();
@@ -519,9 +519,9 @@ function formatTimestamp(date) {
 }
 
 // cli/import.ts
-import fs3 from "fs";
-import path3 from "path";
-import * as readline2 from "readline";
+import fs3 from "node:fs";
+import path3 from "node:path";
+import * as readline2 from "node:readline";
 import { loadRootConfig as loadRootConfig3 } from "@blinkk/root/node";
 import cliProgress from "cli-progress";
 import { Timestamp as Timestamp2, GeoPoint as GeoPoint2 } from "firebase-admin/firestore";

package/dist/client.js

@@ -12,7 +12,7 @@ import {
   translationsForLocale,
   unmarshalArray,
   unmarshalData
-} from "./chunk-2BSW7SIH.js";
+} from "./chunk-N4K6ICFR.js";
 import "./chunk-MLKGABMK.js";
 export {
   BatchRequest,

package/dist/core/ai-tools.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Built-in CMS tools exposed to the chat model on the `/cms/ai` page.
+ *
+ * Read tools (`doc_get`, `docs_list`, etc.) execute server-side via the
+ * Firebase Admin SDK when a `CmsToolContext` is passed to the factory. This
+ * keeps potentially-large doc payloads off the wire: results stay in the
+ * model's server-side context instead of round-tripping through the browser
+ * on every chat turn.
+ *
+ * Write tools (`doc_set`, `doc_create`, `doc_updateField`, `doc_duplicate`)
+ * stay schema-only here — the browser executes them via `onToolCall` so the
+ * user can approve diffs in the UI and so Firestore listeners on other tabs
+ * see the change immediately.
+ *
+ * Validation helpers (`validateFields`, `validateValueAtPath`) live here
+ * too so both browser and server can share the same checks.
+ *
+ * Browser-import safety: this module is dynamically imported by the browser
+ * bundle (cmsToolHandlers.ts) to reuse the validators, so it must not pull
+ * server-only modules into runtime imports. `RootCMSClient` and `RootConfig`
+ * are referenced as types only; the actual instance is passed in at call
+ * time via `CmsToolContext`.
+ */
+import type { RootConfig } from '@blinkk/root';
+import { ToolSet } from 'ai';
+import type { RootCMSClient } from './client.js';
+import { Collection } from './schema.js';
+import { validateFields } from './validation.js';
+/** Tool ids handled client-side. Kept in sync with the schemas below. */
+export declare const CMS_TOOL_NAMES: readonly ["collections_list", "docs_list", "doc_get", "doc_getVersion", "doc_set", "doc_create", "doc_updateField", "doc_edit", "doc_duplicate", "doc_listVersions", "doc_translateField", "schema_get"];
+export type CmsToolName = (typeof CMS_TOOL_NAMES)[number];
+/**
+ * Subset of CMS tools that perform reads only. Used by flows where the user
+ * approves changes via UI (e.g. the array-item "Edit with AI" diff viewer)
+ * and the model must not write to Firestore directly.
+ */
+export declare const READ_ONLY_CMS_TOOL_NAMES: readonly CmsToolName[];
+/**
+ * Result of a server-side search invocation. Loosely-typed — the result is
+ * serialized to JSON and handed to the model, so extra fields are fine.
+ * `hits` is an array of objects each carrying at least a `docId`.
+ */
+export interface CmsSearchResult {
+    hits: Array<Record<string, unknown> | {
+        docId: string;
+    }>;
+}
+/**
+ * Context passed into the tool factory to enable server-side execution of
+ * the read tools. The caller (typically `runChatStream` in `core/ai.ts`)
+ * owns the Firebase Admin client and the schema/search lookups.
+ */
+export interface CmsToolContext {
+    cmsClient: RootCMSClient;
+    user: string;
+    rootConfig: RootConfig;
+    loadCollection: (collectionId: string) => Promise<Collection | null>;
+    loadAllCollections: () => Promise<Record<string, Collection>>;
+    search: (query: string, options: {
+        limit: number;
+    }) => Promise<CmsSearchResult>;
+}
+/**
+ * Returns a `ToolSet` filtered to only the read-only CMS tools. Use this in
+ * flows where the AI assists with proposing changes that the user reviews
+ * and saves manually (so the model can read context but cannot mutate data).
+ */
+export declare function createReadOnlyCmsTools(ctx: CmsToolContext): ToolSet;
+/**
+ * Builds the full tool set advertised to the model.
+ *
+ * Read tools (`collections_list`, `docs_list`, `docs_search`, `doc_get`,
+ * `doc_getVersion`, `doc_listVersions`, `schema_get`) carry a server-side
+ * `execute` so the Vercel AI SDK runs them in-process; their results stay
+ * in the model's server-side context and never round-trip through the
+ * browser. Write tools (`doc_set`, `doc_create`, `doc_updateField`,
+ * `doc_duplicate`, `doc_translateField`) remain schema-only — the browser
+ * executes them via `onToolCall` so the user can approve diffs before
+ * persistence.
+ *
+ * Safety policy: this tool set is intentionally read + draft-write only.
+ * The following operations are deliberately NOT exposed to the model
+ * because they are publishing-related, destructive, or otherwise
+ * irreversible. Surfacing them would let a single hallucinated tool call
+ * affect the live site or wipe authored content. Users must perform these
+ * actions themselves through the regular CMS UI:
+ *
+ *   - `doc_publish` / `doc_unpublish` — promote/demote a draft to/from
+ *     production. Always user-initiated.
+ *   - `doc_delete` — permanent removal of a doc.
+ *   - `doc_revertDraft` — discards in-progress draft edits.
+ *   - `doc_schedule` / `doc_unschedule` — affects future production state.
+ *   - `doc_lockPublishing` / `doc_unlockPublishing` — affects governance state.
+ *   - `doc_restoreVersion` — overwrites the current draft with old data.
+ *   - Bulk variants (e.g. `docs_publish`) of any of the above.
+ *
+ * If you add new write tools here, keep them limited to draft-mode edits
+ * the user can easily review before publishing.
+ */
+export declare function createCmsTools(ctx: CmsToolContext): ToolSet;
+/**
+ * Validates `value` against the field schema located at `path` within
+ * `collection`. Returns validation errors if the field can be resolved and
+ * the value doesn't match its expected shape. If the field cannot be located
+ * (e.g. the path walks through a `oneof` with an unknown discriminator),
+ * returns an empty array to fall back to "no validation" rather than
+ * blocking the write.
+ */
+export declare function validateValueAtPath(collection: Collection, path: string, value: any): Array<{
+    path: string;
+    message: string;
+    expected?: string;
+    received?: any;
+}>;
+export { validateFields };
+/** A single edit operation handled by the `doc_edit` tool. */
+export interface DocEditOperation {
+    op: 'set' | 'insert_item' | 'remove_item';
+    /** Dotted path within the fields object (no leading "fields." prefix). */
+    path: string;
+    /** Value to write ("set") or insert ("insert_item"). Unused for "remove_item". */
+    value?: any;
+    /** Zero-based array index for "insert_item" (optional) and "remove_item" (required). */
+    index?: number;
+}
+/** A structural failure applying one operation in a `doc_edit` batch. */
+export interface DocEditError {
+    /** Zero-based position of the failing operation in the input list. */
+    opIndex: number;
+    op: string;
+    path: string;
+    message: string;
+    expected?: string;
+    received?: any;
+}
+export type ApplyDocEditsResult = {
+    ok: true;
+    fields: Record<string, any>;
+} | {
+    ok: false;
+    error: DocEditError;
+};
+/**
+ * Applies a sequence of `doc_edit` operations to a plain-JSON `fields` object
+ * and returns the resulting fields, or the first operation that failed.
+ *
+ * Pure: the input is deep-cloned and never mutated, so callers can validate
+ * the result against the collection schema (via `validateFields`) before
+ * persisting. Operations run in order — array indices in each op refer to the
+ * array state after earlier ops have been applied.
+ *
+ * This performs structural checks only (path resolves against the current
+ * data, the target is an array for insert_item/remove_item, the index is in
+ * range). Type/schema validation is the caller's responsibility.
+ */
+export declare function applyDocEdits(fields: Record<string, any>, operations: DocEditOperation[]): ApplyDocEditsResult;

package/dist/core/ai.d.ts

@@ -0,0 +1,330 @@
+import { RootConfig } from '@blinkk/root';
+import { ImageModel, LanguageModel, UIMessage } from 'ai';
+import { Timestamp } from 'firebase-admin/firestore';
+import { RootCMSClient } from './client.js';
+import { Collection } from './schema.js';
+/** Filename of the project-level instructions file loaded into the AI prompt. */
+export declare const ROOT_MD_FILENAME = "ROOT.md";
+export type AiExecutionMode = 'read' | 'approve' | 'auto';
+/**
+ * Provider type for an AI model. Use `openai-compatible` for any OpenAI-style
+ * endpoint (e.g. local Ollama, vLLM, OpenRouter).
+ */
+export type AiProvider = 'openai' | 'openai-compatible' | 'anthropic' | 'google';
+/**
+ * Configuration for a single chat model.
+ *
+ * Inspired by Ollama's `Modelfile` and LiteLLM's model config: each entry maps
+ * a CMS-facing id to a provider, model id and credentials.
+ */
+export interface AiModelConfig {
+    /** Stable id used by the CMS UI and stored alongside chat history. */
+    id: string;
+    /** Optional human-readable label rendered in the model picker. */
+    label?: string;
+    /** Optional description shown under the label. */
+    description?: string;
+    /** AI provider/family to route requests to. */
+    provider: AiProvider;
+    /**
+     * Provider-specific model id (e.g. `gpt-4o`, `claude-opus-4-5`,
+     * `gemini-2.5-pro`). Defaults to `id` if omitted.
+     */
+    modelId?: string;
+    /** API key for the provider. */
+    apiKey?: string;
+    /** Override the provider's base URL (required for `openai-compatible`). */
+    baseURL?: string;
+    /** Custom headers to send with each request. */
+    headers?: Record<string, string>;
+    /** Capabilities advertised to the UI. */
+    capabilities?: {
+        /** Whether the model can call tools. Defaults to `true`. */
+        tools?: boolean;
+        /** Whether the model can stream reasoning/thinking. Defaults to `false`. */
+        reasoning?: boolean;
+        /** Whether the model accepts image attachments. Defaults to `false`. */
+        attachments?: boolean;
+    };
+}
+/**
+ * Full AI config registered on the cms plugin.
+ */
+export interface AiConfig {
+    /** Models exposed in the model picker. The first entry is the default. */
+    models: AiModelConfig[];
+    /** Id of the default model. Defaults to the first model in `models`. */
+    defaultModel?: string;
+    /**
+     * Image generation models. Used by the image generator and any other
+     * features that produce images. Only the `openai` and `google` providers
+     * support image generation.
+     */
+    imageModels?: AiModelConfig[];
+    /** Id of the default image model. Defaults to the first entry in `imageModels`. */
+    defaultImageModel?: string;
+    /**
+     * Optional system prompt prepended to every conversation. If a `ROOT.md`
+     * file exists at the project root, its contents are appended to this
+     * prompt automatically.
+     */
+    systemPrompt?: string;
+    /** Maximum tool-loop steps before stopping. Defaults to 10. */
+    maxSteps?: number;
+}
+interface ChatRecord {
+    id: string;
+    createdBy: string;
+    createdAt: Timestamp;
+    modifiedAt: Timestamp;
+    modelId?: string;
+    title?: string;
+    messages: UIMessage[];
+}
+/** Resolves an `AiModelConfig` to an AI SDK `LanguageModel` instance. */
+export declare function resolveLanguageModel(model: AiModelConfig): LanguageModel;
+/** Resolves an `AiModelConfig` to an AI SDK `ImageModel` instance. */
+export declare function resolveImageModel(model: AiModelConfig): ImageModel;
+/** Strips secrets from `AiConfig` before sending to the browser. */
+export declare function serializeAiConfig(config: AiConfig): {
+    defaultModel: string;
+    models: {
+        id: string;
+        label: string;
+        description: string | undefined;
+        provider: AiProvider;
+        capabilities: {
+            tools: boolean;
+            reasoning: boolean;
+            attachments: boolean;
+        };
+    }[];
+    imageGenerationEnabled: boolean;
+};
+/** Returns the AI config registered on the CMS plugin, or `null`. */
+export declare function getAiConfig(rootConfig: RootConfig): AiConfig | null;
+/** Returns the model config matching `modelId`, or the default model. */
+export declare function findModel(config: AiConfig, modelId?: string): AiModelConfig | null;
+/** Returns the image model config matching `modelId`, or the default image model. */
+export declare function findImageModel(config: AiConfig, modelId?: string): AiModelConfig | null;
+export declare function normalizeExecutionMode(value: unknown): AiExecutionMode;
+/**
+ * Persists chat sessions to Firestore so that users can resume past
+ * conversations from the chat history sidebar.
+ */
+export declare class ChatStore {
+    cmsClient: RootCMSClient;
+    user: string;
+    constructor(cmsClient: RootCMSClient, user: string);
+    collection(): FirebaseFirestore.CollectionReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+    createChat(options?: {
+        id?: string;
+        modelId?: string;
+    }): Promise<ChatRecord>;
+    getChat(id: string): Promise<ChatRecord | null>;
+    listChats(options?: {
+        limit?: number;
+    }): Promise<ChatRecord[]>;
+    deleteChat(id: string): Promise<void>;
+    updateMessages(id: string, messages: UIMessage[], options?: {
+        modelId?: string;
+        title?: string;
+    }): Promise<void>;
+}
+/**
+ * Merges the latest incoming message into the persisted chat history.
+ *
+ * The client posts only the last message; the server holds the rest in
+ * Firestore. After client-side tool execution the SDK resubmits the *same*
+ * assistant message — now carrying tool results — under the id it was
+ * streamed with. That id already exists in the persisted history (saved by
+ * `onFinish` before the results came back), so a naive append would
+ * duplicate it: the stored copy still has unresolved tool calls, which
+ * convert to `tool_use` blocks with no following `tool_result` and the model
+ * provider rejects the request.
+ *
+ * Replacing the matched entry (and dropping anything after it) keeps message
+ * ids unique and the tool-call/result pairing intact. A genuinely new
+ * message id is appended as usual.
+ */
+export declare function mergeIncomingMessage(stored: UIMessage[], incoming: UIMessage): UIMessage[];
+/**
+ * Synthesizes an aborted result for any tool-call part still awaiting one, so
+ * every `tool_use` keeps a matching `tool_result` when the history is handed
+ * to the model. Left unresolved, such parts (from an abandoned turn) make the
+ * provider reject the next request. Returns the original array unchanged when
+ * there is nothing to repair.
+ */
+export declare function sanitizeDanglingToolCalls(messages: UIMessage[]): UIMessage[];
+/**
+ * Reads the project's `ROOT.md` file, if present. Mirrors the convention used
+ * by tools like `AGENTS.md` and `CLAUDE.md`: developers can drop a markdown
+ * file at the project root to give Root AI extra context about site-specific
+ * patterns or conventions.
+ *
+ * Returns the file contents (trimmed) or `null` if the file is missing or
+ * unreadable.
+ */
+export declare function readRootMd(rootDir: string): Promise<string | null>;
+/**
+ * Builds the full system prompt by combining the configured/default base
+ * prompt with the contents of `ROOT.md`, when present. The project-level
+ * file is appended under a clearly delimited section so the model can
+ * distinguish it from the framework-provided instructions.
+ */
+export declare function buildSystemPrompt(basePrompt: string, rootMd: string | null): string;
+/** Derives a short title from the first user message (used as fallback). */
+export declare function deriveChatTitle(messages: UIMessage[]): string;
+/**
+ * Extracts the first user turn and first assistant text turn as a plain-text
+ * transcript, suitable for the title-generation prompt. Skips tool-call
+ * parts, reasoning chunks, and attachments so the model sees the
+ * conversational substance and nothing else.
+ *
+ * Only the opening exchange is included on purpose — the chat title should
+ * describe what the conversation is *about*, anchored on the user's initial
+ * ask, not drift as later follow-ups arrive.
+ */
+export declare function buildTitlePromptContext(messages: UIMessage[]): string;
+/**
+ * Strips the cruft LLMs commonly emit around a title — leading "Title:"
+ * preamble, surrounding quotes, trailing punctuation, internal newlines —
+ * and enforces a hard length cap.
+ */
+export declare function sanitizeGeneratedTitle(raw: string): string;
+/**
+ * Uses the AI model to generate a short summary title for the chat. The
+ * prompt is anchored on the user's initial question (and, if available, the
+ * assistant's first reply) so the title captures *intent and topic* rather
+ * than echoing the first line verbatim.
+ *
+ * Falls back to `deriveChatTitle` if the generation fails or returns an
+ * empty result.
+ */
+export declare function generateChatTitle(model: LanguageModel, messages: UIMessage[]): Promise<string>;
+export interface RunChatStreamOptions {
+    rootConfig: RootConfig;
+    cmsClient: RootCMSClient;
+    config: AiConfig;
+    model: AiModelConfig;
+    messages: UIMessage[];
+    chatId: string;
+    user: string;
+    executionMode?: AiExecutionMode;
+    /**
+     * Title already saved on this chat. When non-empty the server will NOT
+     * regenerate it on this turn — titles are derived once, on the first
+     * assistant response, so they describe the original ask instead of
+     * thrashing as follow-up messages arrive.
+     */
+    existingTitle?: string;
+    /**
+     * When set, tells the model which document the user is currently viewing
+     * in the CMS UI so phrases like "this document" can be resolved.
+     */
+    activeDocId?: string;
+    /**
+     * Loads a single collection's schema. The caller owns dev-vs-prod schema
+     * resolution (Vite SSR vs. prebuilt `dist/collections/*.json`).
+     */
+    loadCollection: (collectionId: string) => Promise<Collection | null>;
+    /** Loads every project collection keyed by id. */
+    loadAllCollections: () => Promise<Record<string, Collection>>;
+}
+export declare function buildExecutionModePrompt(mode: AiExecutionMode): string;
+/**
+ * Builds a streaming response that proxies the model's UI message stream
+ * directly to the client. Persists the final message list to Firestore once
+ * the stream finishes.
+ */
+export declare function runChatStream(options: RunChatStreamOptions): Promise<Response>;
+export interface RunEditObjectStreamOptions {
+    rootConfig: RootConfig;
+    cmsClient: RootCMSClient;
+    user: string;
+    config: AiConfig;
+    model: AiModelConfig;
+    messages: UIMessage[];
+    /** The JSON object the user is editing. Injected as context for the model. */
+    editData: unknown;
+    loadCollection: (collectionId: string) => Promise<Collection | null>;
+    loadAllCollections: () => Promise<Record<string, Collection>>;
+}
+/**
+ * Streaming variant used by the array-item "Edit with AI" diff-viewer flow.
+ *
+ * Differences from `runChatStream`:
+ *
+ * - Uses an edit-specific system prompt that injects the JSON the user is
+ *   editing and the project's `root-cms.d.ts` types, and instructs the model
+ *   to end every response with a fenced ```json block containing the
+ *   complete proposed new JSON. The client extracts that block to populate
+ *   the diff viewer.
+ * - Tools are filtered to read-only (see `createReadOnlyCmsTools`). The user
+ *   approves changes via the modal's "Save" button, so the model must not
+ *   mutate Firestore directly.
+ * - No Firestore persistence — edit sessions are ephemeral and don't show up
+ *   in the user's chat history.
+ */
+export declare function runEditObjectStream(options: RunEditObjectStreamOptions): Promise<Response>;
+/**
+ * Recursively removes `undefined` values from an object/array. Returns a new
+ * structure; the input is not mutated. Used to clean payloads before sending
+ * them to Firestore, which rejects `undefined` outright.
+ */
+export declare function stripUndefined<T>(value: T): T;
+export interface SummarizeDiffOptions {
+    before: Record<string, any> | null;
+    after: Record<string, any> | null;
+}
+/**
+ * Generates a natural language summary of the differences between two JSON
+ * payloads.
+ */
+export declare function summarizeDiff(rootConfig: RootConfig, options: SummarizeDiffOptions): Promise<string>;
+/**
+ * Generates a concise commit-style publish message based on document changes.
+ */
+export declare function generatePublishMessage(rootConfig: RootConfig, options: SummarizeDiffOptions): Promise<string>;
+export interface TranslateStringOptions {
+    sourceText: string;
+    targetLocales: string[];
+    description?: string;
+    existingTranslations?: Record<string, string>;
+}
+/**
+ * Translates a source string into multiple target locales using AI.
+ */
+export declare function translateString(rootConfig: RootConfig, options: TranslateStringOptions): Promise<Record<string, string>>;
+export interface GenerateAltTextOptions {
+    /** Absolute URL or data URL of the image to describe. */
+    imageUrl: string;
+}
+/**
+ * Generates concise alt text for the given image URL using a multimodal model.
+ */
+export declare function generateAltText(rootConfig: RootConfig, options: GenerateAltTextOptions): Promise<string>;
+/** Allowed aspect ratios for image generation. */
+export type AspectRatio = '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9';
+export interface GenerateImageOptions {
+    prompt: string;
+    aspectRatio: AspectRatio;
+    /** Specific image model id from `AiConfig.imageModels`. */
+    modelId?: string;
+}
+export interface GenerateImageResult {
+    /** Generated image as a `data:image/...` URL. */
+    imageUrl: string;
+}
+/**
+ * Generates an image using the configured `imageModels`. Returns the image as
+ * a base64-encoded data URL so the caller can either inline it or upload it
+ * to storage.
+ */
+export declare function generateImage(rootConfig: RootConfig, options: GenerateImageOptions): Promise<GenerateImageResult>;
+/**
+ * Extracts JSON from an AI response that may contain markdown code blocks.
+ * @internal
+ */
+export declare function extractJsonFromResponse(responseText: string): string;
+export {};