@salsita-ai/sdk 0.50.0-develop.016963b09e → 0.50.0-develop.08837efd9c

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

@@ -0,0 +1,380 @@
+# Sidebar in a Custom Layout
+
+- [Use case](#use-case)
+- [Guide](#guide)
+- [Example](#example)
+- [Known gaps](#known-gaps)
+- [Test cases](#test-cases)
+- [Complete Implementation](#complete-implementation)
+
+## Use case
+
+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 their spacing, scrolling and empty states. The project writes its own layout, a `ConfiguratorLayout` element, and places the built-in sidebar in it as one piece, `LayoutSlots.DesktopSidebar`. The spec keeps describing what the sidebar shows; the layout only decides where it goes.
+
+Build the sidebar's controls yourself instead when they have to look like the brand's own, as [Custom Layout](?path=/docs/layouts-custom-layout--docs) does; [Configurator Interface → Loaded Configuration UI](?path=/docs/phoenix-configurator-interface--docs#loaded-configuration-ui) lists what a project layout can use. Stay with the built-in layout when its arrangement fits: [Sidebar - General](?path=/docs/layouts-sidebar-general--docs) describes what the spec configures in the sidebar.
+
+## Guide
+
+The layout registers itself under the name `ConfiguratorLayout` and mounts the scene, the safe area and the sidebar:
+
+```tsx
+// src/elements/ConfiguratorLayout.tsx
+import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+
+import { phx } from '../../.phoenix/phx.js'
+
+const GUTTER = 24
+const SIDEBAR_WIDTH = 380
+
+const ConfiguratorLayout = () => {
+  const { containerRef, safeAreaRef } = useSceneSafeArea()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+
+  return (
+    <div ref={containerRef} style={{ position: 'absolute', inset: 0 }}>
+      <LayoutSlots.Services />
+      <LayoutSlots.SharedCanvas />
+
+      {!isFullscreen && (
+        <aside
+          style={{
+            position: 'absolute',
+            insetBlock: GUTTER,
+            insetInlineStart: GUTTER,
+            inlineSize: SIDEBAR_WIDTH,
+          }}
+        >
+          <LayoutSlots.DesktopSidebar side="start" />
+        </aside>
+      )}
+
+      <div
+        ref={safeAreaRef}
+        style={{
+          position: 'absolute',
+          insetBlock: 0,
+          insetInlineStart: isFullscreen ? 0 : SIDEBAR_WIDTH + 2 * GUTTER,
+          insetInlineEnd: 0,
+          pointerEvents: 'none',
+        }}
+      >
+        <div style={{ position: 'absolute', insetBlockEnd: GUTTER, insetInlineStart: GUTTER, pointerEvents: 'auto' }}>
+          <LayoutSlots.DesktopToolbar />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+- **Size the container.** Without `width`, `LayoutSlots.DesktopSidebar` fills the width and height of its container. The layout positions the container above the canvas and gives it a size, here a fixed width and the full height less a gutter. The sidebar's content scrolls inside that height and its footer stays at the bottom.
+- **Say which side it is on.** The sidebar's tabs sit outside it. With `side="start"` they sit on its right, toward the scene; the default, `side="end"`, puts them on its left, as in the built-in layout.
+- **Frame the scene beside it.** `useSceneSafeArea()` measures the free region right of the sidebar, so the camera frames the table there.
+- **Decide what fullscreen does.** In fullscreen the sidebar stays in place, transparent and inert. This layout removes it while `phx.frontend.useIsFullscreenActive()` is set and lets the safe area start at the left edge, so the table is framed in the whole canvas. The toolbar's fullscreen button sets the flag.
+- **Read mode.** The same element renders a configuration shared for viewing. The sidebar handles read mode itself: it applies the spec's `$filter.modes`, so the tabs, which the spec limits to owners, are gone and the footer shows the price only. The banner that offers **Edit configuration** to a viewer is the layout's to mount: the built-in layout shows `LayoutSlots.DesktopReadonlyBanner` in read mode outside fullscreen, and it renders only when the spec sets `shareCloneToEdit` and the viewer's role may create configurations. This spec does not set it, so this layout mounts no banner.
+
+`LayoutSlots.DesktopSidebar` takes two optional props:
+
+| Prop    | Type                 | Default | Meaning                                                                                                                                                          |
+| ------- | -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `width` | CSS width            | none    | Fixed inline size; the sidebar then takes its content's height unless its container stretches it. Without it the sidebar fills its container's width and height. |
+| `side`  | `'start'` \| `'end'` | `'end'` | The side of the layout the sidebar is on; its tabs sit on the other side of it.                                                                                  |
+
+Its look follows the theme component `PhxDesktopSidebar`, as in the built-in layout, see [Theming](?path=/docs/phoenix-theming--docs).
+
+## Example
+
+The spec is a table with one property, its edge finish, on a **Design** tab and a short text on a **Details** tab, and a price. Nothing in the YAML refers to the layout.
+
+## 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 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.
+
+## Test cases
+
+- The sidebar sits on the left with its tabs on its right; the table is framed in the space right of the sidebar.
+- **Design** shows the edge finishes; choosing one changes the table. **Details** shows the text.
+- The footer shows the price and the finalize button.
+- Fullscreen removes the sidebar and frames the table in the whole canvas; leaving it brings the sidebar back.
+- With the **Read User** mock template the tabs are gone and the footer shows the price only.
+
+## Complete Implementation
+
+{/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}
+
+<details>
+<summary>Click to view the complete implementation files</summary>
+
+### ./spec/domain.yaml
+
+```yaml
+model:
+  latest:
+    entityTypes:
+      - Table
+    aliases:
+      RootEntity:
+        - Table
+    commonTypes:
+      EdgeFinish:
+        enum:
+          - None
+          - Facet
+          - Round
+          - TreeTrunk
+    shapes:
+      Table:
+        edgeFinish:
+          $ref: '#/model/latest/commonTypes/EdgeFinish'
+
+presets:
+  - rootEntityType: 'Table'
+    initialDomainEntities:
+      - id: 'Table-1'
+        type: 'Table'
+        edgeFinish: 'None'
+
+navigationStates:
+  - design
+  - details
+
+invariants:
+  Table:
+    trunkDisabled:
+      types:
+        - 'trunkDisabled'
+
+components:
+  Table:
+    propertyPage:
+      design:
+        $filter:
+          navigationStates:
+            - design
+        children:
+          - kind: propertyContainerGroup
+            props:
+              spacing: large
+            children:
+              - kind: propertyContainerItem
+                props:
+                  title: Edge Finish
+                  description: Select the edge finish for the table.
+                children:
+                  - kind: attributeCardSelector
+                    props:
+                      instanceName: edgeFinish
+      details:
+        $filter:
+          navigationStates:
+            - details
+        children:
+          - kind: propertyContainerItem
+            props:
+              title: Dimensions
+              description: 1600 × 800 mm, 750 mm high. Solid oak top on powder-coated steel legs.
+    sidebarTabs:
+      main:
+        $filter:
+          modes:
+            - owner
+        tabs:
+          - label: Design
+            navigationStates:
+              - design
+          - label: Details
+            navigationStates:
+              - details
+    price:
+      main:
+        price: 1200
+    fitRootPerspectiveCamera:
+      main:
+        priority: 1
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 1000
+        maxDistance: 9000
+        distance: 5000
+        azimuthAngle: 1.5
+        polarAngle: 1.1
+        fitMeshChanges: true
+        animateOnLoad: true
+    sceneEntityRemoteObject:
+      top:
+        fileUrl: '/models/tables.gltf'
+        objectName: RECHTHOEK_RECTANGLE
+        dimensionUnit: m
+      leg:
+        fileUrl: '/models/tables.gltf'
+        objectName: AXL_LEG
+        dimensionUnit: m
+    sceneEntityObjectProperties:
+      top:
+        offsetY: 820
+        morphTargetInfluences:
+          Facet:
+            value:
+              $read: $edgeFinishFacet
+            scaleOne: 1
+            scaleZero: 0
+          Bol:
+            value:
+              $read: $edgeFinishRound
+            scaleOne: 1
+            scaleZero: 0
+          Boomstamrand:
+            value:
+              $read: $edgeFinishTreeTrunk
+            scaleOne: 1
+            scaleZero: 0
+      leg:
+        morphTargetInfluences:
+          Length:
+            value: 1000
+            scaleOne: 3000
+            scaleZero: 1400
+          Width:
+            value: 700
+            scaleOne: 1300
+            scaleZero: 600
+          Height:
+            value: 780
+            scaleOne: 780
+            scaleZero: 740
+    attributeSelection:
+      edgeFinish:
+        value:
+          $bind: edgeFinish
+        options:
+          $read: $edgeFinishOptions
+```
+
+### ./src/elements/ConfiguratorLayout.tsx
+
+```tsx
+import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+
+import { phx } from '../../.phoenix/phx.js'
+
+const GUTTER = 24
+const SIDEBAR_WIDTH = 380
+
+const ConfiguratorLayout = () => {
+  const { containerRef, safeAreaRef } = useSceneSafeArea()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+
+  return (
+    <div ref={containerRef} style={{ position: 'absolute', inset: 0 }}>
+      <LayoutSlots.Services />
+      <LayoutSlots.SharedCanvas />
+
+      {!isFullscreen && (
+        <aside
+          style={{
+            position: 'absolute',
+            insetBlock: GUTTER,
+            insetInlineStart: GUTTER,
+            inlineSize: SIDEBAR_WIDTH,
+          }}
+        >
+          <LayoutSlots.DesktopSidebar side="start" />
+        </aside>
+      )}
+
+      <div
+        ref={safeAreaRef}
+        style={{
+          position: 'absolute',
+          insetBlock: 0,
+          insetInlineStart: isFullscreen ? 0 : SIDEBAR_WIDTH + 2 * GUTTER,
+          insetInlineEnd: 0,
+          pointerEvents: 'none',
+        }}
+      >
+        <div style={{ position: 'absolute', insetBlockEnd: GUTTER, insetInlineStart: GUTTER, pointerEvents: 'auto' }}>
+          <LayoutSlots.DesktopToolbar />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+### ./src/expressions/expressions.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomExpressions({
+  Table: {
+    $edgeFinishFacet: s => {
+      return s.edgeFinish === 'Facet' ? 1 : 0
+    },
+    $edgeFinishRound: s => {
+      return s.edgeFinish === 'Round' ? 1 : 0
+    },
+    $edgeFinishTreeTrunk: s => {
+      return s.edgeFinish === 'TreeTrunk' ? 1 : 0
+    },
+    $edgeFinishOptions: () => {
+      return [
+        {
+          label: 'None',
+          img: '/images/edge-none.png',
+          value: phx.domain.model.EdgeFinish.None,
+        },
+        {
+          label: 'Facet',
+          img: '/images/edge-facet.png',
+          value: phx.domain.model.EdgeFinish.Facet,
+        },
+        {
+          label: 'Round',
+          img: '/images/edge-round.png',
+          value: phx.domain.model.EdgeFinish.Round,
+        },
+        {
+          label: 'TreeTrunk',
+          img: '/images/edge-tree-trunk.png',
+          value: phx.domain.model.EdgeFinish.TreeTrunk,
+        },
+      ]
+    },
+  },
+})
+```
+
+### ./src/invariants/invariants.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomInvariants({
+  Table: {
+    trunkDisabled: s => {
+      if (s.edgeFinish === 'TreeTrunk') {
+        return [
+          {
+            type: 'trunkDisabled',
+            severity: 'fatal',
+            message: 'TreeTrunk finish is disabled because stuff!',
+          },
+        ]
+      }
+
+      return []
+    },
+  },
+})
+```
+
+</details>

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/transformers.mdx

@@ -433,6 +433,10 @@ The following sample application has all the above described transformers active
 - When the view changes to `Y`, the navigation state is changed to `C`.
 - When any entity is deselected in view `Z`, the view is changed to `X`.
 
+The example's own tests under `__tests__/` check these cases with `createMockDomainContext` on the config
+`createTestApplicationConfig` builds from the generated application; [Testing](?path=/docs/phoenix-testing--docs)
+shows how a project's test sets that up.
+
 ## Complete Implementation
 
 {/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}

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

@@ -161,6 +161,10 @@ const toolState = phx.frontend.useActiveToolState()
 const navigate = phx.frontend.useNavigate()
 const pushNavigate = phx.frontend.usePushNavigate()
 const popNavigate = phx.frontend.usePopNavigate()
+
+// 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
@@ -386,7 +390,7 @@ const PresetOverlay = phx.frontend.createPresetDeviceNotSupported(SmallScreenNot
 
 ### 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.
+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
@@ -417,7 +421,9 @@ export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout
 - `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`.
-- Nothing of the built-in layouts is rendered for it. The finalize page is `Legacy.CommonFinalizePage`, the dialog is `LayoutDialog`, and 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 not available to a project layout.
+- `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. `Legacy.CommonFinalizePage` shows the page of the `finalizePage` component in a dialog while one of its finalize navigation states is active, so a layout that shows a finalize button mounts it; without it the button changes the navigation state and nothing appears. It is marked deprecated and is the only exported piece that does this. `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. Read mode: `phx.frontend.useAccessService().accessInfo.viewMode`. Fullscreen: `phx.frontend.useIsFullscreenActive()` reads it and `phx.frontend.useSetFullscreen()` sets it; the layout decides what to hide. Preview: `usePreview()` from `@salsita-ai/sdk/configurator`.
 - Any project layout element named `ConfiguratorLayout` takes over the page.
 
 ## TransformerBuilder

package/dist/docs/phoenix/project-structure.mdx

@@ -53,7 +53,8 @@ Every file in `components/`, `elements/`, `expressions/`, `actions/`, `invariant
 (and their `admin/` counterparts) is imported by its location, so its default export must be what that folder's `phx`
 factory returns, or an array of those. A file that exports anything else, such as a plain React component in
 `elements/`, stops the application at start with an `Invalid default export in <file>` error that names the expected
-shape. Keep plain components and helpers in a `_*` folder.
+shape. When several files in `handlers/`, `elements/`, `transformers/`, `components/`, `admin/elements/` and
+`admin/components/` are wrong, the error lists all of them, one numbered line per file. Keep plain components and helpers in a `_*` folder.
 
 ### Admin Folders (src/admin/)
 

package/dist/docs/phoenix/testing.mdx

@@ -0,0 +1,140 @@
+# Testing
+
+- [Your application in a test](#your-application-in-a-test)
+- [Run the domain on a preset](#run-the-domain-on-a-preset)
+- [Test a transformer](#test-a-transformer)
+- [Mock a domain context](#mock-a-domain-context)
+- [Options](#options)
+
+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 run with
+Vitest in Node, without a browser or a server.
+
+## Your application in a test
+
+`createTestApplicationConfig` from `@salsita-ai/sdk/domain` is the way a test builds the project's
+application. It takes the generated application the test imports and returns its application config,
+typed with the project's entities, states and data, with no type argument at the call:
+
+```ts
+import { createTestApplicationConfig } from '@salsita-ai/sdk/domain'
+
+import { configuratorBuilder } from '../../.phoenix/domain.js'
+
+const config = createTestApplicationConfig(configuratorBuilder)
+
+config.domain.presets // the presets of spec/presets
+config.initialPublishedData // the published data the application starts with
+```
+
+`configuratorBuilder` from `.phoenix/domain.js` is the domain of the configurator: the model, expressions,
+invariants, actions, migrations, presets and the components declared in YAML. `configuratorConfig` from
+`.phoenix/configurator-config.js` is the whole configurator as the browser runs it, with every component,
+handler, element and transformer; it reads the frontend environment when it is imported, so a test that
+uses it stubs `phx.frontendEnv` first.
+
+A test passes the generated export to the helper and does not call the export's methods: they are how the
+SDK assembles an application, not an interface for tests, while the helper's call does not depend on that
+assembly.
+
+## Run the domain on a preset
+
+The config goes into `createDomainRuntime`, which runs the same systems as the configurator:
+
+```ts
+import { vi } from 'vitest'
+
+import { NoopAnalyticsSystem, createDomainRuntime, createTestApplicationConfig } from '@salsita-ai/sdk/domain'
+
+import { configuratorBuilder, createI18n } from '../../.phoenix/domain.js'
+
+const logger = {
+  info: vi.fn(),
+  error: vi.fn(),
+  warn: vi.fn(),
+  debug: vi.fn(),
+  verbose: vi.fn(),
+  appendToGlobalContext: vi.fn(),
+}
+const config = createTestApplicationConfig(configuratorBuilder)
+const runtime = createDomainRuntime({
+  config,
+  services: { analyticsService: new NoopAnalyticsSystem(), i18n: createI18n(), logger },
+})
+
+runtime.actions.domainContext.configurator.setExecutionMode('finalize')
+runtime.actions.domainData.setDomainData({
+  publishedData: config.initialPublishedData,
+  backendData: undefined,
+  frontendData: {},
+})
+runtime.actions.sessionContext.setSessionContext({ role: 'anonymous', data: {} })
+
+const preset = config.domain.presets[0]!
+runtime.actions.loadedData.completeConfiguratorLoad({
+  initialRevisionId: 'test',
+  initialEntities: preset.initialDomainEntities,
+  modelVersion: config.domain.domainFactory.modelVersion,
+  rootEntityType: preset.rootEntityType,
+  schemaIdentity: runtime.selectors.spec.getConfiguratorFactory(),
+})
+runtime.selectors.domainContext.configurator.getDomainContext().initialize()
+```
+
+## Test a transformer
+
+The domain of `configuratorBuilder` has no code-attached components and no transformers. A test adds the
+ones it needs, the way the configurator and the webhooks add them:
+
+```ts
+// Files that read `phx.domain` at module scope are imported after `.phoenix/domain.js`.
+const { customComponentOptics } = await import('../../.phoenix/configurator-domain-code.js')
+const { default: addCookingTop } = await import('../transformers/add-cooking-top.js')
+
+const config = createTestApplicationConfig(configuratorBuilder, {
+  componentModules: customComponentOptics,
+  transformers: {
+    importedTransformers: [{ origin: 'src/transformers/add-cooking-top.ts', exports: addCookingTop }],
+    specTransformers: [{ name: 'addCookingTop', priority: 30 }],
+  },
+})
+```
+
+`specTransformers` are the entries of the `transformers` section of `spec/application.yaml` that the test
+runs, with the priorities the spec gives them.
+
+## Mock a domain context
+
+`createMockState`, `createMockDomain` and `createMockDomainContext` take the same config and check the
+mock data against the project's types:
+
+```ts
+import { createMockDomainContext, createTestApplicationConfig } from '@salsita-ai/sdk/domain'
+
+const config = createTestApplicationConfig(configuratorBuilder)
+const preset = config.domain.presets[0]!
+const { domainContext, destroy } = createMockDomainContext(config, {
+  entities: preset.initialDomainEntities,
+  rootEntityType: preset.rootEntityType,
+  publishedData: config.initialPublishedData,
+  frontendData: {},
+  sessionData: {},
+  backendData: undefined,
+  mode: 'owner',
+  role: 'anonymous',
+  transformers: [],
+})
+```
+
+## Options
+
+| Option             | What it does                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `componentModules` | Component files added after the components the application already has, each `{ origin, exports }`                 |
+| `transformers`     | Replaces the application's transformers: files (`importedTransformers`) and spec entries (`specTransformers`)      |
+| `tag`              | The tag of the custom element the application mounts as; without it the application's own (`salsita-configurator`) |
+
+## See Also
+
+- [Best Practices](?path=/docs/phoenix-best-practices--docs) - Where custom code lives
+- [Transformers](?path=/docs/other-features-transformers--docs) - Writing transformers

package/dist/docs/phoenix/webhook-membership.mdx

@@ -4,21 +4,22 @@ Build component controls with React and browser SDKs without pulling them into t
 
 ## Choose Where Each File Runs
 
-| User file                                         | Frontend | Webhook |
-| ------------------------------------------------- | -------- | ------- |
-| Component or admin component without a directive  | Yes      | No      |
-| Component or admin component with `'use webhook'` | Yes      | Yes     |
-| Ordinary handler                                  | Yes      | No      |
-| Published-data or validator handler               | Yes      | Yes     |
-| Any other handler with `'use webhook'`            | Yes      | Yes     |
-| File under `src/webhooks/`                        | No       | Yes     |
+| User file                                            | Frontend | Webhook |
+| ---------------------------------------------------- | -------- | ------- |
+| Component or admin component without a directive     | Yes      | No      |
+| Component or admin component with `'use webhook'`    | Yes      | Yes     |
+| Ordinary handler                                     | Yes      | No      |
+| Published-data, validator or assistant setup handler | Yes      | Yes     |
+| Any other handler with `'use webhook'`               | Yes      | Yes     |
+| File under `src/webhooks/`                           | No       | Yes     |
 
-Published-data and validator handlers are detected when they register one of these APIs:
+Published-data, validator and assistant setup handlers are detected when they register one of these APIs:
 
 - `createMapPublishedRevisionDataHandler`
 - `createMapPublishedChunkedDataHandler`
 - `createDataRowValidatorHandler`
 - `createSheetValidatorHandler`
+- `phx.domain.createAssistantSetupHandler`
 
 ## Pin a Server-Safe Component
 

package/dist/docs/phoenix/webhooks.mdx

@@ -148,7 +148,7 @@ resources:
     s3Key: clientImage
 ```
 
-These resources are automatically made available as typed properties in task handlers via the `resources` parameter.
+These resources are automatically made available as typed properties in task handlers via the `resources` parameter. Two static resources with the same name are an error: `phoenix check` and `phoenix build` report the second entry (`DUPLICATE_RESOURCE_NAME`).
 
 #### Task Payload