@salsita-ai/sdk 0.50.0-develop.a49722158a → 0.50.0-develop.a8cf9ffd01

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

@@ -77,7 +77,7 @@ navigationStates:
 
 Navigation states in Phoenix are controlled by navigation system that manages state transitions and coordinates with the component system. The navigation system handles state changes and maintains consistency across navigation transitions.
 
-Phoenix provides built-in components to visualize and control navigation, eg.
+Phoenix provides built-in components to visualize and control navigation, eg. `navigationSteps` for a step indicator and `horizontalTabs` (or `sidebarTabs` for tabs in the sidebar):
 
 ```yaml
 components:
@@ -86,31 +86,27 @@ components:
       main:
         steps:
           - label: 'Design'
-            description: 'Configure your space'
             navigationStates:
               - design
           - label: 'Preview'
-            description: 'Review your design'
             navigationStates:
               - preview
           - label: 'Summary'
-            description: 'Order details'
             navigationStates:
               - summary
           - label: 'Checkout'
-            description: 'Complete your order'
             navigationStates:
               - finalize
 
-    navigationTabs:
+    horizontalTabs:
       main:
         tabs:
           - label: 'Design'
-            icon: 'edit'
+            icon: 'PencilSimpleBold'
             navigationStates:
               - design
           - label: 'Preview'
-            icon: 'eye'
+            icon: 'EyeBold'
             navigationStates:
               - preview
 ```
@@ -122,39 +118,56 @@ components:
   Room:
     propertyPage:
       design:
-        title: 'Room Configuration'
+        children:
+          - kind: propertyContainerItem
+            props:
+              title: 'Room Configuration'
         $filter:
           navigationStates: ['design'] # Only active during design phase
 
       summary:
-        title: 'Room Summary'
+        children:
+          - kind: propertyContainerItem
+            props:
+              title: 'Room Summary'
         $filter:
           navigationStates: ['summary', 'finalize'] # Show during review phases
 
     toolControls:
       designTools:
-        tools: ['select', 'move', 'rotate', 'resize']
+        items:
+          - label: 'Select'
+            value: 'select'
+            icon: 'CursorClick'
+          - label: 'Move'
+            value: 'move'
+            icon: 'ArrowsOutCardinal'
         $filter:
           navigationStates: ['design'] # Design tools only available in design mode
 
       previewControls:
-        tools: ['zoom', 'pan', 'measure']
+        items:
+          - label: 'Measure'
+            value: 'measure'
+            icon: 'ArrowsHorizontal'
         $filter:
           navigationStates: ['preview'] # Different tools for preview mode
 
   Cabinet:
     detail:
-      editable:
+      design:
         title: 'Cabinet Settings'
-        editable: true
+        subtitle: 'Adjust the size and finish'
+        description: 'Change the cabinet width, height and material.'
         $filter:
-          navigationStates: ['design'] # Editable only in design mode
+          navigationStates: ['design'] # Shown in design mode
 
-      readonly:
+      review:
         title: 'Cabinet Details'
-        editable: false
+        subtitle: 'Your chosen cabinet'
+        description: 'The size and finish you configured.'
         $filter:
-          navigationStates: ['preview', 'summary', 'finalize'] # Read-only in other states
+          navigationStates: ['preview', 'summary', 'finalize'] # Shown in the other states
 ```
 
 **Advanced Filtering**: Filters support combining multiple conditions. Multiple conditions in the same filter are AND-ed together. Use `$or` for OR logic:
@@ -162,16 +175,15 @@ components:
 ```yaml
 components:
   Scene:
-    # AND condition: show only when BOTH conditions are true
     sceneEntitySelectHotspot:
+      # AND condition: show only when BOTH conditions are true
       designAndTopView:
         title: 'Design in Top View'
         $filter:
           navigationStates: ['design']
           viewStates: ['top']
 
-    # OR condition: show when EITHER condition is true
-    sceneEntitySelectHotspot:
+      # OR condition: show when EITHER condition is true
       step2OrFrontView:
         title: 'Step 2 OR Front View'
         $filter:
@@ -216,7 +228,7 @@ components:
             icon: 'Cube'
           - label: 'Close Up'
             value: 'closeup'
-            icon: 'MagnifyingGlass'
+            icon: 'MagnifyingGlassBold'
           - label: 'Blueprint'
             value: 'blueprint'
             icon: 'GridFour'
