@salsita-ai/sdk 0.50.0-develop.ae9a830ef0 → 0.50.0-develop.afbc5157e1

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 and invariants 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- [Actions](actions.md) execute in the browser, but their modules also load in the webhook and must keep runtime imports server-safe; type-only browser imports are allowed.\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 t}from"./domain-controls/index.js";import{generatePhoenixDomainModelGuides as s}from"./domain-model/index.js";import{generatePhoenixInspectionFeature as i}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{generatePhoenixWebhooksGuides as p}from"./webhooks/index.js";export const generatePhoenixFeatureGuides=()=>{let m=[s(),r(),n(),t(),o(),[a()],[d()],p(),[i()],[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:m.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### 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."]}),...m.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;

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

@@ -0,0 +1,87 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";let a=`Read when the configurator needs several languages, when adding user-facing text to such a project, or when a PDF or email must follow the configurator user's language.
+
+Enable localization when the client sells in several languages; take them from the product definition, and ask when it names none. With one language and none planned, plain strings are fine. When more are likely, make every text translatable from the start: converting later touches every label, message and template.`,t=`A table sold in English and German: option labels in the spec, an invariant message and a picker in a custom layout.
+
+\`\`\`yaml
+# spec/application.yaml
+availableLocales: [en, de]
+textLanguages: [en, de]
+
+# spec/table.yaml
+invariants:
+  Table:
+    glassLength:
+      types: [glassTooLong]
+components:
+  Table:
+    applicationConfig:
+      main:
+        availableLocales: [en, de] # what users can pick; add it to an existing instance
+    attributeSelection:
+      finish:
+        value:
+          $bind: finish
+        options:
+          - value: oak
+            label:
+              $msg: Oak
+          - value: glass
+            label:
+              $msg: Glass
+\`\`\`
+
+\`\`\`ts
+// src/invariants/table.ts
+import { msg } from '@lingui/core/macro'
+
+const MAX_GLASS_LENGTH = 2000
+
+export default phx.domain.implementCustomInvariants({
+  Table: {
+    glassLength: table =>
+      table.finish === 'glass' && table.length > MAX_GLASS_LENGTH
+        ? [
+            {
+              type: 'glassTooLong',
+              severity: 'fatal',
+              message: msg\`Glass tops are available up to \${MAX_GLASS_LENGTH} mm.\`,
+            },
+          ]
+        : [],
+  },
+})
+\`\`\`
+
+\`\`\`tsx
+// src/elements/_shared/LanguagePicker.tsx, rendered by the project's ConfiguratorLayout
+import { msg } from '@lingui/core/macro'
+import { MenuItem, TextField } from '@mui/material'
+
+const LANGUAGE = msg\`Language\`
+
+export const LanguagePicker = () => {
+  const label = phx.frontend.useLocalizable(LANGUAGE)
+  const { locales, locale, setLocale, available } = phx.frontend.useLocaleSwitch()
+
+  if (!available) {
+    return null
+  }
+
+  return (
+    <TextField select size="small" label={label} value={locale} onChange={event => setLocale(event.target.value)}>
+      {locales.map(option => (
+        <MenuItem key={option.locale} value={option.locale}>
+          {option.displayName}
+        </MenuItem>
+      ))}
+    </TextField>
+  )
+}
+\`\`\`
+
+After \`pnpm phoenix sync\`, translate the texts in \`src/locales/de/messages.po\`, keeping the placeholder:
+
+\`\`\`po
+msgid "Glass tops are available up to {MAX_GLASS_LENGTH} mm."
+msgstr "Glasplatten gibt es bis {MAX_GLASS_LENGTH} mm L\xe4nge."
+\`\`\``;export const generatePhoenixLocalizationFeature=()=>e({path:"features/localization.md",title:"Localization",summary:"Languages, translatable spec and TypeScript texts, the language switch, the webhook's language, catalogs and formatting; read when the configurator must work in more than one language or a text must be translatable.",whenToUse:a,capabilities:"### Enable languages\n\nThree lists, each with its own job:\n\n- **`availableLocales`** in `spec/application.yaml` (default `[en]`) — the languages with a project catalog, `src/locales/<locale>/messages.po`.\n- **`availableLocales` of the root entity's `applicationConfig`** — the languages users can pick. Without it the switch offers English only and the default toolbar has no language button. Keep it within the top-level list: picking another locale activates its fallback.\n- **`textLanguages`** in `spec/application.yaml` — the languages Admin edits multilingual texts in, and the fallback order of `$lang` values.\n\nThe configurator starts in the embedding page's `locale` attribute or property (English when unset), not the first listed locale. A page locale outside `availableLocales` falls back to a listed one: a regional locale to its listed base language (`de-AT` to `de`), anything else to `en`, or to the first listed locale when `en` is not listed. List a regional locale the site sets when its texts should differ from the base language; its empty entries compile from the base language. In a language the SDK lacks, built-in texts stay English.\n\n### Spec texts: `$msg` or `$lang`\n\n- **`$msg`** — UI text authored in the spec: titles, labels, hints, static invariant messages, constants. The text is its own id, so rewording drops its translations; add a stable `$msgId: 'finish.title'` to texts likely to change.\n- **`$lang`** — data carrying its own translations: Admin content, published data, imports. Inline `$lang` in the spec suits data the client supplies translated.\n- A plain string shows unchanged in every language.\n- An expression holding `$msg` or `$lang` declares `$ref: phx:Localizable`; for `$msg`, `type: string` reports `EXPRESSION_VALUE_TYPE_MISMATCH`.\n- `$lang` resolves to the active locale, then each `textLanguages` entry, then `en`, else an empty string. List every market language there, primary first.\n\n### TypeScript texts\n\n- `msg` from `@lingui/core/macro` creates a message descriptor: use it for invariant messages, expression results the UI shows and labels passed to components. `` msg`Up to ${max} mm` `` keeps a placeholder for translators, `msg({ id, message })` fixes the id, `plural` handles counts.\n- Expressions, invariants and transformers run without a locale, on the server too: return descriptors or `$lang`, never translated strings or formatted numbers. [Violations](state/violations.md) covers hint texts formatted per change.\n- In React, render content with `<Trans>` from `@lingui/react/macro`. Where a string is needed (an attribute, a string-only prop, a spec text, a descriptor):\n  - `phx.frontend.useLocalizable(text)` returns one text in the active language;\n  - `phx.frontend.useResolveLocalizable()` returns `resolve(text)` for lists, loops and conditional texts.\n- Both accept a string, a descriptor or `$lang`, apply the `textLanguages` fallback and re-render on a language change. Resolve inside components, never at module scope.\n\n### Language switch\n\n- The default toolbar shows a language button, and a menu action on phones, when the `applicationConfig` list has several locales. A configured `toolbar` lists `languageToolbarButton` and `languageMenuAction` itself; [Toolbar actions](custom-layout/toolbar-actions.md) covers toolbars a layout renders.\n- `phx.frontend.useLocaleSwitch()` returns `{ locales, locale, setLocale, available }`: the `applicationConfig` locales as `{ locale, displayName }`, each named in its own language; the active locale; a setter; and whether there is a choice. Use it for your own picker and wherever code needs the active locale.\n\n### Webhooks\n\n- The language reaches the webhook only if the finalize handler sends it: `apiClient.finalize(configurationId, finalizationUuid, finalizeData, locale, frontendData)`, with `locale` from `phx.frontend.useLocaleSwitch()`. Without it, PDFs and emails come out in English. [Finalization](../processes/finalization.md) owns the handler.\n- Tasks get `ctx.resolveLocalizable(text)`, bound to that locale and `textLanguages`, and `ctx.i18n`. The PDF and email builders resolve every localizable input; templates use `<Trans>`, and `HtmlHelpers.Localized` from `@salsita-ai/sdk/webhook` for domain texts.\n- `.withLocale('de')` renders one PDF or email in another language. Plain payloads (CSV, HTTP) need `ctx.resolveLocalizable` on each text.\n\n### Catalogs and translation\n\n- `pnpm phoenix sync` and `pnpm phoenix build` extract every `msg`, `<Trans>` and `$msg` into the PO files and compile the TypeScript catalogs.\n- `pnpm phoenix dev` only creates missing catalogs at startup; with `--withLingui` (or `WITH_LINGUI=true`) it extracts and compiles on every change. Without it a new text stays English until the next sync. Restart dev after changing `availableLocales`.\n- Translate in the `msgstr` entries of `src/locales/<locale>/messages.po`, keeping placeholders such as `{max}`. Never edit the compiled `messages.ts` ([CLI core](../core/cli.md)).\n- An empty `msgstr` compiles from the fallback chain (`de-AT` → `de` → `en`): the text shows English, without an error. Before a handover, search for empty `msgstr \"\"` entries after the header.\n- When you translate yourself, tell the client which languages need a native speaker's review and record them as provisional.\n\n### Numbers and currency\n\n- `phx.frontend.useRootEntityPrice()` formats the root's `price` component for the active locale in its `currency` (`USD` when unset), and returns `null` while the root has none; choose the currency per market in the spec.\n- Format other numbers, dates and lists with `Intl` and the active locale: `useLocaleSwitch().locale` in React, `ctx.i18n.locale` in webhooks.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/localization.mdx` — enabling languages, choosing the language, `$msg`, `$msgId`, `$lang` and its sources, the hooks and server-side translation.\n- `docs/phoenix/webhooks.mdx` — localized PDF and email builders and `.withLocale`.\n- `docs/other-features/violation-messages.mdx` — translated violation hints with nested labels.\n- `docs/other-features/currency.mdx` — the currency chosen from session data, one price component per currency filtered with `active`.\n- `docs/integrations/webcomponent-api/basics.mdx` — the page's `locale` property.",phxMembers:["frontend.useResolveLocalizable","frontend.useLocalizable","frontend.useLocaleSwitch","frontend.useRootEntityPrice"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../guide.js';
+/** Scene objects built in code: scene elements, custom entities and attached three.js objects, rebuilding and disposal. */
+export declare const generatePhoenixSceneObjectsFeature: () => PhoenixGuide;

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

@@ -0,0 +1,43 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";let t=`A worktop with a cut-out per basin, as a scene element. The geometry is rebuilt only when the length or the cut-outs change; React Three Fiber releases the old one.
+
+\`\`\`yaml
+# spec/domain.yaml, components of Washtable
+sceneEntityObject:
+  worktop:
+    name: 'Worktop'
+sceneEntityObjectProperties:
+  worktop:
+    offsetY: 850
+\`\`\`
+
+\`\`\`tsx
+// src/elements/Worktop.tsx
+import { useMemo } from 'react'
+import { Path, Shape } from 'three'
+
+const NO_CUT_OUTS: readonly number[] = []
+
+export default phx.frontend.createCustomPhoenixEntityElement('Worktop', ({ entityId }) => {
+  const entity = phx.frontend.useCommittedState().entities.find(e => e.id === entityId)
+  const washtable = entity?.type === 'Washtable' ? entity : undefined
+  const length = washtable?.length ?? 1200
+  const cutOuts = washtable?.basinPositions ?? NO_CUT_OUTS
+
+  const shape = useMemo(() => {
+    const top = new Shape().moveTo(0, 0).lineTo(length, 0).lineTo(length, 460).lineTo(0, 460).closePath()
+    for (const x of cutOuts) {
+      top.holes.push(new Path().absellipse(x, 230, 180, 140, 0, Math.PI * 2, false, 0))
+    }
+    return top
+  }, [length, cutOuts])
+
+  return (
+    <mesh rotation-x={-Math.PI / 2} castShadow receiveShadow>
+      <extrudeGeometry args={[shape, { depth: 12, bevelEnabled: false }]} />
+      <meshPhysicalMaterial color="#f1ede4" roughness={0.35} clearcoat={0.3} />
+    </mesh>
+  )
+})
+\`\`\`
+
+A new finish changes only the material's color; dragging a basin changes \`basinPositions\`, which a cut-out needs, so that rebuild is real.`;export const generatePhoenixSceneObjectsFeature=()=>e({path:"features/scene-objects.md",title:"Scene objects built in code",summary:"Geometry built in code instead of loaded from a model, and keeping its rebuilds cheap; read when part of the product or its setting is generated.",whenToUse:"Read when part of the product or its setting is built in code instead of loaded from a model: geometry that follows the configuration, such as a worktop with cut-outs where the basins sit, a shelf that grows with its width or a room whose walls follow the plan.\n\nPrefer a model when one exists: `sceneEntityRemoteObject` loads a GLB, and `sceneEntityObjectProperties` positions it and binds its transforms to state. Build in code what a model cannot express.",capabilities:"### Three ways to build it\n\n- **A scene element** — usually the best fit. Name an element in an entity's `sceneEntityObject` instance, `name: 'Worktop'`, and register it in `src/elements/` with `phx.frontend.createCustomPhoenixEntityElement('Worktop', ({ entityId }) => …)`; [Custom controls](domain-controls/custom-controls.md) has the registration rules. It returns React Three Fiber JSX, meshes with their geometries and materials, and reads state through the hooks like any entity element. React Three Fiber releases what it created when the element unmounts or a geometry's `args` change.\n- **A whole custom entity** — `customSceneEntity` with `name` replaces the entity's entire representation by the element. The entity's remote objects, object properties, materials, decals and clips are then ignored; child entities still render.\n- **A three.js object** — attach `sceneEntityObjectComponent` from `@salsita-ai/sdk/domain` with `phx.domain.attachComponent` in `src/components/`, its state `{ object }` built in `memoEval`. The SDK renders the object as given and never disposes it.\n\nFor the first and third, `sceneEntityObjectProperties` of the same instance still positions, hides and highlights the object.\n\n### Rebuild only when the shape changes\n\nA rebuild costs geometry, triangulation and an upload to the GPU, and a slider or a drag can ask for one every frame.\n\n- Rebuild when an input that changes the shape changes, such as a length or a cut-out, and nothing else: memoize the geometry on those inputs, `useMemo` in an element or the `memoEval` dependencies of an attached object.\n- Move, rotate or recolor the existing object for a position or a finish, through `sceneEntityObjectProperties` bindings or the material, instead of rebuilding it.\n- A three.js object you replace keeps its GPU memory until you call `dispose()` on its geometries, materials and textures, so dispose what a rebuild replaces. Reuse a texture across rebuilds rather than cloning it and setting `needsUpdate` each time, which uploads it again.\n\n### Shadows and effects\n\n- On a three.js object, `sceneEntityObjectProperties` sets `castShadow` and `receiveShadow` on every child from the spec, `false` when unset, so flags set in code are overwritten: set them in the spec. A scene element sets them on its own meshes.\n- Soft shadows on large surfaces, outlines and other effects cost every frame; keep those whose result the client sees.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/3d-scene/rendering/basic.mdx` — loaded models, object properties and three.js objects attached in code.\n- `docs/3d-scene/rendering/scene-entity-object.mdx` — the `sceneEntityObject` component and its forms.\n- `docs/3d-scene/rendering/custom-entity.mdx` — `customSceneEntity` and a complete React Three Fiber element.\n- `docs/3d-scene/rendering/soft-shadows.mdx` — the canvas, object and light settings shadows need.\n- The **Performance** category — what costs per frame and per change.",phxMembers:[]});

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

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

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

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

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The store's three slices, which UI reads which, and the hooks that read them without needless re-renders. */
+export declare const generatePhoenixStateSlicesFeature: () => PhoenixGuide;

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

@@ -0,0 +1,48 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A cabinet label follows a drag frame by frame, while the order summary ignores previews and rejected changes. The label returns a tuple of numbers, so it re-renders only when one changes; returning \`cabinet.$shelves\` would re-render it on every pointer move.
+
+\`\`\`tsx
+// src/elements/CabinetWidthLabel.tsx
+import { Trans } from '@lingui/react/macro'
+import { Typography } from '@mui/material'
+
+export default phx.frontend.createCustomPhoenixEntityElement('CabinetWidthLabel', ({ entityId }) => {
+  if (!phx.domain.model.Cabinet.isId(entityId)) {
+    throw new Error('CabinetWidthLabel is attached to a Cabinet only.')
+  }
+
+  const [width, shelves] = phx.frontend.useRenderedEntitySelector(
+    entityId,
+    cabinet => [cabinet.width, cabinet.$shelves.length] as const,
+    []
+  )
+
+  return (
+    <Typography variant="caption">
+      <Trans>
+        {width} mm, {shelves} shelves
+      </Trans>
+    </Typography>
+  )
+})
+\`\`\`
+
+\`\`\`tsx
+// src/_shared/OrderSummary.tsx: committed only, so a dragged-across position never shows a price
+import { Trans } from '@lingui/react/macro'
+import { Typography } from '@mui/material'
+
+export const OrderSummary = () => {
+  const [cabinets, total] = phx.frontend.useRootEntitySelector(
+    kitchen => [kitchen.$cabinets.length, kitchen.$totalPrice] as const,
+    []
+  )
+
+  return (
+    <Typography>
+      <Trans>
+        {cabinets} cabinets, {total}
+      </Trans>
+    </Typography>
+  )
+}
+\`\`\``;export const generatePhoenixStateSlicesFeature=()=>e({path:"features/state/slices.md",title:"State slices",summary:"The rendered, committed and potentially invalid slices and the hooks that read them; read when UI shows configuration state, such as a live label during a drag or a price summary.",whenToUse:"Read when UI shows configuration state: choosing between a live preview and the committed configuration, picking a reading hook, or keeping an element from re-rendering on every drag frame. Writing changes belongs to [Updates and dry runs](updates.md).",capabilities:"### The three slices\n\nThe store keeps three slices. Each emits a state emission `{ kind, state, validity }`; an update emission adds `previousState` and `updates`.\n\n- **`rendered`** — every valid state, committed or staged: gesture previews and hover included. The scene renders from it. An invalid staged state is not emitted, so the preview stays at the last valid one.\n- **`committed`** — every valid committed state: what is saved, what undo records and what finalizing checks.\n- **`potentiallyInvalid`** — every attempted commit, rejected ones included. No reading hook targets it; configurator messages report its rejections ([Messages](../custom-layout/messages.md)).\n\n`state` is `{ rootEntityId, rootEntityType, entities, ephemeralRecords }`:\n\n- `entities` are raw entities: own fields only, no `$` expressions or relations. Read the `$` entity through the entity hooks below.\n- `ephemeralRecords` hold navigation, view, tool, selection, hover and drag state. They are never saved, and a commit that changes only them makes no undo step. Read them with the hooks of [Application states](../application-states/index.md), not by scanning records.\n\n### Choose a slice\n\n- **Rendered** — what must follow a gesture while it happens: a dimension label during a drag, an in-scene overlay, a live preview of the value being changed.\n- **Committed** — what must not flicker with previews or show a state nobody accepted: price, summaries, step completion, enabling Next or Finalize, analytics, data sent to a server.\n- Never mix them in one value: a price computed from rendered state shows prices of positions a drag only passed through.\n\n### Reading hooks\n\nEach pair reads the committed slice first, the rendered slice second:\n\n- `phx.frontend.useStoreSelector(select, deps)` \xb7 `phx.frontend.useRenderedSelector(select, deps)` — `select(emission)` returns any value. An optional third argument `false` pauses updates, for hidden UI.\n- `phx.frontend.useEntitySelector(id, select, deps)` \xb7 `phx.frontend.useRenderedEntitySelector(id, select, deps)` — `select($entity, emission)` for one entity.\n- `phx.frontend.useRootEntitySelector(select, deps)` \xb7 `phx.frontend.useRenderedRootEntitySelector(select, deps)` — the same for the root entity.\n- `phx.frontend.useEntityState(id)` — the committed `$` entity. It takes the id only and has no rendered twin on `phx.frontend`; use `useRenderedEntitySelector`.\n- `phx.frontend.useRootEntityState()` \xb7 `phx.frontend.useRootEntityRenderedState()` — the root `$` entity.\n- `phx.frontend.useRootEntityId()` \xb7 `phx.frontend.useRootEntityRenderedId()` — the root entity's id.\n- `phx.frontend.useCommittedState()` \xb7 `phx.frontend.useRenderedState()` — the whole `state`.\n- `phx.frontend.useCommittedSlice()` \xb7 `phx.frontend.useRenderedSlice()` — the whole emission, `validity` included. Neither takes an argument.\n- `phx.frontend.useStoreSelector$(select, deps)` \xb7 `phx.frontend.useRenderedSelector$(select, deps)` — an RxJS observable of the selected value, for work outside rendering such as a debounced request in an effect. It replays the current value and emits for every emission, equal or not: add `distinctUntilChanged()`.\n\nThe entity hooks throw for an id the state does not contain: take ids from the slice you read, and drop an id once its entity is deleted. In event handlers and async flows, read `storeSystem.stateSlices.committed.value.state` from `phx.frontend.useDomain()` when the code runs; a value captured during render may be stale by then.\n\n### Keep re-renders narrow\n\n- A selector runs for every emission of its slice; the component re-renders only when the result changes. Results compare shallowly: a primitive by value, an object or array member by member, each member by reference.\n- Return primitives, ids, counts or tuples of them. A relation such as `$shelves`, and anything built from it, is a new array on every state, so returning it re-renders every time: return its `length` or its ids.\n- The whole-object hooks (`useEntityState`, `useRootEntityState`, `useRootEntityRenderedState`, the state and slice hooks) compare the whole entity or state. An entity re-renders its component when one of its fields or expression values changes, and a relation is a new array on every state, so an entity with relations, such as the root, re-renders on every commit, and on every drag frame for the rendered ones. Keep them for small panels; use a selector in elements mounted per entity or shown during gestures.\n- List in `deps` every component value the selector reads, as for `useMemo`; the entity selectors add the id themselves. A missing dependency keeps a stale selector.\n- Treat every returned value as immutable. Move expensive derivations into [expressions](../domain-model/expressions.md), which are cached per state, rather than computing them in selectors.",example:t,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/performance/render-isolation.mdx` — rendered entity selectors that keep a large scene smooth while dragging, and why their results must compare equal.\n- `docs/phoenix/state-management.mdx` — slices, the emission lifecycle, validity results and the selector hooks.\n- `docs/phoenix/configurator-interface.mdx` — "Core Hooks": the slice, selector and entity hooks with a sample call each.',phxMembers:["frontend.useStoreSelector","frontend.useRenderedSelector","frontend.useStoreSelector$","frontend.useRenderedSelector$","frontend.useEntitySelector","frontend.useRenderedEntitySelector","frontend.useRootEntitySelector","frontend.useRenderedRootEntitySelector","frontend.useEntityState","frontend.useRootEntityState","frontend.useRootEntityRenderedState","frontend.useRootEntityId","frontend.useRootEntityRenderedId","frontend.useCommittedState","frontend.useRenderedState","frontend.useCommittedSlice","frontend.useRenderedSlice"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The state index followed by its guides: reading the store, writing it, and how violations surface. */
+export declare const generatePhoenixStateGuides: () => readonly PhoenixGuide[];

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

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as t}from"../../guide.js";import{generatePhoenixStateSlicesFeature as e}from"./slices.js";import{generatePhoenixUpdatesFeature as o}from"./updates.js";import{generatePhoenixViolationsFeature as a}from"./violations.js";export const generatePhoenixStateGuides=()=>{let n=[e(),o(),a()];return[t({path:"features/state/index.md",title:"State",summary:"Reading and writing the configuration at runtime and how violations surface; read when UI or a handler reads or changes the configuration, or must reflect what a change breaks.",intro:"The configurator keeps the configuration in a store. The slices hold the states UI can read; updates stage and commit changes, and dry runs test them first; the violations of those states disable control options, become hints and block finalizing. Read only the guide for the task. Declaring invariants belongs to [Validation and repair](../domain-model/validation-and-repair.md), transformers to [Transformers](../domain-model/transformers.md), and the controls that write for you to [Domain controls](../domain-controls/index.md).",guides:n,notes:[]}),...n]};

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Writing the configuration: update kinds, the stage and commit cycle, dry runs, undo steps and update guards. */
+export declare const generatePhoenixUpdatesFeature: () => PhoenixGuide;

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

@@ -0,0 +1,39 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A width scrubber no configured control covers: every position is previewed, the release commits once, and the drag is one undo step. A width that breaks an invariant is not previewed, so the cabinet stays at the last valid width; a rejected release reverts the preview and becomes a message.
+
+\`\`\`tsx
+// src/_shared/WidthScrubber.tsx
+import { Slider } from '@mui/material'
+
+export const WidthScrubber = ({ cabinetId }: { readonly cabinetId: Cabinet['id'] }) => {
+  const { storeSystem } = phx.frontend.useDomain()
+  const width = phx.frontend.useRenderedEntitySelector(cabinetId, cabinet => cabinet.width, [])
+
+  const preview = (value: number | number[]) => {
+    if (typeof value !== 'number') {
+      return
+    }
+
+    // Replaces the previous preview: the whole change from the committed state
+    storeSystem.stage([
+      phx.frontend.updates.DomainEntityModification({
+        entityId: cabinetId,
+        stateDelta: { width: value },
+        updateTag: 'cabinet.scrubWidth',
+      }),
+    ])
+  }
+
+  return (
+    <Slider
+      value={width}
+      min={400}
+      max={1200}
+      step={10}
+      onChange={(_event, value) => preview(value)}
+      onChangeCommitted={() => storeSystem.commit()}
+    />
+  )
+}
+\`\`\`
+
+A discrete action is one call, such as \`storeSystem.stageAndCommit([phx.frontend.updates.EntityDeletion({ entityId, updateTag: 'cabinet.remove' })])\`. When configurator users pick it among options, a control with a dry run is the better home.`;export const generatePhoenixUpdatesFeature=()=>e({path:"features/state/updates.md",title:"Updates and dry runs",summary:"Update kinds, the stage, commit and rollback cycle, dry runs and undo steps; read when code writes the configuration or a transformer must stay cheap.",whenToUse:"Read when code writes the configuration outside a configured control, previews a change during a gesture, dry-runs a change to decide whether to offer it, needs ids for new entities, or narrows updates in a transformer.",capabilities:"### Choose the write path\n\n- Write through the control hooks of [Custom controls](../domain-controls/custom-controls.md) first: they build updates, dry-run options, stage gestures and commit. `phx.frontend.useUpdateControl(fixableViolations)` returns `prepare(updates)`, which dry-runs any updates and returns `{ disabled, hints, update, stage, trace }`.\n- Use the store system only when no control hook fits: a gesture you drive yourself, a write from a toolbar action, dialog or handler, a confirmation before a commit, or work that waits for a gesture to end.\n- `phx.frontend.useDomain()` returns the stable domain systems (`storeSystem`, `domain`, `undoSystem`, `navigationSystem`, `componentReader`, the projections), safe in dependency arrays. Navigation and selection changes belong to [Application states](../application-states/index.md).\n- Transformers return update arrays and never write to the store ([Transformers](../domain-model/transformers.md)).\n\n### Build updates\n\nEach `phx.frontend.updates` factory takes one object with an `updateTag` naming the change, such as `'cabinet.scrubWidth'`; `withTag` filters, the guards below and analytics read it. An optional localizable `hint` reaches configurator users as a side-effect message on commit: set it when a transformer changes something they did not touch.\n\n- `DomainEntityModification({ entityId, stateDelta, updateTag })` — sets some of the entity's own fields, never `id` or `type`.\n- `DomainEntityCreation({ entity, parentId, updateTag })` — adds a complete entity, optionally to the reference component instance named by `collection`. Build it with `phx.domain.createRecipe({ type, … })`, which fills the spec defaults, and replace its placeholder id. For children from recipes, prefer `phx.frontend.useCookRecipes`, which assigns ids.\n- `DomainEntityReplacement({ entityId, replacementEntity, keepChildren, updateTag })` — swaps in a new entity with a new id; `keepChildren: false` deletes its composed children.\n- `EntityDeletion({ entityId, updateTag })` — removes an entity; built-in transformers delete its composed children and prune references to it.\n- `ComponentModification({ componentInstance, writableState, updateTag })` — writes a component's writable state, as built-in controls do; it throws for a state the component rejects.\n\n`phx.frontend.getIdSequence(entities, pendingUpdates)` returns `{ nextId(type) }`, above every existing id and every id created or replaced in `pendingUpdates`. Draw a batch's ids from one sequence: two sequences from one state return the same id. In a transformer, use the context's `getIdSequence()`.\n\n### Stage, commit and roll back\n\n- `storeSystem.stage(updates)` runs transformers and invariants against the committed state and previews a valid result in the rendered slice; an invalid stage previews nothing. Each call replaces the staged updates: stage the whole change from the committed state, never a delta.\n- `storeSystem.commit()` prepares the staged updates again, runs the `onBeforeCommit` hooks and commits a valid result. A rejected commit keeps the committed state, resets the preview and reaches configurator messages through the potentially invalid slice.\n- `storeSystem.rollback()` drops the staged updates and their preview.\n- `storeSystem.stageAndCommit(updates)` writes a discrete action in one step: a click, a toggle, an add.\n- `storeSystem.hasStagedUpdates` is `true` while a staged change is pending; a hover stages nothing. It is a getter, not a subscription: check it before snapshotting the committed state, such as for an export.\n- `storeSystem.onBeforeCommit((emission, emit) => …)` runs before every commit and returns its unregister function; register it in an effect. Returning `false` holds the commit, such as to confirm a destructive change: the preview rolls back, and `emit()` commits that emission later. The hooks run again then, so let it through.\n- Leave `storeSystem.commitPrepared` to the SDK's own operations.\n\n### Dry runs\n\n- `storeSystem.prepareStateEmission(updates, storeSystem.stateSlices.committed.value.state, 'committed')` returns the emission a commit would produce, `{ state, validity, updates, … }`, without emitting it. Controls dry-run every option this way ([Violations](violations.md)).\n- Transformers and invariants run in a dry run exactly as in a commit, with the kind `'committed'`, so a transformer cannot tell them apart: `onEmissionsOfKind(['committed'])` skips staged previews but not dry runs.\n- Every mounted control dry-runs each option after every commit: ten options run the transformer pipeline and every invariant ten times per change. Staging runs them on every frame of a gesture.\n- Keep transformers pure and cheap: no requests, storage, analytics or React state.\n\n### Undo steps\n\n- One commit that changes entities is one undo step, transformer updates included, so a transformer's repair undoes with the change that caused it.\n- A commit that changes only navigation, view, tool or selection state makes no step.\n- Staged frames make no steps, but `stageAndCommit` on every keystroke or slider tick makes one each: stage while the value changes and commit once, on release or blur. [Toolbar actions](../custom-layout/toolbar-actions.md) covers the undo and redo buttons.\n\n### Update guards\n\nNarrow updates in a transformer (`ctx.updates`, `overrideAllUpdates`) or in an `onBeforeCommit` emission:\n\n- `phx.frontend.isCreateEntityUpdate(update, types)`, `phx.frontend.isReplaceEntityUpdate(update, types)` and `phx.frontend.isDeleteEntityUpdate(update, types)` — an entity of `types` added or replaced from a recipe, or removed by a built-in delete control. They check the SDK's own tags, so your own `EntityDeletion` does not match.\n- `(update, types, instanceName)` guards — the write of one built-in control on one component instance: `phx.frontend.isAttributeSelectionUpdate`, `phx.frontend.isAttributeSwitchUpdate`, `phx.frontend.isTextValueUpdate`, `phx.frontend.isSwatchSelectionUpdate`, `phx.frontend.isGenericDimensionUpdate`, `phx.frontend.isDistanceDimensionUpdate`, `phx.frontend.isAngleDimensionUpdate`.\n- A built-in step at priority `Infinity` turns component writes into entity modifications. Transformers default to that priority and run after it, and `onBeforeCommit` sees its result, so the control guards never match there. Give such a transformer a finite `priority` in its `transformers:` entry, or filter with `when.entity([...]).modified({ atFields })`.",example:t,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/other-features/transformers.mdx` — the transformer guide, including a component trigger registered with a finite priority.\n- `docs/complex-use-cases/navigation-guard.mdx` — an `onBeforeCommit` hook that holds a commit until configurator users confirm.\n- `docs/phoenix/state-management.mdx` — the stage, commit and rollback cycle and the emission kinds.\n- `docs/phoenix/configurator-interface.mdx` — "Updates Factory" and "Update Type Guards": every factory member, a control that dry-runs its updates, and the guards.',phxMembers:["frontend.updates","frontend.getIdSequence","frontend.useDomain","frontend.isCreateEntityUpdate","frontend.isReplaceEntityUpdate","frontend.isDeleteEntityUpdate","frontend.isAngleDimensionUpdate","frontend.isDistanceDimensionUpdate","frontend.isGenericDimensionUpdate","frontend.isAttributeSelectionUpdate","frontend.isAttributeSwitchUpdate","frontend.isTextValueUpdate","frontend.isSwatchSelectionUpdate"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** How violations disable control options, become hint text and gate Next and Finalize at runtime. */
+export declare const generatePhoenixViolationsFeature: () => PhoenixGuide;