@salsita-ai/sdk 0.50.0-develop.f16492b14e → 0.50.0-develop.f354d3576d

package/dist/docs/complex-use-cases/navigation-reset-selection.mdx

@@ -8,7 +8,7 @@
 
 ## Use case
 
-The `createResetSelectionOnNavigationTransformer` automatically deselects entities when the user navigates to specific steps. This clears the active selection when entering certain workflow phases, ensuring users start each step without inherited selections.
+A transformer built with `when.navigated({ to: [...] }).then.deselect()` automatically deselects entities when the user navigates to specific steps. This clears the active selection when entering certain workflow phases, ensuring users start each step without inherited selections.
 
 **Scenarios** - Use this transformer when you need:
 
@@ -18,30 +18,30 @@ The `createResetSelectionOnNavigationTransformer` automatically deselects entiti
 
 ## Guide
 
-The `createResetSelectionOnNavigationTransformer` is added as a file in `src/transformers/`. It automatically injects a deselect update when navigating to specified states.
+The transformer is added as a file in `src/transformers/`. It automatically deselects when navigating to specified states.
 
-### Step 1: Import the transformer
+### Step 1: Add the transformer to your project
 
-Import the transformer function from the domain package:
+Create the transformer in a file under `src/transformers/`:
 
 ```typescript
-import { createResetSelectionOnNavigationTransformer } from '@salsita-ai/sdk/domain'
+// src/transformers/reset-selection.ts
+export default phx.frontend.transformerBuilder.when
+  .navigated({
+    to: [phx.applicationTypes.NavigationState.SecondStep],
+  })
+  .then.deselect()
+  .build('reset-selection')
 ```
 
-### Step 2: Add the transformer to your project
-
-Create the transformer in a file under `src/transformers/`:
+The transformer has two parts:
 
-```typescript
-// src/transformers/reset-selection.ts
-import { createResetSelectionOnNavigationTransformer } from '@salsita-ai/sdk/domain'
+- `navigated({ to: [...] })` lists the navigation states that should trigger deselection
+- `then.deselect()` deselects the selected entity
 
-export default phx.frontend.createTransformer(ctx =>
-  createResetSelectionOnNavigationTransformer([phx.applicationTypes.NavigationState.SecondStep], ctx)
-)
-```
+### Step 2: Turn the transformer on in the spec
 
-Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by name. For a transformer made with `build(name)` that is the name passed to `build(...)`, which must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). For a plain-function export it is the file name:
+Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by the name passed to `build(...)`, spelled exactly; the name must also match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match):
 
 ```yaml
 # spec/application.yaml
@@ -49,12 +49,7 @@ transformers:
   - name: reset-selection
 ```
 
-The transformer takes two arguments:
-
-- An array of navigation state names that should trigger deselection
-- The domain context object (`ctx`)
-
-The `priority` value determines when this transformer runs relative to other transformers. Lower numbers run first. System transformers typically run at priority 100, so use values below 100 for custom transformers that should run before system logic.
+An entry without a `priority` runs after the SDK's built-in transformers, in the order of the `transformers` section. A `priority` value moves it: the pipeline runs lower numbers first, and the default is `Infinity`. See [Transformers](?path=/docs/other-features-transformers--docs#transformer-pipeline) for the built-in priorities.
 
 ### Step 3: Define navigation states in YAML
 
@@ -72,10 +67,9 @@ navigationStates:
 You can deselect at multiple navigation states by adding more state names to the array:
 
 ```typescript
-transformer: createResetSelectionOnNavigationTransformer(
-  [ApplicationTypes.NavigationState.SecondStep, ApplicationTypes.NavigationState.Summary],
-  ctx
-)
+.navigated({
+  to: [phx.applicationTypes.NavigationState.SecondStep, phx.applicationTypes.NavigationState.Summary],
+})
 ```
 
 This deselects when entering either the SecondStep or Summary navigation states.
@@ -86,39 +80,11 @@ The transformer intercepts update batches and:
 
 1. Checks if any update is a navigation update
 2. Verifies if the new active state matches one of the specified states
-3. Injects a deselect update into the update batch
+3. Adds a deselect update to the batch, in place of any selection update the batch holds
 4. Returns the modified batch with both the navigation and deselect updates
 
 When the transformer triggers, any selected entity is deselected automatically. Users see the selection clear when they navigate to the configured state.
 