@@ -248,11 +260,14 @@ components:
     detail:
       overview:
         title: 'Cabinet'
+        subtitle: ''
+        description: ''
         $filter:
           viewStates: ['overview', 'blueprint']
 
       detailed:
         title: 'Cabinet Details'
+        subtitle: 'Close-up view'
         description: 'Full cabinet configuration options'
         $filter:
           viewStates: ['closeup']
@@ -285,27 +300,30 @@ components:
             icon: 'CursorClick'
           - label: 'Draw'
             value: 'sketch'
-            icon: 'PencilSimple'
+            icon: 'PencilSimpleBold'
           - label: 'Move'
             value: 'move'
             icon: 'ArrowsOutCardinal'
           - label: 'Measure'
             value: 'measure'
-            icon: 'Ruler'
+            icon: 'ArrowsHorizontal'
 
-    sketching:
+    # `key` matches the `key` of the `sketching` component that holds the drawing surface and recipes
+    sketchingDraw:
       drawing:
-        enabled: true
+        key: sketching
         $filter:
           toolStates: ['sketch']
 
     sketchingEdit:
       editing:
-        enabled: true
+        key: sketching
         $filter:
           toolStates: ['select']
 ```
 
+The [Sketching](?path=/docs/complex-use-cases-sketching--docs) example shows the complete setup, including the `sketching` component these refer to.
+
 ## What We Learned
 
 In this guide, we explored Phoenix's application state management:

package/dist/docs/phoenix/blender-rendering.mdx

@@ -23,6 +23,8 @@ Use a **`GenerateImages`** finalization task when an order, quote, PDF, or email
 
 This page describes what the default render script supports and how it behaves. For where the task sits in the finalization flow, see [Webhooks → GenerateImages Task](?path=/docs/phoenix-webhooks--docs#generateimages-task) and [Finalization](?path=/docs/phoenix-finalization--docs).
 
+Renders queue one after another on the platform and can take minutes, so when the configurator calls `waitForFinalizationToComplete` it should pass a `pollingTimeout` long enough for them; the default is 30 seconds.
+
 ## Generate an image from the submitted configuration
 
 Start with **`ctx.blenderProjections.getBlenderImageConfig`** instead of manually assembling objects, lights, and a camera. It applies the requested export state and its transformers once, validates the resulting state, and returns the output dimensions, rendered entities, lights, and an aspect-aware camera projected from that same state.
@@ -422,7 +424,7 @@ export const simpleImageTask = phx.webhooks.taskFactory.createGenerateImagesTask
 - `blenderSetupTemplate`, `templateFiles`, `blenderPythonScriptName`, texture maps, and HDRIs are paths relative to the private deployment assets (see [Static assets](?path=/docs/phoenix-webhooks--docs#static-assets)). A leading slash is removed and backslashes become `/`; URL schemes, network paths, empty or directory paths, control characters, and any `..` segment are rejected.
 - `images[].name` becomes the rendered file name, so it must be a single non-empty path segment without slashes, control characters, `.`, or `..`.
 - Assets are cached per deployment and reused by later jobs. Texture and HDRI references are downloaded and rewritten to their cache paths before Blender starts, so the script only ever sees local files.
-- Blender runs with factory settings, so add-ons and user preferences on the worker do not affect the render. The render engine is the worker's configured engine.
+- Blender runs with factory settings, so add-ons and user preferences on the worker do not affect the render. The engine saved in the template renders the image.
 - A non-zero Blender exit fails the finalization task. Blender's stderr is included in the reported error, and every stdout and stderr line is forwarded to the worker log, including the material and texture warnings described above.
 - Unsupported values inside a material override (for example a map on an input the worker's Blender version lacks) are logged and skipped rather than failing the render; invalid render-setting enum values fail the render.
 

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

@@ -48,17 +48,18 @@ Here's how components are defined, showing both the YAML configuration and the u
 ```yaml
 components:
   Cabinet:
-    # Property page component with writable state
+    # Property page: the sidebar page shown when a cabinet is selected
     propertyPage:
       main:
-        title: 'Cabinet Configuration'
         children:
-          - kind: attributeSlider
+          - kind: propertyContainerItem
             props:
