@salsita-ai/sdk 0.50.0-develop.8c8c362f86 → 0.50.0-develop.8d2f236284

package/dist/docs/layouts/header/fixed.mdx

@@ -145,7 +145,7 @@ interface HorizontalTab {
   /**
    * List of navigation states when the tab is active. First one will be used for activation.
    */
-  readonly navigationStates: string[]
+  readonly navigationStates: readonly string[]
 }
 ```
 
@@ -158,7 +158,7 @@ type HorizontalTabsComponentState = {
   /**
    * List of tabs in the horizontal tabs.
    */
-  readonly tabs: HorizontalTab[]
+  readonly tabs: readonly HorizontalTab[]
 }
 ```
 

package/dist/docs/layouts/header/floating.mdx

@@ -110,11 +110,11 @@ The configuration uses these component types:
 ```typescript
 export interface NavigationStep {
   readonly label: Localizable
-  readonly navigationStates: string[]
+  readonly navigationStates: readonly string[]
 }
 
 export type NavigationStepsComponentState = {
-  readonly steps: NavigationStep[]
+  readonly steps: readonly NavigationStep[]
 }
 ```
 

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/layouts/sidebar-footer/basic.mdx

@@ -41,11 +41,11 @@ The basic sidebar footer adapts its layout based on what's available. The finali
 
 For more control over the sidebar footer, see these related examples:
 
-- **[Phoenix Handlers](../?path=/docs/layouts-phoenix-handlers)**: Learn how to create custom action handlers for sidebar footer buttons
-- **[Read Sidebar Footer](../?path=/docs/layouts-sidebar-footer-read)**: Display price in read-only mode without action buttons
-- **[Universal Sidebar Footer](../?path=/docs/layouts-sidebar-footer-universal)**: Add custom text and multiple action buttons while keeping the standard layout
-- **[Custom Sidebar Footer](../?path=/docs/layouts-sidebar-footer-custom)**: Replace the sidebar footer with your own React components for complete control
-- **[Hidden Sidebar Footer](../?path=/docs/layouts-sidebar-footer-hidden)**: Remove the sidebar footer entirely for embedded or immersive experiences
+- **[Phoenix Handlers](?path=/docs/layouts-phoenix-handlers--docs)**: Learn how to create custom action handlers for sidebar footer buttons
+- **[Read Sidebar Footer](?path=/docs/layouts-sidebar-footer-read--docs)**: Display price in read-only mode without action buttons
+- **[Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs)**: Add custom text and multiple action buttons while keeping the standard layout
+- **[Custom Sidebar Footer](?path=/docs/layouts-sidebar-footer-custom--docs)**: Replace the sidebar footer with your own React components for complete control
+- **[Hidden Sidebar Footer](?path=/docs/layouts-sidebar-footer-hidden--docs)**: Remove the sidebar footer entirely for embedded or immersive experiences
 
 ## Guide
 
@@ -98,84 +98,39 @@ This configuration gives you a fully functional sidebar footer with price displa
 
 ### Customizing finalize behavior
 
-The sidebar footer's finalize button can be customized using two different component types. These components let you either replace the button itself or define what happens when the user clicks finalize.
+New projects finalize with `finalizeAction` components and the [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs), which runs the action's handler. The basic sidebar footer's own customization, the `finalizeButton` and `finalizePage` components, is legacy: the spec parser rejects both in YAML, so a project that keeps them declares them in TypeScript.
 
-#### Using finalizeButton component
+The basic sidebar footer checks for them in this order:
 
-The `finalizeButton` component replaces the default finalize button with your custom React component. This gives you complete control over the button's appearance and behavior.
+1. **finalizeButton**: if configured, its `button` React node is rendered instead of the finalize button, and implements the finalization and the disabled state itself
+2. **finalizePage**: if no custom button exists, a default button navigates to the first of the component's `finalizeNavigationStates`, and the built-in layout shows its `page` in a dialog while one of those states is active
+3. **No-op fallback**: if neither component is configured, a disabled button appears with the hint "Finalize feature is not configured"
 
-```yaml
-components:
-  Scene:
-    finalizeButton:
-      customFinalize:
-        button: <CustomFinalizeButtonComponent />
-```
-
-**TypeScript Interface**:
-
-```typescript
-/**
- * State for a custom finalize button component.
- */
-interface FinalizeButtonComponentState {
-  /**
-   * Custom React node to render as the finalize button.
-   * This completely replaces the default finalize button.
-   */
-  readonly button: ReactNode
-}
-```
+A legacy `finalizePage` is attached in TypeScript, as the [Universal](?path=/docs/layouts-universal--docs) example does in `src/components/components.tsx`:
 