-### Transformer signature
-
-```typescript
-/**
- * Creates a transformer that resets selection when navigating to specified states.
- *
- * The transformer monitors navigation updates and automatically injects a deselect
- * update when the active state matches any of the provided navigation states.
- * This ensures entities are deselected when entering specific workflow phases.
- *
- * @param navigationStates - Array of navigation state names that trigger deselection
- * @param ctx - Domain context providing access to the navigation system
- * @returns Update transformer to return from a transformer file in src/transformers/
- *
- * @example
- * // Deselect when entering the summary step
- * createResetSelectionOnNavigationTransformer(['Summary'], ctx)
- *
- * @example
- * // Deselect at multiple workflow phases
- * createResetSelectionOnNavigationTransformer(['ConfigComplete', 'Summary', 'Checkout'], ctx)
- */
-function createResetSelectionOnNavigationTransformer<NAVIGATION_STATES extends string>(
-  navigationStates: NAVIGATION_STATES[],
-  ctx: DomainContext
-): UpdateTransformer
-```
-
 ### Understanding transformers
 
 Transformers are functions that can modify update batches before they're committed to the store. They allow you to:
@@ -127,7 +93,7 @@ Transformers are functions that can modify update batches before they're committ
 - Modify existing updates (like changing values or constraints)
 - Prevent certain updates from being applied
 
-The `createResetSelectionOnNavigationTransformer` adds a deselect update whenever navigation matches configured states, keeping your workflow clean and predictable.
+The `reset-selection` transformer adds a deselect update whenever navigation matches configured states, keeping your workflow clean and predictable. [Transformers](?path=/docs/other-features-transformers--docs) covers the other triggers and actions of `phx.frontend.transformerBuilder`.
 
 ## Example
 
