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

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Selection and hover: what they drive, making entities selectable, their hooks, selection rules and highlight. */
+export declare const generatePhoenixSelectionFeature: () => PhoenixGuide;

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

@@ -0,0 +1,35 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`Cabinets are selectable in the scene while configuring, and the project layout shows an inspector for the selected cabinet. Assume a \`Cabinet\` with a numeric \`width\`, composed into a \`Wall\`.
+
+\`\`\`yaml
+# spec/domain/cabinet.yaml
+components:
+  Cabinet:
+    selectable:
+      main:
+        $filter:
+          navigationStates: [configure]
+\`\`\`
+
+\`\`\`tsx
+// src/_shared/CabinetInspector.tsx, part of the project layout
+import { Button, Typography } from '@mui/material'
+
+export const CabinetInspector = () => {
+  const selectedId = phx.frontend.useSelectedDomainEntityId()
+  const cabinet = phx.frontend.useSelectedEntity(phx.domain.enhancedModel.$Cabinet)
+  const selectWall = phx.frontend.useSelectParent(selectedId)
+  const deselect = phx.frontend.useDeselect()
+
+  if (cabinet === null) {
+    return <Typography>Pick a cabinet in the scene to change it.</Typography>
+  }
+
+  return (
+    <>
+      <Typography variant="h6">Cabinet, {cabinet.width} mm</Typography>
+      <Button onClick={selectWall}>Select its wall</Button>
+      <Button onClick={deselect}>Done</Button>
+    </>
+  )
+}
+\`\`\``;export const generatePhoenixSelectionFeature=()=>e({path:"features/application-states/selection.md",title:"Selection and hover",summary:"What selection and hover drive, making entities selectable, the selection and hover hooks, selection rules and highlight; read when users pick parts in the scene or a list, or the UI, camera or highlight should follow the pick.",whenToUse:"Read when users should pick parts of the product, in the scene, from hotspots or from a list, and the controls, filters, camera or highlight should follow the pick.",capabilities:"### What selection drives\n\n- One entity is always selected: \"nothing selected\" means the root entity. A configuration opens with the root selected, and deselecting selects the root again.\n- A project layout reads the selection itself and renders the controls of the selected entity.\n- Filters: `selectedEntityIds` and `hoveredEntityIds` gate components, for example `selectedEntityIds: { $read: id }` for \"while this entity is selected\". Selection hotspots hide once their entity is selected (`showWhen`). A `fitSelectionPerspectiveCamera` or `fitSelectionOrthographicCamera` is active only while its entity is selected.\n- Highlight: by default the scene sets the selected entity, with its composed children, apart and marks the hovered one.\n\n### Make entities selectable\n\n- **In the scene** — add `selectable` to the entity type (`selectable: { main: {} }`). Clicking its geometry selects it; clicking empty canvas deselects. `hoverable: false` keeps the click without hover. Filter it like any component to allow picking only in some states.\n- **Small, hidden or grouped parts** — selection hotspots (`sceneEntitySelectHotspot`): [Scene controls](../domain-controls/scene-controls.md).\n- **From the UI** — a list, an outline or a \"next part\" button calls `phx.frontend.useSelectEntity()`.\n- Phoenix's auto-selection transformer (priority 100) selects a created entity, follows a replaced selection to its replacement and deselects a deleted one. A project transformer with the default priority runs after it.\n\n### Read and change the selection\n\n- `phx.frontend.useSelectedDomainEntityId()` returns the selected id: the root id when nothing is selected.\n- `phx.frontend.useSelectedEntityId(reflection)` returns the id while the selected entity has that type, else `null`; without a reflection it is always `null`.\n- `phx.frontend.useSelectedEntity(reflection)` returns the selected entity with its expressions, or `null` for another type. Pass the enhanced reflection, such as `phx.domain.enhancedModel.$Cabinet`.\n- `phx.frontend.useSelectEntity()` returns `(id) => void`; `phx.frontend.useDeselect()` returns `() => void`, which selects the root.\n- `phx.frontend.useSelectParent(id, fallback?)` returns `() => void`: select the composition parent of `id`, else `fallback`, else nothing.\n- Each call commits immediately, so transformers run on it.\n\n### Hover\n\n- `phx.frontend.useHoveredDomainEntityId()` returns the hovered id, or `null` while nothing is hovered.\n- `phx.frontend.useHoveredEntityId(reflection)` and `phx.frontend.useHoveredEntity(reflection)` narrow by type like their selection twins.\n- In the scene only `selectable` entities report hover. Hover is debounced and never committed: use it for labels and emphasis, not for changes.\n\n### Selection rules\n\n- Write them with `phx.frontend.transformerBuilder` (triggers, registration and order in [Transformers](../domain-model/transformers.md)):\n  - open a stage when a part is picked: `when.entity(['Door']).selected().then.navigateTo(state)`;\n  - step up the hierarchy on a click into empty canvas: `when.entity(['Console']).deselected({ inFavorOf: ['Room'] }).then.select.ancestorOfType(['ConsoleGroup'])`, with `Room` the root type;\n  - deselect on a second click: `when.entity(['Console']).selected({ occurrence: 'repeated' }).then.deselect()`.\n- For drill-down, filter the children's `selectable` or hotspots with `selectedEntityIds` read from an expression that lists their parent, so they become pickable once the parent is selected.\n\n### Highlight\n\n- One `canvasConfig` component configures it: `highlightingDisabled: true` turns the built-in highlight off, `enableFastHighlight: true` swaps it for a cheaper emissive one. `highlightingDisabled: true` on an object of `sceneEntityObjectProperties` exempts that object.\n- Outlines: turn the built-in highlight off, name an element in `canvasCustomEnvironment`, register it with `phx.frontend.createCustomPhoenixLayoutElement`, and render `SelectionOutline` and `HoverOutline` inside `Postprocessing` there, all three from `@salsita-ai/sdk/configurator`.\n- An effect of your own: `phx.frontend.useUpdateEntityObjectSelection(filter, selection)` keeps a postprocessing selection (any object with `set(objects)`) filled with the 3D objects of `filter.entityIds` and empties it on unmount. The other filter flags (`entityRoots`, `entityObjects`, `descendantEntities`, `recursiveObjects`, `objectInstanceNames`) choose which objects. It needs the canvas context, so call it only inside the canvas, such as in that environment element.",example:t,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/selection-and-highlight/canvas.mdx`, `docs/selection-and-highlight/hotspots.mdx`, `docs/selection-and-highlight/group-highlighting.mdx` — `selectable`, selection hotspots and composed groups.\n- `docs/other-features/transformers.mdx` — the selection rules above with working examples; `docs/selection-and-highlight/hierarchy.mdx` — a selection hierarchy built from them.\n- `docs/selection-and-highlight/disable-highlight.mdx`, `docs/selection-and-highlight/disable-highlight-per-object.mdx`, `docs/selection-and-highlight/fast-emissive-highlight.mdx` — the built-in highlight.\n- `docs/selection-and-highlight/effects/outline.mdx`, `docs/selection-and-highlight/effects/overlay.mdx` — outline and overlay effects. Their Usage snippet passes the canvas settings to `buildConfig`; in a project use `canvasConfig` and `canvasCustomEnvironment` as above and as their Complete Implementation does.\n- `docs/3d-scene/cameras/fit-selection.mdx` — framing the selected entity.\n- `docs/phoenix/configurator-interface.mdx` — "Selection & Hover": the selection and hover hooks with a sample call each.',phxMembers:["frontend.useSelectedEntity","frontend.useSelectedEntityId","frontend.useSelectedDomainEntityId","frontend.useSelectEntity","frontend.useDeselect","frontend.useSelectParent","frontend.useHoveredEntity","frontend.useHoveredEntityId","frontend.useHoveredDomainEntityId","frontend.useUpdateEntityObjectSelection"]});

package/dist/application-spec/generate-application/code/templates/skills/features/application-states/views-and-tools.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** View states for how the scene is shown and tool states for interaction modes, and how each is switched. */
+export declare const generatePhoenixViewsAndToolsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/application-states/views-and-tools.js

@@ -0,0 +1,61 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A table with a close-up view and a dimensions tool: the toolbar switches tools, a camera keyed to the view frames the edge, and the length options exist only in the dimensions tool. \`Table\` is the root entity type.
+
+\`\`\`yaml
+# spec/application.yaml
+viewStates: [overview, edge]
+toolStates: [Default, Dimensions]
+\`\`\`
+
+\`\`\`yaml
+# spec/domain/table.yaml
+components:
+  Table:
+    toolControls:
+      main:
+        items:
+          - { label: Finish, value: Default, icon: Palette }
+          - { label: Dimensions, value: Dimensions, icon: SlidersHorizontal }
+    fitRootPerspectiveCamera:
+      main:
+        priority: 1
+        distance: 5000
+      edge:
+        priority: 2
+        distance: 2000
+        azimuthAngle: 0.5
+        $filter:
+          viewStates: [edge]
+    distanceDimensionSelect:
+      length:
+        $filter:
+          toolStates: [Dimensions]
+        value:
+          $bind: length
+        options:
+          - value: 1600
+          - value: 2000
+\`\`\`
+
+The project layout draws its own view switch:
+
+\`\`\`tsx
+// src/_shared/ViewSwitch.tsx
+import { Button } from '@mui/material'
+
+const LABELS = { overview: 'Whole table', edge: 'Edge close-up' } as const satisfies Record<ViewState, string>
+
+export const ViewSwitch = () => {
+  const activeView = phx.frontend.useActiveViewState()
+  const setViewState = phx.frontend.useSetViewState()
+
+  return (
+    <>
+      {phx.applicationTypes.ViewState.values().map(view => (
+        <Button key={view} aria-pressed={view === activeView} onClick={() => setViewState(view)}>
+          {LABELS[view]}
+        </Button>
+      ))}
+    </>
+  )
+}
+\`\`\``;export const generatePhoenixViewsAndToolsFeature=()=>e({path:"features/application-states/views-and-tools.md",title:"View and tool states",summary:"View states for how the scene is shown, tool states for interaction modes, switching each and the cameras and filters keyed to them; read when adding camera views, scene presentations or modes such as dimensions, sketching or focus.",whenToUse:"Read when users switch how the scene is shown (a front or top view, a close-up, a room style) or which mode it is in (dimensions, sketching, editing one part), independently of the stage of the flow.",capabilities:"### Choose the kind of state\n\n- **Navigation state** — where users are in the flow; it changes controls and pages: [Navigation states](navigation.md).\n- **View state** — how the scene is presented: a camera, an environment, a close-up. The controls stay as they are.\n- **Tool state** — what users are doing in the scene: setting dimensions, sketching, a focus mode for editing one part. It swaps the in-scene controls.\n- The three lists are independent: one value of each is active, and a filter can combine them. A tool state does not change the selection, nor the selection the tool.\n\n### Declare them\n\n- `viewStates:` and `toolStates:` follow the rules of navigation states: identifier values, each list in one file, the first value active when a configuration opens, a single `Default` when undeclared.\n- `phx.applicationTypes.ViewState` and `phx.applicationTypes.ToolState` are their runtime enums (`ToolState.Dimensions === 'Dimensions'`, `.values()`, `.is(value)`); the global types `ViewState` and `ToolState` are the unions.\n\n### Switch the view\n\n- `phx.frontend.useActiveViewState()` returns the active view; `phx.frontend.useSetViewState()` returns `(state) => void`, which commits immediately.\n- Built-in switch: a `viewControls` component on the root entity, `items: [{ label, value, icon }]` with a view state as `value` and a PhxIcon name as `icon`. The built-in layout shows the first one. A project layout mounts `LayoutSlots.DesktopViewControls` or `MobileViewControls` ([Layout slots](../custom-layout/slots.md)), or draws its own buttons with the two hooks, which need no component.\n- Cameras: filter camera components with `viewStates`. Of the cameras whose filters pass, the highest `priority` (default 1) wins, so keep an unfiltered camera with the lowest priority as the default.\n- Transformers: `when.viewChanged({ from, to })` reacts to a switch, and `.then.changeView(state)` switches as a side effect.\n\n### Switch the tool\n\n- `phx.frontend.useActiveToolState()` returns the active tool. No hook sets it; switch tools with:\n  - a `toolControls` component on the root entity (`items: [{ label, value, icon }]`, `value` a tool state), shown by the built-in layout, or by `LayoutSlots.DesktopToolControls` and `MobileToolControls` in a project layout;\n  - the tool menu `toolMenuFab` in the scene ([Scene controls](../domain-controls/scene-controls.md)) and the exit button `exitToolModeFab` with `exitTo` in the call-to-action slot ([Layout slots](../custom-layout/slots.md));\n  - own UI: take `storeSystem` and `navigationSystem` from `phx.frontend.useDomain()` and call `storeSystem.stageAndCommit([navigationSystem.getToolUpdate(phx.applicationTypes.ToolState.Dimensions)])`, as the SDK's own controls do.\n- Filter each tool's controls with `toolStates`, and give the default tool controls of its own, so every mode offers something to do. A focus mode also hides navigation, tool and view controls and offers a labeled exit.\n- `when.toolChanged({ from, to })` reacts to a switch; the transformer builder has no action that changes the tool.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/application-states.mdx`, sections View States and Tool States — the declarations, filters, `viewControls` and `toolControls`.\n- `docs/layouts/view-controls.mdx` — one camera per view and the built-in view switch.\n- `docs/complex-use-cases/focus-mode.mdx` — a tool state entered from `toolMenuFab` and left with `exitToolModeFab`.\n- `docs/complex-use-cases/sketching.mdx` — tool states switching between drawing and selecting.\n- `docs/ux-guidelines/interaction-modes.mdx` — what each mode shows and hides.\n- `docs/phoenix/layout-slots.mdx` — the view and tool control slots.",phxMembers:["applicationTypes.ViewState","applicationTypes.ToolState","frontend.useActiveViewState","frontend.useSetViewState","frontend.useActiveToolState"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The custom project layout index followed by its guides: one per page-level feature of a project layout. */
+export declare const generatePhoenixCustomLayoutGuides: () => readonly PhoenixGuide[];

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

@@ -0,0 +1,7 @@
+import{createPhoenixIndexGuide as e}from"../../guide.js";import{generatePhoenixFinalizationActionsFeature as o}from"./finalization-actions.js";import{generatePhoenixMessagesFeature as t}from"./messages.js";import{generatePhoenixProjectPagesFeature as s}from"./pages.js";import{generatePhoenixSceneAndSafeAreaFeature as a}from"./scene-and-safe-area.js";import{generatePhoenixLayoutSlotsFeature as r}from"./slots.js";import{generatePhoenixTabsAndStepsFeature as n}from"./tabs-and-steps.js";import{generatePhoenixToolbarActionsFeature as i}from"./toolbar-actions.js";import{generatePhoenixViewModeFeature as d}from"./view-mode.js";let l=`A layout element registered as \`ConfiguratorLayout\` replaces everything Phoenix renders for a loaded configuration, in owner and in read mode, finalization included. It shows only what it composes.
+
+- YAML keeps the domain and the structure the layout reads: control components, in-scene anchors, tabs, steps, toolbar entries and finalize actions. The layout reads them through \`phx.frontend\` hooks, or mounts a built-in slot that reads them.
+- The spec does not describe the page: the layout draws its own panels and renders the project's control elements in them.
+- Start every layout from the skeleton in [Scene and safe area](scene-and-safe-area.md), then read only the guides for the features it offers.
+- Each feature is either a built-in slot ([Layout slots](slots.md)) or the layout's own UI over hooks, which the other guides cover. No hook enforces read mode, so [View mode](view-mode.md) applies to all of them.
+- The controls inside the layout's panels and on the product, their YAML components and React elements, belong to [Domain controls](../domain-controls/index.md).`;export const generatePhoenixCustomLayoutGuides=()=>{let m=[a(),r(),n(),i(),t(),o(),d(),s()];return[e({path:"features/custom-layout/index.md",title:"Custom project layout",summary:"The project's page-level UI: the `ConfiguratorLayout` element with its canvas, built-in slots, tabs and steps, toolbar, messages, finalization and read mode, and the preset screen, loader and error pages; read when creating or changing a project layout or one of these pages.",intro:l,guides:m,notes:[]}),...m]};

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The spec's `finalizeAction` components in a project layout: handlers, rendering, pending and error states. */
+export declare const generatePhoenixFinalizationActionsFeature: () => PhoenixGuide;

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

@@ -0,0 +1,79 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let n=`A secondary action that copies a read-only link next to the primary quote, both rendered by the layout and hidden for viewers.
+
+\`\`\`yaml
+components:
+  Desk:
+    finalizeAction:
+      quote:
+        variant: primary
+        label:
+          $msg: Request a quote
+        title:
+          $msg: Send the configuration to the shop
+        icon: PaperPlaneTilt
+        handler: requestQuote
+      link:
+        variant: secondary
+        label:
+          $msg: Copy a link
+        title:
+          $msg: Copy a read-only link to this configuration
+        icon: CopySimpleBold
+        handler: copyLink
+\`\`\`
+
+\`\`\`ts
+// src/handlers/copy-link.ts
+import { useCallback } from 'react'
+
+export default phx.frontend.createPhoenixHandler('copyLink', () => {
+  // The factory runs as a hook beside the layout: call hooks here, not inside \`handler\`
+  const generateShareLink = phx.frontend.useGenerateShareLink()
+
+  return {
+    handler: useCallback(async () => {
+      // Saves first; a rejection becomes the action's \`error\`
+      const { link } = await generateShareLink({ access: 'rr' })
+      await navigator.clipboard.writeText(link)
+    }, [generateShareLink]),
+  }
+})
+\`\`\`
+
+\`\`\`tsx
+// Part of a ConfiguratorLayout
+export const Finalize = () => {
+  const { accessInfo } = phx.frontend.useAccessService()
+  const { primary, secondary, hints } = phx.frontend.useFinalizeActions()
+
+  if (accessInfo.viewMode || primary === null) {
+    return null
+  }
+
+  const actions = [primary, ...secondary]
+  const failed = actions.find(action => action.error !== null)
+
+  return (
+    <div>
+      {actions.map(action => (
+        <button
+          key={action.key}
+          type="button"
+          title={action.disabled ? hints : action.title}
+          disabled={action.disabled || action.isPending}
+          onClick={() => void action.run()}
+        >
+          {action.isPending ? 'Working…' : action.label}
+        </button>
+      ))}
+      {failed?.error && (
+        <p role="alert">
+          {failed.label}: {failed.error.message}
+        </p>
+      )}
+    </div>
+  )
+}
+\`\`\`
+
+\`requestQuote\` is registered the same way; the quote's server side follows the finalization process.`;export const generatePhoenixFinalizationActionsFeature=()=>e({path:"features/custom-layout/finalization-actions.md",title:"Finalization actions",summary:"The spec's `finalizeAction` components with their handlers, rendered by the layout with pending, error and disabled states, and hidden for viewers; read when a project layout offers quote, order, PDF, email, save or share buttons.",whenToUse:"Read when a project layout offers the buttons that complete a configuration, or when such a button does nothing, stays disabled or fails silently. [Finalization](../../processes/finalization.md) owns agreeing what completing means and the server side.",capabilities:"### Declare an action and its handler\n\n- Declare each completion as a `finalizeAction` component on the root entity, with `variant` (`primary` or `secondary`), `label`, `title`, `icon` (a PhxIcon name) and `handler`, all required.\n- Register the handler in a `src/handlers/` file as its default export, one or an array: `phx.frontend.createPhoenixHandler(name, () => ({ handler }))`.\n- The factory is a hook. Call hooks in it and return `{ handler }`, an async function without arguments wrapped in `useCallback`.\n- The YAML `handler` must equal the registered name. An unknown name only logs \"PhoenixHandler … not found\" to the console and resolves, so the button seems to do nothing.\n- Throw or reject to report a failure; the action's `error` then holds it.\n- A handler that finalizes on the server calls `finalize` and `waitForFinalizationToComplete` of `phx.frontend.useAuthorizedClient()`; [Finalization](../../processes/finalization.md) owns that side and the agreed journey.\n- `finalizePage` and `finalizeButton` are legacy, declared only in TypeScript; do not use them.\n\n### Render them with `useFinalizeActions`\n\n- `phx.frontend.useFinalizeActions()` returns `{ actions, primary, secondary, disabled, hints }`.\n- `actions` lists every active `finalizeAction` in spec order. `primary` is the first `'primary'` one, else the first, else `null`; `secondary` holds the others.\n- Each action is `{ key, handler, variant, label, title, icon, run, isPending, error, disabled }`, with `label` and `title` resolved.\n- `run()` pushes the finalize analytics event and runs the handler. It does nothing while `disabled` or `isPending`, and its promise never rejects.\n- `error` is what the last run rejected with, as an `Error`, cleared on the next run. No snackbar is raised: show it.\n- `disabled` is `true` while a `warning` or worse holds, a save failed or the handler failed to load. Show `hints` beside a disabled button; [Violations](../state/violations.md) owns the gating.\n- Call the hook anywhere in the layout and in dialogs it opens, as often as needed. `isPending` and `error` survive unmounts, such as a panel hidden by fullscreen during a run.\n\n### Handlers run outside the layout\n\n- The configurator runs the handlers itself, beside the layout, whenever a configuration is open, read mode included.\n- A handler can use what the configurator provides, such as every `phx.frontend` hook and opening dialogs, but not a provider the layout adds. Such a handler fails to load and shows as the action's `error`.\n\n### Other ways to run them\n\n- `phx.frontend.useFinalizeAction(handlerName)` runs one known action in the layout and returns `{ run, isPending, error, disabled, hints }`.\n- It calls the handler factory's hooks, so call it once per component, never in a loop or conditionally. Wrap that component in `<PhoenixHandlerBoundary name={handlerName}>` from `@salsita-ai/sdk/react`, so an edited handler takes effect without a reload.\n- Its `isPending` and `error` belong to the mounted component and are lost when it unmounts.\n- `<FinalizeActions />` from `@salsita-ai/sdk/configurator` mounts the built-in buttons, the primary one and a menu of the others. It raises a snackbar on failure, so mount a snackbar root ([Messages](messages.md)).\n\n### Read mode and pending runs\n\n- Neither hook checks read mode. Hide finalization while `accessInfo.viewMode` is `true` ([View mode](view-mode.md)), or filter the components with `$filter.modes: [owner]` so they disappear in every layout.\n- While an action is pending, disable what changes the configuration, such as Back or undo, so it cannot change under the running request.",example:n,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/configurator-interface.mdx` — the "Finalize" paragraph of "Hooks for a Project Layout".\n- `docs/layouts/custom-layout.mdx` — "Request a quote": a review step, a pending button and the handler.\n- `docs/phoenix/finalization.mdx` — the server side, finalize data and result.\n- `docs/layouts/phoenix-handlers.mdx` — handler patterns, such as opening a dialog, each the default export of a file in `src/handlers/`.',phxMembers:["frontend.useFinalizeAction","frontend.useFinalizeActions","frontend.createPhoenixHandler"]});

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

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

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

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

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Showing a project layout's messages: violations, hints, errors and save failures, and where snackbars render. */
+export declare const generatePhoenixMessagesFeature: () => PhoenixGuide;

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

@@ -0,0 +1,52 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`The layout's own toast in place of \`LayoutSlots.Services\`. A rejected change also reports the notices already present, so the toast keeps the most severe message while it shows.
+
+\`\`\`tsx
+// Part of a ConfiguratorLayout, placed in the free area with pointerEvents: 'auto'
+import { Alert } from '@mui/material'
+import { useEffect, useState } from 'react'
+
+type Severity = 'error' | 'warning' | 'info'
+
+const VIOLATION_SEVERITY = { fatal: 'error', fixable: 'error', warning: 'warning', notice: 'info' } as const
+const RANK: Readonly<Record<Severity, number>> = { info: 0, warning: 1, error: 2 }
+
+interface Shown {
+  readonly text: string
+  readonly severity: Severity
+}
+
+export const MessageToast = () => {
+  const [shown, setShown] = useState<Shown | null>(null)
+
+  phx.frontend.useConfiguratorMessages(message => {
+    const severity: Severity =
+      message.kind === 'violation'
+        ? VIOLATION_SEVERITY[message.violation.severity]
+        : message.kind === 'error' || message.kind === 'saveError'
+          ? 'error'
+          : 'info'
+
+    setShown(current =>
+      current !== null && RANK[current.severity] > RANK[severity] ? current : { text: message.text, severity }
+    )
+  })
+
+  useEffect(() => {
+    if (shown === null) {
+      return
+    }
+
+    const timeout = setTimeout(() => setShown(null), 6000)
+
+    return () => clearTimeout(timeout)
+  }, [shown])
+
+  return shown === null ? null : (
+    <Alert severity={shown.severity} onClose={() => setShown(null)}>
+      {shown.text}
+    </Alert>
+  )
+}
+\`\`\`
+
+A failed save shows as an error and stays only six seconds here; a layout that must keep it visible reads \`useConfigurationSaveState().failure\` as well.`;export const generatePhoenixMessagesFeature=()=>e({path:"features/custom-layout/messages.md",title:"Messages",summary:"Showing rejected changes, side-effect hints, validation errors and failed saves with the built-in snackbars or the layout's own UI, the save status, and where snackbars render; read when composing a project layout or when its messages are missing, doubled or outside the configurator.",whenToUse:"Read when composing a project layout: it shows messages only through one of the two routes below. Read also when snackbars appear twice, unstyled or outside the configurator.",capabilities:"### Choose one route\n\n- **Built-in snackbars** — mount `LayoutSlots.Services`. It shows the violations of a rejected change, side-effect hints, validation errors, a failed save (persistent, with **Dismiss**) and \"Configuration updated\" once saving works again.\n- **The layout's own UI** — call `phx.frontend.useConfiguratorMessages(onMessage)` and show each message as a toast, a banner or inline text.\n- Mount one of the two, never both, or every message shows twice.\n- A layout with neither shows no reason for a rejected change and no sign of a failed save.\n\n### Message kinds\n\n`onMessage` is called once per message, with `text` resolved to the current language. It may be a new function on every render.\n\n- **`violation`** — `{ entityId, violation, text }`, one per violation of the rejected state, including notices and warnings already present. `violation.severity` `fixable` or `fatal` is the reason for the rejection, so keep the most severe message while one shows.\n- **`sideEffect`** — `{ text }`, the hint a committed update carried, for example from a transformer.\n- **`error`** — `{ error, text }`, an error thrown while a change was validated; `text` is a generic \"Oops, something went wrong\".\n- **`saveError`** — `{ error, text }`, each failed save. The configurator keeps saving later changes.\n- **`saveRecovery`** — `{ text }`, the first successful save after a failure.\n- A violation's `text` is its `message`, or its `type` without one. On `phx.frontend` the message is typed by the project, so `violation.type` narrows to its violation types.\n- Hints committed and saves failed before the hook mounted are not delivered; the most recent rejected change is delivered again on mount.\n- What the violations mean and how controls show them belongs to [Violations](../state/violations.md).\n\n### Save status\n\n- `phx.frontend.useConfigurationSaveState()` returns `{ revisionId, isSaving, failure }` for a save indicator.\n- `failure` is `{ error, timestamp }` of the latest failed save, and `null` once a later save succeeds or another configuration loads.\n- An editable configuration saves every committed change about three seconds after the last one. A read-only one never saves.\n- The messages of a failed save still come from the route above; finalizing is blocked while the failure stands.\n\n### Snackbar roots\n\n- Snackbars render into the snackbar root the layout mounts. Without one they render into the page's `document.body`, outside the configurator and its theme.\n- Mount a root whenever the layout mounts `LayoutSlots.Services` or a built-in piece with actions, such as the toolbar or `FinalizeActions`. Their failures are snackbars even when the layout uses `useConfiguratorMessages`.\n- A layout drawn only from hooks, with `useConfiguratorMessages` and `useFinalizeActions`, raises no snackbars and needs no root.\n- `LayoutSlots.DesktopSnackbarsRoot` is a zero-height element the snackbars stack upward from, at most 320 px wide: place it where their bottom edge belongs.\n- `LayoutSlots.MobileSnackbarsRoot` leaves them fixed to the viewport's edge wherever it is mounted.\n- The preset screen renders before any layout; a project preset screen mounts its own root ([Project pages](pages.md)).\n- The theme restyles every snackbar under `components.PhxSnackbar`.",example:t,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/configurator-interface.mdx` — the messages paragraph of "Loaded Configuration UI" and the "Violations" table of "Hooks for a Project Layout".\n- `docs/phoenix/layout-slots.mdx` — "Canvas and services" and "Styling the snackbars": the services, the roots and the `PhxSnackbar` theme slots.\n- `docs/layouts/custom-layout.mdx` — "Show messages", the toast this example follows.\n- `docs/other-features/side-effects.mdx`, `docs/other-features/violation-messages.mdx` — where hints and violation texts come from.',phxMembers:["frontend.useConfiguratorMessages","frontend.useConfigurationSaveState"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The project's pages outside the loaded configuration: preset screen, loader, failure pages, assistant form elements and drawings. */
+export declare const generatePhoenixProjectPagesFeature: () => PhoenixGuide;

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

@@ -0,0 +1,49 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A branded preset screen that keeps the preview branch, shows creation progress and errors, and mounts its snackbar root.
+
+\`\`\`tsx
+// src/elements/PresetScreen.tsx
+import { PresetPreviewLayout, PresetSnackbarsRoot } from '@salsita-ai/sdk/configurator'
+import { useResourceUrl } from '@salsita-ai/sdk/react'
+
+const PresetScreen = () => {
+  const { isPreview } = phx.frontend.usePreview()
+  const { presetCategories, selectPreset, creatingPresetId, selectionError } = phx.frontend.usePresetSelection()
+  const resolve = phx.frontend.useResolveLocalizable()
+  const { getResourceUrl } = useResourceUrl()
+
+  // A phone embed with \`preview: auto\` starts here; the button expands it
+  if (isPreview) {
+    return <PresetPreviewLayout title="Design your sofa" startButtonLabel="Start designing" />
+  }
+
+  const presets = presetCategories.flatMap(category => category.presets)
+
+  return (
+    <main style={{ height: '100%', overflowY: 'auto', padding: 32 }}>
+      <h1>Choose a starting sofa</h1>
+      {selectionError !== null && <p role="alert">This sofa could not be opened. Try again.</p>}
+      <div style={{ display: 'grid', gap: 24, gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr))' }}>
+        {presets.map(preset => (
+          <button
+            key={preset.id}
+            type="button"
+            aria-busy={creatingPresetId === preset.id}
+            disabled={creatingPresetId !== null}
+            onClick={() => selectPreset(preset.id)}
+          >
+            {preset.img !== undefined && (
+              <img src={getResourceUrl(preset.img)} alt={resolve(preset.imgAlt ?? preset.name)} width="100%" />
+            )}
+            {resolve(preset.name)}
+          </button>
+        ))}
+      </div>
+      <PresetSnackbarsRoot />
+    </main>
+  )
+}
+
+export default phx.frontend.createPresetUi(PresetScreen)
+\`\`\`
+
+The app loader is as short: \`export default phx.frontend.createAppLoader(({ phases }) => <span role="status">{phases[0]?.label ?? 'Loading…'}</span>)\`.`;export const generatePhoenixProjectPagesFeature=()=>e({path:"features/custom-layout/pages.md",title:"Project pages",summary:"Replacing the preset screen and its action and overlay, the app loader, the not-authenticated, not-found and error pages, the assistant's form elements and its drawings; read when branding the first moments or the failure pages, when the assistant needs a project form element, or when it should draw for configurator users.",whenToUse:"Read when a page outside the loaded configuration should carry the brand, such as the preset screen, the loader or a failure page, when the assistant should offer a form element of the project, or when it should draw schematics for configurator users.",capabilities:"Each page below is an element: default-export its registration from a file in `src/elements/`.\n\n### Preset screen\n\n- The preset screen shows at the start when there is more than one preset; with a single preset the configuration starts at once.\n- `phx.frontend.createPresetUi(Component)` replaces the whole screen. The built-in screen's categories, close button, action, overlay and empty state go with it.\n- Inside it, `phx.frontend.usePresetSelection()` returns `{ presetCategories, hasMultiplePresets, selectPreset, creatingPresetId, selectionError }`.\n- A category is `{ id, name, description?, img?, imgAlt?, presets }`; a preset is `{ id, name, description?, img?, imgAlt?, detailTitle?, detailDescription? }`. Texts are `Localizable`: resolve them with `phx.frontend.useResolveLocalizable()`.\n- `img` is a resource path: turn it into a URL with `useResourceUrl().getResourceUrl(img)` from `@salsita-ai/sdk/react`, as the built-in screen does.\n- `selectPreset(id)` creates the configuration and opens it. While `creatingPresetId` is set, mark that card busy and disable the others.\n- `selectionError` is the last failed creation: show it. In production with several presets the failure is also a snackbar, so mount `PresetSnackbarsRoot` from `@salsita-ai/sdk/configurator`, or it renders outside the configurator.\n- Keep the preview branch. While `phx.frontend.usePreview().isPreview` is `true`, return `PresetPreviewLayout` from `@salsita-ai/sdk/configurator` with `title` and `startButtonLabel`. Without it, a phone embed with `preview: auto` never expands and shows the whole screen in the collapsed preview.\n- With no categories, for example when the host's `presetTags` match none, the built-in screen shows the not-found page; a replacement decides itself.\n- What a preset is and how to declare one belongs to [Presets](../application-states/presets.md).\n\n### Preset action and overlay\n\nThese fill the built-in preset screen only; a `createPresetUi` screen renders its own instead.\n\n- `phx.frontend.createPresetPageAction(Component)` adds content below the cards, such as a link to request an unlisted product.\n- `phx.frontend.createPresetDeviceNotSupported(Component)` adds an overlay, such as a notice that the configurator works best on a larger screen.\n- The overlay renders as the last child of the screen, not over the cards, and at every width: make it a dialog or position it, and gate it on the condition it is for.\n\n### App loader\n\n- `phx.frontend.createAppLoader(({ phases }) => …)` replaces what the loading overlay shows. Phoenix keeps the overlay, its place over the safe area and its fade.\n- `phases` are the running loading phases, each `{ id, label?, progress? }` with `progress` from 0 to 1. The list can be empty while the loader waits for the scene.\n- The loader covers the session, the data, the configuration and the scene; it waits for the scene only when the layout mounts `LayoutSlots.SharedCanvas` ([Scene and safe area](scene-and-safe-area.md)).\n- `phx.frontend.useLoadingStateValue()` returns `{ isLoading, hasError, phases, expectedPhaseIds }` for loader content that needs more than `phases`.\n- `phx.frontend.useLoadingState()` returns `{ startPhase, endPhase }`, or `null` outside the loader's host. `startPhase({ id, label, progress })` holds the overlay for the project's own loading step; calling it again with the same `id` updates it.\n- End every started phase with `endPhase(id)`, on failure and on unmount too, or the overlay never leaves.\n- A top-level `appLoader: legacy` in the spec turns the overlay off.\n\n### Failure pages\n\n- `phx.frontend.createNotAuthenticatedPage(Component)` — shown when session authentication fails, and to an anonymous visitor of the start page when `acl.canCreate` excludes `anonymous`. It gets no props. Its default renders the not-found page, so a project not-found page shows there too.\n- `phx.frontend.createConfigurationNotFoundPage(({ onBack }) => …)` — shown when a configuration fails to load, is opened without a valid access key, or a signed-in role may not create one. Offer a way back only when the optional `onBack` is set.\n- `phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => …)` — the production error page. `reason` is `'uncaughtError'` or `'presetCreationFailed'` (the single preset failed to start); `onRetry` renders again or reloads.\n- Development shows detailed error pages instead, or in agent mode the \"Agent at work\" screen, so check the error page in a production build. A page that throws falls back to the built-in one.\n- Use these helpers rather than `createCustomPhoenixLayoutElement` with the element's name: only the helpers type the props.\n\n### Assistant form elements\n\n- Declare an element under `assistant.formElements.<name>` with `description` (what the model reads), `role` (`group`, `choice`, `choices`, `option` or `input`), optional scalar `attributes` and `required`. Names are lowercase, such as `ralcolor`.\n- Implement it in one file: `export default phx.frontend.createAssistantFormElement('name', Component)`.\n- The name types the props by role through the global `AssistantFormElementProps<'name', STATE>`. Every element gets `attributes`, `label` and `disabled`; an option reports with `onSelect(answer)`, an input with `onChange(state, answer)`, and a container renders `children`.\n- A declared element without a registration, one registered twice, or a registration without a declaration stops the application with an implementation error, at start and on hot reload.\n\n### Assistant drawings\n\n- The assistant can draw a schematic in a reply, as SVG in an `svg` code block. The panel shows it framed in the thread, and a click shows it larger beside the panel.\n- Its prompt lets it draw when a schematic explains better than words or when it is asked to. Ask for more drawings, or for particular ones, in `assistant.instructions` where they help configurator users, such as \"After reading a photo, draw the layout you deduced and ask them to confirm it.\"\n- Nothing needs registering: `AssistantMarkdown` renders drawings, and the configurator page shows the larger view over every layout.",example:t,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/layouts/presets/custom.mdx` — the complete branded preset screen with search and the preview branch.\n- `docs/layouts/presets/action-and-overlay.mdx` — the action and the overlay of the built-in screen.\n- `docs/phoenix/configurator-interface.mdx` — "Preset UI", "Configuration Not Found Page", "Configurator Error Page" and "App Loader".\n- `docs/other-features/not-found-404.mdx`, `docs/other-features/error-5xx.mdx` — worked failure pages.\n- `docs/ux-guidelines/presets.mdx` — what a good preset screen offers.',phxMembers:["frontend.createPresetUi","frontend.usePresetSelection","frontend.createPresetPageAction","frontend.createPresetDeviceNotSupported","frontend.createAppLoader","frontend.useLoadingState","frontend.useLoadingStateValue","frontend.createNotAuthenticatedPage","frontend.createConfigurationNotFoundPage","frontend.createConfiguratorErrorPage","frontend.createAssistantFormElement"]});

package/dist/application-spec/generate-application/code/templates/skills/features/custom-layout/scene-and-safe-area.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The layout element's registration, its canvas, the scene's safe area and the desktop/phone switch. */
+export declare const generatePhoenixSceneAndSafeAreaFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/custom-layout/scene-and-safe-area.js

@@ -0,0 +1,62 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`The minimal layout: the canvas, the layout's own panel with the selected desk's controls, the safe area beside it, and the built-in snackbars with their root. Viewers get no panel. \`DeskControls\` is the project's element from [Custom controls](../domain-controls/custom-controls.md).
+
+\`\`\`tsx
+// src/elements/ConfiguratorLayout.tsx
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+import { DeskControls } from '../_shared/DeskControls.js'
+
+const GUTTER = 24
+const PANEL_WIDTH = 360
+
+const ConfiguratorLayout = () => {
+  const { containerRef, safeAreaRef } = phx.frontend.useSceneSafeArea()
+  const viewports = phx.frontend.useActiveViewports()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  const { accessInfo } = phx.frontend.useAccessService()
+  const deskId = phx.frontend.useSelectedEntityId(phx.domain.enhancedModel.$Desk)
+  // Desktop only here; a phone arrangement puts the panel in the layout's own bottom sheet
+  const showPanel = (viewports?.includes('desktop') ?? false) && !isFullscreen && !accessInfo.viewMode
+
+  return (
+    <div ref={containerRef} style={{ position: 'absolute', inset: 0 }}>
+      <LayoutSlots.Services />
+      <LayoutSlots.SharedCanvas />
+      {showPanel && (
+        <aside
+          style={{
+            position: 'absolute',
+            insetBlock: GUTTER,
+            insetInlineStart: GUTTER,
+            inlineSize: PANEL_WIDTH,
+            overflowY: 'auto',
+            background: 'white',
+          }}
+        >
+          {deskId !== null && <DeskControls deskId={deskId} />}
+        </aside>
+      )}
+      <div
+        ref={safeAreaRef}
+        style={{
+          position: 'absolute',
+          insetBlock: 0,
+          insetInlineStart: showPanel ? PANEL_WIDTH + 2 * GUTTER : 0,
+          insetInlineEnd: 0,
+          pointerEvents: 'none',
+        }}
+      >
+        <div style={{ position: 'absolute', insetBlockEnd: GUTTER, insetInlineStart: GUTTER, inlineSize: 320 }}>
+          <LayoutSlots.DesktopSnackbarsRoot />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+\`\`\`
+
+- \`LayoutSlots.Services\` raises snackbars, so the layout mounts their root; [Messages](messages.md) covers the alternative.
+- [Finalization actions](finalization-actions.md) adds the finalize button, hidden for viewers, with its pending state and error.
+- With the default \`preview: auto\`, a phone embed starts in preview; [View mode](view-mode.md) covers the start screen.`;export const generatePhoenixSceneAndSafeAreaFeature=()=>e({path:"features/custom-layout/scene-and-safe-area.md",title:"Scene and safe area",summary:"Registering `ConfiguratorLayout`, mounting the canvas, framing the product in the free area and switching between desktop and phone, with the minimal skeleton; read when starting a project layout or when the product is framed wrong, hidden or cannot be orbited.",whenToUse:"Read when creating a project layout, or when the product sits behind a panel, the UI is hidden behind the scene, the scene cannot be orbited or the loader leaves before the scene appears. The skeleton in the example is the starting point of every layout; the other guides of [Custom project layout](index.md) add to it.",capabilities:"### Register the layout\n\n- Create `src/elements/ConfiguratorLayout.tsx` and default-export `phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)`.\n- The name is the contract. Phoenix renders this element for every loaded configuration, in owner and read mode, whatever `applicationConfig.layout` says. Nothing in YAML refers to it.\n- The component gets no props besides `children`; it reads everything from `phx.frontend` hooks. `LayoutSlots` comes from `@salsita-ai/sdk/configurator`.\n- The layout replaces the built-in UI entirely: no canvas, panel, messages, finalization or preview screen unless it composes them.\n\n### Mount the canvas\n\n- Give the root a positioned box that covers the page, such as `position: 'absolute', inset: 0`.\n- Mount `LayoutSlots.SharedCanvas` in it. It fills its nearest positioned ancestor and paints an opaque background.\n- Put the UI after the canvas in the markup and position it. Unpositioned content is painted under the canvas and cannot be seen.\n- Mount `SharedCanvas`, not `LayoutSlots.Canvas`: `Canvas` suspends while it probes the GPU, so the loader can leave and come back.\n- With the canvas mounted, the app loader stays until the scene has loaded. A layout without a canvas is not held: the loader leaves once the configuration is up.\n\n### Tell the camera where the free area is\n\n- `phx.frontend.useSceneSafeArea()` returns `{ containerRef, safeAreaRef, update }`.\n- Put `containerRef` on the element that covers the whole canvas, usually the root.\n- Put `safeAreaRef` on the region the product should stay visible in, such as the space beside a panel or above a bottom sheet. The camera frames the product there.\n- The hook measures again whenever either element resizes. Call `update()` after a change no resize reports, such as an ancestor's `transform` settling at the end of an animation.\n- Give the safe-area element `pointerEvents: 'none'`, or the scene cannot be orbited; set `pointerEvents: 'auto'` on buttons placed inside it.\n- Without the refs the product is framed in the whole canvas and sits behind the panel.\n- A `canvasPadding` component in the spec multiplies the measured gaps, and its default of 1 uses all of them. A fraction such as 0.08 shrinks a 420 px panel gap to 34 px and puts the product behind the panel. Leave it at 1 and give the safe-area element insets for breathing room, as the gallery layouts do.\n- Keep one mounted caller at a time: when a start screen and the interface swap, each calls the hook and only the one on screen is mounted.\n\n### Fit desktop and phone\n\n- `phx.frontend.useActiveViewports()` returns the breakpoints the configurator's container satisfies, as `readonly Viewport[]`, or `null` before the first measurement.\n- `desktop` is a container wider than 768 px and `mobile` one at most 768 px; `phone` is below 480 px and `tablet` between 480 and 1024 px. `landscape` and `portrait` follow the window.\n- It follows the container, not the window, so a narrow embed on a wide page gets the phone arrangement. Switch on `desktop`, as the built-in layout does.\n- Render only the canvas while it is `null`, so a phone never flashes the desktop panel.\n- Fullscreen is a flag in the configurator's state, not the browser's fullscreen. Remove panels while `phx.frontend.useIsFullscreenActive()` is `true` and let the safe area cover the canvas; [Toolbar actions](toolbar-actions.md) owns the toggle.",example:t,documentation:'Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/configurator-interface.mdx` — "Loaded Configuration UI": the canvas, safe-area and loader rules.\n- `docs/layouts/custom-layout.mdx` — a complete layout drawn from hooks: desktop panel with its controls, phone bottom sheet, fullscreen and read mode.\n- `docs/layouts/gallery/` — eight complete layouts for real products; `pnpm phoenix docs -l` lists them.\n- `docs/layouts/canvas-padding.mdx` — multiplying the measured gaps.',phxMembers:["frontend.createCustomPhoenixLayoutElement","frontend.useSceneSafeArea","frontend.useActiveViewports"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Reusing the built-in layout's pieces in a project layout, and the layout element factories of the built-in layouts. */
+export declare const generatePhoenixLayoutSlotsFeature: () => PhoenixGuide;

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

@@ -0,0 +1,40 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let o=`The built-in scene tools placed in the free area of a project layout, for a product whose spec configures its toolbar, view controls, tool controls and tool-mode exit. The layout also mounts what the built-in layout would have shown with them: the readonly banner for viewers and the snackbar root.
+
+\`\`\`tsx
+// Part of a ConfiguratorLayout, rendered inside the safe-area element (pointerEvents: 'none')
+import type { CSSProperties } from 'react'
+
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
+
+const corner = (place: CSSProperties): CSSProperties => ({ position: 'absolute', pointerEvents: 'auto', ...place })
+
+export const SceneTools = () => {
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  const { accessInfo } = phx.frontend.useAccessService()
+
+  return (
+    <>
+      <div style={corner({ insetBlockStart: 24, insetInline: 24, display: 'flex', justifyContent: 'center' })}>
+        <LayoutSlots.DesktopCallToAction />
+        {accessInfo.viewMode && !isFullscreen && <LayoutSlots.DesktopReadonlyBanner />}
+      </div>
+      {!isFullscreen && (
+        <div style={corner({ insetBlockEnd: 96, insetInlineEnd: 24 })}>
+          <LayoutSlots.DesktopToolControls />
+        </div>
+      )}
+      <div style={corner({ insetBlockEnd: 24, insetInline: 24, display: 'flex', gap: 16, alignItems: 'end' })}>
+        <LayoutSlots.DesktopToolbar />
+        <LayoutSlots.DesktopViewControls />
+        <div style={{ position: 'relative', flex: 1 }}>
+          <LayoutSlots.DesktopSnackbarsRoot />
+        </div>
+      </div>
+    </>
+  )
+}
+\`\`\`
+
+- Without a \`toolbar\` component, the default toolbar shows only its exit button in fullscreen and drops share, undo and redo for viewers.
+- A configured \`toolbar\` shows as written; the first active one counts, so give viewers their own, filtered with \`$filter.modes: [read]\`.
+- The banner and the tool controls check nothing themselves, so the layout does.`;export const generatePhoenixLayoutSlotsFeature=()=>e({path:"features/custom-layout/slots.md",title:"Layout slots",summary:"Reusing built-in pieces in a project layout: header, toolbar, view and tool controls, banners and footer, and the layout element factories of the built-in layouts; read when a layout keeps part of the built-in UI or a project uses those factories.",whenToUse:"Read when a project layout should keep a built-in piece as the spec configures it, such as the toolbar or the view controls, instead of rebuilding it, or when a project registers a footer, a dialog or a `layout: custom` UI.",capabilities:"### Slot or own UI\n\n- Mount a slot when the spec-configured piece is what users should see and only its place changes. Build the piece from hooks when it has to look like the brand's own.\n- A slot brings its look, not its place: put it in a positioned container that sets its size. `SharedCanvas` fills its container.\n- `Desktop*` and `Mobile*` members are twins; pick one with `phx.frontend.useActiveViewports()` as in [Scene and safe area](scene-and-safe-area.md).\n- Slots read the spec and the configurator's state and take no props unless named below. They render only inside a `ConfiguratorLayout`.\n- A mounted slot with actions raises snackbars on failure, so mount a snackbar root with it; see [Messages](messages.md).\n\n### Panels are the layout's own\n\n- Build the side panel or bottom sheet from the project's control elements ([Custom controls](../domain-controls/custom-controls.md)), not from a slot.\n- Leave out `DesktopSidebar`, the other `*Sidebar*` pieces, `EntityHeader` and `MobileTabs`: they render the spec-driven built-in sidebar. Draw tabs and steps from hooks ([Tabs and steps](tabs-and-steps.md)).\n- Keep `Services`, `SharedCanvas` and the snackbar roots: every layout needs them ([Scene and safe area](scene-and-safe-area.md), [Messages](messages.md)).\n\n### Header, toolbar and scene controls\n\n- `DesktopHeader` and `MobileHeader` — the spec's `floatingHeader`, `fixedHeader`, `customHeader` or `hiddenHeader`.\n- `DesktopToolbar`, `MobileToolbar` and `MobileHamburgerMenu` — the spec's `toolbar` lists `desktop`, `mobile` and `mobileMenu`, or the default buttons. A project element registered under a button kind replaces that button here. [Toolbar actions](toolbar-actions.md) builds the same toolbar from data.\n- `DesktopViewControls` and `MobileViewControls` — the root's `viewControls`. `DesktopToolControls` and `MobileToolControls` — its `toolControls`.\n- `DesktopCallToAction` and `MobileCallToAction` — the `exitToolModeFab` that leaves a tool mode, not a finalize button.\n- These spec components configure only their slots: a layout that mounts none of them ignores `toolbar`, `viewControls` and `toolControls`.\n\n### Banners, branding and footer\n\n- `DesktopReadonlyBanner` and `MobileReadonlyBanner` — \"Edit configuration\" for a viewer. They render only when cloning is allowed and do not check read mode, so mount them only in read mode.\n- `DesktopPoweredBy` and `MobilePoweredBy` — the \"Powered by Salsita\" mark. The built-in layout shows it; a project layout decides.\n- `DesktopFooter` and `MobileFooter` — a page footer below the whole layout.\n\n### Layout element factories\n\nThese register elements that the built-in layouts mount. Default-export each from `src/elements/`.\n\n- `phx.frontend.createLayoutFooter(Component)` — the content of `DesktopFooter` and `MobileFooter`, nothing without it. It adds a footer to the built-in universal layout; in a `ConfiguratorLayout`, render the footer directly, or mount the slot to reuse a registered one.\n- `phx.frontend.createLayoutDialog(Component)` — an overlay the built-in layouts mount. A `ConfiguratorLayout` shows it only if it mounts `LayoutDialog` from `@salsita-ai/sdk/configurator`; open the layout's own dialog instead.\n- `phx.frontend.createLayoutCustomOwnerUi(Component)` and `phx.frontend.createLayoutCustomReadUi(Component)` — the owner and read UI of `applicationConfig.layout: custom`, the older route to a project layout.\n- A registered `ConfiguratorLayout` replaces the built-in UI that renders those two, so they never show beside it. Do not use them in new work; when a project that relies on `layout: custom` changes its layout, move both into one `ConfiguratorLayout` that reads `viewMode`.",example:o,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/layout-slots.mdx` — every `LayoutSlots` member: what it shows, what feeds it, its empty state and its read-mode behavior.\n- `docs/layouts/toolbar.mdx`, `docs/layouts/view-controls.mdx`, `docs/layouts/tool-controls.mdx` — what the spec configures in those slots.",phxMembers:["frontend.createLayoutFooter","frontend.createLayoutDialog","frontend.createLayoutCustomOwnerUi","frontend.createLayoutCustomReadUi"]});

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

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Tabs and steps a project layout draws from the spec's `sidebarTabs`, `horizontalTabs` and `navigationSteps`. */
+export declare const generatePhoenixTabsAndStepsFeature: () => PhoenixGuide;

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;