@salsita-ai/sdk 0.50.0-develop.b7caacb493 → 0.50.0-develop.b929a82a82

package/dist/docs/other-features/transformers.mdx

@@ -37,12 +37,31 @@ transformer is designed to work with component modifications direclty - i.e. usi
 
 ### Transformer pipeline
 
-Multiple transformers can be registered in a sequence (via the domain spec). They run in registration order. Each transformer receives the **updates produced by the previous transformer** (or the initial updates for the first). The same committed state is passed as **old state** for the whole pipeline: `getOldState()` and `getOld$Entity()` always refer to the domain state at the start of the emission.
+Every state emission, staged or committed, runs through one pipeline of transformers. The `transformers` section of the spec lists yours, and the pipeline orders them by ascending `priority`. An entry without `priority` gets `Infinity`, and entries with the same priority keep their order in the spec:
+
+```yaml
+transformers:
+  - name: revertBuiltInAutoSelection # no priority: Infinity, runs in spec order
+  - name: selectParentBranchOnBranchDeselect
+  - name: snapBranchLengthToVariableSteps
+    priority: 5000 # runs before every entry without a priority
+```
+
+The SDK's built-in transformers run in the same pipeline: cascade deletes (priority 10), reference pruning (20), adding created entities to their parent's collection (25), reference replacement (30), auto snap (40) and auto selection (100). The conversion of component modifications to entity modifications runs at `Infinity`, ahead of your transformers without a priority, so a transformer that reads component modifications (`when.component()`) needs a finite priority, like the `5000` of the snapping example below.
+
+The pipeline is a single pass: each transformer runs once per emission and receives the **updates produced by the previous transformer** (or the initial updates for the first); its output is not fed back to the transformers before it. The same committed state is passed as **old state** for the whole pipeline: `getOldState()` and `getOld$Entity()` always refer to the domain state at the start of the emission.
 
 The **new state** seen by a transformer is computed by applying its **input** updates (the output of the previous transformer) to that committed state. So the second transformer’s `getNewState()` / `getNew$Entity()` / violation checks reflect the state **after** the first transformer’s updates; the third transformer sees the state after the first two, and so on. In other words, transformations made in one transformer define the state that the next transformer sees as “after previous updates”—each transformer builds on the result of all prior transformers in the pipeline.
 
 This matters when ordering transformers (e.g. snap-then-validate) or when a later transformer depends on side effects (e.g. creations or modifications) emitted by an earlier one.
 
+When the pipeline runs:
+
+- **Before validation.** The invariants check the state the whole pipeline produced, in the same emission, so a transformer can repair a violation its change would cause (see `causes` below).
+- **Undone with the change.** The updates a transformer adds are committed with the change that triggered them, so one undo reverts both.
+- **At startup.** When the initial state has a `fatal` or `fixable` violation, the pipeline runs once with no input updates, and its updates are applied to the initial state before it is committed. Only a trigger that does not need an update, such as `when.entity([...]).violated([...])` or `always`, can repair a loaded configuration.
+- **In dry runs.** A control dry-runs each of its options to disable the ones that would fail, and a dry run is a `'committed'` emission. Your transformers run for every option a control checks, `onEmissionsOfKind(['committed'])` ones included, so keep them pure (no requests, no state outside the returned updates) and cheap.
+
 ## Examples
 
 In all the examples, we are working with a hierarchical tree structure where the primary entities are trees, branches, and leaves. Each tree can have multiple branches, and each branch can have multiple leaves. The branches can also have sub-branches, creating a nested structure.
@@ -51,12 +70,15 @@ In all the examples, we are working with a hierarchical tree structure where the
 - **Branch**: A sub-entity of a tree that can contain other branches and leaves. Branches have properties such as length and diameter.
 - **Leaf**: The smallest entity in the structure, attached to branches. Leaves do not contain other entities.
 
