@salsita-ai/sdk 0.50.0-develop.2331d4a6b7 → 0.50.0-develop.24077d65e6

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

@@ -40,6 +40,7 @@ project-root/
 | `components/`   | Phoenix system components (ECS)                                        |
 | `elements/`     | Page elements (pages, providers)                                       |
 | `expressions/`  | Domain logic expressions                                               |
+| `actions/`      | Implementations of the domain actions declared under `actions:`        |
 | `invariants/`   | Domain constraints                                                     |
 | `transformers/` | Data transformation logic                                              |
 | `handlers/`     | Event & lifecycle handlers                                             |
@@ -48,6 +49,13 @@ project-root/
 | `locales/`      | Locale catalogs (`.po` sources; compiled `.ts`, do not edit)           |
 | `_*`            | Shared code folders at any depth (not auto-imported)                   |
 
+Every file in `components/`, `elements/`, `expressions/`, `actions/`, `invariants/`, `transformers/` and `handlers/`
+(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. 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.
+
 ### Admin Folders (src/admin/)
 
 The `admin/` folder supports these admin-specific categories:
@@ -171,25 +179,29 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 | File                                                   | Auto-Generated? | Notes                                  |
 | ------------------------------------------------------ | --------------- | -------------------------------------- |
-| `package.json`                                         | Partially       | Dependencies merged, scripts preserved |
+| `package.json`                                         | Partially       | Dependencies merged, scripts untouched |
 | `tsconfig.json`                                        | Yes             | Managed by Phoenix                     |
 | `eslint.config.js`                                     | Yes             | Managed by Phoenix                     |
 | `prettier.config.js`                                   | Yes             | Managed by Phoenix                     |
-| `.prettierignore`                                      | Yes             | Managed by Phoenix                     |
+| `.prettierignore`                                      | No              | Optional and your own; see below       |
 | `.linguirc`                                            | Yes             | Managed by Phoenix                     |
 | `.nvmrc`                                               | Yes             | Managed by Phoenix                     |
-| `.gitignore`                                           | Partially       | User entries between markers preserved |
+| `.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        |
 | `README.md`                                            | No              | Project documentation                  |
-| `AGENTS.md`                                            | Once            | Coding-agent instructions, yours after |
+| `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.
+
+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.
+
 ### DO NOT EDIT (Fully Auto-Generated)
 
-- **Everything in `.phoenix/`** - Completely regenerated on each build
-- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`
+- **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`
 - `.linguirc`, `.nvmrc`
 - `src/locales/**/*.ts` - Compiled from `.po` catalogs
 - `.env.generated`
@@ -197,23 +209,25 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Agent Guidance
 
-Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
+Coding agents (Claude Code, Codex, Cursor) read the Phoenix agent skills. An `AGENTS.md` is yours to add for your own instructions; sync does not write one. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. The `phoenix-variants` skill has the agent show you several options over the dev preview when a decision is a matter of taste, and build the one you pick. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
 
 Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; use the `phoenix-review` skill instead of `/review`.
 
 ### Markers for Partial Auto-Generation
 
-`.gitignore` preserves custom entries between markers:
+`.gitignore` holds the Phoenix entries between two marker lines. Sync rewrites that block and keeps everything outside it:
 
 ```gitignore
-# phoenix-start
+# ===== BEGIN PHOENIX AUTO-GENERATED =====
 # ... Phoenix-managed ignores ...
-# phoenix-end
+# ===== END PHOENIX AUTO-GENERATED =====
 
-# Your custom ignores below (preserved)
+# Your custom ignores (preserved)
 my-custom-folder/
 ```
 
+With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), sync writes `.gitignore` only when the project is inside a git repository: the project folder or one of its parent folders holds a `.git` entry. Outside a repository it neither creates the file nor changes one that is already there. Run `git init` before the first sync, or sync again after it, to get the file. The legacy pipeline writes the file in every project.
+
 ### Safe to Edit
 
 - `src/` (except compiled `src/locales/**/*.ts` files)
