@salsita-ai/sdk 0.50.0-develop.2331d4a6b7 → 0.50.0-develop.26a71cda28

package/dist/docs/other-features/violation-messages.mdx

@@ -153,10 +153,10 @@ The `formatControlViolationMessage` function is where the magic happens. It rece
 3. **Actionable guidance**: Tell users exactly what values are valid or how to fix the problem
 4. **Consistent terminology**: Use the same terms and units throughout your application
 
-Implement violations with custom message formatting in your domain TypeScript file:
+Implement violations with custom message formatting in a file of `src/invariants/`:
 
 ```typescript
-// domain/index.ts
+// src/invariants/invariants.ts
 
 // Pre-define translatable labels for nested localization
 const colorLabels = {
@@ -166,60 +166,56 @@ const colorLabels = {
   yellow: msg`yellow`,
 } as const
 
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Scene: {
-        itIsNotZero: s => {
-          if (s.x !== 0) {
-            return [
-              {
-                type: 'itIsNotZero',
-                severity: 'fatal',
-                message: 'Scene is not zero',
-                controlViolationPriority: 1,
-                formatControlViolationMessage: () => {
-                  return msg({
-                    message: `Scene is not zero: The position would be ${s.x} which is not equal to 0`,
-                  })
-                },
-              },
-            ]
-          }
-          return []
-        },
-        // ... tooMuchRight omitted for brevity ...
-
-        // Static violation: severity, message and controlViolationPriority
-        // are declared in YAML. Implementation only returns a boolean.
-        wayTooFarRight: s => s.x < 200,
-
-        colorPositionIncompatible: s => {
-          const compatibleColors = ['red', 'blue', 'green'] as const
-          if (s.x >= 200 && !compatibleColors.includes(s.color)) {
-            return [
-              {
-                type: 'colorPositionIncompatible',
-                severity: 'fatal',
-                message: 'Color is not compatible with far right position',
-                controlViolationPriority: 3,
-                formatControlViolationMessage: (_emission, { i18n }) => {
-                  const labels = new Intl.ListFormat(i18n.locale, {
-                    style: 'long',
-                    type: 'disjunction',
-                  }).format(compatibleColors.map(c => i18n.t(colorLabels[c])))
-
-                  return msg({ message: `Far right position is only available for ${labels}` })
-                },
-              },
-            ]
-          }
-          return []
-        },
-      },
-    })
-  )
-  .buildViolationExpressions()
+export default phx.domain.implementCustomInvariants({
+  Buckyball: {
+    itIsNotZero: s => {
+      if (s.x !== 0) {
+        return [
+          {
+            type: 'itIsNotZero',
+            severity: 'fatal',
+            message: 'Scene is not zero',
+            controlViolationPriority: 1,
+            formatControlViolationMessage: () => {
+              return msg({
+                message: `Scene is not zero: The position would be ${s.x} which is not equal to 0`,
+              })
+            },
+          },
+        ]
+      }
+      return []
+    },
+    // ... tooMuchRight omitted for brevity ...
+
+    // Static violation: severity, message and controlViolationPriority
+    // are declared in YAML. Implementation only returns a boolean.
+    wayTooFarRight: s => s.x < 200,
+
+    colorPositionIncompatible: s => {
+      const compatibleColors = ['red', 'blue', 'green'] as const
+      if (s.x >= 200 && !compatibleColors.includes(s.color)) {
+        return [
+          {
+            type: 'colorPositionIncompatible',
+            severity: 'fatal',
+            message: 'Color is not compatible with far right position',
+            controlViolationPriority: 3,
+            formatControlViolationMessage: (_emission, { i18n }) => {
+              const labels = new Intl.ListFormat(i18n.locale, {
+                style: 'long',
+                type: 'disjunction',
+              }).format(compatibleColors.map(c => i18n.t(colorLabels[c])))
+
+              return msg({ message: `Far right position is only available for ${labels}` })
+            },
+          },
+        ]
+      }
+      return []
+    },
+  },
+})
 ```
 
 ### Internationalization with Dynamic Content