+Each snippet is the default export of its own file in `src/transformers/`, and the `transformers` section of the spec lists it by its `build(...)` name. The [complete implementation](#complete-implementation) shows each file with its imports.
+
 ### Side-Effect on Update Causing an Entity Violation
 
 This example demonstrates how to use a transformer to remove extraneous branches and leaves when a branch is shortened. The transformer reacts to modifications in the length of a branch and ensures that the branch does not violate space constraints by removing enough branches and leaves to fit the new length.
 
-```javascript
-export const removeExtraneousBranchesAndLeavesWhenShortened = phx.frontend.transformerBuilder.when
+```ts
+// src/transformers/remove-extraneous-branches-and-leaves-when-shortened.ts
+export default phx.frontend.transformerBuilder.when
   .entity(['Branch'])
   .modified({ atFields: ['length'] })
   .causes.self.violation(['notEnoughSpaceForBranchesOrLeaves'])
@@ -74,7 +96,7 @@ export const removeExtraneousBranchesAndLeavesWhenShortened = phx.frontend.trans
       })
     )
   })
-  .build('Remove extraneous branches and leaves when shortened')
+  .build('removeExtraneousBranchesAndLeavesWhenShortened')
 ```
 
 #### Individual Pieces Analyzed
@@ -99,20 +121,21 @@ export const removeExtraneousBranchesAndLeavesWhenShortened = phx.frontend.trans
 - `then` specifies what should happen when the transformer is triggered. In this case, we want to apply a side effect. There are two groups of actions that can be performed:
   - Raw update manipulation:
     - With `applySideEffect(ctx => /* side effect updates */)` the updates returned by the provided callback will be applied in addition to the original updates. This will be triggered for every matching update.
-    - With `overrideMatchinUpdates(ctx => /* side effect updates */)` the updates returned by the provided callback will replace the original **matched update**. This will be triggered for every matching update. Note that this action is not available in events which are not bound to a specific update - such as a violation check without a defined cause.
+    - With `overrideMatchingUpdate(ctx => /* side effect updates */)` the updates returned by the provided callback will replace the original **matched update**. This will be triggered for every matching update. Note that this action is not available in events which are not bound to a specific update - such as a violation check without a defined cause.
     - With `overrideAllUpdates(ctx => /* side effect updates */)` the updates returned by the provided callback will replace all original updates. This will be triggered only once for a single run of the transformer. This allows for implementation of transformers that behave similarly as the raw `UpdateTransformer`
-  - High-level actions: `select`, `deselect`, `navigate`, `changeView` - more on these in the other examples.
-- `build(name)` is the final step to create the transformer. The name identifies the transformer while tracing, and it is the name the `transformers` section of the spec refers to, so it must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). Note that this returns a `RegistrableTransformer`. Default-export it from a file in `src/transformers/` and list the name passed to `build(...)` in the `transformers` section of the spec; the generated code registers it. The shorter snippets on this page use descriptive names for readability; the complete implementation below uses names that match its files.
+  - High-level actions: `select`, `deselect`, `navigateTo`, `changeView` - more on these in the other examples.
+- `build(name)` is the final step to create the transformer. The name identifies the transformer while tracing, and it is the name the `transformers` section of the spec refers to, spelled exactly; it must also match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). Note that this returns a `RegistrableTransformer`. Default-export it from a file in `src/transformers/` and list the name passed to `build(...)` in the `transformers` section of the spec; the generated code registers it.
 
 ### Side-Effect on Update Causing Another Entity's Violation
 
 This example demonstrates how to use a transformer to prolong a parent branch when a new branch doesn't fit due to space constraints. The transformer reacts to the creation of a new branch and ensures that the parent branch has enough space by increasing its length.
 
-```javascript
-export const prolongParentBranchWhenNewBranchDoesntFit = phx.frontend.transformerBuilder.when
+```ts
+// src/transformers/prolong-parent-branch-when-new-branch-doesnt-fit.ts
+export default phx.frontend.transformerBuilder.when
   .entity(['Branch'])
   .created()
-  .causes.entity(WithBranches.types)
+  .causes.entity(phx.domain.model.WithBranches.types)
   .withId(ctx => ctx.getNew$Entity().$parent.id)
   .violation(['notEnoughSpaceForBranchesOrLeaves'])
   .then.applySideEffect(ctx => {
@@ -128,7 +151,7 @@ export const prolongParentBranchWhenNewBranchDoesntFit = phx.frontend.transforme
       }),
     ]
   })
-  .build('Prolong parent branch when new branch doesnt fit')
+  .build('prolongParentBranchWhenNewBranchDoesntFit')
 ```
 
 #### Individual Pieces Analyzed