@@ -249,6 +263,7 @@ project-root/
 │   ├── components/                # Phoenix system components (ECS)
 │   ├── elements/                  # UI elements (pages, providers)
 │   ├── expressions/               # Domain logic expressions
+│   ├── actions/                   # Domain action implementations
 │   ├── invariants/                # Domain constraints
 │   ├── transformers/              # Data transformation logic
 │   ├── handlers/                  # Event & lifecycle handlers
@@ -314,6 +329,7 @@ project-root/
 │   │   └── builders.ts
 │   ├── .swc/                      # SWC transpiled sources
 │   ├── .lingui/                   # Compiled i18n catalogs
+│   ├── variants/                  # Option files of `phoenix variants`, written by coding agents
 │   ├── dist/                      # Build output
 │   │   ├── frontend/              # Frontend bundles
 │   │   └── webhooks/              # Webhook bundles
@@ -362,6 +378,7 @@ Domain logic files define the business rules and computed properties of your con
 | Purpose      | Location            | Example Files                                  |
 | ------------ | ------------------- | ---------------------------------------------- |
 | Expressions  | `src/expressions/`  | `table.ts`, `legs.ts`, `module.ts`             |
+| Actions      | `src/actions/`      | `move-part.ts`, `swap-cabinets.ts`             |
 | Invariants   | `src/invariants/`   | `top.ts`, `legs.ts`                            |
 | Transformers | `src/transformers/` | `fix-table-top-material-update-transformer.ts` |
 | Migrations   | `src/migrations/`   | `v2.ts`, `v3.ts`, `v4.ts`                      |
@@ -510,7 +527,7 @@ The `application.yaml` file contains global application-level settings. These fi
 | Field                | Type     | Description                                                                                                                                                                                       |
 | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `project`            | `string` | Server project `phoenix dev` develops in: a project slug, or `default` for the default project of the signed-in workspace. Read only by the CLI; overridden by `--projectSlug` and `PROJECT_SLUG` |
-| `applicationVersion` | `string` | Semantic version (`x.y.z`) exported as `ApplicationVersion` constant and stored on the deployment record                                                                                          |
+| `applicationVersion` | `string` | Semantic version (`x.y.z`) exported as `ApplicationVersion` constant, stored on the deployment record and named in the banner comment of built bundles                                            |
 | `webComponentTag`    | `string` | Custom HTML web component tag name for embedding                                                                                                                                                  |
 | `pageTitle`          | `string` | Browser page title                                                                                                                                                                                |
 

package/dist/docs/phoenix/quickstart.mdx

@@ -104,10 +104,10 @@ pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix sync` keeps `spec/` and `src/` as your authored inputs and generates the application shell, scripts, types, and `.phoenix/` implementation. Start the generated development script without a server:
+`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
-pnpm dev:local
+pnpm phoenix dev --persistence local-storage
 ```
 
 Open the URL printed by the command. The application shell loads with the default `<salsita-configurator>` element and an empty 3D scene.

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. `phoenix sync` then adds the rest of the project: package scripts, webhooks, README and lint config.
+`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.
 
 `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.
 
@@ -36,7 +36,7 @@ The starter `spec/application.yaml` begins with `project: default`, which means
 pnpm phoenix login <workspace>
 ```
 
-`phoenix login` opens Studio, where you name the token and approve the sign-in. The CLI suggests `phoenix CLI on <computer>`; a name of your own, such as the agent and the machine, tells your tokens apart later. Studio sends a one-time code back to the CLI on `127.0.0.1`, the CLI exchanges it for a personal token and returns the browser to Studio, which confirms the sign-in. The code only works for the CLI that asked for it and expires after five minutes. **Deny** stops the waiting CLI at once and creates no token. Use `--no-open` to print the link instead of opening a browser.
+`phoenix login` opens Studio, where you name the token and approve the sign-in. Only a super admin of the workspace can open Studio, so only a super admin can approve it. The CLI suggests `phoenix CLI on <computer>`; a name of your own, such as the agent and the machine, tells your tokens apart later. Studio sends a one-time code back to the CLI on `127.0.0.1`, the CLI exchanges it for a personal token and returns the browser to Studio, which confirms the sign-in. The code only works for the CLI that asked for it and expires after five minutes. **Deny** stops the waiting CLI at once and creates no token. Use `--no-open` to print the link instead of opening a browser.
 
 The CLI stores the token in `~/.phoenix/credentials.json`, readable only by you, with one entry per server. `PHOENIX_CREDENTIALS_FILE` moves the file. The token acts for you in your workspace until you revoke it. It stops working when you are removed from the workspace or banned.
 
