@elytracms/studio 0.0.43 → 0.0.44

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

@@ -0,0 +1,35 @@
+import type { CollectionDef, JsonSchema } from '@elytracms/core/cms-core';
+import type { RelationCandidates } from './types';
+/** A relation field's resolved candidate set — how the engine maps ids → reference envelopes. */
+export interface TargetRelationField {
+    fieldName: string;
+    /** The relation's target collection id. */
+    target: string;
+    multiple: boolean;
+    /** The allowed candidate ids (the enum the model chose from). */
+    candidateIds: string[];
+}
+/** The derived target shape + the metadata the engine needs to post-process the output. */
+export interface TargetShape {
+    /** The JSON Schema the structured output must satisfy. */
+    schema: JsonSchema;
+    /** Field names removed by `ai.exclude` (untouchable). */
+    excluded: string[];
+    /** Field names whose values route under `localized[locale]`. */
+    localizedFields: string[];
+    /** Relation fields with their candidate enums. */
+    relationFields: TargetRelationField[];
+}
+export interface BuildTargetShapeInput {
+    collection: CollectionDef;
+    /** Relation candidate ids by field — a relation field with none is omitted from the shape. */
+    candidates?: RelationCandidates;
+    /** UI locale for resolving field labels into descriptions. */
+    locale?: string;
+}
+/**
+ * Build the leash-aware target shape from a collection + candidates. Deterministic;
+ * never throws. Reuses `collectionJsonSchema` as the base, then rewrites relations /
+ * rich text and strips excluded fields.
+ */
+export declare function buildTargetShape(input: BuildTargetShapeInput): TargetShape;

package/dist/lib/ai/shape.js