@@ -136,7 +159,7 @@ export const prolongParentBranchWhenNewBranchDoesntFit = phx.frontend.transforme
 - `created()` specifies that the transformer should be triggered when a new `Branch` entity is created.
   - Unlike `modified()`, which reacts to changes in existing entities, `created()` focuses on the creation of new entities.
   - This is reflected in the context, where `ctx.getNew$Entity()` returns the newly created entity and `ctx.getOld$Entity()` is absent.
-- `causes.entity(WithBranches.types)` indicates that we want to check for violations in entities of types defined by the given alias.
+- `causes.entity(phx.domain.model.WithBranches.types)` indicates that we want to check for violations in entities of types defined by the given alias.
   - This is different from `self` as it targets related entities rather than the entity being directly modified or created.
 - `withId(ctx => ctx.getNew$Entity().$parent.id)` specifies that we want to check for violations in the parent branch of the newly created branch.
   - This selector helps in navigating from the newly created branch to its parent branch.
@@ -148,8 +171,9 @@ export const prolongParentBranchWhenNewBranchDoesntFit = phx.frontend.transforme
 
 This example demonstrates how to use a transformer to populate a branch with new branches and leaves when it grows. The transformer reacts to committed updates that increase the length of a branch and ensures that the branch is populated with the appropriate number of branches and leaves.
 
-```javascript
-export const populateWithBranchesAndLeavesWhenBranchGrew = phx.frontend.transformerBuilder
+```ts
+// src/transformers/populate-with-branches-and-leaves-when-branch-grew.ts
+export default phx.frontend.transformerBuilder
   .onEmissionsOfKind(['committed'])
   .when.entity(['Branch'])
   .modified({ atFields: ['length'] })
@@ -193,12 +217,12 @@ export const populateWithBranchesAndLeavesWhenBranchGrew = phx.frontend.transfor
       ),
     ]
   })
-  .build('Populate with branches and leaves when branch grew')
+  .build('populateWithBranchesAndLeavesWhenBranchGrew')
 ```
 
 #### Individual Pieces Analyzed
 
-- `onEmissionsOfKind(['committed'])` specifies that the transformer should be triggered only on committed updates, ignoring dry-runs and staged updates.
+- `onEmissionsOfKind(['committed'])` specifies that the transformer should be triggered only on committed updates, ignoring staged updates such as a drag in progress. Controls dry-run their options as committed emissions, so the transformer still runs in those dry runs.
   - This ensures that the transformer reacts only to finalized changes, which can help save CPU resources and avoid too radical changes in the data model while staging.
   - Note that this will become more useful when we allow suppressing invariants
     on dry-runs and staged updates as well. Then we will be able to save CPU on
@@ -212,8 +236,9 @@ export const populateWithBranchesAndLeavesWhenBranchGrew = phx.frontend.transfor
 
 This example demonstrates how to use a transformer to snap the length of a branch to variable steps based on its current length. The transformer reacts to committed updates to a system component and modifies the update before it gets processed by other system transformers.
 
-```javascript
-export const snapBranchLengthToVariableSteps = phx.frontend.transformerBuilder
+```ts
+// src/transformers/snap-branch-length-to-variable-steps.ts
+export default phx.frontend.transformerBuilder
   .onEmissionsOfKind(['committed'])
   .when.component([genericDimensionComponent])
   .instance(['length'])
@@ -236,7 +261,7 @@ export const snapBranchLengthToVariableSteps = phx.frontend.transformerBuilder
     }
     return [update]
   })
-  .build('Snap branch length to variable steps')
+  .build('snapBranchLengthToVariableSteps')
 ```
 
 #### Individual Pieces Analyzed
