@salsita-ai/sdk 0.50.0-develop.f101f4c3c9 → 0.50.0-develop.f354d3576d

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 and assistant form elements. */
+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, and the assistant's form elements; read when branding the first moments or the failure pages, or when the assistant needs a project form element.",whenToUse:"Read when a page outside the loaded configuration should carry the brand, such as the preset screen, the loader or a failure page, or when the assistant should offer a form element of the project.",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, 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.",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;

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- **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.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)` with the same result, for several lists; leave out the cook function's second argument: it is typed as a collection but read as `keepChildren`.\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;