-Your custom button component receives no special props. You must implement all the finalization logic yourself, including calling the appropriate handlers and managing the button's disabled state based on validation errors.
-
-#### Using finalizePage component
-
-The `finalizePage` component opens a modal page when the user clicks finalize. This is useful for multi-step checkout flows, order forms, or any scenario where you need to collect additional information before completing the order.
-
-```yaml
-components:
-  Scene:
-    finalizePage:
-      checkoutFlow:
-        finalizeNavigationStates: ['checkout', 'payment', 'confirmation']
-        page: <CheckoutFormComponent />
-```
+```tsx
+import { finalizePageComponent, memoEval } from '@salsita-ai/sdk/domain'
 
-**TypeScript Interface**:
+// CheckoutPage is the project's own React component
+import { CheckoutPage } from '../_shared/CheckoutPage.js'
 
-```typescript
-/**
- * State for a finalize page component that opens a modal.
- */
-interface FinalizePageComponentState {
-  /**
-   * The navigation states that are active when finalization is in progress.
-   * The first state in this array is used for initial navigation when the
-   * finalize button is clicked.
-   */
-  readonly finalizeNavigationStates: string[]
+// `phx` is a global in an application project; a Storybook example imports it from '../../.phoenix/phx.js'
 
-  /**
-   * React node to render as the page content in the finalize modal.
-   */
-  readonly page: ReactNode
-}
+export default phx.domain.attachComponent
+  .withComponent(finalizePageComponent, 'default')
+  .withEntity('Scene')
+  .attach(
+    memoEval(
+      () => [],
+      () => ({
+        finalizeNavigationStates: [phx.applicationTypes.NavigationState.finalize],
+        page: <CheckoutPage />,
+      })
+    )
+  )
 ```
 
-When the user clicks the finalize button, the system navigates to the first state in `finalizeNavigationStates`. Your page component can then navigate between these states to create a multi-step flow. All states must be defined in your navigation configuration.
-
-#### Priority and fallback behavior
-
-The sidebar footer checks for finalize components in this order:
-
-1. **finalizeButton**: If configured, this component is rendered as-is with no modifications
-2. **finalizePage**: If no custom button exists, a default button is shown that opens the specified page
-3. **No-op fallback**: If neither component is configured, a disabled button appears with the hint "Finalize feature is not configured"
-
-This priority system lets you customize either the button appearance or the finalization flow, but not both simultaneously. If you need both, use `finalizeButton` and implement the page navigation logic within your custom component.
-
-See the [Finalize Page Layout](../?path=/docs/layouts-simple-layout-finalize-page) example for a complete implementation of the finalize page pattern.
+The states in `finalizeNavigationStates` must be listed in the spec's `navigationStates`. The universal sidebar footer never opens a `finalizePage`.
 
 ### Navigation steps influence
 
@@ -278,7 +233,7 @@ Use `simpleSummary` for basic summaries that just need to display a list of conf
 
 Both component types require a `summaryNavigationState` that must exist in your navigation configuration. The sidebar footer checks the current navigation state against this property to determine whether the summary is currently active.
 
-See the [Summary Layout](../?path=/docs/layouts-simple-layout-summary) example for a complete summary implementation.
+See the [Sidebar Summary](?path=/docs/layouts-sidebar-summary--docs) example for a complete summary implementation.
 
 ### Custom price sidebar footer
 
@@ -317,11 +272,11 @@ When `customPriceSidebarFooter` is configured:
 - The sidebar footer layout remains unchanged - only the price display is replaced
 - Action buttons (finalize, next/previous, etc.) are not affected
 
-This component affects **only** the price display, not the overall sidebar footer structure. If you need to change the entire sidebar footer layout, use the [Universal Sidebar Footer](../?path=/docs/layouts-sidebar-footer-universal) or [Custom Sidebar Footer](../?path=/docs/layouts-sidebar-footer-custom) instead.
+This component affects **only** the price display, not the overall sidebar footer structure. If you need to change the entire sidebar footer layout, use the [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) or [Custom Sidebar Footer](?path=/docs/layouts-sidebar-footer-custom--docs) instead.
 
 The custom price node receives no special props. You must access price data yourself through the configurator hooks like `useRootEntityPrice()` or by reading entity attributes directly.
 
-See the [Custom Price Sidebar Footer](../?path=/docs/layouts-custom-price) example for implementation details and best practices.
+See the [Custom Price Sidebar Footer](?path=/docs/layouts-custom-price--docs) example for implementation details and best practices.
 
 ## Example
 

package/dist/docs/other-features/client-side-rendering/declarative.mdx

@@ -229,7 +229,7 @@ export type ClientSideImageComponentState = {
   /** Output format: PNG (with transparency) or JPEG */
   readonly fileFormat: 'PNG' | 'JPEG'
   /** Optional background color (hex string) */
-  readonly backgroundColor?: string
+  readonly backgroundColor?: HexColor
 
   /** Tool state the image is rendered in (pins component filters keyed on tool state) */
   readonly toolState: string

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 by registering a layout element under the name `ConfigurationNotFoundPage`, 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.