@@ -257,12 +282,13 @@ This example demonstrates how to use a transformer to override all updates and f
 - `created()` specifies that the transformer should be triggered when a new entity is created.
 - `overrideAllUpdates(ctx => ctx.updates.filter(update => !isSelectUpdate(update)))` filters out selection updates from all updates.
 
-```javascript
-export const revertBuiltInAutoSelection = phx.frontend.transformerBuilder.when
-  .entity(AnyDomainEntity.types)
+```ts
+// src/transformers/revert-built-in-auto-selection.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(phx.domain.model.AnyDomainEntity.types)
   .created()
   .then.overrideAllUpdates(ctx => ctx.updates.filter(update => !isSelectUpdate(update)))
-  .build('Revert built-in auto-selection')
+  .build('revertBuiltInAutoSelection')
 ```
 
 ### Hierarchical Selection - Select Parent Entity on Deselection
@@ -272,12 +298,13 @@ This example demonstrates how to use a transformer to select the parent branch w
 - `deselected({ inFavorOf: ['Tree'] })` specifies that the transformer should be triggered when a branch is deselected in favor of a tree.
 - `select.ancestorOfType(['Branch'])` selects the parent branch.
 
-```javascript
-export const selectParentBranchOnBranchDeselect = phx.frontend.transformerBuilder.when
+```ts
+// src/transformers/select-parent-branch-on-branch-deselect.ts
+export default phx.frontend.transformerBuilder.when
   .entity(['Branch'])
   .deselected({ inFavorOf: ['Tree'] })
   .then.select.ancestorOfType(['Branch'])
-  .build('Select parent branch on branch deselect')
+  .build('selectParentBranchOnBranchDeselect')
 ```
 
 ### Toggle Selection on Click
@@ -287,12 +314,13 @@ This example demonstrates how to use a transformer to deselect a branch when it
 - `selected({ occurrence: 'repeated' })` specifies that the transformer should be triggered when a branch is selected (clicked) repeatedly.
 - `then.deselect()` deselects the branch.
 
-```javascript
-export const toggleSelectionOnClick = phx.frontend.transformerBuilder.when
+```ts
+// src/transformers/toggle-selection-on-click.ts
+export default phx.frontend.transformerBuilder.when
   .entity(['Branch'])
   .selected({ occurrence: 'repeated' })
   .then.deselect()
-  .build('Toggle selection on click')
+  .build('toggleSelectionOnClick')
 ```
 
 ### Switch View on Selection
@@ -300,46 +328,49 @@ export const toggleSelectionOnClick = phx.frontend.transformerBuilder.when
 This example demonstrates how to use a transformer to change the view to `Z` when a leaf is selected.
 
 - `selected()` specifies that the transformer should be triggered when a leaf is selected.
-- `then.changeView(ViewStateTag.z)` changes the view to `Z`.
+- `then.changeView(phx.applicationTypes.ViewState.z)` changes the view to `Z`.
 
-```javascript
-export const switchToZViewWhenLeafIsSelected = phx.frontend.transformerBuilder.when
+```ts
+// src/transformers/switch-to-z-view-when-leaf-is-selected.ts
+export default phx.frontend.transformerBuilder.when
   .entity(['Leaf'])
   .selected()
-  .then.changeView(ViewStateTag.z)
-  .build('Switch to Z view when leaf is selected')
+  .then.changeView(phx.applicationTypes.ViewState.z)
+  .build('switchToZViewWhenLeafIsSelected')
 ```
 
 ### Clear Selection When Leaving Navigation State
 
 This example demonstrates how to use a transformer to clear the selection when navigating away from state `A`.
 
