@salsita-ai/sdk 0.50.0-develop.97a772d197 → 0.50.0-develop.996c9540be

package/dist/configurator/ui/configurator-layout/universal/use-layout-scene-safe-area.d.ts

@@ -0,0 +1,47 @@
+/** What a built-in layout tells the safe-area measurement about itself. */
+export interface LayoutSceneSafeAreaOptions {
+    /** Whether the layout owns the canvas padding now. See `useLayoutSceneSafeArea`. */
+    readonly enabled: boolean;
+    /** Whether the sidebar is collapsed to its mini form, which the scene clears only in part. */
+    readonly hasMiniSidebar: boolean;
+}
+/**
+ * Measures the gap between a full-area container and an inner "safe area" element,
+ * and writes the resulting gaps to the responsive context as canvas padding — letting the
+ * 3D scene render only in the region not covered by overlay UI (preview body, sidebar, etc.).
+ *
+ * The implementation behind `useSceneSafeArea`, with the two things only the built-in
+ * layouts need: `enabled` and `hasMiniSidebar`.
+ *
+ * Returns:
+ * - `containerRef` — attach to the full-area measurement element.
+ * - `safeAreaRef` — attach to the region the scene should remain visible in.
+ * - `update` — trigger a manual re-measure on demand.
+ *
+ * `containerRef` / `safeAreaRef` are *callback* refs: the `ResizeObserver` (re)connects
+ * whenever a node attaches or detaches. This matters because the owning layout can mount
+ * late — `AnimatePresence mode="wait"` only mounts the interface after the preview has
+ * finished exiting, well after a one-shot mount effect would have run and bailed on null
+ * refs (leaving the scene stuck at the preview's padding).
+ *
+ * `enabled` is for a layout that stays mounted while another one owns the padding (e.g. the
+ * mobile interface while previewing, or a preview that lingers through its exit fade). While
+ * it is `false` the observer is disconnected, and a measurement started by the `update` of that
+ * render or by a pending retry writes nothing. An `update` that was created while the hook was
+ * enabled, such as a handler an animation already holds, still measures and writes. Turning
+ * `enabled` back on reconnects the observer, which measures again.
+ *
+ * `getBoundingClientRect()` returns *visually transformed* rects, so `measure` skips
+ * transformed frames automatically (retrying until the transform clears) to avoid feeding
+ * the scene a scaled gap mid layout animation.
+ *
+ * `update` exists for the complementary case: when only an ancestor's `transform` changes
+ * (e.g. motion FLIP settling), `ResizeObserver` doesn't fire, so nothing re-triggers
+ * `measure`. Call `update()` once the transform settles (e.g. from
+ * `onLayoutAnimationComplete`) to re-measure against the actual layout box.
+ */
+export declare const useLayoutSceneSafeArea: (options: LayoutSceneSafeAreaOptions) => {
+    containerRef: (node: HTMLDivElement | null) => void;
+    safeAreaRef: (node: HTMLDivElement | null) => void;
+    update: () => void;
+};

package/dist/configurator/ui/configurator-layout/universal/use-layout-scene-safe-area.js

