@elytracms/studio 0.0.52 → 0.0.54

package/dist/customization.js

@@ -38,15 +38,15 @@
  * createStudio(config, studioConfig)
  * ```
  */
-export { defineStudio } from './components/app-views/studio-config';
-export { nav } from './components/app-views/default-modules';
-export { createStudio } from './lib/workspace';
+export { defineStudio } from './components/app-views/studio-config.js';
+export { nav } from './components/app-views/default-modules.js';
+export { createStudio } from './lib/workspace/index.js';
 /** A ready-made example renderer; a consuming repo may use it or author its own. */
-export { colorFieldRenderer } from './components/cms/field-renderer';
+export { colorFieldRenderer } from './components/cms/field-renderer.js';
 /**
  * Studio-UI localization (EC-241): author a translation catalog for `defineStudio({
  * i18n })`. `msg` is only needed to build an in-repo *source* catalog with translator
  * hints; a plain `MessageCatalog` (flat key → string) is all a consumer supplies.
  */
-export { msg } from './lib/i18n';
+export { msg } from './lib/i18n/index.js';
 //# sourceMappingURL=customization.js.map

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

@@ -10,7 +10,7 @@
  * dependency, never in `packages/core`. Key custody stays with the host: the key is
  * read from host env by the mount and passed in (or falls back to `ANTHROPIC_API_KEY`).
  */
-import type { AiProvider } from './types';
+import type { AiProvider } from './types.js';
 export interface AnthropicProviderOptions {
     /** Provider key (host-env secret). Falls back to the SDK's `ANTHROPIC_API_KEY` lookup. */
     apiKey?: string;

package/dist/lib/ai/apply-content.d.ts

@@ -1,4 +1,4 @@
-import type { ApplyContentInput, ApplyContentResult } from './types';
+import type { ApplyContentInput, ApplyContentResult } from './types.js';
 /** Default repair attempts after the first generation. */
 export declare const DEFAULT_MAX_REPAIR_ATTEMPTS = 2;
 /**

package/dist/lib/ai/apply-content.js

@@ -19,9 +19,9 @@
  * whole loop without a key. No data access, no service credentials here.
  */
 import { assetNode, referenceNode, resolveLabel, validateDocument } from '@elytracms/core/cms-core';
-import { assembleKnowledgeBlock } from './knowledge';
-import { aiProvenance } from './provenance';
-import { buildTargetShape } from './shape';
+import { assembleKnowledgeBlock } from './knowledge.js';
+import { aiProvenance } from './provenance.js';
+import { buildTargetShape } from './shape.js';
 /** Default repair attempts after the first generation. */
 export const DEFAULT_MAX_REPAIR_ATTEMPTS = 2;
 const SYSTEM_PROMPT = [

package/dist/lib/ai/chat-state.d.ts

@@ -9,8 +9,8 @@
  * every run (determinism principle).
  */
 import type { FieldValues } from '@elytracms/core/cms-core';
-import type { AiProvenance, ContentPatch } from './types';
-import type { CreateFlowResult, CreateFlowStep, ProposalOrigin } from './create-flow';
+import type { AiProvenance, ContentPatch } from './types.js';
+import type { CreateFlowResult, CreateFlowStep, ProposalOrigin } from './create-flow.js';
 /** A proposal the editor reviews as a diff and then applies (as a draft) or rejects. */
 export interface ProposalReview {
     id: string;

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

@@ -13,7 +13,7 @@
  * never pulls the AI SDK. When `enabled: false`, the gate is skipped (nothing loads).
  */
 import { z } from 'zod';
-import type { AiLimits, AiProvider, KnowledgeSource, StudioAiConfig } from './types';
+import type { AiLimits, AiProvider, KnowledgeSource, StudioAiConfig } from './types.js';
 export declare const AI_CONFIG_ISSUE_CODES: readonly ["invalid-config-shape", "missing-provider", "provider-missing-capabilities", "provider-not-callable"];
 export type AiConfigIssueCode = (typeof AI_CONFIG_ISSUE_CODES)[number];
 /** A structured, path-located `ai`-config issue (never thrown — collected). */

package/dist/lib/ai/convex-session-headers.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `createConvexSessionHeaders` — the CLIENT half of the engine-default AI session
+ * gate (EC-371). It supplies the `headers` thunk `createRouteProvider` re-evaluates
+ * per request, attaching the signed-in user's Convex Auth JWT as
+ * `authorization: Bearer <token>` so the route's {@link createConvexJwtSessionResolver}
+ * can verify it against the deployment's JWKS.
+ *
+ * Two storage conventions, owned HERE and nowhere else:
+ *
+ * 1. **The engine's own session store (primary).** The studio's `ConvexAuthAdapter`
+ *    (`lib/auth`) persists the JWT in `sessionStorage` under
+ *    `elytra.convex-auth.jwt` / `elytra.convex-auth.jwt::<deployment-url>`
+ *    (per-backend sessions, EC-179). This covers every engine studio sign-in,
+ *    including the dev-login path. The prefix is pinned against `tokenStorageKey()`
+ *    by a drift test in `convex-session-headers.test.ts` — if `lib/auth` ever
+ *    renames it, that test fails loudly.
+ * 2. **The `@convex-dev/auth` react-client store (fallback).** Hosts that mount the
+ *    official `ConvexAuthProvider` get the JWT persisted in `localStorage` under a
+ *    key starting with `__convexAuthJWT` — an INTERNAL convention of that package,
+ *    not a public API. If a future upgrade renames it, the token is simply not
+ *    found and the assistant fails CLOSED (401) — never open.
+ *
+ * A playground/local studio has no Convex session, so the thunk returns `undefined`
+ * (no auth header); the route then rejects unless the loud dev-only opt-in on
+ * `createAiDevPlugin` is active. Browser-only reads; SSR yields no header.
+ *
+ * Note on multiple per-backend sessions: the scan returns the first token found;
+ * a token minted by a DIFFERENT deployment fails the route's issuer/JWKS check and
+ * yields 401 (fail-closed), never a cross-deployment pass.
+ */
+/**
+ * The engine `ConvexAuthAdapter` sessionStorage key prefix (`lib/auth`,
+ * `tokenStorageKey()`), duplicated here so `lib/ai` carries no runtime edge into
+ * the auth adapter (which pulls the Convex client). Drift-pinned by test.
+ */
+export declare const ELYTRA_CONVEX_JWT_STORAGE_PREFIX = "elytra.convex-auth.jwt";
+/** The `@convex-dev/auth`-internal localStorage key prefix carrying the fresh JWT. */
+export declare const CONVEX_AUTH_JWT_STORAGE_PREFIX = "__convexAuthJWT";
+/** The read-only subset of DOM `Storage` the token scan needs (test seam). */
+export interface TokenStorageLike {
+    readonly length: number;
+    key(index: number): string | null;
+    getItem(key: string): string | null;
+}
+/** First non-empty value under a key starting with `prefix`; `null` when absent. */
+export declare function readTokenByPrefix(storage: TokenStorageLike | null | undefined, prefix: string): string | null;
+export interface ConvexSessionStorages {
+    /** The engine adapter's store (default: `window.sessionStorage`). */
+    sessionStorage?: TokenStorageLike | null;
+    /** The @convex-dev/auth react-client store (default: `window.localStorage`). */
+    localStorage?: TokenStorageLike | null;
+}
+/**
+ * Read the current Convex Auth JWT: the engine's sessionStorage convention first,
+ * then the `@convex-dev/auth` localStorage convention. Pure over the injected
+ * storages; `null` when signed out (or outside a browser).
+ */
+export declare function readConvexAuthToken(storages: ConvexSessionStorages): string | null;
+export interface ConvexSessionHeadersOptions {
+    /** Storage accessor override (default: the browser's session/local storages). */
+    storages?: () => ConvexSessionStorages;
+}
+/**
+ * Build the `headers` thunk for `createRouteProvider({ headers })`. Re-evaluated on
+ * every request, so a refreshed token is picked up automatically; `undefined` (no
+ * header) when no session token exists.
+ */
+export declare function createConvexSessionHeaders(options?: ConvexSessionHeadersOptions): () => HeadersInit | undefined;

package/dist/lib/ai/convex-session-headers.js

@@ -0,0 +1,79 @@
+/**
+ * `createConvexSessionHeaders` — the CLIENT half of the engine-default AI session
+ * gate (EC-371). It supplies the `headers` thunk `createRouteProvider` re-evaluates
+ * per request, attaching the signed-in user's Convex Auth JWT as
+ * `authorization: Bearer <token>` so the route's {@link createConvexJwtSessionResolver}
+ * can verify it against the deployment's JWKS.
+ *
+ * Two storage conventions, owned HERE and nowhere else:
+ *
+ * 1. **The engine's own session store (primary).** The studio's `ConvexAuthAdapter`
+ *    (`lib/auth`) persists the JWT in `sessionStorage` under
+ *    `elytra.convex-auth.jwt` / `elytra.convex-auth.jwt::<deployment-url>`
+ *    (per-backend sessions, EC-179). This covers every engine studio sign-in,
+ *    including the dev-login path. The prefix is pinned against `tokenStorageKey()`
+ *    by a drift test in `convex-session-headers.test.ts` — if `lib/auth` ever
+ *    renames it, that test fails loudly.
+ * 2. **The `@convex-dev/auth` react-client store (fallback).** Hosts that mount the
+ *    official `ConvexAuthProvider` get the JWT persisted in `localStorage` under a
+ *    key starting with `__convexAuthJWT` — an INTERNAL convention of that package,
+ *    not a public API. If a future upgrade renames it, the token is simply not
+ *    found and the assistant fails CLOSED (401) — never open.
+ *
+ * A playground/local studio has no Convex session, so the thunk returns `undefined`
+ * (no auth header); the route then rejects unless the loud dev-only opt-in on
+ * `createAiDevPlugin` is active. Browser-only reads; SSR yields no header.
+ *
+ * Note on multiple per-backend sessions: the scan returns the first token found;
+ * a token minted by a DIFFERENT deployment fails the route's issuer/JWKS check and
+ * yields 401 (fail-closed), never a cross-deployment pass.
+ */
+/**
+ * The engine `ConvexAuthAdapter` sessionStorage key prefix (`lib/auth`,
+ * `tokenStorageKey()`), duplicated here so `lib/ai` carries no runtime edge into
+ * the auth adapter (which pulls the Convex client). Drift-pinned by test.
+ */
+export const ELYTRA_CONVEX_JWT_STORAGE_PREFIX = 'elytra.convex-auth.jwt';
+/** The `@convex-dev/auth`-internal localStorage key prefix carrying the fresh JWT. */
+export const CONVEX_AUTH_JWT_STORAGE_PREFIX = '__convexAuthJWT';
+/** First non-empty value under a key starting with `prefix`; `null` when absent. */
+export function readTokenByPrefix(storage, prefix) {
+    if (!storage)
+        return null;
+    for (let i = 0; i < storage.length; i += 1) {
+        const key = storage.key(i);
+        if (!key?.startsWith(prefix))
+            continue;
+        const token = storage.getItem(key);
+        if (token)
+            return token;
+    }
+    return null;
+}
+/**
+ * Read the current Convex Auth JWT: the engine's sessionStorage convention first,
+ * then the `@convex-dev/auth` localStorage convention. Pure over the injected
+ * storages; `null` when signed out (or outside a browser).
+ */
+export function readConvexAuthToken(storages) {
+    return (readTokenByPrefix(storages.sessionStorage, ELYTRA_CONVEX_JWT_STORAGE_PREFIX) ??
+        readTokenByPrefix(storages.localStorage, CONVEX_AUTH_JWT_STORAGE_PREFIX));
+}
+function browserStorages() {
+    if (typeof window === 'undefined')
+        return {};
+    return { sessionStorage: window.sessionStorage, localStorage: window.localStorage };
+}
+/**
+ * Build the `headers` thunk for `createRouteProvider({ headers })`. Re-evaluated on
+ * every request, so a refreshed token is picked up automatically; `undefined` (no
+ * header) when no session token exists.
+ */
+export function createConvexSessionHeaders(options = {}) {
+    const storages = options.storages ?? browserStorages;
+    return () => {
+        const token = readConvexAuthToken(storages());
+        return token ? { authorization: `Bearer ${token}` } : undefined;
+    };
+}
+//# sourceMappingURL=convex-session-headers.js.map

package/dist/lib/ai/convex-session-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex-session-headers.js","sourceRoot":"","sources":["../../../src/lib/ai/convex-session-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,wBAAwB,CAAA;AAExE,sFAAsF;AACtF,MAAM,CAAC,MAAM,8BAA8B,GAAG,iBAAiB,CAAA;AAS/D,oFAAoF;AACpF,MAAM,UAAU,iBAAiB,CAC/B,OAA4C,EAC5C,MAAc;IAEd,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAA;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QAC1B,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC;YAAE,SAAQ;QACtC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,KAAK;YAAE,OAAO,KAAK,CAAA;IACzB,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AASD;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA+B;IACjE,OAAO,CACL,iBAAiB,CAAC,QAAQ,CAAC,cAAc,EAAE,gCAAgC,CAAC;QAC5E,iBAAiB,CAAC,QAAQ,CAAC,YAAY,EAAE,8BAA8B,CAAC,CACzE,CAAA;AACH,CAAC;AAOD,SAAS,eAAe;IACtB,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,EAAE,CAAA;IAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAA;AACrF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,UAAuC,EAAE;IAEzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAA;IACpD,OAAO,GAAG,EAAE;QACV,MAAM,KAAK,GAAG,mBAAmB,CAAC,QAAQ,EAAE,CAAC,CAAA;QAC7C,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;IACjE,CAAC,CAAA;AACH,CAAC","sourcesContent":["/**\n * `createConvexSessionHeaders` — the CLIENT half of the engine-default AI session\n * gate (EC-371). It supplies the `headers` thunk `createRouteProvider` re-evaluates\n * per request, attaching the signed-in user's Convex Auth JWT as\n * `authorization: Bearer <token>` so the route's {@link createConvexJwtSessionResolver}\n * can verify it against the deployment's JWKS.\n *\n * Two storage conventions, owned HERE and nowhere else:\n *\n * 1. **The engine's own session store (primary).** The studio's `ConvexAuthAdapter`\n *    (`lib/auth`) persists the JWT in `sessionStorage` under\n *    `elytra.convex-auth.jwt` / `elytra.convex-auth.jwt::<deployment-url>`\n *    (per-backend sessions, EC-179). This covers every engine studio sign-in,\n *    including the dev-login path. The prefix is pinned against `tokenStorageKey()`\n *    by a drift test in `convex-session-headers.test.ts` — if `lib/auth` ever\n *    renames it, that test fails loudly.\n * 2. **The `@convex-dev/auth` react-client store (fallback).** Hosts that mount the\n *    official `ConvexAuthProvider` get the JWT persisted in `localStorage` under a\n *    key starting with `__convexAuthJWT` — an INTERNAL convention of that package,\n *    not a public API. If a future upgrade renames it, the token is simply not\n *    found and the assistant fails CLOSED (401) — never open.\n *\n * A playground/local studio has no Convex session, so the thunk returns `undefined`\n * (no auth header); the route then rejects unless the loud dev-only opt-in on\n * `createAiDevPlugin` is active. Browser-only reads; SSR yields no header.\n *\n * Note on multiple per-backend sessions: the scan returns the first token found;\n * a token minted by a DIFFERENT deployment fails the route's issuer/JWKS check and\n * yields 401 (fail-closed), never a cross-deployment pass.\n */\n\n/**\n * The engine `ConvexAuthAdapter` sessionStorage key prefix (`lib/auth`,\n * `tokenStorageKey()`), duplicated here so `lib/ai` carries no runtime edge into\n * the auth adapter (which pulls the Convex client). Drift-pinned by test.\n */\nexport const ELYTRA_CONVEX_JWT_STORAGE_PREFIX = 'elytra.convex-auth.jwt'\n\n/** The `@convex-dev/auth`-internal localStorage key prefix carrying the fresh JWT. */\nexport const CONVEX_AUTH_JWT_STORAGE_PREFIX = '__convexAuthJWT'\n\n/** The read-only subset of DOM `Storage` the token scan needs (test seam). */\nexport interface TokenStorageLike {\n  readonly length: number\n  key(index: number): string | null\n  getItem(key: string): string | null\n}\n\n/** First non-empty value under a key starting with `prefix`; `null` when absent. */\nexport function readTokenByPrefix(\n  storage: TokenStorageLike | null | undefined,\n  prefix: string,\n): string | null {\n  if (!storage) return null\n  for (let i = 0; i < storage.length; i += 1) {\n    const key = storage.key(i)\n    if (!key?.startsWith(prefix)) continue\n    const token = storage.getItem(key)\n    if (token) return token\n  }\n  return null\n}\n\nexport interface ConvexSessionStorages {\n  /** The engine adapter's store (default: `window.sessionStorage`). */\n  sessionStorage?: TokenStorageLike | null\n  /** The @convex-dev/auth react-client store (default: `window.localStorage`). */\n  localStorage?: TokenStorageLike | null\n}\n\n/**\n * Read the current Convex Auth JWT: the engine's sessionStorage convention first,\n * then the `@convex-dev/auth` localStorage convention. Pure over the injected\n * storages; `null` when signed out (or outside a browser).\n */\nexport function readConvexAuthToken(storages: ConvexSessionStorages): string | null {\n  return (\n    readTokenByPrefix(storages.sessionStorage, ELYTRA_CONVEX_JWT_STORAGE_PREFIX) ??\n    readTokenByPrefix(storages.localStorage, CONVEX_AUTH_JWT_STORAGE_PREFIX)\n  )\n}\n\nexport interface ConvexSessionHeadersOptions {\n  /** Storage accessor override (default: the browser's session/local storages). */\n  storages?: () => ConvexSessionStorages\n}\n\nfunction browserStorages(): ConvexSessionStorages {\n  if (typeof window === 'undefined') return {}\n  return { sessionStorage: window.sessionStorage, localStorage: window.localStorage }\n}\n\n/**\n * Build the `headers` thunk for `createRouteProvider({ headers })`. Re-evaluated on\n * every request, so a refreshed token is picked up automatically; `undefined` (no\n * header) when no session token exists.\n */\nexport function createConvexSessionHeaders(\n  options: ConvexSessionHeadersOptions = {},\n): () => HeadersInit | undefined {\n  const storages = options.storages ?? browserStorages\n  return () => {\n    const token = readConvexAuthToken(storages())\n    return token ? { authorization: `Bearer ${token}` } : undefined\n  }\n}\n"]}

package/dist/lib/ai/convex-session.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `createConvexJwtSessionResolver` — the engine-default `getSession` for
+ * {@link createAiRouteHandler} (EC-371; closes EC-369 finding #1, where the template
+ * shipped an auth-shaped no-op that accepted any caller with a non-empty marker
+ * header).
+ *
+ * REAL verification, fail-closed: the studio client attaches the signed-in user's
+ * Convex Auth JWT (`authorization: Bearer …`, see `createConvexSessionHeaders`), and
+ * this resolver verifies signature / issuer / audience / expiry against the Convex
+ * deployment's public JWKS (`<site-url>/.well-known/jwks.json`). Only a signed-in
+ * studio user of THIS deployment can spend the route's provider key. No token,
+ * an invalid token, or missing site-URL env → `null` → the route answers 401.
+ *
+ * The deployment's site URL (JWT issuer + JWKS host) resolves from, in order:
+ * the explicit `siteUrl` option, `VITE_CONVEX_SITE_URL`, or `VITE_CONVEX_URL`
+ * (`….convex.cloud` mapped to `….convex.site`). In a Vite-dev mount these are
+ * surfaced to `process.env` by {@link createAiDevPlugin}'s `loadEnv` bridge.
+ *
+ * Dev-only anonymous escape hatch (playground DX): a playground/local studio has no
+ * Convex session at all, so the assistant panel would 401 there. Anonymous requests
+ * (NO credential presented) may pass ONLY when the loud
+ * {@link INSECURE_ANONYMOUS_SESSION_ENV_VAR} handshake is active — set exclusively by
+ * `createAiDevPlugin`'s explicit `insecureAllowAnonymousSessions` opt-in under
+ * `vite dev` (the plugin is `apply: 'serve'`, so no production build ever carries it)
+ * AND additionally gated on `NODE_ENV !== 'production'`. A PRESENTED token must
+ * always verify for real — the bypass never masks an invalid credential.
+ *
+ * `jose` is loaded via dynamic `import()` so this module can sit in the barrel
+ * without putting the JWT library on the studio client's critical path (the same
+ * discipline `anthropic-provider` applies to the AI SDK; pinned in `bundle.test.ts`).
+ */
+import type { JWTVerifyGetKey } from 'jose';
+import type { AiSession } from './types.js';
+/** A `getSession` implementation for {@link AiRouteHandlerOptions.getSession}. */
+export type AiSessionResolver = (request: Request) => Promise<AiSession | null>;
+/**
+ * The dev-bypass handshake env var. Set ONLY by `createAiDevPlugin` (vite dev) when
+ * the host explicitly opts in via `insecureAllowAnonymousSessions`. Never set this
+ * on a deployment: the name says exactly what it does.
+ */
+export declare const INSECURE_ANONYMOUS_SESSION_ENV_VAR = "ELYTRA_AI_INSECURE_ALLOW_ANONYMOUS";
+/** The exact value the handshake requires (anything else is ignored, fail-closed). */
+export declare const INSECURE_ANONYMOUS_SESSION_ENV_VALUE = "dev-only";
+/** The synthetic principal id an insecure dev-anonymous session carries. */
+export declare const INSECURE_ANONYMOUS_USER_ID = "insecure-anonymous-dev";
+/** An env bag (defaults to `process.env`, read per-request). */
+export type EnvSource = Record<string, string | undefined>;
+export interface ConvexJwtSessionResolverOptions {
+    /**
+     * The Convex deployment's SITE url — the JWT issuer and JWKS host (e.g.
+     * `https://your-deployment-123.convex.site`). Default: resolved from env via
+     * {@link resolveConvexSiteUrl}. Missing everywhere ⇒ fail closed (nobody passes).
+     */
+    siteUrl?: string;
+    /** Expected JWT audience (default `convex` — what Convex Auth mints). */
+    audience?: string;
+    /** Env source override (default `process.env`, read per-request). */
+    env?: EnvSource;
+    /**
+     * Key source override — primarily a test seam (a `createLocalJWKSet` over a
+     * locally generated pair). Default: the deployment's remote JWKS.
+     */
+    getKey?: JWTVerifyGetKey;
+}
+/**
+ * Resolve the Convex SITE url (JWT issuer + JWKS host) from env:
+ * `VITE_CONVEX_SITE_URL`, else derived from `VITE_CONVEX_URL`
+ * (`….convex.cloud` → `….convex.site`), else `null` (fail closed).
+ */
+export declare function resolveConvexSiteUrl(env: EnvSource): string | null;
+/**
+ * True when the dev-only anonymous handshake is active: the loud env var carries its
+ * exact value AND the process is not a production one. Both conditions are required —
+ * setting the var on a production deployment does nothing.
+ */
+export declare function insecureAnonymousSessionActive(env: EnvSource): boolean;
+/**
+ * Build the engine-default `getSession`: verify the caller's Convex Auth Bearer JWT
+ * against the deployment's public JWKS; every failure resolves `null` (→ 401), never
+ * throws. See the module doc for the full contract.
+ */
+export declare function createConvexJwtSessionResolver(options?: ConvexJwtSessionResolverOptions): AiSessionResolver;