-- `navigated({ from: [NavigationStateTag.a] })` specifies that the transformer should be triggered when navigating away from state `A`.
+- `navigated({ from: [phx.applicationTypes.NavigationState.a] })` specifies that the transformer should be triggered when navigating away from state `A`.
 - `then.deselect()` clears the selection.
 
-```javascript
-export const clearSelectionWhenLeavingA = phx.frontend.transformerBuilder.when
+```ts
+// src/transformers/clear-selection-when-leaving-a.ts
+export default phx.frontend.transformerBuilder.when
   .navigated({
-    from: [NavigationStateTag.a],
+    from: [phx.applicationTypes.NavigationState.a],
   })
   .then.deselect()
-  .build('Clear selection when leaving A')
+  .build('clearSelectionWhenLeavingA')
 ```
 
 ### Force Selection For Certain Navigation State
 
 This example demonstrates how to use a transformer to select the first branch when navigating to state `A`.
 
-- `navigated({ to: [NavigationStateTag.a] })` specifies that the transformer should be triggered when navigating to state `A`.
+- `navigated({ to: [phx.applicationTypes.NavigationState.a] })` specifies that the transformer should be triggered when navigating to state `A`.
 - `then.select.entity(ctx => ctx.getOld$Root().$branches[0]?.id)` selects the first branch.
 
-```javascript
-export const selectFirstBranchWhenEnteringA = phx.frontend.transformerBuilder.when
+```ts
+// src/transformers/select-first-branch-when-entering-a.ts
+export default phx.frontend.transformerBuilder.when
   .navigated({
-    to: [NavigationStateTag.a],
+    to: [phx.applicationTypes.NavigationState.a],
   })
   .then.select.entity(ctx => ctx.getOld$Root().$branches[0]?.id)
-  .build('Select first branch when entering A')
+  .build('selectFirstBranchWhenEnteringA')
 ```
 
 ### Reset View on Navigation
@@ -347,47 +378,50 @@ export const selectFirstBranchWhenEnteringA = phx.frontend.transformerBuilder.wh
 This example demonstrates how to use a transformer to reset the view to `X` on any navigation.
 
 - `navigated()` specifies that the transformer should be triggered on any navigation.
-- `then.changeView(ViewStateTag.x)` changes the view to `X`.
+- `then.changeView(phx.applicationTypes.ViewState.x)` changes the view to `X`.
 
-```javascript
-export const resetViewOnNavigation = phx.frontend.transformerBuilder.when
+```ts
+// src/transformers/reset-view-on-navigation.ts
+export default phx.frontend.transformerBuilder.when
   .navigated()
-  .then.changeView(ViewStateTag.x)
-  .build('Reset view on navigation')
+  .then.changeView(phx.applicationTypes.ViewState.x)
+  .build('resetViewOnNavigation')
 ```
 
 ### Navigate When Switching Views
 
-This example demonstrates how to use a transformer to navigate to state `B` when the view changes to `Y`.
+This example demonstrates how to use a transformer to navigate to state `C` when the view changes to `Y`.
 
-- `viewChanged({ to: [ViewStateTag.y] })` specifies that the transformer should be triggered when the view changes to `Y`.
-- `then.navigateTo(NavigationStateTag.c)` navigates to state `C`.
+- `viewChanged({ to: [phx.applicationTypes.ViewState.y] })` specifies that the transformer should be triggered when the view changes to `Y`.
+- `then.navigateTo(phx.applicationTypes.NavigationState.c)` navigates to state `C`.
 
-```javascript
-export const navigateToBWhenSwitchingToXView = phx.frontend.transformerBuilder.when
+```ts
+// src/transformers/navigate-to-b-when-switching-to-x-view.ts
+export default phx.frontend.transformerBuilder.when
   .viewChanged({
-    to: [ViewStateTag.y],
+    to: [phx.applicationTypes.ViewState.y],
   })
-  .then.navigateTo(NavigationStateTag.c)
-  .build('Navigate to B when switching to X view')
+  .then.navigateTo(phx.applicationTypes.NavigationState.c)
+  .build('navigateToBWhenSwitchingToXView')
 ```
 
 ### Change View When Deselecting in a specific View
 
 This example demonstrates how to use a transformer to change the view to `X` when any entity is deselected in view `Z`.
 