@@ -0,0 +1 @@
+import{useCallback as t,useEffect as e,useRef as r}from"react";import{canvasPaddingComponent as n}from"#package/domain";import{useFirstComponent as o}from"#package/react-sdk";import{useResponsive as a}from"#package/ui-sdk";export const useLayoutSceneSafeArea=c=>{let{enabled:u,hasMiniSidebar:i}=c,{setCanvasPadding:m}=a(),l=r(null),s=r(null),f=r(null),h=r(null),p=r(0),g=r(()=>{}),b=o({componentTypes:[n]}),d=t(()=>{let t=s.current,e=f.current;if(!u||!t||!e)return;let r=t.getBoundingClientRect(),n=e.getBoundingClientRect();if(Math.abs(r.width-t.offsetWidth)>1||Math.abs(r.height-t.offsetHeight)>1){if(p.current+=1,p.current>60){p.current=0;return}l.current&&cancelAnimationFrame(l.current),l.current=requestAnimationFrame(()=>g.current());return}p.current=0;let o={bottom:Math.max(0,r.bottom-n.bottom),left:Math.max(0,n.left-r.left),right:Math.max(0,r.right-n.right),top:Math.max(0,n.top-r.top)},a=i?.3:1,c=b?.state.bottom??1,h=b?.state.left??1,d=b?.state.right??a,A=b?.state.top??1;m({bottom:o.bottom*c,left:o.left*h,right:o.right*d,top:o.top*A})},[u,i,b?.state.bottom,b?.state.left,b?.state.right,b?.state.top,m]);g.current=d;let A=t(()=>{l.current&&cancelAnimationFrame(l.current),l.current=requestAnimationFrame(d)},[d]),M=t(()=>{h.current?.disconnect(),h.current=null},[]),k=t(()=>{let t=s.current,e=f.current;if(!u||!t||!e)return void M();M();let r=new ResizeObserver(A);r.observe(t),r.observe(e),h.current=r},[M,u,A]),x=t(t=>{s.current=t,k()},[k]),F=t(t=>{f.current=t,k()},[k]);return e(()=>(k(),()=>{M(),l.current&&cancelAnimationFrame(l.current)}),[k,M]),{containerRef:x,safeAreaRef:F,update:A}};

package/dist/configurator/ui/configurator-layout/universal/use-scene-safe-area.d.ts

@@ -1,33 +1,18 @@
-import type { CanvasPadding } from '#package/ui-sdk';
 /**
- * Measures the gap between a full-area container and an inner "safe area" element,
- * and forwards the resulting gaps as canvas padding — letting the 3D scene render
- * only in the region not covered by overlay UI (preview body, sidebar, etc.).
+ * Tells the camera which part of the canvas a layout leaves free for the scene.
  *
- * Returns:
- * - `containerRef` — attach to the full-area measurement element.
- * - `safeAreaRef` — attach to the region the scene should remain visible in.
- * - `update` — trigger a manual re-measure on demand.
- *
- * `containerRef` / `safeAreaRef` are *callback* refs: the `ResizeObserver` (re)connects
- * whenever a node attaches or detaches. This matters because the owning layout can mount
- * late — `AnimatePresence mode="wait"` only mounts the interface after the preview has
- * finished exiting, well after a one-shot mount effect would have run and bailed on null
- * refs (leaving the scene stuck at the preview's padding).
- *
- * `enabled` gates the whole thing: when `false` the observer is disconnected so an inactive
- * layout (e.g. the interface while previewing) neither measures nor writes padding.
+ * A layout attaches `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,
+ * again whenever either element resizes, and writes it to the responsive context as the canvas
+ * padding the camera frames the scene with.
  *
- * `getBoundingClientRect()` returns *visually transformed* rects, so `measure` skips
- * transformed frames automatically (retrying until the transform clears) to avoid feeding
- * the scene a scaled gap mid layout animation.
- *
- * `update` exists for the complementary case: when only an ancestor's `transform` changes
- * (e.g. motion FLIP settling), `ResizeObserver` doesn't fire, so nothing re-triggers
- * `measure`. Call `update()` once the transform settles (e.g. from
- * `onLayoutAnimationComplete`) to re-measure against the actual layout box.
+ * Returns:
+ * - `containerRef` — attach to the element that covers the whole canvas.
+ * - `safeAreaRef` — attach to the region the scene should stay visible in.
+ * - `update` — measures again on demand, for a change no resize reports, such as a `transform`
+ *   on an ancestor settling at the end of an animation.
  */