package/dist/lib/ai/convex-session.js

@@ -0,0 +1,92 @@
+/**
+ * The dev-bypass handshake env var. Set ONLY by `createAiDevPlugin` (vite dev) when
+ * the host explicitly opts in via `insecureAllowAnonymousSessions`. Never set this
+ * on a deployment: the name says exactly what it does.
+ */
+export const INSECURE_ANONYMOUS_SESSION_ENV_VAR = 'ELYTRA_AI_INSECURE_ALLOW_ANONYMOUS';
+/** The exact value the handshake requires (anything else is ignored, fail-closed). */
+export const INSECURE_ANONYMOUS_SESSION_ENV_VALUE = 'dev-only';
+/** The synthetic principal id an insecure dev-anonymous session carries. */
+export const INSECURE_ANONYMOUS_USER_ID = 'insecure-anonymous-dev';
+/**
+ * Resolve the Convex SITE url (JWT issuer + JWKS host) from env:
+ * `VITE_CONVEX_SITE_URL`, else derived from `VITE_CONVEX_URL`
+ * (`….convex.cloud` → `….convex.site`), else `null` (fail closed).
+ */
+export function resolveConvexSiteUrl(env) {
+    const site = env.VITE_CONVEX_SITE_URL?.trim();
+    if (site)
+        return site.replace(/\/$/, '');
+    const cloud = env.VITE_CONVEX_URL?.trim();
+    if (cloud)
+        return cloud.replace(/\/$/, '').replace('.convex.cloud', '.convex.site');
+    return null;
+}
+/**
+ * True when the dev-only anonymous handshake is active: the loud env var carries its
+ * exact value AND the process is not a production one. Both conditions are required —
+ * setting the var on a production deployment does nothing.
+ */
+export function insecureAnonymousSessionActive(env) {
+    return (env[INSECURE_ANONYMOUS_SESSION_ENV_VAR] === INSECURE_ANONYMOUS_SESSION_ENV_VALUE &&
+        env.NODE_ENV !== 'production');
+}
+function processEnv() {
+    return typeof process !== 'undefined' ? process.env : {};
+}
+let josePromise = null;
+function loadJose() {
+    return (josePromise ??= import('jose'));
+}
+let warnedInsecureAnonymous = false;
+function insecureAnonymousSession() {
+    if (!warnedInsecureAnonymous) {
+        warnedInsecureAnonymous = true;
+        console.warn(`[elytra-ai] INSECURE anonymous AI session bypass is ACTIVE (${INSECURE_ANONYMOUS_SESSION_ENV_VAR}). ` +
+            'This is a dev-only playground convenience — if you ever see this on a deployment, remove the env var immediately.');
+    }
+    return { userId: INSECURE_ANONYMOUS_USER_ID };
+}
+/**
+ * Build the engine-default `getSession`: verify the caller's Convex Auth Bearer JWT
+ * against the deployment's public JWKS; every failure resolves `null` (→ 401), never
+ * throws. See the module doc for the full contract.
+ */
+export function createConvexJwtSessionResolver(options = {}) {
+    const audience = options.audience ?? 'convex';
+    // Remote JWKS getters are cached per site URL (jose caches the fetched keys inside).
+    const remoteKeys = new Map();
+    return async (request) => {
+        const env = options.env ?? processEnv();
+        const authorization = request.headers.get('authorization');
+        const token = authorization?.startsWith('Bearer ')
+            ? authorization.slice('Bearer '.length)
+            : null;
+        if (!token) {
+            // No credential presented. The ONLY way this passes is the loud, dev-only
+            // anonymous opt-in (set by `createAiDevPlugin` under `vite dev`).
+            return insecureAnonymousSessionActive(env) ? insecureAnonymousSession() : null;
+        }
+        // A presented token must ALWAYS verify for real — the dev bypass never masks
+        // an invalid credential.
+        const siteUrl = options.siteUrl?.replace(/\/$/, '') ?? resolveConvexSiteUrl(env);
+        if (!siteUrl)
+            return null; // fail closed: gate env missing → nobody passes
+        try {
+            const jose = await loadJose();
+            let getKey = options.getKey ?? remoteKeys.get(siteUrl);
+            if (!getKey) {
+                getKey = jose.createRemoteJWKSet(new URL('/.well-known/jwks.json', siteUrl));
+                remoteKeys.set(siteUrl, getKey);
+            }
+            const { payload } = await jose.jwtVerify(token, getKey, { issuer: siteUrl, audience });
+            return typeof payload.sub === 'string' && payload.sub.length > 0
+                ? { userId: payload.sub }
+                : null;
+        }
+        catch {
+            return null; // expired / bad signature / wrong issuer, audience, or deployment → 401
+        }
+    };
+}
+//# sourceMappingURL=convex-session.js.map