@@ -0,0 +1,113 @@
+/**
+ * Target-shape derivation for `applyContentWithShape` (EC-331).
+ *
+ * Reuses the existing collection→JSON-Schema derivation (`collectionJsonSchema`,
+ * cms-core) rather than writing a new one, then applies the three leashes the AI
+ * engine adds on top:
+ *
+ *  - `ai.exclude` fields are removed entirely (the model never sees them → cannot
+ *    write them).
+ *  - relation fields become an ENUM over the provided candidate ids (or are omitted
+ *    when no candidates exist) — so a hallucinated relation id is not representable
+ *    as valid structured output.
+ *  - rich-text fields are emitted in the `{ version, doc }` ProseMirror storage shape
+ *    (the `allow` leash on embeds is enforced later by `validateRichTextEmbeds`).
+ *
+ * Localized fields stay flat in the shape (the model authors one locale at a time);
+ * the engine routes their values under `localized[locale]`.
+ */
+import { collectionJsonSchema, resolveLabel } from '@elytracms/core/cms-core';
+/** The rich-text `{ version, doc }` storage envelope, as a JSON Schema. */
+function richTextEnvelopeSchema() {
+    return {
+        type: 'object',
+        description: 'Rich text in the ProseMirror storage shape: { version, doc: { type: "doc", content: [...] } }.',
+        properties: {
+            version: { type: 'number' },
+            doc: {
+                type: 'object',
+                properties: {
+                    type: { type: 'string', const: 'doc' },
+                    content: { type: 'array', items: { type: 'object' } },
+                },
+                required: ['type', 'content'],
+            },
+        },
+        required: ['version', 'doc'],
+    };
+}
+/** A field's model-facing description: resolved label + optional `ai.hint`. */
+function describe(field, locale) {
+    const label = resolveLabel(field.form?.label, locale) ?? field.name;
+    const hint = field.ai?.hint;
+    const parts = [label, hint].filter((p) => typeof p === 'string' && p.length > 0);
+    return parts.length > 0 ? parts.join(' — ') : undefined;
+}
+/**
+ * Build the leash-aware target shape from a collection + candidates. Deterministic;
+ * never throws. Reuses `collectionJsonSchema` as the base, then rewrites relations /
+ * rich text and strips excluded fields.
+ */
+export function buildTargetShape(input) {
+    const base = collectionJsonSchema(input.collection);
+    const properties = {
+        ...(base.properties ?? {}),
+    };
+    const excluded = [];
+    const localizedFields = [];
+    const relationFields = [];
+    for (const field of input.collection.fields) {
+        if (field.localized)
+            localizedFields.push(field.name);
+        if (field.ai?.exclude) {
+            excluded.push(field.name);
+            delete properties[field.name];
+            continue;
+        }
+        if (field.type === 'relation') {
+            const candidates = input.candidates?.[field.name] ?? [];
+            if (candidates.length === 0) {
+                // No candidate ids ⇒ omit the field: the model cannot emit a relation value
+                // at all, so a hallucinated id is structurally impossible.
+                delete properties[field.name];
+                continue;
+            }
+            const ids = candidates.map((c) => c.id);
+            const label = candidates
+                .map((c) => (c.label ? `${c.id} (${c.label})` : c.id))
+                .join(', ');
+            const idSchema = {
+                type: 'string',
+                enum: ids,
+                description: `Choose one of: ${label}`,
+            };
+            properties[field.name] = field.multiple ? { type: 'array', items: idSchema } : idSchema;
+            relationFields.push({
+                fieldName: field.name,
+                target: field.target,
+                multiple: field.multiple,
+                candidateIds: ids,
+            });
+        }
+        else if (field.type === 'richText') {
+            properties[field.name] = richTextEnvelopeSchema();
+        }
+        const prop = properties[field.name];
+        if (prop) {
+            const desc = describe(field, input.locale);
+            // Preserve an existing description (e.g. relation enum / rich-text note).
+            if (desc && typeof prop.description !== 'string')
+                prop.description = desc;
+        }
+    }
+    const requiredIn = Array.isArray(base.required) ? base.required : [];
+    const required = requiredIn.filter((n) => !excluded.includes(n) && properties[n] !== undefined);
+    const schema = {
+        type: 'object',
+        properties,
+        additionalProperties: false,
+        ...(required.length > 0 ? { required } : {}),
+    };
+    return { schema, excluded, localizedFields, relationFields };
+}
+//# sourceMappingURL=shape.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shape.js","sourceRoot":"","sources":["../../../src/lib/ai/shape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Target-shape derivation for `applyContentWithShape` (EC-331).\n *\n * Reuses the existing collection→JSON-Schema derivation (`collectionJsonSchema`,\n * cms-core) rather than writing a new one, then applies the three leashes the AI\n * engine adds on top:\n *\n *  - `ai.exclude` fields are removed entirely (the model never sees them → cannot\n *    write them).\n *  - relation fields become an ENUM over the provided candidate ids (or are omitted\n *    when no candidates exist) — so a hallucinated relation id is not representable\n *    as valid structured output.\n *  - rich-text fields are emitted in the `{ version, doc }` ProseMirror storage shape\n *    (the `allow` leash on embeds is enforced later by `validateRichTextEmbeds`).\n *\n * Localized fields stay flat in the shape (the model authors one locale at a time);\n * the engine routes their values under `localized[locale]`.\n */\nimport { collectionJsonSchema, resolveLabel } from '@elytracms/core/cms-core'\nimport type { CollectionDef, FieldDef, JsonSchema } from '@elytracms/core/cms-core'\nimport type { RelationCandidates } from './types'\n\n/** A relation field's resolved candidate set — how the engine maps ids → reference envelopes. */\nexport interface TargetRelationField {\n  fieldName: string\n  /** The relation's target collection id. */\n  target: string\n  multiple: boolean\n  /** The allowed candidate ids (the enum the model chose from). */\n  candidateIds: string[]\n}\n\n/** The derived target shape + the metadata the engine needs to post-process the output. */\nexport interface TargetShape {\n  /** The JSON Schema the structured output must satisfy. */\n  schema: JsonSchema\n  /** Field names removed by `ai.exclude` (untouchable). */\n  excluded: string[]\n  /** Field names whose values route under `localized[locale]`. */\n  localizedFields: string[]\n  /** Relation fields with their candidate enums. */\n  relationFields: TargetRelationField[]\n}\n\nexport interface BuildTargetShapeInput {\n  collection: CollectionDef\n  /** Relation candidate ids by field — a relation field with none is omitted from the shape. */\n  candidates?: RelationCandidates\n  /** UI locale for resolving field labels into descriptions. */\n  locale?: string\n}\n\n/** The rich-text `{ version, doc }` storage envelope, as a JSON Schema. */\nfunction richTextEnvelopeSchema(): JsonSchema {\n  return {\n    type: 'object',\n    description:\n      'Rich text in the ProseMirror storage shape: { version, doc: { type: \"doc\", content: [...] } }.',\n    properties: {\n      version: { type: 'number' },\n      doc: {\n        type: 'object',\n        properties: {\n          type: { type: 'string', const: 'doc' },\n          content: { type: 'array', items: { type: 'object' } },\n        },\n        required: ['type', 'content'],\n      },\n    },\n    required: ['version', 'doc'],\n  }\n}\n\n/** A field's model-facing description: resolved label + optional `ai.hint`. */\nfunction describe(field: FieldDef, locale?: string): string | undefined {\n  const label = resolveLabel(field.form?.label, locale) ?? field.name\n  const hint = field.ai?.hint\n  const parts = [label, hint].filter((p): p is string => typeof p === 'string' && p.length > 0)\n  return parts.length > 0 ? parts.join(' — ') : undefined\n}\n\n/**\n * Build the leash-aware target shape from a collection + candidates. Deterministic;\n * never throws. Reuses `collectionJsonSchema` as the base, then rewrites relations /\n * rich text and strips excluded fields.\n */\nexport function buildTargetShape(input: BuildTargetShapeInput): TargetShape {\n  const base = collectionJsonSchema(input.collection)\n  const properties: Record<string, JsonSchema> = {\n    ...((base.properties as Record<string, JsonSchema>) ?? {}),\n  }\n  const excluded: string[] = []\n  const localizedFields: string[] = []\n  const relationFields: TargetRelationField[] = []\n\n  for (const field of input.collection.fields) {\n    if (field.localized) localizedFields.push(field.name)\n\n    if (field.ai?.exclude) {\n      excluded.push(field.name)\n      delete properties[field.name]\n      continue\n    }\n\n    if (field.type === 'relation') {\n      const candidates = input.candidates?.[field.name] ?? []\n      if (candidates.length === 0) {\n        // No candidate ids ⇒ omit the field: the model cannot emit a relation value\n        // at all, so a hallucinated id is structurally impossible.\n        delete properties[field.name]\n        continue\n      }\n      const ids = candidates.map((c) => c.id)\n      const label = candidates\n        .map((c) => (c.label ? `${c.id} (${c.label})` : c.id))\n        .join(', ')\n      const idSchema: JsonSchema = {\n        type: 'string',\n        enum: ids,\n        description: `Choose one of: ${label}`,\n      }\n      properties[field.name] = field.multiple ? { type: 'array', items: idSchema } : idSchema\n      relationFields.push({\n        fieldName: field.name,\n        target: field.target,\n        multiple: field.multiple,\n        candidateIds: ids,\n      })\n    } else if (field.type === 'richText') {\n      properties[field.name] = richTextEnvelopeSchema()\n    }\n\n    const prop = properties[field.name]\n    if (prop) {\n      const desc = describe(field, input.locale)\n      // Preserve an existing description (e.g. relation enum / rich-text note).\n      if (desc && typeof prop.description !== 'string') prop.description = desc\n    }\n  }\n\n  const requiredIn = Array.isArray(base.required) ? (base.required as string[]) : []\n  const required = requiredIn.filter((n) => !excluded.includes(n) && properties[n] !== undefined)\n\n  const schema: JsonSchema = {\n    type: 'object',\n    properties,\n    additionalProperties: false,\n    ...(required.length > 0 ? { required } : {}),\n  }\n  return { schema, excluded, localizedFields, relationFields }\n}\n"]}

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

