@salsita-ai/sdk 0.50.0-develop.5f7528aea8 → 0.50.0-develop.61093ff937

package/dist/docs/phoenix/quickstart.mdx

@@ -15,7 +15,7 @@ Build a working office desk configurator from an empty folder. You will describe
 
 ## Before you start
 
-Use Node.js 24 and pnpm 11. The tutorial uses the office desk model served by this documentation site at `/models/office-desk.gltf`; download it first. Real client projects normally start from `phoenix init`. This tutorial creates the four essential files by hand so you can see what Phoenix owns.
+Use Node.js 24 and any package manager; the commands below use pnpm, and with pnpm 11 the project also needs the `pnpm-workspace.yaml` in [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager). The tutorial uses the office desk model served by this documentation site at `/models/office-desk.gltf`; download it first. Real client projects normally start from `phoenix init`. This tutorial creates the four essential files by hand so you can see what Phoenix owns.
 
 ## Step 0 — Create the project
 
@@ -40,17 +40,13 @@ Now add these four files.
   "dependencies": {
     "@salsita-ai/sdk": "0.48.0"
   },
-  "devDependencies": {
-    "@lingui/cli": "5.9.5",
-    "@lingui/swc-plugin": "5.11.0"
-  },
   "phoenix": {
     "applicationFlow": true
   }
 }
 ```
 
-Use the SDK version supplied by your team if it differs from the repository's current `0.48.0` version. `phoenix.applicationFlow` selects the application-spec project structure. The first sync uses Lingui while generating the rest of the dependencies, so its CLI and SWC plugin must also be present in the initial install.
+Use the SDK version supplied by your team if it differs from the repository's current `0.48.0` version. `phoenix.applicationFlow` selects the application-spec project structure. The SDK runs its own Lingui, so the SDK is the only dependency you write by hand; `phoenix deps` adds the packages it needs next to it in the install step below. A project started with `phoenix init` gets a `package.json` that already declares them.
 
 ### `.env`
 
@@ -97,13 +93,17 @@ components:
         layout: universal
 ```
 
-Install the SDK, then ask Phoenix to generate the rest of the project:
+Install the SDK, let it declare the packages it needs, such as React, three.js and MUI, install them, then ask Phoenix to generate the rest of the project:
 
 ```sh
 pnpm install
+pnpm phoenix deps
+pnpm install
 pnpm phoenix sync
 ```
 
