@salsita-ai/sdk 0.50.0-develop.b47f1774a2 → 0.50.0-develop.b5d443db78

package/dist/application-spec/generate-application/code/templates/skills/features/domain-controls/scene-controls.js

@@ -0,0 +1,48 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`Shelves with the SDK's in-scene controls, placed by the spec and restyled once for the brand. The delete FAB keeps its dry run: it is disabled with the reason while removing the shelf would break an invariant.
+
+\`\`\`yaml
+# spec/scene-controls.yaml
+components:
+  Cabinet:
+    sceneEntityAddFab:
+      shelves:
+        $filter:
+          modes: [owner]
+        instanceNames: [shelves]
+        skipMenuWhenOnlyOne: true
+        hideWhenNone: true
+        title: Add a shelf
+        offsetY: 900
+  Shelf:
+    sceneEntityDeleteFab:
+      main:
+        $filter:
+          modes: [owner]
+        title: Remove shelf
+        offsetY:
+          $eval: self.height + 40
+        hideWhileDragging: true
+\`\`\`
+
+\`\`\`tsx
+// src/elements/DeleteEntityFab.tsx
+import { Fab, Tooltip } from '@mui/material'
+
+export default phx.frontend.createDeleteEntityFab(({ onDelete, disabled, disabledHint, title }) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const label = resolve(title) ?? 'Remove'
+
+  return (
+    <Tooltip title={disabledHint ?? label}>
+      {/* A disabled button fires no events, so the span carries the tooltip */}
+      <span>
+        <Fab size="small" color="primary" aria-label={label} disabled={disabled} onClick={onDelete}>
+          \xd7
+        </Fab>
+      </span>
+    </Tooltip>
+  )
+})
+\`\`\`
+
+\`onDelete\` already stops the click's propagation and records the built-in analytics event.`;export const generatePhoenixSceneControlsFeature=()=>e({path:"features/domain-controls/scene-controls.md",title:"Scene controls",summary:"Hotspots, FABs, editable dimension indicators and 3D entity controls, their placement, and replacing the built-in look; read when putting a control on the product.",whenToUse:"Read when configurator users should act on the product itself: select a part or go to a step from a hotspot, add or delete from a FAB, edit a dimension in the scene, switch tools, or open a project control next to a part. These controls write the same control components as the project's elements ([Control components](control-components.md)).",capabilities:"### Choose the control\n\n- **Select a part** — `sceneEntitySelectHotspot`. Selection itself belongs to [Selection and hover](../application-states/selection.md).\n- **Go to a navigation state** — `sceneEntityNavigationHotspot` with `navigationState` (required), `pushToStack` and `canStackOnto`; [Navigation states](../application-states/navigation.md) owns the stack.\n- **Add children** — `sceneEntityAddFab` offers the entity's `childEntityRecipes`: `instanceNames` narrows them, `skipMenuWhenOnlyOne` adds a single recipe directly, `hideWhenNone` hides an empty FAB, `label` and `icon` style it, and `hiddenViolations` drops those types from its hints.\n- **Delete the entity** — `sceneEntityDeleteFab` with `icon`, `title` and `label`, and `hiddenViolations` to drop those types from its hints.\n- **Switch tools** — `toolMenuFab` with `title` and `options` of `{ label, icon?, toolState }`; [View and tool states](../application-states/views-and-tools.md) owns tools.\n- **Edit a dimension on the product** — the editable indicators open an input for the component they target. `editableDistanceDimensionIndicator` (`targetDimension`, a `distanceDimension` instance), `listSelectorDimensionIndicator` (`targetDistanceDimensionSelect`) and `editableSizeIndicator` (`targetSize`) draw a dimension line from `startX/Y/Z` to `endX/Y/Z`. `editableAngleIndicator` targets an `angleDimension` and is placed by `positionX/Y/Z`, `startAngle` and `sweepAngle`.\n- `editableOffsetIndicator` has no start and end: it requires `targetOffset`, `targetEntityOffsetAnchors`, `targetReferenceOffsetAnchors` and `directionVector`. `dimensionIndicator`, `angleIndicator` and `offsetIndicator` only show the value.\n- **A project control on the product** — `htmlHotspot` with `name`, a project element ([Custom controls](custom-controls.md)), or `sceneEntityObjectHtmlHotspot` with `target`, a `sceneEntityRemoteObject` instance whose animation it follows, offsets in that object's local space and units.\n- **3D content on an entity** — `sceneEntityControl` with `name`: the element renders inside the WebGL scene, so it returns React Three Fiber objects, such as drei's `Billboard` and `Text`, not DOM. It stays out of camera fitting unless `includeInCameraFit: true`.\n\nPrefer the built-in control for its job and restyle it (below); an `htmlHotspot` is for a control the SDK has none of.\n\n### Place and show\n\n- `offsetX`, `offsetY` and `offsetZ` are measured from the entity's origin in the distance data unit; `screenOffsetHorizontal` and `screenOffsetVertical` shift the control in pixels. `$read` or `$eval` an offset that follows a size.\n- `showWhen` takes `selected` and `unselected`. Defaults: `[selected]` for the add and delete FABs, `[unselected]` for the selection and navigation hotspots and the tool menu; an `htmlHotspot` shows in both.\n- `hideWhileDragging` hides the control while an entity is dragged. `azimuthAngleLimits` and `polarAngleLimits` (radians) and `distanceLimits` fade it outside `{ min, max, smoothZone?, minOpacity? }`.\n- Give an icon-only FAB or hotspot a `title`; `tooltipVisibility` is `on-hover` (default), `forced`, `forced-when-still` or `hidden`.\n- `$filter` decides when the control exists: `modes: [owner]` keeps editing controls from viewers, `navigationStates` ties them to a step. [Components](../domain-model/components.md) owns filters.\n- `controlHotspot: true` on an `htmlHotspot` hides it while a change is previewed, so its dry runs never read a stale state; the add and delete FABs always behave so. It also unmounts an open popover on every change: leave it off for a hotspot whose menu stays open while users compare options. `inert: true` makes an `htmlHotspot` ignore the pointer.\n\n### Elements in the scene\n\n- In-scene elements get the theme and every `phx.frontend` hook; MUI popovers and tooltips work inside them.\n- Stop a click inside a project control from reaching the scene with `event.stopPropagation()`, or it also changes the selection. The `onDelete`, `onSelect` and `onNavigate` props below already do; a recipe's `handleClick` does not.\n- The scene's HTML sits under the layout's panels, so a covered control cannot be clicked.\n\n### Replace a built-in control's look\n\nEach helper registers the element the scene renders for one component, everywhere the spec places it, in the built-in layout and in a project layout. The spec keeps the position, visibility, filters and tooltip settings. Pass a component `(props) => JSX.Element | null` (`null` shows nothing) and default-export the registration, or an array of registrations, from a file in `src/elements/`:\n\n- `phx.frontend.createAddEntityFab(Component)` — replaces `AddEntityFab`, for `sceneEntityAddFab`. Props: `entityId`, `instanceNames`, `fixableViolations` (the spec's `hiddenViolations`), `icon`, `label`, `title`, `tooltipVisibility`, `skipMenuWhenOnlyOne`, `hideWhenNone`. It gets no recipes: read them with `phx.frontend.useGroupedRecipeOptions(entityId, instanceNames, fixableViolations)` in the menu, mounted only while open, since every recipe is a dry run.\n- `phx.frontend.createDeleteEntityFab(Component)` — replaces `DeleteEntityFab`. Props: `entityId`, `onDelete`, `disabled`, `disabledHint`, `trace` (logs the dry run), `icon`, `label`, `title`, `tooltipVisibility`.\n- `phx.frontend.createSelectionHotspot(Component)` — replaces `SelectionHotspot`. Props: `entityId`, `onSelect`, `title`, `tooltipVisibility`.\n- `phx.frontend.createNavigationHotspot(Component)` — replaces `NavigationHotspot`. Props: `entityId`, `navigationState`, `onNavigate`, `title`, `tooltipVisibility`.\n- `phx.frontend.createToolMenuFab(Component)` — replaces `ToolMenuFab`. Props: `entityId`, `options`, `onSelectTool(toolState)`, `icon`, `title`, `tooltipVisibility`.\n\n`title` and `label` are localizable: resolve them with `phx.frontend.useResolveLocalizable()`. Registering these names with `createCustomPhoenixEntityElement` works too, but types only `entityId`. The dimension indicators have no replacement; build a different editor as an `htmlHotspot`.",example:t,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- "In-Scene Controls" in `docs/phoenix/configurator-interface.mdx` — the replaceable elements, their props and a complete replacement.\n- `docs/fabs/basic.mdx`, `docs/fabs/layout.mdx` — FAB settings, visibility and tooltips, and grouping controls with screen offsets.\n- `docs/controls/scene/html-hotspots.mdx`, `docs/controls/scene/object-html-hotspots.mdx`, `docs/controls/scene/custom-controls.mdx` (`sceneEntityControl`).\n- "Put a control on the product" in `docs/layouts/custom-layout.mdx` — a project hotspot with a popover.\n- `docs/dimensions/3d-scene-integration/editable-distance-dimension-indicator.mdx` and its siblings in that folder, one per indicator (`pnpm phoenix docs -l` lists them).',phxMembers:["frontend.createAddEntityFab","frontend.createDeleteEntityFab","frontend.createSelectionHotspot","frontend.createNavigationHotspot","frontend.createToolMenuFab"]});

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/actions.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Named domain operations: declaration, implementation and running them from the UI or the assistant. */
+export declare const generatePhoenixActionsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/actions.js

@@ -0,0 +1,64 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`Moving a drawer among the desk's drawers is a reorder of the desk's \`drawerIds\` that the arrow buttons and the assistant share:
+
+\`\`\`yaml
+# spec/actions.yaml
+actions:
+  moveDrawer:
+    description: Moves a drawer among the desk's drawers by a number of positions
+    params:
+      drawerId:
+        $ref: phx:DomainEntityId
+        references: Drawer
+        description: The drawer to move
+      delta:
+        type: integer
+        description: Positions to move by; negative moves left
+    result:
+      desk:
+        $ref: phx:$DomainEntity
+        references: Desk
+        description: The desk with its drawers in the new order
+\`\`\`
+
+\`\`\`ts
+// src/actions/move-drawer.ts
+export default phx.domain.implementActions({
+  moveDrawer: ({ drawerId, delta }, state, { systems: { domain }, updates }) => {
+    const desk = domain.getRoot$Entity(state)
+    const from = desk.drawerIds.indexOf(drawerId)
+    const to = from + delta
+
+    if (from === -1 || to < 0 || to >= desk.drawerIds.length) {
+      throw new Error(
+        \`Cannot move "\${drawerId}" by \${delta}. Pass the id of one of the desk's drawers and a delta that keeps it among them.\`
+      )
+    }
+
+    const drawerIds = [...desk.drawerIds]
+    drawerIds.splice(to, 0, ...drawerIds.splice(from, 1))
+
+    return {
+      updates: [
+        updates.DomainEntityModification({ entityId: desk.id, stateDelta: { drawerIds }, updateTag: 'moveDrawer' }),
+      ],
+      readResult: ({ state: moved }) => ({ desk: domain.getRoot$Entity(moved) }),
+    }
+  },
+})
+\`\`\`
+
+\`\`\`tsx
+// in the drawer's custom element: one prepared move per button
+const { actionSystem } = phx.frontend.useDomain()
+const state = phx.frontend.useCommittedState()
+const prepare = phx.frontend.useUpdateControl()
+
+const move = (delta: number) => {
+  try {
+    return prepare(actionSystem.prepareAction('moveDrawer', { drawerId: entityId, delta }, state).updates)
+  } catch (error) {
+    return { disabled: true, hints: error instanceof Error ? error.message : String(error), update: () => {} }
+  }
+}
+const left = move(-1) // <Button disabled={left.disabled} title={left.hints} onClick={left.update}>
+\`\`\``;export const generatePhoenixActionsFeature=()=>e({path:"features/domain-model/actions.md",title:"Actions",summary:"Named domain operations declared in YAML, prepared in `src/actions/` and run by controls or the assistant; read when one change touches several entities or the UI and the assistant must share it.",whenToUse:"Read when a change is more than writing one field — a move among siblings, a swap, a change to several entities at once — or when the UI and the assistant must make the same change under the same rule. A single bound field needs no action: bind it in YAML ([Components](components.md)).",capabilities:"### Declare\n\n- Declare actions under the top-level `actions:`, each with a `description`, `params` and `result`. Both maps are required; write `params: {}` for an action without parameters. Names are identifiers.\n- Each param and result member is a JSON schema with the shape syntax: `$ref: phx:...`, `references`, `tsType` and `import`. A param whose schema admits `null` is optional; the others are required.\n- `phx:DomainEntityId` with `references` types an id param; `phx:$DomainEntity` with `references` types a result member as the `$` entity after the change.\n- The descriptions become the doc comments of the generated `ActionParams<'name'>` and `ActionResult<'name'>` types and what the assistant reads about the action, so write them for both readers.\n- Only the configurator domain has actions; the admin domain has none.\n\n### Implement\n\n- Default-export `phx.domain.implementActions({ name: (params, state, ctx) => ... })` from a file in `src/actions/`. A file may implement any subset of the declared actions.\n- `params` arrive validated against the declared schema; `state` is the state the action runs on.\n- `ctx.systems` holds the domain systems (`systems.domain.get$Entity(id, state)`, `systems.domain.getRoot$Entity(state)`); `ctx.updates` is the typed update factory, `ctx.getIdSequence()` gives ids for created entities, and `ctx.expressionContext` is the expression context.\n- Return `{ updates, readResult }`: the updates to apply, and `readResult({ previousState, state })`, which reads the declared result from the state those updates produced, transformer changes included.\n- An action only prepares. It never stages or commits; its caller does.\n- Throw to reject a call, with a message that says what was wrong and what to send instead: users see it as the control's hint and the assistant as the failed mutation's error.\n- `references` types an id but any entity id passes validation, so check what the id names, for example with `phx.domain.model.Drawer.isId(id)` or by finding it in the parent's list.\n- A declared action without an implementation stops the application at start (`MISSING_ACTION_IMPLEMENTATIONS` in the dev editor); implementing an undeclared name is a type error. Nothing validates what `readResult` returns at runtime.\n- Actions are domain code that also runs on the server: pure, `phx.domain` only, no browser imports.\n\n### Run from the UI\n\n- `phx.frontend.useDomain().actionSystem.prepareAction(name, args, state)` returns the prepared action for the committed state from `phx.frontend.useCommittedState()`.\n- Pass its `updates` to a function from `phx.frontend.useUpdateControl()`: it dry-runs them for `disabled` and `hints` and commits them on `update()`. [Custom controls](../domain-controls/custom-controls.md) owns that hook and the control around it.\n- `prepareAction` throws for an unknown name, arguments that do not fit and every rejection; catch it and show the message as the disabled control's hint.\n- At the call site the name and arguments are not checked against the generated types; the implementation is.\n\n### Expose to the assistant\n\n- List the action under `assistant.actions` to add it as a custom mutation; `as` renames the field and `description` replaces the action's. The mutation runs the same `prepareAction` and applies its updates with the same validation as every other change.",example:t,documentation:"Read `docs/other-features/domain-actions.mdx` with `pnpm phoenix docs -r docs/other-features/domain-actions.mdx`: declaring, implementing and running an action, with a complete control and the assistant schema. `docs/phoenix/domain-model.mdx` has no actions section.",phxMembers:["domain.implementActions"]});

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/components.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Attaching components in YAML or TypeScript, bindings, filters and the component hooks. */
+export declare const generatePhoenixComponentsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/components.js

@@ -0,0 +1,62 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A bound control shown only while designing and only to owners, a label that follows the selection, and legs whose number depends on the width:
+
+\`\`\`yaml
+# spec/components.yaml
+components:
+  Desk:
+    attributeSelection:
+      finish:
+        value:
+          $bind: finish
+        options:
+          $read: $finishOptions # an expression implemented in src/expressions/
+        $filter:
+          navigationStates: [design]
+          modes: [owner]
+  Drawer:
+    detail:
+      main:
+        title: Drawer
+        subtitle:
+          $eval: "self.handle + ' handle'"
+        description: ''
+        $filter:
+          selectedEntityIds:
+            $read: id
+\`\`\`
+
+\`\`\`ts
+// src/components/desk-legs.ts
+import { memoEval, sceneEntityRemoteObjectComponent } from '@salsita-ai/sdk/domain'
+
+// One leg per started 800 mm plus one; a sceneEntityObjectProperties attachment
+// with the same instance name and keys places each leg.
+export default phx.domain.attachComponent
+  .withEntity('Desk')
+  .withComponent(sceneEntityRemoteObjectComponent, 'leg')
+  .attachMany(
+    memoEval(
+      self => [Math.ceil(self.width / 800) + 1],
+      count =>
+        Array.from({ length: count }, (_, index) => ({
+          key: \`leg-\${index}\`,
+          fileUrl: '/models/desk.glb',
+          objectName: 'Leg',
+        }))
+    )
+  )
+\`\`\`
+
+\`\`\`tsx
+// in a custom element; attributeSelectionComponent comes from '@salsita-ai/sdk/domain'
+const deskId = phx.frontend.useRootEntityId()
+const finish = phx.frontend.useComponent({
+  entityId: deskId,
+  componentType: attributeSelectionComponent,
+  instanceName: 'finish',
+})
+
+if (finish === null) {
+  return null // filtered out: not designing, or a viewer
+}
+\`\`\``;export const generatePhoenixComponentsFeature=()=>e({path:"features/domain-model/components.md",title:"Components",summary:"Attaching components in YAML or TypeScript, bindings, `$eval`, filters and reading components in React; read when binding data or behavior to entities or reading a component in custom UI.",whenToUse:"Read when attaching a component to an entity or alias, binding its props to the domain, limiting it to some states, or reading one in custom React code. The guide of each job names the kind that does it: [Domain controls](../domain-controls/index.md) for controls, [Custom project layout](../custom-layout/index.md) for page-level UI.",capabilities:"### Attach in YAML first\n\n- Nest `components:` by entity type or alias, component kind, instance name, then props. On an alias the instance applies to every member type.\n- Instance names are yours. One entity can carry several instances of a kind; name each by its job (`finish`, `width`).\n- A prop holds a static value or a binding:\n  - `$read: field` or `$read: $name` — one field, expression, relation or constant of the entity, by name only (no path).\n  - `$bind: field` — reads and writes one shape field, on the props a kind lets users change, such as a selection's `value`.\n  - `$read` or `$eval` together with `$write: field` — read one thing, write a shape field. `$write` never stands alone and never targets an expression.\n  - `$eval: <expression>` — one inline JavaScript expression of `self`, the `$` entity with its relations and expressions (`self.$desk.width / 2`). It sees nothing else: no state, no context, no imports and no TypeScript-only syntax.\n- Whole state from one expression: give the instance `$read: $name` instead of props, with an optional `$filter` beside it.\n- Reading an undeclared `$name` declares an expression that still needs an implementation; see [Expressions](expressions.md).\n- The build checks that a bound value fits its prop (`COMPONENT_BINDING_TYPE_MISMATCH`). An entity id cannot be written in YAML: bind it (`$read: id`).\n\n### Filters\n\n- A `$filter` inside an instance decides when the component is active. An inactive component is absent for every system and hook.\n- Criteria: `navigationStates`, `viewStates`, `toolStates`, `exportStates`, `modes` (`owner`, `read`, `finalize`), `roles`, `selectedEntityIds`, `hoveredEntityIds`, `draggedEntityIds`, `exportedEntityIds`, `viewports`, `fullscreen`, `debug` and `active`.\n- Each criterion is static or a `$read` or `$eval`. An omitted criterion matches everything, an empty list nothing. All stated criteria must match; `$or: [...]` lists alternative filters, any of which may match.\n- `selectedEntityIds: { $read: id }` shows an instance only while its own entity is selected.\n- Criteria run cheapest first and `active` last, so put a computed condition in `active: { $read: $name }` beside the static ones. Never write `$filter: { $read: $name }`: that whole-filter form is the deprecated legacy filter and warns at runtime.\n- `modes` tests the configurator mode; a viewer is in `read` mode, so `modes: [owner]` keeps an editing component from viewers.\n- [Application states](../application-states/index.md) explains the navigation, view and tool states and the selection the criteria test.\n\n### Attach in TypeScript\n\n- Use `phx.domain.attachComponent` in `src/components/` only for what YAML cannot express: a React node or other browser value, or a number of instances that depends on the state. A file default-exports one attachment or an array.\n- Chain `.withEntity('Desk')` or `.withAlias('Top')` (repeatable), `.withComponent(<kind>Component, 'instance')`, optionally `.withGradualFilter({ ... })` (each call is one alternative), then `.attach(read, write?)` or `.attachMany(read)`.\n- `read(self, state, ctx)` returns the state; `write(writableState)` returns the entity fields to change; `attachMany` returns an array of states, each with a stable `key`, one instance per key.\n- Component types are `<kind>Component` exports of `@salsita-ai/sdk/domain`, such as `attributeSelectionComponent`; `phx` does not carry them.\n- Wrap `read` in `memoEval` (from `@salsita-ai/sdk/domain`) so the state keeps its reference while its inputs are unchanged. A fresh object on every state re-renders controls and can reset systems that react to references, such as cameras.\n- Files in `src/components/` stay out of the webhook unless their first statement is `'use webhook'`; [Webhooks](../webhooks.md) says when a component needs it.\n\n### Read components in React\n\n- `phx.frontend.useComponent({ entityId, componentType, instanceName })` returns the component's state, or `null` while it is not attached or filtered out. Leave out `instanceName` only when the kind is attached once; several matches throw.\n- `phx.frontend.useComponents({ componentTypes, entityIds?, instanceNames? })` returns `{ componentInstance, state }` snapshots, empty when nothing matches although its type admits `null`.\n- `phx.frontend.useFirstComponent({ ... })` takes the same filter and returns the first snapshot or `null`.\n- `phx.frontend.useRootComponents(componentType)` and `phx.frontend.useFirstRootComponent(componentType)` read the root entity; both also take an array of types.\n- These read the committed state. The rendered variants follow staged changes too, such as a slider being dragged: `phx.frontend.useRenderedComponent`, `phx.frontend.useRenderedComponents`, `phx.frontend.useFirstRenderedComponent`, `phx.frontend.useRootRenderedComponents` and `phx.frontend.useFirstRootRenderedComponent`. [State slices](../state/slices.md) explains when each fits.\n- Control hooks throw for a component that is not attached: check it with `phx.frontend.useComponent` first and render nothing on `null`.",example:t,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/components.mdx` — bindings, `$eval`, filters and `memoEval`.\n- `docs/other-features/component-filters.mdx` — every criterion combination, `$or` included.\n- `docs/other-features/dynamic-component-attachments.mdx` — `attachMany` from memoized expressions, beside static YAML components.\n- `docs/phoenix/configurator-interface.mdx` — "Components" under "Core Hooks": the component hooks with a sample call each.',phxMembers:["domain.attachComponent","frontend.useComponent","frontend.useRenderedComponent","frontend.useComponents","frontend.useRenderedComponents","frontend.useFirstComponent","frontend.useFirstRenderedComponent","frontend.useRootComponents","frontend.useRootRenderedComponents","frontend.useFirstRootComponent","frontend.useFirstRootRenderedComponent"]});

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/domain-model.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The domain model index followed by its guides. */
+export declare const generatePhoenixDomainModelGuides: () => readonly PhoenixGuide[];

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/domain-model.js

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as e}from"../../guide.js";import{generatePhoenixActionsFeature as s}from"./actions.js";import{generatePhoenixComponentsFeature as t}from"./components.js";import{generatePhoenixEntitiesAndRelationsFeature as n}from"./entities-and-relations.js";import{generatePhoenixExpressionsFeature as r}from"./expressions.js";import{generatePhoenixTransformersFeature as i}from"./transformers.js";import{generatePhoenixValidationAndRepairFeature as a}from"./validation-and-repair.js";export const generatePhoenixDomainModelGuides=()=>{let o=[n(),t(),r(),a(),i(),s()];return[e({path:"features/domain-model/index.md",title:"Domain model",summary:"Entities, relations, components, expressions, invariants, transformers and actions; read when modeling the product or changing its rules.",intro:"The domain model is the product's saved state and its rules: YAML in `spec/` declares it, and `src/expressions/`, `src/invariants/`, `src/transformers/`, `src/actions/` and `src/components/` implement what YAML cannot. Entities and relations give it its shape; components attach data and behavior to it; expressions derive values from it; invariants reject an invalid change; transformers add the updates a change carries with it, such as a repair; actions are named operations over several entities. Read only the guide the task needs.",guides:o,notes:[]}),...o]};

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/entities-and-relations.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Entities, aliases, relations, recipes and the model reflections. */
+export declare const generatePhoenixEntitiesAndRelationsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/entities-and-relations.js

@@ -0,0 +1,59 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A desk with one plain attribute, a top slot two types can fill, and an ordered list of drawers:
+
+\`\`\`yaml
+# spec/model.yaml
+model:
+  latest:
+    entityTypes: [Desk, RectTop, RoundTop, Drawer]
+    aliases:
+      RootEntity: [Desk]
+      Top: [RectTop, RoundTop]
+    shapes:
+      Desk:
+        finish: # one value per desk: an attribute
+          type: string
+        topId:
+          $ref: phx:DomainEntityId
+          references: Top
+        drawerIds:
+          type: array
+          items:
+            $ref: phx:DomainEntityId
+            references: Drawer
+      RectTop:
+        width: { type: number }
+      RoundTop:
+        diameter: { type: number }
+      Drawer:
+        handle: { type: string }
+relations:
+  Desk:
+    $top: { kind: direct, field: topId, target: Top, cardinality: 1-1, composedOf: true }
+    $drawers: { kind: direct, field: drawerIds, target: Drawer, cardinality: 0-N, composedOf: true }
+  Top:
+    $desk: { kind: indirect, field: topId, target: Desk, cardinality: 1-1, composedOf: false }
+  Drawer:
+    $desk: { kind: indirect, field: drawerIds, target: Desk, cardinality: 1-1, composedOf: false }
+components:
+  Desk:
+    childEntityRecipes:
+      drawers:
+        collection: Desk.$drawers
+        recipes:
+          $read: $drawerRecipes # declared by this read, implemented below
+\`\`\`
+
+\`\`\`ts
+// src/expressions/desk.ts
+export default phx.domain.implementCustomExpressions({
+  Desk: {
+    // A round top takes no drawers; the guard narrows the alias to one member type.
+    $drawerRecipes: self =>
+      phx.domain.enhancedModel.$RoundTop.is(self.$top)
+        ? []
+        : [{ title: 'Drawer', recipes: [phx.domain.createRecipe({ type: 'Drawer', handle: 'bar' })] }],
+  },
+})
+\`\`\`
+
+Deleting a drawer removes its id from \`drawerIds\`, and replacing the top writes the new id into \`topId\`, with no project code. The finish all drawers share stays \`Desk.finish\` rather than a field on each drawer.`;export const generatePhoenixEntitiesAndRelationsFeature=()=>e({path:"features/domain-model/entities-and-relations.md",title:"Entities and relations",summary:"Attribute or entity, aliases, relation kinds and ownership, recipes and the model reflections; read when shaping or changing the domain model.",whenToUse:"Read when deciding the shape of the domain model: which choices stay attributes, which become entities, how they relate and own each other, and how code tells entity types apart. Decide before the first deploy: splitting or merging entities later is a model migration.",capabilities:"### Attribute or entity\n\n- Keep a choice as an attribute of the entity it describes when the product has exactly one value of it and it needs no scene object, selection or page of its own: a finish, a width, a fabric.\n- Split it into an entity when users add, remove or repeat it, when several types with different attributes can fill the same place, or when users select it, see it as its own object or edit it on its own.\n- The split drives what follows: the composition tree is the scene hierarchy and the selection ancestry, deleting an owner deletes what it owns, and the child-entity controls (add, replace, list, delete) work on relations.\n- Start with one root entity and split only what the product needs. After a deploy, adding, removing or splitting entity types or shapes is a model change: follow [Model migration](../../processes/model-migration.md).\n\n### Aliases\n\n- An alias in `model.latest.aliases` is a named union of entity types. `RootEntity` lists the types a configuration can be rooted at.\n- Target an alias for a slot several types can fill (a `Top` that is a `RectTop` or a `RoundTop`), and declare shapes, expressions, invariants, relations and components once on it for all its members.\n\n### Relations\n\n- Declare relations under `relations:`, keyed by entity type or alias and named `$camelCase`. Each states `kind`, `target`, `cardinality` (`0-1`, `1-1`, `0-N`, `1-N`) and `composedOf`; `direct` and `indirect` also state `field`. None has a default.\n- **direct** — the declaring entity stores the ids in `field`: one id for `1-1`, an id or `null` for `0-1`, an ordered array for `0-N` and `1-N`. Use it for slots and ordered lists.\n- **indirect** — the target stores a pointer back in `field`. Use it when membership lives on the child, such as a `parentId`.\n- **allOfType** — every entity of the target type or alias, nothing stored. Use it for a link back to the root or a dynamic group.\n- A `field` is a `phx:DomainEntityId` with `references` (alone, or null, or in an array) that references exactly the related types.\n- Declare both sides. The counterpart on the target points back with the opposite kind (`direct` and `indirect`, or `allOfType` on both) and the same `field`; a missing side fails parsing with `RELATION_MISSING_COUNTERPART`.\n- Mark the owning side `composedOf: true`, at most one side of a pair. Every entity type must be reachable from the root through owning relations (`RELATION_ENTITY_NOT_IN_COMPOSITION_TREE`), and each entity has one owner, without cycles.\n- A cross-reference (`composedOf: false` on both sides) links entities already in the tree; it neither cascades nor nests in the scene.\n- Built-in transformers keep relations consistent: deleting an owner deletes what it owns, deleting a referenced entity removes its id from `direct` fields, and creating or replacing an entity writes the ids. Write no transformer for these.\n- Read relations as `$` fields in code: `desk.$top`, `desk.$drawers` (an array), `drawer.$desk`.\n\n### Create and remove children\n\n- Create children from recipes: `phx.domain.createRecipe({ type: 'Drawer', ... })` returns a whole entity of that type with a placeholder id, and the configurator gives it a real id when it adds it. State every shape property; spec `defaults:` are deprecated.\n- Return recipe groups from an expression and let a recipe control add or replace with them; remove a child with a deletion. [Control components](../domain-controls/control-components.md) owns the add, replace and remove controls.\n- For an `indirect` collection, set the child's pointer field in the recipe.\n\n### Model reflections\n\n- `phx.domain.model` has a reflection per entity type, alias and common type. Entity and alias reflections have `is(entity)`, `isId(id)`, `assert` and `assertId`; an alias also lists its `types`. A string-only enum common type has `values()` and one constant per value (`phx.domain.model.Finish.oak`); other common types validate with `is(value)`.\n- `phx.domain.enhancedModel` has `$<Type>` and `$<Alias>` for `$` entities: `is` and `isId` narrow them, and constants that do not read `self` are members (`phx.domain.enhancedModel.$Desk.$maxWidth`).\n- Hooks that take a reflection take the enhanced one, such as `phx.frontend.useSelectedEntity(phx.domain.enhancedModel.$Drawer)`; a `phx.domain.model` reflection has no `expressions` and does not type-check there. [Selection and hover](../application-states/selection.md) owns the selection hooks.\n- Call guards on the reflection object; a destructured assertion loses its narrowing (TS2775). Narrow ids that arrive untyped, such as action parameters, with `isId`.\n\n### Composition in React\n\n- `phx.frontend.useComposition()` returns the composition tree of the rendered state as `{ root, map }`. Each node has `id`, `parent`, and `children()`, `descendants()` and `ancestors()` iterators; `map` finds a node by id. Use it for outlines and breadcrumbs, and the state hooks for entity data.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/domain-model.mdx` — the Relations and Aliases sections, enums and the `phx.domain` reflections.\n- `docs/relations/aliases.mdx`, `docs/relations/hierarchy.mdx`, `docs/relations/collection-direct.mdx`, `docs/relations/collection-indirect.mdx`, `docs/relations/all-of-type.mdx`, `docs/relations/cross-reference.mdx` — one worked relation pattern each.\n- `docs/recipes-and-delete/simple.mdx`, `docs/recipes-and-delete/delete-entity.mdx` — recipes and deletion end to end.",phxMembers:["domain.model","domain.enhancedModel","domain.createRecipe","frontend.useComposition"]});

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/expressions.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Derived values in YAML and TypeScript, memoEval, the expression context and the data hooks. */
+export declare const generatePhoenixExpressionsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/expressions.js

@@ -0,0 +1,46 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`An inline value and a memoized object. The spec declares \`Cabinet.width\` (number) and \`Cabinet.finish\` (string), \`finishes\` (string array) in \`publishedData\` and \`currency\` (string) in \`frontendData\`, each in its schema's \`required\` list, or the implementation does not type-check; and \`customerGroup\` (string) in \`sessionData\`, optional like every session data property.
+
+\`\`\`yaml
+# spec/cabinet.yaml
+expressions:
+  Cabinet:
+    $halfWidth: # reads only self: no TypeScript
+      type: number
+      $eval: self.width / 2
+    $delivery: # reads the data sources: implemented in src/expressions/cabinet.ts
+      type: object
+      properties:
+        available: { type: boolean }
+        currency: { type: string }
+        customerGroup: { type: [string, 'null'] } # session data may lack it
+        days: { type: [number, 'null'] }
+      required: [available, currency, customerGroup, days]
+      additionalProperties: false
+\`\`\`
+
+\`\`\`ts
+// src/expressions/cabinet.ts
+import { memoEval } from '@salsita-ai/sdk/domain'
+
+export default phx.domain.implementCustomExpressions({
+  Cabinet: {
+    $delivery: memoEval(
+      (self, _state, ctx) => [
+        self.finish,
+        ctx.publishedData.finishes,
+        ctx.frontendData.currency,
+        ctx.sessionData.customerGroup,
+        ctx.backendData?.['deliveryDays'],
+      ],
+      (finish, finishes, currency, customerGroup, deliveryDays) => ({
+        available: finishes.includes(finish),
+        currency,
+        customerGroup: customerGroup ?? null,
+        days: typeof deliveryDays === 'number' ? deliveryDays : null,
+      })
+    ),
+  },
+})
+\`\`\`
+
+\`$delivery\` keeps one object while its five inputs are unchanged, so a reader of \`cabinet.$delivery\` re-renders only when one of them changes. \`$halfWidth\` is a number and needs neither TypeScript nor \`memoEval\`.`;export const generatePhoenixExpressionsFeature=()=>e({path:"features/domain-model/expressions.md",title:"Expressions",summary:"Derived values in YAML or TypeScript, `memoEval`, the expression context and the data hooks; read when computing a value from entity state or data sources.",whenToUse:"Read when a value derives from the configuration or its data — a price, a label, a limit, recipe options, a filter condition — or when custom React code needs the published, frontend or backend data.",capabilities:"### Choose the form\n\n- **`constants:`** — a fixed value per entity type or alias, without code (`$maxLegs: 4`). One that does not read `self` is also readable without an entity, as `phx.domain.enhancedModel.$Chair.$maxLegs`.\n- **`$eval` under `expressions:`** — one inline JavaScript expression of `self` (`$eval: self.width / 2`); give it an explicit `type`, because a value that reads `self` cannot be inferred. It sees only `self`: no state, context, helpers or imports. A `$eval` that does not read `self` is folded at parse time when it uses only literals, operators and `Math`; anything else needs an explicit `type` too.\n- **`$msg`** — a translatable text; [Localization](../localization.md) owns it.\n- **TypeScript** — anything that reads the data sources, the state or a helper, or needs more than one expression: declare the type in YAML and implement it in `src/expressions/`.\n\n### Declare and implement\n\n- Declare under `expressions:`, by entity type or alias, a `$name` with a JSON schema: `type`, `items`, `properties`, `$ref: phx:...`, or `tsType` with `import`.\n- Implement it with `phx.domain.implementCustomExpressions({ Desk: { $name: (self, state, ctx) => value } })`, default-exported from a file in `src/expressions/`, one file per entity type. Implement it under the entity type or alias that declares it.\n- A declared expression without an implementation stops the application at start with `MISSING_IMPLEMENTATION`; one implemented twice, or one the spec already gives a value, with `DUPLICATE_DEFINITION`.\n- Inference: a component `$read: $name` or filter `active: { $read: $name }` of an undeclared `$name` declares it with the type that prop or criterion expects, as recipe lists usually are. It still needs a TypeScript implementation. Declare it yourself to own the type; a type no read can accept fails with `EXPRESSION_READ_TYPE_CONFLICT`.\n\n### Pure, server-safe and stable\n\n- Expressions are pure: no side effects, no mutation of inputs, the same result for the same state and data. They are computed on demand and cached per state.\n- Expressions, invariants and actions also run on the server. Use `phx.domain` only, never `phx.frontend`, React or a browser-only import; put shared helpers in `_`-prefixed folders.\n- Keep the reference of an object or array result while its inputs are unchanged: wrap the implementation in `memoEval(deps, compute)` from `@salsita-ai/sdk/domain`. `deps(self, state, ctx)` returns an array compared item by item with `===`, and `compute(...deps)` runs only when an item changed.\n- List every input in `deps` and read nothing else in `compute`. Primitives need no `memoEval`.\n- A new object on every evaluation re-renders every reader and can reset systems that react to references, such as cameras; a mutated cached result hides the change.\n\n### The expression context\n\n- `self` is the `$` entity: fields, relations (`self.$drawers`), expressions and constants.\n- `state` is the domain state: `state.entities`, `state.rootEntityId`.\n- `ctx.publishedData`, `ctx.frontendData` and `ctx.sessionData` are typed by the spec's `publishedData:`, `frontendData:` and `sessionData:` schemas: a property missing from the schema's `required` list is optional.\n- A `sessionData` schema cannot list `required` properties (`SESSION_DATA_REQUIRED_PROPERTIES`), so every `ctx.sessionData` property may be `undefined`.\n- `ctx.backendData` is `Record<string, unknown> | undefined`: optional and untyped, so narrow each value before use.\n- `ctx.mode` is `owner`, `read` or `finalize`; `ctx.role` is the session role.\n- `ctx.domain.get$Entity(id, state)` and `ctx.domain.getRoot$Entity(state)` read other entities; `ctx` also has the component reader and the projections.\n\n### The data in React\n\n- `phx.frontend.usePublishedData()` and `phx.frontend.useFrontendData()` return the typed published and frontend data.\n- `phx.frontend.useBackendData()` returns the same optional, untyped backend data as `ctx.backendData`.\n- `phx.frontend.useLoadedData()` returns what the configurator loaded — `initialEntities`, `initialRevisionId`, `modelVersion`, `rootEntityType` — not the current state, which [State slices](../state/slices.md) reads.\n- Prefer an expression when the value also depends on the configuration: it is cached, runs on the server and can be bound in YAML. Read the hooks for data a custom element only displays.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/domain-model.mdx` — the Expressions, Constants and Static values with `$eval` sections.\n- `docs/phoenix/expression-context.mdx` — the context, its projections and the SDK expression builders.\n- `docs/phoenix/data-sources.mdx` — declaring the data schemas, their sources and lifetimes.\n- `docs/phoenix/components.mdx` — the `memoEval` section, for component outputs.",phxMembers:["domain.implementCustomExpressions","frontend.usePublishedData","frontend.useFrontendData","frontend.useBackendData","frontend.useLoadedData"]});

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/index.d.ts

@@ -0,0 +1 @@
+export * from './domain-model.js';

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/index.js

@@ -0,0 +1 @@
+export*from"./domain-model.js";

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/transformers.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Transformers: when to write one, triggers, actions, registration, order and debugging. */
+export declare const generatePhoenixTransformersFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/transformers.js

@@ -0,0 +1,43 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`The repair of [Validation and repair](validation-and-repair.md)'s \`widthTooLargeForTop\` invariant, and a stage that opens when users add a drawer, with \`Drawer\` composed under \`Desk\` and \`navigationStates: [configure, drawers, review]\`.
+
+\`\`\`yaml
+# spec/desk.yaml
+transformers:
+  - name: clampDeskWidth
+  - name: openDrawersStage
+\`\`\`
+
+\`\`\`ts
+// src/transformers/clamp-desk-width.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(['Desk'])
+  .modified({ atFields: ['topMaterial'] })
+  .causes.self.violation(['widthTooLargeForTop'])
+  .then.applySideEffect(ctx => {
+    const desk = ctx.getNew$Entity()
+
+    return [
+      phx.frontend.updates.DomainEntityModification({
+        entityId: desk.id,
+        stateDelta: { width: desk.$maxWidth },
+        updateTag: 'clampDeskWidth',
+        hint: 'The width was reduced to fit the new top',
+      }),
+    ]
+  })
+  .build('clampDeskWidth')
+\`\`\`
+
+\`\`\`ts
+// src/transformers/open-drawers-stage.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(['Drawer'])
+  .created()
+  .and(ctx => ctx.getNewNavigationState() === phx.applicationTypes.NavigationState.configure)
+  .then.navigateTo(phx.applicationTypes.NavigationState.drawers)
+  .build('openDrawersStage')
+\`\`\`
+
+- Choosing glass on an 1800 mm desk commits glass and 1600 mm as one undo step; the material control's dry run sees the repair, so glass stays enabled.
+- \`clampDeskWidth\` listens to \`topMaterial\` only, so a width option above the limit has no repair and stays disabled. \`when.entity(['Desk']).violated([...])\` would clamp every cause instead, a loaded configuration included.
+- Neither entry has a priority, so both see a control's write as an entity change, and \`openDrawersStage\` runs after auto selection has selected the new drawer.`;export const generatePhoenixTransformersFeature=()=>e({path:"features/domain-model/transformers.md",title:"Transformers",summary:"Rules that add or replace updates in a change: triggers, actions, registration, order and cost; read when one change must adjust other state, repair a violation or react to selection or navigation.",whenToUse:"Read when a change must carry follow-up updates: repairing a `fixable` violation, keeping dependent fields in step, or selecting, navigating or switching the view in reaction to a change. Declaring the invariant a transformer repairs belongs to [Validation and repair](validation-and-repair.md).",capabilities:"### Choose a transformer\n\n- **Expression** — a value derived from the state, such as a limit or a price: [Expressions](expressions.md).\n- **Action** — a named operation users trigger, such as adding a shelf: [Actions](actions.md).\n- **Invariant alone** — an option that is simply unavailable: the control disables it ([Validation and repair](validation-and-repair.md)).\n- **Transformer** — one change must carry more updates with it: repair a `fixable` violation, keep a stored field in step, or react to a selection, navigation or view change.\n- Built-in transformers already delete composed children, prune and write references, and select a created entity. Write none for these.\n\n### Triggers\n\nStart with `phx.frontend.transformerBuilder.when`. Each entity trigger adds `entityId`, `update` and its own entity getters:\n\n- `.entity(['Desk']).modified()` or `.modified({ atFields: ['width'] })` — every listed field is in `update.stateDelta`; `getOld$Entity()` and `getNew$Entity()`.\n- `.created()` — `getNew$Entity()` only. `.deleted()` — `getOld$Entity()` only.\n- `.entity(['New']).replaces(['Old'])`, `.entity(['Old']).replacedWith(['New'])` — `getReplacing$Entity()`, `getReplaced$Entity()`.\n- `.selected({ occurrence, insteadOf })`, `.deselected({ occurrence, inFavorOf })` — `getSelected$Entity()`, `getDeselected$Entity()`. `occurrence` is `'initial'` (default), `'repeated'` or `'any'`.\n- `.violated(['widthTooLargeForTop'])` — fires for each entity with that violation, whatever caused it, with `getViolated$Entity()` and no matched update.\n\nOther triggers:\n\n- `when.navigated({ from, to })`, `when.viewChanged(...)`, `when.toolChanged(...)` — both lists optional; `getFrom()`, `getTo()`.\n- `when.component([attributeSelectionComponent]).instance(['topMaterial']).modified` — the raw component write, with the type from `@salsita-ai/sdk/domain`; add `.onEntity(['Desk'])` for the entity getters. It sees a control's write only with a finite `priority`. Prefer an entity trigger.\n- `transformerBuilder.always` — every emission.\n\nNarrow a trigger before `.then`:\n\n- `.causes.self.violation([...])` — the matched entity has the violation after the change. `.causes.entity(['Leg']).withId(ctx => ids).violation([...])`, or without `withId` for every `Leg` — other entities have it; `getViolated$Entities()`.\n- `causes` and `violated` fire only while the new state is invalid, a `fatal` or `fixable` violation present. A `warning` or `notice` never triggers them.\n- `.withTag(['tag'])` filters by `updateTag`; prefer `atFields` or an instance name.\n- `.and(ctx => boolean)` adds any condition.\n- `transformerBuilder.onEmissionsOfKind(['committed']).when…` skips staged previews, such as a drag in progress, but not dry runs.\n\n### The context\n\n- `ctx.updates` — the whole batch this transformer receives; `ctx.update` — the matched update.\n- `ctx.getOldState()` and `getOld$Root()` — the committed state before the change, the same for every transformer.\n- `ctx.getNewState()`, `getNew$Root()`, `getNewValidity()` — the input batch applied, earlier transformers' updates included.\n- `ctx.getOldNavigationState()`, `getNewNavigationState()`, and the view-state pair.\n- `ctx.stateEmissionKind` — `'staged'` or `'committed'`.\n- `ctx.getIdSequence()` — ids for created entities.\n- Build every update with `phx.frontend.updates`: [Updates and dry runs](../state/updates.md) owns the kinds and the `hint` users see.\n\n### Actions\n\n- `.then.applySideEffect(ctx => updates)` adds updates; `[]` is a no-op.\n- `.then.overrideMatchingUpdate(ctx => updates)` replaces the matched update; not after `violated` or `always`.\n- `.then.overrideAllUpdates(ctx => updates)` replaces the whole batch, for the first match only; return `ctx.updates` to change nothing.\n- `.then.select.entity(ctx => id)`, and after an entity trigger `.select.self()` and `.select.ancestorOfType([...])`; `.then.deselect()`.\n- `.then.navigateTo(state)` and `.then.changeView(state)`, each taking a state or `ctx => state`. No action changes the tool.\n- Selecting, deselecting, navigating and changing the view drop the batch's other updates of that kind: the last one in the pipeline wins.\n- Added updates still get cascade deletes and reference upkeep.\n- Chain: `.then(other)` on the result runs `other` only when this stage changed the batch, `.else(other)` only when it did not. Finish with `.build('name')`.\n\n### Register\n\n- One file per transformer in `src/transformers/`, default-exported (an array exports several). Transformers are browser code.\n- List it under the top-level `transformers:` as `- name: <build name>`, with an optional `priority`. Only listed transformers run.\n- The entry equals the `build` name exactly, and the file name matches it with case and dashes ignored (`clamp-desk-width.ts`, `clampDeskWidth`). A missing file fails the spec check; a wrong `build` name fails when the configurator starts.\n- Only one spec file may declare `transformers:`, and each name once.\n\n### Order\n\n- One pass in ascending `priority`; ties keep the list order. Each transformer receives the previous one's output and never sees its own output again, so loops cannot happen.\n- Built-ins: 10 cascade deletes, 20 reference pruning, 25 reference creation, 30 reference replacement, 40 auto snap, 100 auto selection.\n- At `Infinity` a step turns control component writes into entity modifications, ahead of every transformer without a priority.\n- Leave the priority out for a transformer that reacts to control changes: with one, it runs before that step, where `.modified(...)` never sees a control's write. Give one only when it must run before a built-in, such as before auto selection or snapping, or for a component trigger.\n\n### Runtime and cost\n\n- Transformers run before validation in the same emission; their updates commit and undo with the change.\n- At startup they run once with empty updates, only when the loaded state has a `fatal` or `fixable` violation. Only `violated` and `always` fire then.\n- Every dry run of every control option runs them, as `'committed'`: a transformer cannot tell a dry run from a commit. Keep them pure and cheap: no requests, timers, storage or outside state.\n\n### Debug\n\n- With `IS_DEV` on, the default in local development, each emission carries `transformationLog`: per transformer its name, `status` (`no-event`, `no-match`, `no-resolve`, `match`, `no-apply`, `apply`), messages and the updates in and out.\n- Commits are logged to the console at debug level as `commit`. On the SDK's built-in controls, Shift with Cmd or Alt clicked on an option logs that option's `Trace dry-run:` emission, a disabled option included; in a project element, call the `trace()` the control hooks return.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/other-features/transformers.mdx` — every trigger and action with worked examples, the pipeline, cascades and tracing.\n- `docs/phoenix/configurator-interface.mdx`, section TransformerBuilder — registration and priority in brief.\n- `docs/selection-and-highlight/hierarchy.mdx` — a selection hierarchy built from selection and navigation transformers.",phxMembers:["frontend.transformerBuilder"]});

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/validation-and-repair.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Invariants, the four severities and when a transformer repairs a violation. */
+export declare const generatePhoenixValidationAndRepairFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/domain-model/validation-and-repair.js

@@ -0,0 +1,30 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let a=`The top material caps a desk's width. A width above the limit is unavailable, and choosing glass on a wide desk is repaired. The shape declares \`width\` (number) and \`topMaterial\` (string).
+
+\`\`\`yaml
+# spec/desk.yaml
+expressions:
+  Desk:
+    $maxWidth:
+      type: number
+      $eval: "self.topMaterial === 'glass' ? 1600 : 2000"
+invariants:
+  Desk:
+    widthFitsTop:
+      type: widthTooLargeForTop
+      severity: fixable
+      message:
+        $msg: This top is not made in this width
+transformers:
+  - name: clampDeskWidth
+\`\`\`
+
+\`\`\`ts
+// src/invariants/desk.ts
+export default phx.domain.implementCustomInvariants({
+  Desk: {
+    widthFitsTop: self => self.width <= self.$maxWidth,
+  },
+})
+\`\`\`
+
+The severity is \`fixable\` because \`clampDeskWidth\`, the first example in [Transformers](transformers.md), shrinks the width when the material changes to glass. A width option above the limit has no repair, so its dry run fails and the width control disables it with the message.`;export const generatePhoenixValidationAndRepairFeature=()=>e({path:"features/domain-model/validation-and-repair.md",title:"Validation and repair",summary:"Invariants in YAML and TypeScript, the four severities and when a violation needs a repairing transformer; read when enforcing a configuration rule.",whenToUse:"Read when the product has a rule a configuration must satisfy, such as an unsupported combination or a size limit, or when deciding whether a violation is repaired. [Transformers](transformers.md) owns writing the repair; [Violations](../state/violations.md) owns how violations reach controls, hints and the finalize button.",capabilities:"### Declare an invariant\n\n- Declare invariants under `invariants:`, by entity type or alias, each under a camelCase name:\n  - **Static** — `type`, `severity`, `message` (a string or `$msg`) and an optional `controlViolationPriority`. The implementation returns `true` when the rule holds and `false` to report the declared violation.\n  - **Dynamic** — `types: [...]` and nothing else. The implementation returns an array of `{ type, severity, message?, controlViolationPriority?, formatControlViolationMessage? }`, each `type` one of the declared `types`, and `[]` when the rule holds. Use it when the severity or the message depends on the state, or one rule reports several kinds.\n- Violation types start with a lowercase letter. Transformers and a control's `fixableViolations` name violation types, not invariant names.\n- Implement with `phx.domain.implementCustomInvariants({ Desk: { name: (self, state, ctx) => ... } })`, default-exported from a file in `src/invariants/`. A type the call lists must implement every invariant declared for it, so keep one file per entity type. A declared invariant no file implements never runs, and nothing reports it.\n- Keep invariants pure, cheap and server-safe like expressions: compute the limit in an expression and compare in the invariant (`self.width <= self.$maxWidth`). An invariant that throws makes every change invalid, with no message.\n- [Violations](../state/violations.md) owns how priorities and messages reach controls and the finalize button; [Localization](../localization.md) owns translated messages.\n\n### Choose a severity\n\nThe parser accepts exactly `fatal`, `fixable`, `warning` and `notice`; there is no `error`.\n\n| Severity | At commit | Control option in a dry run | Finalizing |\n| --- | --- | --- | --- |\n| `fatal` | rejected: never rendered, saved or undoable | disabled | blocked |\n| `fixable` | rejected, as `fatal` | disabled | blocked |\n| `warning` | committed and saved | enabled | blocked |\n| `notice` | committed and saved | enabled | allowed, message shown as a hint |\n\n- **fatal** — a combination that must never exist and that no repair makes valid.\n- **fixable** — behaves as `fatal`, and states that a transformer repairs it; use it for every violation a transformer handles.\n- **warning** — users may work with it but must resolve it before finalizing, such as a choice not made yet.\n- **notice** — information that restricts nothing.\n- A preset or saved configuration with a `fatal` or `fixable` violation runs through the transformers once, with no updates, when it loads; if it is still invalid, it does not load.\n\n### Repair with a transformer\n\n- Write a transformer when users should be able to make a choice that breaks the rule, such as a new top material on a wide desk: it adds the repairing updates before validation, so the change commits valid, and the control's dry run sees the repair and keeps the option enabled.\n- Repair the choice users expect to win, not every cause: a violation no transformer repairs keeps disabling its options.\n- Declare every repaired violation `fixable`, so the spec states that a repair exists.\n- [Transformers](transformers.md) owns the builder, registration, priority and order.",example:a,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/domain-model.mdx` — "Invariants": static and dynamic invariants in YAML and TypeScript, and the four severities.\n- `docs/other-features/violation-severity.mdx` — each severity tried live on controls and the finalize button.\n- `docs/other-features/violation-messages.mdx` — `controlViolationPriority` and formatted messages.',phxMembers:["domain.implementCustomInvariants"]});

package/dist/application-spec/generate-application/code/templates/skills/features/features.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../guide.js';
+/** The capability index followed by every feature guide, each folder listed by its own index. */
+export declare const generatePhoenixFeatureGuides: () => readonly PhoenixGuide[];

package/dist/application-spec/generate-application/code/templates/skills/features/features.js

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as e}from"../guide.js";import{generatePhoenixApplicationStatesGuides as n}from"./application-states/index.js";import{generatePhoenixCustomLayoutGuides as o}from"./custom-layout/index.js";import{generatePhoenixDomainControlsGuides as s}from"./domain-controls/index.js";import{generatePhoenixDomainModelGuides as i}from"./domain-model/index.js";import{generatePhoenixInspectionFeature as t}from"./inspection.js";import{generatePhoenixLocalizationFeature as a}from"./localization.js";import{generatePhoenixSceneObjectsFeature as d}from"./scene-objects.js";import{generatePhoenixStateGuides as r}from"./state/index.js";import{generatePhoenixVariantsFeature as c}from"./variants.js";import{generatePhoenixWebhooksFeature as m}from"./webhooks.js";export const generatePhoenixFeatureGuides=()=>{let p=[i(),r(),n(),s(),o(),[a()],[d()],[m()],[t()],[c()]];return[e({path:"features/index.md",title:"Features",summary:"What Phoenix capabilities support, their constraints and the canonical SDK documentation.",intro:"Read only the guide the task needs. Each guide teaches its part of the `phx` global and names the SDK documents to read with `pnpm phoenix docs -r <path>`; a link does not make its destination required reading.",guides:p.flatMap(e=>e.slice(0,1)),notes:["## Browse the SDK docs\n\n`pnpm phoenix docs` lists every category with its document count, `-c '<Category>'` shows one category's documents with descriptions and `-l` lists every path with its title. `-s '<text>'` matches literal text line by line, so search for one distinctive term, such as an API or YAML key, rather than a phrase.","## Topic map\n\nTopics no guide covers yet point straight to the canonical SDK docs.\n\n### Project and customization\n\n- `docs/phoenix/getting-started.mdx`, `docs/phoenix/quickstart.mdx` — setup and a complete worked configurator.\n- `docs/phoenix/best-practices.mdx` — supported composition and extension patterns.\n- `docs/phoenix/project-structure.mdx` — authored folders, generated files and naming rules.\n- `docs/phoenix/theming.mdx`, `docs/ux-guidelines/overview.mdx` — theme, branding and interaction principles.\n- The **3d scene**, **Drag & Drop**, **Performance** and **Complex Use Cases** categories — materials, lights, cameras, dragging and snapping, and worked combinations.\n\n### Webhooks and finalization\n\n- `docs/phoenix/webhooks.mdx`, `docs/phoenix/finalization.mdx` — execution, tasks, PDF, email and CSV.\n- `docs/phoenix/blender-rendering.mdx` — server-rendered images of the `GenerateImages` task.\n- `docs/other-features/client-side-rendering/declarative.mdx` — configurator-rendered images in PDFs and emails.\n\n### Data sources\n\n- `docs/phoenix/data-sources.mdx`, `docs/phoenix/connected-data-sources.mdx` — published, frontend, session and backend data, and connected sheets.\n\n### Admin and Studio\n\n- `docs/phoenix/admin.mdx`, `docs/phoenix/publishing.mdx` — project content administration and published revisions.\n- `docs/phoenix/sdk-builder-workflow.mdx` — Studio workspaces, projects, environments and builds.\n\n### CLI, access and deployment\n\n- `docs/phoenix/phoenix-cli.mdx` — login, dependencies, sync, dev, build and check.\n- `docs/phoenix/sessions-and-access.mdx`, `docs/phoenix/clerk-sign-in.mdx` — configurator access and project authentication.\n- `docs/phoenix/deployments.mdx` — environments and server builds."]}),...p.flat()]};

package/dist/application-spec/generate-application/code/templates/skills/features/index.d.ts

@@ -0,0 +1 @@
+export * from './features.js';

package/dist/application-spec/generate-application/code/templates/skills/features/index.js

@@ -0,0 +1 @@
+export*from"./features.js";

package/dist/application-spec/generate-application/code/templates/skills/features/inspection.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixInspectionFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/inspection.js

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";import{sdkGuidanceSections as n}from"../sdk-content.js";export const generatePhoenixInspectionFeature=()=>e({path:"features/inspection.md",title:"Inspection",summary:"Asset and live runtime inspection commands; read when checking models, scene, state, data or rendered output.",whenToUse:"Read when checking imported assets or investigating the running configurator. Runtime inspection needs dev running and the preview open in a browser.",capabilities:[n.assetInspection,n.screenshotCli,n.inspectState,n.inspectData,n.inspectScene,n.playwrightMcpSetup].join("\n\n"),example:"After changing a material, run `pnpm phoenix inspect:scene` to inspect the assigned material, then `pnpm phoenix screenshot -o ./render.png` to compare the rendered result. A canvas screenshot does not cover the surrounding interface.",documentation:"Read `docs/phoenix/phoenix-cli.mdx` with `pnpm phoenix docs -r docs/phoenix/phoenix-cli.mdx` for command flags and output contracts. Use the [review index](../processes/review/index.md) when deciding which evidence the change needs.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/localization.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../guide.js';
+/** The guide to languages: enabling them, translatable texts, the language switch, webhook locale and catalogs. */
+export declare const generatePhoenixLocalizationFeature: () => PhoenixGuide;