@@ -0,0 +1,227 @@
+/**
+ * `@elytracms/studio/lib/ai` — headless AI platform seam types (EC-331, phase 1).
+ *
+ * Pure types only: this module imports nothing at runtime (every import is
+ * `import type`), so referencing `StudioAiConfig` from the studio-config type does
+ * NOT pull the `ai` / `@ai-sdk/*` runtime onto the critical path. The runtime lives
+ * in the sibling modules (`config`, `anthropic-provider`, `fake-provider`,
+ * `knowledge`, `shape`, `apply-content`, `route`, `provenance`), reached only when
+ * the `ai` block is configured and the AI subsystem actually boots. The Anthropic
+ * provider additionally loads `ai`/`@ai-sdk/anthropic` via dynamic `import()`, so
+ * even importing this barrel never eagerly loads the SDK.
+ */
+import type { CollectionDef, CollectionRegistry, CmsValidationIssue, FieldValues, JsonSchema, ValidateDocumentOptions } from '@elytracms/core/cms-core';
+import type { ComponentManifest } from '@elytracms/core/component-registry';
+/**
+ * The capabilities the engine requires of a provider. Both must be `true` — the
+ * capability gate (`resolveAiConfig`) fails loud otherwise (tool-calling +
+ * structured output are the non-negotiable floor for schema-guaranteed authoring).
+ */
+export interface AiProviderCapabilities {
+    /** The provider can call tools (function/tool calling). */
+    toolCalling: boolean;
+    /** The provider can return schema-constrained structured output. */
+    structuredOutput: boolean;
+}
+/** A request for one schema-constrained structured object — the engine's core primitive. */
+export interface GenerateStructuredRequest {
+    /** System prompt: rules, injection stance, closed-world constraints. */
+    system?: string;
+    /** The task prompt plus assembled context (knowledge, existing values, prior issues). */
+    prompt: string;
+    /** The target shape as a JSON Schema (draft 2020-12 subset) the output must satisfy. */
+    schema: JsonSchema;
+    /** A short name for the schema (some providers surface it as the tool/output name). */
+    schemaName?: string;
+    /** A one-line description of what the schema represents. */
+    schemaDescription?: string;
+}
+/** Token usage a provider may report (best-effort; recorded for soft spend counters). */
+export interface AiUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+}
+export interface GenerateStructuredResult {
+    /** The structured object the provider produced (best-effort match to the request schema). */
+    object: unknown;
+    usage?: AiUsage;
+}
+/** One chat message the streaming route relays to the provider. */
+export interface AiChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/** A streaming chat/completion request the server-route factory forwards to the provider. */
+export interface StreamChatRequest {
+    system?: string;
+    messages: AiChatMessage[];
+}
+/**
+ * A provider adapter over a tool-calling, structured-output model. Anthropic in
+ * production, {@link FakeProvider} (deterministic, keyless) in tests/playground —
+ * both implement this identical surface so the whole loop runs without a key.
+ */
+export interface AiProvider {
+    /** Stable provider id (e.g. `anthropic`, `fake`); recorded in provenance. */
+    readonly id: string;
+    /** The model id the provider targets, when fixed; recorded in provenance. */
+    readonly model?: string;
+    /** The provider's capabilities — validated by the capability gate at config load. */
+    capabilities(): AiProviderCapabilities;
+    /** Produce a single schema-constrained structured object. */
+    generateStructured(request: GenerateStructuredRequest): Promise<GenerateStructuredResult>;
+    /**
+     * Stream a chat/completion response as a Web `Response` — the server-route body.
+     * Optional: headless callers may only use {@link generateStructured}.
+     */
+    streamChat?(request: StreamChatRequest): Promise<Response>;
+}
+/** Soft, advisory limits for the route counter and the engine repair loop. */
+export interface AiLimits {
+    /** Soft per-project ceiling on route requests per minute (advisory; route-enforced). */
+    maxRequestsPerMinute?: number;
+    /** Cap on repair attempts after the first generation (engine default when omitted). */
+    maxRepairAttempts?: number;
+}
+/**
+ * The `ai` block of `defineStudio({ ai })` (EC-331). Studio-only live code — like
+ * `fieldRenderers` / `i18n`, it never reaches the delivery bundle. The block's
+ * ABSENCE means the feature is fully absent (no AI UI, no AI deps on the critical
+ * path); `enabled: false` is a temporary kill-switch that keeps the config.
+ */
+export interface StudioAiConfig {
+    /**
+     * Temporary kill-switch. Presence of the whole `ai` block enables the feature;
+     * `enabled: false` disables it without removing the config. Omitted ⇒ enabled.
+     */
+    enabled?: boolean;
+    /** The provider adapter (live code): Anthropic in production, FakeProvider in tests/playground. */
+    provider: AiProvider;
+    /** Project knowledge sources assembled into the model's context. */
+    knowledge?: KnowledgeSource[];
+    /** Soft rate / repair limits. */
+    limits?: AiLimits;
+}
+/** An inline knowledge literal (markdown prose versioned with the repo). */
+export interface KnowledgeItem {
+    title?: string;
+    content: string;
+}
+/**
+ * A `fromCollection('<id>')` source: studio-editable knowledge whose *content* is
+ * prose held in the DB (data), while the mechanism stays code. Resolved by a
+ * caller-supplied collection reader (starter-kit / studio wires it to operations).
+ */
+export interface KnowledgeCollectionSource {
+    readonly kind: 'collection';
+    /** Collection id whose documents supply editable knowledge prose. */
+    readonly collectionId: string;
+    /** Field carrying the prose; when omitted the reader picks the collection's title/first text field. */
+    readonly field?: string;
+}
+/** An async (or sync) function producing knowledge items at resolve time. */
+export type KnowledgeFn = () => KnowledgeItem | KnowledgeItem[] | Promise<KnowledgeItem | KnowledgeItem[]>;
+/** A knowledge source: inline literal, async function, or `fromCollection(...)` sugar. */
+export type KnowledgeSource = KnowledgeItem | KnowledgeFn | KnowledgeCollectionSource;
+/** The assembled knowledge context — a flat, deterministic list of resolved items. */
+export interface ResolvedKnowledge {
+    items: KnowledgeItem[];
+}
+/** Reads knowledge prose out of a `fromCollection` source (wired to the operations layer). */
+export type KnowledgeCollectionReader = (source: KnowledgeCollectionSource) => KnowledgeItem[] | Promise<KnowledgeItem[]>;
+/**
+ * A relation candidate id (from a `searchDocuments`/tool result). Relation fields may
+ * ONLY use ids present here — the target shape emits them as an enum, so a
+ * hallucinated id is not even representable as valid structured output.
+ */
+export interface RelationCandidate {
+    id: string;
+    /** Human label (title) for the model to choose against. */
+    label?: string;
+}
+/** Relation candidate ids keyed by field name. A field absent here is omitted from the shape. */
+export type RelationCandidates = Record<string, RelationCandidate[]>;
+/** The typed draft-values patch the engine emits — applied by the draft-write path. */
+export interface ContentPatch {
+    collection: string;
+    id: string;
+    /** Non-localized field values. */
+    values: FieldValues;
+    /** Per-locale field values (localized fields, under the target locale). */
+    localized?: Record<string, FieldValues>;
+}
+/** Origin marker the draft-write path records so an AI-authored draft is attributable. */
+export interface AiProvenance {
+    origin: 'assistant';
+    /** Provider id (e.g. `anthropic`, `fake`). */
+    provider: string;
+    /** Model id, when the provider fixes one. */
+    model?: string;
+    /** ISO timestamp when the content was generated. */
+    at: string;
+}
+export interface ApplyContentInput {
+    provider: AiProvider;
+    registry: CollectionRegistry;
+    collection: CollectionDef;
+    /** Document id the patch targets (an existing doc for updates, or a fresh id for creation). */
+    documentId: string;
+    /** The author's instruction / prompt. */
+    instruction: string;
+    /** Assembled knowledge context (from `resolveKnowledge`). */
+    knowledge?: ResolvedKnowledge;
+    /** Component manifests — context for `allow`-leashed richText/blocks fields. */
+    components?: readonly ComponentManifest[];
+    /** Relation candidate ids by field — the ONLY ids a relation field may use. */
+    candidates?: RelationCandidates;
+    /** Existing draft values (updates): the model output merges over these before validation. */
+    existing?: FieldValues;
+    /** Target locale for localized fields (their values land under `localized[locale]`). */
+    locale?: string;
+    /** Injected rich-text embed leash (studio-wired); enforced when present. */
+    validateRichTextEmbeds?: ValidateDocumentOptions['validateRichTextEmbeds'];
+    /** Injected blocks composition leash (studio-wired); enforced when present. */
+    validateComposition?: ValidateDocumentOptions['validateComposition'];
+    /** Document store for relation/asset existence checks (optional). */
+    store?: ValidateDocumentOptions['store'];
+    /** Max repair attempts after the first generation (default {@link DEFAULT_MAX_REPAIR_ATTEMPTS}). */
+    maxRepairAttempts?: number;
+}
+/** The engine's outcome: a valid, leash-compliant patch, or the blocking issues. */
+export type ApplyContentResult = {
+    ok: true;
+    patch: ContentPatch;
+    provenance: AiProvenance;
+    /** Total generation attempts made (1 = happy path, >1 = repaired). */
+    attempts: number;
+    /** Non-error issues surfaced by the accepted document (e.g. warnings). */
+    issues: CmsValidationIssue[];
+} | {
+    ok: false;
+    /** The error-severity issues from the final failed attempt. */
+    issues: CmsValidationIssue[];
+    attempts: number;
+    provenance: AiProvenance;
+};
+/** A validated studio session, from the host-wired `getSession`. Opaque beyond `userId`. */
+export interface AiSession {
+    /** Authenticated principal id. */
+    userId: string;
+    [key: string]: unknown;
+}
+export interface AiRouteHandlerOptions {
+    /** The provider (holds the host-env key). The route is a thin proxy over it. */
+    provider: AiProvider;
+    /**
+     * Server-side session check (reject anonymous callers). Returns a session for an
+     * authenticated caller, `null` otherwise. Wired by the host to its own auth — the
+     * route consumes it, never re-implements it.
+     */
+    getSession: (request: Request) => AiSession | null | Promise<AiSession | null>;
+    /** Soft per-project rate limit (advisory spend guard). */
+    limits?: AiLimits;
+    /** Derive the per-project rate-bucket key from a request (default: one global bucket). */
+    projectKey?: (request: Request) => string;
+}
+/** The mounted route handler: a framework-agnostic Web `Request → Response`. */
+export type AiRouteHandler = (request: Request) => Promise<Response>;

