@blinkk/root-cms 3.1.3 → 3.1.5

package/dist/cli.js

@@ -5,7 +5,7 @@ import {
   RootCMSClient,
   getCmsPlugin,
   unmarshalData
-} from "./chunk-AFBSITEO.js";
+} from "./chunk-ETHWZSNM.js";
 import "./chunk-J72JK4KR.js";
 import "./chunk-MLKGABMK.js";
 

package/dist/client.js

@@ -12,7 +12,7 @@ import {
   translationsForLocale,
   unmarshalArray,
   unmarshalData
-} from "./chunk-AFBSITEO.js";
+} from "./chunk-ETHWZSNM.js";
 import "./chunk-J72JK4KR.js";
 import "./chunk-MLKGABMK.js";
 export {

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

@@ -1,11 +1,11 @@
 /**
  * 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.
+ * Read tools (`doc_get`, `docs_list`, etc.) run their `execute` against a
+ * pluggable `CmsToolReadBackend`. The `/cms/ai` chat now streams directly from
+ * the browser, so the client supplies a Firebase-web-SDK backend (see
+ * `ui/components/RootAIChat/clientCmsTools.ts`). The factory itself is
+ * data-source agnostic.
  *
  * Write tools (`doc_set`, `doc_create`, `doc_updateField`, `doc_duplicate`)
  * stay schema-only here — the browser executes them via `onToolCall` so the
@@ -15,16 +15,12 @@
  * 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`.
+ * Browser-import safety: this module is imported by the browser bundle, so it
+ * must not pull server-only modules (`firebase-admin`, `node:*`) into runtime
+ * imports. The backend implementation is injected at call time.
  */
-import type { RootConfig } from '@blinkk/root';
 import { ToolSet } from 'ai';
-import type { RootCMSClient } from './client.js';
-import { Collection } from './schema.js';
+import { Collection, Field } 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"];
@@ -35,48 +31,83 @@ export type CmsToolName = (typeof CMS_TOOL_NAMES)[number];
  * 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;
-    }>;
+/** A CMS document shaped for the model (fields/sys already unmarshalled). */
+export interface CmsToolDoc {
+    id: string;
+    collection: string;
+    slug: string;
+    sys: Record<string, unknown>;
+    fields: Record<string, unknown>;
+}
+/** Lightweight doc summary returned by `docs_list`. */
+export interface CmsToolDocSummary {
+    id: string;
+    slug: string;
+    sys: Record<string, unknown>;
+}
+/** Version summary returned by `doc_listVersions`. */
+export interface CmsToolVersionSummary {
+    versionId: string;
+    sys: Record<string, unknown>;
+    tags: string[];
+    publishMessage?: string;
+}
+/** Collection summary returned by `collections_list`. */
+export interface CmsToolCollectionSummary {
+    id: string;
+    name?: string;
+    description?: 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.
+ * Data-source backing the read tools. Implemented server-side (Firebase Admin)
+ * or in the browser (Firebase web SDK — see `clientCmsTools.ts`). The factory
+ * is agnostic to where the reads run.
+ *
+ * Implementations own docId parsing and unmarshalling so the tool `execute`
+ * blocks stay thin and the returned shapes are model-ready.
  */
-export interface CmsToolContext {
-    cmsClient: RootCMSClient;
-    user: string;
-    rootConfig: RootConfig;
-    loadCollection: (collectionId: string) => Promise<Collection | null>;
-    loadAllCollections: () => Promise<Record<string, Collection>>;
-    search: (query: string, options: {
+export interface CmsToolReadBackend {
+    /** Lists all collections with optional name/description metadata. */
+    listCollections(): Promise<CmsToolCollectionSummary[]>;
+    /** Lists docs in a collection (draft or published). */
+    listDocs(collectionId: string, options: {
+        mode: 'draft' | 'published';
+        limit: number;
+    }): Promise<CmsToolDocSummary[]>;
+    /** Reads a single doc, or `null` if it does not exist. */
+    getDoc(docId: string, options: {
+        mode: 'draft' | 'published';
+    }): Promise<CmsToolDoc | null>;
+    /**
+     * Reads a specific version of a doc. `versionId` is "draft", "published" or
+     * a numeric timestamp. Returns `null` if it does not exist.
+     */
+    getDocVersion(docId: string, versionId: string): Promise<CmsToolDoc | null>;
+    /** Lists a doc's version history, most recent first. */
+    listVersions(docId: string, options: {
         limit: number;
-    }) => Promise<CmsSearchResult>;
+    }): Promise<CmsToolVersionSummary[]>;
+    /**
+     * Returns the simplified field definitions for a collection (see
+     * `simplifyFields`), or `null` if the collection is unknown.
+     */
+    getSchemaFields(collectionId: string): Promise<unknown[] | null>;
 }
 /**
  * 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;
+export declare function createReadOnlyCmsTools(backend: CmsToolReadBackend): 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.
+ * `doc_getVersion`, `doc_listVersions`, `schema_get`) carry an `execute` that
+ * delegates to the supplied `CmsToolReadBackend`. 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
@@ -97,7 +128,16 @@ export declare function createReadOnlyCmsTools(ctx: CmsToolContext): ToolSet;
  * 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;
+export declare function createCmsTools(backend: CmsToolReadBackend): ToolSet;
+/**
+ * Reduces a collection's field definitions down to the bits the model needs
+ * (id, type, label, options, nested shape). Drops Root-internal metadata
+ * (preview, conditional visibility, default UI widget hints, etc.) since
+ * those would bloat the model context without adding decision-useful info.
+ *
+ * Exported so the browser backend can shape `schema_get` results the same way.
+ */
+export declare function simplifyFields(fields: Field[]): unknown[];
 /**
  * Validates `value` against the field schema located at `path` within
  * `collection`. Returns validation errors if the field can be resolved and

package/dist/core/ai.d.ts

@@ -1,98 +1,26 @@
 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';
+import { AiConfig, AiExecutionMode, AiModelConfig, resolveLanguageModel } from '../shared/ai/models.js';
+import { deriveChatTitle } from '../shared/ai/prompt-utils.js';
+export type { AiConfig, AiExecutionMode, AiModelCapabilities, AiModelConfig, AiProvider, } from '../shared/ai/models.js';
+export { normalizeExecutionMode, resolveImageModel, resolveLanguageModel, withBrowserHeaders, } from '../shared/ai/models.js';
+export { buildTitlePrompt, buildTitlePromptContext, deriveChatTitle, extractJsonFromResponse, mergeIncomingMessage, sanitizeDanglingToolCalls, sanitizeGeneratedTitle, stripUndefined, TITLE_GENERATION_SYSTEM_PROMPT, } from '../shared/ai/prompt-utils.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';
+/** Default base system prompt for the Root AI chat. */
+export declare const DEFAULT_CHAT_SYSTEM_PROMPT: string;
 /**
- * Provider type for an AI model. Use `openai-compatible` for any OpenAI-style
- * endpoint (e.g. local Ollama, vLLM, OpenRouter).
+ * Strips secrets from `AiConfig` before sending to the browser. Used by the
+ * `/cms/api/ai.config` endpoint and the inlined `window.__ROOT_CTX.ai` to
+ * populate the model picker. The key-bearing connection config is sent
+ * separately (and only for the selected model) via `serializeAiClientModel`.
  */
-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;
+        provider: import("../shared/ai/models.js").AiProvider;
         capabilities: {
             tools: boolean;
             reasoning: boolean;
@@ -101,61 +29,37 @@ export declare function serializeAiConfig(config: AiConfig): {
     }[];
     imageGenerationEnabled: boolean;
 };
+/**
+ * Serializes a single chat model's full connection config — INCLUDING the API
+ * key, base URL and custom headers — for direct browser-to-provider calls.
+ *
+ * Security note: this intentionally exposes the provider API key to the
+ * authenticated CMS client (the project opted into direct client-side calls).
+ * Only return it from authenticated endpoints, and only for the model the user
+ * actually selected.
+ */
+export declare function serializeAiClientModel(model: AiModelConfig): {
+    id: string;
+    label: string;
+    description: string | undefined;
+    provider: import("../shared/ai/models.js").AiProvider;
+    modelId: string;
+    apiKey: string | undefined;
+    baseURL: string | undefined;
+    headers: Record<string, string> | undefined;
+    capabilities: {
+        tools: boolean;
+        reasoning: boolean;
+        attachments: boolean;
+    };
+};
+export type SerializedAiClientModel = ReturnType<typeof serializeAiClientModel>;
 /** 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
@@ -173,106 +77,44 @@ export declare function readRootMd(rootDir: string): Promise<string | null>;
  * 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.
+ * Uses the AI model to generate a short summary title for a chat. Kept for
+ * server-side callers; the browser chat generates titles client-side using the
+ * shared `TITLE_GENERATION_SYSTEM_PROMPT` + `buildTitlePrompt` helpers.
  *
  * 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 {
+export declare function generateChatTitle(model: ReturnType<typeof resolveLanguageModel>, messages: Parameters<typeof deriveChatTitle>[0]): Promise<string>;
+export declare function buildExecutionModePrompt(mode: AiExecutionMode): string;
+export interface BuildChatSystemPromptOptions {
     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;
+    executionMode: AiExecutionMode;
     /**
      * 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.
+ * Assembles the chat system prompt: base prompt + workspace context + tool
+ * safety policy + execution-mode workflow + (optional) active-doc context,
+ * with `ROOT.md` appended when present.
  */
-export declare function runChatStream(options: RunChatStreamOptions): Promise<Response>;
-export interface RunEditObjectStreamOptions {
+export declare function buildChatSystemPrompt(options: BuildChatSystemPromptOptions): Promise<string>;
+export interface BuildEditSystemPromptOptions {
     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.
+ * Assembles the system prompt for the array-item "Edit with AI" diff-viewer
+ * flow: the edit instructions + output-format contract + read-only tool policy
+ * + the project's `root-cms.d.ts` types + the JSON being edited (wrapped as
+ * untrusted data), with `ROOT.md` appended when present.
  */
-export declare function stripUndefined<T>(value: T): T;
+export declare function buildEditSystemPrompt(options: BuildEditSystemPromptOptions): Promise<string>;
 export interface SummarizeDiffOptions {
     before: Record<string, any> | null;
     after: Record<string, any> | null;
@@ -322,9 +164,3 @@ export interface GenerateImageResult {
  * 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 {};

package/dist/core/plugin.d.ts

@@ -182,11 +182,17 @@ export type CMSPluginOptions = {
     onAction?: (action: Action) => any;
     /**
      * Configures the Root CMS AI chat (`/cms/ai`). Provide one or more models
-     * — the CMS proxies user requests directly to the configured providers.
+     * — each entry declares the provider, model id and credentials. The shape
+     * mirrors open source tools like Ollama and LiteLLM.
      *
-     * The shape mirrors open source tools like Ollama and LiteLLM: each entry
-     * declares the provider, model id and credentials. Keys live on the server,
-     * never on the client.
+     * IMPORTANT: the streaming chat (`/cms/ai`, the document-editor AI panel and
+     * the "Edit with AI" modal) calls the provider DIRECTLY from the browser —
+     * SSE proxying through the server did not work on App Engine / Firebase
+     * Hosting. The selected model's API key is therefore delivered to the
+     * authenticated CMS client. Use keys scoped/billed for this trusted,
+     * signed-in audience. The one-shot helpers (diff summaries, publish
+     * messages, translations, alt text, image generation) still run server-side,
+     * so their keys stay on the server.
      *
      * Example:
      * ```ts

package/dist/core/schema.d.ts

@@ -17,6 +17,64 @@ export interface CommonFieldProps {
     /** Hides just the field label in the CMS UI. */
     hideLabel?: boolean;
 }
+/**
+ * Sources the selectable values for a field from a field within another CMS
+ * document.
+ *
+ * Use this when a set of allowed values is managed centrally in the CMS (e.g. a
+ * list of feature flags defined in a global module) and you want other fields
+ * to pick from that list instead of typing free-form strings.
+ *
+ * Example: source a `flag` select's options from the `name` of each item in
+ * the `flags` array of the `GlobalModules/flags` document.
+ *
+ * ```ts
+ * schema.select({
+ *   id: 'flag',
+ *   source: {
+ *     doc: 'GlobalModules/flags',
+ *     field: 'flags',
+ *     valueKey: 'name',
+ *     helpKey: 'description',
+ *   },
+ *   creatable: true,
+ * });
+ * ```
+ */
+export interface DocumentSource {
+    /**
+     * The document to source values from, in `<collection>/<slug>` format, e.g.
+     * `GlobalModules/flags`.
+     */
+    doc: string;
+    /**
+     * The field within the document that holds the values, e.g. `flags`. This is
+     * usually an array; for an array of objects use `valueKey`/`labelKey` to map
+     * each item, and for an array of strings each string is used directly.
+     */
+    field: string;
+    /**
+     * The key on each item to use as the stored value, e.g. `name`. Dot-paths are
+     * supported for nested keys (e.g. `meta.id`). Omit for arrays of strings.
+     */
+    valueKey?: string;
+    /**
+     * The key on each item to use as the display label, e.g. `name`. Dot-paths
+     * are supported. Defaults to `valueKey`.
+     */
+    labelKey?: string;
+    /**
+     * The key on each item to use as secondary help text, shown in a smaller,
+     * dimmed line beneath the label in the dropdown, e.g. `description`. Dot-paths
+     * are supported.
+     */
+    helpKey?: string;
+}
+/**
+ * The source of selectable values for a field. Currently only a CMS document
+ * source is supported; other source types may be added in the future.
+ */
+export type FieldValueSource = DocumentSource;
 export type StringField = CommonFieldProps & {
     type: 'string';
     default?: string;
@@ -67,19 +125,27 @@ export declare function boolean(field: Omit<BooleanField, 'type'>): BooleanField
 export type SelectField = CommonFieldProps & {
     type: 'select';
     default?: string;
+    /** A static list of options to choose from. */
     options?: Array<{
         value: string;
         label?: string;
     }> | string[];
+    /**
+     * Dynamically source the options from a field in another CMS document,
+     * instead of the static `options` list. See {@link DocumentSource}.
+     */
+    source?: FieldValueSource;
+    /**
+     * Whether to allow the user to enter arbitrary values that aren't in the
+     * options/source list. Defaults to `false`.
+     */
+    creatable?: boolean;
     translate?: boolean;
     searchable?: boolean;
 };
 export declare function select(field: Omit<SelectField, 'type'>): SelectField;
 export type MultiSelectField = Omit<SelectField, 'type'> & {
     type: 'multiselect';
-    /** Set to `true` to allow users to create arbitrary values. */
-    creatable?: boolean;
-    translate?: boolean;
 };
 export declare function multiselect(field: Omit<MultiSelectField, 'type'>): MultiSelectField;
 export type ImageField = CommonFieldProps & {
@@ -416,6 +482,25 @@ export type Collection = SchemaWithTypes & {
         /** Sort direction. Defaults to ascending. */
         direction?: 'asc' | 'desc';
     }>;
+    /**
+     * Options that control how the document listing for this collection is
+     * rendered in the CMS.
+     */
+    viewOptions?: {
+        /**
+         * Forces the document listing to always use the "compact" view, which
+         * renders a condensed table (image, doc id, title, badges, and
+         * created/modified timestamps) instead of the default cards with large
+         * titles and preview URLs. Useful for collections that don't have
+         * meaningful preview metadata (e.g. redirects).
+         *
+         * When set, the listing is locked to the compact layout and the CMS
+         * "View" density control is disabled. When unset, users can choose the
+         * listing density (their choice is remembered globally and stays sticky as
+         * they navigate between collections).
+         */
+        compact?: boolean;
+    };
 };
 export declare function defineCollection(collection: Omit<Collection, 'id'>): Omit<Collection, 'id'>;
 export declare const collection: typeof defineCollection;