@salsita-ai/sdk 0.50.0-develop.0b28d3ba99 → 0.50.0-develop.0d2418cc3b

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]}>

package/dist/docs/controls/scene/html-hotspots.mdx

@@ -38,8 +38,6 @@ Create the element using `phx.frontend.createCustomPhoenixEntityElement()`:
 import { IconButton } from '@mui/material'
 import { CaretUpDown } from '@phosphor-icons/react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixEntityElement('AnimationTrigger', () => {
   const { animationSystem } = phx.frontend.useConfigurator()
 
@@ -312,8 +310,6 @@ import { IconButton } from '@mui/material'
 import { CaretUpDown } from '@phosphor-icons/react'
 import { useCallback } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixEntityElement('AnimationTrigger', () => {
   const { animationSystem } = phx.frontend.useConfigurator()
 

package/dist/docs/controls/scene/object-html-hotspots.mdx

@@ -49,8 +49,6 @@ Create the element using `phx.frontend.createCustomPhoenixEntityElement()`:
 import { IconButton } from '@mui/material'
 import { CaretUpDown } from '@phosphor-icons/react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixEntityElement('AnimationTrigger', () => {
   const { animationSystem } = phx.frontend.useConfigurator()
 
@@ -254,8 +252,6 @@ import { IconButton } from '@mui/material'
 import { CaretUpDown } from '@phosphor-icons/react'
 import { useCallback } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixEntityElement('AnimationTrigger', () => {
   const { animationSystem } = phx.frontend.useConfigurator()
 

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

@@ -256,8 +256,6 @@ components:
 ### ./src/expressions/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Table: {
     $edgeFinishFacet: s => {
@@ -276,8 +274,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/trunk-disabled.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Table: {
     trunkDisabled: s => {

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

@@ -236,8 +236,6 @@ components:
 ### ./src/expressions/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Table: {
     $edgeFinishFacet: s => {
@@ -256,8 +254,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Table: {
     trunkDisabled: s => {

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

@@ -220,8 +220,6 @@ components:
 ### ./src/expressions/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Table: {
     $edgeFinishFacet: s => {
@@ -240,8 +238,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Table: {
     trunkDisabled: s => {

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

@@ -361,8 +361,6 @@ components:
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Chair: {
     $colorMaterialColor: (s, __, ctx) => {
@@ -381,8 +379,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Chair: {
     accentColorIncompatibility: (s, __, ctx) => {

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

@@ -194,8 +194,6 @@ components:
 ### ./src/expressions/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Table: {
     $topEdgeMorph: s => (s.hasTreeTrunkEdgeFinish ? 1 : 0),
@@ -206,8 +204,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Table: {
     trunkDisabled: s => {

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

@@ -212,8 +212,6 @@ components:
 ### ./src/expressions/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Table: {
     $edgeFinishFacet: s => {
@@ -232,8 +230,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Table: {
     trunkDisabled: s => {

package/dist/docs/controls/select-child-entity/cardselect.mdx

@@ -147,7 +147,7 @@ components:
               fixableViolations: ['tDisabled'] # Violations to ignore in tooltips
 ```
 
-The component dry-runs each option and disables those that would violate your domain invariants. Violation messages are concatenated and displayed in tooltips.
+The component dry-runs each option and disables those that would cause a `fatal` or `fixable` violation of your domain invariants. Violation messages are concatenated and displayed in tooltips. `fixableViolations` only leaves the listed violation types out of the tooltip: an option that causes them stays disabled. To make such an option selectable, repair the violation with a [transformer](?path=/docs/other-features-transformers--docs).
 
 ### Entity Tree Structure Requirements
 
@@ -208,7 +208,7 @@ interface ChildEntitySelectionOption {
 - All options rendered as cards with label and image; select → child entity replaced, 3D scene updates
 - Card layout respects `imageLayout` setting (square, vertical, horizontal)
 - Options violating invariants are disabled with violation tooltip (T legs)
-- Fixable violations keep option enabled with warning tooltip
+- Violation types listed in `fixableViolations` are left out of the tooltip; the option stays disabled
 
 ## Complete Implementation
 
@@ -365,8 +365,6 @@ components:
 ### ./src/expressions/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Table: {
     $options: () => {
@@ -407,8 +405,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Table: {
     tDisabled: s => {

package/dist/docs/controls/select-child-entity/listselect.mdx

@@ -200,9 +200,8 @@ interface ChildEntityListSelectorSchema {
      */
     readonly instanceName: string
     /**
-     * Array of violation type names that should be treated as warnings rather than errors.
-     * Options that trigger only these violations will remain selectable but show warning tooltips.
-     * Options triggering other violations will be disabled completely.
+     * Violation types to leave out of an option's tooltip. An option that would cause a `fatal` or `fixable`
+     * violation stays disabled whatever its type; a transformer that repairs the violation makes the option selectable.
      */
     readonly fixableViolations?: readonly string[]
     /**
@@ -235,9 +234,8 @@ interface ChildEntityListSelectorProps {
    */
   instanceName: string
   /**
-   * Array of violation type names that should be treated as warnings rather than errors.
-   * Options that trigger only these violations will remain selectable but show warning tooltips.
-   * Options triggering other violations will be disabled completely.
+   * Violation types to leave out of an option's tooltip. An option that would cause a `fatal` or `fixable`
+   * violation stays disabled whatever its type; a transformer that repairs the violation makes the option selectable.
    */
   fixableViolations?: readonly string[]
   /**
@@ -257,7 +255,7 @@ interface ChildEntityListSelectorProps {
 - All options rendered; select option → child entity replaced, 3D scene updates
 - Vertical mode shows dropdown; horizontal mode shows inline buttons
 - Options violating invariants are disabled with violation tooltip
-- Fixable violations keep option enabled with warning tooltip
+- Violation types listed in `fixableViolations` are left out of the tooltip; the option stays disabled
 
 ## Complete Implementation
 
@@ -422,8 +420,6 @@ components:
 ### ./src/expressions/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Table: {
     $options: () => {
@@ -464,8 +460,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Table: {
     tDisabled: s => {

package/dist/docs/controls/select-child-entity/toggleselect.mdx

@@ -190,9 +190,8 @@ interface ChildEntityToggleSelectorSchema {
      */
     readonly instanceName: string
     /**
-     * Array of violation type names that should be treated as warnings rather than errors.
-     * Options that trigger only these violations will remain selectable but show warning tooltips.
-     * Options triggering other violations will be disabled completely.
+     * Violation types to leave out of an option's tooltip. An option that would cause a `fatal` or `fixable`
+     * violation stays disabled whatever its type; a transformer that repairs the violation makes the option selectable.
      */
     readonly fixableViolations?: readonly string[]
     /**
@@ -225,9 +224,8 @@ interface ChildEntityToggleSelectorProps {
    */
   instanceName: string
   /**
-   * Array of violation type names that should be treated as warnings rather than errors.
-   * Options that trigger only these violations will remain selectable but show warning tooltips.
-   * Options triggering other violations will be disabled completely.
+   * Violation types to leave out of an option's tooltip. An option that would cause a `fatal` or `fixable`
+   * violation stays disabled whatever its type; a transformer that repairs the violation makes the option selectable.
    */
   fixableViolations?: readonly string[]
   /**
@@ -405,8 +403,6 @@ components:
 ### ./src/expressions/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Table: {
     $options: () => {
@@ -444,8 +440,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/table.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Table: {
     tDisabled: s => {