@elytracms/studio 0.0.45 → 0.0.47

package/dist/lib/ai/rich-text-translate.js

@@ -0,0 +1,229 @@
+/**
+ * Structure-preserving rich-text translation (EC-332).
+ *
+ * The load-bearing invariant: **the model never emits node structure.** Each
+ * translatable block's inline content is serialized to a single plain string in which
+ * every text run is wrapped in an opaque placeholder token (`[[s{k}]]…[[/s{k}]]`) and
+ * every non-text inline atom (image, embed, componentEmbed, hardBreak, mention, any
+ * unknown inline node) is a self-closing token (`[[a{k}]]`). The model translates ONLY
+ * the human-readable text between tokens; on reconstruction each token is mapped back to
+ * the ORIGINAL stored mark stack / atom node — byte-for-byte — so marks, links, internal
+ * `attrs.ref` references, and embeds survive by construction. Only `text` leaves change.
+ *
+ * This ports the Sanity precedent's `blockToMarkdown` / `markdownToChildren` moves to
+ * Elytra's ProseMirror storage, but uses opaque placeholder tokens rather than literal
+ * markdown: Elytra marks (`strike`/`underline`/`link` + its `attrs.ref` envelope) do not
+ * round-trip through markdown losslessly, and reference-index integrity (EC-286) requires
+ * the `ref` bytes to be preserved exactly — which token-indexed restoration guarantees.
+ *
+ * Robust against a misbehaving translator: if a translated block's tokens don't parse
+ * back to a coherent structure, the ORIGINAL block is kept unchanged (never a broken
+ * tree). Determinism: given a deterministic segment transform the output is identical
+ * every run. See `rich-text-translate.test.ts` for the round-trip property tests.
+ */
+import { createRichTextValue, parseRichTextValue } from '@elytracms/core/rich-text';
+// --- Token vocabulary -------------------------------------------------------------
+const spanOpen = (k) => `[[s${k}]]`;
+const spanClose = (k) => `[[/s${k}]]`;
+const atomToken = (k) => `[[a${k}]]`;
+/** Matches every placeholder token: open/close spans and atoms. */
+const TOKEN_RE = /\[\[(\/?)([sa])(\d+)\]\]/g;
+/** True when a string contains any placeholder token (non-global; no shared state). */
+function containsToken(value) {
+    return /\[\[\/?[sa]\d+\]\]/.test(value);
+}
+/** Key-order-insensitive canonical JSON for de-duplicating identical mark stacks. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+    return `{${entries.join(',')}}`;
+}
+/** True when a node is a text leaf (`{ type: 'text', text }`). */
+function isTextNode(node) {
+    return node.type === 'text' && typeof node.text === 'string';
+}
+/** True when a node's direct children include a text leaf (⇒ it is an inline/text block). */
+function hasDirectText(node) {
+    return Array.isArray(node.content) && node.content.some(isTextNode);
+}
+/** Encode one text-bearing block's inline content into a token string + tables. */
+function encodeBlock(node) {
+    const markStacks = [];
+    const markIndex = new Map();
+    const atoms = [];
+    const stackKey = (marks) => {
+        const key = canonicalJson(marks ?? []);
+        const existing = markIndex.get(key);
+        if (existing !== undefined)
+            return existing;
+        const idx = markStacks.length;
+        markStacks.push(marks ? marks.map((m) => ({ ...m })) : []);
+        markIndex.set(key, idx);
+        return idx;
+    };
+    const parts = [];
+    for (const child of node.content ?? []) {
+        if (isTextNode(child)) {
+            const k = stackKey(child.marks);
+            parts.push(`${spanOpen(k)}${child.text ?? ''}${spanClose(k)}`);
+        }
+        else {
+            const k = atoms.length;
+            atoms.push(child);
+            parts.push(atomToken(k));
+        }
+    }
+    return { encoded: parts.join(''), markStacks, atoms };
+}
+/** True when an encoded block holds at least one non-whitespace translatable segment. */
+function hasTranslatableText(encoded) {
+    return encoded.replace(TOKEN_RE, '').trim().length > 0;
+}
+/**
+ * Walk a rich-text value and extract its translatable blocks. Deterministic; never
+ * throws. A value that is not parseable rich text yields no units (and a plan whose
+ * rebuild is a no-op). Code blocks are skipped (code is not prose).
+ */
+export function extractRichTextUnits(raw) {
+    const parsed = parseRichTextValue(raw);
+    const blocks = new Map();
+    const units = [];
+    if (!parsed.ok) {
+        return { units, plan: { value: { version: 1, doc: { type: 'doc', content: [] } }, blocks } };
+    }
+    const value = parsed.value;
+    const walk = (node, path) => {
+        if (node.type === 'codeBlock')
+            return;
+        if (hasDirectText(node)) {
+            const { encoded, markStacks, atoms } = encodeBlock(node);
+            if (hasTranslatableText(encoded)) {
+                const id = path.join('.');
+                blocks.set(id, { path, markStacks, atoms });
+                units.push({ id, text: encoded });
+            }
+            return;
+        }
+        node.content?.forEach((child, i) => walk(child, [...path, i]));
+    };
+    value.doc.content.forEach((node, i) => walk(node, [i]));
+    return { units, plan: { value, blocks } };
+}
+// --- Reconstruction ---------------------------------------------------------------
+/**
+ * Parse an encoded (translated) block string back into inline nodes, or `null` on any
+ * structural mismatch. Strict on purpose: the block is only rewritten when the translated
+ * string is token-faithful — every atom token present exactly once, every span opened and
+ * closed, and no non-whitespace text stranded outside a span (which would mean a dropped
+ * formatting/reference token). Anything else keeps the ORIGINAL block, so an internal
+ * link, image ref, or embed can never be silently lost to a garbled translation.
+ */
+function decodeBlock(translated, tables) {
+    const out = [];
+    const atomsUsed = new Set();
+    let cursor = 0;
+    const pushText = (text, marks) => {
+        if (text.length === 0)
+            return;
+        out.push(marks.length > 0 ? { type: 'text', text, marks: marks.map((m) => ({ ...m })) } : { type: 'text', text });
+    };
+    const re = new RegExp(TOKEN_RE.source, 'g');
+    let match;
+    while ((match = re.exec(translated)) !== null) {
+        const [token, closing, kind, digits] = match;
+        const index = Number(digits);
+        const before = translated.slice(cursor, match.index);
+        // Only whitespace may sit between/around tokens (a translator's added spacing);
+        // stranded words mean a formatting/reference token was dropped → reject.
+        if (before.trim().length > 0)
+            return null;
+        if (kind === 'a') {
+            const atom = tables.atoms[index];
+            if (!atom || atomsUsed.has(index))
+                return null;
+            atomsUsed.add(index);
+            out.push(atom);
+            cursor = match.index + token.length;
+            continue;
+        }
+        // kind === 's'
+        if (closing === '/')
+            return null; // an unmatched close — garbled structure
+        const marks = tables.markStacks[index];
+        if (!marks)
+            return null;
+        const close = spanClose(index);
+        const closeAt = translated.indexOf(close, re.lastIndex);
+        if (closeAt === -1)
+            return null;
+        const inner = translated.slice(re.lastIndex, closeAt);
+        // Inner must not itself contain tokens (spans never nest in our encoding).
+        if (containsToken(inner))
+            return null;
+        pushText(inner, marks);
+        cursor = closeAt + close.length;
+        re.lastIndex = cursor;
+    }
+    if (translated.slice(cursor).trim().length > 0)
+        return null;
+    // Every atom the block carried (image/embed/ref) must survive the translation.
+    if (atomsUsed.size !== tables.atoms.length)
+        return null;
+    return out;
+}
+/** Deep-clone a node array and replace the inline content at `path` with `content`. */
+function replaceAtPath(nodes, path, content) {
+    const [head, ...rest] = path;
+    return nodes.map((node, i) => {
+        if (i !== head)
+            return node;
+        if (rest.length === 0)
+            return { ...node, content };
+        return { ...node, content: replaceAtPath(node.content ?? [], rest, content) };
+    });
+}
+/**
+ * Rebuild a rich-text value from a plan + a per-block translation map. A block absent
+ * from `translations` (skipped/aborted) or whose translated tokens don't parse keeps its
+ * ORIGINAL content — never a broken structure. Returns a fresh `{ version, doc }` value.
+ */
+export function rebuildRichText(plan, translations) {
+    let content = plan.value.doc.content.map((n) => n);
+    for (const [id, tables] of plan.blocks) {
+        const translated = translations.get(id);
+        if (translated === undefined)
+            continue;
+        const decoded = decodeBlock(translated, tables);
+        if (!decoded)
+            continue;
+        content = replaceAtPath(content, tables.path, decoded);
+    }
+    const doc = { type: 'doc', content };
+    return createRichTextValue(doc);
+}
+// --- Deterministic segment transform (FakeProvider + tests) -----------------------
+/**
+ * Apply `fn` to only the human-readable text segments of an encoded block (the runs
+ * between placeholder tokens), leaving every token exactly in place. This is how the
+ * deterministic FakeProvider "translates" a block and how the property tests apply a
+ * real text change without ever touching structure. Pure.
+ */
+export function mapEncodedSegments(encoded, fn) {
+    const re = new RegExp(TOKEN_RE.source, 'g');
+    let out = '';
+    let cursor = 0;
+    let match;
+    while ((match = re.exec(encoded)) !== null) {
+        out += fn(encoded.slice(cursor, match.index)) + match[0];
+        cursor = match.index + match[0].length;
+    }
+    out += fn(encoded.slice(cursor));
+    return out;
+}
+//# sourceMappingURL=rich-text-translate.js.map

