@salsita-ai/sdk 0.50.0-develop.c1dcc73e88 → 0.50.0-develop.ca72986c39

package/dist/docs/phoenix/phoenix-cli.mdx

@@ -137,8 +137,8 @@ The same streams are available in the editor's **Logs** sidebar panel with per-s
 
 Runs all code quality checks in sequence:
 
-1. **TypeScript** — Type checking with `tsc`
-2. **ESLint** — Linting rules
+1. **TypeScript** — Type checking with `tsc`, with the project's root `tsconfig.json`, or with `.phoenix/tsconfig.json` when the project has none (see [Project Structure](?path=/docs/phoenix-project-structure--docs#root-level-files))
+2. **ESLint** — Linting rules, over `src/`; a project with no files there passes
 3. **Prettier** — Code formatting
 
 ### `phoenix fix`
@@ -147,12 +147,23 @@ Auto-fixes ESLint and Prettier issues. Equivalent to running `eslint --fix` and
 
 ## Environment Variables
 
-When you run `deployment:prepare-local` or `deployment:prepare`, the CLI communicates with the Phoenix server, which generates environment variables and writes them to `.env.generated`.
+When you run `deployment:prepare-local` or `deployment:prepare`, the CLI communicates with the Phoenix server, which generates environment variables and writes them to `.env.generated`. `phoenix dev` does the same for its development deployment when it starts.
+
+### The generated env file
+
+A project has one generated env file. Phoenix keeps it in `.phoenix/`, as `.phoenix/.env.generated`, unless the project has a `.env.generated` in its root, which then is the one that counts.
+
+- `phoenix dev` reads and writes `.phoenix/.env.generated` in a project without a root `.env.generated`, and creates no file in the project root. In a project that has a root `.env.generated`, it reads and writes that file and `.phoenix/.env.generated` is not used.
+- The deployment and environment commands (`deployment:prepare`, `deployment:prepare-dev`, `deployment:prepare-local`, `deployment:build-envs` and the others with an `--outFile` option) write `.env.generated` in the project root unless `--outFile` or `OUT_FILE` names another file. Deploy pipelines read it there. Once one of them has written it, `phoenix dev` and `phoenix build` use it.
+- Everything that reads environment variables follows the same rule: the root `.env.generated` when it exists, otherwise `.phoenix/.env.generated`. The two files are never merged.
+- `phoenix clean` removes `.phoenix/` and with it `.phoenix/.env.generated`; the next `phoenix dev` prepares the development deployment again. A root `.env.generated` stays.
+
+This holds for a project on the application-spec pipeline. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix dev` always reads and writes `.env.generated` in the project root.
 
 ### Data Flow
 
 ```
-spec/application.yaml → Server prepares environment → CLI writes .env.generated → Frontend/Webhooks read it
+spec/application.yaml → Server prepares environment → CLI writes the generated env file → Frontend/Webhooks read it
 ```
 
 ### Project Scripts
@@ -173,7 +184,7 @@ A project may have other scripts than these five, such as `sync`, `test` or `ver
 
 ### Server-Generated Variables
 
-These are automatically computed by the server and written to `.env.generated`:
+These are automatically computed by the server and written to the generated env file:
 
 | Variable                         | Purpose                                                 |
 | -------------------------------- | ------------------------------------------------------- |