@@ -44,12 +44,12 @@ The CLI stores the token in `~/.phoenix/credentials.json`, readable only by you,
 
 `login`, `logout` and `deploy` follow the region, not the `SERVER_URL` in the project's `.env`. `dev` follows the region too when `.env` has no `SERVER_URL`:
 
-| Flag                  | Default                              | Description                                      |
-| --------------------- | ------------------------------------ | ------------------------------------------------ |
-| `--region`            | `eu`                                 | Phoenix region of the workspace: `eu` or `us`    |
-| `--serverUrl` / `-su` | the region's server                  | Phoenix server URL, for a local or custom server |
-| `--studioUrl`         | the workspace's Studio in the region | Studio URL of the workspace (`login`)            |
-| `--open`              | `true`                               | Open the approval page in your browser (`login`) |
+| Flag                   | Default                              | Description                                      |
+| ---------------------- | ------------------------------------ | ------------------------------------------------ |
+| `--region`             | `eu`                                 | Phoenix region of the workspace: `eu` or `us`    |
+| `--serverUrl` / `--su` | the region's server                  | Phoenix server URL, for a local or custom server |
+| `--studioUrl`          | the workspace's Studio in the region | Studio URL of the workspace (`login`)            |
+| `--open`               | `true`                               | Open the approval page in your browser (`login`) |
 
 ## 3. Develop
 
@@ -59,9 +59,9 @@ pnpm phoenix dev
 
 Signed in, `phoenix dev` needs no `.env` and nothing set up in Studio. When it starts, it asks the server for your development environment in the project the spec names. The server creates that environment the first time and finds it again on every later run. `phoenix dev` prints the workspace, project and environment it works in, prepares a development deployment there and opens the webhook tunnel, as for any Phoenix project (see [Phoenix CLI](?path=/docs/phoenix-phoenix-cli--docs)). It then prints the address of the preview as `Preview: <url>`; the preview talks to the server the deployment was prepared on.
 
-Every user of the workspace gets their own development environment, so a teammate who clones the project and signs in doesn't overwrite your schema or take over your webhooks. The development environment is separate from `production`: nothing you do in `phoenix dev` changes the live configurator.
+Every user who signs the CLI in gets their own development environment, so a teammate (a super admin of the workspace, like you) who clones the project and signs in doesn't overwrite your schema or take over your webhooks. The development environment is separate from `production`: nothing you do in `phoenix dev` changes the live configurator.
 
-`pnpm dev:local` still runs the project without any server, with state kept in the browser.
+`pnpm phoenix dev --persistence local-storage` still runs the project without any server, with state kept in the browser.
 
 Coding agents follow the generated `phoenix` skill: before their first change they start `phoenix dev` and open the preview in your browser, and after `phoenix deploy` starts a build they open its page in Studio.
 
@@ -94,9 +94,10 @@ Studio's **Builds & deployments** page lists your builds and shows which one you
 Tell us what is broken, confusing or missing, from wherever you are:
 
 - In Studio, **Send beta feedback** in the sidebar opens a short form.
-- In the terminal, `pnpm phoenix feedback "<message>" --type bug|idea|other` sends it with your sign-in. See the [CLI reference](?path=/docs/phoenix-phoenix-cli--docs).
+- In the terminal, `pnpm phoenix feedback "<message>" --type bug|idea|other` sends it with your sign-in, and `--file <path>` sends a text file instead of the argument. See the [CLI reference](?path=/docs/phoenix-phoenix-cli--docs).
+- On a build's page in Studio, **Download sources** downloads the archive `phoenix deploy` uploaded for that build, so a report only needs to name the build.
 
-Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. They are told never to include secrets, customer data or your project's source. After a deploy goes live, the agent also asks you, once per conversation, to rate building with Phoenix from 0 to 10; it tells you the answer goes to the Phoenix team, shows the message and sends it only after you approve it.
+Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. A report names the build with its Studio page link and the live configurator, says what the agent was doing, what happened and what it expected, quotes the exact error and ends with a condensed conversation log. Agents are told never to include secrets, credentials or personal data; parts of your project and your own words go in only through a draft you approved. When you are done with the configurator, the agent also asks you, once per conversation, to evaluate the run: minutes spent, then scores from 0 to 10 for the agent's guidance, functionality, UX, 3D quality, UI visuals and the overall result, and your comments. It asks one question at a time, never picks a score for you, tells you the answers go to the Phoenix team, shows the message and sends it only after you approve it.
 
 ## Known limits
 
@@ -106,4 +107,5 @@ Coding agents working in your project use the same command, guided by the genera
 - `phoenix deploy` always deploys to the workspace's default project; it doesn't read `project` from the spec yet.
 - Only `phoenix dev` works from the sign-in. `phoenix deployment:prepare-dev` still needs the `.env` block of a Studio development environment.
 - Every deploy uploads the whole project; there are no incremental uploads.
-- Your own environment variables can't use platform names such as `LAMBDA_FUNCTION_NAME` or the `AWS_` prefix. A deploy that sets them fails before it registers.
+- Your own environment variables are set in Studio under Environment, by a super admin of the workspace, and apply from the next deploy. `phoenix dev` doesn't receive them: your development environment has its own variables. A build reads them from `process.env`; a webhook reads the ones the spec declares under `env.webhook`, through `phx.webhooksEnv` (see [Webhooks](?path=/docs/phoenix-webhooks--docs)). They can't use platform names such as `LAMBDA_FUNCTION_NAME`, the `AWS_` prefix, the identity provider settings such as `CLERK_API_KEY`, or names the CLI and the deploy tooling read themselves, such as `SERVER_URL` or `NODE_OPTIONS`; Studio refuses those names.
+- Only super admins of a workspace can open its Studio. Admins and users see a page that says so.

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

@@ -148,7 +148,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
 
@@ -991,7 +991,7 @@ Save the same OAuth client ID, client secret, and base URL in the customer's **C
 JWT_SECRET_BASE64=<base64 of a long random key>
 ```
 
-For a deployment, run `pnpm phoenix deployment:prepare` followed by `pnpm phoenix deployment:finish`. For local development, run `pnpm deployment:prepare-local`. These current commands use the customer settings stored in Studio; the removed `environment:create` and `deployment:register` commands are not part of the setup flow.
+For a deployment, run `pnpm phoenix deployment:prepare` followed by `pnpm phoenix deployment:finish`. For local development, run `pnpm phoenix deployment:prepare-local`. These current commands use the customer settings stored in Studio; the removed `environment:create` and `deployment:register` commands are not part of the setup flow.
 
 #### Clerk organization
 

package/dist/docs/recipes-and-delete/recipe-hierarchy-selection.mdx

@@ -160,21 +160,23 @@ Room: {
 
 ### Entity Replacement Transformer
 
-Configure transformers to handle entity deselection when replacement occurs. This ensures clean state transitions:
+Add a transformer to handle entity deselection when replacement occurs. This ensures clean state transitions:
 
 ```typescript