package/dist/lib/ai/rich-text-translate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rich-text-translate.js","sourceRoot":"","sources":["../../../src/lib/ai/rich-text-translate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Structure-preserving rich-text translation (EC-332).\n *\n * The load-bearing invariant: **the model never emits node structure.** Each\n * translatable block's inline content is serialized to a single plain string in which\n * every text run is wrapped in an opaque placeholder token (`[[s{k}]]…[[/s{k}]]`) and\n * every non-text inline atom (image, embed, componentEmbed, hardBreak, mention, any\n * unknown inline node) is a self-closing token (`[[a{k}]]`). The model translates ONLY\n * the human-readable text between tokens; on reconstruction each token is mapped back to\n * the ORIGINAL stored mark stack / atom node — byte-for-byte — so marks, links, internal\n * `attrs.ref` references, and embeds survive by construction. Only `text` leaves change.\n *\n * This ports the Sanity precedent's `blockToMarkdown` / `markdownToChildren` moves to\n * Elytra's ProseMirror storage, but uses opaque placeholder tokens rather than literal\n * markdown: Elytra marks (`strike`/`underline`/`link` + its `attrs.ref` envelope) do not\n * round-trip through markdown losslessly, and reference-index integrity (EC-286) requires\n * the `ref` bytes to be preserved exactly — which token-indexed restoration guarantees.\n *\n * Robust against a misbehaving translator: if a translated block's tokens don't parse\n * back to a coherent structure, the ORIGINAL block is kept unchanged (never a broken\n * tree). Determinism: given a deterministic segment transform the output is identical\n * every run. See `rich-text-translate.test.ts` for the round-trip property tests.\n */\nimport { createRichTextValue, parseRichTextValue } from '@elytracms/core/rich-text'\nimport type {\n  RichTextDoc,\n  RichTextMark,\n  RichTextNode,\n  RichTextValue,\n} from '@elytracms/core/rich-text'\n\n// --- Token vocabulary -------------------------------------------------------------\n\nconst spanOpen = (k: number): string => `[[s${k}]]`\nconst spanClose = (k: number): string => `[[/s${k}]]`\nconst atomToken = (k: number): string => `[[a${k}]]`\n\n/** Matches every placeholder token: open/close spans and atoms. */\nconst TOKEN_RE = /\\[\\[(\\/?)([sa])(\\d+)\\]\\]/g\n\n/** True when a string contains any placeholder token (non-global; no shared state). */\nfunction containsToken(value: string): boolean {\n  return /\\[\\[\\/?[sa]\\d+\\]\\]/.test(value)\n}\n\n/** Key-order-insensitive canonical JSON for de-duplicating identical mark stacks. */\nfunction canonicalJson(value: unknown): string {\n  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'\n  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`\n  const entries = Object.entries(value as Record<string, unknown>)\n    .filter(([, v]) => v !== undefined)\n    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n    .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`)\n  return `{${entries.join(',')}}`\n}\n\n// --- Block-unit model -------------------------------------------------------------\n\n/** The per-block side tables the rebuild uses to restore marks + atoms verbatim. */\ninterface BlockTables {\n  /** Path (content-index chain) to the text-bearing node within the doc. */\n  path: number[]\n  /** De-duplicated mark stacks; a span token's index selects one. */\n  markStacks: RichTextMark[][]\n  /** Inline atom nodes (image/embed/componentEmbed/hardBreak/…), preserved verbatim. */\n  atoms: RichTextNode[]\n}\n\n/** One translatable rich-text block: an id stable within the field + its encoded text. */\nexport interface RichTextBlockUnit {\n  /** Stable within the field (the block's content-index path, dot-joined). */\n  id: string\n  /** The encoded translatable string (text runs + placeholder tokens). */\n  text: string\n}\n\n/** The extraction plan: the original value + every block's restoration tables. */\nexport interface RichTextPlan {\n  value: RichTextValue\n  blocks: Map<string, BlockTables>\n}\n\n/** True when a node is a text leaf (`{ type: 'text', text }`). */\nfunction isTextNode(node: RichTextNode): boolean {\n  return node.type === 'text' && typeof node.text === 'string'\n}\n\n/** True when a node's direct children include a text leaf (⇒ it is an inline/text block). */\nfunction hasDirectText(node: RichTextNode): boolean {\n  return Array.isArray(node.content) && node.content.some(isTextNode)\n}\n\n/** Encode one text-bearing block's inline content into a token string + tables. */\nfunction encodeBlock(node: RichTextNode): { encoded: string; markStacks: RichTextMark[][]; atoms: RichTextNode[] } {\n  const markStacks: RichTextMark[][] = []\n  const markIndex = new Map<string, number>()\n  const atoms: RichTextNode[] = []\n  const stackKey = (marks: RichTextMark[] | undefined): number => {\n    const key = canonicalJson(marks ?? [])\n    const existing = markIndex.get(key)\n    if (existing !== undefined) return existing\n    const idx = markStacks.length\n    markStacks.push(marks ? marks.map((m) => ({ ...m })) : [])\n    markIndex.set(key, idx)\n    return idx\n  }\n  const parts: string[] = []\n  for (const child of node.content ?? []) {\n    if (isTextNode(child)) {\n      const k = stackKey(child.marks)\n      parts.push(`${spanOpen(k)}${child.text ?? ''}${spanClose(k)}`)\n    } else {\n      const k = atoms.length\n      atoms.push(child)\n      parts.push(atomToken(k))\n    }\n  }\n  return { encoded: parts.join(''), markStacks, atoms }\n}\n\n/** True when an encoded block holds at least one non-whitespace translatable segment. */\nfunction hasTranslatableText(encoded: string): boolean {\n  return encoded.replace(TOKEN_RE, '').trim().length > 0\n}\n\n/**\n * Walk a rich-text value and extract its translatable blocks. Deterministic; never\n * throws. A value that is not parseable rich text yields no units (and a plan whose\n * rebuild is a no-op). Code blocks are skipped (code is not prose).\n */\nexport function extractRichTextUnits(raw: unknown): { units: RichTextBlockUnit[]; plan: RichTextPlan } {\n  const parsed = parseRichTextValue(raw)\n  const blocks = new Map<string, BlockTables>()\n  const units: RichTextBlockUnit[] = []\n  if (!parsed.ok) {\n    return { units, plan: { value: { version: 1, doc: { type: 'doc', content: [] } }, blocks } }\n  }\n  const value = parsed.value\n\n  const walk = (node: RichTextNode, path: number[]): void => {\n    if (node.type === 'codeBlock') return\n    if (hasDirectText(node)) {\n      const { encoded, markStacks, atoms } = encodeBlock(node)\n      if (hasTranslatableText(encoded)) {\n        const id = path.join('.')\n        blocks.set(id, { path, markStacks, atoms })\n        units.push({ id, text: encoded })\n      }\n      return\n    }\n    node.content?.forEach((child, i) => walk(child, [...path, i]))\n  }\n\n  value.doc.content.forEach((node, i) => walk(node, [i]))\n  return { units, plan: { value, blocks } }\n}\n\n// --- Reconstruction ---------------------------------------------------------------\n\n/**\n * Parse an encoded (translated) block string back into inline nodes, or `null` on any\n * structural mismatch. Strict on purpose: the block is only rewritten when the translated\n * string is token-faithful — every atom token present exactly once, every span opened and\n * closed, and no non-whitespace text stranded outside a span (which would mean a dropped\n * formatting/reference token). Anything else keeps the ORIGINAL block, so an internal\n * link, image ref, or embed can never be silently lost to a garbled translation.\n */\nfunction decodeBlock(translated: string, tables: BlockTables): RichTextNode[] | null {\n  const out: RichTextNode[] = []\n  const atomsUsed = new Set<number>()\n  let cursor = 0\n  const pushText = (text: string, marks: RichTextMark[]): void => {\n    if (text.length === 0) return\n    out.push(marks.length > 0 ? { type: 'text', text, marks: marks.map((m) => ({ ...m })) } : { type: 'text', text })\n  }\n  const re = new RegExp(TOKEN_RE.source, 'g')\n  let match: RegExpExecArray | null\n  while ((match = re.exec(translated)) !== null) {\n    const [token, closing, kind, digits] = match\n    const index = Number(digits)\n    const before = translated.slice(cursor, match.index)\n    // Only whitespace may sit between/around tokens (a translator's added spacing);\n    // stranded words mean a formatting/reference token was dropped → reject.\n    if (before.trim().length > 0) return null\n    if (kind === 'a') {\n      const atom = tables.atoms[index]\n      if (!atom || atomsUsed.has(index)) return null\n      atomsUsed.add(index)\n      out.push(atom)\n      cursor = match.index + token.length\n      continue\n    }\n    // kind === 's'\n    if (closing === '/') return null // an unmatched close — garbled structure\n    const marks = tables.markStacks[index]\n    if (!marks) return null\n    const close = spanClose(index)\n    const closeAt = translated.indexOf(close, re.lastIndex)\n    if (closeAt === -1) return null\n    const inner = translated.slice(re.lastIndex, closeAt)\n    // Inner must not itself contain tokens (spans never nest in our encoding).\n    if (containsToken(inner)) return null\n    pushText(inner, marks)\n    cursor = closeAt + close.length\n    re.lastIndex = cursor\n  }\n  if (translated.slice(cursor).trim().length > 0) return null\n  // Every atom the block carried (image/embed/ref) must survive the translation.\n  if (atomsUsed.size !== tables.atoms.length) return null\n  return out\n}\n\n/** Deep-clone a node array and replace the inline content at `path` with `content`. */\nfunction replaceAtPath(nodes: RichTextNode[], path: number[], content: RichTextNode[]): RichTextNode[] {\n  const [head, ...rest] = path\n  return nodes.map((node, i) => {\n    if (i !== head) return node\n    if (rest.length === 0) return { ...node, content }\n    return { ...node, content: replaceAtPath(node.content ?? [], rest, content) }\n  })\n}\n\n/**\n * Rebuild a rich-text value from a plan + a per-block translation map. A block absent\n * from `translations` (skipped/aborted) or whose translated tokens don't parse keeps its\n * ORIGINAL content — never a broken structure. Returns a fresh `{ version, doc }` value.\n */\nexport function rebuildRichText(\n  plan: RichTextPlan,\n  translations: ReadonlyMap<string, string>,\n): RichTextValue {\n  let content = plan.value.doc.content.map((n) => n)\n  for (const [id, tables] of plan.blocks) {\n    const translated = translations.get(id)\n    if (translated === undefined) continue\n    const decoded = decodeBlock(translated, tables)\n    if (!decoded) continue\n    content = replaceAtPath(content, tables.path, decoded)\n  }\n  const doc: RichTextDoc = { type: 'doc', content }\n  return createRichTextValue(doc)\n}\n\n// --- Deterministic segment transform (FakeProvider + tests) -----------------------\n\n/**\n * Apply `fn` to only the human-readable text segments of an encoded block (the runs\n * between placeholder tokens), leaving every token exactly in place. This is how the\n * deterministic FakeProvider \"translates\" a block and how the property tests apply a\n * real text change without ever touching structure. Pure.\n */\nexport function mapEncodedSegments(encoded: string, fn: (segment: string) => string): string {\n  const re = new RegExp(TOKEN_RE.source, 'g')\n  let out = ''\n  let cursor = 0\n  let match: RegExpExecArray | null\n  while ((match = re.exec(encoded)) !== null) {\n    out += fn(encoded.slice(cursor, match.index)) + match[0]\n    cursor = match.index + match[0].length\n  }\n  out += fn(encoded.slice(cursor))\n  return out\n}\n"]}