-              instanceName: width
-              label: Width
-              min: 100
-              max: 2000
+              title: 'Cabinet Configuration'
+            children:
+              - kind: distanceDimensionSlider
+                props:
+                  instanceName: width # The distanceDimension instance below, which sets min and max
+                  label: Width
 
     # Attribute selection with domain-bound writable state
     attributeSelection:
@@ -109,16 +110,15 @@ The component system provides full TypeScript support for both configuration and
 ```yaml
 components:
   Cabinet: # Component attached to Cabinet entity type
-    propertyPage:
+    detail: # The title, subtitle and description shown in the entity header above the property page
       main:
         title:
           $read: name # Read from Cabinet.name property
         subtitle:
-          $read: $area # Read from Cabinet.$area expression
-        visible:
-          $read: $isVisible # Read from Cabinet.$isVisible expression
+          $read: $areaLabel # Read from Cabinet.$areaLabel expression
+        description: 'Base cabinet'
 
-    attributeSlider:
+    distanceDimension:
       width:
         value:
           $bind: width # Bidirectional binding to Cabinet.width
@@ -132,6 +132,7 @@ components:
       main:
         title:
           $read: type # Read entity type (Chair/Table/Cabinet)
+        subtitle: 'Furniture'
         description:
           $read: $description # Read from common expression across all furniture
 ```
@@ -191,7 +192,7 @@ components:
 
 Phoenix provides three powerful binding mechanisms that connect components to your domain model data:
 
-> Note on `$codeRef`: it's evaluated without entity context and is meant for static math/constants (e.g., `4 * 25.4`, `Math.PI / 2 - 0.2`). If a value depends on entity state, expose it via an expression and reference it with `$read`. Don't attempt to read entity data inside `$codeRef`. This feature is experimental.
+> For inline math in a prop, such as `4 * 25.4` or `self.width / 2`, use `$eval` (described below). `$codeRef` with an inline `code:` block is not supported and reports `ENHANCED_JSON_VALUE_CODE_REF_NOT_SUPPORTED`.
 
 ### `$read` - Reading Values
 
@@ -219,18 +220,18 @@ components:
 
 ### `$write` - Writing Values
 
-`$write` allows components to modify entity properties directly. This creates a two-way binding where user interactions can update the domain state.
+`$write` allows components to modify entity properties directly. This creates a two-way binding where user interactions can update the domain state. `$write` is paired with `$read` or `$eval`, which supplies the value the component shows; `$bind: width` is the short form of `$read: width` with `$write: width`.
 
 ```yaml
 components:
   Cabinet:
-    attributeSlider:
+    distanceDimension:
       width:
         value:
+          $read: $clampedWidth # The control shows the value of an expression
           $write: width # User input directly updates the width property
         min: 100
         max: 2000
-        step: 50
 ```
 
 **Use cases for `$write`:**
@@ -273,6 +274,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.
@@ -332,7 +339,10 @@ components:
   Cabinet:
     propertyPage:
       main:
-        title: 'Cabinet Settings'
+        children:
+          - kind: distanceDimensionSlider
+            props:
+              instanceName: width
         $filter:
           # Static filter configuration
           navigationStates: ['design', 'configure']
@@ -342,13 +352,16 @@ components:
     detail:
       advanced:
         title: 'Advanced Options'
+        subtitle: 'Cabinet'
+        description: 'Fine-tune the cabinet'
         $filter:
           # Dynamic filter using expression
-          $read: $showAdvancedOptions
+          active:
+            $read: $showAdvancedOptions
 
-    contextualTools:
+    htmlHotspot:
       edit:
-        title: 'Edit Cabinet'
+        name: EditCabinetButton # A custom element shown next to the cabinet in the scene
         $filter:
           # Show only when this specific entity is selected
           selectedEntityIds:
@@ -484,14 +497,11 @@ components:
   Cabinet:
     propertyPage:
       main:
-        title: 'Cabinet Configuration'
         children:
-          - kind: attributeSlider
+          - kind: distanceDimensionSlider
             props:
               instanceName: width
               label: Width