-const config = configuratorBuilder
-  .withTransformers(ctx => {
-    return [
-      phx.frontend.transformerBuilder.when
-        .entity(['RedSpecialConsole', 'BlueSpecialConsole'])
-        .replacedWith(['RedSpecialConsole', 'BlueSpecialConsole'])
-        .then.deselect()
-        .build('Deselect special console on replacement')
-        .register(ctx),
-    ]
-  })
-  .buildConfig()
+// src/transformers/deselect-special.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(['RedSpecialConsole', 'BlueSpecialConsole'])
+  .replacedWith(['RedSpecialConsole', 'BlueSpecialConsole'])
+  .then.deselect()
+  .build('deselect-special')
+```
+
+Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by name. For a transformer made with `build(name)` that is the name passed to `build(...)`, which must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). For a plain-function export it is the file name:
+
+```yaml
+# spec/application.yaml
+transformers:
+  - name: deselect-special
 ```
 
 ### Initial Configuration

package/dist/docs/relations/hierarchy.mdx

@@ -69,8 +69,19 @@ relations:
 
 Consider enabling select-parent-on-deselection to keep selection stable:
 
-```ts
-.withTransformers(ctx => [{ priority: 101, transformer: createSelectParentOnDeselectionTransformer(ctx) }])
+```typescript
+// src/transformers/select-parent.ts
+import { createSelectParentOnDeselectionTransformer } from '@salsita-ai/sdk/domain'
+
+export default createSelectParentOnDeselectionTransformer
+```
+
+Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by name. For a transformer made with `build(name)` that is the name passed to `build(...)`, which must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). For a plain-function export it is the file name:
+
+```yaml
+# spec/application.yaml
+transformers:
+  - name: select-parent
 ```
 
 ## Example

package/dist/docs/ux-guidelines/choosing-a-control.mdx

@@ -13,6 +13,15 @@ Choose the control from how users understand the options.
    - Long labels or descriptions: list selector.
    - Many text options or tight space: select dropdown.
 
+## Adding, removing, and placing
+
+The controls above choose a value for a property. A decision that changes which parts exist is a different kind of choice, and where its control lives is part of the decision.
+
+- Put the control in the scene when position carries the meaning of the action: where the next part goes, what sits on top of this one, which part this removes. An add FAB stands at the place the new part will occupy, and a delete FAB sits on the part it removes.
+- Put the control in the sidebar when the choice is a catalogue pick and position is incidental, or when the scene offers no obvious place for the control to stand.
+- A product the user assembles or arranges is the first case. A sidebar list for it turns building into list-keeping and leaves the scene a picture of the result rather than the place the user works.
+- Both forms offer the same recipes, so this chooses where the user acts, not what they can add.
+
 ## Common control guidance
 
 - Order properties in the sequence users naturally make the decisions.
@@ -31,3 +40,5 @@ Choose the control from how users understand the options.
 - [Select dropdown](?path=/docs/controls-select-attribute-select--docs)
 - [Text input](?path=/docs/design-system-inputs-textinput--docs)
 - [Color picker](?path=/docs/controls-color-picker-input--docs)
+- [Scene add and delete FABs](?path=/docs/fabs-basic--docs)
+- [Recipe panel in the sidebar](?path=/docs/recipes-delete-simple--docs)

package/dist/domain/admin-domain/__generated/enhanced-model.d.ts

@@ -3,8 +3,7 @@
  * @file enhanced-model.ts
  * @description Standalone common-admin enhanced model types.
  */