package/dist/lib/ai/route-provider.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `createRouteProvider` — the CLIENT-side {@link AiProvider} the studio runs in the
+ * browser (EC-199). It is a thin proxy that forwards `generateStructured` /
+ * `streamChat` to the host's mounted {@link createAiRouteHandler} endpoint over
+ * `fetch`. The provider KEY never touches the browser: the key-holding
+ * {@link createAnthropicProvider} lives only inside the server route; the studio's
+ * `defineStudio({ ai: { provider } })` gets this route provider (or the FakeProvider
+ * for a keyless playground), so the whole authoring loop —
+ * `applyContentWithShape` included — proxies its model calls through the session-gated
+ * route while the tools (search / list / apply) execute client-side with the user's
+ * own session.
+ *
+ * Bundle-safe by construction: this module imports nothing from `ai` / `@ai-sdk/*`
+ * (it only uses `fetch`), so it stays off the AI-SDK dependency edge the bundle test
+ * pins — the route provider can sit on the studio critical path without pulling the
+ * SDK. The capability gate passes: the route only ever fronts a gate-checked provider
+ * (validated at the server mount), so the proxy declares both required capabilities.
+ */
+import type { AiProvider } from './types';
+/** How extra request headers are supplied — a static set or a (possibly async) thunk. */
+export type RouteHeaders = HeadersInit | (() => HeadersInit | undefined | Promise<HeadersInit | undefined>);
+export interface RouteProviderOptions {
+    /** The mounted route path/URL (default `/api/ai`). */
+    endpoint?: string;
+    /** `fetch` implementation (default the global). Injected in tests. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Extra headers per request — e.g. the studio session token the route's `getSession`
+     * checks. A thunk is re-evaluated on every call so a refreshed token is picked up.
+     */
+    headers?: RouteHeaders;
+    /** Provider id recorded in provenance (default `route`). */
+    id?: string;
+    /** Model id recorded in provenance (the downstream model, when the host fixes one). */
+    model?: string;
+}
+/** Default mount path a consuming studio app exposes for {@link createAiRouteHandler}. */
+export declare const DEFAULT_AI_ENDPOINT = "/api/ai";
+/** A structured error thrown when the route rejects (surfaced by the chat UI). */
+export declare class AiRouteError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string);
+}
+/**
+ * Build a route-backed {@link AiProvider}. Deterministic given a deterministic route
+ * (so the FakeProvider mounted behind the route drives the whole client loop in the
+ * playground). Never holds a key; never imports the AI SDK.
+ */
+export declare function createRouteProvider(options?: RouteProviderOptions): AiProvider;

