@salsita-ai/sdk 0.50.0-develop.eb204e0da4 → 0.50.0-develop.f03b563886

package/dist/docs/layouts/toolbar.mdx

@@ -81,6 +81,12 @@ Phoenix provides built-in toolbar buttons for common operations:
   `props.showIndicatorSwitch: false` to hide the Dimension indicators switch. When omitted, the prop falls back to
   `applicationConfig.indicatorSwitch`, then `true`.
 - `helpToolbarButton` - Show help content (supports custom children)
+- `assistantToolbarButton` - Open and close the built-in assistant panel. It renders only in a project whose
+  application spec has an `assistant` section. `props.showTitle` defaults to `true`; the label shows on a
+  desktop-sized layout only. The default toolbar includes it, in a group of its own, when the spec has an
+  `assistant` section. Only the universal layout carries the panel, and the button does not hide itself in a
+  layout without it. A custom layout that renders the toolbar therefore defines a `toolbar` component without the
+  button, because the default toolbar would add it.
 
 ### Mobile Toolbar Configuration
 

package/dist/docs/other-features/domain-actions.mdx

@@ -0,0 +1,418 @@
+# Domain Actions
+
+- [Use case](#use-case)
+- [Declare the action](#declare-the-action)
+- [Implement it](#implement-it)
+- [Run it from the UI](#run-it-from-the-ui)
+- [Expose it to the assistant](#expose-it-to-the-assistant)
+- [Known gaps](#known-gaps)
+- [Example](#example)
+
+## Use case
+
+A plate carries holes, and a hole can be nudged by an offset as long as it stays on the plate. The arrow buttons of a selected hole and the AI assistant both make this change, so the rule ("stay on the plate") has to live in one place.
+
+An **action** is that place: a named domain operation you declare once under `actions:`, implement in `src/actions/` with generated parameter and result types, and run from any control through `actionSystem.prepareAction()`. The same action is exposed to the assistant as a custom mutation by naming it under `assistant.actions`. Use an action whenever a change is more than writing one field: a swap, a move among siblings, a change that touches several entities at once.
+
+## Declare the action
+
+`params` and `result` are maps of named JSON schemas, with the same `phx:` refs, `references`, `tsType` and `import` as entity shapes. A param whose schema allows `null` is optional; every other param is required. A result member typed `phx:$DomainEntity` is the enhanced entity after the change.
+
+```yaml
+actions:
+  nudgeHole:
+    description: Moves a hole by an offset on the plate; the move fails when the hole would leave the plate
+    params:
+      holeId:
+        $ref: phx:DomainEntityId
+        references: Hole
+        description: The hole to move
+      dx:
+        type: integer
+        description: Offset along the x axis, in plate units
+      dy:
+        type: integer
+        description: Offset along the y axis, in plate units
+    result:
+      hole:
+        $ref: phx:$DomainEntity
+        references: Hole
+        description: The hole at its new position
+      plate:
+        $ref: phx:$DomainEntity
+        references: Plate
+        description: The plate after the move
+```
+
+Generation derives the types `ActionTypes`, `ActionName`, `ActionParams<'nudgeHole'>` and `ActionResult<'nudgeHole'>` from it: here `ActionParams<'nudgeHole'>` is `{ holeId: Hole['id']; dx: number; dy: number }` and `ActionResult<'nudgeHole'>` is `{ hole: $Hole; plate: $Plate }`. The `description` of the action, of a param and of a result member becomes the doc comment of its generated property, so it shows in the editor wherever the action is implemented or called.
+
+## Implement it
+
+A file in `src/actions/` default-exports `phx.domain.implementActions({...})` with any subset of the declared actions. The implementation receives the validated parameters, the state the action runs on, and a context with the `expressionContext`, the domain `systems`, `getIdSequence()` for entities it creates and the typed `updates` factory. It returns the updates it wants applied and `readResult`, which reads the result from the state those updates produced, including whatever the transformers added. It never stages or commits anything.
+
+```ts
+// src/actions/nudge-hole.ts
+export default phx.domain.implementActions({
+  nudgeHole: ({ holeId, dx, dy }, state, { systems: { domain }, updates }) => {
+    // `references: Hole` types the id, but any entity id passes the runtime check, so the entity is verified here.
+    const hole = state.entities.find(entity => entity.id === holeId)
+
+    if (hole?.type !== 'Hole') {
+      throw new Error(
+        `"${holeId}" is not a hole of the plate, so it cannot be nudged. Query the plate's holes and use an id they return.`
+      )
+    }
+
+    const x = hole.x + dx
+    const y = hole.y + dy
+
+    if (Math.abs(x) > 150 || Math.abs(y) > 150) {
+      throw new Error(
+        `Nudging "${holeId}" by (${dx}, ${dy}) would put it at (${x}, ${y}), outside the plate. Keep both coordinates between -150 and 150.`
+      )
+    }
+
+    return {
+      updates: [updates.DomainEntityModification({ entityId: hole.id, stateDelta: { x, y }, updateTag: 'nudgeHole' })],
+      readResult: ({ state: nudged }) => ({
+        hole: domain.get$Entity(holeId, nudged),
+        plate: domain.getRoot$Entity(nudged),
+      }),
+    }
+  },
+})
+```
+
+Throw to reject a call: the message reaches the user through the control's hint and the assistant through the failed mutation, so say what went wrong and what to send instead. An implementation of a name the spec does not declare is a type error. A declared action without an implementation is not: it stops the domain from initializing, and under `phoenix dev` the editor reports it as a `MISSING_ACTION_IMPLEMENTATIONS` diagnostic and does not apply the change; an implementation of an undeclared name is logged.
+
+## Run it from the UI
+
+`phx.frontend.useDomain().actionSystem.prepareAction(name, args, state)` validates `args` against the declared params and returns `{ updates, readResult }`. Hand the updates to `useUpdateControl()` like any other change: it dry-runs them for hints and commits them on click.
+
+```tsx
+export default phx.frontend.createCustomPhoenixEntityElement('NudgeControl', ({ entityId }) => {
+  const { actionSystem } = phx.frontend.useDomain()
+  const state = phx.frontend.useCommittedState()
+  const prepare = phx.frontend.useUpdateControl()
+
+  const left = prepare(actionSystem.prepareAction('nudgeHole', { holeId: entityId, dx: -20, dy: 0 }, state).updates)
+
+  return (
+    <Button disabled={left.disabled} title={left.hints} onClick={left.update}>
+      ←
+    </Button>
+  )
+})
+```
+
+`prepareAction` throws for arguments that do not fit the params, for an unknown action and for whatever the implementation rejects, so a control that may ask for an impossible move catches the error and shows its message, as the example's control does.
+
+## Expose it to the assistant
+
+Naming the action under `assistant.actions` adds a `Mutation` field with one argument per param and a `<Name>Result` type whose entity members are traversable edges. `as` renames the field, `description` replaces the action's.
+
+```yaml
+assistant:
+  actions:
+    nudgeHole:
+```
+
+```graphql
+type Mutation {
+  nudgeHole(holeId: ID!, dx: Int!, dy: Int!): NudgeHoleResult!
+}
+
+type NudgeHoleResult {
+  hole: Hole!
+  plate: Plate!
+}
+```
+
+The field runs the same `prepareAction`, applies the updates through the same validation as every other mutation, and fails with the action's message when the call is rejected.
+
+## Known gaps
+
+- `references` on a `phx:DomainEntityId` param types the parameter and the GraphQL argument, but at runtime any entity id passes the params check: the implementation verifies that the id names an entity of the expected type, as the example does.
+- Actions exist in the configurator domain only; the admin domain declares none.
+- The result of `readResult` is not validated at runtime: the generated TypeScript type and the GraphQL coercion are the checks.
+- The assistant cannot dry-run a custom mutation the way it dry-runs recipes and field options.
+- `useDomain()` types `prepareAction` with the generic action map, so the name and the arguments are not checked against your `ActionTypes` at that call site; the implementation side is fully typed.
+
+## Example
+
+Select a hole and nudge it with the arrows. A move that would leave the plate is disabled with the action's message.
+
+## Complete Implementation
+
+{/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}
+
+<details>
+<summary>Click to view the complete implementation files</summary>
+
+### ./spec/domain.yaml
+
+```yaml
+model:
+  latest:
+    entityTypes:
+      - Plate
+      - Hole
+    aliases:
+      RootEntity:
+        - Plate
+    shapes:
+      Hole:
+        x:
+          type: number
+        y:
+          type: number
+
+relations:
+  Plate:
+    $holes:
+      kind: allOfType
+      target: Hole
+      cardinality: 0-N
+      composedOf: true
+  Hole:
+    $plate:
+      kind: allOfType
+      target: Plate
+      cardinality: 1-1
+      composedOf: false
+
+expressions:
+  Hole:
+    $radius:
+      type: number
+
+# A named domain operation: declared once, implemented in src/actions/, run by the NudgeControl
+# element and by the assistant alike.
+actions:
+  nudgeHole:
+    description: Moves a hole by an offset on the plate; the move fails when the hole would leave the plate
+    params:
+      holeId:
+        $ref: phx:DomainEntityId
+        references: Hole
+        description: The hole to move
+      dx:
+        type: integer
+        description: Offset along the x axis, in plate units
+      dy:
+        type: integer
+        description: Offset along the y axis, in plate units
+    result:
+      hole:
+        $ref: phx:$DomainEntity
+        references: Hole
+        description: The hole at its new position
+      plate:
+        $ref: phx:$DomainEntity
+        references: Plate
+        description: The plate after the move
+
+assistant:
+  ai:
+    provider: openai
+    model: balanced
+    reasoning: low
+  entities:
+    Plate:
+      $holes:
+        description: The holes of the plate
+    Hole:
+      x:
+      y:
+  actions:
+    nudgeHole:
+
+presets:
+  - rootEntityType: 'Plate'
+    initialDomainEntities:
+      - id: 'Plate-1'
+        type: 'Plate'
+      - id: 'Hole-1'
+        type: 'Hole'
+        x: -60
+        y: 40
+      - id: 'Hole-2'
+        type: 'Hole'
+        x: 70
+        y: -50
+
+components:
+  Plate:
+    applicationConfig:
+      main:
+        layout: 'universal'
+    staticPerspectiveCamera:
+      main:
+        distance: 400
+        priority: 1
+        polarAngle: 1.2
+        azimuthAngle: -0.2
+    sceneEntityProperties:
+      main:
+        offsetX: -100
+        offsetY: -100
+        offsetZ: -10
+    sceneEntityObject:
+      Plate:
+        object:
+          $read: $render
+    detail:
+      main:
+        title: 'Plate'
+        subtitle: 'A plate with holes'
+        description: 'Select a hole to nudge it.'
+  Hole:
+    sceneEntityProperties:
+      main:
+        offsetX:
+          $read: x
+        offsetY:
+          $read: y
+    sceneEntitySelectHotspot:
+      main:
+        offsetX: 15
+        offsetY: 15
+        offsetZ: 30
+    detail:
+      main:
+        title: 'Hole'
+        subtitle: 'A hole in the plate'
+        description: 'Nudge it with the arrows; a hole cannot leave the plate.'
+    propertyPage:
+      main:
+        children:
+          - kind: propertyContainerGroup
+            props:
+              spacing: large
+            children:
+              - kind: customElement
+                props:
+                  name: NudgeControl
+```
+
+### ./src/actions/nudge-hole.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+/** How far a hole may sit from the plate's center on either axis, in plate units. */
+const REACH = 150
+
+export default phx.domain.implementActions({
+  nudgeHole: ({ holeId, dx, dy }, state, { systems: { domain }, updates }) => {
+    // `references: Hole` types the id, but any entity id passes the runtime check, so the entity is verified here.
+    const hole = state.entities.find(entity => entity.id === holeId)
+
+    if (hole?.type !== 'Hole') {
+      throw new Error(
+        `"${holeId}" is not a hole of the plate, so it cannot be nudged. Query the plate's holes and use an id they return.`
+      )
+    }
+
+    const x = hole.x + dx
+    const y = hole.y + dy
+
+    if (Math.abs(x) > REACH || Math.abs(y) > REACH) {
+      throw new Error(
+        `Nudging "${holeId}" by (${dx}, ${dy}) would put it at (${x}, ${y}), outside the plate. Keep both coordinates between ${-REACH} and ${REACH}.`
+      )
+    }
+
+    return {
+      updates: [updates.DomainEntityModification({ entityId: hole.id, stateDelta: { x, y }, updateTag: 'nudgeHole' })],
+      readResult: ({ state: nudged }) => ({
+        hole: domain.get$Entity(holeId, nudged),
+        plate: domain.getRoot$Entity(nudged),
+      }),
+    }
+  },
+})
+```
+
+### ./src/elements/NudgeControl.tsx
+
+```tsx
+import { Button, Stack } from '@mui/material'
+
+import { PropertyContainer } from '@salsita-ai/sdk/ui'
+
+import { phx } from '../../.phoenix/phx.js'
+
+const STEP = 20
+
+/** Nudges the selected hole with the same `nudgeHole` action the assistant calls, one step at a time. */
+export default phx.frontend.createCustomPhoenixEntityElement('NudgeControl', ({ entityId }) => {
+  const { actionSystem } = phx.frontend.useDomain()
+  const state = phx.frontend.useCommittedState()
+  const prepare = phx.frontend.useUpdateControl()
+  const hole = state.entities.find(entity => entity.id === entityId)
+
+  if (hole?.type !== 'Hole') {
+    return <></>
+  }
+
+  // An action throws when the move leaves the plate; the button for that direction is then disabled with the message.
+  const nudge = (dx: number, dy: number) => {
+    try {
+      return prepare(actionSystem.prepareAction('nudgeHole', { holeId: hole.id, dx, dy }, state).updates)
+    } catch (error) {
+      return { disabled: true, hints: error instanceof Error ? error.message : String(error), update: () => {} }
+    }
+  }
+
+  const directions = [
+    { label: '←', dx: -STEP, dy: 0 },
+    { label: '→', dx: STEP, dy: 0 },
+    { label: '↑', dx: 0, dy: STEP },
+    { label: '↓', dx: 0, dy: -STEP },
+  ]
+
+  return (
+    <PropertyContainer.Item title="Nudge" description={`Moves the hole by ${STEP} units.`}>
+      <Stack direction="row" spacing={1}>
+        {directions.map(({ label, dx, dy }) => {
+          const control = nudge(dx, dy)
+
+          return (
+            <Button
+              key={label}
+              variant="outlined"
+              disabled={control.disabled}
+              title={control.hints ?? undefined}
+              onClick={event => {
+                event.stopPropagation()
+                control.update()
+              }}
+            >
+              {label}
+            </Button>
+          )
+        })}
+      </Stack>
+    </PropertyContainer.Item>
+  )
+})
+```
+
+### ./src/expressions/plate.ts
+
+```ts
+import { createPlate } from '../../../../common/plate-rendering.js'
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomExpressions({
+  Hole: {
+    $radius: () => 10,
+  },
+  Plate: {
+    $render: plate => createPlate({ features: plate.$holes }),
+  },
+})
+```
+
+</details>

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

@@ -66,42 +66,76 @@ 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
+
+In a configurator with the AI assistant, the assistant is told the same hints: they arrive as
+`sideEffects` with the result of its changes and in the dry-runs of recipes and options, so it can
+tell the user what else happened. The hints also explain what the user changed between two messages:
+every message carries a change record of the configuration, and each of its lines ends with the hint
+of the last update that touched it, or with the `updateTag` when the update has none. Set `agentHint`
+beside `hint` when the assistant needs different wording, for example with ids or values a snackbar
+would not show:
+
+```ts
+phx.frontend.updates.DomainEntityModification({
+  entityId: oldPlate.id,
+  stateDelta: { finish: validMaterial.finish },
+  updateTag: 'fix.finish',
+  hint: msg`Material finish was adjusted`,
+  agentHint: `The finish of ${oldPlate.id} was changed to ${validMaterial.finish}, the only one this material comes in.`,
+})
+```
+
+- `agentHint` is a plain string, never shown to the user and not localized.
+- `agentHint: null` keeps the wording from the assistant while the user still gets the `hint`: the
+  update is left out of `sideEffects`, and the change record explains its line by the `updateTag`. It
+  does not hide the change itself, which the assistant can always read from the configuration.
+- `agentHint` without a `hint` tells only the assistant.
+
 ## Example
 
 Here you can see the live example!

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

@@ -421,49 +421,34 @@ export const handler = webhookBuilder
 
 The publishing workflow validates admin state, transforms entities, and stores JSON to S3. Configurators access published data via `ctx.publishedData` in expressions.
 
-For implementation examples, see `packages/demos/demo-finalize/src/handlers/map-published-revision-data.ts`.
+For implementation examples, see `packages/demos/demo-catalog-builder/src/handlers/map-published-chunked-data.ts`.
 
 For technical details about data transformation and storage, see [Data Sources - Published Data](?path=/docs/phoenix-data-sources--docs#published-data).
 
 ## 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
 
@@ -515,4 +500,4 @@ Ready to implement admin functionality in your Phoenix project? Here's what to e
 - **[Sessions and Access](?path=/docs/phoenix-sessions-and-access--docs)** - Understand admin authentication and permissions
 - **[Connected Data Sources](?path=/docs/phoenix-connected-data-sources--docs)** - Wire `$data` entries to Google Sheets or Excel; requires the embedded admin mode
 
-For hands-on examples, check out the finalize demo (`packages/demos/demo-finalize/`) which shows spec-driven admin using `createAdminPages` for presets and recipes. This demo demonstrates the YAML-based admin approach with publishing workflows rather than custom admin UI components.
+For hands-on examples, check out the Catalog Builder demo (`packages/demos/demo-catalog-builder/`), which shows spec-driven admin pages over connected and generated data, custom catalog pages beside them, admin model migrations, and the publishing workflow.

package/dist/docs/phoenix/best-practices.mdx

@@ -5,6 +5,7 @@
 1. **YAML is king** - 99% of configuration should be in spec/\*.yaml files
 2. **Custom code locations** (in order of preference):
    - `src/expressions/` - Computed/derived properties
+   - `src/actions/` - Named domain operations declared under `actions:`
    - `src/invariants/` - Business rule constraints
    - `src/transformers/` - Automatic state fixers
    - `src/handlers/` - Event & lifecycle handlers

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.