package/dist/lib/ai/convex-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex-session.js","sourceRoot":"","sources":["../../../src/lib/ai/convex-session.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `createConvexJwtSessionResolver` — the engine-default `getSession` for\n * {@link createAiRouteHandler} (EC-371; closes EC-369 finding #1, where the template\n * shipped an auth-shaped no-op that accepted any caller with a non-empty marker\n * header).\n *\n * REAL verification, fail-closed: the studio client attaches the signed-in user's\n * Convex Auth JWT (`authorization: Bearer …`, see `createConvexSessionHeaders`), and\n * this resolver verifies signature / issuer / audience / expiry against the Convex\n * deployment's public JWKS (`<site-url>/.well-known/jwks.json`). Only a signed-in\n * studio user of THIS deployment can spend the route's provider key. No token,\n * an invalid token, or missing site-URL env → `null` → the route answers 401.\n *\n * The deployment's site URL (JWT issuer + JWKS host) resolves from, in order:\n * the explicit `siteUrl` option, `VITE_CONVEX_SITE_URL`, or `VITE_CONVEX_URL`\n * (`….convex.cloud` mapped to `….convex.site`). In a Vite-dev mount these are\n * surfaced to `process.env` by {@link createAiDevPlugin}'s `loadEnv` bridge.\n *\n * Dev-only anonymous escape hatch (playground DX): a playground/local studio has no\n * Convex session at all, so the assistant panel would 401 there. Anonymous requests\n * (NO credential presented) may pass ONLY when the loud\n * {@link INSECURE_ANONYMOUS_SESSION_ENV_VAR} handshake is active — set exclusively by\n * `createAiDevPlugin`'s explicit `insecureAllowAnonymousSessions` opt-in under\n * `vite dev` (the plugin is `apply: 'serve'`, so no production build ever carries it)\n * AND additionally gated on `NODE_ENV !== 'production'`. A PRESENTED token must\n * always verify for real — the bypass never masks an invalid credential.\n *\n * `jose` is loaded via dynamic `import()` so this module can sit in the barrel\n * without putting the JWT library on the studio client's critical path (the same\n * discipline `anthropic-provider` applies to the AI SDK; pinned in `bundle.test.ts`).\n */\nimport type { JWTVerifyGetKey } from 'jose'\nimport type { AiSession } from './types'\n\n/** A `getSession` implementation for {@link AiRouteHandlerOptions.getSession}. */\nexport type AiSessionResolver = (request: Request) => Promise<AiSession | null>\n\n/**\n * The dev-bypass handshake env var. Set ONLY by `createAiDevPlugin` (vite dev) when\n * the host explicitly opts in via `insecureAllowAnonymousSessions`. Never set this\n * on a deployment: the name says exactly what it does.\n */\nexport const INSECURE_ANONYMOUS_SESSION_ENV_VAR = 'ELYTRA_AI_INSECURE_ALLOW_ANONYMOUS'\n\n/** The exact value the handshake requires (anything else is ignored, fail-closed). */\nexport const INSECURE_ANONYMOUS_SESSION_ENV_VALUE = 'dev-only'\n\n/** The synthetic principal id an insecure dev-anonymous session carries. */\nexport const INSECURE_ANONYMOUS_USER_ID = 'insecure-anonymous-dev'\n\n/** An env bag (defaults to `process.env`, read per-request). */\nexport type EnvSource = Record<string, string | undefined>\n\nexport interface ConvexJwtSessionResolverOptions {\n  /**\n   * The Convex deployment's SITE url — the JWT issuer and JWKS host (e.g.\n   * `https://your-deployment-123.convex.site`). Default: resolved from env via\n   * {@link resolveConvexSiteUrl}. Missing everywhere ⇒ fail closed (nobody passes).\n   */\n  siteUrl?: string\n  /** Expected JWT audience (default `convex` — what Convex Auth mints). */\n  audience?: string\n  /** Env source override (default `process.env`, read per-request). */\n  env?: EnvSource\n  /**\n   * Key source override — primarily a test seam (a `createLocalJWKSet` over a\n   * locally generated pair). Default: the deployment's remote JWKS.\n   */\n  getKey?: JWTVerifyGetKey\n}\n\n/**\n * Resolve the Convex SITE url (JWT issuer + JWKS host) from env:\n * `VITE_CONVEX_SITE_URL`, else derived from `VITE_CONVEX_URL`\n * (`….convex.cloud` → `….convex.site`), else `null` (fail closed).\n */\nexport function resolveConvexSiteUrl(env: EnvSource): string | null {\n  const site = env.VITE_CONVEX_SITE_URL?.trim()\n  if (site) return site.replace(/\\/$/, '')\n  const cloud = env.VITE_CONVEX_URL?.trim()\n  if (cloud) return cloud.replace(/\\/$/, '').replace('.convex.cloud', '.convex.site')\n  return null\n}\n\n/**\n * True when the dev-only anonymous handshake is active: the loud env var carries its\n * exact value AND the process is not a production one. Both conditions are required —\n * setting the var on a production deployment does nothing.\n */\nexport function insecureAnonymousSessionActive(env: EnvSource): boolean {\n  return (\n    env[INSECURE_ANONYMOUS_SESSION_ENV_VAR] === INSECURE_ANONYMOUS_SESSION_ENV_VALUE &&\n    env.NODE_ENV !== 'production'\n  )\n}\n\nfunction processEnv(): EnvSource {\n  return typeof process !== 'undefined' ? process.env : {}\n}\n\n// jose stays off the studio client's critical path: loaded on first verification only.\ntype JoseModule = typeof import('jose')\nlet josePromise: Promise<JoseModule> | null = null\nfunction loadJose(): Promise<JoseModule> {\n  return (josePromise ??= import('jose'))\n}\n\nlet warnedInsecureAnonymous = false\nfunction insecureAnonymousSession(): AiSession {\n  if (!warnedInsecureAnonymous) {\n    warnedInsecureAnonymous = true\n    console.warn(\n      `[elytra-ai] INSECURE anonymous AI session bypass is ACTIVE (${INSECURE_ANONYMOUS_SESSION_ENV_VAR}). ` +\n        'This is a dev-only playground convenience — if you ever see this on a deployment, remove the env var immediately.',\n    )\n  }\n  return { userId: INSECURE_ANONYMOUS_USER_ID }\n}\n\n/**\n * Build the engine-default `getSession`: verify the caller's Convex Auth Bearer JWT\n * against the deployment's public JWKS; every failure resolves `null` (→ 401), never\n * throws. See the module doc for the full contract.\n */\nexport function createConvexJwtSessionResolver(\n  options: ConvexJwtSessionResolverOptions = {},\n): AiSessionResolver {\n  const audience = options.audience ?? 'convex'\n  // Remote JWKS getters are cached per site URL (jose caches the fetched keys inside).\n  const remoteKeys = new Map<string, JWTVerifyGetKey>()\n\n  return async (request: Request): Promise<AiSession | null> => {\n    const env = options.env ?? processEnv()\n    const authorization = request.headers.get('authorization')\n    const token = authorization?.startsWith('Bearer ')\n      ? authorization.slice('Bearer '.length)\n      : null\n\n    if (!token) {\n      // No credential presented. The ONLY way this passes is the loud, dev-only\n      // anonymous opt-in (set by `createAiDevPlugin` under `vite dev`).\n      return insecureAnonymousSessionActive(env) ? insecureAnonymousSession() : null\n    }\n\n    // A presented token must ALWAYS verify for real — the dev bypass never masks\n    // an invalid credential.\n    const siteUrl = options.siteUrl?.replace(/\\/$/, '') ?? resolveConvexSiteUrl(env)\n    if (!siteUrl) return null // fail closed: gate env missing → nobody passes\n    try {\n      const jose = await loadJose()\n      let getKey = options.getKey ?? remoteKeys.get(siteUrl)\n      if (!getKey) {\n        getKey = jose.createRemoteJWKSet(new URL('/.well-known/jwks.json', siteUrl))\n        remoteKeys.set(siteUrl, getKey)\n      }\n      const { payload } = await jose.jwtVerify(token, getKey, { issuer: siteUrl, audience })\n      return typeof payload.sub === 'string' && payload.sub.length > 0\n        ? { userId: payload.sub }\n        : null\n    } catch {\n      return null // expired / bad signature / wrong issuer, audience, or deployment → 401\n    }\n  }\n}\n"]}

package/dist/lib/ai/create-flow.d.ts

@@ -21,8 +21,8 @@
  */
 import type { CmsDocument, CmsValidationIssue, CollectionDef, CollectionRegistry, FieldValues, LocaleConfig, ValidateDocumentOptions } from '@elytracms/core/cms-core';
 import type { ComponentManifest } from '@elytracms/core/component-registry';
-import type { AiProvenance, AiProvider, ContentPatch, ResolvedKnowledge } from './types';
-import type { CreateFlowTools } from './tools';
+import type { AiProvenance, AiProvider, ContentPatch, ResolvedKnowledge } from './types.js';
+import type { CreateFlowTools } from './tools.js';
 /** A progress event the UI renders as a tool-status affordance while the loop runs. */
 export type CreateFlowStep = {
     kind: 'search';

package/dist/lib/ai/create-flow.js

@@ -1,6 +1,6 @@
-import { applyContentWithShape } from './apply-content';
-import { translateDocument } from './translate-document';
-import { PLANNER_SCHEMA_NAME, parsePlannerAction, plannerSchema, } from './tools';
+import { applyContentWithShape } from './apply-content.js';
+import { translateDocument } from './translate-document.js';
+import { PLANNER_SCHEMA_NAME, parsePlannerAction, plannerSchema, } from './tools.js';
 export const DEFAULT_MAX_STEPS = 6;
 export const DEFAULT_SEARCH_LIMIT = 20;
 /**

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

@@ -9,7 +9,7 @@
  * them in call order (the last is reused once the script is exhausted). Or pass
  * `respond` to compute the object from the request.
  */
-import type { AiProvider, AiProviderCapabilities, GenerateStructuredRequest, StreamChatRequest } from './types';
+import type { AiProvider, AiProviderCapabilities, GenerateStructuredRequest, StreamChatRequest } from './types.js';
 export interface FakeProviderOptions {
     /** Provider id (default `fake`). */
     id?: string;

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

@@ -8,21 +8,32 @@
  * Bundle discipline: nothing exported here statically imports `ai` / `@ai-sdk/*` —
  * only `anthropic-provider` touches them, via dynamic `import()`. So importing this
  * barrel never eagerly loads the AI SDK, and a studio without an `ai` config block
- * (which only references `StudioAiConfig` as a type) reaches none of it.
+ * (which only references `StudioAiConfig` as a type) reaches none of it. The same
+ * discipline keeps `jose` (the session resolver's JWT library) behind a dynamic
+ * `import()` in `convex-session`.
+ *
+ * EC-371 adds the engine-default session gate + mounting kit: the Convex JWT
+ * session resolver (server), the matching client header provider, and the Node
+ * `(req, res)` bridge. The Vite DEV mount lives in its own entry —
+ * `@elytracms/studio/lib/ai/vite` (`createAiDevPlugin`) — because it imports `vite`,
+ * a dev-only tool that must stay out of this barrel's dependency edge.
  */
 export declare const PACKAGE = "@elytracms/studio/lib/ai";
-export * from './types';
-export * from './config';
-export * from './provenance';
-export * from './knowledge';
-export * from './shape';
-export * from './apply-content';
-export * from './anthropic-provider';
-export * from './fake-provider';
-export * from './route';
-export * from './route-provider';
-export * from './tools';
-export * from './create-flow';
-export * from './chat-state';
-export * from './rich-text-translate';
-export * from './translate-document';
+export * from './types.js';
+export * from './config.js';
+export * from './provenance.js';
+export * from './knowledge.js';
+export * from './shape.js';
+export * from './apply-content.js';
+export * from './anthropic-provider.js';
+export * from './fake-provider.js';
+export * from './route.js';
+export * from './route-provider.js';
+export * from './convex-session.js';
+export * from './convex-session-headers.js';
+export * from './node-handler.js';
+export * from './tools.js';
+export * from './create-flow.js';
+export * from './chat-state.js';
+export * from './rich-text-translate.js';
+export * from './translate-document.js';

package/dist/lib/ai/index.js

@@ -8,22 +8,33 @@
  * Bundle discipline: nothing exported here statically imports `ai` / `@ai-sdk/*` —
  * only `anthropic-provider` touches them, via dynamic `import()`. So importing this
  * barrel never eagerly loads the AI SDK, and a studio without an `ai` config block
- * (which only references `StudioAiConfig` as a type) reaches none of it.
+ * (which only references `StudioAiConfig` as a type) reaches none of it. The same
+ * discipline keeps `jose` (the session resolver's JWT library) behind a dynamic
+ * `import()` in `convex-session`.
+ *
+ * EC-371 adds the engine-default session gate + mounting kit: the Convex JWT
+ * session resolver (server), the matching client header provider, and the Node
+ * `(req, res)` bridge. The Vite DEV mount lives in its own entry —
+ * `@elytracms/studio/lib/ai/vite` (`createAiDevPlugin`) — because it imports `vite`,
+ * a dev-only tool that must stay out of this barrel's dependency edge.
  */
 export const PACKAGE = '@elytracms/studio/lib/ai';
-export * from './types';
-export * from './config';
-export * from './provenance';
-export * from './knowledge';
-export * from './shape';
-export * from './apply-content';
-export * from './anthropic-provider';
-export * from './fake-provider';
-export * from './route';
-export * from './route-provider';
-export * from './tools';
-export * from './create-flow';
-export * from './chat-state';
-export * from './rich-text-translate';
-export * from './translate-document';
+export * from './types.js';
+export * from './config.js';
+export * from './provenance.js';
+export * from './knowledge.js';
+export * from './shape.js';
+export * from './apply-content.js';
+export * from './anthropic-provider.js';
+export * from './fake-provider.js';
+export * from './route.js';
+export * from './route-provider.js';
+export * from './convex-session.js';
+export * from './convex-session-headers.js';
+export * from './node-handler.js';
+export * from './tools.js';
+export * from './create-flow.js';
+export * from './chat-state.js';
+export * from './rich-text-translate.js';
+export * from './translate-document.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/ai/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,0BAA0B,CAAA;AAEjD,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,SAAS,CAAA;AACvB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,SAAS,CAAA;AACvB,cAAc,kBAAkB,CAAA;AAChC,cAAc,SAAS,CAAA;AACvB,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA","sourcesContent":["/**\n * `@elytracms/studio/lib/ai` — the headless AI platform seam (EC-331, phase 1).\n *\n * Public surface: the config gate, the provider adapters (Anthropic + Fake), the\n * knowledge mechanism, the target-shape derivation, the `applyContentWithShape`\n * engine, the server-route factory, and the provenance seam. No chat UI here.\n *\n * Bundle discipline: nothing exported here statically imports `ai` / `@ai-sdk/*` —\n * only `anthropic-provider` touches them, via dynamic `import()`. So importing this\n * barrel never eagerly loads the AI SDK, and a studio without an `ai` config block\n * (which only references `StudioAiConfig` as a type) reaches none of it.\n */\nexport const PACKAGE = '@elytracms/studio/lib/ai'\n\nexport * from './types'\nexport * from './config'\nexport * from './provenance'\nexport * from './knowledge'\nexport * from './shape'\nexport * from './apply-content'\nexport * from './anthropic-provider'\nexport * from './fake-provider'\nexport * from './route'\nexport * from './route-provider'\nexport * from './tools'\nexport * from './create-flow'\nexport * from './chat-state'\nexport * from './rich-text-translate'\nexport * from './translate-document'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/ai/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,0BAA0B,CAAA;AAEjD,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,SAAS,CAAA;AACvB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,SAAS,CAAA;AACvB,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA;AAChC,cAAc,0BAA0B,CAAA;AACxC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,SAAS,CAAA;AACvB,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA","sourcesContent":["/**\n * `@elytracms/studio/lib/ai` — the headless AI platform seam (EC-331, phase 1).\n *\n * Public surface: the config gate, the provider adapters (Anthropic + Fake), the\n * knowledge mechanism, the target-shape derivation, the `applyContentWithShape`\n * engine, the server-route factory, and the provenance seam. No chat UI here.\n *\n * Bundle discipline: nothing exported here statically imports `ai` / `@ai-sdk/*` —\n * only `anthropic-provider` touches them, via dynamic `import()`. So importing this\n * barrel never eagerly loads the AI SDK, and a studio without an `ai` config block\n * (which only references `StudioAiConfig` as a type) reaches none of it. The same\n * discipline keeps `jose` (the session resolver's JWT library) behind a dynamic\n * `import()` in `convex-session`.\n *\n * EC-371 adds the engine-default session gate + mounting kit: the Convex JWT\n * session resolver (server), the matching client header provider, and the Node\n * `(req, res)` bridge. The Vite DEV mount lives in its own entry —\n * `@elytracms/studio/lib/ai/vite` (`createAiDevPlugin`) — because it imports `vite`,\n * a dev-only tool that must stay out of this barrel's dependency edge.\n */\nexport const PACKAGE = '@elytracms/studio/lib/ai'\n\nexport * from './types'\nexport * from './config'\nexport * from './provenance'\nexport * from './knowledge'\nexport * from './shape'\nexport * from './apply-content'\nexport * from './anthropic-provider'\nexport * from './fake-provider'\nexport * from './route'\nexport * from './route-provider'\nexport * from './convex-session'\nexport * from './convex-session-headers'\nexport * from './node-handler'\nexport * from './tools'\nexport * from './create-flow'\nexport * from './chat-state'\nexport * from './rich-text-translate'\nexport * from './translate-document'\n"]}

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

@@ -7,7 +7,7 @@
  * deterministic item list; `assembleKnowledgeBlock` renders the context block the
  * engine injects. Knowledge is DATA, never instructions (see the engine's stance).
  */
-import type { KnowledgeCollectionReader, KnowledgeCollectionSource, KnowledgeFn, KnowledgeItem, KnowledgeSource, ResolvedKnowledge } from './types';
+import type { KnowledgeCollectionReader, KnowledgeCollectionSource, KnowledgeFn, KnowledgeItem, KnowledgeSource, ResolvedKnowledge } from './types.js';
 /** `fromCollection('faq')` — sugar for a studio-editable knowledge source. */
 export declare function fromCollection(collectionId: string, options?: {
     field?: string;

package/dist/lib/ai/node-handler.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `toNodeHandler` — bridge the framework-agnostic Web `Request → Response`
+ * {@link AiRouteHandler} to Node's `(req, res)` signature (EC-371; closes EC-369
+ * finding #2, where the identical ~25-line bridge was hand-copied four times across
+ * consumers). This is the PROD half of the mounting kit: a Vercel Node function (or
+ * any Node server) mounts the route as
+ *
+ * ```ts
+ * // api/ai.ts (Vercel filesystem routing beats the SPA catch-all rewrite)
+ * import { toNodeHandler } from '@elytracms/studio/lib/ai'
+ * import { aiRouteHandler } from '../src/server/ai-handler.js'
+ * export default toNodeHandler(aiRouteHandler)
+ * ```
+ *
+ * The DEV half (`createAiDevPlugin`, Vite middleware + `ssrLoadModule`) reuses this
+ * same bridge — one implementation, both mounts. No platform dependency: the classic
+ * `(IncomingMessage, ServerResponse)` signature works on every @vercel/node version
+ * and on plain `node:http`. Note it buffers the response body (including the chat
+ * stream) — the proven Konditorei behavior; native streaming is EC-334's scope.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { AiRouteHandler } from './types.js';
+/** A Node-mountable request handler (Vercel Node function / `node:http` compatible). */
+export type NodeAiRouteHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/**
+ * Wrap an {@link AiRouteHandler} as a Node `(req, res)` handler: buffer the body,
+ * bridge headers both directions, copy status + payload back.
+ */
+export declare function toNodeHandler(handler: AiRouteHandler): NodeAiRouteHandler;