@salsita-ai/sdk 0.50.0-develop.68d6fe1d1b → 0.50.0-develop.71209819cd

package/dist/docs/other-features/side-effects.mdx

@@ -66,40 +66,48 @@ With following control structure. The top input selects the material, the bottom
 The transformer is used to change the finish if necessary and show the notification.
 
 ```typescript
-configuratorBuilder
-  .withTransformers(domainContext => [
-    phx.frontend.transformerBuilder.when
-      .entity(['Plate'])
-      .modified({ atFields: ['material'] })
-      .causes.self.violation(['finishNotAvailable'])
-      .then.applySideEffect(({ update, getOld$Entity }) => {
-        const oldPlate = getOld$Entity()
-        const newMaterial = update.stateDelta.material
-
-        const validMaterial =
-          availableMaterials.find(m => m.material === newMaterial && m.finish === oldPlate.finish) ??
-          availableMaterials.find(m => m.material === newMaterial)
-
-        if (!validMaterial || validMaterial.finish === oldPlate.finish) {
-          return []
-        }
-
-        // create an additional update that will fix the material finish
-        const fixUpdate = phx.frontend.updates.DomainEntityModification({
-          entityId: oldPlate.id,
-          stateDelta: {
-            finish: validMaterial.finish,
-          },
-          updateTag: 'fix.finish',
-          hint: msg`Material finish was adjusted`, // specify a hint for the user (side effect)
-        })
-
-        return [fixUpdate]
-      })
-      .build('Fix material finish')
-      .register(domainContext),
-  ])
-  .buildConfig()
+// src/transformers/fix-finish.ts
+import { msg } from '@lingui/core/macro'
+
+import { availableMaterials } from '../_shared/materials.js'
+
+export default phx.frontend.transformerBuilder.when
+  .entity(['Plate'])
+  .modified({ atFields: ['material'] })
+  .causes.self.violation(['finishNotAvailable'])
+  .then.applySideEffect(({ update, getOld$Entity }) => {
+    const oldPlate = getOld$Entity()
+    const newMaterial = update.stateDelta.material
+
+    const validMaterial =
+      availableMaterials.find(m => m.material === newMaterial && m.finish === oldPlate.finish) ??
+      availableMaterials.find(m => m.material === newMaterial)
+
+    if (!validMaterial || validMaterial.finish === oldPlate.finish) {
+      return []
+    }
+
+    // create an additional update that will fix the material finish
+    const fixUpdate = phx.frontend.updates.DomainEntityModification({
+      entityId: oldPlate.id,
+      stateDelta: {
+        finish: validMaterial.finish,
+      },
+      updateTag: 'fix.finish',
+      hint: msg`Material finish was adjusted`, // specify a hint for the user (side effect)
+    })
+
+    return [fixUpdate]
+  })
+  .build('fix-finish')
+```
+
+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: fix-finish
 ```
 
 ### Hints and the AI assistant

package/dist/docs/other-features/transformers.mdx

@@ -102,7 +102,7 @@ export const removeExtraneousBranchesAndLeavesWhenShortened = phx.frontend.trans
     - With `overrideMatchinUpdates(ctx => /* side effect updates */)` the updates returned by the provided callback will replace the original **matched update**. This will be triggered for every matching update. Note that this action is not available in events which are not bound to a specific update - such as a violation check without a defined cause.
     - With `overrideAllUpdates(ctx => /* side effect updates */)` the updates returned by the provided callback will replace all original updates. This will be triggered only once for a single run of the transformer. This allows for implementation of transformers that behave similarly as the raw `UpdateTransformer`
   - High-level actions: `select`, `deselect`, `navigate`, `changeView` - more on these in the other examples.
-- `build(name)` is the final step to create the transformer. Assign a descriptive name (no restrictions) to easily identify the transformer while tracing. Note that this returns a `RegistrableTransformer` which needs to be registered using the `register(domainContext)` method. This is usually done in the `.withTransformers()` method of the configurator builder.
+- `build(name)` is the final step to create the transformer. The name identifies the transformer while tracing, and it is the name the `transformers` section of the spec refers to, so it must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). Note that this returns a `RegistrableTransformer`. Default-export it from a file in `src/transformers/` and list the name passed to `build(...)` in the `transformers` section of the spec; the generated code registers it. The shorter snippets on this page use descriptive names for readability; the complete implementation below uses names that match its files.
 
 ### Side-Effect on Update Causing Another Entity's Violation
 

package/dist/docs/phoenix/admin.mdx

@@ -427,43 +427,28 @@ For technical details about data transformation and storage, see [Data Sources -
 
 ## Web Component Integration
 
-Admin functionality integrates through the configurator builder rather than requiring separate web component setup.
+Admin functionality is part of the same application as the configurator and needs no separate web component setup.
 
-### Configurator Builder Setup
+### Registering Admin Components
 
-In phx-cli projects, frontend entry is auto-generated in `.phoenix/`. Admin components are registered through `src/admin/components/`:
+The frontend entry is generated into `.phoenix/`, so a project never calls the configurator builder itself. Every file
+in `src/admin/components/` is picked up by its location and its default export is registered as admin components:
 
 ```typescript
 // src/admin/components/admin-components.tsx
-import { configuratorBuilder } from '.phoenix/frontend.js'
-import { customAdminOptics } from './optics.js'
-import { NotAuthenticatedPage } from '../pages/NotAuthenticatedPage.js'
-
-const config = configuratorBuilder
-  .withComponentOptics(customConfiguratorComponents)
-  .withAdminComponentOptics(customAdminOptics) // Register admin components
-  .buildConfig({
-    deploymentId: phx.runtimeConfig.DEPLOYMENT_ID,
-    persistence: {
-      type: 'server',
-      serverUrl: phx.runtimeConfig.SERVER_URL,
-    },
-    ui: {
-      notAuthenticatedPage: <NotAuthenticatedPage />, // Show when user not authenticated
-    },
-    // ... other config
-  })
+// ... customAdminOptics as defined in the example above
 
-phx.frontend.mountApplication(config)
+export default customAdminOptics
 ```
 
-Admin component files go in `src/admin/components/` and are automatically discovered by phx-cli.
+The page shown to a user who is not authenticated is an element. Create it with
+`phx.frontend.createNotAuthenticatedPage(...)` in a file under `src/elements/`.
 
 ### Built-in Admin Integration
 
 Phoenix automatically provides admin functionality when:
 
-1. Admin components are registered via `withAdminComponentOptics()`
+1. Admin components are default-exported from files in `src/admin/components/`
 2. Admin configuration exists in `phoenix.config.ts`
 3. User has admin session token
 

package/dist/docs/phoenix/deployments.mdx

@@ -464,7 +464,7 @@ Error: Failed to upload to S3
 
 - Run `deployment:prepare` again to get fresh presigned URLs
 - Check that `.upload-links.json` exists and is readable
-- Use `--skipUpload` / `-su` flag to test without uploading assets
+- Use `--skipUpload` / `--su` flag to test without uploading assets
 
 ### "Server URL is required"
 

package/dist/docs/phoenix/expression-context.mdx

@@ -35,15 +35,23 @@ interface ExpressionContext<
 
   // System services
   readonly domain: Domain // Access to domain model and other entities
-  readonly componentReader: ComponentReader // Read component states across all entities
   readonly migrate: MigrateFunction // Data migration utilities
-  readonly sketchingProjections: SketchingProjections // Sketching system projections
-  readonly collisionProjections: CollisionProjections // Collision detection projections
+  readonly componentReader: ComponentReader // Read component states across all entities
+
+  // Projections
+  readonly positionProjections: PositionProjections // World matrices of scene entities
+  readonly sketchingProjections: SketchingProjections // Shapes and connections of a sketch
+  readonly collisionProjections: CollisionProjections // Collision meshes and collisions between entities
+  readonly constraintProjections: ConstraintProjections // Spatial constraints an entity violates
+  readonly snappingProjections: SnappingProjections // Snap points, edges, planes and matches
+  readonly projectedEntitiesProjections: ProjectedEntitiesProjections // Data of projected entities
 }
 ```
 
 The context includes data sources (session, published, frontend, backend), system services (domain access, component reader, projections), and application state (mode, role). Each part serves a different purpose in expression calculations.
 
+The SDK declares the context in two parts. `CoreExpressionContext` holds the mode, the role, the data sources, `domain` and `migrate`. `RuntimeExpressionContext` holds the component reader and the projections. An editor hover or a type error therefore shows `ctx` as `OpenExpressionContext<..., RuntimeExpressionContext<AnyDomainEntity>>`, which has the members listed above. A helper of your own that takes the context declares its parameter as `ExpressionContext` with the five types of your project.
+
 ### Configurator Modes
 
 The `mode` property indicates the current operational context of the configurator. Different modes enable different functionality and access levels. Expressions can check the mode to change their behavior.

package/dist/docs/phoenix/localization.mdx

@@ -116,28 +116,9 @@ After running `pnpm lingui:compile`, your custom translations will override the
 - Adapt translations for your target audience
 - Maintain consistency with your existing product language
 
-**Frontend integration**:
-
-```typescript
-import { configuratorBuilder } from 'project-domain'
-import { createI18n } from 'project-i18n'
-
-const i18n = createI18n()
-
-export const config = configuratorBuilder
-  .withComponentOptics(customComponents)
-  .withPresets(presets)
-  .withI18n(i18n) // Register i18n service with configurator
-  .buildConfig({
-    features: {
-      availableLocales: ['en', 'de', 'cs'],
-    },
-    services: {
-      logger,
-    },
-    // ... other configuration
-  })
-```
+**Frontend integration**: the generated `.phoenix` code creates the i18n service from `.phoenix/i18n.ts` and registers
+it with the application, so there is nothing to wire by hand. The languages come from `availableLocales` in
+`spec/application.yaml`.
 
 ## Working with YAML Domain Specifications
 

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

@@ -257,11 +257,14 @@ The frontend reads these at runtime from the generated config:
 | Variable                         | Required | Default                 |
 | -------------------------------- | -------- | ----------------------- |
 | `IS_DEV`                         | No       | `false` (`true` in dev) |
+| `ASSISTANT_STRICT_THREADS`       | No       | `false`                 |
 | `AWS_S3_PUBLIC_RESOURCES_BUCKET` | Yes      | —                       |
 | `AWS_S3_RESOURCES_REGION`        | Yes      | —                       |
 | `DEPLOYMENT_RESOURCES_PATH`      | No       | `deployment-resources`  |
 | Clerk vars (if enabled)          | Yes      | —                       |
 
+A development environment keeps the AI assistant's conversation when the assistant setup (manifest, instructions, AI settings) changes, and applies the new setup from the next message on. Set `ASSISTANT_STRICT_THREADS=true` in `.env` to try the behavior of every other environment locally, where a changed setup locks the conversation and the next message continues it in a summarized one. The variable has no effect outside a development environment.
+
 ### Precedence
 
 Environment variables are resolved in this order (highest to lowest priority):
@@ -283,20 +286,20 @@ The Phoenix CLI auto-generates config files that read these variables:
 
 Starts the full development environment: Vite dev server, development webhook tunnel, domain-cli watcher, and editor WebSocket server.
 
