handoff-app 2.0.0-0 → 2.0.0-10

package/UPGRADE.md

@@ -0,0 +1,218 @@
+# Upgrade Handoff
+
+This document contains migration steps for each major version upgrade.
+
+## Version 1.x.x to version 2.x.x
+
+This guide describes how to upgrade a Handoff project from version 1.x.x to version 2.x.x.
+Each feature section identifies the affected projects and the required changes.
+
+### Before you start
+
+1. Verify that the project builds with its current Handoff version.
+2. Save the project files, package version, and lockfile in version control.
+3. Install the version 2.x.x package that you plan to use.
+4. Apply the migration sections that affect your project.
+
+### Breaking changes
+
+| Change | Affected projects |
+| --- | --- |
+| [Figma token environment references](#figma-token-environment-references) | Projects that put a Figma token directly in config |
+| [Catalog items](#catalog-items) | Projects with component or pattern declarations |
+
+<!-- Add future breaking changes as feature sections before "Verify the upgrade". Add each section to this table. -->
+
+### Figma token environment references
+
+`devAccessToken` and its legacy spelling `dev_access_token` now accept only an environment reference.
+A literal token throws `HandoffConfigError`, including in JavaScript and JSON configs.
+Move the token to the environment and replace the literal:
+
+```ts
+import { defineConfig, fromEnv } from 'handoff-app';
+
+export default defineConfig({
+  devAccessToken: fromEnv('HANDOFF_DEV_ACCESS_TOKEN'),
+});
+```
+
+For JSON, use `"devAccessToken": { "$env": "HANDOFF_DEV_ACCESS_TOKEN" }`.
+If you already use `HANDOFF_DEV_ACCESS_TOKEN` and omit the config property, no change is required.
+Environment references resolve after profile merging. Higher-layer literals still override default
+environment seeds for properties that allow literals, such as output directories.
+
+### Catalog items
+
+#### Affected projects
+
+This change affects projects that use the old component or pattern registration API.
+It also affects projects that use the deprecated API from an earlier version 2.x.x prerelease.
+Version 2.x.x requires `defineCatalogItem` for implementations and compositions.
+
+#### Register catalog directories
+
+Move component and pattern directories from `entries` to `catalog.include`.
+
+Version 1.x.x:
+
+```js
+entries: { components: ['components'], patterns: ['patterns'], scss: 'styles/main.scss' }
+```
+
+Version 2.x.x:
+
+```js
+catalog: { include: ['components', 'patterns'] },
+entries: { scss: 'styles/main.scss' }
+```
+
+Each path can name one item directory or a collection of item directories. Global `entries.js` and `entries.scss` still work.
+
+#### Convert declaration files
+
+Use `<name>.handoff.ts`, `<name>.handoff.js`, or `<name>.handoff.cjs`.
+Replace legacy filenames such as `button.json` or `button.js`.
+
+Version 2.x.x does not support JSON item declarations, including `.handoff.json`.
+JSON project config (`handoff.config.json`) remains supported.
+
+If `runtime.workspace.declarationFormat` is `json`, change it to `ts`, `js`, or `cjs`. The default remains `ts`.
+
+#### Replace declaration helpers
+
+| Removed API | Replacement |
+| --- | --- |
+| `defineReactComponent(Component, config)` | `defineCatalogItem({ ...config, implementation: Component })` from `handoff-app/react` |
+| `defineHandlebarsComponent(config)` | `defineCatalogItem({ ...config, implementation: './Button.hbs' })` from `handoff-app/handlebars` |
+| `defineCsfComponent(config)` | `defineCatalogItem({ ...config, implementation: fromCSF('./Button.stories.tsx') })` from `handoff-app/react` |
+| `defineComponent(config)` | `defineCatalogItem({ ...config, implementation: './Button.tsx' })` from the module for its renderer |
+| `definePattern({ components })` | `defineCatalogItem({ composition })` from `handoff-app/pattern` |
+
+Remove the old `renderer`, `entries.component`, `entries.template`, and `entries.story` fields.
+The implementation supplies the renderer and source file.
+Keep the supporting `entries.js`, `entries.scss`, `entries.schema`, and `entries.templates` paths that your item uses.
+Rename the metadata fields:
+
+| Old field | Version 2.x.x field |
+| --- | --- |
+| `title` | `name` |
+| `should_do` | `shouldDo` |
+| `should_not_do` | `shouldNotDo` |
+
+##### React
+
+```ts
+import { defineCatalogItem, type Preview } from 'handoff-app/react';
+import Button from './Button';
+
+const item = defineCatalogItem({
+  name: 'Button',
+  implementation: Button,
+  entries: { scss: './button.scss' },
+});
+export default item;
+export const Primary = { args: { children: 'Save' } } satisfies Preview<typeof item>;
+```
+
+Imported components retain their prop types. A file path also works: `implementation: './Button.tsx'`.
+Keep implementation files inside the item directory to publish them.
+
+##### Handlebars and CommonJS
+
+```js
+const { defineCatalogItem } = require('handoff-app/handlebars');
+
+exports.default = defineCatalogItem({
+  name: 'Badge',
+  implementation: './Badge.hbs',
+});
+exports.Primary = { args: { children: 'New' } };
+```
+
+Use this form in `.handoff.js` or `.handoff.cjs`. JavaScript declarations can also use `import` and `export`.
+
+##### CSF
+
+```ts
+import { defineCatalogItem, fromCSF } from 'handoff-app/react';
+
+export default defineCatalogItem({
+  name: 'Button',
+  implementation: fromCSF('./Button.stories.tsx'),
+});
+```
+
+CSF is a React source format. The story file supplies the previews.
+The filename does not select CSF automatically.
+
+##### Compositions
+
+```ts
+import { defineCatalogItem } from 'handoff-app/pattern';
+
+export default defineCatalogItem({
+  name: 'Toolbar',
+  composition: [{ ref: 'button', preview: 'Primary', args: { children: 'Save' } }],
+});
+```
+
+Rename `components` to `composition`.
+Rename each member's `id` to `ref`.
+Keep item IDs stable.
+
+#### Export previews
+
+Remove the inline `previews` map.
+Export each preview beside the default catalog item.
+Rename preview `title` to `name`.
+Rename `values` to `args`:
+
+```ts
+export const Primary = { name: 'Primary action', args: { children: 'Save' } };
+```
+
+If a preview key is a valid export name, preserve its spelling and capitalization.
+If a key is not a valid export name, rename it.
+Update composition references to each renamed preview.
+
+Previews appear in source export order.
+
+For CommonJS declarations, use `exports.default` for the item.
+Use a named export such as `exports.Primary` for each preview.
+
+#### Replace declaration types
+
+Replace imports of the removed types:
+
+| Removed type | Replacement |
+| --- | --- |
+| `Component` | `CatalogItem` |
+| `DeclarationPreview` | `CatalogPreview` or `Preview<typeof item>` |
+| `PatternComponentRef` | `CompositionRef` |
+| `ReactDeclarationConfig`, `HandlebarsDeclarationConfig`, `CsfDeclarationConfig` | The catalog helper's input type |
+| `GenericDeclarationConfig`, `GenericPatternDeclarationConfig` | The catalog helper's input type, or `CatalogItemMeta` for shared metadata |
+
+`RendererKind` comes from the catalog API and contains `react` and `handlebars`.
+CSF uses `renderer: 'react'` with `format: 'csf'` inside `implementation`.
+
+#### Registry projects
+
+Checkout writes only catalog declarations.
+Registry records require explicit renderer and source-format metadata where applicable.
+
+### Verify the upgrade
+
+After you apply the required migrations, verify the project:
+
+1. Build the project with version 2.x.x.
+2. Verify that all expected catalog items appear in the documentation.
+3. Verify the preview order, arguments, and composition references.
+4. Start the workspace with file watchers.
+5. Edit a declaration to verify that its previews update.
+
+If the project uses a registry, verify the published items:
+
+1. Publish the migrated items.
+2. Verify that checkout produces valid declarations.
+3. Rebuild the checked-out items.

package/config/config.template.js

@@ -54,13 +54,10 @@ const config = {
     ports: { app: 3000, websocket: 3001 },
   },
   // These are the entry points used to compile the target application
+  catalog: { include: ['./components'] },
   entries: {
     scss: './sass/main.scss',
     js: './js/main.js',
-    components: ['./components'],
-    // Uncomment to enable pattern documentation pages.
-    // Patterns compose component previews into single-page views.
-    // patterns: ['./patterns'],
   },
   // These are the asset zip file download links
   assetsZipLinks: {

package/config/config.template.ts

@@ -34,11 +34,10 @@ export default defineConfig({
     },
     ports: { app: 3000, websocket: 3001 },
   },
+  catalog: { include: ['./components'] },
   entries: {
     scss: './sass/main.scss',
     js: './js/main.js',
-    components: ['./components'],
-    // patterns: ['./patterns'],
   },
   assetsZipLinks: {
     icons: null,

package/config/docs/foundations/colors/guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Color Guidelines
+description: How to apply the color palette consistently and accessibly across products.
+metaTitle: 'Color Guidelines | Handoff Design System'
+metaDescription: 'How to apply the color palette consistently and accessibly across products.'
+---
+
+This is placeholder content for the **Color Guidelines** page. Replace it with your rules for
+contrast, pairing, and semantic usage. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/effects/guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Effects Guidelines
+description: When and how to apply shadows, blurs, and elevation across the interface.
+metaTitle: 'Effects Guidelines | Handoff Design System'
+metaDescription: 'When and how to apply shadows, blurs, and elevation across the interface.'
+---
+
+This is placeholder content for the **Effects Guidelines** page. Replace it with your rules for
+elevation, depth, and motion. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/effects/resources.md

@@ -0,0 +1,9 @@
+---
+title: Effects Resources
+description: Reference values and assets for reproducing the brand's effects in any tool.
+metaTitle: 'Effects Resources | Handoff Design System'
+metaDescription: 'Reference values and assets for reproducing effects in any tool.'
+---
+
+This is placeholder content for the **Effects Resources** page. Replace it with your shadow tokens,
+blur values, and export notes. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/grid.md

@@ -0,0 +1,10 @@
+---
+title: Grid
+description: Layout grid and spacing system that keeps compositions aligned and balanced.
+image: hero-design
+metaTitle: 'Grid | Handoff Design System'
+metaDescription: 'Layout grid and spacing system that keeps compositions aligned and balanced.'
+---
+
+This is placeholder content for the **Grid** page. Replace it with your columns, gutters, and
+breakpoint rules. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/icons/guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Icon Guidelines
+description: Sizing, spacing, and usage rules that keep the icon set consistent.
+metaTitle: 'Icon Guidelines | Handoff Design System'
+metaDescription: 'Sizing, spacing, and usage rules that keep the icon set consistent.'
+---
+
+This is placeholder content for the **Icon Guidelines** page. Replace it with your rules for grid
+sizing, stroke, and when to use each icon. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/images/guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Image Guidelines
+description: How to select, crop, and treat imagery so it stays on brand.
+metaTitle: 'Image Guidelines | Handoff Design System'
+metaDescription: 'How to select, crop, and treat imagery so it stays on brand.'
+---
+
+This is placeholder content for the **Image Guidelines** page. Replace it with your rules for
+composition, cropping, and treatments. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/images/resources.md

@@ -0,0 +1,9 @@
+---
+title: Image Resources
+description: Source files and downloads for approved photography and illustration.
+metaTitle: 'Image Resources | Handoff Design System'
+metaDescription: 'Source files and downloads for approved photography and illustration.'
+---
+
+This is placeholder content for the **Image Resources** page. Replace it with your image library,
+downloads, and licensing notes. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/images.md

@@ -0,0 +1,10 @@
+---
+title: Images
+description: Photography and illustration style that shapes how the brand looks and feels.
+image: hero-design
+metaTitle: 'Images | Handoff Design System'
+metaDescription: 'Photography and illustration style that shapes how the brand looks and feels.'
+---
+
+This is placeholder content for the **Images** page. Replace it with your art direction,
+photography style, and illustration principles. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/logo/resources.md

@@ -0,0 +1,9 @@
+---
+title: Logo Resources
+description: Downloadable logo files and everything teams need to represent the brand correctly.
+metaTitle: 'Logo Resources | Handoff Design System'
+metaDescription: 'Downloadable logo files and everything teams need to represent the brand correctly.'
+---
+
+This is placeholder content for the **Logo Resources** page. Replace it with your logo downloads,
+file formats, and usage notes. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/typography/guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Typography Guidelines
+description: Best practices for type scale, hierarchy, and readability across the system.
+metaTitle: 'Typography Guidelines | Handoff Design System'
+metaDescription: 'Best practices for type scale, hierarchy, and readability across the system.'
+---
+
+This is placeholder content for the **Typography Guidelines** page. Replace it with your rules for
+hierarchy, spacing, and responsive type. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/typography/resources.md

@@ -0,0 +1,9 @@
+---
+title: Typography Resources
+description: Font files, licenses, and assets needed to work with the brand typography.
+metaTitle: 'Typography Resources | Handoff Design System'
+metaDescription: 'Font files, licenses, and assets needed to work with the brand typography.'
+---
+
+This is placeholder content for the **Typography Resources** page. Replace it with your font
+downloads, licensing details, and platform notes. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations.md

@@ -67,8 +67,10 @@ menu:
         title: Images
         icon: image
         menu:
-          - path: foundations/icons
-            title: Library
-          - path: foundations/icons/guidelines
+          - path: foundations/images
+            title: Overview
+          - path: foundations/images/guidelines
             title: Guidelines
+          - path: foundations/images/resources
+            title: Resources
 ---

package/dist/ai/connections.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AI connection resolution.
+ *
+ * `runtime.ai.connections` declares the whole surface a reader can reach. Mirrors
+ * {@link import('../registry/asset-storage/resolve')}: only provider selection, module location,
+ * non-secret options, and env-var *names* are ever persisted; secret *values* are read from
+ * `process.env` at request time.
+ *
+ * The list is deployment data rather than build shape, so `HANDOFF_AI_CONNECTIONS` can extend or
+ * replace the baked list at request time. A registry is built once and redeployed many times, and a
+ * new gateway should not need a rebuild.
+ */
+import type { AiCredentialKind, ResolvedConfig } from '../types/config';
+/** A connection as it is baked and read back: env-var names, never secret values. */
+export interface AiConnectionSettings {
+    id: string;
+    label: string;
+    baseUrl?: string;
+    module?: string;
+    /** Name of the env var holding the deployment's own key. Its presence marks a service connection. */
+    apiKeyEnv?: string;
+    credential?: 'user';
+    models?: string[];
+    options?: Record<string, unknown>;
+}
+/** The resolved AI block: whether this build serves the assistant, and what it can reach. */
+export interface AiSettings {
+    enabled: boolean;
+    connections: AiConnectionSettings[];
+    defaultModel?: string;
+}
+/**
+ * Which of the three credential states a connection declares. Derived from the declaration, never
+ * from a missing key: without the explicit `user` state, a connection that needs a reader's key
+ * would be indistinguishable from one that needs none.
+ */
+export declare const aiCredentialKind: (connection: AiConnectionSettings) => AiCredentialKind;
+/** Split `<connectionId>/<model>`. Only the first slash separates them, since model ids carry slashes. */
+export declare const parseAiModelId: (value: string) => {
+    connectionId: string;
+    model: string;
+} | null;
+/** Join a connection id and a model into the address the client sends back. */
+export declare const formatAiModelId: (connectionId: string, model: string) => string;
+/**
+ * Merge a deployment-supplied list over the baked one by `id`: a matching id replaces the baked
+ * connection outright, and a new id is appended. Replacement rather than a field-wise merge, so a
+ * deployment that repoints a gateway cannot leave a stale model list or key name behind.
+ */
+export declare const mergeAiConnections: (baked: readonly AiConnectionSettings[], overrides: readonly AiConnectionSettings[]) => AiConnectionSettings[];
+/** Parse the `HANDOFF_AI_CONNECTIONS` JSON array. A malformed value is ignored rather than fatal. */
+export declare const parseAiConnections: (raw: string | undefined) => AiConnectionSettings[];
+/**
+ * Whether this build serves the assistant. The `ai` block is the opt-in; `enabled: false` turns it
+ * back off. Config-only and baked, like `runtime.mcp`.
+ */
+export declare const isAiEnabled: (config: Pick<ResolvedConfig, "runtime"> | null | undefined) => boolean;
+/**
+ * Resolve the AI settings from a loaded config (CLI/build side).
+ *
+ * An authored connection that cannot be used fails the build rather than disappearing. A deployment
+ * list stays lenient by contrast: a bad `HANDOFF_AI_CONNECTIONS` entry must not take the server down.
+ */
+export declare const resolveAiFromConfig: (config: ResolvedConfig | null | undefined) => AiSettings;

package/dist/ai/connections.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * AI connection resolution.
+ *
+ * `runtime.ai.connections` declares the whole surface a reader can reach. Mirrors
+ * {@link import('../registry/asset-storage/resolve')}: only provider selection, module location,
+ * non-secret options, and env-var *names* are ever persisted; secret *values* are read from
+ * `process.env` at request time.
+ *
+ * The list is deployment data rather than build shape, so `HANDOFF_AI_CONNECTIONS` can extend or
+ * replace the baked list at request time. A registry is built once and redeployed many times, and a
+ * new gateway should not need a rebuild.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAiFromConfig = exports.isAiEnabled = exports.parseAiConnections = exports.mergeAiConnections = exports.formatAiModelId = exports.parseAiModelId = exports.aiCredentialKind = void 0;
+const errors_1 = require("../config/errors");
+/** A connection id addresses a model as `<id>/<model>`, so it cannot itself contain a slash. */
+const isUsableId = (id) => typeof id === 'string' && id.trim().length > 0 && !id.includes('/');
+/**
+ * Which of the three credential states a connection declares. Derived from the declaration, never
+ * from a missing key: without the explicit `user` state, a connection that needs a reader's key
+ * would be indistinguishable from one that needs none.
+ */
+const aiCredentialKind = (connection) => {
+    if (connection.credential === 'user')
+        return 'user';
+    return connection.apiKeyEnv ? 'service' : 'none';
+};
+exports.aiCredentialKind = aiCredentialKind;
+/** Split `<connectionId>/<model>`. Only the first slash separates them, since model ids carry slashes. */
+const parseAiModelId = (value) => {
+    const separator = value.indexOf('/');
+    if (separator <= 0 || separator === value.length - 1)
+        return null;
+    return { connectionId: value.slice(0, separator), model: value.slice(separator + 1) };
+};
+exports.parseAiModelId = parseAiModelId;
+/** Join a connection id and a model into the address the client sends back. */
+const formatAiModelId = (connectionId, model) => `${connectionId}/${model}`;
+exports.formatAiModelId = formatAiModelId;
+/** Normalize one authored or deployment-supplied connection, dropping anything unusable. */
+const toConnectionSettings = (input) => {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return null;
+    const raw = input;
+    if (!isUsableId(raw.id))
+        return null;
+    const baseUrl = typeof raw.baseUrl === 'string' ? raw.baseUrl.trim() : undefined;
+    const module = typeof raw.module === 'string' ? raw.module.trim() : undefined;
+    if (!baseUrl && !module)
+        return null;
+    // An authored config carries `apiKey` as a deferred `{ $env }` reference; a baked or
+    // deployment-supplied list carries the name it resolved to.
+    const reference = raw.apiKey;
+    const apiKeyEnv = typeof raw.apiKeyEnv === 'string' && raw.apiKeyEnv.trim()
+        ? raw.apiKeyEnv.trim()
+        : typeof (reference === null || reference === void 0 ? void 0 : reference.$env) === 'string'
+            ? reference.$env
+            : undefined;
+    // A repeated model would be two picker entries for one choice, so the first occurrence wins.
+    const models = Array.isArray(raw.models)
+        ? [...new Set(raw.models.filter((model) => typeof model === 'string' && !!model.trim()).map((model) => model.trim()))]
+        : [];
+    const options = raw.options && typeof raw.options === 'object' && !Array.isArray(raw.options) ? raw.options : undefined;
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ id: raw.id.trim(), label: typeof raw.label === 'string' && raw.label.trim() ? raw.label.trim() : raw.id.trim() }, (baseUrl ? { baseUrl } : {})), (module ? { module } : {})), (apiKeyEnv ? { apiKeyEnv } : {})), (raw.credential === 'user' ? { credential: 'user' } : {})), (models.length ? { models } : {})), (options ? { options } : {}));
+};
+/** Normalize a declared list, keeping the first entry for any repeated id. */
+const toConnectionList = (input) => {
+    const byId = new Map();
+    for (const entry of input !== null && input !== void 0 ? input : []) {
+        const connection = toConnectionSettings(entry);
+        if (connection && !byId.has(connection.id))
+            byId.set(connection.id, connection);
+    }
+    return [...byId.values()];
+};
+/**
+ * Merge a deployment-supplied list over the baked one by `id`: a matching id replaces the baked
+ * connection outright, and a new id is appended. Replacement rather than a field-wise merge, so a
+ * deployment that repoints a gateway cannot leave a stale model list or key name behind.
+ */
+const mergeAiConnections = (baked, overrides) => {
+    const byId = new Map(baked.map((connection) => [connection.id, connection]));
+    for (const connection of overrides)
+        byId.set(connection.id, connection);
+    return [...byId.values()];
+};
+exports.mergeAiConnections = mergeAiConnections;
+/** Parse the `HANDOFF_AI_CONNECTIONS` JSON array. A malformed value is ignored rather than fatal. */
+const parseAiConnections = (raw) => {
+    if (!(raw === null || raw === void 0 ? void 0 : raw.trim()))
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? toConnectionList(parsed) : [];
+    }
+    catch (_a) {
+        return [];
+    }
+};
+exports.parseAiConnections = parseAiConnections;
+/**
+ * Whether this build serves the assistant. The `ai` block is the opt-in; `enabled: false` turns it
+ * back off. Config-only and baked, like `runtime.mcp`.
+ */
+const isAiEnabled = (config) => { var _a, _b, _c; return Boolean((_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.ai) && ((_c = (_b = config === null || config === void 0 ? void 0 : config.runtime) === null || _b === void 0 ? void 0 : _b.ai) === null || _c === void 0 ? void 0 : _c.enabled) !== false; };
+exports.isAiEnabled = isAiEnabled;
+/**
+ * Resolve the AI settings from a loaded config (CLI/build side).
+ *
+ * An authored connection that cannot be used fails the build rather than disappearing. A deployment
+ * list stays lenient by contrast: a bad `HANDOFF_AI_CONNECTIONS` entry must not take the server down.
+ */
+const resolveAiFromConfig = (config) => {
+    var _a, _b, _c, _d, _e, _f;
+    const authored = ((_c = (_b = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.ai) === null || _b === void 0 ? void 0 : _b.connections) !== null && _c !== void 0 ? _c : []);
+    const fail = (problem, ids) => {
+        throw new errors_1.HandoffConfigError(`Config "runtime.ai.connections": ${problem} (${ids.map((id) => JSON.stringify(id !== null && id !== void 0 ? id : null)).join(', ')}).`);
+    };
+    const normalized = authored.map((connection) => ({ authored: connection, settings: toConnectionSettings(connection) }));
+    const unusable = normalized.filter((entry) => !entry.settings);
+    if (unusable.length > 0) {
+        fail('every connection needs an "id" without a slash, and either a "baseUrl" or a "module"', unusable.map((entry) => { var _a; return (_a = entry.authored) === null || _a === void 0 ? void 0 : _a.id; }));
+    }
+    const ids = normalized.map((entry) => entry.settings.id);
+    const duplicates = ids.filter((id, index) => ids.indexOf(id) !== index);
+    if (duplicates.length > 0) {
+        fail('a connection id must be unique, because it is half of every model address', duplicates);
+    }
+    return {
+        enabled: (0, exports.isAiEnabled)(config),
+        connections: normalized.map((entry) => entry.settings),
+        defaultModel: ((_f = (_e = (_d = config === null || config === void 0 ? void 0 : config.runtime) === null || _d === void 0 ? void 0 : _d.ai) === null || _e === void 0 ? void 0 : _e.defaultModel) === null || _f === void 0 ? void 0 : _f.trim()) || undefined,
+    };
+};
+exports.resolveAiFromConfig = resolveAiFromConfig;

package/dist/ai/define.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Typed identity helper for custom AI providers (mirrors `defineAssetStorage`): a consumer
+ * default-exports its result from a **server-only** module and points a connection's `module` at
+ * it. It must be its own module (not an inline `defineConfig` function) so the build can trace it
+ * into the deployed registry. The default export may be the provider object, or a factory
+ * `(context) => AiProvider` when it needs its options, env or the resolved key.
+ */
+import type { AiProvider, AiProviderFactory } from './types';
+export declare function defineAiProvider(provider: AiProvider): AiProvider;
+export declare function defineAiProvider(factory: AiProviderFactory): AiProviderFactory;

package/dist/ai/define.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Typed identity helper for custom AI providers (mirrors `defineAssetStorage`): a consumer
+ * default-exports its result from a **server-only** module and points a connection's `module` at
+ * it. It must be its own module (not an inline `defineConfig` function) so the build can trace it
+ * into the deployed registry. The default export may be the provider object, or a factory
+ * `(context) => AiProvider` when it needs its options, env or the resolved key.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAiProvider = defineAiProvider;
+function defineAiProvider(input) {
+    return input;
+}

package/dist/ai/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Server-only AI provider contract for connections that are not OpenAI-compatible.
+ *
+ * Every built-in connection speaks the OpenAI-compatible `/chat/completions` API and needs no
+ * adapter — Ollama, LiteLLM, OpenRouter, vLLM, LM Studio and Azure OpenAI all serve it, and each of
+ * them fronts Anthropic, Google and xAI models. A provider that fits nothing else names a
+ * {@link defineAiProvider} module instead of a base URL.
+ */
+import type { LanguageModel } from 'ai';
+/** Context passed to a custom provider factory: its non-secret options, the process env, and the resolved key. */
+export interface AiProviderContext {
+    /** Non-secret options from the connection's `options`. Put env-var *names* here, never values. */
+    options: Record<string, unknown>;
+    /** The process environment. Read secret *values* here by the env-var *names* carried in options. */
+    env: NodeJS.ProcessEnv;
+    /**
+     * The resolved key for this request: the deployment's own key for a service connection, or the
+     * reader's saved key for a `credential: 'user'` connection. Undefined when neither applies.
+     */
+    apiKey?: string;
+}
+/** The pluggable provider contract: resolve one of the connection's declared models. */
+export interface AiProvider {
+    languageModel(modelId: string): LanguageModel;
+}
+/** A custom provider may export the provider directly or a factory that builds it from its context. */
+export type AiProviderFactory = (context: AiProviderContext) => AiProvider | Promise<AiProvider>;

package/dist/ai/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Server-only AI provider contract for connections that are not OpenAI-compatible.
+ *
+ * Every built-in connection speaks the OpenAI-compatible `/chat/completions` API and needs no
+ * adapter — Ollama, LiteLLM, OpenRouter, vLLM, LM Studio and Azure OpenAI all serve it, and each of
+ * them fronts Anthropic, Google and xAI models. A provider that fits nothing else names a
+ * {@link defineAiProvider} module instead of a base URL.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });