@salsita-ai/sdk 0.50.0-develop.6d8967bc99 → 0.50.0-develop.6fc83d7732

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

@@ -8,9 +8,9 @@ Your workspace's Studio shows the setup, the link to your configurator and the s
 
 ## Before you start
 
-- **Package access:** `@salsita-ai/sdk` is public on npm; `npx` and `pnpm install` download it without a registry token.
+- **Package access:** `@salsita-ai/sdk` is public on npm; any package manager downloads it without a registry token.
 - **Workspace details:** you need your workspace slug and its Phoenix region (`eu` or `us`), which you also received with your workspace.
-- **Tools:** Node.js and pnpm.
+- **Tools:** Node.js and a package manager. The commands below use pnpm; with npm, run `npm install` and `npx phoenix …` instead, with Yarn `yarn phoenix …`, with Bun `bunx phoenix …`.
 - **SDK build:** during the internal beta, use the `canary` build of the SDK, as the commands below do. It is published from every change to the platform, so it is newer than the last release.
 
 ## 1. Create a project
@@ -22,11 +22,11 @@ pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix init [folder]` writes the starter project: `package.json`, `pnpm-workspace.yaml` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it. `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` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it and on the packages the SDK requires next to it (React, three.js, MUI, Lingui and the others, with their type packages), with ESLint and Prettier at the versions the SDK uses itself. Its `package.json` has the `dev`, `build`, `deploy`, `check` and `fix` scripts, which are yours to change. `phoenix sync` then adds the rest of the project: the TypeScript, lint and formatting config and the agent skills. It writes no webhook code: a project without `src/webhooks/index.ts` gets a built-in webhook (see [Webhook Entry Point](?path=/docs/phoenix-webhooks--docs#webhook-entry-point)). It writes a `.gitignore` only when the folder is inside a git repository; run `git init` before the first sync, or sync again after it, to get the file.
 
-`init` only writes these files: it asks nothing and contacts no server. It refuses a folder that already has a `spec/` folder. A `package.json` already in the folder is kept, as long as it depends on the SDK.
+`init` only writes these files: it asks nothing and contacts no server. It refuses a folder that already has a `spec/` folder. A `package.json` already in the folder is kept, as long as it depends on the SDK, and gains only the entries it lacks (see [Starting a New Project](?path=/docs/phoenix-phoenix-cli--docs#starting-a-new-project)).
 
-`pnpm-workspace.yaml` holds the pnpm settings the install needs: it allows the build scripts of the SDK's dependencies and exempts `@salsita-ai/*` packages from pnpm's minimum release age, so a build of the SDK published today installs. The file is yours to edit, for example to allow the build script of a dependency you add. `phoenix sync` adds these entries when they are missing and keeps the values you set. A project inside a pnpm monorepo gets no file of its own; the workspace root holds the settings.
+Phoenix writes no package-manager settings. With pnpm 11, add a `pnpm-workspace.yaml` that allows the build scripts of the SDK's dependencies before the first install; [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager) has the file.
 
 The starter `spec/application.yaml` begins with `project: default`, which means the default project of the workspace you sign in to. Leave it as it is; a workspace has one project.
 
@@ -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
 
@@ -61,7 +61,7 @@ Signed in, `phoenix dev` needs no `.env` and nothing set up in Studio. When it s
 
 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.
 
@@ -76,16 +76,18 @@ pnpm phoenix deploy
 `phoenix deploy` goes through these steps:
 
 1. It validates the application spec.
-2. It packs the project files: the `.yaml` files in `spec`, everything in `src`, `mocks`, `assets`, `public` and `templates`, and `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.gitignore`, `CLAUDE.md` and `.cursor/rules/phoenix.mdc`. Every `node_modules`, `.phoenix` and `__generated` folder, every `.DS_Store` and `._*` file and every `.env` and `.env.*` file are left out, at any depth.
+2. It packs the project files: the `.yaml` files in `spec`, everything in `src`, `mocks`, `assets`, `public` and `templates`, and `package.json`, `tsconfig.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.gitignore`, `CLAUDE.md` and `.cursor/rules/phoenix.mdc`. Every `node_modules`, `.phoenix` and `__generated` folder, every `.DS_Store` and `._*` file and every `.env` and `.env.*` file are left out, at any depth.
 3. It asks the server for a build. The server compares your domain model with the deployed one and refuses, before anything is uploaded, a model that changed under an already deployed model version; see [Migrations](?path=/docs/phoenix-migrations--docs).
 4. It uploads the archive, which may be up to 200 MB.
 5. It starts the build, prints a link to the build's page in Studio and follows the build until your configurator is live, then prints its URL.
 
-On the server, the install follows your `pnpm-lock.yaml` and `pnpm-workspace.yaml`, so it allows the same build scripts and package versions as `pnpm install` on your computer. The build runs without platform secrets. It sees only your own environment variables and the public platform values, the [build environment](?path=/docs/phoenix-phoenix-cli--docs) that `phoenix deployment:build-envs` writes. The trusted deploy step then publishes the frontend, webhooks and assets.
+On the server, the install runs pnpm. It follows your `pnpm-lock.yaml` and `pnpm-workspace.yaml` when the project has them, so a pnpm project gets the same build scripts and package versions as on your computer; without them, pnpm resolves `package.json` with the settings the SDK needs. The build runs without platform secrets. It sees only your own environment variables and the public platform values, the [build environment](?path=/docs/phoenix-phoenix-cli--docs) that `phoenix deployment:build-envs` writes. The trusted deploy step then publishes the frontend, webhooks and assets.
 
 If the build fails, is cancelled or takes too long, `phoenix deploy` prints the end of the build log and exits with an error. `--no-wait` returns as soon as the build starts.
 
-Studio's **Builds & deployments** page lists your builds and shows which one your configurator serves. Each build shows its progress, its error and the full build log while it runs.
+Studio's **Builds & deployments** page lists your builds, 20 to a page, and shows which one your configurator serves. Filter it to the live build or to the builds that failed. Each build shows its progress, its error and the full build log while it runs, and who deployed it with which CLI token.
+
+**Rebuild** on a build's page builds the files uploaded with that build again, with your environment variables as they are now, without a new `phoenix deploy`. Use it after changing a variable, or when a build failed for a reason on our side. If the rebuild succeeds it goes live, so rebuilding an older build rolls production back to it.
 
 `phoenix deploy` refuses symlinks, hard-linked files and other special files among the project files, because builds only accept regular files. Packing uses the system `tar`, which macOS, Linux and Windows 10 or later all include. The build runner checks the uploaded archive again and keeps only project files, so a file outside the list above never reaches the build.
 
@@ -95,7 +97,7 @@ 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, 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.
+- 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. 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.
 
@@ -107,5 +109,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 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.
+- Your own environment variables are set in Studio under Environment, by a super admin of the workspace, and apply from the next deploy. After a change, **Redeploy #N now** there rebuilds your live build with the new values, without a new `phoenix deploy`; it appears once your own build is live. `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/sessions-and-access.mdx

@@ -427,6 +427,8 @@ The `readonly` web component property lets the host force view mode without chan
 
 Because an owner-token session can be forced read-only client-side while the server still accepts writes from that owner token, Phoenix skips persistence and logs a warning instead of updating the configuration. This guards against the configuration being silently overwritten by code paths that mutate state in read-only mode. UI that triggers significant changes (anything that produces a new revision) should still be disabled when `accessInfo.viewMode` is true — the warning is a backstop, not a substitute.
 
+The assistant follows the same read-only rule as the UI: its `apply` tool refuses changes while `accessInfo.viewMode` is true, that is with a read-revision token or while `readonly` is set, and makes them again once it is false. A switch of `readonly` takes effect at once, in both directions, and the configurator loads the configuration again. A change applied after `readonly` is cleared and before the configuration has loaded again is not saved; saving resumes once it has loaded. The `query` tool keeps working, including its dry-run mutations.
+
 ```html
 <salsita-configurator readonly></salsita-configurator>
 ```

package/dist/docs/phoenix/testing.mdx

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

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

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

package/dist/docs/phoenix/webhooks.mdx

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

@@ -56,6 +56,8 @@ sceneEntitySelectHotspot:
 
 The `title` supplies the tooltip text. Tooltips appear on hover by default; `tooltipVisibility` can instead keep them visible continuously, while the camera is still, or hide them. The `showWhen` property controls visibility based on selection state. The default `['unselected']` hides hotspots once entities are selected, keeping the view clean. Setting it to `['selected', 'unselected']` keeps hotspots always visible.
 
+The hotspot is the entity element `SelectionHotspot`. A project replaces its look by registering its own with `phx.frontend.createSelectionHotspot`, which receives `onSelect`, the selection with its analytics event; the settings above still apply. See [Configurator Interface → In-Scene Controls](?path=/docs/phoenix-configurator-interface--docs#in-scene-controls).
+
 ## System Component Interfaces
 
 ```typescript

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/implementation/common-admin-expressions.d.ts

@@ -1,4 +1,4 @@
-import type { DomainEntity, DomainState, ExpressionContext, Violation } from '../../core/index.js';
+import type { DomainEntity, MigrateFunction, Violation } from '../../core/index.js';
 import type { ChildEntitySelectionOption } from '../../system-components/child-entity-selection.js';
 import type { RecipeListItem } from '../../system-components/index.js';
 import type { SwatchOptionMap } from '../../system-components/material-swatch.js';
@@ -17,11 +17,23 @@ export declare const commonAdminCustomExpressions: {
         readonly $isDraft: (self: PresetCategory) => boolean;
     };
 };
+/**
+ * An expression of this file. It reads nothing of the entity or of the state, and of the context
+ * only `CONTEXT`, so it is written against that part alone: it fits every entity of every project
+ * whose expression context has that part, because the project's own entity view, state and context
+ * are assignable to these parameters.
+ */
+type CommonAdminExpression<CONTEXT, T> = (self: unknown, state: unknown, ctx: CONTEXT) => T;
+/** The part of the expression context a recipe expression reads. */
+interface RecipeExpressionContext<PUBLISHED_DATA> {
+    readonly publishedData: PUBLISHED_DATA;
+    readonly migrate: MigrateFunction<DomainEntity<string>>;
+}
 export declare const CommonAdminExpressionBuilder: {
-    createConstantSwatchExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(swatches: SwatchOptionMap) => ((self: SELF, state: DomainState<ENTITIES>, ctx: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => SwatchOptionMap);
-    createConstantRecipeExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(recipes: RecipeListItem[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => RecipeListItem[]);
-    createConstantChildEntitySelectionExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(entities: ChildEntitySelectionOption[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => ChildEntitySelectionOption[]);
-    createRecipeExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends CommonAdminPublishedData, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(collection: string, defaults: RecipeListItem[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => RecipeListItem[]);
+    createConstantSwatchExpression: (swatches: SwatchOptionMap) => (() => SwatchOptionMap);
+    createConstantRecipeExpression: (recipes: RecipeListItem[]) => (() => RecipeListItem[]);
+    createConstantChildEntitySelectionExpression: (entities: ChildEntitySelectionOption[]) => (() => ChildEntitySelectionOption[]);
+    createRecipeExpression: (collection: string, defaults: RecipeListItem[]) => CommonAdminExpression<RecipeExpressionContext<CommonAdminPublishedData>, RecipeListItem[]>;
 };
 /**
  * Expression helpers for projects with chunked published data.
@@ -30,13 +42,16 @@ export declare const CommonAdminExpressionBuilder: {
  * Use {@link CommonAdminExpressionBuilder} for projects with flat published data.
  */
 export declare const ChunkedCommonAdminExpressionBuilder: {
-    createConstantSwatchExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(swatches: SwatchOptionMap) => ((self: SELF, state: DomainState<ENTITIES>, ctx: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => SwatchOptionMap);
-    createConstantRecipeExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(recipes: RecipeListItem[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => RecipeListItem[]);
-    createConstantChildEntitySelectionExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(entities: ChildEntitySelectionOption[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => ChildEntitySelectionOption[]);
-    createRecipeExpression: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends {
+    createConstantSwatchExpression: (swatches: SwatchOptionMap) => (() => SwatchOptionMap);
+    createConstantRecipeExpression: (recipes: RecipeListItem[]) => (() => RecipeListItem[]);
+    createConstantChildEntitySelectionExpression: (entities: ChildEntitySelectionOption[]) => (() => ChildEntitySelectionOption[]);
+    createRecipeExpression: (collection: string, defaults: RecipeListItem[]) => CommonAdminExpression<RecipeExpressionContext<{
         readonly system?: CommonAdminPublishedData;
-    }, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(collection: string, defaults: RecipeListItem[]) => ((self: SELF, state: DomainState<ENTITIES>, ctx: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => RecipeListItem[]);
+    }>, RecipeListItem[]>;
 };
 export declare const createDataSwatchMap: (tableName: string, chunkKey?: string) => {
-    bind: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>() => (_self: SELF, _state: DomainState<ENTITIES>, ctx: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>) => SwatchOptionMap;
+    bind: () => CommonAdminExpression<{
+        readonly publishedData: Record<string, unknown>;
+    }, SwatchOptionMap>;
 };
+export {};

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

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

package/dist/domain/admin-domain/index.d.ts

@@ -10,9 +10,14 @@ export * from './__generated/model/index.js';
 export * from './implementation/common-admin-expressions.js';
 export * from './implementation/common-admin-publish.js';
 export * from './schema/index.js';
-export declare const createCommonAdminRecipe: import("../domain-context/recipe-system/recipes.js").RecipeFactory<AnyDomainEntity>;
-export declare const attachCommonAdminDomainComponent: DomainComponentOpticBuilder<AnyDomainEntity, import("./index.js").Admin, $Map, PublishedData, SessionData, Record<string, unknown>, Aliases, never, never, never>;
-export declare const commonAdminComponents: import("../index.js").DomainComponentSimpleOptic<AnyDomainEntity, import("./index.js").Admin, PublishedData, SessionData, Record<string, unknown>, import("./index.js").Preset, import("../index.js").SystemComponentType<"attributeSelection", import("../index.js").AttributeSelectionComponentState, "value">>[];
+export declare const createCommonAdminRecipe: import("../index.js").RecipeFactory<AnyDomainEntity>;
+/**
+ * Closed with core's part of the expression context only: `admin-domain/` counts as core and may
+ * not import the runtime. A callback that needs the component reader or a projection is written
+ * through a builder closed with `RuntimeExpressionContext`.
+ */
+export declare const attachCommonAdminDomainComponent: DomainComponentOpticBuilder<AnyDomainEntity, import("./index.js").Admin, $Map, PublishedData, SessionData, Record<string, unknown>, Aliases, never, never, never, unknown>;
+export declare const commonAdminComponents: import("../index.js").DomainComponentSimpleOptic<AnyDomainEntity, import("./index.js").Admin, PublishedData, SessionData, Record<string, unknown>, import("./index.js").Preset, import("../index.js").SystemComponentType<"attributeSelection", import("../index.js").AttributeSelectionComponentState, "value">, unknown>[];
 /**
  * Type-level carrier for the common-admin builder shape consumed by `createAdminInterface`.
  *

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

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

package/dist/domain/application/GetApplicationWrapperHandler.d.ts

@@ -1,7 +1,7 @@
 import type { ComponentType } from 'react';
 import type { $DomainEntity, DomainEntity } from '../core/index.js';
+import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../domain-runtime/index.js';
 import type { ApplicationConfig } from './application-config.js';
-import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from './handler-registration.js';
 export declare const createGetApplicationWrapperHandler: (fn: (ctx: ApplicationConfig<any, any, any, any, any, any, never, any, any, any, any, any, any, any, any, any>) => ComponentType) => SystemPhoenixHandlerRegistration<ApplicationConfig<any, any, any, any, any, any, never, any, any, any, any, any, any, any, any, any>, ComponentType>;
-export type CreateGetApplicationWrapperHandler<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, CHAT_CONTEXT extends Record<string, unknown>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ADMIN_ENTITIES extends DomainEntity<string>, ADMIN_ALLOWED_ROOT_ENTITIES extends ADMIN_ENTITIES, ADMIN_$MAP extends Record<ADMIN_ENTITIES['type'], $DomainEntity<ADMIN_ENTITIES>>, ADMIN_NAVIGATION_STATES extends string, ADMIN_VIEW_STATES extends string> = (fn: (ctx: ApplicationConfig<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>) => ComponentType) => SystemPhoenixHandlerRegistration<ApplicationConfig<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>, ComponentType>;
+export type CreateGetApplicationWrapperHandler = typeof createGetApplicationWrapperHandler;
 export declare const isGetApplicationWrapperHandler: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, CHAT_CONTEXT extends Record<string, unknown>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ADMIN_ENTITIES extends DomainEntity<string>, ADMIN_ALLOWED_ROOT_ENTITIES extends ADMIN_ENTITIES, ADMIN_$MAP extends Record<ADMIN_ENTITIES['type'], $DomainEntity<ADMIN_ENTITIES>>, ADMIN_NAVIGATION_STATES extends string, ADMIN_VIEW_STATES extends string>(handler: HandlerRegistration<ApplicationConfig<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>, ComponentType>) => handler is SystemPhoenixHandlerRegistration<ApplicationConfig<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>, ComponentType>;

package/dist/domain/application/GetThemeHandler.d.ts

@@ -1,5 +1,5 @@
 import type { ThemeOptions } from '@mui/material';
-import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from './handler-registration.js';
+import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../domain-runtime/index.js';
 export declare const GetThemeHandlerName = "GetThemeHandler";
 export declare const createGetThemeHandler: (fn: () => ThemeOptions) => SystemPhoenixHandlerRegistration<void, ThemeOptions>;
 export type CreateGetThemeHandler = (fn: () => ThemeOptions) => SystemPhoenixHandlerRegistration<void, ThemeOptions>;

package/dist/domain/application/GetWebComponentOptions.d.ts

@@ -1,5 +1,5 @@
+import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../domain-runtime/index.js';
 import type { WebComponentOptions } from './application-config.js';
-import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from './handler-registration.js';
 export declare const createGetWebComponentOptionsHandler: (fn: () => WebComponentOptions) => SystemPhoenixHandlerRegistration<undefined, WebComponentOptions>;
 export type CreateGetWebComponentOptionsHandler = (fn: () => WebComponentOptions) => SystemPhoenixHandlerRegistration<undefined, WebComponentOptions>;
 export declare const isGetWebComponentOptionsHandler: (handler: HandlerRegistration<any, any>) => handler is SystemPhoenixHandlerRegistration<undefined, WebComponentOptions>;

package/dist/domain/application/admin-page-factories.d.ts

@@ -1,7 +1,6 @@
-import type { DomainEntityId } from '../core/index.js';
+import type { DataCellValue, DataSchema, DomainEntityId } from '../core/index.js';
 import type { AttributeSelectionComponentState } from '../system-components/attribute-selection.js';
 import type { NavigationListItem, NestedNavigationListItem } from '../system-components/navigation-panel-list.js';
-import type { DataCellValue, DataSchema } from './application-config.js';
 interface PresetPagesConfig {
     readonly categoryNavigationState: string;
     readonly presetNavigationState: string;