@salsita-ai/sdk 0.50.0-develop.26a71cda28 → 0.50.0-develop.2ad6270b01

package/dist/docs/layouts/sidebar/in-a-custom-layout.mdx

@@ -90,8 +90,8 @@ The spec is a table with one property, its edge finish, on a **Design** tab and
 
 ## Known gaps
 
-- The finalize button is disabled unless the spec configures `finalizeButton` or `finalizePage`, as in the built-in layout. A `finalizePage` is not shown by a project layout unless the layout renders it.
-- `LayoutSlots.DesktopSidebar` is the desktop sidebar. At phone width a project layout needs its own arrangement, for example the `Mobile*` members of `LayoutSlots` in a drawer.
+- The footer is the basic sidebar footer, as in the built-in layout when the spec configures none. Its finalize button is disabled unless the spec configures the legacy `finalizeButton` or `finalizePage` components, which are declared only in TypeScript, and a project layout shows a `finalizePage` only if it renders it. New projects finalize over `finalizeAction` components, which the universal sidebar footer offers when the spec configures `universalSidebarFooter`.
+- `LayoutSlots.DesktopSidebar` is the desktop sidebar. At phone width a project layout needs its own arrangement, for example the `Mobile*` members of `LayoutSlots`, listed in [Layout Slots](?path=/docs/phoenix-layout-slots--docs#phone-layout), in a drawer.
 - The tabs overlap the scene beside the sidebar; the safe area in this example does not leave room for them.
 - `miniSidebar` does not shrink the sidebar: the built-in layout does that, and here the sidebar fills its container. A layout that honours it reads `LayoutSlots.useSidebarContent().hasMiniSidebar` and gives the container no fixed height, anchored at the bottom for example, so the sidebar takes its content's height.
 

package/dist/docs/other-features/error-5xx.mdx

@@ -12,7 +12,7 @@ Error page that is displayed when needed.
 
 ## Code
 
-The `ErrorPage` is provided in the default in the `LoadedConfigurationDetailPage` and `PresetSelectionProvider`.
+In production the configurator renders the layout element `ConfiguratorErrorPage` when an error reaches its error boundary or a configuration cannot be created from the only preset. Its default is a built-in page made with `ErrorPage` from `@salsita-ai/sdk/ui`; this example renders `ErrorPage` directly to show it. A project replaces the page with `phx.frontend.createConfiguratorErrorPage`, see [Configurator Interface → Configurator Error Page](?path=/docs/phoenix-configurator-interface--docs#configurator-error-page), which also lists the cases that still show another page.
 
 ## Example
 

package/dist/docs/other-features/not-found-404.mdx

@@ -12,7 +12,7 @@ Error page that is displayed when the configuration is not accesible.
 
 ## Code
 
-The `NotFoundPage` is provided in the default in the `ConfiguratorRoot` and `ConfiguratorApp`.
+The configurator renders the layout element `ConfigurationNotFoundPage`, whose default is the built-in page, `ConfigurationNotFoundPage` from `@salsita-ai/sdk/react`. This example renders that component directly to show it. A project replaces the page with `phx.frontend.createConfigurationNotFoundPage`, see [Configurator Interface → Configuration Not Found Page](?path=/docs/phoenix-configurator-interface--docs#configuration-not-found-page), which also lists when the page is shown.
 
 ## Example
 

package/dist/docs/phoenix/application-states.mdx

@@ -223,22 +223,24 @@ components:
 
     staticPerspectiveCamera:
       overview:
-        position: [0, 10, 10]
-        target: [0, 0, 0]
+        distance: 14
+        polarAngle: 0.8
+        azimuthAngle: 0
         $filter:
           viewStates: ['overview']
 
       detail:
-        position: [2, 2, 2]
-        target: [0, 0, 0]
+        distance: 3.5
+        polarAngle: 0.95
+        azimuthAngle: 0.8
         $filter:
           viewStates: ['closeup']
 
     staticOrthographicCamera:
       blueprint:
-        position: [0, 20, 0]
-        target: [0, 0, 0]
-        zoom: 1.5
+        distance: 20
+        polarAngle: 0
+        frustumSize: 12
         $filter:
           viewStates: ['blueprint']
 

package/dist/docs/phoenix/clerk-sign-in.mdx

@@ -14,7 +14,7 @@ useAuthHook: true
 useClerk: true
 ```
 
-`phoenix sync` then adds `@clerk/clerk-react` as a direct application dependency and generates typed Clerk environment readers. `phoenix deployment:prepare-local` writes the deployment's public `CLERK_PUBLISHABLE_KEY` to `.env.generated`; application source should read it from `phx.frontendEnv`, not hardcode a key.
+`@clerk/clerk-react` then becomes a dependency the project declares: run `phoenix deps` through your package manager (for example `pnpm phoenix deps`) and install to add it, because `phoenix sync`, `dev` and `build` stop while it is missing. `phoenix sync` generates typed Clerk environment readers. In a project on the legacy pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), `phoenix sync` adds the dependency itself. `phoenix deployment:prepare-local` writes the deployment's public `CLERK_PUBLISHABLE_KEY` to `.env.generated`; application source should read it from `phx.frontendEnv`, not hardcode a key.
 
 ## Configure the auth webhook
 

package/dist/docs/phoenix/components.mdx

@@ -273,6 +273,12 @@ components:
 
 `$bind` is essential for form controls that need to show current state and accept changes, any UI element that both displays and modifies data, and interactive controls like attribute selectors, toggles, sliders, and input fields.
 
+### Types of bound values
+
+The build checks that the field a `$read` or `$bind` reads fits the prop it is read into, the filter criterion, or, for `$filter: { $read: field }`, the whole filter. A `string` field read into a number prop, a nullable field read into a text, or an array read into a boolean is reported as `COMPONENT_BINDING_TYPE_MISMATCH` at the prop. A field whose schema gives its type only as `tsType` is not checked here. Expressions are checked where their type is settled.
+
+A prop or filter criterion that takes an entity id, such as the `value` of `childEntitySelection` or `selectedEntityIds`, cannot hold an id written in YAML: an entity id is a branded type that only comes from the domain state. Bind it to a field or expression that holds the id; a written id is reported as `COMPONENT_STATIC_ENTITY_ID`.
+
 ### `$eval` - Inline Expressions
 
 `$eval` allows simple dynamic calculations directly in YAML without defining separate `$expression` implementations in TypeScript. It can appear wherever `$read` is allowed — including in component filter `active` properties — and is mutually exclusive with `$read` on the same property, but both can coexist on the same component instance across different properties.

package/dist/docs/phoenix/configurator-interface.mdx

@@ -165,6 +165,10 @@ const popNavigate = phx.frontend.usePopNavigate() // popNavigate() returns to th
 // Fullscreen: a flag in the configurator's state that the layout honours; it does not put the browser into fullscreen
 const isFullscreen = phx.frontend.useIsFullscreenActive()
 const setFullscreen = phx.frontend.useSetFullscreen() // setFullscreen(true) or setFullscreen(false)
+
+// View state and camera
+const setViewState = phx.frontend.useSetViewState() // setViewState(state) makes one of the spec's viewStates active
+const resetCamera = phx.frontend.useResetCamera() // resetCamera() undoes the user's orbit, pan and zoom
 ```
 
 ### Controls
@@ -218,6 +222,9 @@ const controlViolations = phx.frontend.useControlViolations([])
 // Finalize violations
 const { disabled, hints } = phx.frontend.useFinalizeViolations()
 
+// Messages for the user: violations of a rejected change, side-effect hints, errors and failed saves, one call each
+phx.frontend.useConfiguratorMessages(message => showToast(message.text))
+
 // Map violations to hints
 const mapViolationHints = phx.frontend.useMapViolationHints()
 ```
@@ -384,24 +391,68 @@ Use these factories to customize the preset-selection screen without changing ho
 - `createPresetPageAction` adds project-specific content below the default preset cards.
 - `createPresetDeviceNotSupported` adds project-specific overlay content above the default preset cards.
 
+Without `createPresetUi`, Phoenix renders its built-in preset screen, which is the default `PresetUi` registration in `defaultConfiguratorElements`. The action and the overlay are parts of that built-in screen and render nothing until the project registers them.
+
 ```typescript
 const PresetScreen = phx.frontend.createPresetUi(CustomPresetScreen)
 const PresetAction = phx.frontend.createPresetPageAction(PresetHelpAction)
 const PresetOverlay = phx.frontend.createPresetDeviceNotSupported(SmallScreenNotice)
 ```
 
+### Configuration Not Found Page
+
+`phx.frontend.createConfigurationNotFoundPage` registers a page that replaces the one the configurator shows when it cannot open a configuration, as the layout element `ConfigurationNotFoundPage`. Without it, Phoenix renders its built-in "Configuration not accessible" page, which is the default `ConfigurationNotFoundPage` registration in `defaultConfiguratorElements`.
+
+```typescript
+// src/elements/ConfigurationNotFoundPage.tsx
+export default phx.frontend.createConfigurationNotFoundPage(({ onBack }) => (
+  <main>
+    <h1>We could not find this configuration</h1>
+    {onBack && <button onClick={onBack}>Start a new one</button>}
+  </main>
+))
+```
+
+The helper types the page's props as `ConfigurationNotFoundPageProps` from `@salsita-ai/sdk/react`. A layout element registered under the name `ConfigurationNotFoundPage` with `createCustomPhoenixLayoutElement` replaces the page too, but its component is typed as taking only `children`.
+
+- The page receives one optional prop, `onBack`, which returns to the start of the configurator. It is set when a configuration fails to load or is opened without a valid access key. It is not set on the start page itself, so a page that offers a way back shows it only when `onBack` is set.
+- The configurator renders the element in four cases: a configuration fails to load, for example because its ID does not exist or the server rejects its access key; a configuration is opened without an access key for it; a signed-in user whose role may not create configurations (`acl.canCreate`) opens the start page; the preset screen has no preset category to show, for example because the host's `presetTags` match no preset. The last case happens inside the built-in preset screen, so a project that replaces it with `createPresetUi` decides what to show itself.
+- The not-authenticated page, shown when session authentication fails or to an anonymous visitor who may not create a configuration, is its own element, which `createNotAuthenticatedPage` replaces. Its default, the `NotAuthenticatedPage` registration in `defaultConfiguratorElements`, renders the `ConfigurationNotFoundPage` element, so a project's not-found page shows there too.
+- The admin's not-authorized page still shows the built-in page directly, not the element.
+
+### Configurator Error Page
+
+`phx.frontend.createConfiguratorErrorPage` registers a page that replaces the one the configurator shows in production when it cannot go on, as the layout element `ConfiguratorErrorPage`. Without it, Phoenix renders its built-in "Whoops, something went wrong!" page, which is the default `ConfiguratorErrorPage` registration in `defaultConfiguratorElements`.
+
+```typescript
+// src/elements/ConfiguratorErrorPage.tsx
+export default phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => (
+  <main>
+    <h1>{reason === 'presetCreationFailed' ? 'We could not start your design' : 'Something went wrong'}</h1>
+    <button onClick={onRetry}>{reason === 'presetCreationFailed' ? 'Reload' : 'Try again'}</button>
+  </main>
+))
+```
+
+The helper types the page's props as `ConfiguratorErrorPageProps` from `@salsita-ai/sdk/react`. A layout element registered under the name `ConfiguratorErrorPage` with `createCustomPhoenixLayoutElement` replaces the page too, but its component is typed as taking only `children`.
+
+- The page receives two props. `reason` says what failed: `uncaughtError` when rendering the configurator failed with an error nothing else handled, `presetCreationFailed` when starting a configuration from the only preset failed. `onRetry` tries again: after `uncaughtError` it renders the configurator again, after `presetCreationFailed` it reloads the page. The error itself is not passed; it is logged to the console.
+- The configurator renders the element in two cases: an error reaches the configurator's error boundary, which wraps everything from the scene resources and the session down to the pages, including a failure while the application starts; and creating a configuration fails on a start screen with a single preset. The element is available in both, because the spec and its elements are part of the application before the configurator renders.
+- A registered page that throws does not take the configurator down: the built-in page is shown in its place and the error is logged, until a hot reload replaces or removes the page.
+- Three cases do not show the element. In development the configurator shows its detailed error pages instead. A failed preset creation with more than one preset is a snackbar on the preset screen (see [Loaded Configuration UI](#loaded-configuration-ui) for how a project shows it). The admin's own error page stays the built-in one, while the configurator the admin embeds renders the element.
+
 ### Loaded Configuration UI
 
 A layout element registered under the name `ConfiguratorLayout` replaces the whole UI of a loaded configuration, in owner and in read mode, whatever `layout` the spec sets. Without it, Phoenix renders the layout the spec selects. [Custom Layout](?path=/docs/layouts-custom-layout--docs) is a worked example: a fully custom product page with its panel on the left, built from the scene, the safe-area hook and state hooks.
 
 ```typescript
 // src/elements/ConfiguratorLayout.tsx
-import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+import { LayoutSlots } from '@salsita-ai/sdk/configurator'
 
 const SIDEBAR_WIDTH = 320
 
 export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', () => {
-  const { containerRef, safeAreaRef } = useSceneSafeArea()
+  const { containerRef, safeAreaRef } = phx.frontend.useSceneSafeArea()
 
   return (
     <div ref={containerRef} style={{ position: 'absolute', inset: 0 }}>
@@ -420,17 +471,20 @@ export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout
 ```
 
 - `LayoutSlots.SharedCanvas` renders the scene. It is absolutely positioned and fills its nearest positioned ancestor, so the layout's root is positioned and covers the page. The layout positions its own UI above the canvas and after it in the markup, as the `aside` does; unpositioned content is painted under the canvas.
-- `useSceneSafeArea()`, called without arguments, tells the camera which part of the canvas the UI leaves free. Attach `containerRef` to the element that covers the whole canvas and `safeAreaRef` to the region the scene should stay visible in: the hook measures the gap between the two and the camera frames the scene inside the safe area. Without it the scene is framed in the whole canvas. The safe-area element lies over the canvas, so it sets `pointerEvents: 'none'` to leave orbiting and clicking to the scene. A `canvasPadding` component in the spec scales the measured gaps, see [Canvas Padding](?path=/docs/layouts-canvas-padding--docs).
+- `phx.frontend.useSceneSafeArea()`, called without arguments, tells the camera which part of the canvas the UI leaves free. Attach `containerRef` to the element that covers the whole canvas and `safeAreaRef` to the region the scene should stay visible in: the hook measures the gap between the two and the camera frames the scene inside the safe area. Without it the scene is framed in the whole canvas. The safe-area element lies over the canvas, so it sets `pointerEvents: 'none'` to leave orbiting and clicking to the scene. A `canvasPadding` component in the spec scales the measured gaps, see [Canvas Padding](?path=/docs/layouts-canvas-padding--docs). Besides `phx.frontend`, `@salsita-ai/sdk/configurator` exports it.
 - The layout has to mount `LayoutSlots.SharedCanvas`, or the project sets `appLoader: legacy`. Otherwise the app loader stays on screen.
-- The layout composes the rest from what `@salsita-ai/sdk/configurator` exports: `LayoutSlots.Services` and the other members of `LayoutSlots`.
+- The layout composes the rest from what `@salsita-ai/sdk/configurator` exports: `LayoutSlots.Services` and the other members of `LayoutSlots`, which [Layout Slots](?path=/docs/phoenix-layout-slots--docs) lists with what each shows, what feeds it, what it renders when the spec configures nothing for it and what it does in read mode.
 - `LayoutSlots.DesktopSidebar` is the built-in desktop sidebar as one piece: the spec's tabs, back button, property pages and sidebar footer with their spacing, scrolling and empty states, and the assistant panel. Use it when the spec's property pages are what the customer should see and only their place changes, for example a sidebar on the left; build the controls yourself when they have to look like the brand's own. Without `width` it fills its container, so the layout positions and sizes that container; `miniSidebar` does not shrink it, so a layout that honours it reads `LayoutSlots.useSidebarContent().hasMiniSidebar` and lets the container take the sidebar's height. Its tabs sit outside it on the left; `side="start"` puts them on its right, for a sidebar on the left. In fullscreen it stays in place, transparent and inert, so a layout that wants the space back removes it while `phx.frontend.useIsFullscreenActive()` is set. See [Sidebar in a Custom Layout](?path=/docs/layouts-sidebar-in-a-custom-layout--docs).
-- Nothing of the built-in layouts is rendered for it. A project layout finalizes over the spec's `finalizeAction` components, see the finalize paragraph of [Hooks for a Project Layout](#hooks-for-a-project-layout). The `finalizePage` and `finalizeButton` components are legacy: they cannot be declared in YAML, only in TypeScript, and `Legacy.CommonFinalizePage`, which is deprecated, shows a `finalizePage` for projects that still have one. `LayoutDialog` renders only what the project registers with `createLayoutDialog` and is not part of the finalize flow. The preview start screen is `DesktopPreview` or `MobilePreview`, which the layout shows while `usePreview().isPreview` is set. Both previews frame the scene themselves, so the layout renders the component that calls `useSceneSafeArea()` only while `isPreview` is not set; it then measures when it mounts after the preview. The assistant panel is available to a project layout only inside `LayoutSlots.DesktopSidebar`.
+- Nothing of the built-in layouts is rendered for it. A project layout finalizes over the spec's `finalizeAction` components, see the finalize paragraph of [Hooks for a Project Layout](#hooks-for-a-project-layout). The `finalizePage` and `finalizeButton` components are legacy: they cannot be declared in YAML, only in TypeScript, and `Legacy.CommonFinalizePage`, which is deprecated, shows a `finalizePage` for projects that still have one. `LayoutDialog` renders only what the project registers with `createLayoutDialog` and is not part of the finalize flow. The preview start screen is `DesktopPreview` or `MobilePreview`, which the layout shows while `phx.frontend.usePreview().isPreview` is set. Both previews frame the scene themselves, so the layout renders the component that calls `phx.frontend.useSceneSafeArea()` only while `isPreview` is not set; it then measures when it mounts after the preview. The assistant panel is available to a project layout only inside `LayoutSlots.DesktopSidebar`.
 - The layout reads the state it has to react to from hooks, listed with what each returns in [Hooks for a Project Layout](#hooks-for-a-project-layout).
+- Messages for the user come one of two ways. `LayoutSlots.Services` shows violations of a rejected change, side-effect hints, errors and failed saves as the built-in snackbars, which render into `LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot` wherever the layout mounts it. `phx.frontend.useConfiguratorMessages(onMessage)` hands the same messages to the layout's own UI instead, with their text resolved, as the toast in [Custom Layout](?path=/docs/layouts-custom-layout--docs#show-messages) does; mount one of the two, not both, or every message is shown twice. A failure to save the configuration, and the first successful save after it, are messages too, so a layout that mounts neither shows no sign of a failed save. An error of the built-in finalize and other actions stays a snackbar either way. It renders into the snackbar root, so a layout that mounts none shows it outside the configurator, in the page's `body`. A failure to start a configuration from a preset is not a message of the hook either: it happens on the preset screen, before any `ConfiguratorLayout` mounts. In production with more than one preset it is a snackbar there, also on a preset screen replaced with `createPresetUi` (see [Preset UI](#preset-ui)), which reads the error from `phx.frontend.usePresetSelection().selectionError` and mounts `PresetSnackbarsRoot` to keep the snackbar inside the configurator. With a single preset it is the [Configurator Error Page](#configurator-error-page). A finalize action the layout runs with `phx.frontend.useFinalizeActions` or `phx.frontend.useFinalizeAction` reports its error as the action's `error` instead, neither as a message nor as a snackbar.
 - Any project layout element named `ConfiguratorLayout` takes over the page.
 
+`defaultConfiguratorElements`, exported from `@salsita-ai/sdk/configurator`, holds the built-in UI as a `ConfiguratorLayout` registration that renders the layout the spec selects, the built-in not-found page as a `ConfigurationNotFoundPage` registration, the built-in not-authenticated page as a `NotAuthenticatedPage` registration, the built-in preset screen as a `PresetUi` registration, and the built-in error page as a `ConfiguratorErrorPage` registration. Generated code registers these defaults with `withDefaultElements`, apart from the project's elements, so the built-in UI is a registration like any other; a project element registered under the same name wins over a default. The list also holds the configurator's built-in controls and layout elements under the kinds the spec names them by, such as `attributeSelect` or `undoToolbarButton`, so a project element registered under one of those names replaces the built-in one wherever the spec names that kind. A config assembled by hand, without generated code, calls `withDefaultElements(defaultConfiguratorElements)` too; the lists are the only way the built-in elements are registered, so without it the page shows a "not found" box instead of the configurator, and a project layout shows one in place of every built-in control. The admin mounts a full configurator, so its list, `defaultAdminElements` from `@salsita-ai/sdk/admin`, holds the configurator's defaults followed by the admin's built-in pages, sidebars and actions; generated admin code passes it to `withDefaultElements` in place of `defaultConfiguratorElements`, because each call replaces the defaults passed before.
+
 #### Hooks for a Project Layout
 
-A project layout reads the product and the configurator's state through hooks, and changes them through the functions the hooks return. Each row names where its hook comes from; the `phx.frontend` hooks in these tables are also exported from `@salsita-ai/sdk/react` under the same name. No hook looks at read mode: the control hooks and the navigation and fullscreen setters keep working while `accessInfo.viewMode` is `true`, so the layout decides what a viewer can change.
+A project layout reads the product and the configurator's state through hooks, and changes them through the functions the hooks return. Every hook in these tables is a member of `phx.frontend` and is also exported from `@salsita-ai/sdk/react` under the same name, unless its row names another export. No hook looks at read mode: the control hooks and the navigation and fullscreen setters keep working while `accessInfo.viewMode` is `true`, so the layout decides what a viewer can change.
 
 **The product**
 
@@ -453,36 +507,121 @@ The other control hooks in [Controls](#controls) take the same two arguments, `u
 
 **Texts**
 
-Texts from the spec, such as option titles and the `detail` fields, are `Localizable`, not `string`. `useResolveLocalizable()` from `@salsita-ai/sdk/react` returns a function that turns one into a string in the current language, which suits a list; `useLocalizable(text)` and `<LocalizableMessage>` resolve a single text, see [Localization](?path=/docs/phoenix-localization--docs).
+Texts from the spec, such as option titles and the `detail` fields, are `Localizable`, not `string`. `phx.frontend.useResolveLocalizable()` returns a function that turns one into a string in the current language, which suits a list; `phx.frontend.useLocalizable(text)` and `<LocalizableMessage>` from `@salsita-ai/sdk/react` resolve a single text, see [Localization](?path=/docs/phoenix-localization--docs).
 
 **Mode, fullscreen, preview and navigation**
 
-| Hook                                                                         | Returns                                                                                                                                                                                                                                                                  |
-| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `phx.frontend.useAccessService()`                                            | `{ configurationId, accessInfo }`. `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property.                                                                                               |
-| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | The fullscreen flag, a `boolean`, and a function `(enabled: boolean) => void` that sets it.                                                                                                                                                                              |
-| `usePreview()` from `@salsita-ai/sdk/configurator`                           | `{ isPreview, isExpanded, isPreviewEnabled, isHidden, enter, leave }`. The layout shows a preview start screen while `isPreview` is `true`.                                                                                                                              |
-| `phx.frontend.useActiveNavigationState()`                                    | The active navigation state, one of the spec's `navigationStates`.                                                                                                                                                                                                       |
-| `phx.frontend.usePushNavigate()` and `phx.frontend.usePopNavigate()`         | `(state) => void`, which enters a state and remembers the active one, and `() => void`, which returns to the remembered state and does nothing when there is none. `phx.frontend.useNavigate()` returns `(state) => void`, which enters a state and forgets the history. |
-| `phx.frontend.useActiveViewState()` and `phx.frontend.useActiveToolState()`  | The active view state and tool state.                                                                                                                                                                                                                                    |
-| `useActiveViewports()` from `@salsita-ai/sdk/react`                          | The responsive breakpoints the configurator's container satisfies, as `Viewport[]`, or `null` before it is measured. It follows the container, not the window, so it is the switch between a desktop and a phone layout.                                                 |
+| Hook                                                                         | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `phx.frontend.useAccessService()`                                            | `{ configurationId, accessInfo }`. `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | The fullscreen flag, a `boolean`, and a function `(enabled: boolean) => void` that sets it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `phx.frontend.usePreview()`                                                  | `{ isPreview, isExpanded, isPreviewEnabled, isHidden, enter, leave }`. The layout shows a preview start screen while `isPreview` is `true`. Besides `phx.frontend`, `@salsita-ai/sdk/configurator` exports it, not `@salsita-ai/sdk/react`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `phx.frontend.useCloseAction()`                                              | The host's close action, `() => Promise<void>`, or `null` when the integration mode offers none. It dispatches the web component's `close` event and, depending on the integration mode, first leaves for the go-back URL of the page's query or puts the configurator on standby. Besides `phx.frontend`, `@salsita-ai/sdk/configurator` exports it, not `@salsita-ai/sdk/react`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `phx.frontend.useActiveNavigationState()`                                    | The active navigation state, one of the spec's `navigationStates`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `phx.frontend.usePushNavigate()` and `phx.frontend.usePopNavigate()`         | `(state) => void`, which enters a state and remembers the active one, and `() => void`, which returns to the remembered state and does nothing when there is none. `phx.frontend.useNavigate()` returns `(state) => void`, which enters a state and forgets the history.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `phx.frontend.useActiveViewState()` and `phx.frontend.useActiveToolState()`  | The active view state and tool state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `phx.frontend.useSetViewState()`                                             | `(state) => void`, which makes the given view state, one of the spec's `viewStates`, the active one; setting the active state again keeps it. Cameras and components filtered by `viewStates` follow the change.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `phx.frontend.useResetCamera()`                                              | `() => void`, which moves the camera back to the framing of the active camera configuration, undoing the user's orbit, pan and zoom, as the toolbar's reset button does. Besides `phx.frontend`, `@salsita-ai/sdk/configurator` exports it, not `@salsita-ai/sdk/react`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `phx.frontend.useUndoRedo()`                                                 | `{ canUndo, canRedo, undo, redo }`: whether the undo history has a change to undo or to redo, and two `() => void` functions that undo or redo it, as the toolbar's undo and redo buttons do, pushing the same analytics events; each does nothing while there is nothing to undo or redo. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `phx.frontend.useTabNavigation(options?)`                                    | `{ source, tabs, activeTab, select }` for the spec's tabs: `source` is `'sidebarTabs'` (every active `sidebarTabs` of the selected entity, in spec order) or `'horizontalTabs'` (the first active `horizontalTabs`), or `null` without tabs. Each tab is `{ index, label, icon, iconNode, navigationStates, state, isActive }`, with the label resolved, `icon` a PhxIcon name and `iconNode` a React node given by TypeScript spec code; `activeTab` is the first active tab or `null`. `select(index or navigation state)` enters the tab's first navigation state, as the built-in tabs do, pushing the same analytics event for `horizontalTabs`. `options.source` (`'auto'`, `'sidebarTabs'` or `'horizontalTabs'`) chooses the kind; `'auto'` prefers `sidebarTabs` when both are active, with a warning in development. `options.entityId` reads another entity's `sidebarTabs`. A tab without navigation states is left out, with a warning in development. It does not check read mode. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                   |
+| `phx.frontend.useStepNavigation()`                                           | `{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }` for the spec's `navigationSteps`, read from the first active instance on the root entity, the one the built-in layout shows. Each step is `{ index, label, navigationStates, state, status }`, with the label resolved, `state` the navigation state that enters the step and `status` `'complete'`, `'active'` or `'upcoming'`; while the active navigation state belongs to no step, `activeStep` is `null`, `activeIndex` is -1, every step is `'upcoming'` and the next step is the first one. A single step is both first and last. `next()` and `previous()` enter the following or preceding step, as the built-in step buttons do, pushing the same analytics events; `goTo(index or navigation state)` enters any step, as the header's stepper does, pushing its event. Each does nothing without a step to enter. A step without navigation states is left out, with a warning in development. It enforces no order and does not check read mode. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it. |
+| `phx.frontend.useActiveViewports()`                                          | The responsive breakpoints the configurator's container satisfies, as `Viewport[]`, or `null` before it is measured. It follows the container, not the window, so it is the switch between a desktop and a phone layout. `desktop` is a container wider than 768 pixels and `mobile` one at most 768 pixels wide; `phone` is narrower than 480 and `tablet` between 480 and 1024 pixels; `landscape` and `portrait` follow the browser window's orientation. The built-in layout uses its phone arrangement unless `desktop` is active.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+
+**Steps and tabs**
+
+A project layout builds its steps and tabs from the spec, so the structure stays in `navigationSteps`, `sidebarTabs` and `horizontalTabs`, where `$filter` switches it, and the layout decides how it looks. `phx.frontend.useStepNavigation()` gives a wizard its steps with a `status` each, and `next`, `previous` and `goTo`; `phx.frontend.useTabNavigation()` gives tabs with `isActive` each, and `select`. Both enter a navigation state, so controls, cameras and components filtered by `navigationStates` follow. Neither hides anything in read mode or blocks a step on violations: a layout that should not move on while the configuration is invalid combines `canGoNext` with `useStateValidity()`, and a stepper that offers only earlier steps enables the steps whose `status` is `'complete'`.
+
+```tsx
+export const Wizard = () => {
+  const { steps, activeStep, canGoNext, canGoPrevious, next, previous, goTo } = phx.frontend.useStepNavigation()
+
+  return (
+    <nav aria-label="Steps">
+      <ol>
+        {steps.map(step => (
+          <li key={step.state} aria-current={step.status === 'active' ? 'step' : undefined}>
+            <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" onClick={next}>
+          Next: {steps[(activeStep?.index ?? -1) + 1]?.label}
+        </button>
+      )}
+    </nav>
+  )
+}
+```
 
 **Violations**
 
-| Hook                                   | Returns                                                                                                                                                                                                                                                                                                                         |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `phx.frontend.useStateValidity()`      | The validity of the last committed state: `{ valid: true, severity: null }`, or `{ valid: true, severity: 'notice' \| 'warning', entityViolations }`. A change that leaves a `fixable` or `fatal` violation is rejected and never committed, and neither is a change during which an error was thrown, so neither is seen here. |
-| `phx.frontend.useFinalizeViolations()` | `{ disabled, hints, violations }`. `disabled` is `true` while a `warning`, `fixable` or `fatal` violation holds or the configuration failed to save; `hints` is the violations' text, or `undefined`.                                                                                                                           |
+| Hook                                              | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useStateValidity()`                 | The validity of the last committed state: `{ valid: true, severity: null }`, or `{ valid: true, severity: 'notice' \| 'warning', entityViolations }`. A change that leaves a `fixable` or `fatal` violation is rejected and never committed, and neither is a change during which an error was thrown, so neither is seen here.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `phx.frontend.useFinalizeViolations()`            | `{ disabled, hints, violations }`. `disabled` is `true` while a `warning`, `fixable` or `fatal` violation holds or the configuration failed to save; `hints` is the violations' text, or `undefined`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `phx.frontend.useConfiguratorMessages(onMessage)` | Nothing. It calls `onMessage(message)` once per message: `{ kind: 'violation', entityId, violation, text }` for each violation of the rejected state, including notices and warnings already present, so `violation.severity` tells the reason for the rejection (`fixable` or `fatal`) from them, `{ kind: 'sideEffect', text }` for each hint of a committed update, `{ kind: 'error', error, text }` when an error is thrown while a change is validated, with `text` the generic "Oops, something went wrong", `{ kind: 'saveError', error, text }` each time saving the configuration fails, with `error` what the save rejected with and `text` a generic message, and `{ kind: 'saveRecovery', text }` when a save succeeds after a failed one, with `text` "Configuration updated". `text` is resolved to the current language; a violation's is its `message`, or its `type` without one, and the built-in snackbar prefixes it with `entityId`. Hints committed before the layout mounted are not delivered, nor is a save that failed before it mounted; when the most recent change was rejected or threw, its messages are delivered again when the hook mounts. `onMessage` may be a new function on every render. On `phx.frontend` the message is typed by the project, so `violation.type` narrows to its violation types; from `@salsita-ai/sdk/react` the type is `ConfiguratorMessage`. |
+| `phx.frontend.useFinalizeAction(handler)`         | `{ run, isPending, error, disabled, hints }` for the `finalizeAction` whose `handler` it is given; see the Finalize paragraph below for how to call it. `run()` records the finalize-button click for analytics and runs the project's handler, does nothing while `disabled` or `isPending`, and returns a promise that resolves once the handler has settled and never rejects; `error` is what the handler's last run rejected with, or `null`; `disabled` and `hints` are those of `useFinalizeViolations()`. The type of the result is `UseFinalizeActionResult` from `@salsita-ai/sdk/configurator`, which also exports the hook.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `phx.frontend.useFinalizeActions()`               | `{ actions, primary, secondary, disabled, hints }`: every active `finalizeAction` of the spec in spec order, `primary` the first `'primary'` one, or else the first, or `null`, and `secondary` the others; see the Finalize paragraph below. Each action is `{ key, handler, variant, label, title, icon, run, isPending, error, disabled }`, with `label` and `title` resolved; `run()` records the finalize-button click for analytics and runs the action's handler, does nothing while `disabled` or `isPending`, and returns a promise that never rejects. `disabled` and `hints` are those of `useFinalizeViolations()`. Besides `phx.frontend`, `@salsita-ai/sdk/react` exports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 
-`LayoutSlots.Services` shows rejected changes, errors and side-effect hints as snackbars, rendered into `LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`. No hook delivers them to a layout's own UI.
+`LayoutSlots.Services` shows every message of `useConfiguratorMessages` as a snackbar, `saveError` and `saveRecovery` included; see the messages paragraph of [Loaded Configuration UI](#loaded-configuration-ui) for choosing between the two and for the messages that stay snackbars.
 
 **Finalize**
 
-A project layout finalizes over the spec's `finalizeAction` components. `phx.frontend.useComponents({ componentTypes: [finalizeActionComponent] })`, with `finalizeActionComponent` from `@salsita-ai/sdk/domain`, lists them; each `state` is `{ variant, label, title, icon, handler }`, where `variant` is `'primary'` or `'secondary'` and `handler` names the project's handler registered with `phx.frontend.createPhoenixHandler`. The built-in footer offers the first `'primary'` action, or else the first action, as its button and the others in a menu, and disables them with `phx.frontend.useFinalizeViolations()`.
+A project layout finalizes over the spec's `finalizeAction` components, each `{ variant, label, title, icon, handler }`, where `variant` is `'primary'` or `'secondary'` and `handler` names the project's handler registered with `phx.frontend.createPhoenixHandler`. `phx.frontend.useFinalizeActions()` is the convenient way: it lists them with what a button needs, runs their handlers itself, and can be called anywhere in the layout, including a dialog the layout opens with `useModal`, as often as it likes. It returns:
+
+- `actions`, every active `finalizeAction` in spec order, and `primary` and `secondary`, the same actions split as the built-in footer splits them: `primary` is the first `'primary'` action, or else the first action, or `null` without any, and `secondary` the others in spec order.
+- `disabled` and `hints`, those of `useFinalizeViolations()`: finalizing is not possible while a `warning`, `fixable` or `fatal` violation holds or the configuration failed to save, and `hints` says why.
+
+Each action has `key`, a stable key for React, `handler`, `variant`, `label` and `title` resolved to the current language, `icon`, a `PhxIcon` name, and:
+
+- `run()`, which records the finalize-button click for analytics and then runs the handler. It does nothing while `disabled` or `isPending`. It returns a promise that resolves once the handler has settled and never rejects, so a menu or a sheet can close after it.
+- `isPending`, `true` while the handler runs.
+- `error`, what the handler's last run rejected with, or `null`; a rejection that is not an `Error` is wrapped in one, with the value as its `cause`. It is cleared when the action runs again. No snackbar is raised; the layout shows the error its own way. A handler that throws while it is loaded, for example because it calls a hook that needs a provider the configurator does not have, makes `error` that error and the action `disabled`.
+- `disabled`, `true` while finalizing is not possible, or when the handler could not be loaded.
+
+```tsx
+export const Finalize = () => {
+  const { accessInfo } = phx.frontend.useAccessService()
+  const { primary, secondary, hints } = phx.frontend.useFinalizeActions()
+
+  if (accessInfo.viewMode || !primary) {
+    return null
+  }
+
+  return (
+    <div>
+      <button
+        type="button"
+        disabled={primary.disabled || primary.isPending}
+        onClick={() => void primary.run()}
+        title={hints}
+      >
+        {primary.isPending ? 'Sending…' : primary.label}
+      </button>
+      {primary.error && <p role="alert">{primary.error.message}</p>}
+      {secondary.map(action => (
+        <button key={action.key} type="button" disabled={action.disabled} onClick={() => void action.run()}>
+          {action.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+```
+
+The configurator runs the handlers outside the layout, beside it, whenever a configuration is open, also in read mode and on every step. A handler can use what the configurator provides, such as `useModal`, but not a provider the layout itself adds; such a handler fails to load and shows as that action's `error`. An action's `isPending` and `error` are kept while the layout re-renders and while its components unmount and mount again.
+
+To run a single action the layout already knows, `phx.frontend.useFinalizeAction(handler)` runs it in the layout itself and returns `{ run, isPending, error, disabled, hints }`, with the same meaning. It runs the project's handler factory, which calls hooks, so the layout calls it once per component, never in a loop or conditionally, and wraps that component in `<PhoenixHandlerBoundary name={handler}>` from `@salsita-ai/sdk/react`, so an edited handler takes effect without a reload. Its `isPending` and `error` belong to the mounted component: when it unmounts during a run, the handler keeps running, and a component mounted afterwards starts with `isPending` false and no `error`. [Custom Layout](?path=/docs/layouts-custom-layout--docs#request-a-quote) runs a finalize action this way from its review step.
 
-To offer the same buttons, a project layout mounts `<FinalizeActions />` from `@salsita-ai/sdk/configurator`: the built-in footer's finalize buttons, the primary action plus a menu of the others, disabled with the hints of `useFinalizeViolations()`, with a spinner while the handler runs and a snackbar when it fails. It renders nothing without a `finalizeAction`, and it does not check read mode, so a layout hides it while `accessInfo.viewMode` is `true`.
+Neither hook checks read mode, so the layout hides finalizing while `accessInfo.viewMode` is `true`, as above.
 
-To build its own buttons, a layout runs an action with `usePhoenixHandler(action.state.handler).handler()` from `@salsita-ai/sdk/react`, which returns a promise. `usePhoenixHandler` runs the project's handler factory, which calls hooks, so each action gets its own component that calls it once, never in a loop, and that component is wrapped in `<PhoenixHandlerBoundary name={action.state.handler}>` from the same import, so an edited handler takes effect without a reload. The layout then shows the pending state, the error and the disabled state from `useFinalizeViolations()` itself.
+Instead of its own buttons, a project layout can mount `<FinalizeActions />` from `@salsita-ai/sdk/configurator`: the built-in footer's finalize buttons, the primary action plus a menu of the others, disabled with the hints of `useFinalizeViolations()`, with a spinner while the handler runs and a snackbar when it fails. It renders nothing without a `finalizeAction`, and it does not check read mode either.
 
 ## TransformerBuilder
 
@@ -566,7 +705,7 @@ const NotAuthorizedAdminPage = phx.frontend.admin.createNotAuthorizedAdminPage((
 ```
 
 When no authentication-error page is registered, Phoenix falls back to the registered not-authorized page and then
-to the default configuration-not-found page.
+to the built-in configuration-not-found page. The admin shows the built-in page even when the project registers a `ConfigurationNotFoundPage`, see [Configuration Not Found Page](#configuration-not-found-page).
 
 ## What We Learned
 

package/dist/docs/phoenix/deployments.mdx

@@ -281,9 +281,7 @@ Phoenix provides two helper functions for reading environment variables with val
 **`createEnvReader`** - General purpose environment reader used in frontend and deployment contexts:
 
 ```typescript
-import { bool, str } from 'envalid'
-
-import { createEnvReader } from '@salsita-ai/sdk/common/env'
+import { bool, createEnvReader, str } from '@salsita-ai/sdk/common/env'
 
 // Create a reader function
 const readEnv = createEnvReader({
@@ -301,9 +299,7 @@ console.log(env.SERVER_URL) // Typed and validated
 
 ```typescript
 // webhooks/webhooks.config.ts
-import { str } from 'envalid'
-
-import { createEnvReader } from '@salsita-ai/sdk/common/env'
+import { createEnvReader, str } from '@salsita-ai/sdk/common/env'
 
 export const readRuntimeConfig = createEnvReader({
   AWS_S3_PUBLIC_RESOURCES_BUCKET: str(),

package/dist/docs/phoenix/domain-model.mdx

@@ -329,6 +329,8 @@ components:
 
 The code generator will automatically create an expression with the same name and infer the return type based on usage context.
 
+The type of an expression must share values with the type every component expects where it is read, and with its declared type. An expression declared as a number and read into a `title`, or one read both into a `title` and into `offsetX`, has no value its implementation could return, so the build reports `EXPRESSION_READ_TYPE_CONFLICT` at the expression and names each place it is read. A type given only as `tsType` is not checked here.
+
 ## Constants
 
 Constants are pre-generated expressions that return fixed values. Under the hood, they are implemented as expressions but are automatically generated by the Phoenix system, so you don't need to write TypeScript implementation code for them.

package/dist/docs/phoenix/finalization.mdx

@@ -15,7 +15,7 @@ Finalization is Phoenix's system for completing configurator sessions and proces
 
 > For integration-specific finalization flows — how host-specific data is passed in and how the host is notified on completion (event dispatch in `headless`, redirect in `handoff`) — see [Finalization (Internal)](?path=/docs/phoenix-integration-finalization-internal--docs) and [Finalization (External)](?path=/docs/phoenix-integration-finalization-external--docs).
 
-The universal sidebar footer offers the spec's `finalizeAction` components: Phoenix selects one primary footer action and places additional finalization actions in its menu. It never opens a `finalizePage`; the `finalizePage` and `finalizeButton` components are legacy, declared only in TypeScript, and used by the basic sidebar footer and the legacy layouts. Built-in finalization actions use configuration validity to disable the footer action and provide pending and generic error states, including for add-to-cart handlers. See [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) for the layout behavior.
+The universal sidebar footer offers the spec's `finalizeAction` components: Phoenix selects one primary footer action and places additional finalization actions in its menu. It never opens a `finalizePage`; the `finalizePage` and `finalizeButton` components are legacy, declared only in TypeScript, and used by the basic sidebar footer and the legacy layouts. Built-in finalization actions use configuration validity to disable the footer action and provide pending and generic error states, including for add-to-cart handlers. See [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) for the layout behavior. A project layout (`ConfiguratorLayout`) offers the same actions with its own buttons through `phx.frontend.useFinalizeActions`, which lists them with the primary one picked as the footer picks it, each with its own `run`, pending state, error and disabled state, or through `phx.frontend.useFinalizeAction`, which runs one known action's handler and returns the same state with hints; see the Finalize paragraph of [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
 
 ## How Finalization Works
 

package/dist/docs/phoenix/getting-started.mdx

@@ -22,10 +22,11 @@ The frontend SDK provides the core libraries and components for building configu
 
 The Phoenix CLI (`phoenix` command) is the unified tool for all configurator development. It combines domain code generation, webhook building, deployment management, and development workflows into a single interface:
 
-- `phoenix init` - Start a new project with a working starter spec
+- `phoenix init` - Start a new project: a working starter spec and a `package.json` with the SDK, the packages it requires next to it, ESLint and Prettier
 - `phoenix dev` - Start the development server with hot reload
 - `phoenix build` - Build the configurator for production
-- `phoenix sync` - Synchronize dependencies and generated code
+- `phoenix sync` - Regenerate the generated code and project files
+- `phoenix deps` - Add the SDK's missing peer dependencies to `package.json` and move out-of-range ones into range
 - `phoenix check` - Validate domain configuration and code
 - `phoenix fix` - Auto-fix common issues in domain files
 
@@ -57,12 +58,14 @@ This section provides practical guidance for developers who are new to Phoenix P
 
 Before diving into Phoenix Platform development, ensure you have:
 
-- **Node.js** and **pnpm** - Required versions are set automatically in the project
+- **Node.js 22.13 or newer** and **a package manager** - The SDK and the Phoenix CLI run on Node.js 22.13 or newer (see [Starting a New Project](?path=/docs/phoenix-phoenix-cli--docs#starting-a-new-project)). A project installs with any package manager; with pnpm 11 it needs the settings in [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager)
 - **JavaScript/TypeScript** - Phoenix generates TypeScript code and uses modern JavaScript patterns
 - **React** - The platform builds on React components, hooks, and modern React patterns
 - **Three.js** - Basic knowledge of 3D graphics, scenes, cameras, and rendering concepts
 - **React Three Fiber** - Understanding of declarative 3D development and R3F component patterns
 
+The commands in this documentation use pnpm, as in `pnpm phoenix sync`. They work the same through any other package manager: `npx phoenix sync` with npm, `yarn phoenix sync` with Yarn, `bunx phoenix sync` with Bun.
+
 We assume you have working knowledge of these technologies before starting with Phoenix Platform. If you're new to any of these areas, we recommend familiarizing yourself with them first, as Phoenix Platform builds directly on these foundations.
 
 ### Your First Steps