@@ -261,8 +227,6 @@ transformers:
 import { SelectionHotspot } from '@salsita-ai/sdk/configurator'
 import { htmlHotspotComponent, memoEval } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default [
   phx.domain.attachComponent
     .withComponent(htmlHotspotComponent, 'main')
@@ -285,13 +249,12 @@ export default [
 ### ./src/transformers/reset-selection.ts
 
 ```ts
-import { createResetSelectionOnNavigationTransformer } from '@salsita-ai/sdk/domain'
-
-import { phx } from '../../.phoenix/phx.js'
-
-export default phx.frontend.createTransformer(ctx =>
-  createResetSelectionOnNavigationTransformer([phx.applicationTypes.NavigationState.SecondStep], ctx)
-)
+export default phx.frontend.transformerBuilder.when
+  .navigated({
+    to: [phx.applicationTypes.NavigationState.SecondStep],
+  })
+  .then.deselect()
+  .build('reset-selection')
 ```
 
 </details>

package/dist/docs/complex-use-cases/navigation-reset-undo.mdx

@@ -18,7 +18,7 @@ The `ResetUndoListener` component clears the undo/redo history when the user nav
 
 ## Guide
 
-The `ResetUndoListener` is added to your configurator through the `OnLoadProvider` in the build configuration. It listens for navigation changes and clears the undo stack when entering specified states.
+The `ResetUndoListener` is mounted in a provider created with `phx.frontend.createOnConfiguratorReadyProvider`. It listens for navigation changes and clears the undo stack when entering specified states.
 
 ### Step 1: Import the component
 
@@ -28,20 +28,21 @@ Import `ResetUndoListener` from the configurator package:
 import { ResetUndoListener } from '@salsita-ai/sdk/configurator'
 ```
 
-### Step 2: Add the listener to your config
+### Step 2: Add the listener to your configurator
 
-Use the `OnLoadProvider` in your build configuration to mount the listener:
+Mount the listener in a provider that wraps the configurator, the default export of a file in `src/elements/`:
 
-```typescript
-const config = configuratorBuilder.buildConfig({
-  ui: {
-    OnLoadProvider: ({ children }) => (
-      <>
-        <ResetUndoListener navigationStates={[ApplicationTypes.NavigationState.SecondStep]} />
-        {children}
-      </>
-    ),
-  },
+```tsx
+// src/elements/OnConfiguratorReady.tsx
+import { ResetUndoListener } from '@salsita-ai/sdk/configurator'
+
+export default phx.frontend.createOnConfiguratorReadyProvider(({ children }) => {
+  return (
+    <>
+      <ResetUndoListener navigationStates={[phx.applicationTypes.NavigationState.SecondStep]} />
+      {children}
+    </>
+  )
 })
 ```
 
@@ -62,12 +63,9 @@ navigationStates:
 
 You can reset the undo stack at multiple navigation states by adding more state names to the array:
 
-```typescript
+```tsx
 <ResetUndoListener
-  navigationStates={[
-    ApplicationTypes.NavigationState.SecondStep,
-    ApplicationTypes.NavigationState.Summary
-  ]}
+  navigationStates={[phx.applicationTypes.NavigationState.SecondStep, phx.applicationTypes.NavigationState.Summary]}
 />
 ```
 
@@ -222,8 +220,6 @@ components:
 ```tsx
 import { ResetUndoListener } from '@salsita-ai/sdk/configurator'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createOnConfiguratorReadyProvider(({ children }) => {
   return (
     <>

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

@@ -626,7 +626,7 @@ const handles = ctx.sketchingProjections.getSketchingHandlePoints(state, s.$scen
 
 Rendering note: sketching doesn’t render shapes for you. In this example, visuals come from simple custom Three.js shapes attached to the entities; feel free to swap in your own renderer.
 
-Useful references in code: `sceneEntitySelectHotspot`, `sceneEntityDeleteFab`, `sceneEntityCustomObjectComponent`, `sketching-projections.ts` (cache + API), `sketching.ts` (connections/epsilon).
+Useful references in code: `sceneEntitySelectHotspot`, `sceneEntityDeleteFab`, `sceneEntityObjectComponent`, `sketching-projections.ts` (cache + API), `sketching.ts` (connections/epsilon).
 
 ## Common pitfalls
 
@@ -659,7 +659,7 @@ The example starts with two Stairs entities connected at a 90‑degree angle, fo
 import * as THREE from 'three'
 
 import { createConfiguratorInterface } from '@salsita-ai/sdk/configurator'
-import { isSelectUpdate, memoEval, sceneEntityCustomObjectComponent } from '@salsita-ai/sdk/domain'
+import { isSelectUpdate, memoEval, sceneEntityObjectComponent } from '@salsita-ai/sdk/domain'
 import { Editor } from '@salsita-ai/sdk/editor'
 
 import { FullscreenWCTemplate } from '../common/page-templates/FullscreenWCTemplate.js'
@@ -993,8 +993,6 @@ import * as THREE from 'three'
 
 import { distanceUnitToDefault, memoEval, sceneEntityObjectComponent } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const renderSurfaceDrawing = (length: number) => {
   const lineShape = new THREE.Shape()
 
@@ -1091,8 +1089,6 @@ export default [
 ```ts
 import { memoEval } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Scene: {
     $recipes: memoEval(
@@ -1189,8 +1185,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 interface Point {
   readonly x: number
   readonly y: number
@@ -1375,8 +1369,6 @@ export default phx.domain.implementCustomInvariants({
 ```ts
 import { isSelectUpdate } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.transformerBuilder.when
   .entity(phx.domain.model.AnyDomainEntity.types)
   .created()

package/dist/docs/controls/custom.mdx

@@ -21,33 +21,26 @@ This example shows two custom controls: a button that updates multiple existing
 
 ## Guide
 
-Building custom controls requires creating React components that use the `phx.frontend` hooks. The interface is created using `createConfiguratorInterface` and provides type-safe access to the domain state and update mechanisms.
+Building custom controls requires creating React components that use the `phx.frontend` hooks. `phx.frontend` is the configurator interface, typed by your domain model, and provides type-safe access to the domain state and update mechanisms.
 
-### Step 1: Set up the configurator interface
+### Step 1: Use the `phx` global
 
-First, create the interface from your configurator builder:
-
-```typescript
-import { createConfiguratorInterface } from '@salsita-ai/sdk/domain'
-
-import { configuratorBuilder } from '../domain/index.js'
-
-export const phx.frontend = createConfiguratorInterface(configuratorBuilder)
-```
+In a project, `phx` is a global: the generated code creates the configurator interface from your spec and sets it as `phx.frontend` before any file in `src/` loads, so a control uses `phx.frontend` without importing it. The files of this Storybook example import `phx` from the generated `.phoenix/phx.js` instead, because several examples share one Storybook page; a project leaves that import out, as the snippets below do.
 
 ### Step 2: Create a custom control for updating entities
 
-To modify existing entities, use the `useUpdatedControl` hook. This hook takes an array of updates and returns an object with an `update` function and validation state (`disabled`, `hints`).
+To modify existing entities, use the `useUpdatedControl` hook. This hook takes an array of updates and returns an object with an `update` function and validation state (`disabled`, `hints`). Register the control with `phx.frontend.createCustomPhoenixEntityElement` and default-export it from a file in `src/elements/`:
 
-```typescript
-import { useMemo, useCallback } from 'react'
+```tsx
+// src/elements/CustomMagicControl.tsx
 import { Button } from '@mui/material'
-import { PropertyContainer, createCustomPhoenixEntityElement } from '@salsita-ai/sdk/ui'
+import { useCallback, useMemo } from 'react'
+
+import { PropertyContainer } from '@salsita-ai/sdk/ui'
 
-createCustomPhoenixEntityElement('CustomMagicControl', () => {
+export default phx.frontend.createCustomPhoenixEntityElement('CustomMagicControl', () => {
   const state = phx.frontend.useCommittedState()
 
-  // Calculate updates based on current state
   const updates = useMemo(() => {
     return state.entities
       .filter(e => e.type === 'Monitor')
@@ -62,13 +55,15 @@ createCustomPhoenixEntityElement('CustomMagicControl', () => {
       })
   }, [state.entities])
 
-  // Get update function with validation
   const { update, disabled } = phx.frontend.useUpdatedControl(updates)
 
-  const handleClick = useCallback((e: React.MouseEvent) => {
-    e.stopPropagation()
-    update()
-  }, [update])
+  const handleClick = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation()
+      update()
+    },
+    [update]
+  )
 
   return (
     <PropertyContainer.Item title="Custom input" description="Magic stuff....">
@@ -80,11 +75,11 @@ createCustomPhoenixEntityElement('CustomMagicControl', () => {
 })
 ```
 
-The `useUpdatedControl` hook prepares the updates and validates them against domain invariants. The returned `disabled` flag indicates whether the updates would violate any constraints.
+The `useUpdatedControl` hook dry-runs the updates against the domain invariants. The returned `disabled` flag is `true` when committing them would be rejected, because they would leave a `fixable` or `fatal` violation.
 
 ### Step 3: Register the custom control in the domain
 
-Add the custom element to the property page in your domain YAML:
+Add the custom element to the property page in your domain YAML. The `customElement` takes only `name`, and the element receives the `entityId` of the entity it is shown for:
 
 ```yaml
 components:
@@ -94,23 +89,29 @@ components:
         children:
           - kind: propertyContainerGroup
             props:
-              spacing: medium
+              spacing: large
             children:
-              - kind: customElement
-                props:
-                  name: CustomMagicControl
+              - kind: propertyContainerItem
+                props: {}
+                children:
+                  - kind: customElement
+                    props:
+                      name: CustomMagicControl
 ```
 
 ### Step 4: Create a custom control for adding entities
 
 To add new entities, use the `useCookedRecipes` hook. This hook takes recipes, a parent entity ID, and a collection path, returning a `create` function and validation state.
 
-```typescript
+```tsx
+// src/components/fab-hotspot.tsx
 import { IconButton } from '@mui/material'
+import { useCallback, useMemo } from 'react'
+
+import { type DomainEntityId, htmlHotspotComponent, memoEval } from '@salsita-ai/sdk/domain'
 import { PhxIcon } from '@salsita-ai/sdk/ui'
 
 const CustomFabRecipe = (props: { x: number; y: number; z: number }) => {
-  // Create recipes dynamically based on props
   const recipes = useMemo(() => {
     return [
       {
@@ -123,66 +124,73 @@ const CustomFabRecipe = (props: { x: number; y: number; z: number }) => {
     ]
   }, [props.x, props.y, props.z])
 
-  // Get create function with validation
   const { create, disabled, hints } = phx.frontend.useCookedRecipes(
     recipes,
     'Console-1' as DomainEntityId<'Console'>,
     'Console.$monitors'
   )
 
-  const handleClick = useCallback((e: React.MouseEvent) => {
-    e.stopPropagation()
-    create()
-  }, [create])
+  const handleClick = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation()
+      create()
+    },
+    [create]
+  )
 
   return (
-    <IconButton
-      onClick={handleClick}
-      title={hints}
-      disabled={disabled}
-      color="primary"
-    >
+    <IconButton onClick={handleClick} color="primary" title={hints} disabled={disabled}>
       <PhxIcon name="Plus" />
     </IconButton>
   )
 }
 ```
 
-The `useCookedRecipes` hook validates recipes against domain constraints. The `hints` return value contains user-friendly error messages if validation fails.
+The `useCookedRecipes` hook validates recipes against domain constraints. The `hints` return value contains user-friendly error messages if validation fails. The complete file also styles the button.
 
 ### Step 5: Attach the custom control to the scene
 
-Use the `phx.domain.attachComponent` API to place custom components in the 3D scene as HTML hotspots:
+Place the control in the 3D scene as an HTML hotspot: in the same file, default-export an `htmlHotspotComponent` attached with `phx.domain.attachComponent`. Files in `src/components/` are loaded by convention, so the default export is all the registration it needs:
 
-```typescript
-import { htmlHotspotComponent, memoEval } from '@salsita-ai/sdk/domain'
+```tsx
+// src/components/fab-hotspot.tsx (continued)
+export default phx.domain.attachComponent
+  .withComponent(htmlHotspotComponent, 'fab')
+  .withEntity('Console')
+  .withGradualFilter({ selectedEntityIds: s => [s.id] })
+  .attach(
+    memoEval(
+      s => [s.$monitors],
+      monitors => {
+        const monitor = monitors.at(-1)
 
-export default configuratorBuilder.defineConfig({
-  components: [
-    phx.domain.attachComponent
-      .withComponent(htmlHotspotComponent, 'fab')
-      .withEntity('Console')
-      .withGradualFilter({
-        selectedEntityIds: s => [s.id],
-      })
-      .attach(
-        memoEval(
-          s => [s.$fabOffsetX, s.$fabOffsetY, s.$fabOffsetZ],
-          (x, y, z) => ({
-            offsetX: x,
-            offsetY: y,
-            offsetZ: z,
-            unit: 'mm',
-            node: <CustomFabRecipe x={x} y={y} z={z} />,
+        if (!monitor || monitors.length === 2) {
+          return {
+            offsetX: 0,
+            offsetY: 0,
+            offsetZ: 0,
+            node: null,
             controlHotspot: true,
-          })
-        )
-      ),
-  ],
-})
+          }
+        }
+
+        const x = monitor.x + 600
+        const y = monitor.y
+        const z = monitor.z
+
+        return {
+          offsetX: x,
+          offsetY: y,
+          offsetZ: z,
+          node: <CustomFabRecipe x={x} y={y} z={z} />,
+          controlHotspot: true,
+        }
+      }
+    )
+  )
 ```
 
-The gradual filter controls when the hotspot appears, and the offset expressions position it in 3D space.
+The gradual filter shows the hotspot only while the console is selected, and the expression places it next to the last monitor, or hides it once the console has two monitors.
 
 ### Available hooks reference
 
@@ -199,25 +207,25 @@ The `phx.frontend` provides many hooks for different scenarios:
 
 - `useUpdatedControl(updates)`: Prepare and validate entity modifications
 - `useCookedRecipes(recipes, parentId, collection)`: Prepare and validate entity creation
-- `useCookedReplaceRecipes(recipes, entityId)`: Prepare and validate entity replacement
+- `useCookedReplaceRecipes(entityId, recipes)`: Prepare and validate entity replacement
 - `useDeletedEntity(entityId)`: Prepare and validate entity deletion
 
 **Validation hooks:**
 
-- `useStateValidity()`: Check if the current state is valid
-- `useControlViolations(fixableViolations)`: Map violations to user-friendly messages
+- `useStateValidity()`: Read the validity of the last committed state; its `severity` is `null`, `'notice'` or `'warning'`, because a change that leaves a `fixable` or `fatal` violation is never committed
+- `useControlViolations(fixableViolations)`: Return a function that maps a dry-run state emission to `{ disabled, hints, violations }`, leaving the given violation types out of the hints
 - `useFinalizeViolations()`: Check if the state can be finalized
 
-**Specialized control hooks:**
+**Specialized control hooks**, each taking the entity id and the instance name of the control's component:
 
-- `useDistanceDimension()`: Manage distance/length attributes with unit conversion
-- `useGenericDimension()`: Manage generic numerical attributes
-- `useAngleDimension()`: Manage angle attributes
-- `useAttributeSelection()`: Manage selection from attribute options
-- `useAttributeSwitch()`: Manage boolean attribute toggles
-- `useChildEntitySelection()`: Manage selection from child entity lists
-- `useSwatchSelection()`: Manage material/color swatch selection
-- `useTextValue()`: Manage text input
+- `useDistanceDimension(entityId, instanceName)`: Manage distance/length attributes with unit conversion
+- `useGenericDimension(entityId, instanceName)`: Manage generic numerical attributes
+- `useAngleDimension(entityId, instanceName)`: Manage angle attributes
+- `useAttributeSelection(entityId, instanceName)`: Manage selection from attribute options
+- `useAttributeSwitch(entityId, instanceName)`: Manage boolean attribute toggles
+- `useChildEntitySelection(entityId, instanceName)`: Manage selection from child entity lists
+- `useSwatchSelection(entityId, instanceName, fixableViolations)`: Manage material/color swatch selection
+- `useTextValue(entityId, instanceName)`: Manage text input
 
 For complete type definitions and documentation, see `ConfiguratorInterface` exported from `@salsita-ai/sdk/configurator`.
 
@@ -473,7 +481,6 @@ transformers:
 ```ts
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
 import { getMonitorRenderingComponents } from '../../../../common/monitor-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getConsoleRenderingComponents('Console', phx.domain.attachComponent),
@@ -490,8 +497,6 @@ import { useCallback, useMemo } from 'react'
 import { type DomainEntityId, htmlHotspotComponent, memoEval } from '@salsita-ai/sdk/domain'
 import { PhxIcon } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const CustomFabRecipe = (props: { x: number; y: number; z: number }) => {
   const recipes = useMemo(() => {
     return [
@@ -586,8 +591,6 @@ import { useCallback, useMemo } from 'react'
 
 import { PropertyContainer } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixEntityElement('CustomMagicControl', () => {
   const state = phx.frontend.useCommittedState()
 
@@ -630,8 +633,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('CustomMagicControl
 ```ts
 import type { DomainEntityId } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Room: {
     $childRecipes: s => {

package/dist/docs/controls/manage-child-entities/entitychildrenlist.mdx

@@ -222,8 +222,6 @@ components:
 import { type DomainEntityId, memoEval, propertyPageComponent } from '@salsita-ai/sdk/domain'
 import { EntityChildActionDelete, EntityChildActionSelect, EntityChildrenList } from '@salsita-ai/sdk/react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const SceneList = ({ entityId }: { entityId: DomainEntityId<'Scene'> }) => {
   return (
     <EntityChildrenList
@@ -257,8 +255,6 @@ export default [
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Group: {
     $center: s => {

package/dist/docs/controls/nullable-attributes.mdx

@@ -282,8 +282,6 @@ components:
 ### ./src/expressions/bucky-ball.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   BuckyBall: {
     $color: s => {

package/dist/docs/controls/scene/custom-controls.mdx

@@ -38,8 +38,6 @@ Create the element using `phx.frontend.createCustomPhoenixEntityElement()`. The
 ```tsx
 import { Billboard, Circle, Text } from '@react-three/drei'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixEntityElement('SectionLabel', () => {
   return (
     <Billboard position={[1500, 2250, -1500]}>
@@ -58,15 +56,18 @@ The `Billboard` component from drei ensures the element always faces the camera.
 
 ### Accessing Entity State
 
-The component can access configurator state through hooks. The `entityId` prop identifies which entity the control belongs to:
+The component can access configurator state through hooks. The `entityId` prop identifies which entity the control belongs to. It is typed as the id of any entity, so narrow it with the entity's `isId` before passing it to a typed hook such as `phx.frontend.useEntityState`; without the check the call does not compile. This sketch assumes `Item` has a string attribute `label`:
 
 ```tsx
-phx.frontend.createCustomPhoenixEntityElement('DynamicLabel', props => {
-  const entity = phx.frontend.useEntityState(props.entityId)
+export default phx.frontend.createCustomPhoenixEntityElement('DynamicLabel', ({ entityId }) => {
+  if (!phx.domain.model.Item.isId(entityId)) {
+    throw new Error(`Expected an Item entity id but received '${entityId}'.`)
+  }
+  const item = phx.frontend.useEntityState(entityId)
 
   return (
     <Billboard position={[0, 500, 0]}>
-      <Text fontSize={100}>{entity.label}</Text>
+      <Text fontSize={100}>{item.label}</Text>
     </Billboard>
   )
 })
@@ -616,8 +617,6 @@ components:
 ```tsx
 import { Billboard, Circle, Text } from '@react-three/drei'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixEntityElement('SectionLabel', () => {
   return (
     <Billboard position={[1500, 2250, -1500]}>