@@ -222,7 +233,7 @@ A build pipeline that receives the source archive of a [`phoenix deploy`](#phoen
 - it refuses an archive over 200 MB, one that extracts to more than 1 GB, or one with more than 100,000 files;
 - it refuses links, special files, absolute paths, paths that leave the folder, names with control characters, and entries that repeat or collide with an earlier one;
 - it refuses an archive it cannot read to the end, such as a truncated upload;
-- it extracts only project files, the same set `phoenix deploy` packs, and reports the entries it left out.
+- it extracts only project files and reports the entries it left out, including the optional `conversation.log` that deploy keeps in the private archive for review.
 
 `<folder>` must be new or empty. When the command refuses an archive, it removes the folder, so a partly extracted project is never built.
 
@@ -261,7 +272,7 @@ A development environment keeps the AI assistant's conversation when the assista
 Environment variables are resolved in this order (highest to lowest priority):
 
 1. Process environment variables (shell)
-2. `.env.generated` (created by deployment commands)
+2. [The generated env file](#the-generated-env-file): `.env.generated` in the project root when the project has one, otherwise `.phoenix/.env.generated`
 3. `.env` (manual overrides)
 
 ### Generated Config Files
@@ -292,13 +303,16 @@ Starts the full development environment: Vite dev server, development webhook tu
 | `--region`              | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
 | `--skipUpload` / `--su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
 
+With the application-spec pipeline, `phoenix dev` creates an empty `src/` folder when the project has none, so that it rebuilds when the first source file, such as `src/webhooks/index.ts`, is added.
+
 In `server` persistence mode the project comes from `--projectSlug`, `PROJECT_SLUG` or `project` in the spec, and the credential from `DEVELOPMENT_KEY` or the `phoenix login` sign-in; see [Starting a New Project](#starting-a-new-project). When signed in, the environment is always your own development environment and `--environmentSlug` is ignored.
 
 The dev server watches for changes in:
 
 - `spec/**/*.yaml` — Domain specification files
 - `src/**/*.{ts,tsx,yaml,yml,json,html,css}` — Source files
-- `.env`, `.env.generated` — Environment files (triggers full Vite restart)
+- `.env` — Environment file; a change restarts the Vite dev server
+- `.env.generated`, `.phoenix/.env.generated` — Generated env files; a change rebuilds the project files. Only a file that exists when `phoenix dev` starts is watched: a root `.env.generated` that a deployment command creates while dev runs is not watched; restart `phoenix dev` to use it.
 
 When linked SDK packages are detected (`phoenix link`), changes to SDK dist files are also watched.
 
@@ -396,6 +410,24 @@ With the application-spec pipeline (see [Current and legacy project tooling](#cu
 | ---------------- | --------------- | ------- | ------------------------------ |
 | `--force` / `-f` | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache |
 
+### `phoenix deps`
+
+Brings `package.json` in line with the SDK's peer dependencies: the packages the SDK's code imports and the project installs next to it, so the project and the SDK share one copy. The `peerDependencies` of the installed `@salsita-ai/sdk` decide which packages and which versions. `@clerk/clerk-react` is needed only when the spec sets `useClerk`.
+
+```bash
+pnpm phoenix deps
+pnpm install
+```
+
+- A missing peer is added at the lowest version of the SDK's range, as an exact version, in alphabetical order: type packages (`@types/*`) to `devDependencies`, the others to `dependencies`.
+- A peer declared with a version range whose lowest version falls outside the SDK's range is set to the lowest version of the SDK's range, in the field that declares it. The output says when that is a downgrade.
+- A peer declared with a specifier that is not a version range, such as `workspace:`, `npm:`, `catalog:`, `file:`, `link:` or a git URL, stays as it is.
+- `@salsita-ai/common`, `@salsita-ai/contracts`, `@salsita-ai/platform-project-sdk`, `@salsita-ai/platform-common` and `@salsita-ai/platform-contracts` are removed, because `@salsita-ai/sdk` replaces them. No other entry is removed.
+
+Every other part of `package.json` keeps its order and formatting. `phoenix deps` installs nothing: it lists each change and names `pnpm install` as the next step, or says that nothing needed to change. Running it again changes nothing. It reads the spec to learn whether the project uses Clerk, so it stops with the spec's errors when the spec does not parse.
+
+This holds for a project on the application-spec pipeline. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix deps` changes nothing and says that `phoenix sync` manages the dependencies.
+
 ### Current and legacy project tooling
 
 Use the `phoenix` binary for projects that still use domain-spec generation. The CLI selects a
@@ -705,6 +737,10 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation of the `phoenix-feedback` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
+To keep the conversation that led to a build, place a reviewed UTF-8 transcript in `conversation.log` at the project root before deploying. Deploy automatically includes it in the private source archive. Download the build's sources from Studio to read it; access is the same as for the rest of that build's sources. The build extractor skips the log, so it is not an application build input or a public asset. Missing logs produce a warning and deployment continues. Directories, links and special files at that path are rejected.
+
+The Phoenix agent skill explains how to prepare the transcript: prefer a native session export; otherwise mark a reconstruction as incomplete. Preserve available user/assistant messages and tool calls, cap individual tool results at 16 KiB with explicit truncation markers, and reference images rather than embedding them. Include the agent, export time, source and known omissions. Review and redact credentials or unrelated sensitive content before approving upload. The CLI uploads the file as supplied; it does not collect agent history, redact content, check freshness or verify completeness. Remove the file from the project root to deploy without it. The log counts toward the source archive's existing size limits; there is no separate conversation upload or viewer.
+
 ### `phoenix feedback [message]`
 
 Sends feedback about the SDK, the CLI, the documentation or Studio to the Phoenix team. It needs `phoenix login`: the server records the workspace, user and API token of the sign-in, so the message itself needs no introduction.

package/dist/docs/phoenix/project-structure.mdx

@@ -44,7 +44,7 @@ project-root/
 | `invariants/`   | Domain constraints                                                     |
 | `transformers/` | Data transformation logic                                              |
 | `handlers/`     | Event & lifecycle handlers                                             |
-| `webhooks/`     | Webhook implementations                                                |
+| `webhooks/`     | Webhook implementations, entered through `index.ts`                    |
 | `migrations/`   | Data schema migrations (v\*.ts) - auto-created based on model versions |
 | `locales/`      | Locale catalogs (`.po` sources; compiled `.ts`, do not edit)           |
 | `_*`            | Shared code folders at any depth (not auto-imported)                   |
@@ -53,7 +53,11 @@ Every file in `components/`, `elements/`, `expressions/`, `actions/`, `invariant
 (and their `admin/` counterparts) is imported by its location, so its default export must be what that folder's `phx`
 factory returns, or an array of those. A file that exports anything else, such as a plain React component in
 `elements/`, stops the application at start with an `Invalid default export in <file>` error that names the expected
-shape. Keep plain components and helpers in a `_*` folder.
+shape. When several files in `handlers/`, `elements/`, `transformers/`, `components/`, `admin/elements/` and
+`admin/components/` are wrong, the error lists all of them, one numbered line per file. Keep plain components and helpers in a `_*` folder.
+
+With the application-spec pipeline, sync does not write `src/webhooks/index.ts`, and a project without it gets a
+built-in webhook; see [Webhook Entry Point](?path=/docs/phoenix-webhooks--docs#webhook-entry-point).
 
 ### Admin Folders (src/admin/)
 
@@ -179,7 +183,7 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 | File                                                   | Auto-Generated? | Notes                                  |
 | ------------------------------------------------------ | --------------- | -------------------------------------- |
 | `package.json`                                         | Partially       | Dependencies merged, scripts untouched |
-| `tsconfig.json`                                        | Yes             | Managed by Phoenix                     |
+| `tsconfig.json`                                        | Once            | Yours; see below                       |
 | `eslint.config.js`                                     | Yes             | Managed by Phoenix                     |
 | `prettier.config.js`                                   | Yes             | Managed by Phoenix                     |
 | `.prettierignore`                                      | No              | Optional and your own; see below       |
@@ -188,19 +192,29 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 | `.gitignore`                                           | Partially       | Only in a git repository; see Markers  |
 | `.env`                                                 | No              | Git-ignored, local config              |
 | `.env.example`                                         | No              | Template for env vars                  |
-| `.env.generated`                                       | Yes             | Auto-generated IDs, git-ignored        |
+| `.env.generated`                                       | Yes             | Optional, git-ignored; see below       |
 | `README.md`                                            | No              | Project documentation                  |
 | `AGENTS.md`                                            | No              | Your own coding-agent instructions     |
 | `.claude/skills/phoenix*/`, `.agents/skills/phoenix*/` | Yes             | Phoenix agent skills                   |
 
 Sync does not write `README.md`, `AGENTS.md`, `.env.example`, `.env.ci` or the `README.md` files in `assets/public/` and `assets/private/`. Earlier SDK versions wrote them once; a project that has them keeps them, and they are yours to edit.
 
+Phoenix keeps the generated env file, with the IDs and values of the prepared deployment, in `.phoenix/` unless the project has a `.env.generated` in its root, which then is the one that counts. `phoenix dev` creates no `.env.generated` in the project root; the deployment and environment commands write it there. See [The generated env file](?path=/docs/phoenix-phoenix-cli--docs#the-generated-env-file).
+
 With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), Phoenix does not write a `.prettierignore`, and a fresh clone or CI checkout of a project has none. `phoenix check` and `phoenix fix` do not read one: they skip `.phoenix/`, `dist/`, the compiled catalogs in `src/locales/`, `pnpm-lock.yaml` and `.linguirc` on their own. A project that runs Prettier directly, as `prettier --check .` or from an editor, can add its own `.prettierignore`. To commit it, add a `!.prettierignore` line after the Phoenix block of `.gitignore`, because that block lists the file. The legacy pipeline writes `.prettierignore` on every sync.
 
+With the application-spec pipeline, the project's TypeScript settings are in `.phoenix/tsconfig.json`, which sync rewrites with the rest of `.phoenix/`. The root `tsconfig.json` is the one editors and tools find: sync writes it only when the project has none, as a single line that extends the generated settings, and it is yours to commit and to add to:
+
+```json
+{ "extends": "./.phoenix/tsconfig.json" }
+```
+
+The only root `tsconfig.json` sync replaces is the full file earlier SDK versions generated there, recognised by its settings; any other stays as it is. `phoenix dev`, `phoenix build` and the webhook bundle do not resolve `paths` aliases, so an alias added to the root file passes `phoenix check` and fails the build. `phoenix check` type-checks with the root `tsconfig.json`, or with `.phoenix/tsconfig.json` when the project has none. The legacy pipeline writes the full `tsconfig.json` on every sync.
+
 ### DO NOT EDIT (Fully Auto-Generated)
 
-- **Everything in `.phoenix/`** - Completely regenerated on each build. The one exception is `.phoenix/variants/`, where a coding agent writes the option files for `phoenix variants`; a rebuild keeps it
-- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`
+- **Everything in `.phoenix/`** - Completely regenerated on each build. The exceptions are `.phoenix/variants/`, where a coding agent writes the option files for `phoenix variants`, and `.phoenix/.env.generated`, the generated env file of `phoenix dev`; a rebuild keeps both
+- `eslint.config.js`, `prettier.config.js`
 - `.linguirc`, `.nvmrc`
 - `src/locales/**/*.ts` - Compiled from `.po` catalogs
 - `.env.generated`
@@ -238,6 +252,7 @@ With the application-spec pipeline (see [Current and legacy project tooling](?pa
 - `templates/`
 - `package.json` (scripts section, custom dependencies)
 - `.env`, `.env.example`, `.env.ci`
+- `tsconfig.json` (application-spec pipeline; keep it extending `.phoenix/tsconfig.json`)
 - `README.md`, `AGENTS.md`
 
 ## File Naming Conventions
@@ -345,6 +360,7 @@ project-root/
 │   ├── admin-interface.ts         # Admin interface types
 │   ├── i18n.ts                    # i18n initialization
 │   ├── globals.d.ts               # Global type definitions
+│   ├── tsconfig.json              # TypeScript settings, extended by the root tsconfig.json
 │   ├── index.html                 # Configurator HTML entry
 │   └── admin.html                 # Admin HTML entry
 │
@@ -508,7 +524,7 @@ Assets are split between two locations with different deployment strategies:
 
 Localization files enable multi-language support in your configurator.
 
-Translatable messages are authored in TypeScript and TSX source files using `@lingui/macro`.
+Translatable messages are authored in TypeScript and TSX source files using Lingui's macros: `msg` from `@lingui/core/macro` and `<Trans>` from `@lingui/react/macro`.
 
 Locale catalogs live in `src/locales/<lang>/`. Phoenix creates and updates the `messages.po` source catalogs; edit their `msgstr` values to provide translations. The `messages.ts` files are compiled from those catalogs and must not be edited directly.
 

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

@@ -22,7 +22,7 @@ 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`, `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: 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.
 
@@ -76,7 +76,7 @@ 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.

package/dist/docs/phoenix/testing.mdx

@@ -0,0 +1,140 @@
+# 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 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'
@@ -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/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-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']>;