-- `entity(AnyDomainEntity.types)` specifies that the transformer should be triggered for any domain entity type. This is useful when you want to apply the same logic to multiple entity types without specifying each one individually.
+- `entity(phx.domain.model.AnyDomainEntity.types)` specifies that the transformer should be triggered for any domain entity type. This is useful when you want to apply the same logic to multiple entity types without specifying each one individually.
 - `deselected()` specifies that the transformer should be triggered when any entity is deselected.
-- `and(ctx => ctx.getOldViewState() === ViewStateTag.z)` adds a condition to check if the old view state is `Z`.
-- `then.changeView(ViewStateTag.x)` changes the view to `X`.
+- `and(ctx => ctx.getOldViewState() === phx.applicationTypes.ViewState.z)` adds a condition to check if the old view state is `Z`.
+- `then.changeView(phx.applicationTypes.ViewState.x)` changes the view to `X`.
 
-```javascript
-export const changeViewToXWhenDeselecctingInViewZ = phx.frontend.transformerBuilder.when
-  .entity(AnyDomainEntity.types)
+```ts
+// src/transformers/change-view-to-x-when-deseleccting-in-view-z.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(phx.domain.model.AnyDomainEntity.types)
   .deselected()
-  .and(ctx => ctx.getOldViewState() === ViewStateTag.z)
-  .then.changeView(ViewStateTag.x)
-  .build('Change view to X when deselecting in view Z')
+  .and(ctx => ctx.getOldViewState() === phx.applicationTypes.ViewState.z)
+  .then.changeView(phx.applicationTypes.ViewState.x)
+  .build('changeViewToXWhenDeselecctingInViewZ')
 ```
 
 ## Tracing
@@ -771,8 +805,6 @@ import {
 import { GenericDimensionInput, SimpleRecipePanel } from '@salsita-ai/sdk/react'
 import { PropertyContainer } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const createCylinder = (height: number, diameter: number, color: string, offset: number) => {
   const cylinderGeometry = new CylinderGeometry(diameter / 2, diameter / 2, height, 32)
   const cylinderMaterial = new MeshBasicMaterial({ color })
@@ -920,7 +952,6 @@ export default [
 import { getIdSequence, memoEval } from '@salsita-ai/sdk/domain'
 
 import type { AnyDomainEntity } from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 import { BRANCH_SPACING } from '../_shared/spacing.js'
 
 export default phx.domain.implementCustomExpressions({
@@ -1007,8 +1038,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   WithBranches: {
     hasEnoughSpaceForBranches: self => self.$availableSpace >= self.$takenSpace,
@@ -1019,8 +1048,6 @@ export default phx.domain.implementCustomInvariants({
 ### ./src/transformers/change-view-to-x-when-deseleccting-in-view-z.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const changeViewToXWhenDeselecctingInViewZ = phx.frontend.transformerBuilder.when
   .entity(phx.domain.model.AnyDomainEntity.types)
   .deselected()
@@ -1034,8 +1061,6 @@ export default changeViewToXWhenDeselecctingInViewZ
 ### ./src/transformers/clear-selection-when-leaving-a.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const clearSelectionWhenLeavingA = phx.frontend.transformerBuilder.when
   .navigated({
     from: [phx.applicationTypes.NavigationState.a],
@@ -1049,8 +1074,6 @@ export default clearSelectionWhenLeavingA
 ### ./src/transformers/navigate-to-b-when-switching-to-x-view.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const navigateToBWhenSwitchingToXView = phx.frontend.transformerBuilder.when
   .viewChanged({
     to: [phx.applicationTypes.ViewState.y],
@@ -1066,12 +1089,11 @@ export default navigateToBWhenSwitchingToXView
 ```ts
 import range from 'lodash-es/range.js'
 