package/dist/lib/ai/route-provider.js

@@ -0,0 +1,60 @@
+/** Default mount path a consuming studio app exposes for {@link createAiRouteHandler}. */
+export const DEFAULT_AI_ENDPOINT = '/api/ai';
+async function resolveHeaders(headers) {
+    if (typeof headers === 'function')
+        return headers();
+    return headers;
+}
+/** A structured error thrown when the route rejects (surfaced by the chat UI). */
+export class AiRouteError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(`AI route request failed (${status}: ${code})`);
+        this.status = status;
+        this.code = code;
+        this.name = 'AiRouteError';
+    }
+}
+async function errorCode(response) {
+    try {
+        const body = (await response.json());
+        return typeof body.error === 'string' ? body.error : 'request-failed';
+    }
+    catch {
+        return 'request-failed';
+    }
+}
+/**
+ * Build a route-backed {@link AiProvider}. Deterministic given a deterministic route
+ * (so the FakeProvider mounted behind the route drives the whole client loop in the
+ * playground). Never holds a key; never imports the AI SDK.
+ */
+export function createRouteProvider(options = {}) {
+    const endpoint = options.endpoint ?? DEFAULT_AI_ENDPOINT;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    async function post(body) {
+        const extra = await resolveHeaders(options.headers);
+        const headers = new Headers(extra);
+        headers.set('content-type', 'application/json');
+        return fetchImpl(endpoint, { method: 'POST', headers, body: JSON.stringify(body) });
+    }
+    return {
+        id: options.id ?? 'route',
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        capabilities: () => ({ toolCalling: true, structuredOutput: true }),
+        async generateStructured(request) {
+            const response = await post({ kind: 'generate', request });
+            if (!response.ok)
+                throw new AiRouteError(response.status, await errorCode(response));
+            return (await response.json());
+        },
+        async streamChat(request) {
+            const response = await post({ kind: 'chat', ...request });
+            if (!response.ok)
+                throw new AiRouteError(response.status, await errorCode(response));
+            return response;
+        },
+    };
+}
+//# sourceMappingURL=route-provider.js.map

