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

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/error-5xx.mdx

@@ -12,7 +12,7 @@ Error page that is displayed when needed.
 
 ## Code
 
-The `ErrorPage` is provided in the default in the `LoadedConfigurationDetailPage` and `PresetSelectionProvider`.
+In production the configurator renders the layout element `ConfiguratorErrorPage` when an error reaches its error boundary or a configuration cannot be created from the only preset. Its default is a built-in page made with `ErrorPage` from `@salsita-ai/sdk/ui`; this example renders `ErrorPage` directly to show it. A project replaces the page with `phx.frontend.createConfiguratorErrorPage`, see [Configurator Interface → Configurator Error Page](?path=/docs/phoenix-configurator-interface--docs#configurator-error-page), which also lists the cases that still show another page.
 
 ## Example
 

package/dist/docs/other-features/navigation-hotspot.mdx

@@ -96,6 +96,8 @@ Key observations:
 - With `pushToStack: true` and no `canStackOnto`, the new state is always pushed on top
 - With `canStackOnto: [Legs]`, the stack is "rewound" to `Legs` before pushing - any states after `Legs` are removed
 
+The hotspot is the entity element `NavigationHotspot`. A project replaces its look by registering its own with `phx.frontend.createNavigationHotspot`, which receives `navigationState` and `onNavigate`, the navigation with the stack rules above. See [Configurator Interface → In-Scene Controls](?path=/docs/phoenix-configurator-interface--docs#in-scene-controls).
+
 ## Example
 
 This example demonstrates navigation hotspots with stack behavior. The sidebar shows breadcrumbs displaying the current navigation stack for easier understanding.

package/dist/docs/other-features/not-found-404.mdx

@@ -12,7 +12,7 @@ Error page that is displayed when the configuration is not accesible.
 
 ## Code
 
-The `NotFoundPage` is provided in the default in the `ConfiguratorRoot` and `ConfiguratorApp`.
+The configurator renders the layout element `ConfigurationNotFoundPage`, whose default is the built-in page, `ConfigurationNotFoundPage` from `@salsita-ai/sdk/react`. This example renders that component directly to show it. A project replaces the page with `phx.frontend.createConfigurationNotFoundPage`, see [Configurator Interface → Configuration Not Found Page](?path=/docs/phoenix-configurator-interface--docs#configuration-not-found-page), which also lists when the page is shown.
 
 ## Example
 

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

@@ -32,17 +32,14 @@ finishNotAvailable:
 ```
 
 ```ts
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Plate: {
-        finishNotAvailable: s => {
-          return availableMaterials.some(state => state.material === s.material && state.finish === s.finish)
-        },
-      },
-    })
-  )
-  .buildViolationExpressions()
+// src/invariants/invariants.ts
+export default phx.domain.implementCustomInvariants({
+  Plate: {
+    finishNotAvailable: s => {
+      return availableMaterials.some(state => state.material === s.material && state.finish === s.finish)
+    },
+  },
+})
 ```
 
 With following control structure. The top input selects the material, the bottom one selects the finish.
@@ -66,42 +63,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
 
@@ -433,6 +433,10 @@ The following sample application has all the above described transformers active
 - When the view changes to `Y`, the navigation state is changed to `C`.
 - When any entity is deselected in view `Z`, the view is changed to `X`.
 
+The example's own tests under `__tests__/` check these cases with `createMockDomainContext` on the config
+`createTestApplicationConfig` builds from the generated application; [Testing](?path=/docs/phoenix-testing--docs)
+shows how a project's test sets that up.
+
 ## Complete Implementation
 
 {/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}