-import { phx } from '../../.phoenix/phx.js'
 import { BRANCH_SPACING } from '../_shared/spacing.js'
 
 const populateWithBranchesAndLeavesWhenBranchGrew = phx.frontend.transformerBuilder
   // this will make the transformer trigger only on committed updates
-  // dry-runs and staged updates will be ignored
+  // staged updates will be ignored, dry-runs of controls are committed emissions and still trigger it
   //
   // Note that this will become more useful when we allow suppressing invariants
   // on dry-runs and staged updates as well. Then we will be able to save CPU on
@@ -1130,8 +1152,6 @@ export default populateWithBranchesAndLeavesWhenBranchGrew
 ### ./src/transformers/prolong-parent-branch-when-new-branch-doesnt-fit.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const prolongParentBranchWhenNewBranchDoesntFit = phx.frontend.transformerBuilder.when
   .entity(['Branch'])
   .created()
@@ -1165,7 +1185,6 @@ export default prolongParentBranchWhenNewBranchDoesntFit
 ### ./src/transformers/remove-extraneous-branches-and-leaves-when-shortened.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { BRANCH_SPACING } from '../_shared/spacing.js'
 
 const removeExtraneousBranchesAndLeavesWhenShortened = phx.frontend.transformerBuilder.when
@@ -1200,8 +1219,6 @@ export default removeExtraneousBranchesAndLeavesWhenShortened
 ### ./src/transformers/reset-view-on-navigation.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const resetViewOnNavigation = phx.frontend.transformerBuilder.when
   .navigated()
   .then.changeView(phx.applicationTypes.ViewState.x)
@@ -1215,8 +1232,6 @@ export default resetViewOnNavigation
 ```ts
 import { isSelectUpdate } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const revertBuiltInAutoSelection = phx.frontend.transformerBuilder.when
   .entity(phx.domain.model.AnyDomainEntity.types)
   .created()
@@ -1229,8 +1244,6 @@ export default revertBuiltInAutoSelection
 ### ./src/transformers/select-first-branch-when-entering-a.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const selectFirstBranchWhenEnteringA = phx.frontend.transformerBuilder.when
   .navigated({
     to: [phx.applicationTypes.NavigationState.a],
@@ -1245,8 +1258,6 @@ export default selectFirstBranchWhenEnteringA
 ### ./src/transformers/select-parent-branch-on-branch-deselect.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 // hierarchical selection - when a branch is deselected, its parent branch is selected
 const selectParentBranchOnBranchDeselect = phx.frontend.transformerBuilder.when
   .entity(['Branch'])
@@ -1262,8 +1273,6 @@ export default selectParentBranchOnBranchDeselect
 ```ts
 import { genericDimensionComponent } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const snapBranchLengthToVariableSteps = phx.frontend.transformerBuilder
   .onEmissionsOfKind(['committed'])
   .when // This transformer is special because it doesn't work with entity modifications,
@@ -1307,8 +1316,6 @@ export default snapBranchLengthToVariableSteps
 ### ./src/transformers/switch-to-z-view-when-leaf-is-selected.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const switchToZViewWhenLeafIsSelected = phx.frontend.transformerBuilder.when
   .entity(['Leaf'])
   .selected()
@@ -1321,8 +1328,6 @@ export default switchToZViewWhenLeafIsSelected
 ### ./src/transformers/toggle-selection-on-click.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const toggleSelectionOnClick = phx.frontend.transformerBuilder.when
   .entity(['Branch'])
   .selected({ occurrence: 'repeated' })