-              min: 100
-              max: 2000
 ```
 
 **Generated TypeScript Code:**
@@ -508,15 +518,12 @@ export default [
       memoEval(
         cabinet => [cabinet.id], // Dependencies
         () => ({
-          title: 'Cabinet Configuration',
           children: [
             {
-              kind: 'attributeSlider',
+              kind: 'distanceDimensionSlider',
               props: {
                 instanceName: 'width',
                 label: 'Width',
-                min: 100,
-                max: 2000,
               },
             },
           ],
@@ -725,7 +732,6 @@ phx.domain.attachComponent
         primaryButton: canManufacture ?
           <ManufactureButton entityId={entityId} status={status} /> : null,
         secondaryButton: <QualityCheckButton entityId={entityId} />,
-        page: <ManufacturingDetails entityId={entityId} />,
       })
     )
   )
@@ -762,14 +768,17 @@ Custom components in `src/components/` are automatically collected by Phoenix an
 export default [customRenderingComponent, advancedUIComponent, specializedToolComponent]
 ```
 
-**When to Use Custom Components:**
+**When to Attach Components in Code:**
+
+A file in `src/components/` attaches a component from TypeScript instead of YAML. Use it when the component's state needs more than YAML can express:
 
-- **Custom 3D Rendering**: Complex Three.js scenes that can't be achieved with standard components
-- **Advanced UI Logic**: React components with complex state management or business logic
-- **Specialized Tools**: Custom interaction modes or editing tools
-- **External Integrations**: Components that integrate with external APIs or services
-- **Performance Optimizations**: Highly optimized rendering for specific use cases
-- **Domain-Specific Behavior**: Functionality unique to your particular domain
+- **Custom 3D Rendering**: a `customSceneEntity` node built from React and Three.js
+- **Computed State**: component values that need TypeScript logic beyond `$read`, `$eval` and expressions
+- **Many Instances**: one instance per item of a collection, with `attachMany` (see [Advanced: Dynamic Components](#advanced-dynamic-components))
+- **Programmatic Filters**: `withGradualFilter` predicates written as functions
+- **Performance Optimizations**: hand-tuned `memoEval` dependencies for expensive state
+
+A custom control or panel in the sidebar does not need a component attachment. Build it as a React element with `phx.frontend.createCustomPhoenixEntityElement('Name', ...)`, default-exported from a file in `src/elements/`, and place it in the YAML property page as a `customElement` with `props.name` set to that name; see [Custom Controls](?path=/docs/controls-custom--docs).
 
 Custom component attachments provide the flexibility to extend Phoenix's capabilities while maintaining the performance benefits of the component system and seamless integration with your domain model.
 
@@ -787,7 +796,7 @@ Dynamic components are attached programmatically using the `phx.domain.attachCom
 
 **Key Use Cases:**
 
-- Creating component instances for each item in a collection (e.g., one control per cabinet door)
+- Creating component instances for each item in a collection (e.g., one door model per cabinet door)
 - Conditionally showing components based on complex business logic
 - Generating UI elements that depend on dynamic entity relationships
 - Building adaptive interfaces that change based on configuration complexity
@@ -795,24 +804,28 @@ Dynamic components are attached programmatically using the `phx.domain.attachCom
 **Example Pattern:**
 
 ```typescript
-// Dynamic component that creates controls for each door
+// Dynamic component that loads one door model for each door of the cabinet
+import { memoEval, sceneEntityRemoteObjectComponent } from '@salsita-ai/sdk/domain'
+
 phx.domain.attachComponent
   .withEntity('Cabinet')
-  .withComponent(customControlComponent, 'doors')
+  .withComponent(sceneEntityRemoteObjectComponent, 'door')
   .attachMany(
     memoEval(
-      cabinet => [cabinet.$doors],
-      doors =>
-        doors.map(door => ({
-          key: door.id,
-          label: `Door ${door.id}`,
-          doorId: door.id,
-          isOpen: door.isOpen,
+      cabinet => [cabinet.doorCount],
+      doorCount =>
+        Array.from({ length: doorCount }, (_, index) => ({
+          key: String(index), // Unique per instance
+          fileUrl: '/models/cabinet.gltf',
+          objectName: 'Door',
+          dimensionUnit: 'm',
         }))
     )
   )
 ```
 
+The `attachMany` callback returns an array of component states, each with a unique `key`. To position each door, also attach `sceneEntityObjectPropertiesComponent` with the same instance name and keys, as the example linked below does. A custom control is not a component: for custom UI in the sidebar, use a `customElement` as described in [Custom Component Attachments](#custom-component-attachments).
+
 For comprehensive examples and implementation details, see the [Dynamic Component Attachments](?path=/docs/other-features-dynamic-component-attachments--docs) documentation.
 
 ## What We Learned