-export declare const useSceneSafeArea: (setCanvasPadding: (padding: CanvasPadding) => void, hasMiniSidebar: boolean, enabled?: boolean) => {
+export declare const useSceneSafeArea: () => {
     containerRef: (node: HTMLDivElement | null) => void;
     safeAreaRef: (node: HTMLDivElement | null) => void;
     update: () => void;

package/dist/configurator/ui/configurator-layout/universal/use-scene-safe-area.js

@@ -1 +1 @@
-import{useCallback as t,useEffect as e,useRef as r}from"react";import{canvasPaddingComponent as n}from"#package/domain";import{useFirstComponent as o}from"#package/react-sdk";export const useSceneSafeArea=(a,c,u=!0)=>{let i=r(null),l=r(null),m=r(null),s=r(null),f=r(0),h=r(()=>{}),g=o({componentTypes:[n]}),p=t(()=>{let t=l.current,e=m.current;if(!t||!e)return;let r=t.getBoundingClientRect(),n=e.getBoundingClientRect();if(Math.abs(r.width-t.offsetWidth)>1||Math.abs(r.height-t.offsetHeight)>1){if(f.current+=1,f.current>60){f.current=0;return}i.current&&cancelAnimationFrame(i.current),i.current=requestAnimationFrame(()=>h.current());return}f.current=0;let o={bottom:Math.max(0,r.bottom-n.bottom),left:Math.max(0,n.left-r.left),right:Math.max(0,r.right-n.right),top:Math.max(0,n.top-r.top)},u=c?.3:1,s=g?.state.bottom??1,p=g?.state.left??1,b=g?.state.right??u,d=g?.state.top??1;a({bottom:o.bottom*s,left:o.left*p,right:o.right*b,top:o.top*d})},[c,g?.state.bottom,g?.state.left,g?.state.right,g?.state.top,a]);h.current=p;let b=t(()=>{i.current&&cancelAnimationFrame(i.current),i.current=requestAnimationFrame(p)},[p]),d=t(()=>{s.current?.disconnect(),s.current=null},[]),A=t(()=>{let t=l.current,e=m.current;if(!u||!t||!e)return void d();d();let r=new ResizeObserver(b);r.observe(t),r.observe(e),s.current=r},[d,u,b]),M=t(t=>{l.current=t,A()},[A]),x=t(t=>{m.current=t,A()},[A]);return e(()=>(A(),()=>{d(),i.current&&cancelAnimationFrame(i.current)}),[A,d]),{containerRef:M,safeAreaRef:x,update:b}};
+import{useLayoutSceneSafeArea as e}from"./use-layout-scene-safe-area.js";export const useSceneSafeArea=()=>e({enabled:!0,hasMiniSidebar:!1});

package/dist/configurator/ui/legacy/layout/steps/StepsNavigation.d.ts

@@ -1,10 +1,10 @@
 import type { Localizable } from '@salsita-ai/common/utils';
 export interface TopNavigationStep {
-    navigationStates: string[];
+    readonly navigationStates: readonly string[];
     label: Localizable;
 }
 export interface StepsNavigationComponentProps {
-    steps: TopNavigationStep[];
+    steps: readonly TopNavigationStep[];
 }
 declare const StepsNavigationComponent: (props: StepsNavigationComponentProps) => import("react/jsx-runtime").JSX.Element;
 /**

package/dist/configurator/ui/phoenix-layout-elements/header/common/step-navigation/StepsNavigation.d.ts

@@ -1,9 +1,9 @@
 import type { Localizable } from '@salsita-ai/common/utils';
 export interface TopNavigationStep {
-    navigationStates: string[];
+    readonly navigationStates: readonly string[];
     label: Localizable;
 }
 export interface StepsNavigationComponentProps {
-    steps: TopNavigationStep[];
+    steps: readonly TopNavigationStep[];
 }
 export declare const StepsNavigation: import("react").MemoExoticComponent<(props: StepsNavigationComponentProps) => import("react/jsx-runtime").JSX.Element>;

package/dist/docs/complex-use-cases/filtered-controls-with-fix-dialog.mdx

@@ -46,25 +46,22 @@ countersinkNotAvailable:
 ```
 
 ```ts
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Plate: {
-        finishNotAvailable: s => {
-          return availableMaterials.some(state => state.material === s.material && state.finish === s.finish)
-        },
-        thicknessNotAvailable: s => {
-          return availableMaterials.some(
-            state => state.material === s.material && state.finish === s.finish && state.thickness === s.thickness
-          )
-        },
-        countersinkNotAvailable: s => {
-          return !s.someCounterSinkAdded || counterSinkThicknesses.includes(s.thickness)
-        },
-      },
-    })
-  )
-  .buildViolationExpressions()
+// src/invariants/invariants.ts
+export default phx.domain.implementCustomInvariants({
+  Plate: {
+    finishNotAvailable: s => {
+      return availableMaterials.some(state => state.material === s.material && state.finish === s.finish)
+    },
+    thicknessNotAvailable: s => {
+      return availableMaterials.some(
+        state => state.material === s.material && state.finish === s.finish && state.thickness === s.thickness
+      )
+    },
+    countersinkNotAvailable: s => {
+      return !s.someCounterSinkAdded || counterSinkThicknesses.includes(s.thickness)
+    },
+  },
+})
 ```
 
 With following control structure. Note the hierarchy of `fixableViolations`. The top input "fixes" all violations as it should never be disabled.

package/dist/docs/complex-use-cases/sketching.mdx

@@ -669,44 +669,6 @@ import { Model, attachComponent, configuratorBuilder } from './domain/index.js'
 // ... identical to the Code section above ...
 ```
 
-### Domain Setup (`domain/index.ts`)
-
-```typescript
-import { memoEval } from '@salsita-ai/sdk/domain'
-
-import { adminDomainBuilder } from './__generated/admin-implementation.js'
-import { generatedConfiguratorBuilder } from './__generated/configurator-builder.js'
-import {
-  domainBuilder,
-  implementCustomExpressions,
-  implementCustomInvariants,
-  invariantBuilder,
-} from './__generated/implementation.js'
-
-const violationExpressions = invariantBuilder.withInvariants(implementCustomInvariants({})).buildViolationExpressions()
-
-const customExpressions = implementCustomExpressions({
-  // ... as shown in Code section ...
-})
-
-const domainFactory = domainBuilder.withExpressions(violationExpressions).withExpressions(customExpressions).build()
-const adminDomainFactory = adminDomainBuilder.build()
-
-export const configuratorBuilder = generatedConfiguratorBuilder
-  .withDomainFactory(domainFactory)
-  .withAdminDomainFactory(adminDomainFactory)
-
-export * as AdminEnhancedDomain from './__generated/admin-enhanced-model.js'
-export * as AdminModel from './__generated/admin-model/index.js'
-export * as ApplicationTypes from './__generated/application-types.js'
-export * as EnhancedDomain from './__generated/enhanced-model.js'
-export * as Model from './__generated/model/index.js'
-
-export { attachAdminComponent, createAdminRecipe } from './__generated/admin-implementation.js'
-export { attachComponent, createRecipe } from './__generated/implementation.js'
-export { createPresets } from './__generated/presets.js'
-```
-
 ### Domain Configuration (`domain/domain.yaml`)
 
 ```yaml

package/dist/docs/controls/select-attribute/cardselect.mdx

@@ -99,19 +99,15 @@ components:
 Optionally disable specific options using invariants. The control performs a dry run for each option and disables those that would violate your rules. Provide a clear message; if multiple violations apply, messages are concatenated.
 
 ```typescript
-// domain/index.ts (extract)
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Table: {
-        trunkDisabled: s =>
-          s.edgeFinish === 'TreeTrunk'
-            ? [{ type: 'trunkDisabled', severity: 'fatal', message: 'TreeTrunk finish is disabled because stuff!' }]
-            : [],
-      },
-    })
-  )
-  .buildViolationExpressions()
+// src/invariants/trunk-disabled.ts
+export default phx.domain.implementCustomInvariants({
+  Table: {
+    trunkDisabled: s =>
+      s.edgeFinish === 'TreeTrunk'
+        ? [{ type: 'trunkDisabled', severity: 'fatal', message: 'TreeTrunk finish is disabled because stuff!' }]
+        : [],
+  },
+})
 ```
 
 Register the invariant type in YAML so the system knows about it.

package/dist/docs/dimensions/3d-scene-integration/dimension-indicators.mdx

@@ -572,9 +572,9 @@ export type DimensionIndicatorState = {
    */
   readonly labelFontStyle?: 'normal' | 'italic'
   /**
-   * Font weight, which can be a numeric value, 'normal', or 'bold'.
+   * Font weight: a number, or a keyword such as 'normal' or 'bold'.
    */
-  readonly labelFontWeight?: number | 'normal' | 'bold'
+  readonly labelFontWeight?: number | string
   /**
    * Spacing between letters. Default is 0.
    */

package/dist/docs/dimensions/3d-scene-integration/editable-angle-indicator.mdx

@@ -131,7 +131,7 @@ export type EditableAngleIndicatorComponentState = AngleIndicatorBaseState &
     /** The instance name of the angleDimension component that will be used to update the angle. */
     readonly targetDimension: string
     /** An array of fixable violations. They will be ignored in the violation hint. */
-    readonly fixableViolations?: string[]
+    readonly fixableViolations?: readonly string[]
     /** The label of the input field. */
     readonly inputLabel?: Localizable
     /** The title of the modal. */

package/dist/docs/dimensions/3d-scene-integration/editable-distance-dimension-indicator.mdx

@@ -330,7 +330,7 @@ export type EditableDistanceDimensionIndicatorComponentState = DimensionIndicato
     /**
      * An array of fixable violations. They will be ignored in the violation hint.
      */
-    readonly fixableViolations?: string[]
+    readonly fixableViolations?: readonly string[]
     /**
      * The label of the input field.
      */

package/dist/docs/dimensions/3d-scene-integration/list-selector-dimension-indicator.mdx

@@ -365,7 +365,7 @@ export type ListSelectorDimensionIndicatorComponentState = DimensionIndicatorSta
     /**
      * An array of fixable violations. They will be ignored in the violation hint.
      */
-    readonly fixableViolations?: string[]
+    readonly fixableViolations?: readonly string[]
     /**
      * The title of the modal.
      */

package/dist/docs/drag-and-drop/drag-handle.mdx

@@ -71,7 +71,7 @@ export type DragHandleComponentState = {
    * It is defined in hessian normal form: `normal.x * x + normal.y * y + normal.z * z + constant = 0`
    * see https://threejs.org/docs/#api/en/math/Plane
    */
-  readonly surfaces: DraggableSurface[]
+  readonly surfaces: readonly DraggableSurface[]
 
   /**
    * The x property to be updated when the drag handle is dragged.

package/dist/docs/drag-and-drop/hotspot-handle.mdx

@@ -120,7 +120,7 @@ export type HotspotDragHandleComponentState = SceneEntityHtmlPositionState &
      * It is defined in hessian normal form: `normal.x * x + normal.y * y + normal.z * z + constant = 0`
      * see https://threejs.org/docs/#api/en/math/Plane
      */
-    readonly surfaces: DraggableSurface[]
+    readonly surfaces: readonly DraggableSurface[]
     /**
      * Instance name of hotspot binding. All hotspots which instance name is the same as the target will be dragged when the hotspot drag handle is dragged.
      */

package/dist/docs/drag-and-drop/planes.mdx

@@ -76,7 +76,7 @@ export type DragHandleComponentState = {
    * It is defined in hessian normal form: `normal.x * x + normal.y * y + normal.z * z + constant = 0`
    * see https://threejs.org/docs/#api/en/math/Plane
    */
-  readonly surfaces: DraggableSurface[]
+  readonly surfaces: readonly DraggableSurface[]
 
   /**
    * The x property to be updated when the drag handle is dragged.

package/dist/docs/drag-and-drop/rotatable.mdx

@@ -154,9 +154,9 @@ export type RotationHandleComponentState = {
 ```typescript
 export type RotatableSurface = {
   /**
-   * Unique identifier for the surface.
+   * Identifier of the surface.
    */
-  readonly key: string
+  readonly key?: string
 
   /**
    * The widget rotation axis in normal form. Usually corresponds to the target object's rotation axis.

package/dist/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-13T11:33:34.337Z",
+  "generatedAt": "2026-10-15T09:43:50.477Z",
   "categories": [
     {
       "name": "Phoenix",
@@ -164,6 +164,16 @@
           ],
           "source": "storybook-root"
         },
+        {
+          "title": "Layout Slots",
+          "description": "A project layout registered as `ConfiguratorLayout` builds its UI from its own components and from the pieces of the built-in layout it wants to keep. Those pieces are the members of `LayoutSlots`,...",
+          "path": "docs/phoenix/layout-slots.mdx",
+          "category": [
+            "Phoenix",
+            "Layout Slots"
+          ],
+          "source": "storybook-root"
+        },
         {
           "title": "Localization",
           "description": "Phoenix provides a localization system built on **Lingui** that enables multi-language support across your configurator. The system handles React components and server-side webhook processing,...",
@@ -264,6 +274,16 @@
           ],
           "source": "storybook-root"
         },
+        {
+          "title": "Testing",
+          "description": "A project's tests check its own logic, such as an expression on a preset, a transformer that completes an edit, a Blender projection or a migration, against the application the project ships. They...",
+          "path": "docs/phoenix/testing.mdx",
+          "category": [
+            "Phoenix",
+            "Testing"
+          ],
+          "source": "storybook-root"
+        },
         {
           "title": "Webhook Membership",
           "description": "Build component controls with React and browser SDKs without pulling them into the server webhook bundle. Phoenix keeps user-authored components and handlers in the frontend unless a file explicitly...",
@@ -686,6 +706,16 @@
           ],
           "source": "storybook-example"
         },
+        {
+          "title": "Custom Layout",
+          "description": "Make the configurator look like the brand's own product page. A furniture shop wants its table configurator to read like the rest of its site: a floating panel on the left with the product's name,...",
+          "path": "docs/layouts/custom-layout.mdx",
+          "category": [
+            "Layouts",
+            "Custom Layout"
+          ],
+          "source": "storybook-example"
+        },
         {
           "title": "Custom Price",
           "description": "The custom price footer component replaces the standard price display in the sidebar footer with a fully customizable React component. This allows you to create custom pricing interfaces, add...",
@@ -804,6 +834,17 @@
               ],
               "source": "storybook-example"
             },
+            {
+              "title": "In a Custom Layout",
+              "description": "A project wants the configurator arranged differently, for example with the sidebar on the left, but the sidebar itself is right as it is: the spec's tabs, property pages and sidebar footer, with...",
+              "path": "docs/layouts/sidebar/in-a-custom-layout.mdx",
+              "category": [
+                "Layouts",
+                "Sidebar",
+                "In a Custom Layout"
+              ],
+              "source": "storybook-example"
+            },
             {
               "title": "General",
               "description": "The sidebar is the primary navigation and control interface in Phoenix configurators. It provides a flexible container for property pages, tabs, summary views, and other interactive components that...",

package/dist/docs/integrations/woocommerce/local-development.mdx

@@ -133,7 +133,7 @@ The value of `WOOCOMMERCE_API_KEY` must correspond to the value of the 'API key'
 settings page and `WOOCOMMERCE_PRODUCT_NAME` must correspond to the name of the product template you created.
 
 - run development server (from this repo): `pnpm dev:server`
-- prepare local deployment (from the implementation project): `pnpm deployment:prepare-local`
+- prepare local deployment (from the implementation project): `pnpm phoenix deployment:prepare-local`
 - start the dev process (from the implementation project): `pnpm dev`
 - run bundle build (from the implementation project): `pnpm build`