@salsita-ai/sdk 0.50.0-develop.bc08a38ffe → 0.50.0-develop.bc204720a8

package/dist/application-spec/generate-application/code/templates/skills/features/custom-layout/tabs-and-steps.js

@@ -0,0 +1,65 @@
+import{createPhoenixFeatureGuide as t}from"../../guide.js";let e=`A three-step wizard whose Next waits until the configuration is valid, and horizontal tabs for a layout that shows that kind only.
+
+\`\`\`yaml
+navigationStates: [size, finish, summary]
+
+components:
+  Desk:
+    navigationSteps:
+      main:
+        steps:
+          - label:
+              $msg: Size
+            navigationStates: [size]
+          - label:
+              $msg: Finish
+            navigationStates: [finish]
+          - label:
+              $msg: Summary
+            navigationStates: [summary]
+\`\`\`
+
+\`\`\`tsx
+// Part of a ConfiguratorLayout
+export const Wizard = () => {
+  const { steps, canGoNext, canGoPrevious, next, previous, goTo } = phx.frontend.useStepNavigation()
+  const { disabled: hasProblem, hints } = phx.frontend.useFinalizeViolations()
+
+  return (
+    <nav aria-label="Steps">
+      <ol>
+        {steps.map(step => (
+          <li key={step.state} aria-current={step.status === 'active' ? 'step' : undefined}>
+            {/* Earlier steps only: an upcoming step is reached with Next */}
+            <button type="button" disabled={step.status === 'upcoming'} onClick={() => goTo(step.index)}>
+              {step.index + 1}. {step.label}
+            </button>
+          </li>
+        ))}
+      </ol>
+      <button type="button" disabled={!canGoPrevious} onClick={previous}>
+        Back
+      </button>
+      {canGoNext && (
+        <button type="button" disabled={hasProblem} title={hints} onClick={next}>
+          Next
+        </button>
+      )}
+    </nav>
+  )
+}
+
+export const Tabs = () => {
+  const { tabs, select } = phx.frontend.useTabNavigation({ source: 'horizontalTabs' })
+
+  return (
+    <div role="tablist">
+      {tabs.map(tab => (
+        <button key={tab.state} type="button" role="tab" aria-selected={tab.isActive} onClick={() => select(tab.index)}>
+          {tab.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+\`\`\``;export const generatePhoenixTabsAndStepsFeature=()=>t({path:"features/custom-layout/tabs-and-steps.md",title:"Tabs and steps",summary:"Drawing tabs and a stepper from the spec's `sidebarTabs`, `horizontalTabs` and `navigationSteps`, and holding Next while the configuration has a problem; read when a project layout shows tabs, steps or a wizard.",whenToUse:"Read when a project layout renders its own tabs or steps. The structure stays in YAML, where `$filter` can switch it; the layout decides how it looks and whether Next waits for a valid configuration.",capabilities:"### Tabs\n\n- `phx.frontend.useTabNavigation(options?)` returns `{ source, tabs, activeTab, select }` for the spec's tabs.\n- Each tab is `{ index, label, icon, iconNode, navigationStates, state, isActive }`. `label` is resolved to the current language, `icon` is a PhxIcon name, and `iconNode` is a React node only when TypeScript spec code gives one.\n- `select(tab.index)` or `select(navigationState)` enters the tab's first navigation state; an unknown tab does nothing.\n- `source` is `'sidebarTabs'` (every active instance on the selected entity, the root while nothing is selected), `'horizontalTabs'` (the first active instance on any entity) or `null` without tabs.\n- `options.source` defaults to `'auto'`, which prefers `sidebarTabs` when both kinds are active and warns in development. Pass `'sidebarTabs'` or `'horizontalTabs'` when the layout shows one kind.\n- `options.entityId` reads another entity's `sidebarTabs`.\n- A tab without navigation states is left out, with a warning in development.\n\n### Steps\n\n- `phx.frontend.useStepNavigation()` returns `{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }` for the spec's `navigationSteps`.\n- It reads the first active `navigationSteps` instance on the root entity, so `$filter` can switch between several.\n- Each step is `{ index, label, navigationStates, state, status }`, with `status` `'complete'`, `'active'` or `'upcoming'`.\n- While the active navigation state belongs to no step, `activeStep` is `null`, `activeIndex` is -1, every step is `'upcoming'` and `next()` enters the first step.\n- `next()` and `previous()` read the committed state when called, so a double click never skips a step. `goTo(index or state)` enters any step.\n- Each action pushes the analytics event of the built-in control it replaces.\n\n### Order, validity and read mode\n\n- Tabs and steps enter navigation states, so controls, cameras and components filtered by `navigationStates` follow. [Navigation states](../application-states/navigation.md) owns declaring them.\n- Neither hook enforces an order or validity, and neither checks read mode.\n- For a stepper that offers only earlier steps, enable the steps whose `status` is `'complete'`.\n- A change with a `fixable` or `fatal` violation is never committed, so a `warning` is the problem that can stay. To hold Next while one does, require besides `canGoNext` either `!phx.frontend.useFinalizeViolations().disabled` or `phx.frontend.useStateValidity().severity !== 'warning'`.\n- Prefer `useFinalizeViolations()`: its `hints` tell users why Next waits, and it holds Next on the same rule as Finalize, a failed save included. `useStateValidity()` gives only the severity, for a gate that ignores saving.\n- [Violations](../state/violations.md) owns these semantics and gating on the violations of one step.\n- Switching tabs and steps is navigation, not editing: a viewer may use them. Hide the editing controls inside them instead ([View mode](view-mode.md)).",example:e,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/configurator-interface.mdx` — "Hooks for a Project Layout" and its "Steps and tabs" paragraph: both hooks and a wizard whose Next gates on `useStateValidity()`.\n- `docs/layouts/gallery/nightjar-guitar.mdx`, `docs/layouts/gallery/ardent-compressor.mdx` — complete layouts with their own steppers; `docs/layouts/gallery/corvid-drone.mdx` with its own tabs.\n- `docs/layouts/sidebar/tabs.mdx` — what `sidebarTabs` configures; its samples render the tabs in the built-in sidebar, so take only the YAML.',phxMembers:["frontend.useTabNavigation","frontend.useStepNavigation"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Undo, fullscreen, camera, toolbar, measurements, sharing, assistant and close actions for a project layout. */
+export declare const generatePhoenixToolbarActionsFeature: () => PhoenixGuide;

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;