package/dist/lib/ai/route-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-provider.js","sourceRoot":"","sources":["../../../src/lib/ai/route-provider.ts"],"names":[],"mappings":"AA+CA,0FAA0F;AAC1F,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAA;AAE5C,KAAK,UAAU,cAAc,CAAC,OAAiC;IAC7D,IAAI,OAAO,OAAO,KAAK,UAAU;QAAE,OAAO,OAAO,EAAE,CAAA;IACnD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,kFAAkF;AAClF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAE1B;IACA;IAFX,YACW,MAAc,EACd,IAAY;QAErB,KAAK,CAAC,4BAA4B,MAAM,KAAK,IAAI,GAAG,CAAC,CAAA;QAH5C,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAQ;QAGrB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;IAC5B,CAAC;CACF;AAED,KAAK,UAAU,SAAS,CAAC,QAAkB;IACzC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAwB,CAAA;QAC3D,OAAO,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAA;IACvE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,gBAAgB,CAAA;IACzB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAgC,EAAE;IACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,mBAAmB,CAAA;IACxD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAA;IAE5C,KAAK,UAAU,IAAI,CAAC,IAAa;QAC/B,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QACnD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;QAClC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAA;QAC/C,OAAO,SAAS,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACrF,CAAC;IAED,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,OAAO;QACzB,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,YAAY,EAAE,GAA2B,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;QAE3F,KAAK,CAAC,kBAAkB,CACtB,OAAkC;YAElC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAA;YAC1D,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAA;YACpF,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA6B,CAAA;QAC5D,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,OAA0B;YACzC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;YACzD,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAA;YACpF,OAAO,QAAQ,CAAA;QACjB,CAAC;KACF,CAAA;AACH,CAAC","sourcesContent":["/**\n * `createRouteProvider` — the CLIENT-side {@link AiProvider} the studio runs in the\n * browser (EC-199). It is a thin proxy that forwards `generateStructured` /\n * `streamChat` to the host's mounted {@link createAiRouteHandler} endpoint over\n * `fetch`. The provider KEY never touches the browser: the key-holding\n * {@link createAnthropicProvider} lives only inside the server route; the studio's\n * `defineStudio({ ai: { provider } })` gets this route provider (or the FakeProvider\n * for a keyless playground), so the whole authoring loop —\n * `applyContentWithShape` included — proxies its model calls through the session-gated\n * route while the tools (search / list / apply) execute client-side with the user's\n * own session.\n *\n * Bundle-safe by construction: this module imports nothing from `ai` / `@ai-sdk/*`\n * (it only uses `fetch`), so it stays off the AI-SDK dependency edge the bundle test\n * pins — the route provider can sit on the studio critical path without pulling the\n * SDK. The capability gate passes: the route only ever fronts a gate-checked provider\n * (validated at the server mount), so the proxy declares both required capabilities.\n */\nimport type {\n  AiProvider,\n  AiProviderCapabilities,\n  GenerateStructuredRequest,\n  GenerateStructuredResult,\n  StreamChatRequest,\n} from './types'\n\n/** How extra request headers are supplied — a static set or a (possibly async) thunk. */\nexport type RouteHeaders =\n  | HeadersInit\n  | (() => HeadersInit | undefined | Promise<HeadersInit | undefined>)\n\nexport interface RouteProviderOptions {\n  /** The mounted route path/URL (default `/api/ai`). */\n  endpoint?: string\n  /** `fetch` implementation (default the global). Injected in tests. */\n  fetchImpl?: typeof fetch\n  /**\n   * Extra headers per request — e.g. the studio session token the route's `getSession`\n   * checks. A thunk is re-evaluated on every call so a refreshed token is picked up.\n   */\n  headers?: RouteHeaders\n  /** Provider id recorded in provenance (default `route`). */\n  id?: string\n  /** Model id recorded in provenance (the downstream model, when the host fixes one). */\n  model?: string\n}\n\n/** Default mount path a consuming studio app exposes for {@link createAiRouteHandler}. */\nexport const DEFAULT_AI_ENDPOINT = '/api/ai'\n\nasync function resolveHeaders(headers: RouteHeaders | undefined): Promise<HeadersInit | undefined> {\n  if (typeof headers === 'function') return headers()\n  return headers\n}\n\n/** A structured error thrown when the route rejects (surfaced by the chat UI). */\nexport class AiRouteError extends Error {\n  constructor(\n    readonly status: number,\n    readonly code: string,\n  ) {\n    super(`AI route request failed (${status}: ${code})`)\n    this.name = 'AiRouteError'\n  }\n}\n\nasync function errorCode(response: Response): Promise<string> {\n  try {\n    const body = (await response.json()) as { error?: unknown }\n    return typeof body.error === 'string' ? body.error : 'request-failed'\n  } catch {\n    return 'request-failed'\n  }\n}\n\n/**\n * Build a route-backed {@link AiProvider}. Deterministic given a deterministic route\n * (so the FakeProvider mounted behind the route drives the whole client loop in the\n * playground). Never holds a key; never imports the AI SDK.\n */\nexport function createRouteProvider(options: RouteProviderOptions = {}): AiProvider {\n  const endpoint = options.endpoint ?? DEFAULT_AI_ENDPOINT\n  const fetchImpl = options.fetchImpl ?? fetch\n\n  async function post(body: unknown): Promise<Response> {\n    const extra = await resolveHeaders(options.headers)\n    const headers = new Headers(extra)\n    headers.set('content-type', 'application/json')\n    return fetchImpl(endpoint, { method: 'POST', headers, body: JSON.stringify(body) })\n  }\n\n  return {\n    id: options.id ?? 'route',\n    ...(options.model !== undefined ? { model: options.model } : {}),\n    capabilities: (): AiProviderCapabilities => ({ toolCalling: true, structuredOutput: true }),\n\n    async generateStructured(\n      request: GenerateStructuredRequest,\n    ): Promise<GenerateStructuredResult> {\n      const response = await post({ kind: 'generate', request })\n      if (!response.ok) throw new AiRouteError(response.status, await errorCode(response))\n      return (await response.json()) as GenerateStructuredResult\n    },\n\n    async streamChat(request: StreamChatRequest): Promise<Response> {\n      const response = await post({ kind: 'chat', ...request })\n      if (!response.ok) throw new AiRouteError(response.status, await errorCode(response))\n      return response\n    },\n  }\n}\n"]}