package/dist/docs/phoenix/admin.mdx

@@ -421,49 +421,34 @@ export const handler = webhookBuilder
 
 The publishing workflow validates admin state, transforms entities, and stores JSON to S3. Configurators access published data via `ctx.publishedData` in expressions.
 
-For implementation examples, see `packages/demos/demo-finalize/src/handlers/map-published-revision-data.ts`.
+For implementation examples, see `packages/demos/demo-catalog-builder/src/handlers/map-published-chunked-data.ts`.
 
 For technical details about data transformation and storage, see [Data Sources - Published Data](?path=/docs/phoenix-data-sources--docs#published-data).
 
 ## Web Component Integration
 
-Admin functionality integrates through the configurator builder rather than requiring separate web component setup.
+Admin functionality is part of the same application as the configurator and needs no separate web component setup.
 
-### Configurator Builder Setup
+### Registering Admin Components
 
-In phx-cli projects, frontend entry is auto-generated in `.phoenix/`. Admin components are registered through `src/admin/components/`:
+The frontend entry is generated into `.phoenix/`, so a project never calls the configurator builder itself. Every file
+in `src/admin/components/` is picked up by its location and its default export is registered as admin components:
 
 ```typescript
 // src/admin/components/admin-components.tsx
-import { configuratorBuilder } from '.phoenix/frontend.js'
-import { customAdminOptics } from './optics.js'
-import { NotAuthenticatedPage } from '../pages/NotAuthenticatedPage.js'
-
-const config = configuratorBuilder
-  .withComponentOptics(customConfiguratorComponents)
-  .withAdminComponentOptics(customAdminOptics) // Register admin components
-  .buildConfig({
-    deploymentId: phx.runtimeConfig.DEPLOYMENT_ID,
-    persistence: {
-      type: 'server',
-      serverUrl: phx.runtimeConfig.SERVER_URL,
-    },
-    ui: {
-      notAuthenticatedPage: <NotAuthenticatedPage />, // Show when user not authenticated
-    },
-    // ... other config
-  })
+// ... customAdminOptics as defined in the example above
 
-phx.frontend.mountApplication(config)
+export default customAdminOptics
 ```
 
-Admin component files go in `src/admin/components/` and are automatically discovered by phx-cli.
+The page shown to a user who is not authenticated is an element. Create it with
+`phx.frontend.createNotAuthenticatedPage(...)` in a file under `src/elements/`.
 
 ### Built-in Admin Integration
 
 Phoenix automatically provides admin functionality when:
 
-1. Admin components are registered via `withAdminComponentOptics()`
+1. Admin components are default-exported from files in `src/admin/components/`
 2. Admin configuration exists in `phoenix.config.ts`
 3. User has admin session token
 
@@ -515,4 +500,4 @@ Ready to implement admin functionality in your Phoenix project? Here's what to e
 - **[Sessions and Access](?path=/docs/phoenix-sessions-and-access--docs)** - Understand admin authentication and permissions
 - **[Connected Data Sources](?path=/docs/phoenix-connected-data-sources--docs)** - Wire `$data` entries to Google Sheets or Excel; requires the embedded admin mode
 
-For hands-on examples, check out the finalize demo (`packages/demos/demo-finalize/`) which shows spec-driven admin using `createAdminPages` for presets and recipes. This demo demonstrates the YAML-based admin approach with publishing workflows rather than custom admin UI components.
+For hands-on examples, check out the Catalog Builder demo (`packages/demos/demo-catalog-builder/`), which shows spec-driven admin pages over connected and generated data, custom catalog pages beside them, admin model migrations, and the publishing workflow.

package/dist/docs/phoenix/best-practices.mdx

@@ -5,6 +5,7 @@
 1. **YAML is king** - 99% of configuration should be in spec/\*.yaml files
 2. **Custom code locations** (in order of preference):
    - `src/expressions/` - Computed/derived properties
+   - `src/actions/` - Named domain operations declared under `actions:`
    - `src/invariants/` - Business rule constraints
    - `src/transformers/` - Automatic state fixers
    - `src/handlers/` - Event & lifecycle handlers

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

@@ -25,8 +25,9 @@ The configurator interface is generated in `.phoenix/configurator-interface.ts`:
 
 ```typescript
 // .phoenix/configurator-interface.ts (AUTO-GENERATED - DO NOT EDIT)
-import {'{'} createConfiguratorInterface {'}'} from '@salsita-ai/sdk/configurator'
-import {'{'} configuratorBuilder {'}'} from './domain.js'
+import { createConfiguratorInterface } from '@salsita-ai/sdk/configurator'
+
+import { configuratorBuilder } from './domain.js'
 
 export const configuratorInterface = createConfiguratorInterface(configuratorBuilder)
 
@@ -64,9 +65,9 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 Access the configurator interface via `phx.frontend`:
 
 ```typescript
-export const CustomComponent = () => {'{'}
+export const CustomComponent = () => {
   // Access domain systems
-  const {'{'} navigationSystem, storeSystem {'}'} = phx.frontend.useDomain()
+  const { navigationSystem, storeSystem } = phx.frontend.useDomain()
 
   // Entity state hooks
   const rootEntity = phx.frontend.useRootEntityState()
@@ -76,11 +77,11 @@ export const CustomComponent = () => {'{'}
   const selectEntity = phx.frontend.useSelectEntity()
 
   // Type-safe entity access
-  if (selectedEntity && Cabinet.is(selectedEntity)) {'{'}
+  if (selectedEntity && Cabinet.is(selectedEntity)) {
     // selectedEntity is now typed as $Cabinet
     console.log(selectedEntity.width, selectedEntity.$area)
-  {'}'}
-{'}'}
+  }
+}
 ```
 
 ## Core Hooks
@@ -90,16 +91,16 @@ The configurator interface provides 100+ hooks organized by category. Use TypeSc
 ### Domain & Application Context
 
 ```typescript
-const ExampleComponent = () => {'{'}
+const ExampleComponent = () => {
   // Core domain systems
-  const {'{'} navigationSystem, storeSystem, entitySystem {'}'} = phx.frontend.useDomain()
+  const { navigationSystem, storeSystem, entitySystem } = phx.frontend.useDomain()
 
   // Domain application context
-  const {'{'} configurationPersistSystem {'}'} = phx.frontend.useDomainApplication()
+  const { configurationPersistSystem } = phx.frontend.useDomainApplication()
 
   // Full configurator context
-  const {'{'} imageRenderingSystem {'}'} = phx.frontend.useConfigurator()
-{'}'}
+  const { imageRenderingSystem } = phx.frontend.useConfigurator()
+}
 ```
 
 ### State Subscriptions
@@ -157,26 +158,31 @@ const viewState = phx.frontend.useActiveViewState()
 const toolState = phx.frontend.useActiveToolState()
 
 // Navigation actions
-const navigate = phx.frontend.useNavigate()
-const pushNavigate = phx.frontend.usePushNavigate()
-const popNavigate = phx.frontend.usePopNavigate()
+const navigate = phx.frontend.useNavigate() // navigate(state) replaces the active state and clears the history
+const pushNavigate = phx.frontend.usePushNavigate() // pushNavigate(state) remembers the active state for popNavigate
+const popNavigate = phx.frontend.usePopNavigate() // popNavigate() returns to the remembered state, if there is one
+
+// 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)
 ```
 
 ### Controls
 
 ```typescript
-// Control hooks for UI inputs
-const swatchSelection = phx.frontend.useSwatchSelection(entityId, controlId)
-const textValue = phx.frontend.useTextValue(entityId, controlId)
-const attributeSelection = phx.frontend.useAttributeSelection(entityId, controlId)
-const attributeSwitch = phx.frontend.useAttributeSwitch(entityId, controlId)
-const distanceDimension = phx.frontend.useDistanceDimension(entityId, controlId)
-const angleDimension = phx.frontend.useAngleDimension(entityId, controlId)
-const genericDimension = phx.frontend.useGenericDimension(entityId, controlId)
+// Control hooks for UI inputs: the entity id and the instance name of the control component on it
+// useSwatchSelection requires its third argument, the fixable violation types
+const swatchSelection = phx.frontend.useSwatchSelection(entityId, instanceName, [])
+const textValue = phx.frontend.useTextValue(entityId, instanceName)
+const attributeSelection = phx.frontend.useAttributeSelection(entityId, instanceName)
+const attributeSwitch = phx.frontend.useAttributeSwitch(entityId, instanceName)
+const distanceDimension = phx.frontend.useDistanceDimension(entityId, instanceName)
+const angleDimension = phx.frontend.useAngleDimension(entityId, instanceName)
+const genericDimension = phx.frontend.useGenericDimension(entityId, instanceName)
 
 // Update control
 const updateControl = phx.frontend.useUpdateControl()
-const updatedControl = phx.frontend.useUpdatedControl(entityId, controlId)
+const updatedControl = phx.frontend.useUpdatedControl(updates)
 ```
 
 ### Recipes & Entity Creation
@@ -202,14 +208,15 @@ const deletedEntity = phx.frontend.useDeletedEntity()
 ### Validation & Violations
 
 ```typescript
-// State validity
+// Validity of the last committed state; a rejected change never becomes committed, so it is not seen here
 const validity = phx.frontend.useStateValidity()
 
-// Control violations
-const controlViolations = phx.frontend.useControlViolations(entityId, controlId)
+// Control violations: takes the violation types to ignore and returns a function that maps a prepared
+// state emission to { disabled, hints, violations }
+const controlViolations = phx.frontend.useControlViolations([])
 
 // Finalize violations
-const {'{'} disabled, hints {'}'} = phx.frontend.useFinalizeViolations()
+const { disabled, hints } = phx.frontend.useFinalizeViolations()
 
 // Map violations to hints
 const mapViolationHints = phx.frontend.useMapViolationHints()
@@ -284,89 +291,89 @@ The interface provides factory functions for creating handlers and providers:
 
 ```typescript
 // Runs early in app startup, before session auth
-const OnApplicationStart = phx.frontend.createOnApplicationStartProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnApplicationStart = phx.frontend.createOnApplicationStartProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after session auth, before domain data loading
-const OnSessionReady = phx.frontend.createOnSessionReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnSessionReady = phx.frontend.createOnSessionReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after published data is parsed, before frontend/backend loading
-const OnPublishedDataReady = phx.frontend.createOnPublishedDataReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnPublishedDataReady = phx.frontend.createOnPublishedDataReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after frontend collection and parsing, before backend loading
-const OnFrontendDataReady = phx.frontend.createOnFrontendDataReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnFrontendDataReady = phx.frontend.createOnFrontendDataReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after backend loading, before preset selection and configurator initialization
-const OnBackendDataReady = phx.frontend.createOnBackendDataReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnBackendDataReady = phx.frontend.createOnBackendDataReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after routing and preset selection are ready
-const OnRoutingReady = phx.frontend.createOnRoutingReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnRoutingReady = phx.frontend.createOnRoutingReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Wraps OwnerUi and ReadUi pages
-const OnConfiguratorReady = phx.frontend.createOnConfiguratorReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnConfiguratorReady = phx.frontend.createOnConfiguratorReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 ```
 
 ### Data Handlers
 
 ```typescript
 // Collect frontend data during initialization
-const collectFrontendData = phx.frontend.createCollectFrontendDataHandler(async (context) => {'{'}
-  return {'{'} customData: await fetchCustomData() {'}'}
-{'}'})
+const collectFrontendData = phx.frontend.createCollectFrontendDataHandler(async context => {
+  return { customData: await fetchCustomData() }
+})
 
 // Override which published chunks are fetched by the frontend.
 // See Publishing page for full documentation.
-const filterPublishedChunks = phx.frontend.createFilterPublishedChunksHandler(() => {'{'}
+const filterPublishedChunks = phx.frontend.createFilterPublishedChunksHandler(() => {
   const session = phx.frontend.useSession()
 
-  return useMemo(() => {'{'}
+  return useMemo(() => {
     if (session.sessionPayload?.role === 'admin') return ['styling', 'catalog-na']
     return ['styling']
-  {'}'}, [session.sessionPayload?.role])
-{'}'})
+  }, [session.sessionPayload?.role])
+})
 
 // Runs after preset data is loaded
-const onPresetLoaded = phx.frontend.createOnPresetLoadedHandler((entities, presetData) => {'{'}
+const onPresetLoaded = phx.frontend.createOnPresetLoadedHandler((entities, presetData) => {
   // Can modify preset entities before rendering
   return entities
-{'}'})
+})
 
 // Intercept navigation to index/presets page
-const onGoToIndex = phx.frontend.createOnGoToIndexHandler(() => {'{'}
+const onGoToIndex = phx.frontend.createOnGoToIndexHandler(() => {
   // Custom logic before navigating
-{'}'})
+})
 ```
 
 ### UI Components
 
 ```typescript
 // Custom Phoenix layout element
-const MyLayoutElement = phx.frontend.createCustomPhoenixLayoutElement(() => {'{'}
+const MyLayoutElement = phx.frontend.createCustomPhoenixLayoutElement('MyLayoutElement', () => {
   return <div>Custom Layout</div>
-{'}'})
+})
 
 // Custom Phoenix entity element
-const MyEntityElement = phx.frontend.createCustomPhoenixEntityElement(() => {'{'}
+const MyEntityElement = phx.frontend.createCustomPhoenixEntityElement('MyEntityElement', () => {
   return <mesh>...</mesh>
-{'}'})
+})
 
 // Custom page when auth fails
-const NotAuthenticatedPage = phx.frontend.createNotAuthenticatedPage(() => {'{'}
+const NotAuthenticatedPage = phx.frontend.createNotAuthenticatedPage(() => {
   return <div>Please log in</div>
-{'}'})
+})
 ```
 
 ### Preset UI
@@ -383,21 +390,113 @@ const PresetAction = phx.frontend.createPresetPageAction(PresetHelpAction)
 const PresetOverlay = phx.frontend.createPresetDeviceNotSupported(SmallScreenNotice)
 ```
 
+### 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'
+
+const SIDEBAR_WIDTH = 320
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', () => {
+  const { containerRef, safeAreaRef } = useSceneSafeArea()
+
+  return (
+    <div ref={containerRef} style={{ position: 'absolute', inset: 0 }}>
+      <LayoutSlots.Services />
+      <LayoutSlots.SharedCanvas />
+      <aside style={{ position: 'absolute', insetBlock: 0, insetInlineStart: 0, inlineSize: SIDEBAR_WIDTH }}>
+        Project sidebar
+      </aside>
+      <div
+        ref={safeAreaRef}
+        style={{ position: 'absolute', insetBlock: 0, insetInlineStart: SIDEBAR_WIDTH, insetInlineEnd: 0, pointerEvents: 'none' }}
+      />
+    </div>
+  )
+})
+```
+
+- `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).
+- 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`.
+- `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`.
+- 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).
+- Any project layout element named `ConfiguratorLayout` takes over the page.
+
+#### 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.
+
+**The product**
+
+| Hook                                                                            | Returns                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useRootEntityId()`                                                | The id of the root entity, which the control hooks take.                                                                                                                                                                                                                                                                        |
+| `phx.frontend.useSelectedDomainEntityId()`                                      | The id of the selected entity, or the root entity's id while nothing is selected.                                                                                                                                                                                                                                               |
+| `phx.frontend.useFirstRootComponent(componentType)`                             | The first component of that type on the root entity as `{ componentInstance, state }`, or `null` without one. It takes a component type such as `detailComponent` from `@salsita-ai/sdk/domain`, or an array of them. The `detail` component's `state` is `{ title, subtitle, description, thumbnailUrl? }`, all `Localizable`. |
+| `phx.frontend.useComponents({ componentTypes, entityIds?, instanceNames? })`    | Every matching component on any entity, as `{ componentInstance, state }[]`. Its type on `phx.frontend` includes `null`, but it returns an empty array when nothing matches.                                                                                                                                                    |
+| `phx.frontend.useRootEntityPrice()` and `phx.frontend.useEntityPrice(entityId)` | The value of the entity's `price` component formatted as currency for the current locale, in the component's `currency` or `USD`, or `null` without a `price` component.                                                                                                                                                        |
+
+**Controls**
+
+| Hook                                                         | Returns                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useAttributeSelection(entityId, instanceName)` | `{ value, options }`. Each option has `title` and `description` (`Localizable`, the spec's `label` and `description`), `value`, `imageSrc` (the spec's `img`), `disabled`, `error`, `hint` (a `string` saying why it is disabled, or `undefined`) and `onSelect()`, which writes the option; the selected option's `onSelect` does nothing. It throws when the entity has no `attributeSelection` component named `instanceName`. |
+| `phx.frontend.useAttributeSwitch(entityId, instanceName)`    | `{ state, onChange, disabled, error, hint }`: `state.value` is the boolean and `onChange()` writes its opposite. It throws without the component.                                                                                                                                                                                                                                                                                 |
+
+The other control hooks in [Controls](#controls) take the same two arguments, `useSwatchSelection` a required third. `useSwatchSelection` returns `{ value, options }`, where `value` is the selected swatch key and each option is `{ swatchName, onClick, swatchKey, selected, thumbnailUrl, disabled, color, hint?, trace? }`; `useTextValue` and the dimension hooks return `{ value, hints, hasErrors, update, resolve, trace }` instead, where `update(value)` stages a value the scene shows at once (`useTextValue`'s is an `onChange` handler, `update(event, value)`) and `resolve()` commits it, or rolls it back when it breaks an invariant. Their TypeScript types give the exact shapes, and [Custom Controls](?path=/docs/controls-custom--docs) lists them.
+
+**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).
+
+**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.                                                 |
+
+**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`.                                                                                                                           |
+
+`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.
+
+**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()`.
+
+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`.
+
+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.
+
 ## TransformerBuilder
 
 Use `transformerBuilder` to create entity transformers:
 
 ```typescript
 // Create a transformer that runs when specific conditions are met