+`phoenix sync` stops while `package.json` lacks one of those packages; after every SDK update, run `phoenix deps` and install again (see [`phoenix deps`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-deps)). With npm, the same steps are `npm install`, `npx phoenix deps`, `npm install` and `npx phoenix sync`.
+
 `phoenix sync` keeps `spec/` and `src/` as your authored inputs and generates the application shell, types, and `.phoenix/` implementation. Start development without a server:
 
 ```sh

package/dist/docs/phoenix/sdk-builder-workflow.mdx

@@ -8,9 +8,9 @@ Your workspace's Studio shows the setup, the link to your configurator and the s
 
 ## Before you start
 
-- **Package access:** `@salsita-ai/sdk` is public on npm; `npx` and `pnpm install` download it without a registry token.
+- **Package access:** `@salsita-ai/sdk` is public on npm; any package manager downloads it without a registry token.
 - **Workspace details:** you need your workspace slug and its Phoenix region (`eu` or `us`), which you also received with your workspace.
-- **Tools:** Node.js and pnpm.
+- **Tools:** Node.js and a package manager. The commands below use pnpm; with npm, run `npm install` and `npx phoenix …` instead, with Yarn `yarn phoenix …`, with Bun `bunx phoenix …`.
 - **SDK build:** during the internal beta, use the `canary` build of the SDK, as the commands below do. It is published from every change to the platform, so it is newer than the last release.
 
 ## 1. Create a project
@@ -22,11 +22,11 @@ pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix init [folder]` writes the starter project: `package.json`, `pnpm-workspace.yaml` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it, and its `package.json` has the `dev`, `build`, `deploy`, `check` and `fix` scripts, which are yours to change. `phoenix sync` then adds the rest of the project: webhooks and lint config. It writes a `.gitignore` only when the folder is inside a git repository; run `git init` before the first sync, or sync again after it, to get the file.
+`phoenix init [folder]` writes the starter project: `package.json` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it and on the packages the SDK requires next to it (React, three.js, MUI, Lingui and the others, with their type packages), with ESLint and Prettier at the versions the SDK uses itself. Its `package.json` has the `dev`, `build`, `deploy`, `check` and `fix` scripts, which are yours to change. `phoenix sync` then adds the rest of the project: the TypeScript, lint and formatting config and the agent skills. It writes no webhook code: a project without `src/webhooks/index.ts` gets a built-in webhook (see [Webhook Entry Point](?path=/docs/phoenix-webhooks--docs#webhook-entry-point)). It writes a `.gitignore` only when the folder is inside a git repository; run `git init` before the first sync, or sync again after it, to get the file.
 
-`init` only writes these files: it asks nothing and contacts no server. It refuses a folder that already has a `spec/` folder. A `package.json` already in the folder is kept, as long as it depends on the SDK.
+`init` only writes these files: it asks nothing and contacts no server. It refuses a folder that already has a `spec/` folder. A `package.json` already in the folder is kept, as long as it depends on the SDK, and gains only the entries it lacks (see [Starting a New Project](?path=/docs/phoenix-phoenix-cli--docs#starting-a-new-project)).
 
-`pnpm-workspace.yaml` holds the pnpm settings the install needs: it allows the build scripts of the SDK's dependencies and exempts `@salsita-ai/*` packages from pnpm's minimum release age, so a build of the SDK published today installs. The file is yours to edit, for example to allow the build script of a dependency you add. `phoenix sync` adds these entries when they are missing and keeps the values you set. A project inside a pnpm monorepo gets no file of its own; the workspace root holds the settings.
+Phoenix writes no package-manager settings. With pnpm 11, add a `pnpm-workspace.yaml` that allows the build scripts of the SDK's dependencies before the first install; [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager) has the file.
 
 The starter `spec/application.yaml` begins with `project: default`, which means the default project of the workspace you sign in to. Leave it as it is; a workspace has one project.
 
@@ -76,12 +76,12 @@ pnpm phoenix deploy
 `phoenix deploy` goes through these steps:
 
 1. It validates the application spec.
-2. It packs the project files: the `.yaml` files in `spec`, everything in `src`, `mocks`, `assets`, `public` and `templates`, and `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.gitignore`, `CLAUDE.md` and `.cursor/rules/phoenix.mdc`. Every `node_modules`, `.phoenix` and `__generated` folder, every `.DS_Store` and `._*` file and every `.env` and `.env.*` file are left out, at any depth.
+2. It packs the project files: the `.yaml` files in `spec`, everything in `src`, `mocks`, `assets`, `public` and `templates`, and `package.json`, `tsconfig.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.gitignore`, `CLAUDE.md` and `.cursor/rules/phoenix.mdc`. Every `node_modules`, `.phoenix` and `__generated` folder, every `.DS_Store` and `._*` file and every `.env` and `.env.*` file are left out, at any depth.
 3. It asks the server for a build. The server compares your domain model with the deployed one and refuses, before anything is uploaded, a model that changed under an already deployed model version; see [Migrations](?path=/docs/phoenix-migrations--docs).
 4. It uploads the archive, which may be up to 200 MB.
 5. It starts the build, prints a link to the build's page in Studio and follows the build until your configurator is live, then prints its URL.
 
-On the server, the install follows your `pnpm-lock.yaml` and `pnpm-workspace.yaml`, so it allows the same build scripts and package versions as `pnpm install` on your computer. The build runs without platform secrets. It sees only your own environment variables and the public platform values, the [build environment](?path=/docs/phoenix-phoenix-cli--docs) that `phoenix deployment:build-envs` writes. The trusted deploy step then publishes the frontend, webhooks and assets.
+On the server, the install runs pnpm. It follows your `pnpm-lock.yaml` and `pnpm-workspace.yaml` when the project has them, so a pnpm project gets the same build scripts and package versions as on your computer; without them, pnpm resolves `package.json` with the settings the SDK needs. The build runs without platform secrets. It sees only your own environment variables and the public platform values, the [build environment](?path=/docs/phoenix-phoenix-cli--docs) that `phoenix deployment:build-envs` writes. The trusted deploy step then publishes the frontend, webhooks and assets.
 
 If the build fails, is cancelled or takes too long, `phoenix deploy` prints the end of the build log and exits with an error. `--no-wait` returns as soon as the build starts.
 

package/dist/docs/phoenix/testing.mdx

@@ -0,0 +1,148 @@
+# Testing
+
+- [Your application in a test](#your-application-in-a-test)
+- [Run the domain on a preset](#run-the-domain-on-a-preset)
+- [Test a transformer](#test-a-transformer)
+- [Mock a domain context](#mock-a-domain-context)
+- [Options](#options)
+
+A project's tests check its own logic, such as an expression on a preset, a transformer that completes an
+edit, a Blender projection or a migration, against the application the project ships. They run with
+Vitest in Node, without a browser or a server.
+
+## Your application in a test
+
+`createTestApplicationConfig` from `@salsita-ai/sdk/domain` is the way a test builds the project's
+application. It takes the generated application the test imports and returns its application config,
+typed with the project's entities, states and data, with no type argument at the call:
+
+```ts
+import { createTestApplicationConfig } from '@salsita-ai/sdk/domain'
+
+import { configuratorBuilder } from '../../.phoenix/domain.js'
+
+const config = createTestApplicationConfig(configuratorBuilder)
+
+config.domain.presets // the presets of spec/presets
+config.initialPublishedData // the published data the application starts with
+```
+
+`configuratorBuilder` from `.phoenix/domain.js` is the domain of the configurator: the model, expressions,
+invariants, actions, migrations, presets and the components declared in YAML. `configuratorConfig` from
+`.phoenix/configurator-config.js` is the whole configurator as the browser runs it, with every component,
+handler, element and transformer; it reads the frontend environment when it is imported, so a test that
+uses it stubs `phx.frontendEnv` first.
+
+A test that mounts the configurator's UI builds from `configuratorConfig`: it carries the SDK's default
+elements, the built-in layout, preset screen, not-found and not-authenticated pages, controls, toolbar
+buttons and sidebar-footer pieces, which `configuratorBuilder` does not, so a test that mounts the UI from `createTestApplicationConfig(configuratorBuilder)`
+shows a "not found" box in place of every built-in element. Code that assembles a config without the
+generated files calls `.withDefaultElements(defaultConfiguratorElements)` on its configurator builder, with
+the list from `@salsita-ai/sdk/configurator`, or `defaultAdminElements` from `@salsita-ai/sdk/admin` for
+the admin.
+
+A test passes the generated export to the helper and does not call the export's methods: they are how the
+SDK assembles an application, not an interface for tests, while the helper's call does not depend on that
+assembly.
+
+## Run the domain on a preset
+
+The config goes into `createDomainRuntime`, which runs the same systems as the configurator:
+
+```ts
+import { vi } from 'vitest'
+
+import { NoopAnalyticsSystem, createDomainRuntime, createTestApplicationConfig } from '@salsita-ai/sdk/domain'
+
+import { configuratorBuilder, createI18n } from '../../.phoenix/domain.js'
+
+const logger = {
+  info: vi.fn(),
+  error: vi.fn(),
+  warn: vi.fn(),
+  debug: vi.fn(),
+  verbose: vi.fn(),
+  appendToGlobalContext: vi.fn(),
+}
+const config = createTestApplicationConfig(configuratorBuilder)
+const runtime = createDomainRuntime({
+  config,
+  services: { analyticsService: new NoopAnalyticsSystem(), i18n: createI18n(), logger },
+})
+
+runtime.actions.domainContext.configurator.setExecutionMode('finalize')
+runtime.actions.domainData.setDomainData({
+  publishedData: config.initialPublishedData,
+  backendData: undefined,
+  frontendData: {},
+})
+runtime.actions.sessionContext.setSessionContext({ role: 'anonymous', data: {} })
+
+const preset = config.domain.presets[0]!
+runtime.actions.loadedData.completeConfiguratorLoad({
+  initialRevisionId: 'test',
+  initialEntities: preset.initialDomainEntities,
+  modelVersion: config.domain.domainFactory.modelVersion,
+  rootEntityType: preset.rootEntityType,
+  schemaIdentity: runtime.selectors.spec.getConfiguratorFactory(),
+})
+runtime.selectors.domainContext.configurator.getDomainContext().initialize()
+```
+
+## Test a transformer
+
+The domain of `configuratorBuilder` has no code-attached components and no transformers. A test adds the
+ones it needs, the way the configurator and the webhooks add them:
+
+```ts
+// Files that read `phx.domain` at module scope are imported after `.phoenix/domain.js`.
+const { customComponentOptics } = await import('../../.phoenix/configurator-domain-code.js')
+const { default: addCookingTop } = await import('../transformers/add-cooking-top.js')
+
+const config = createTestApplicationConfig(configuratorBuilder, {
+  componentModules: customComponentOptics,
+  transformers: {
+    importedTransformers: [{ origin: 'src/transformers/add-cooking-top.ts', exports: addCookingTop }],
+    specTransformers: [{ name: 'addCookingTop', priority: 30 }],
+  },
+})
+```
+
+`specTransformers` are the entries of the `transformers` section of `spec/application.yaml` that the test
+runs, with the priorities the spec gives them.
+
+## Mock a domain context
+
+`createMockState`, `createMockDomain` and `createMockDomainContext` take the same config and check the
+mock data against the project's types:
+
+```ts
+import { createMockDomainContext, createTestApplicationConfig } from '@salsita-ai/sdk/domain'
+
+const config = createTestApplicationConfig(configuratorBuilder)
+const preset = config.domain.presets[0]!
+const { domainContext, destroy } = createMockDomainContext(config, {
+  entities: preset.initialDomainEntities,
+  rootEntityType: preset.rootEntityType,
+  publishedData: config.initialPublishedData,
+  frontendData: {},
+  sessionData: {},
+  backendData: undefined,
+  mode: 'owner',
+  role: 'anonymous',
+  transformers: [],
+})
+```
+
+## Options
+
+| Option             | What it does                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `componentModules` | Component files added after the components the application already has, each `{ origin, exports }`                 |
+| `transformers`     | Replaces the application's transformers: files (`importedTransformers`) and spec entries (`specTransformers`)      |
+| `tag`              | The tag of the custom element the application mounts as; without it the application's own (`salsita-configurator`) |
+
+## See Also
+
+- [Best Practices](?path=/docs/phoenix-best-practices--docs) - Where custom code lives
+- [Transformers](?path=/docs/other-features-transformers--docs) - Writing transformers

package/dist/docs/phoenix/webhook-membership.mdx

@@ -4,21 +4,22 @@ Build component controls with React and browser SDKs without pulling them into t
 
 ## Choose Where Each File Runs
 
-| User file                                         | Frontend | Webhook |
-| ------------------------------------------------- | -------- | ------- |
-| Component or admin component without a directive  | Yes      | No      |
-| Component or admin component with `'use webhook'` | Yes      | Yes     |
-| Ordinary handler                                  | Yes      | No      |
-| Published-data or validator handler               | Yes      | Yes     |
-| Any other handler with `'use webhook'`            | Yes      | Yes     |
-| File under `src/webhooks/`                        | No       | Yes     |
+| User file                                            | Frontend | Webhook |
+| ---------------------------------------------------- | -------- | ------- |
+| Component or admin component without a directive     | Yes      | No      |
+| Component or admin component with `'use webhook'`    | Yes      | Yes     |
+| Ordinary handler                                     | Yes      | No      |
+| Published-data, validator or assistant setup handler | Yes      | Yes     |
+| Any other handler with `'use webhook'`               | Yes      | Yes     |
+| File under `src/webhooks/`                           | No       | Yes     |
 
-Published-data and validator handlers are detected when they register one of these APIs:
+Published-data, validator and assistant setup handlers are detected when they register one of these APIs:
 
 - `createMapPublishedRevisionDataHandler`
 - `createMapPublishedChunkedDataHandler`
 - `createDataRowValidatorHandler`
 - `createSheetValidatorHandler`
+- `phx.domain.createAssistantSetupHandler`
 
 ## Pin a Server-Safe Component
 

package/dist/docs/phoenix/webhooks.mdx

@@ -34,6 +34,23 @@ Phoenix provides domain-aware builders through the global `phx.webhooks` namespa
 
 ### Webhook Entry Point
 
+Your webhook is the default export of `src/webhooks/index.ts`. With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), the file is yours to create; sync does not write it. A project without it gets a built-in webhook, so it builds and deploys with no webhook code. The built-in webhook has one handler, an anonymous auth handler, which the platform calls only when `spec/application.yaml` sets `useAuthHook`. The legacy pipeline writes the file with that webhook on the first sync.
+
+Create `src/webhooks/index.ts` when the project needs its own handlers: finalization, backend data, or an auth handler that does more than start an anonymous session. A project that sets `useAuthHook` or `useClerk` needs its own auth handler, because the built-in one answers only anonymous requests. The smallest file is the built-in webhook itself:
+
+```ts
+// src/webhooks/index.ts
+const authHandler = phx.webhooks.authHandlerBuilder
+  .withAnonymousHandler(async () => ({ success: true, data: {}, role: 'anonymous' }))
+  .build()
+
+export default phx.webhooks.webhookBuilder.withAuthHook(authHandler).build()
+```
+
+The next `phoenix sync` or `phoenix build`, or the rebuild of a running `phoenix dev`, uses the file; deleting it brings the built-in webhook back. A webhook needs at least one handler, and a project with any other file in `src/webhooks/` must have `index.ts`.
+
+A webhook with more handlers:
+
 ```ts
 // src/webhooks/index.ts
 import { authHandler } from './handlers/auth-handler.js'
@@ -148,7 +165,7 @@ resources:
     s3Key: clientImage
 ```
 
-These resources are automatically made available as typed properties in task handlers via the `resources` parameter.
+These resources are automatically made available as typed properties in task handlers via the `resources` parameter. Two static resources with the same name are an error: `phoenix check` and `phoenix build` report the second entry (`DUPLICATE_RESOURCE_NAME`).
 
 #### Task Payload
 
@@ -391,7 +408,7 @@ ctx.emailTaskBuilder.withSubject(msg`Your configuration`)
 In React templates, use `<Trans>` for inline strings and `<HtmlHelpers.Localized>` to render message descriptors:
 
 ```tsx
-import { Trans } from '@lingui/macro'
+import { Trans } from '@lingui/react/macro'
 
 import { HtmlHelpers } from '@salsita-ai/sdk/webhook'
 
@@ -456,7 +473,7 @@ The template file:
 
 ```tsx
 // src/webhooks/handlers/configurator-finalize-handler/tasks/pdf-template.tsx
-import { Trans } from '@lingui/macro'
+import { Trans } from '@lingui/react/macro'
 
 import { HtmlHelpers, PdfHelpers, ResourceHelpers } from '@salsita-ai/sdk/webhook'
 
@@ -578,7 +595,7 @@ except for resource reference interpolation.
 
 ```tsx
 // src/webhooks/handlers/configurator-finalize-handler/tasks/email-task.tsx
-import { msg } from '@lingui/macro'
+import { msg } from '@lingui/core/macro'
 
 import { EmailTemplate } from './email-template.js'
 
@@ -603,7 +620,7 @@ export const simpleEmailTask = phx.webhooks.taskFactory.createSendEmailTask((res
 
 ```tsx
 // src/webhooks/handlers/configurator-finalize-handler/tasks/email-template.tsx
-import { Trans } from '@lingui/macro'
+import { Trans } from '@lingui/react/macro'
 
 import { EmailHelpers, ResourceHelpers } from '@salsita-ai/sdk/webhook'
 

package/dist/domain/admin-domain/implementation/common-admin-publish.d.ts

@@ -1,6 +1,5 @@
 import type { DomainEntity } from '../../core/index.js';
 import type { PublishedData } from '../__generated/application-types.js';
-import { type AnyDomainEntity } from '../__generated/model/index.js';
 export type CommonAdminPublishedData = PublishedData;
 export declare const CommonAdminPublishedDataSchema: {
     type: "object";
@@ -182,4 +181,4 @@ export declare const CommonAdminPublishedDataSchema: {
     additionalProperties: false;
     required: never[];
 };
-export declare const mapCommonAdminPublishedData: <ENTITIES extends DomainEntity<string>>(entities: ReadonlyArray<ENTITIES | AnyDomainEntity>) => CommonAdminPublishedData;
+export declare const mapCommonAdminPublishedData: (entities: ReadonlyArray<DomainEntity<string>>) => CommonAdminPublishedData;

package/dist/domain/admin-domain/index.js

@@ -1 +1 @@
-import{DomainComponentOpticBuilder as o,RecipeFactoryBuilder as e}from"../core/index.js";import{attributeSelectionComponent as n}from"../system-components/index.js";import{AnyDomainEntity as m,PresetCategory as t,aliases as i}from"./__generated/model/index.js";import{DraftId as a}from"./implementation/common-admin-expressions.js";export{migrateCommonAdminDomain}from"./implementation/common-admin-migrations.js";export*from"./__generated/model/index.js";export*from"./implementation/common-admin-expressions.js";export*from"./implementation/common-admin-publish.js";export*from"./schema/index.js";export const createCommonAdminRecipe=e.forAliases(i).forEntities(m.reflections).withDefaults({}).build();export const attachCommonAdminDomainComponent=o.from(i);export const commonAdminComponents=[attachCommonAdminDomainComponent.withEntity("Preset").withComponent(n,"category").attach((o,e)=>{let n=e.entities.filter(t.is);return null===o.categoryId?{value:a,options:n.map(o=>({value:o.id,label:o.name})).concat([{value:a,label:{$lang:{en:"Draft"}}}])}:{value:o.categoryId,options:n.map(o=>({value:o.id,label:o.name}))}},o=>({categoryId:o.value===a?null:o.value}))];export const configuratorBuilder=null;
+import{DomainComponentOpticBuilder as o,createRecipeFactory as e}from"../core/index.js";import{attributeSelectionComponent as n}from"../system-components/index.js";import{AnyDomainEntity as m,PresetCategory as t,aliases as i}from"./__generated/model/index.js";import{DraftId as a}from"./implementation/common-admin-expressions.js";export{migrateCommonAdminDomain}from"./implementation/common-admin-migrations.js";export*from"./__generated/model/index.js";export*from"./implementation/common-admin-expressions.js";export*from"./implementation/common-admin-publish.js";export*from"./schema/index.js";export const createCommonAdminRecipe=e(i,m.reflections,{});export const attachCommonAdminDomainComponent=o.from(i);export const commonAdminComponents=[attachCommonAdminDomainComponent.withEntity("Preset").withComponent(n,"category").attach((o,e)=>{let n=e.entities.filter(t.is);return null===o.categoryId?{value:a,options:n.map(o=>({value:o.id,label:o.name})).concat([{value:a,label:{$lang:{en:"Draft"}}}])}:{value:o.categoryId,options:n.map(o=>({value:o.id,label:o.name}))}},o=>({categoryId:o.value===a?null:o.value}))];export const configuratorBuilder=null;

package/dist/domain/application/application-config.d.ts

@@ -8,7 +8,7 @@ import type { CellValue } from '@salsita-ai/contracts/webhook';
 import type { AdminIntegrationService } from '#package/react-sdk';
 import type { $DomainEntity, DataCellValue, DataSchema, DomainEntity, DomainFactory, ProductPreset } from '../core/index.js';
 import type { AnalyticsSystem, RegistrableTransformer, TransformerFactory } from '../domain-context/index.js';
-import type { ProjectModule } from '../domain-runtime/index.js';
+import type { ElementRegistration, ProjectModule } from '../domain-runtime/index.js';
 import type { AssistantResolvedManifest } from './assistant/index.js';
 import type { WebComponentEventDescriptor } from './web-component-event.js';
 import type { WebComponentPropertyDescriptor } from './web-component-property.js';
@@ -292,6 +292,8 @@ export interface ApplicationConfig<ENTITIES extends DomainEntity<string>, ALLOWE
     /** The `src/handlers/` and `src/elements/` files as project modules; the runtime spec validates and flattens both. */
     readonly handlers: readonly ProjectModule[];
     readonly elements: readonly ProjectModule[];
+    /** The SDK's default element registrations; a project element with the same name replaces one. */
+    readonly defaultElements?: readonly ElementRegistration[];
     readonly mount: MountConfig<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, CHAT_CONTEXT, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ADMIN_ENTITIES, ADMIN_ALLOWED_ROOT_ENTITIES, ADMIN_$MAP, ADMIN_NAVIGATION_STATES, ADMIN_VIEW_STATES>;
 }
 export {};

package/dist/domain/application/assistant/assistant-fields.d.ts

@@ -0,0 +1,12 @@
+import type { AssistantDeclaredField, AssistantResolvedField } from './assistant-resolved-manifest.js';
+/** Combines the effective description with allowed string values. */
+export declare const describeAssistantValues: (description: string | undefined, values: readonly string[] | undefined) => string | undefined;
+/** Applies GraphQL field inheritance identically at parse time and after session narrowing. */
+export declare const mergeAssistantFields: (inherited: ReadonlyArray<readonly AssistantDeclaredField[]>, own: readonly AssistantDeclaredField[], ownEnumValues: (source: string) => readonly string[] | undefined, conflict: (name: string, first: string, second: string) => void) => readonly AssistantDeclaredField[];
+/**
+ * The serializable form of a merged field of one alias or type. Merging keeps the inherited entry of
+ * a field declared twice, so the lens tags are taken from `own`, the declarations of that alias or
+ * type itself: each lens condition then comes from its own declaration, at parse time and after
+ * session narrowing alike.
+ */
+export declare const resolveAssistantField: (field: AssistantDeclaredField, own: readonly AssistantDeclaredField[]) => AssistantResolvedField;

package/dist/domain/application/assistant/assistant-fields.js

@@ -0,0 +1 @@
+export const describeAssistantValues=(e,s)=>{if(!s?.length)return e;let t=`One of: ${s.map(e=>`"${e}"`).join(", ")}.`;return e?`${e}${/[.!?]$/.test(e)?"":"."} ${t}`:t};export const mergeAssistantFields=(e,s,t,n)=>{let r=new Map,i=new Set(s);for(let t of[...e.flat(),...s]){let e=r.get(t.name);e?e.source!==t.source?n(t.name,e.source,t.source):r.set(t.name,{...e,...i.has(t)&&t.describedByManifest?{description:t.description,describedByManifest:!0,valueDescription:t.valueDescription}:{}}):r.set(t.name,t)}return[...r.values()].map(e=>{let s=e.enumValues&&t(e.source);return s?{...e,enumValues:s,description:describeAssistantValues(e.valueDescription,s)}:e})};export const resolveAssistantField=(e,s)=>{let t=s.find(s=>s.name===e.name&&s.source===e.source)?.lenses;return{name:e.name,source:e.source,localized:e.localized,type:e.type,...void 0===e.description?{}:{description:e.description},...t?.length?{lenses:t}:{}}};

package/dist/domain/application/assistant/assistant-form-elements.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What an element of an assistant form collects: a `group` all its children, a `choice` exactly one
+ * of its options, a `choices` any number of them; an `option` is something to pick and an `input` a
+ * free value.
+ */
+export type AssistantFormRole = 'group' | 'choice' | 'choices' | 'option' | 'input';
+/** The type an attribute of a form element is validated and coerced to; the model writes every attribute as a string. */
+export interface AssistantFormAttribute {
+    readonly type: 'string' | 'number' | 'integer' | 'boolean';
+    readonly enum?: readonly string[];
+}
+/**
+ * An element the assistant can write inside a ```` ```form ```` fence of its reply to ask the user
+ * something. The panel renders it, and the SDK prompt lists it, so the model and the panel agree on
+ * one set of elements.
+ */
+export interface AssistantFormElementDescriptor {
+    /** The tag: lowercase, and never the name of an HTML element. */
+    readonly name: string;
+    readonly role: AssistantFormRole;
+    /** What the element is for, printed in the prompt after its signature. */
+    readonly description: string;
+    /** Attributes beyond the built-in `label` and, on an option or an input, `value`. */
+    readonly attributes: Readonly<Record<string, AssistantFormAttribute>>;
+    readonly required?: readonly string[];
+}
+/** The elements every assistant form understands, in the order the prompt lists them. */
+export declare const ASSISTANT_BUILT_IN_FORM_ELEMENTS: readonly AssistantFormElementDescriptor[];

package/dist/domain/application/assistant/assistant-form-elements.js

@@ -0,0 +1 @@
+export const ASSISTANT_BUILT_IN_FORM_ELEMENTS=[{name:"group",role:"group",description:"Puts related questions together under its label.",attributes:{}},{name:"choice",role:"choice",description:"The user picks exactly one of its options.",attributes:{}},{name:"choices",role:"choices",description:"The user picks any number of its options.",attributes:{}},{name:"reply",role:"option",description:"A short answer shown as a button.",attributes:{}},{name:"text",role:"input",description:"A single line the user types.",attributes:{placeholder:{type:"string"}}}];

package/dist/domain/application/assistant/assistant-manifest.d.ts

@@ -47,7 +47,11 @@ export interface AssistantFieldOptions {
  * means none; `replaceRecipes` lists the same for `meta { replaceRecipes }` and `replaceEntity`;
  * `fieldOptions` lists, per entity type, the options edges `meta` exposes for its
  * writable fields, and absent means none; `actions` maps each custom `Mutation` field to the
- * declared action it runs, and absent means none. Consumed by the configurator GraphQL system.
+ * declared action it runs, and absent means none; `lenses` holds the generated lens fragments, and
+ * absent means none: `declarations` is the text the prompt shows, each lens once with its relations
+ * spreading the lens itself, and `definitions` the valid GraphQL injected into an operation that
+ * spreads a lens, with the copies that unroll each lens to its depth. Consumed by the configurator
+ * GraphQL system.
  */
 export interface AssistantManifest {
     readonly sdl: string;
@@ -60,4 +64,8 @@ export interface AssistantManifest {
     readonly replaceRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
     readonly fieldOptions?: Readonly<Record<string, readonly AssistantFieldOptions[]>>;
     readonly actions?: Readonly<Record<string, string>>;
+    readonly lenses?: {
+        readonly declarations: string;
+        readonly definitions: string;
+    };
 }

package/dist/domain/application/assistant/assistant-resolved-manifest.d.ts

@@ -15,7 +15,11 @@ export interface AssistantRelationType {
     readonly target: string;
     readonly cardinality: '1-1' | '0-1' | '0-N' | '1-N';
 }
-/** A field's source and resolved type, carried in the application bundle without GraphQL instances. */
+/**
+ * A field's source and resolved type, carried in the application bundle without GraphQL instances.
+ * `lenses` names the lenses the field's own declaration on this alias or type tags it with; a field
+ * only inherited from an alias carries none here, since the alias already selects it.
+ */
 export interface AssistantResolvedField {
     readonly name: string;
     readonly source: string;
@@ -25,6 +29,7 @@ export interface AssistantResolvedField {
     } | AssistantRelationType;
     readonly localized: boolean;
     readonly description?: string;
+    readonly lenses?: readonly string[];
 }
 /** Declared UI state values used to describe the navigation query. */
 export interface AssistantStates {
@@ -34,6 +39,7 @@ export interface AssistantStates {
 }
 /** Serializable resolved whitelist from which the browser or backend constructs the assistant schema. */
 export interface AssistantResolvedManifest {
+    readonly declarations: AssistantDeclarations;
     readonly entityTypes: readonly string[];
     readonly aliases: Readonly<Record<string, readonly string[]>>;
     readonly exampleType?: string;
@@ -45,6 +51,11 @@ export interface AssistantResolvedManifest {
     readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
     readonly optionsEdges: Readonly<Record<string, readonly AssistantResolvedOptionsEdge[]>>;
     readonly actionFields: readonly AssistantResolvedAction[];
+    /** The declared lenses by name: when to use each, and how many levels its tagged relations nest. */
+    readonly lenses: Readonly<Record<string, {
+        readonly description: string;
+        readonly maxDepth: number;
+    }>>;
 }
 /** Optional mutation input for one stored field, using its exposed name. */
 export interface AssistantWritableField {
@@ -59,7 +70,8 @@ export interface AssistantWritableType {
     readonly fields: readonly AssistantWritableField[];
 }
 /** Description hints resolved from recipe/option entries; no parse context is retained. */
-export type AssistantResolvedHint = 'sameForAllInstances' | 'constantDuringSession';
+export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
+export type AssistantResolvedHint = (typeof ASSISTANT_HINTS)[number];
 /** Recipe groups and their description hints for one entity type. */
 export interface AssistantResolvedRecipes {
     readonly groups: readonly AssistantRecipeGroup[];
@@ -93,3 +105,27 @@ export interface AssistantResolvedAction {
     }>>;
     readonly result: Readonly<Record<string, AssistantResolvedActionResult>>;
 }
+/** Immutable, validated declaration bindings retained before alias expansion for session narrowing. */
+export interface AssistantDeclarations {
+    readonly entities: Readonly<Record<string, readonly AssistantDeclaredField[]>>;
+    readonly enumValues: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+    readonly deletable: readonly string[];
+    readonly writable: Readonly<Record<string, Readonly<Record<string, AssistantDeclaredWrite>>>>;
+    readonly childRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+}
+/** An original field declaration, including metadata needed to reapply inheritance and enum descriptions. */
+export interface AssistantDeclaredField extends AssistantResolvedField {
+    readonly describedByManifest: boolean;
+    readonly enumValues?: readonly string[];
+    readonly valueDescription?: string;
+}
+/** Stored-property types and component bindings, resolved separately for each concrete member. */
+export interface AssistantDeclaredWrite {
+    readonly members: Readonly<Record<string, {
+        readonly exposedDescription?: string;
+        readonly field: AssistantWritableField;
+        readonly options?: AssistantResolvedOptionsEdge;
+    }>>;
+    readonly defaultOptionsName: boolean;
+}

package/dist/domain/application/assistant/assistant-resolved-manifest.js

@@ -1 +1 @@
-export{};
+export const ASSISTANT_HINTS=["sameForAllInstances","constantDuringSession"];

package/dist/domain/application/assistant/build-assistant-lenses.d.ts

@@ -0,0 +1,14 @@
+import { type GraphQLSchema } from 'graphql';
+import type { AssistantManifest } from './assistant-manifest.js';
+import type { AssistantResolvedManifest } from './assistant-resolved-manifest.js';
+/**
+ * Generates the lens fragments of a resolved manifest for the execution schema compiled from it. A
+ * declared lens becomes one fragment on `AnyDomainEntity`; one that session narrowing left without a
+ * tagged field is dropped, so the agent is never offered a lens that selects nothing. A built-in lens
+ * is present only when the schema has its type. A tagged relation spreads the lens itself in the
+ * declarations, which GraphQL forbids, so the definitions unroll it into copies down to `maxDepth`,
+ * where relations select only `id`. The definitions are checked here against the execution schema,
+ * with every declared lens spread on one entity, so a fault in them fails the build and not the
+ * operations that spread them.
+ */
+export declare const buildAssistantLenses: (resolved: AssistantResolvedManifest, schema: GraphQLSchema) => NonNullable<AssistantManifest['lenses']>;

package/dist/domain/application/assistant/build-assistant-lenses.js

@@ -0,0 +1,5 @@
+import{NoUnusedFragmentsRule as e,parse as t,specifiedRules as i,validate as n}from"graphql";let s="AnyDomainEntity",r=[{name:"RecipeGroup",description:"A recipe group with its recipes, without their dry-runs.",selections:["groupId","name","description","recipes { ...Recipe }"]},{name:"Recipe",description:"A recipe without its dry-run.",selections:["key","name","description","imageUrl"]},{name:"FieldOption",description:"A value a field accepts, without its dry-run.",selections:["value","name","description","imageUrl","color"]},{name:"DryRun",description:"What a dry-run would do, with the ids of the entities it would change instead of the entities.",selections:["ok","deletedEntityIds","sideEffects","errors { type entityId message }","changedEntities { id }"]}],a=(e,t)=>0===t?e:`${e}__${t}`,l=e=>e.split("\n").map(e=>`# ${e}`.trimEnd()).join("\n"),o=(e,t,i)=>[`fragment ${e} on ${t} {`,...i.map(e=>`  ${e}`),"}"].join("\n"),p=(e,t,i)=>{let n=e=>"edge"===e.type.kind?`${e.name} { ${i} }`:e.name;return o(e,s,["id",...t.flatMap(({typeName:e,fields:t})=>e===s?t.map(n):[`... on ${e} {`,...t.map(e=>`  ${n(e)}`),"}"])])};export const buildAssistantLenses=(d,m)=>{let c=Object.entries(d.lenses).flatMap(([e,t])=>{let i=[s,...Object.keys(d.aliases).filter(e=>e!==s),...d.entityTypes].flatMap(t=>{let i=(d.fields[t]??[]).filter(t=>t.lenses?.includes(e));return i.length>0?[{typeName:t,fields:i}]:[]});return i.length>0?[{name:e,...t,conditions:i}]:[]}),$=r.filter(({name:e})=>void 0!==m.getType(e)),h=[...c.map(({name:e,description:t,maxDepth:i,conditions:n})=>{let s=n.some(({fields:e})=>e.some(e=>"edge"===e.type.kind));return`${l(s?`${t} ${`Nested relations carry the same selection up to ${i} ${1===i?"level":"levels"}, below that only \`id\`.`}`:t)}
+${p(e,n,`...${e}`)}`}),...$.map(({name:e,description:t,selections:i})=>`${l(t)}
+${o(e,e,i)}`)].join("\n\n"),u=[...c.flatMap(({name:e,maxDepth:t,conditions:i})=>Array.from({length:t+1},(n,s)=>p(a(e,s),i,s<t?`...${a(e,s+1)}`:"id"))),...$.map(({name:e,selections:t})=>o(e,e,t))].join("\n\n");if(""!==u){let s=c.length>0?`entities { ${c.map(({name:e})=>`...${e}`).join(" ")} }`:"__typename",r=n(m,t(`${u}
+
+{ ${s} }`),i.filter(t=>t!==e));if(r.length>0)throw Error(`The lens fragments generated from "assistant.lenses" are not valid GraphQL: ${[...new Set(r.map(e=>e.message))].join(" ")}`)}return{declarations:h,definitions:u}};