package/dist/lib/ai/route.d.ts

@@ -13,8 +13,20 @@
  * Session-gated: `getSession` (host-wired, reading its own auth — this module never
  * touches `lib/auth`) must return a session for authenticated callers; anonymous
  * callers are rejected. Plus a soft, in-memory per-project rate counter (spend guard).
+ *
+ * EC-199: the route serves TWO model operations — both thin proxies, neither with any
+ * data access — discriminated by the request body's `kind`:
+ *   - `{ kind: 'chat', messages, system? }`  → `provider.streamChat` (text stream);
+ *   - `{ kind: 'generate', request }`         → `provider.generateStructured` (JSON).
+ * The structured mode is what lets `applyContentWithShape` run CLIENT-side against a
+ * {@link createRouteProvider} whose key never touches the browser — the creation flow's
+ * whole authoring loop proxies its model calls here while the tools (search/list/apply)
+ * execute in the client with the user's own session. A body with `messages` and no
+ * `kind` is still treated as a chat request (back-compat with the phase-1 contract).
  */
 import type { AiRouteHandler, AiRouteHandlerOptions } from './types';
+/** The wire discriminator selecting which model operation the route proxies. */
+export type AiRouteKind = 'chat' | 'generate';
 /**
  * Build the mounted route handler. The returned function is a plain
  * `(Request) => Promise<Response>` — session-gated, soft-rate-limited, and a thin

package/dist/lib/ai/route.js

@@ -24,6 +24,29 @@ function parseChatBody(body) {
         ...(typeof system === 'string' ? { system } : {}),
     };
 }
+/** Structurally validate a {@link GenerateStructuredRequest}, or `null` when malformed. */
+function parseGenerateBody(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const request = body.request;
+    if (typeof request !== 'object' || request === null)
+        return null;
+    const { prompt, schema } = request;
+    if (typeof prompt !== 'string' || typeof schema !== 'object' || schema === null)
+        return null;
+    return request;
+}
+/** The `kind` a body selects: explicit `kind`, else `messages` ⇒ chat (back-compat). */
+function bodyKind(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const kind = body.kind;
+    if (kind === 'chat' || kind === 'generate')
+        return kind;
+    if (Array.isArray(body.messages))
+        return 'chat';
+    return null;
+}
 /**
  * Build the mounted route handler. The returned function is a plain
  * `(Request) => Promise<Response>` — session-gated, soft-rate-limited, and a thin
@@ -63,7 +86,7 @@ export function createAiRouteHandler(options) {
         // 3. Soft per-project rate / spend counter.
         if (rateLimited(projectKey(request)))
             return jsonResponse({ error: 'rate-limited' }, 429);
-        // 4. Body → chat request.
+        // 4. Body → the requested model operation.
         let body;
         try {
             body = await request.json();
@@ -71,11 +94,27 @@ export function createAiRouteHandler(options) {
         catch {
             return jsonResponse({ error: 'invalid-json' }, 400);
         }
-        const chat = parseChatBody(body);
+        const kind = bodyKind(body);
+        // 5a. Structured generation — the thin proxy that lets `applyContentWithShape`
+        //     run client-side without the key ever reaching the browser.
+        if (kind === 'generate') {
+            const generate = parseGenerateBody(body);
+            if (!generate) {
+                return jsonResponse({ error: 'invalid-request', message: 'expected { kind: "generate", request }' }, 400);
+            }
+            try {
+                const result = await options.provider.generateStructured(generate);
+                return jsonResponse(result, 200);
+            }
+            catch {
+                return jsonResponse({ error: 'provider-error' }, 502);
+            }
+        }
+        // 5b. Chat stream (default / back-compat).
+        const chat = kind === 'chat' ? parseChatBody(body) : null;
         if (!chat) {
             return jsonResponse({ error: 'invalid-request', message: 'expected { messages: AiChatMessage[] }' }, 400);
         }
-        // 5. Thin proxy to the provider stream.
         if (!options.provider.streamChat) {
             return jsonResponse({ error: 'provider-cannot-stream' }, 501);
         }

package/dist/lib/ai/route.js.map

@@ -1 +1 @@
-{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../src/lib/ai/route.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Server-route factory (EC-331): a streaming chat/completion endpoint the consuming\n * studio app mounts. Key custody = host route (never the browser, never Convex): the\n * `provider` holds the host-env key and this handler is a THIN model proxy — NO data\n * access, NO service credentials.\n *\n * Framework-agnostic on purpose: it returns a Web `Request → Response` handler the\n * host wires into whatever server entry it has (a TanStack Start server route, a\n * Convex `httpAction`, a plain fetch handler). The current demo studio builds as a\n * pure client SPA with server functions disabled (EC-234), so actually mounting this\n * is an EC-199 integration step; phase 1 ships the handler + its contract.\n *\n * Session-gated: `getSession` (host-wired, reading its own auth — this module never\n * touches `lib/auth`) must return a session for authenticated callers; anonymous\n * callers are rejected. Plus a soft, in-memory per-project rate counter (spend guard).\n */\nimport type {\n  AiChatMessage,\n  AiRouteHandler,\n  AiRouteHandlerOptions,\n  AiSession,\n  StreamChatRequest,\n} from './types'\n\nfunction jsonResponse(value: unknown, status: number): Response {\n  return new Response(JSON.stringify(value), {\n    status,\n    headers: { 'content-type': 'application/json' },\n  })\n}\n\ninterface RateBucket {\n  windowStart: number\n  count: number\n}\n\nfunction isChatMessage(value: unknown): value is AiChatMessage {\n  if (typeof value !== 'object' || value === null) return false\n  const m = value as { role?: unknown; content?: unknown }\n  return (\n    (m.role === 'system' || m.role === 'user' || m.role === 'assistant') &&\n    typeof m.content === 'string'\n  )\n}\n\n/** Parse a request body into a {@link StreamChatRequest}, or `null` when malformed. */\nfunction parseChatBody(body: unknown): StreamChatRequest | null {\n  if (typeof body !== 'object' || body === null) return null\n  const { messages, system } = body as { messages?: unknown; system?: unknown }\n  if (!Array.isArray(messages) || messages.length === 0 || !messages.every(isChatMessage)) {\n    return null\n  }\n  return {\n    messages: messages as AiChatMessage[],\n    ...(typeof system === 'string' ? { system } : {}),\n  }\n}\n\n/**\n * Build the mounted route handler. The returned function is a plain\n * `(Request) => Promise<Response>` — session-gated, soft-rate-limited, and a thin\n * proxy to `provider.streamChat`. Never throws to the caller: every failure is a\n * structured JSON response with an appropriate status.\n */\nexport function createAiRouteHandler(options: AiRouteHandlerOptions): AiRouteHandler {\n  const maxPerMinute = options.limits?.maxRequestsPerMinute\n  const buckets = new Map<string, RateBucket>()\n  const projectKey = options.projectKey ?? (() => 'global')\n\n  function rateLimited(key: string): boolean {\n    if (maxPerMinute === undefined || maxPerMinute <= 0) return false\n    const now = Date.now()\n    const bucket = buckets.get(key)\n    if (!bucket || now - bucket.windowStart >= 60_000) {\n      buckets.set(key, { windowStart: now, count: 1 })\n      return false\n    }\n    bucket.count += 1\n    return bucket.count > maxPerMinute\n  }\n\n  return async (request: Request): Promise<Response> => {\n    // 1. Session gate — reject anonymous callers (the route holds spend, not data).\n    let session: AiSession | null\n    try {\n      session = await options.getSession(request)\n    } catch {\n      return jsonResponse({ error: 'unauthorized' }, 401)\n    }\n    if (!session) return jsonResponse({ error: 'unauthorized' }, 401)\n\n    // 2. Method.\n    if (request.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405)\n\n    // 3. Soft per-project rate / spend counter.\n    if (rateLimited(projectKey(request))) return jsonResponse({ error: 'rate-limited' }, 429)\n\n    // 4. Body → chat request.\n    let body: unknown\n    try {\n      body = await request.json()\n    } catch {\n      return jsonResponse({ error: 'invalid-json' }, 400)\n    }\n    const chat = parseChatBody(body)\n    if (!chat) {\n      return jsonResponse(\n        { error: 'invalid-request', message: 'expected { messages: AiChatMessage[] }' },\n        400,\n      )\n    }\n\n    // 5. Thin proxy to the provider stream.\n    if (!options.provider.streamChat) {\n      return jsonResponse({ error: 'provider-cannot-stream' }, 501)\n    }\n    try {\n      return await options.provider.streamChat(chat)\n    } catch {\n      return jsonResponse({ error: 'provider-error' }, 502)\n    }\n  }\n}\n"]}
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../src/lib/ai/route.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Server-route factory (EC-331): a streaming chat/completion endpoint the consuming\n * studio app mounts. Key custody = host route (never the browser, never Convex): the\n * `provider` holds the host-env key and this handler is a THIN model proxy — NO data\n * access, NO service credentials.\n *\n * Framework-agnostic on purpose: it returns a Web `Request → Response` handler the\n * host wires into whatever server entry it has (a TanStack Start server route, a\n * Convex `httpAction`, a plain fetch handler). The current demo studio builds as a\n * pure client SPA with server functions disabled (EC-234), so actually mounting this\n * is an EC-199 integration step; phase 1 ships the handler + its contract.\n *\n * Session-gated: `getSession` (host-wired, reading its own auth — this module never\n * touches `lib/auth`) must return a session for authenticated callers; anonymous\n * callers are rejected. Plus a soft, in-memory per-project rate counter (spend guard).\n *\n * EC-199: the route serves TWO model operations — both thin proxies, neither with any\n * data access — discriminated by the request body's `kind`:\n *   - `{ kind: 'chat', messages, system? }`  → `provider.streamChat` (text stream);\n *   - `{ kind: 'generate', request }`         → `provider.generateStructured` (JSON).\n * The structured mode is what lets `applyContentWithShape` run CLIENT-side against a\n * {@link createRouteProvider} whose key never touches the browser — the creation flow's\n * whole authoring loop proxies its model calls here while the tools (search/list/apply)\n * execute in the client with the user's own session. A body with `messages` and no\n * `kind` is still treated as a chat request (back-compat with the phase-1 contract).\n */\nimport type {\n  AiChatMessage,\n  AiRouteHandler,\n  AiRouteHandlerOptions,\n  AiSession,\n  GenerateStructuredRequest,\n  StreamChatRequest,\n} from './types'\n\nfunction jsonResponse(value: unknown, status: number): Response {\n  return new Response(JSON.stringify(value), {\n    status,\n    headers: { 'content-type': 'application/json' },\n  })\n}\n\ninterface RateBucket {\n  windowStart: number\n  count: number\n}\n\nfunction isChatMessage(value: unknown): value is AiChatMessage {\n  if (typeof value !== 'object' || value === null) return false\n  const m = value as { role?: unknown; content?: unknown }\n  return (\n    (m.role === 'system' || m.role === 'user' || m.role === 'assistant') &&\n    typeof m.content === 'string'\n  )\n}\n\n/** Parse a request body into a {@link StreamChatRequest}, or `null` when malformed. */\nfunction parseChatBody(body: unknown): StreamChatRequest | null {\n  if (typeof body !== 'object' || body === null) return null\n  const { messages, system } = body as { messages?: unknown; system?: unknown }\n  if (!Array.isArray(messages) || messages.length === 0 || !messages.every(isChatMessage)) {\n    return null\n  }\n  return {\n    messages: messages as AiChatMessage[],\n    ...(typeof system === 'string' ? { system } : {}),\n  }\n}\n\n/** The wire discriminator selecting which model operation the route proxies. */\nexport type AiRouteKind = 'chat' | 'generate'\n\n/** Structurally validate a {@link GenerateStructuredRequest}, or `null` when malformed. */\nfunction parseGenerateBody(body: unknown): GenerateStructuredRequest | null {\n  if (typeof body !== 'object' || body === null) return null\n  const request = (body as { request?: unknown }).request\n  if (typeof request !== 'object' || request === null) return null\n  const { prompt, schema } = request as { prompt?: unknown; schema?: unknown }\n  if (typeof prompt !== 'string' || typeof schema !== 'object' || schema === null) return null\n  return request as GenerateStructuredRequest\n}\n\n/** The `kind` a body selects: explicit `kind`, else `messages` ⇒ chat (back-compat). */\nfunction bodyKind(body: unknown): AiRouteKind | null {\n  if (typeof body !== 'object' || body === null) return null\n  const kind = (body as { kind?: unknown }).kind\n  if (kind === 'chat' || kind === 'generate') return kind\n  if (Array.isArray((body as { messages?: unknown }).messages)) return 'chat'\n  return null\n}\n\n/**\n * Build the mounted route handler. The returned function is a plain\n * `(Request) => Promise<Response>` — session-gated, soft-rate-limited, and a thin\n * proxy to `provider.streamChat`. Never throws to the caller: every failure is a\n * structured JSON response with an appropriate status.\n */\nexport function createAiRouteHandler(options: AiRouteHandlerOptions): AiRouteHandler {\n  const maxPerMinute = options.limits?.maxRequestsPerMinute\n  const buckets = new Map<string, RateBucket>()\n  const projectKey = options.projectKey ?? (() => 'global')\n\n  function rateLimited(key: string): boolean {\n    if (maxPerMinute === undefined || maxPerMinute <= 0) return false\n    const now = Date.now()\n    const bucket = buckets.get(key)\n    if (!bucket || now - bucket.windowStart >= 60_000) {\n      buckets.set(key, { windowStart: now, count: 1 })\n      return false\n    }\n    bucket.count += 1\n    return bucket.count > maxPerMinute\n  }\n\n  return async (request: Request): Promise<Response> => {\n    // 1. Session gate — reject anonymous callers (the route holds spend, not data).\n    let session: AiSession | null\n    try {\n      session = await options.getSession(request)\n    } catch {\n      return jsonResponse({ error: 'unauthorized' }, 401)\n    }\n    if (!session) return jsonResponse({ error: 'unauthorized' }, 401)\n\n    // 2. Method.\n    if (request.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405)\n\n    // 3. Soft per-project rate / spend counter.\n    if (rateLimited(projectKey(request))) return jsonResponse({ error: 'rate-limited' }, 429)\n\n    // 4. Body → the requested model operation.\n    let body: unknown\n    try {\n      body = await request.json()\n    } catch {\n      return jsonResponse({ error: 'invalid-json' }, 400)\n    }\n\n    const kind = bodyKind(body)\n\n    // 5a. Structured generation — the thin proxy that lets `applyContentWithShape`\n    //     run client-side without the key ever reaching the browser.\n    if (kind === 'generate') {\n      const generate = parseGenerateBody(body)\n      if (!generate) {\n        return jsonResponse(\n          { error: 'invalid-request', message: 'expected { kind: \"generate\", request }' },\n          400,\n        )\n      }\n      try {\n        const result = await options.provider.generateStructured(generate)\n        return jsonResponse(result, 200)\n      } catch {\n        return jsonResponse({ error: 'provider-error' }, 502)\n      }\n    }\n\n    // 5b. Chat stream (default / back-compat).\n    const chat = kind === 'chat' ? parseChatBody(body) : null\n    if (!chat) {\n      return jsonResponse(\n        { error: 'invalid-request', message: 'expected { messages: AiChatMessage[] }' },\n        400,\n      )\n    }\n    if (!options.provider.streamChat) {\n      return jsonResponse({ error: 'provider-cannot-stream' }, 501)\n    }\n    try {\n      return await options.provider.streamChat(chat)\n    } catch {\n      return jsonResponse({ error: 'provider-error' }, 502)\n    }\n  }\n}\n"]}

package/dist/lib/ai/tools.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The narrow tool set the creation flow's model works against (EC-199).
+ *
+ * Per the ratified AD, tools execute CLIENT-side against the operations layer with
+ * the user's own session — this module only declares their SHAPES (the model-facing
+ * planner schema) and the reader interface the studio binds to operations. The engine
+ * never gains a write path: `searchDocuments` / `listAssets` are reads that gather the
+ * real ids a proposal may reference (a relation id is otherwise structurally
+ * impossible — see `buildTargetShape`), and `createDocument` is the terminal action
+ * that runs `applyContentWithShape` and yields a reviewable proposal. `updateFields`
+ * and `translate` are deliberately NOT here — they are later slices (EC-332 / post-v1).
+ */
+import type { CmsDocument, JsonSchema } from '@elytracms/core/cms-core';
+/** A document the model may reference as a relation target (from a `searchDocuments` read). */
+export interface DocumentSearchResult {
+    id: string;
+    title?: string;
+}
+/** An asset the model may reference (from a `listAssets` read). */
+export interface AssetSearchResult {
+    id: string;
+    title?: string;
+}
+/**
+ * The client-side, operations-backed readers the orchestrator calls. The studio binds
+ * these to the user's authenticated operations client; tests bind an in-memory fake.
+ * Reads only — there is no write tool (apply is a separate, human-gated draft write).
+ */
+export interface CreateFlowTools {
+    searchDocuments(input: {
+        collection: string;
+        query?: string;
+        limit?: number;
+    }): Promise<DocumentSearchResult[]>;
+    listAssets(input: {
+        query?: string;
+        limit?: number;
+    }): Promise<AssetSearchResult[]>;
+    /**
+     * Fetch a full document (values + localized) for the translate flow (EC-332). Optional:
+     * the creation flow never needs it, so a studio that only wires create can omit it.
+     */
+    getDocument?(input: {
+        collection: string;
+        id: string;
+    }): Promise<CmsDocument | null>;
+}
+/** One planned step the model returns — the discriminated tool/action union. */
+export type PlannerAction = {
+    action: 'searchDocuments';
+    collection: string;
+    query?: string;
+} | {
+    action: 'listAssets';
+    query?: string;
+} | {
+    action: 'createDocument';
+    collection: string;
+    instruction?: string;
+} | {
+    action: 'translateDocument';
+    collection: string;
+    query?: string;
+} | {
+    action: 'respond';
+    message: string;
+};
+/** The schema name the planner call carries — how a FakeProvider tells plan vs. author. */
+export declare const PLANNER_SCHEMA_NAME = "create_flow_action";
+/**
+ * The structured-output schema for ONE planning step. `action` is a closed enum and
+ * `collection` is leashed to the known collection ids, so the model can neither invent
+ * an action nor target a collection that does not exist.
+ */
+export declare function plannerSchema(collectionIds: readonly string[]): JsonSchema;
+/** Coerce a raw structured-output object into a {@link PlannerAction}; `null` if unusable. */
+export declare function parsePlannerAction(raw: unknown): PlannerAction | null;