-const cabinetTransformer = phx.frontend.transformerBuilder
-  .when(Cabinet.is)
-  .do((cabinet, context) => {'{'}
-    // Transform cabinet data
-    return {'{'}
-      ...cabinet,
-      $computedField: calculateSomething(cabinet)
-    {'}'}
-  {'}'})
+const cabinetTransformer = phx.frontend.transformerBuilder.when(Cabinet.is).do((cabinet, context) => {
+  // Transform cabinet data
+  return {
+    ...cabinet,
+    $computedField: calculateSomething(cabinet),
+  }
+})
 ```
 
 **Note**: The deprecated `createTransformer` function should not be used for new implementations.
@@ -407,19 +506,19 @@ const cabinetTransformer = phx.frontend.transformerBuilder
 The `updates` factory creates type-safe entity updates:
 
 ```typescript
-const {'{'} storeSystem {'}'} = phx.frontend.useDomain()
+const { storeSystem } = phx.frontend.useDomain()
 
 // Create new entity
-const createUpdates = phx.frontend.updates.create({'{'}
+const createUpdates = phx.frontend.updates.create({
   type: 'Cabinet',
   width: 800,
   height: 2000,
-{'}'})
+})
 
 // Modify existing entity
-const modifyUpdates = phx.frontend.updates.modify(cabinetId, {'{'}
+const modifyUpdates = phx.frontend.updates.modify(cabinetId, {
   width: 1000,
-{'}'})
+})
 
 // Delete entity
 const deleteUpdates = phx.frontend.updates.delete(cabinetId)

package/dist/docs/phoenix/deployments.mdx

@@ -464,7 +464,7 @@ Error: Failed to upload to S3
 
 - Run `deployment:prepare` again to get fresh presigned URLs
 - Check that `.upload-links.json` exists and is readable
-- Use `--skipUpload` / `-su` flag to test without uploading assets
+- Use `--skipUpload` / `--su` flag to test without uploading assets
 
 ### "Server URL is required"