-| Flag                   | Env Variable       | Default              | Description                                                                     |
-| ---------------------- | ------------------ | -------------------- | ------------------------------------------------------------------------------- |
-| `--workspace`          | —                  | from `.phoenix.json` | Override workspace mode                                                         |
-| `--editor`             | `ENABLE_EDITOR`    | `true`               | Enable editor file generation                                                   |
-| `--editorWsPort`       | `EDITOR_WS_PORT`   | `3020`               | Editor WebSocket port                                                           |
-| `--debug`              | `DEBUG`            | `false`              | Verbose logging                                                                 |
-| `--projectSlug`        | `PROJECT_SLUG`     | `local`              | Project slug                                                                    |
-| `--environmentSlug`    | `ENVIRONMENT_SLUG` | package.json name    | Environment slug                                                                |
-| `--withLingui`         | `WITH_LINGUI`      | `false`              | Enable i18n extraction/compilation and watch i18n sources during dev            |
-| `--persistence`        | `PERSISTENCE_MODE` | `server`             | Persistence mode                                                                |
-| `--force` / `-f`       | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache                                                  |
-| `--serverUrl`          | `SERVER_URL`       | the region's server  | Phoenix server URL                                                              |
-| `--region`             | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
-| `--skipUpload` / `-su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
+| Flag                    | Env Variable       | Default              | Description                                                                     |
+| ----------------------- | ------------------ | -------------------- | ------------------------------------------------------------------------------- |
+| `--workspace`           | —                  | from `.phoenix.json` | Override workspace mode                                                         |
+| `--editor`              | `ENABLE_EDITOR`    | `true`               | Enable editor file generation                                                   |
+| `--editorWsPort`        | `EDITOR_WS_PORT`   | `3020`               | Editor WebSocket port                                                           |
+| `--debug`               | `DEBUG`            | `false`              | Verbose logging                                                                 |
+| `--projectSlug`         | `PROJECT_SLUG`     | `local`              | Project slug                                                                    |
+| `--environmentSlug`     | `ENVIRONMENT_SLUG` | package.json name    | Environment slug                                                                |
+| `--withLingui`          | `WITH_LINGUI`      | `false`              | Enable i18n extraction/compilation and watch i18n sources during dev            |
+| `--persistence`         | `PERSISTENCE_MODE` | `server`             | Persistence mode                                                                |
+| `--force` / `-f`        | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache                                                  |
+| `--serverUrl`           | `SERVER_URL`       | the region's server  | Phoenix server URL                                                              |
+| `--region`              | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
+| `--skipUpload` / `--su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
 
 In `server` persistence mode the project comes from `--projectSlug`, `PROJECT_SLUG` or `project` in the spec, and the credential from `DEVELOPMENT_KEY` or the `phoenix login` sign-in; see [Starting a New Project](#starting-a-new-project). When signed in, the environment is always your own development environment and `--environmentSlug` is ignored.
 
@@ -682,7 +685,7 @@ SDK-builder workspaces sign the CLI in with a personal API token instead of proj
 
 Signs the CLI in to the SDK-builder workspace `<customer>`:
 
-1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). The page shows the workspace, your account, the computer the CLI runs on and how long the link still works. The CLI suggests the name `phoenix CLI on <computer>`; change it so you can tell your machines and agents apart later.
+1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). Only a super admin of the workspace can open its Studio, so only a super admin can sign the CLI in. The page shows the workspace, your account, the computer the CLI runs on and how long the link still works. The CLI suggests the name `phoenix CLI on <computer>`; change it so you can tell your machines and agents apart later.
 2. Studio sends a one-time code back to the CLI on `127.0.0.1`.
 3. The CLI exchanges the code for a token with the name you approved, and sends the browser back to Studio, which confirms the sign-in.
 
@@ -690,12 +693,12 @@ Signs the CLI in to the SDK-builder workspace `<customer>`:
 
 The token is stored in `~/.phoenix/credentials.json`, readable only by you, per server, together with the Studio URL of the sign-in; `PHOENIX_CREDENTIALS_FILE` moves the file. The token works until you revoke it. Signing in again to the same server revokes the token it replaces; the CLI warns if the server could not revoke it.
 
-| 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                      |
-| `--open`              | `true`                               | Open the approval page in your browser           |
+| 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                      |
+| `--open`               | `true`                               | Open the approval page in your browser           |
 
 The sign-in follows the region, not the `SERVER_URL` in a project's `.env`: that variable names the server of the project's own environment. The CLI prints the server it signs in to.
 
@@ -728,7 +731,7 @@ Pass the message as the argument for a short note, or `--file` for a longer repo
 | `--agent`              | —              | —                             | Name of the coding agent that writes the feedback         |
 | `--projectSlug` / `-p` | `PROJECT_SLUG` | `project` of the spec, if any | Workspace project the feedback is about                   |
 | `--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          |
+| `--serverUrl` / `--su` | —              | the region's server           | Phoenix server URL, for a local or custom server          |
 
 A message holds at most 100,000 characters, from the argument or from the file. Besides the message and the flags, the CLI sends only the SDK version, the operating system and the Node.js version; no file of the project is attached, and the Phoenix team reads a build's sources through the build's page in Studio. The project must belong to the signed-in workspace, otherwise the server refuses the feedback; without a project, the feedback is sent on its own.
 

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

@@ -49,6 +49,12 @@ 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. Keep plain components and helpers in a `_*` folder.
+
 ### Admin Folders (src/admin/)
 
 The `admin/` folder supports these admin-specific categories:

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

@@ -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,7 +59,7 @@ 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.
 
@@ -107,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/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};