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

package/dist/application-spec/generate-application/code/templates/skills/features/custom-layout/toolbar-actions.js

@@ -0,0 +1,58 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let n=`The spec's desktop toolbar drawn in the layout's own style, with the share entry opening the layout's dialog. Measurements, language and help would open the layout's own popovers; this toolbar leaves them out.
+
+\`\`\`tsx
+// Part of a ConfiguratorLayout
+interface ToolbarProps {
+  readonly onShare: () => void
+}
+
+export const Toolbar = ({ onShare }: ToolbarProps) => {
+  const { actions } = phx.frontend.useToolbarActions('desktop')
+
+  return (
+    <div role="toolbar" aria-label="Tools" style={{ display: 'flex', gap: 8 }}>
+      {actions.map(action => {
+        switch (action.kind) {
+          case 'undo':
+          case 'redo':
+            return (
+              <button key={action.key} type="button" disabled={action.disabled} onClick={action.run}>
+                {action.label}
+              </button>
+            )
+          case 'fullscreen':
+            return (
+              <button key={action.key} type="button" aria-pressed={action.active} onClick={action.run}>
+                {action.label}
+              </button>
+            )
+          case 'resetCamera':
+          case 'assistant':
+            return (
+              <button key={action.key} type="button" onClick={action.run}>
+                {action.label}
+              </button>
+            )
+          case 'share':
+            return (
+              <button key={action.key} type="button" onClick={onShare}>
+                {action.label}
+              </button>
+            )
+          case 'custom':
+            return <action.Element key={action.key} />
+          default:
+            return null
+        }
+      })}
+    </div>
+  )
+}
+
+export const ShareLinks = ({ open }: { readonly open: boolean }) => {
+  // Generating a link saves the configuration: only while the dialog is open
+  const { readLink, isLoading } = phx.frontend.useShareLinks({ enabled: open })
+
+  return open ? <p>{isLoading || readLink === null ? 'Preparing a link…' : readLink}</p> : null
+}
+\`\`\``;export const generatePhoenixToolbarActionsFeature=()=>e({path:"features/custom-layout/toolbar-actions.md",title:"Toolbar actions",summary:"Undo and redo, fullscreen, camera reset, the spec's toolbar as data, measurements, share links, the assistant panel and the host's close action; read when a project layout draws its own toolbar or any of these buttons.",whenToUse:"Read when a project layout offers configurator actions with its own buttons instead of mounting the built-in toolbar. The language switch belongs to [Localization](../localization.md).",capabilities:"### Choose the route\n\n- Mount `LayoutSlots.DesktopToolbar` when the built-in look fits; it keeps project elements registered under button kinds ([Layout slots](slots.md)).\n- Build from `phx.frontend.useToolbarActions()` when the spec's `toolbar` should decide which actions appear but the layout draws them.\n- Use the single-action hooks when the layout places actions itself, independent of the spec's `toolbar`.\n- The hooks act as the built-in buttons do, and the toolbar's actions push the same analytics events. None checks read mode.\n\n### The spec's toolbar as data\n\n- `phx.frontend.useToolbarActions(placement?)` takes `'desktop'` (the default), `'mobile'` or `'mobileMenu'`, the `toolbar` component's list of that name.\n- It returns `{ groups, actions }`: the spec's `toolbarButtonGroup`s, an element outside a group being a group of one, and the same entries flattened.\n- Every entry has `key`, `kind`, `label` (the built-in button's title, resolved), `icon` and `showTitle`. Switch on `kind` and TypeScript narrows the rest:\n  - `undo`, `redo` — `disabled` and `run`;\n  - `fullscreen` — `active` and `run`, which toggles the flag;\n  - `resetCamera` — `run`;\n  - `share` — nothing to run: open the layout's own dialog over `useShareLinks`;\n  - `measurements` — `measurements`, the result of `useMeasurements`, and `icons` per unit;\n  - `language` — `language`, the locale switch [Localization](../localization.md) describes;\n  - `help` — `Content`, a component that renders the help;\n  - `assistant` — `assistant`, the result of `useAssistantPanel`, and `run`;\n  - `custom` — `name` and `Element`, the project element a `customLayoutElement` names.\n- Entries with nothing to offer are left out: share with sharing disabled, language with one locale, an assistant the spec lacks.\n- Without a `toolbar` component it returns the default set, which drops share, undo and redo for a viewer. A configured `toolbar` is returned as written.\n- A project element registered under a button kind, such as `undoToolbarButton`, replaces that button in the built-in toolbar only, not here.\n\n### Single actions\n\n- **Undo and redo** — `phx.frontend.useUndoRedo()` returns `{ canUndo, canRedo, undo, redo }`. Disable each button from `canUndo` and `canRedo`.\n- **Fullscreen** — `phx.frontend.useIsFullscreenActive()` returns the flag and `phx.frontend.useSetFullscreen()` a setter `(enabled: boolean) => void`. The layout decides what fullscreen removes; keep the exit button where the enter button was.\n- **Camera reset** — `phx.frontend.useResetCamera()` returns `() => void`, which returns to the framing of the active camera after an orbit, pan or zoom.\n- **Measurements** — `phx.frontend.useMeasurements(options?)` returns `{ units, unit, setUnit, hasIndicatorSwitch, indicatorsShown, toggleIndicators, available }`. Offer it only while `available`; `options.showIndicatorSwitch` overrides `applicationConfig.indicatorSwitch`.\n- **Share dialog** — `phx.frontend.useShareLinks({ enabled })` returns `{ available, ownerLinkAvailable, readLinkAvailable, ownerLink, readLink, isLoading }`; each link is `null` until generated.\n- Generating a link saves the configuration, and while enabled every commit generates a new read link. Pass `enabled: isDialogOpen`.\n- **One link on demand** — `phx.frontend.useGenerateShareLink()` returns `async ({ access, expiration? }) => ({ link })`. `access` is `'o'` for an editable link or `'rr'` for the saved revision, read-only. It saves first, ignores `shareDisabled`, and suits a handler, such as a link in a quote.\n- **Assistant panel** — `phx.frontend.useAssistantPanel()` returns `{ available, open, hasUnreadReply, setOpen }`. The panel renders only inside the built-in sidebar, which a project layout leaves out ([Layout slots](slots.md)), so a project layout offers no assistant button.\n- **Assistant conversation** — a project element that shows the conversation or takes a message itself reads the panel's state: `phx.frontend.useAssistantThread()` returns the thread's `items` with its loading, reply and failure state, and `phx.frontend.useAssistantComposer()` the message being written with `setDraft`, `addFiles`, `send` and `stop`. They are separate so a composer does not render again with every chunk of a reply.\n- **Close** — `phx.frontend.useCloseAction()` returns the host's close action, `() => Promise<void>`, or `null` when the integration mode offers none. Show a close button only when it is not `null`.\n\n### Read mode and fullscreen\n\n- Hide undo, redo and other editing actions while `accessInfo.viewMode` is `true` ([View mode](view-mode.md)); fullscreen, camera reset and view switching stay.\n- In fullscreen keep the controls for looking at the product: exit, reset, views.\n- Components follow the flag through `$filter.fullscreen`.",example:n,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/configurator-interface.mdx` — "Hooks for a Project Layout", its toolbar table and "Mode, fullscreen, preview and navigation".\n- `docs/layouts/custom-layout.mdx` — the layout\'s own fullscreen toggle, undo and redo, and camera reset.\n- `docs/layouts/toolbar.mdx` — what the spec\'s `toolbar` configures.\n- `docs/phoenix/sharing.mdx` — access levels and what a share link opens.',phxMembers:["frontend.useUndoRedo","frontend.useIsFullscreenActive","frontend.useSetFullscreen","frontend.useResetCamera","frontend.useToolbarActions","frontend.useMeasurements","frontend.useShareLinks","frontend.useGenerateShareLink","frontend.useAssistantPanel","frontend.useAssistantThread","frontend.useAssistantComposer","frontend.useCloseAction"]});

package/dist/application-spec/generate-application/code/templates/skills/features/custom-layout/view-mode.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Read mode, clone to edit, the preview start screen, the configuration id and the session role. */
+export declare const generatePhoenixViewModeFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/custom-layout/view-mode.js

@@ -0,0 +1,41 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let o=`What a viewer sees in place of the editing panel, and the start screen while the preview is on. Both are parts of a \`ConfiguratorLayout\`.
+
+\`\`\`tsx
+import { type ReactNode, useState } from 'react'
+
+import { DesktopPreview, LayoutSlots, MobilePreview } from '@salsita-ai/sdk/configurator'
+
+export const ViewerBar = () => {
+  const { accessInfo } = phx.frontend.useAccessService()
+  const canClone = phx.frontend.useIsCloningAllowed()
+  const [isCloneOpen, setCloneOpen] = useState(false)
+
+  if (!accessInfo.viewMode) {
+    return null
+  }
+
+  return (
+    <div role="status">
+      View only
+      {canClone && (
+        <button type="button" onClick={() => setCloneOpen(true)}>
+          Edit a copy
+        </button>
+      )}
+      <LayoutSlots.CloneToEditDialog open={isCloneOpen} onClose={() => setCloneOpen(false)} />
+    </div>
+  )
+}
+
+// Over the canvas: the start screen while the preview is on, else the interface, which calls useSceneSafeArea
+export const StartOrInterface = ({ children }: { readonly children: ReactNode }) => {
+  const { isPreview } = phx.frontend.usePreview()
+  const isDesktop = phx.frontend.useActiveViewports()?.includes('desktop') ?? false
+
+  if (!isPreview) {
+    return <>{children}</>
+  }
+
+  return isDesktop ? <DesktopPreview /> : <MobilePreview />
+}
+\`\`\``;export const generatePhoenixViewModeFeature=()=>e({path:"features/custom-layout/view-mode.md",title:"View mode",summary:"Read mode for shared and read-only configurations, clone to edit, the preview start screen, the configuration id and the session role; read when a layout must behave differently for viewers, phone embeds or roles.",whenToUse:"Read when deciding what a viewer of a shared configuration may do, when offering to edit a copy, when a phone embed should start with a preview, or when the layout depends on the signed-in role. Every guide of [Custom project layout](index.md) relies on its read-mode rule.",capabilities:"### Read mode\n\n- `phx.frontend.useAccessService()` returns `{ configurationId, accessInfo }`.\n- `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, or while the host sets the web component's `readonly` property. Decide on `viewMode`, not on `accessInfo.access`, so both routes count.\n- The same `ConfiguratorLayout` renders read mode, and no hook enforces it: control hooks, setters, undo and redo, finalize actions and step navigation keep working for a viewer.\n- Hide or disable what changes the configuration: editing controls, undo and redo, add and delete actions, finalization.\n- Keep what only looks: orbit and zoom, view states, camera reset, fullscreen, and switching tabs and steps.\n- A read-only configuration never saves, so a viewer's change would be lost; hide editing anyway, so nothing suggests it counts.\n- Read mode also sets the spec's filter mode to `read`. A component filtered with `$filter.modes: [owner]` disappears wherever it renders; use it for scene controls, hotspots and finalize actions, which the built-in pieces keep showing to viewers otherwise. Leave control components unfiltered and hide their elements instead, since their hooks throw while filtered out.\n- How a project's own control behaves for viewers belongs to [Custom controls](../domain-controls/custom-controls.md).\n\n### Clone to edit\n\n- `phx.frontend.useIsCloningAllowed()` returns `true` when `applicationConfig.shareCloneToEdit` is set and the session's role may create configurations (`acl.canCreate`). It does not check read mode.\n- Offer \"Edit a copy\" only while `viewMode` and cloning is allowed: mount `LayoutSlots.DesktopReadonlyBanner` or `LayoutSlots.MobileReadonlyBanner`, or the layout's own button.\n- The own button opens `LayoutSlots.CloneToEditDialog`, with `open` and `onClose`, which creates the editable copy and opens it.\n\n### Preview start screen\n\n- `phx.frontend.usePreview()` returns `{ isPreview, isExpanded, isPreviewEnabled, isHidden, enter, leave }`.\n- The spec's top-level `preview` decides: `auto`, the default, shows the preview while the container is `mobile`; `always` shows it everywhere and `never` nowhere. `hide` shows no preview and hides the collapsed embed (`isHidden`) until it is expanded.\n- `alwaysExpand: true` acts only when users leave the preview: `enter()` then expands the embed on every width, not only on a phone.\n- `isPreview` stays `true` until `enter()`, which also expands the embedded configurator on a phone.\n- The built-in layout shows a start screen while `isPreview`; a `ConfiguratorLayout` must do it itself, or set `preview: never`. Otherwise it renders the full interface inside the collapsed embed.\n- Render `DesktopPreview` or `MobilePreview` from `@salsita-ai/sdk/configurator`, or the layout's own start screen with a button that calls `enter`.\n- The previews frame the scene themselves, so render the component that calls `phx.frontend.useSceneSafeArea()` only while `isPreview` is `false`.\n- A project preset screen keeps its own preview branch ([Project pages](pages.md)).\n\n### Configuration and role\n\n- `phx.frontend.useConfigurationId()` returns the open configuration's id, the same as `useAccessService().configurationId`. Use it in a handler, an analytics event or a support reference.\n- `phx.frontend.useSessionRole()` returns the session's role: `'anonymous'`, `'user'`, `'admin'` or `'superadmin'`, as authentication assigned it; Admin always reports `'admin'`. It throws before the session is loaded, so call it inside the layout.\n- The same roles drive `$filter.roles` and `acl.canCreate`. Prefer `$filter.roles` for components shown per role; use the hook for differences in the layout itself, such as a dealer price panel.\n- Sessions and roles come from the project's authentication, described in `docs/phoenix/sessions-and-access.mdx`.",example:o,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/configurator-interface.mdx` — "Loaded Configuration UI" on the preview start screen and "Mode, fullscreen, preview and navigation".\n- `docs/layouts/custom-layout.mdx` — "Serve read mode": both read routes and what the layout hides.\n- `docs/layouts/preview/auto.mdx`, `docs/layouts/preview/always-expand.mdx` — the preview modes, set with the top-level `preview` and `alwaysExpand` keys of a spec file.\n- `docs/layouts/gallery/kestrel-kettle.mdx` — a layout with its own phone start screen.\n- `docs/ux-guidelines/interaction-modes.mdx` — what view-only and fullscreen should offer.\n- `docs/phoenix/sharing.mdx` — access levels, shared links and revisions.',phxMembers:["frontend.useAccessService","frontend.useIsCloningAllowed","frontend.usePreview","frontend.useConfigurationId","frontend.useSessionRole"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Choosing and declaring the YAML control components by job, with their filters and violations. */
+export declare const generatePhoenixControlComponentsFeature: () => PhoenixGuide;

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

@@ -0,0 +1,24 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let n=`A desk with two control components: the frame colour as a choice and the width as a length. Nothing here renders; the element in [Custom controls](custom-controls.md) reads both by instance name.
+
+\`\`\`yaml
+# spec/controls.yaml
+components:
+  Desk:
+    attributeSelection:
+      frameColor:
+        value:
+          $bind: frameColor
+        options:
+          - label: Grey
+            value: Grey
+          - label: Black
+            value: Black
+    distanceDimension:
+      width:
+        min: 1200
+        max: 2000
+        value:
+          $bind: width
+\`\`\`
+
+The width is in millimetres, the default data unit, whatever unit the element displays. Neither component is filtered, so the hooks always find them; the layout hides the panel from viewers.`;export const generatePhoenixControlComponentsFeature=()=>e({path:"features/domain-controls/control-components.md",title:"Control components",summary:"Choosing the control component kind by job, declaring it in YAML with its instance name, bindings and props, filters, read mode and violations; read when adding or changing a control on an entity.",whenToUse:"Read when configurator users need to change the product: pick a value, pick, add, replace or remove a part, set a size or an angle, or enter a text. Declare the component here first; [Custom controls](custom-controls.md) renders it.",capabilities:"### What a control component is\n\n- A control component holds one control's value and options and binds them to the model. Declare it in YAML on an entity type or alias: `components: <Type>: <kind>: <instanceName>:`.\n- The instance name is the contract with the project's element: the element passes the entity id and that name to a control hook ([Control hooks](control-hooks.md)).\n- The component defines no UI. The project's element renders it ([Custom controls](custom-controls.md)); the project layout or an in-scene anchor decides where.\n- `$bind` the writable key to a field, and compute options, `min` or `max` with `$read` of an expression or `$eval`. [Components](../domain-model/components.md) owns bindings, `$eval` and `$filter`.\n\n### Pick a value\n\n- `attributeSelection` — `value` (writable) and `options`, each `{ value, label, description?, img? }`.\n- `materialSwatch` — `selectedSwatchKey` (writable) and `swatches`, a map from key to `{ swatchName, color, thumbnailUrl? }` with a six-digit hex `color`.\n- `attributeSwitch` — a boolean `value` (writable).\n- A `null` value shows no option as selected; picking one writes it, so a nullable field needs no special component.\n\n### Pick, add, replace or remove parts\n\n- `childEntitySelection` swaps a child for another type. `value` is `$read` of the current child's id (it is not writable), each option is `{ label, description?, img?, recipes }`, and `keepChildren: true` keeps the old child's composed children.\n- `childEntityRecipes` adds children: `recipes` lists `{ title, description?, thumbnailUrl?, recipes }`, usually from an expression whose inner `recipes` are fragments made with `phx.domain.createRecipe({ type, … })`; their ids are renumbered when added. `groupLabel` and `groupDescription` label the group in a grouped panel; `simpleRecipePanel` shows one flat list.\n- Set `collection: <Parent>.$<relation>` when the parent holds the child ids; omit it when the child holds its parent's id.\n- `replaceEntityRecipes` replaces the entity itself: `recipes` as above, each with exactly one root entity, and optional `keepChildren`.\n- Deleting needs no component: the element calls the deletion hook, and deleting removes the `composedOf: true` children too.\n- Each recipe is a dry run that runs every transformer and invariant ([Updates and dry runs](../state/updates.md)), so a long recipe list costs as many runs per change.\n\n### Set a size, an angle or a text\n\n- `distanceDimension` — a length: `value` (writable), `min` and `max` in the data unit (`distanceDataUnit` of `applicationConfig`, `mm` by default), optional `displayUnit` and `unitDisplayConfig`.\n- `distanceDimensionSelect` — a length from `options` of `{ value, description? }`; use it when only catalog sizes exist.\n- `genericDimension` — any other number: `value`, `unit` label, `min`, `max`, `decimalPlaces`.\n- `angleDimension` — `value`, optional `min`, `max`, `unit` (`degree` by default, or `radian`) and `decimalPlaces`.\n- `textValue` — a string `value`; limit it with an invariant, not in the component.\n- `colorValue` — a hex string `value`. No `phx.frontend` hook reads it; prefer `materialSwatch` when the palette is fixed.\n- The editable indicators of [Scene controls](scene-controls.md) target the same dimension components on the product.\n\n### Filters and read mode\n\n- A hook throws when its instance is missing, and a `$filter` that does not match removes the instance. So an element must not call the hook while the component is filtered out.\n- Leave control components unfiltered by mode. Hide the control from viewers in the element or the layout by branching on `phx.frontend.useAccessService().accessInfo.viewMode`; [View mode](../custom-layout/view-mode.md) owns read mode.\n- Filter a component by `navigationStates` or `active` only when the element mirrors the condition, such as a layout that renders it only in that step.\n\n### Violations\n\n- Every option is dry-run: one that would leave a `fatal` or `fixable` violation is disabled, with the violation's message as its hint. The value controls preview while dragging and roll back on release while they have errors.\n- The hooks' `fixableViolations` argument only hides those types from the hint; the option stays disabled. [Violations](../state/violations.md) owns the mapping and repair.",example:n,documentation:"Read each with `pnpm phoenix docs -r <path>`; `pnpm phoenix docs -l` lists the SDK documents. Their samples mount the components in YAML property pages: take only the component definitions.\n\n- `docs/phoenix/components.mdx` — bindings, `$eval` and filters.\n- `docs/controls/select-attribute/cardselect.mdx`, `docs/controls/select-attribute/swatchselect.mdx`, `docs/controls/select-child-entity/listselect.mdx`, `docs/controls/nullable-attributes.mdx` — the selection components and their options.\n- `docs/recipes-and-delete/simple.mdx`, `docs/recipes-and-delete/replace-dropdown.mdx`, `docs/recipes-and-delete/delete-entity.mdx` — recipes, replacing and deleting, with the dry-run behavior of their options.\n- `docs/dimensions/input-controls/distance-slider.mdx`, `docs/dimensions/selection-controls/list-selector.mdx`, `docs/dimensions/basic-concepts/dimension-data-unit.mdx` — the dimension components and the data unit their values use.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/domain-controls/control-hooks.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The control hooks by job: their arguments, return shapes and dry-run contract. */
+export declare const generatePhoenixControlHooksFeature: () => PhoenixGuide;

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

@@ -0,0 +1,44 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A toolbar for a selected base unit on the product, attached as \`htmlHotspot\` \`name: BaseToolbar\` with \`showWhen: [selected]\`. \`drawers\` is an \`attributeSelection\` instance on \`Base\`. A drawer layout or the removal that would break an invariant stays visible but disabled, with the reason as its tooltip.
+
+\`\`\`tsx
+// src/elements/BaseToolbar.tsx
+import { Button, Chip, Stack, Tooltip } from '@mui/material'
+
+const Toolbar = ({ base }: { readonly base: Base }) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const drawers = phx.frontend.useAttributeSelection(base.id, 'drawers')
+  const removal = phx.frontend.useDeletedEntity(base.id)
+
+  return (
+    // Keeps presses on the toolbar from reaching the scene
+    <Stack direction="row" spacing={1} onPointerDown={event => event.stopPropagation()}>
+      {drawers.options.map(option => (
+        <Tooltip key={String(option.value)} title={option.hint ?? ''}>
+          <span>
+            <Chip
+              label={resolve(option.title)}
+              color={option.value === drawers.value ? 'primary' : 'default'}
+              disabled={option.disabled}
+              onClick={option.onSelect}
+            />
+          </span>
+        </Tooltip>
+      ))}
+      <Tooltip title={removal.hints ?? ''}>
+        <span>
+          <Button disabled={removal.disabled} onClick={removal.remove}>
+            Remove
+          </Button>
+        </span>
+      </Tooltip>
+    </Stack>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixEntityElement('BaseToolbar', ({ entityId }) => {
+  // Narrow the untyped id to a Base before using the typed hooks
+  const base = phx.frontend.useCommittedState().entities.find(entity => entity.id === entityId)
+
+  return base?.type === 'Base' ? <Toolbar base={base} /> : <></>
+})
+\`\`\``;export const generatePhoenixControlHooksFeature=()=>e({path:"features/domain-controls/control-hooks.md",title:"Control hooks",summary:"The hooks of each control component, recipes and deletion, with arguments, return shapes and the dry-run contract; read when a custom element reads or writes a control.",whenToUse:"Read when a custom element reads or writes a control component: which hook serves which control, its arguments and return shape, and how it previews, commits and dry-runs. [Custom controls](custom-controls.md) covers where the element lives, how the layout mounts it and the write path for other changes.",capabilities:"### The contract\n\n- Call a hook with the entity's id and the instance name of its control component, plus optional `fixableViolations`, which only hides those violation types from hints. The single-instance hooks below throw when that entity has no such instance, a filtered-out one included.\n- Every option is dry-run in advance: `disabled` (or `error`) and `hint` follow [Violations](../state/violations.md), and the current option's `onSelect` does nothing. Each dry run runs every transformer and invariant ([Updates and dry runs](../state/updates.md)), so mount long option lists only while they are open.\n- Titles, descriptions and labels are localizable: resolve them with `phx.frontend.useResolveLocalizable()`.\n- The recipe and deletion hooks are typed with the project's entity ids: pass an id narrowed from the state, such as `base.id`, not an element's untyped `entityId`.\n\n### Pick a value\n\n- `phx.frontend.useAttributeSelection(entityId, name)` returns `{ value, options }`, each option `{ value, title, description, imageSrc, disabled, hint, onSelect }`: the spec's `label` and `img` arrive as `title` and `imageSrc`.\n- `phx.frontend.useSwatchSelection(entityId, name, [])`, whose third argument is required, returns `{ value, options }`, each `{ swatchKey, swatchName, color, thumbnailUrl, selected, disabled, hint, onClick }`.\n- `phx.frontend.useAttributeSwitch(entityId, name)` returns `{ state, onChange, disabled, hint }`: `state.value` is the boolean, and `onChange()` writes its opposite.\n- `phx.frontend.useChildEntitySelection(entityId, name)` returns `{ value, options }`, each `{ value, title, imageSrc, selected, error, hint, onSelect }`. `value` is the current child's id and `error` stands for `disabled`; it also throws when the current child is missing.\n- `phx.frontend.useDistanceDimensionSelection(entityId, name)` returns `{ value, valueWithUnit, unitLabel, options }`, each option `{ value, title, disabled, hint, onSelect }` with `title` formatted in the display unit.\n\n### Set a value continuously\n\n`phx.frontend.useDistanceDimension`, `phx.frontend.useGenericDimension`, `phx.frontend.useAngleDimension` and `phx.frontend.useTextValue` take `(entityId, name)` and return `{ value, hints, hasErrors, update, resolve }`, the numeric ones also `min` and `max`.\n\n- `update(value)` stages a preview that the scene renders; `resolve()` commits it, or rolls it back while it has errors. Call `update` on every change and `resolve` on release or blur, so a drag is one undo step.\n- Show `hints` when `hasErrors`. The numeric hooks always fill it, with the allowed range when nothing is wrong; `useTextValue` gives only the staged preview's hint, else `null`.\n- Distance: `value`, `min`, `max` and `update` use the display unit: the component's `displayUnit`, else the unit configurator users picked. `valueWithUnit`, `unitLabel`, `formatValue`, `parseValue` and `toDisplayUnit` format values and convert data-unit steps; `rollback()` drops the preview. `min` and `max` are `NaN` unless the component declares them.\n- Generic: `value`, `min` and `max` are rounded to the component's `decimalPlaces`, with its `unit` label. Angle: in the component's `unit`, degrees by default, with `unitLabel`.\n- Text: `update(event, text)` takes the text second, as MUI's `onChange` passes it.\n\n### Add, replace and delete\n\n- `phx.frontend.useGroupedRecipeOptions(entityId, instanceNames?)` returns one group per `childEntityRecipes` instance, `{ instanceName, label, description, recipes }`, each recipe `{ title, description, thumbnailUrl, disabled, tooltipTitle, handleClick }`. `phx.frontend.useReplaceEntityRecipeOptions(entityId, instanceNames?)` does the same for `replaceEntityRecipes`. Both return `[]` instead of throwing.\n- Recipes the element builds itself: `phx.frontend.useCookRecipes(parentId)` returns `cook(recipes, collection?)`, which returns `{ disabled, hints, create, recipes }`; `phx.frontend.useCookedRecipes(recipes, parentId, collection?)` cooks one memoized list. [Control components](control-components.md) explains `collection`.\n- Replace: `phx.frontend.useCookedReplaceRecipes(entityId, recipes, keepChildren?)` returns `{ disabled, hints, replace, recipes }` for one memoized list. `phx.frontend.useCookReplaceRecipes(entityId)` returns `cook(recipes, keepChildren?)` with the same result, for several lists.\n- Delete: `phx.frontend.useDeletedEntity(entityId)` returns `{ remove, disabled, hints }`; `phx.frontend.useDeleteEntity()` returns `(entityId) => { remove, disabled, hints }` for a list. Deleting removes the composed children too.",example:t,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- "Read and change the product" and "Put a control on the product" in `docs/layouts/custom-layout.mdx` — `useAttributeSelection` in a layout panel and in a hotspot.\n- `docs/controls/custom.mdx` — `useUpdatedControl` and `useCookedRecipes` in elements.\n- `docs/dimensions/input-controls/distance-slider.mdx`, `docs/dimensions/basic-concepts/dimension-unit-config.mdx` — the unit rules the distance hooks share.\n- "Controls" and "Recipes & Entity Creation" in `docs/phoenix/configurator-interface.mdx` — the main control, recipe and deletion hooks with a sample call each.',phxMembers:["frontend.useAttributeSelection","frontend.useSwatchSelection","frontend.useAttributeSwitch","frontend.useChildEntitySelection","frontend.useDistanceDimensionSelection","frontend.useDistanceDimension","frontend.useGenericDimension","frontend.useAngleDimension","frontend.useTextValue","frontend.useGroupedRecipeOptions","frontend.useReplaceEntityRecipeOptions","frontend.useCookRecipes","frontend.useCookedRecipes","frontend.useCookReplaceRecipes","frontend.useCookedReplaceRecipes","frontend.useDeletedEntity","frontend.useDeleteEntity"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Building the project's own control elements: where they live, how the layout mounts them, and the write path. */
+export declare const generatePhoenixCustomControlsFeature: () => PhoenixGuide;

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

@@ -0,0 +1,74 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A desk panel the layout shows while a desk is selected, over the two control components of [Control components](control-components.md). A frame colour or a width that would break an invariant is disabled or shows its message while dragging, and the width rolls back on release.
+
+\`\`\`yaml
+# spec/controls.yaml
+components:
+  Desk:
+    attributeSelection:
+      frameColor:
+        value:
+          $bind: frameColor
+        options:
+          - { label: Grey, value: Grey }
+          - { label: Black, value: Black }
+    distanceDimension:
+      width:
+        min: 1200
+        max: 2000
+        value:
+          $bind: width
+\`\`\`
+
+\`\`\`tsx
+// src/_shared/DeskControls.tsx
+import { Button, Slider, Stack, Tooltip, Typography } from '@mui/material'
+
+export const DeskControls = ({ deskId }: { readonly deskId: Desk['id'] }) => {
+  const resolve = phx.frontend.useResolveLocalizable()
+  const frame = phx.frontend.useAttributeSelection(deskId, 'frameColor')
+  // value, min and max are in the display unit, not the data unit
+  const width = phx.frontend.useDistanceDimension(deskId, 'width')
+
+  return (
+    <Stack spacing={2}>
+      <Stack direction="row" spacing={1}>
+        {frame.options.map(option => (
+          <Tooltip key={String(option.value)} title={option.hint ?? ''}>
+            <span>
+              <Button
+                variant={option.value === frame.value ? 'contained' : 'outlined'}
+                disabled={option.disabled}
+                onClick={option.onSelect}
+              >
+                {resolve(option.title)}
+              </Button>
+            </span>
+          </Tooltip>
+        ))}
+      </Stack>
+      <Typography>Width {width.valueWithUnit}</Typography>
+      <Slider
+        aria-label="Width"
+        min={width.min}
+        max={width.max}
+        value={width.value}
+        onChange={(_event, value) => typeof value === 'number' && width.update(value)}
+        onChangeCommitted={() => width.resolve()}
+      />
+      {width.hasErrors && <Typography color="error">{width.hints}</Typography>}
+    </Stack>
+  )
+}
+\`\`\`
+
+\`\`\`tsx
+// In src/elements/ConfiguratorLayout.tsx, inside the layout's own panel
+import { DeskControls } from '../_shared/DeskControls.js'
+
+const DeskPanel = () => {
+  const deskId = phx.frontend.useSelectedEntityId(phx.domain.enhancedModel.$Desk)
+  const { accessInfo } = phx.frontend.useAccessService()
+
+  return deskId !== null && !accessInfo.viewMode ? <DeskControls deskId={deskId} /> : null
+}
+\`\`\``;export const generatePhoenixCustomControlsFeature=()=>e({path:"features/domain-controls/custom-controls.md",title:"Custom controls",summary:"The project's own React element per control: where the file lives, registering spec-named elements, mounting it for the selected entity, read mode and the write path; read when rendering a control component.",whenToUse:"Read when a control component needs its UI: a panel in the project layout, a control next to a part on the product, or a change no single control component makes. [Control hooks](control-hooks.md) lists the hooks by job; [Updates and dry runs](../state/updates.md) covers writing the store directly.",capabilities:"### One element per control\n\n- Render each control component with the project's own React element, built from its control hook ([Control hooks](control-hooks.md)): `phx.frontend.useAttributeSelection(entityId, 'frameColor')` for an `attributeSelection` instance named `frameColor`, and so on.\n- Take a typed entity id as a prop, such as `Desk['id']`. Entity types are global in a project, like `phx`.\n- Group the elements of one entity type in a panel component when the layout shows them together.\n\n### Where the file lives\n\n- **Rendered by the layout** — a plain component in an underscore folder, such as `src/_shared/DeskControls.tsx`, with a named export. The layout imports it with a relative `.js` path. It needs no registration: the control hooks work anywhere inside the `ConfiguratorLayout`.\n- **Named by the spec** — an element that an `htmlHotspot`, `sceneEntityObjectHtmlHotspot` or `sceneEntityControl` names ([Scene controls](scene-controls.md)). Default-export `phx.frontend.createCustomPhoenixEntityElement('Name', ({ entityId }) => …)` from `src/elements/`; a file may export an array of registrations instead. It must return an element, `<></>` for nothing.\n- Every file in `src/elements/` outside an underscore folder must default-export a registration, so keep plain components out of it. An unregistered name in the spec renders a red \"not found\" box.\n- A spec-named element receives only `entityId`, untyped: find the entity in `phx.frontend.useCommittedState().entities` and narrow it by `type` before reading fields or calling the typed hooks. An element registered under a built-in kind name, such as the FAB factories of [Scene controls](scene-controls.md), also receives that kind's YAML props.\n\n### Mount it from the layout\n\n- Read the selected entity with `phx.frontend.useSelectedEntityId(phx.domain.enhancedModel.$Desk)`: the id while a desk is selected, else `null`. With nothing selected the root counts as selected.\n- `phx.frontend.useRootEntityId()` gives the root's id for controls that always show.\n- Render the panel only for an id of the right type, and only while `phx.frontend.useAccessService().accessInfo.viewMode` is `false`: no hook enforces read mode.\n- Mirror any `$filter` of the control component in the same condition, since the hook throws while its instance is filtered out ([Control components](control-components.md)).\n- [Scene and safe area](../custom-layout/scene-and-safe-area.md) has the layout skeleton with such a panel.\n\n### Write anything else\n\nWhen no control hook fits, such as a change to several fields or entities, build the updates with `phx.frontend.updates` ([Updates and dry runs](../state/updates.md)) and let a hook dry-run them:\n\n- `phx.frontend.useUpdatedControl(updates)` returns `{ disabled, hints, update }` for one update list. Memoize the list: every new array is a new dry run.\n- `phx.frontend.useUpdateControl()` returns `prepare(updates)`, which returns the same for each candidate, such as one per button.\n- `update()` stages and commits in one step, one undo entry; `disabled` and `hints` follow [Violations](../state/violations.md). Both hooks take `fixableViolations`, which only hides those types from `hints`.\n- Run a domain action the same way: `prepare(phx.frontend.useDomain().actionSystem.prepareAction(name, args, state).updates)`, with `state` from `phx.frontend.useCommittedState()`. `prepareAction` throws on arguments it rejects, so catch it and show its message; [Actions](../domain-model/actions.md) owns them.\n\n```tsx\nconst control = prepare([\n  phx.frontend.updates.DomainEntityModification({\n    entityId: deskId,\n    stateDelta: { width: 1800, depth: 800 },\n    updateTag: 'desk.sizePreset',\n  }),\n])\n// <Button disabled={control.disabled} title={control.hints} onClick={control.update}>Large</Button>\n```\n\n### Look native\n\nThe project's element is the default. Inside it, the SDK's control components from `@salsita-ai/sdk/react`, such as `AttributeCardSelector` with `entityId` and `instanceName`, can render one control in the SDK's look, and `PropertyContainer` from `@salsita-ai/sdk/ui` gives section spacing and headings. None of these is on `phx`.",example:t,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/layouts/custom-layout.mdx` — "Read and change the product" (a control in the layout\'s panel, from `src/_shared/`) and "Put a control on the product" (a hotspot element).\n- `docs/controls/custom.mdx` — `useUpdatedControl` and `useCookedRecipes` in elements; skip its property-page attachment.\n- `docs/other-features/domain-actions.mdx` — "Run it from the UI": an action behind `useUpdateControl`.\n- "Updates Factory" in `docs/phoenix/configurator-interface.mdx` — `useUpdatedControl` and `useUpdateControl` with a worked element.',phxMembers:["frontend.createCustomPhoenixEntityElement","frontend.useUpdateControl","frontend.useUpdatedControl"]});

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

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

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

@@ -0,0 +1,8 @@
+import{createPhoenixIndexGuide as o}from"../../guide.js";import{generatePhoenixControlComponentsFeature as t}from"./control-components.js";import{generatePhoenixControlHooksFeature as e}from"./control-hooks.js";import{generatePhoenixCustomControlsFeature as n}from"./custom-controls.js";import{generatePhoenixSceneControlsFeature as s}from"./scene-controls.js";let r=`Domain controls let configurator users change the product. Each control has two halves:
+
+- A **control component** in YAML, such as \`attributeSelection\` or \`distanceDimension\`, attached to an entity under an instance name. It binds the value and its options to the model and defines no UI.
+- The project's own **React element**, which renders that component with a control hook. The project layout mounts it, such as in a panel for the selected entity, or the spec anchors it on the product.
+
+Every control dry-runs its options, so one that would break the configuration is disabled with the reason. The spec does not describe the page: the layout around the controls, its tabs, steps and messages, belongs to [Custom project layout](../custom-layout/index.md).
+
+Declare the component in Control components, build its element in Custom controls with the hooks of Control hooks, and use Scene controls for anchors, FABs and indicators on the product.`;export const generatePhoenixDomainControlsGuides=()=>{let c=[t(),n(),e(),s()];return[o({path:"features/domain-controls/index.md",title:"Domain controls",summary:"Controls that change the product: YAML control components, the project's React elements and their hooks, and in-scene controls; read when adding or changing how configurator users edit the product.",intro:r,guides:c,notes:[]}),...c]};

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

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

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

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

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** In-scene controls: hotspots, FABs, dimension indicators and 3D entity controls, and replacing the built-in look. */
+export declare const generatePhoenixSceneControlsFeature: () => PhoenixGuide;

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 and the registered systems for this browser application slot (`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: `.phoenix/phoenix-dev.log` shows `Missing actions: <names>`, and the editor (`--editor`) the `MISSING_ACTION_IMPLEMENTATIONS` diagnostic; implementing an undeclared name is a type error. Nothing validates what `readResult` returns at runtime.\n- Actions currently execute in the browser, including assistant custom mutations. Built-in extensions such as `ctx.systems.sketchingSystem` are optional: check the value before using it and throw a clear message when the slot does not provide it. For a custom system, check its name with `in` and narrow its value with a local type guard.\n- Action modules are also loaded by the webhook's shared domain assembly. Keep their runtime imports server-safe, including transitive helper imports; browser SDK entry points and browser-only initialization can break the webhook. Type-only browser imports are safe. Use structural guards for registered systems rather than importing a browser class for an `instanceof` check. [Webhook entry](../webhooks/entry-and-environment.md) describes the loading boundary.\n- Read sketching projections from the supplied `state` and call `getLineLengthUpdates`, `getRectangleWidthUpdates`, `getRectangleDepthUpdates`, `getConnectionAngleUpdate` or `getMoveSketchingPointUpdates`. Do not use methods that read committed state, such as `prepareInitialDrawingUpdates`. Never stage, commit, roll back, or change drawing/camera state in an action: assistant operations can use a hypothetical working state.\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- The generated `useDomain()` checks action names and arguments and preserves each action result type.\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 n=`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'`; [Webhook entry and environment](../webhooks/entry-and-environment.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:n,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;