package/dist/docs/other-features/violation-messages.mdx

@@ -505,8 +505,6 @@ components:
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const colorMap: Record<string, string> = {
   red: '#e74c3c',
   blue: '#3498db',
@@ -526,8 +524,6 @@ export default phx.domain.implementCustomExpressions({
 ```ts
 import { msg } from '@lingui/core/macro'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const colorLabels = {
   red: msg`red`,
   blue: msg`blue`,

package/dist/docs/other-features/violation-severity.mdx

@@ -20,6 +20,8 @@ All controls are disabled for levels fixable and higher
 
 All finalization buttons are (should be) disabled for levels warning and higher
 
+The example finalizes through a legacy `finalizePage` component; a new project declares `finalizeAction` components instead, see [Finalization](?path=/docs/phoenix-finalization--docs).
+
 ## Code
 
 In this example we create a simple invariant that reacts to the set state.
@@ -188,7 +190,6 @@ import { PropertyContainer } from '@salsita-ai/sdk/ui'
 
 import { MockFinalizePage } from '../../../../common/MockFinalizePage.js'
 import { getMockChairComponents } from '../../../../common/mock-chair-model/mock-chair-model-components.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getMockChairComponents('Scene', phx.domain.attachComponent),
@@ -234,8 +235,6 @@ export default [
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Scene: {
     isSceneValid: s => {

package/dist/docs/performance/clone-highlight.mdx

@@ -174,7 +174,6 @@ import { SelectionHotspot } from '@salsita-ai/sdk/configurator'
 import { htmlHotspotComponent, memoEval } from '@salsita-ai/sdk/domain'
 
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getConsoleRenderingComponents('ConsoleUnit', phx.domain.attachComponent),
@@ -208,8 +207,6 @@ export default [
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   ConsoleUnit: {
     $x: s => s.x,
@@ -221,7 +218,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { isConsoleOverlapping } from '../_shared/overlap.js'
 
 export default phx.domain.implementCustomInvariants({
@@ -251,7 +247,6 @@ export default phx.domain.implementCustomInvariants({
 import { type DomainEntityId } from '@salsita-ai/sdk/domain'
 
 import type * as EnhancedModel from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 import { CONSOLE_DEPTH, CONSOLE_WIDTH, type Coords, isConsoleOverlapping } from '../_shared/overlap.js'
 
 const distance = (a: Coords, b: Coords) => Math.sqrt((a.x - b.x) ** 2 + (a.z - b.z) ** 2)
@@ -327,8 +322,6 @@ export default phx.frontend.transformerBuilder.when
 ### ./src/transformers/initial.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.transformerBuilder.always.then
   .applySideEffect(ctx => {
     const $root = ctx.getNew$Root()

package/dist/docs/performance/dynamic-components.mdx

@@ -428,8 +428,6 @@ import {
   sceneEntityRemoteObjectComponent,
 } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default [
   phx.domain.attachComponent
     .withComponent(sceneEntityRemoteObjectComponent, 'drawers')
@@ -464,7 +462,6 @@ export default [
 import { memoEval } from '@salsita-ai/sdk/domain'
 
 import type { $DrawerCabinet } from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 
 const SEPARATOR_WIDTH = 30
 const FRAME_WIDTH = 50
@@ -616,7 +613,6 @@ export default phx.domain.implementCustomExpressions({
 
 ```ts
 import type * as EnhancedModel from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 import { isOverlapping } from '../_shared/overlap.js'
 
 const getCollisionFixingUpdates = (
@@ -678,8 +674,6 @@ export default phx.frontend.transformerBuilder.when
 ### ./src/transformers/initial.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.transformerBuilder.always.then
   .applySideEffect(ctx => {
     const $root = ctx.getNew$Root()

package/dist/docs/performance/editable-dimension-stress-test.mdx

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