package/dist/lib/ai/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/ai/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * `@elytracms/studio/lib/ai` — headless AI platform seam types (EC-331, phase 1).\n *\n * Pure types only: this module imports nothing at runtime (every import is\n * `import type`), so referencing `StudioAiConfig` from the studio-config type does\n * NOT pull the `ai` / `@ai-sdk/*` runtime onto the critical path. The runtime lives\n * in the sibling modules (`config`, `anthropic-provider`, `fake-provider`,\n * `knowledge`, `shape`, `apply-content`, `route`, `provenance`), reached only when\n * the `ai` block is configured and the AI subsystem actually boots. The Anthropic\n * provider additionally loads `ai`/`@ai-sdk/anthropic` via dynamic `import()`, so\n * even importing this barrel never eagerly loads the SDK.\n */\nimport type {\n  CollectionDef,\n  CollectionRegistry,\n  CmsValidationIssue,\n  FieldValues,\n  JsonSchema,\n  ValidateDocumentOptions,\n} from '@elytracms/core/cms-core'\nimport type { ComponentManifest } from '@elytracms/core/component-registry'\n\n// --- Provider seam ----------------------------------------------------------------\n\n/**\n * The capabilities the engine requires of a provider. Both must be `true` — the\n * capability gate (`resolveAiConfig`) fails loud otherwise (tool-calling +\n * structured output are the non-negotiable floor for schema-guaranteed authoring).\n */\nexport interface AiProviderCapabilities {\n  /** The provider can call tools (function/tool calling). */\n  toolCalling: boolean\n  /** The provider can return schema-constrained structured output. */\n  structuredOutput: boolean\n}\n\n/** A request for one schema-constrained structured object — the engine's core primitive. */\nexport interface GenerateStructuredRequest {\n  /** System prompt: rules, injection stance, closed-world constraints. */\n  system?: string\n  /** The task prompt plus assembled context (knowledge, existing values, prior issues). */\n  prompt: string\n  /** The target shape as a JSON Schema (draft 2020-12 subset) the output must satisfy. */\n  schema: JsonSchema\n  /** A short name for the schema (some providers surface it as the tool/output name). */\n  schemaName?: string\n  /** A one-line description of what the schema represents. */\n  schemaDescription?: string\n}\n\n/** Token usage a provider may report (best-effort; recorded for soft spend counters). */\nexport interface AiUsage {\n  inputTokens?: number\n  outputTokens?: number\n}\n\nexport interface GenerateStructuredResult {\n  /** The structured object the provider produced (best-effort match to the request schema). */\n  object: unknown\n  usage?: AiUsage\n}\n\n/** One chat message the streaming route relays to the provider. */\nexport interface AiChatMessage {\n  role: 'system' | 'user' | 'assistant'\n  content: string\n}\n\n/** A streaming chat/completion request the server-route factory forwards to the provider. */\nexport interface StreamChatRequest {\n  system?: string\n  messages: AiChatMessage[]\n}\n\n/**\n * A provider adapter over a tool-calling, structured-output model. Anthropic in\n * production, {@link FakeProvider} (deterministic, keyless) in tests/playground —\n * both implement this identical surface so the whole loop runs without a key.\n */\nexport interface AiProvider {\n  /** Stable provider id (e.g. `anthropic`, `fake`); recorded in provenance. */\n  readonly id: string\n  /** The model id the provider targets, when fixed; recorded in provenance. */\n  readonly model?: string\n  /** The provider's capabilities — validated by the capability gate at config load. */\n  capabilities(): AiProviderCapabilities\n  /** Produce a single schema-constrained structured object. */\n  generateStructured(request: GenerateStructuredRequest): Promise<GenerateStructuredResult>\n  /**\n   * Stream a chat/completion response as a Web `Response` — the server-route body.\n   * Optional: headless callers may only use {@link generateStructured}.\n   */\n  streamChat?(request: StreamChatRequest): Promise<Response>\n}\n\n// --- Config seam ------------------------------------------------------------------\n\n/** Soft, advisory limits for the route counter and the engine repair loop. */\nexport interface AiLimits {\n  /** Soft per-project ceiling on route requests per minute (advisory; route-enforced). */\n  maxRequestsPerMinute?: number\n  /** Cap on repair attempts after the first generation (engine default when omitted). */\n  maxRepairAttempts?: number\n}\n\n/**\n * The `ai` block of `defineStudio({ ai })` (EC-331). Studio-only live code — like\n * `fieldRenderers` / `i18n`, it never reaches the delivery bundle. The block's\n * ABSENCE means the feature is fully absent (no AI UI, no AI deps on the critical\n * path); `enabled: false` is a temporary kill-switch that keeps the config.\n */\nexport interface StudioAiConfig {\n  /**\n   * Temporary kill-switch. Presence of the whole `ai` block enables the feature;\n   * `enabled: false` disables it without removing the config. Omitted ⇒ enabled.\n   */\n  enabled?: boolean\n  /** The provider adapter (live code): Anthropic in production, FakeProvider in tests/playground. */\n  provider: AiProvider\n  /** Project knowledge sources assembled into the model's context. */\n  knowledge?: KnowledgeSource[]\n  /** Soft rate / repair limits. */\n  limits?: AiLimits\n}\n\n// --- Knowledge seam ---------------------------------------------------------------\n\n/** An inline knowledge literal (markdown prose versioned with the repo). */\nexport interface KnowledgeItem {\n  title?: string\n  content: string\n}\n\n/**\n * A `fromCollection('<id>')` source: studio-editable knowledge whose *content* is\n * prose held in the DB (data), while the mechanism stays code. Resolved by a\n * caller-supplied collection reader (starter-kit / studio wires it to operations).\n */\nexport interface KnowledgeCollectionSource {\n  readonly kind: 'collection'\n  /** Collection id whose documents supply editable knowledge prose. */\n  readonly collectionId: string\n  /** Field carrying the prose; when omitted the reader picks the collection's title/first text field. */\n  readonly field?: string\n}\n\n/** An async (or sync) function producing knowledge items at resolve time. */\nexport type KnowledgeFn = () =>\n  | KnowledgeItem\n  | KnowledgeItem[]\n  | Promise<KnowledgeItem | KnowledgeItem[]>\n\n/** A knowledge source: inline literal, async function, or `fromCollection(...)` sugar. */\nexport type KnowledgeSource = KnowledgeItem | KnowledgeFn | KnowledgeCollectionSource\n\n/** The assembled knowledge context — a flat, deterministic list of resolved items. */\nexport interface ResolvedKnowledge {\n  items: KnowledgeItem[]\n}\n\n/** Reads knowledge prose out of a `fromCollection` source (wired to the operations layer). */\nexport type KnowledgeCollectionReader = (\n  source: KnowledgeCollectionSource,\n) => KnowledgeItem[] | Promise<KnowledgeItem[]>\n\n// --- Engine seam ------------------------------------------------------------------\n\n/**\n * A relation candidate id (from a `searchDocuments`/tool result). Relation fields may\n * ONLY use ids present here — the target shape emits them as an enum, so a\n * hallucinated id is not even representable as valid structured output.\n */\nexport interface RelationCandidate {\n  id: string\n  /** Human label (title) for the model to choose against. */\n  label?: string\n}\n\n/** Relation candidate ids keyed by field name. A field absent here is omitted from the shape. */\nexport type RelationCandidates = Record<string, RelationCandidate[]>\n\n/** The typed draft-values patch the engine emits — applied by the draft-write path. */\nexport interface ContentPatch {\n  collection: string\n  id: string\n  /** Non-localized field values. */\n  values: FieldValues\n  /** Per-locale field values (localized fields, under the target locale). */\n  localized?: Record<string, FieldValues>\n}\n\n/** Origin marker the draft-write path records so an AI-authored draft is attributable. */\nexport interface AiProvenance {\n  origin: 'assistant'\n  /** Provider id (e.g. `anthropic`, `fake`). */\n  provider: string\n  /** Model id, when the provider fixes one. */\n  model?: string\n  /** ISO timestamp when the content was generated. */\n  at: string\n}\n\nexport interface ApplyContentInput {\n  provider: AiProvider\n  registry: CollectionRegistry\n  collection: CollectionDef\n  /** Document id the patch targets (an existing doc for updates, or a fresh id for creation). */\n  documentId: string\n  /** The author's instruction / prompt. */\n  instruction: string\n  /** Assembled knowledge context (from `resolveKnowledge`). */\n  knowledge?: ResolvedKnowledge\n  /** Component manifests — context for `allow`-leashed richText/blocks fields. */\n  components?: readonly ComponentManifest[]\n  /** Relation candidate ids by field — the ONLY ids a relation field may use. */\n  candidates?: RelationCandidates\n  /** Existing draft values (updates): the model output merges over these before validation. */\n  existing?: FieldValues\n  /** Target locale for localized fields (their values land under `localized[locale]`). */\n  locale?: string\n  /** Injected rich-text embed leash (studio-wired); enforced when present. */\n  validateRichTextEmbeds?: ValidateDocumentOptions['validateRichTextEmbeds']\n  /** Injected blocks composition leash (studio-wired); enforced when present. */\n  validateComposition?: ValidateDocumentOptions['validateComposition']\n  /** Document store for relation/asset existence checks (optional). */\n  store?: ValidateDocumentOptions['store']\n  /** Max repair attempts after the first generation (default {@link DEFAULT_MAX_REPAIR_ATTEMPTS}). */\n  maxRepairAttempts?: number\n}\n\n/** The engine's outcome: a valid, leash-compliant patch, or the blocking issues. */\nexport type ApplyContentResult =\n  | {\n      ok: true\n      patch: ContentPatch\n      provenance: AiProvenance\n      /** Total generation attempts made (1 = happy path, >1 = repaired). */\n      attempts: number\n      /** Non-error issues surfaced by the accepted document (e.g. warnings). */\n      issues: CmsValidationIssue[]\n    }\n  | {\n      ok: false\n      /** The error-severity issues from the final failed attempt. */\n      issues: CmsValidationIssue[]\n      attempts: number\n      provenance: AiProvenance\n    }\n\n// --- Route seam -------------------------------------------------------------------\n\n/** A validated studio session, from the host-wired `getSession`. Opaque beyond `userId`. */\nexport interface AiSession {\n  /** Authenticated principal id. */\n  userId: string\n  [key: string]: unknown\n}\n\nexport interface AiRouteHandlerOptions {\n  /** The provider (holds the host-env key). The route is a thin proxy over it. */\n  provider: AiProvider\n  /**\n   * Server-side session check (reject anonymous callers). Returns a session for an\n   * authenticated caller, `null` otherwise. Wired by the host to its own auth — the\n   * route consumes it, never re-implements it.\n   */\n  getSession: (request: Request) => AiSession | null | Promise<AiSession | null>\n  /** Soft per-project rate limit (advisory spend guard). */\n  limits?: AiLimits\n  /** Derive the per-project rate-bucket key from a request (default: one global bucket). */\n  projectKey?: (request: Request) => string\n}\n\n/** The mounted route handler: a framework-agnostic Web `Request → Response`. */\nexport type AiRouteHandler = (request: Request) => Promise<Response>\n"]}

package/dist/lib/i18n/messages.en.js

@@ -578,9 +578,11 @@ export const EN_MESSAGES = {
     'components.preview.propNeedsDocument': msg('Editable in a document — no workspace context in the component preview.', 'Hint under an asset/relation/object prop control in the read-only component preview.'),
     'components.transfer.action': msg('Use in document…'),
     'components.transfer.title': msg('Use “{name}” in a document'),
-    'components.transfer.description': msg('Create a new draft whose blocks field holds this combination, then open it.'),
+    'components.transfer.description': msg('Create a new draft, or add to an existing document’s blocks field, then open it.'),
     'components.transfer.intoField': msg('into'),
-    'components.transfer.noTargets': msg('No collection declares a blocks field to transfer into.'),
+    'components.transfer.newDocument': msg('New {collection} document'),
+    'components.transfer.orExisting': msg('or add to an existing document'),
+    'components.transfer.noTargets': msg('No document field can receive this component.'),
     'components.fieldInspector.props': msg('Props'),
     'components.fieldInspector.noProps': msg('This component declares no editable props.'),
     'components.fieldInspector.slots': msg('Slots'),