-import type { $DomainEntity } from '../../core/model.js';
-import type { Violation } from '../../invariants/violation.js';
+import type { $DomainEntity, Violation } from '../../core/index.js';
 import type { Admin, ConnectedDataConfig, DataTable, DummyDoNotUse, Preset, PresetCategory, Recipe } from './model/index.js';
 export type PresetCategoryExpressions = {
     readonly $isDraft: boolean;

package/dist/domain/admin-domain/__generated/model/versions/v1.d.ts

@@ -3,7 +3,7 @@
  * @file model/versions/v1.ts
  * @description Historical domain model types for the migration chain.
  */
-import type { DomainEntityId } from '../../../../core/model.js';
+import type { DomainEntityId } from '../../../../core/index.js';
 export interface Admin {
     readonly id: DomainEntityId<'Admin'>;
     readonly type: 'Admin';

package/dist/domain/admin-domain/__generated/model/versions/v2.d.ts

@@ -3,7 +3,7 @@
  * @file model/versions/v2.ts
  * @description Historical domain model types for the migration chain.
  */
-import type { DomainEntityId } from '../../../../core/model.js';
+import type { DomainEntityId } from '../../../../core/index.js';
 export type GenericDomainEntity = {
     readonly id: DomainEntityId<string>;
     readonly type: string;

package/dist/domain/admin-domain/__generated/model/versions/v3.d.ts

@@ -3,7 +3,7 @@
  * @file model/versions/v3.ts
  * @description Historical domain model types for the migration chain.
  */
-import type { DomainEntityId } from '../../../../core/model.js';
+import type { DomainEntityId } from '../../../../core/index.js';
 export type GenericDomainEntity = {
     readonly id: DomainEntityId<string>;
     readonly type: string;

package/dist/domain/admin-domain/__generated/model/versions/v4.d.ts

@@ -4,7 +4,7 @@
  * @description Historical domain model types for the migration chain.
  */
 import type { MultilingualString } from '@salsita-ai/common/utils';
-import type { DomainEntityId } from '../../../../core/model.js';
+import type { DomainEntityId } from '../../../../core/index.js';
 export type GenericDomainEntity = {
     readonly id: DomainEntityId<string>;
     readonly type: string;

package/dist/domain/admin-domain/__generated/model/versions/v5.d.ts

@@ -4,7 +4,7 @@
  * @description Historical domain model types for the migration chain.
  */
 import type { MultilingualString } from '@salsita-ai/common/utils';
-import type { DomainEntityId } from '../../../../core/model.js';
+import type { DomainEntityId } from '../../../../core/index.js';
 export type GenericDomainEntity = {
     readonly id: DomainEntityId<string>;
     readonly type: string;

package/dist/domain/admin-domain/__generated/model/versions/v6.d.ts

@@ -4,8 +4,8 @@
  * @description Standalone versioned domain model and reflections.
  */
 import type { MultilingualString } from '@salsita-ai/common/utils';
-import type { DomainEntityId } from '../../../../core/model.js';
-import { DomainEntityReflection, RawAliasReflection } from '../../../../core/reflection.js';
+import type { DomainEntityId } from '../../../../core/index.js';
+import { DomainEntityReflection, RawAliasReflection } from '../../../../core/index.js';
 export declare const modelVersion = 6;
 export type GenericDomainEntity = {
     readonly id: DomainEntityId<string>;

package/dist/domain/admin-domain/__generated/model/versions/v6.js

@@ -1 +1 @@
-import{DomainEntityReflection as e,RawAliasReflection as t}from"../../../../core/reflection.js";export const modelVersion=6;export const Admin=new e("Admin",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]}},required:["commonAdminModelVersion"],additionalProperties:!1}]);export const Preset=new e("Preset",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]},name:{$ref:"#/$defs/MultilingualString"},description:{$ref:"#/$defs/MultilingualString"},index:{type:"number"},visible:{type:"boolean"},categoryId:{oneOf:[{$ref:"#/$defs/DomainEntityId"},{type:"null"}]},configurationId:{oneOf:[{type:"string"},{type:"null"}]},revisionId:{oneOf:[{type:"string"},{type:"null"}]},ownerToken:{oneOf:[{type:"string"},{type:"null"}]},readToken:{oneOf:[{type:"string"},{type:"null"}]},thumbnailUrl:{oneOf:[{type:"string"},{type:"null"}]},customThumbnailUrl:{oneOf:[{type:"string"},{type:"null"}]},tags:{type:"array",items:{type:"string"}}},required:["commonAdminModelVersion","name","description","index","visible","categoryId","configurationId","revisionId","ownerToken","readToken","thumbnailUrl","customThumbnailUrl","tags"],additionalProperties:!1,$defs:{MultilingualString:{type:"object",properties:{$lang:{type:"object",additionalProperties:{type:"string"}}},required:["$lang"],additionalProperties:!1},DomainEntityId:{type:"string",pattern:"^[A-Z]\\w*-\\d+$"}}}]);export const PresetCategory=new e("PresetCategory",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]},name:{$ref:"#/$defs/MultilingualString"},index:{type:"number"},visible:{type:"boolean"},description:{$ref:"#/$defs/MultilingualString"}},required:["commonAdminModelVersion","name","index","visible","description"],additionalProperties:!1,$defs:{MultilingualString:{type:"object",properties:{$lang:{type:"object",additionalProperties:{type:"string"}}},required:["$lang"],additionalProperties:!1}}}]);export const Recipe=new e("Recipe",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]},name:{$ref:"#/$defs/MultilingualString"},description:{$ref:"#/$defs/MultilingualString"},collection:{type:"string"},index:{type:"number"},visible:{type:"boolean"},configuration:{anyOf:[{$ref:"#/$defs/RecipeConfiguration"},{type:"null"}]}},required:["commonAdminModelVersion","name","description","collection","index","visible","configuration"],additionalProperties:!1,$defs:{MultilingualString:{type:"object",properties:{$lang:{type:"object",additionalProperties:{type:"string"}}},required:["$lang"],additionalProperties:!1},RecipeConfiguration:{type:"object",properties:{modelVersion:{type:"integer"},entities:{type:"array",items:{$ref:"#/$defs/GenericDomainEntity"}},rootEntityType:{type:"string"},rootRecipeId:{type:"string"},recipeIds:{type:"array",items:{type:"string"}},configurationId:{type:"string"},revisionId:{type:"string"},ownerToken:{type:"string"}},additionalProperties:!1,required:["entities","rootEntityType","rootRecipeId","recipeIds","modelVersion","configurationId","revisionId","ownerToken"]},GenericDomainEntity:{type:"object",properties:{id:{$ref:"#/$defs/DomainEntityId"},type:{type:"string"}},additionalProperties:!0,required:["id","type"]},DomainEntityId:{type:"string",pattern:"^[A-Z]\\w*-\\d+$"}}}]);export const ConnectedDataConfig=new e("ConnectedDataConfig",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]},dataEntryKey:{type:"string"},provider:{type:"string"},externalFileId:{type:"string"},fileLabel:{type:"string"},driveId:{oneOf:[{type:"string"},{type:"null"}]},tabSelection:{type:"array",items:{type:"string"}},headerRowIndex:{oneOf:[{type:"integer"},{type:"null"}]}},required:["commonAdminModelVersion","dataEntryKey","provider","externalFileId","fileLabel","driveId","tabSelection","headerRowIndex"],additionalProperties:!1}]);export const DataTable=new e("DataTable",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]},dataEntryKey:{type:"string"},data:{type:"object"}},required:["commonAdminModelVersion","dataEntryKey","data"],additionalProperties:!1}]);export const DummyDoNotUse=new e("DummyDoNotUse",[{type:"object",properties:{},required:[],additionalProperties:!1}]);export const RootEntity=new t("RootEntity",[Admin]);export const CommonAdminEntity=new t("CommonAdminEntity",[Admin,Preset,PresetCategory,Recipe,ConnectedDataConfig,DataTable]);export const AnyDomainEntity=new t("AnyDomainEntity",[Admin,Preset,PresetCategory,Recipe,ConnectedDataConfig,DataTable,DummyDoNotUse]);export const aliases={RootEntity:RootEntity.types,CommonAdminEntity:CommonAdminEntity.types,AnyDomainEntity:AnyDomainEntity.types};
+import{DomainEntityReflection as e,RawAliasReflection as t}from"../../../../core/index.js";export const modelVersion=6;export const Admin=new e("Admin",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]}},required:["commonAdminModelVersion"],additionalProperties:!1}]);export const Preset=new e("Preset",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]},name:{$ref:"#/$defs/MultilingualString"},description:{$ref:"#/$defs/MultilingualString"},index:{type:"number"},visible:{type:"boolean"},categoryId:{oneOf:[{$ref:"#/$defs/DomainEntityId"},{type:"null"}]},configurationId:{oneOf:[{type:"string"},{type:"null"}]},revisionId:{oneOf:[{type:"string"},{type:"null"}]},ownerToken:{oneOf:[{type:"string"},{type:"null"}]},readToken:{oneOf:[{type:"string"},{type:"null"}]},thumbnailUrl:{oneOf:[{type:"string"},{type:"null"}]},customThumbnailUrl:{oneOf:[{type:"string"},{type:"null"}]},tags:{type:"array",items:{type:"string"}}},required:["commonAdminModelVersion","name","description","index","visible","categoryId","configurationId","revisionId","ownerToken","readToken","thumbnailUrl","customThumbnailUrl","tags"],additionalProperties:!1,$defs:{MultilingualString:{type:"object",properties:{$lang:{type:"object",additionalProperties:{type:"string"}}},required:["$lang"],additionalProperties:!1},DomainEntityId:{type:"string",pattern:"^[A-Z]\\w*-\\d+$"}}}]);export const PresetCategory=new e("PresetCategory",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]},name:{$ref:"#/$defs/MultilingualString"},index:{type:"number"},visible:{type:"boolean"},description:{$ref:"#/$defs/MultilingualString"}},required:["commonAdminModelVersion","name","index","visible","description"],additionalProperties:!1,$defs:{MultilingualString:{type:"object",properties:{$lang:{type:"object",additionalProperties:{type:"string"}}},required:["$lang"],additionalProperties:!1}}}]);export const Recipe=new e("Recipe",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]},name:{$ref:"#/$defs/MultilingualString"},description:{$ref:"#/$defs/MultilingualString"},collection:{type:"string"},index:{type:"number"},visible:{type:"boolean"},configuration:{anyOf:[{$ref:"#/$defs/RecipeConfiguration"},{type:"null"}]}},required:["commonAdminModelVersion","name","description","collection","index","visible","configuration"],additionalProperties:!1,$defs:{MultilingualString:{type:"object",properties:{$lang:{type:"object",additionalProperties:{type:"string"}}},required:["$lang"],additionalProperties:!1},RecipeConfiguration:{type:"object",properties:{modelVersion:{type:"integer"},entities:{type:"array",items:{$ref:"#/$defs/GenericDomainEntity"}},rootEntityType:{type:"string"},rootRecipeId:{type:"string"},recipeIds:{type:"array",items:{type:"string"}},configurationId:{type:"string"},revisionId:{type:"string"},ownerToken:{type:"string"}},additionalProperties:!1,required:["entities","rootEntityType","rootRecipeId","recipeIds","modelVersion","configurationId","revisionId","ownerToken"]},GenericDomainEntity:{type:"object",properties:{id:{$ref:"#/$defs/DomainEntityId"},type:{type:"string"}},additionalProperties:!0,required:["id","type"]},DomainEntityId:{type:"string",pattern:"^[A-Z]\\w*-\\d+$"}}}]);export const ConnectedDataConfig=new e("ConnectedDataConfig",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]},dataEntryKey:{type:"string"},provider:{type:"string"},externalFileId:{type:"string"},fileLabel:{type:"string"},driveId:{oneOf:[{type:"string"},{type:"null"}]},tabSelection:{type:"array",items:{type:"string"}},headerRowIndex:{oneOf:[{type:"integer"},{type:"null"}]}},required:["commonAdminModelVersion","dataEntryKey","provider","externalFileId","fileLabel","driveId","tabSelection","headerRowIndex"],additionalProperties:!1}]);export const DataTable=new e("DataTable",[{type:"object",properties:{commonAdminModelVersion:{enum:[6]},dataEntryKey:{type:"string"},data:{type:"object"}},required:["commonAdminModelVersion","dataEntryKey","data"],additionalProperties:!1}]);export const DummyDoNotUse=new e("DummyDoNotUse",[{type:"object",properties:{},required:[],additionalProperties:!1}]);export const RootEntity=new t("RootEntity",[Admin]);export const CommonAdminEntity=new t("CommonAdminEntity",[Admin,Preset,PresetCategory,Recipe,ConnectedDataConfig,DataTable]);export const AnyDomainEntity=new t("AnyDomainEntity",[Admin,Preset,PresetCategory,Recipe,ConnectedDataConfig,DataTable,DummyDoNotUse]);export const aliases={RootEntity:RootEntity.types,CommonAdminEntity:CommonAdminEntity.types,AnyDomainEntity:AnyDomainEntity.types};