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

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

@@ -153,10 +153,10 @@ The `formatControlViolationMessage` function is where the magic happens. It rece
 3. **Actionable guidance**: Tell users exactly what values are valid or how to fix the problem
 4. **Consistent terminology**: Use the same terms and units throughout your application
 
-Implement violations with custom message formatting in your domain TypeScript file:
+Implement violations with custom message formatting in a file of `src/invariants/`:
 
 ```typescript
-// domain/index.ts
+// src/invariants/invariants.ts
 
 // Pre-define translatable labels for nested localization
 const colorLabels = {
@@ -166,60 +166,56 @@ const colorLabels = {
   yellow: msg`yellow`,
 } as const
 
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Scene: {
-        itIsNotZero: s => {
-          if (s.x !== 0) {
-            return [
-              {
-                type: 'itIsNotZero',
-                severity: 'fatal',
-                message: 'Scene is not zero',
-                controlViolationPriority: 1,
-                formatControlViolationMessage: () => {
-                  return msg({
-                    message: `Scene is not zero: The position would be ${s.x} which is not equal to 0`,
-                  })
-                },
-              },
-            ]
-          }
-          return []
-        },
-        // ... tooMuchRight omitted for brevity ...
-
-        // Static violation: severity, message and controlViolationPriority
-        // are declared in YAML. Implementation only returns a boolean.
-        wayTooFarRight: s => s.x < 200,
-
-        colorPositionIncompatible: s => {
-          const compatibleColors = ['red', 'blue', 'green'] as const
-          if (s.x >= 200 && !compatibleColors.includes(s.color)) {
-            return [
-              {
-                type: 'colorPositionIncompatible',
-                severity: 'fatal',
-                message: 'Color is not compatible with far right position',
-                controlViolationPriority: 3,
-                formatControlViolationMessage: (_emission, { i18n }) => {
-                  const labels = new Intl.ListFormat(i18n.locale, {
-                    style: 'long',
-                    type: 'disjunction',
-                  }).format(compatibleColors.map(c => i18n.t(colorLabels[c])))
-
-                  return msg({ message: `Far right position is only available for ${labels}` })
-                },
-              },
-            ]
-          }
-          return []
-        },
-      },
-    })
-  )
-  .buildViolationExpressions()
+export default phx.domain.implementCustomInvariants({
+  Buckyball: {
+    itIsNotZero: s => {
+      if (s.x !== 0) {
+        return [
+          {
+            type: 'itIsNotZero',
+            severity: 'fatal',
+            message: 'Scene is not zero',
+            controlViolationPriority: 1,
+            formatControlViolationMessage: () => {
+              return msg({
+                message: `Scene is not zero: The position would be ${s.x} which is not equal to 0`,
+              })
+            },
+          },
+        ]
+      }
+      return []
+    },
+    // ... tooMuchRight omitted for brevity ...
+
+    // Static violation: severity, message and controlViolationPriority
+    // are declared in YAML. Implementation only returns a boolean.
+    wayTooFarRight: s => s.x < 200,
+
+    colorPositionIncompatible: s => {
+      const compatibleColors = ['red', 'blue', 'green'] as const
+      if (s.x >= 200 && !compatibleColors.includes(s.color)) {
+        return [
+          {
+            type: 'colorPositionIncompatible',
+            severity: 'fatal',
+            message: 'Color is not compatible with far right position',
+            controlViolationPriority: 3,
+            formatControlViolationMessage: (_emission, { i18n }) => {
+              const labels = new Intl.ListFormat(i18n.locale, {
+                style: 'long',
+                type: 'disjunction',
+              }).format(compatibleColors.map(c => i18n.t(colorLabels[c])))
+
+              return msg({ message: `Far right position is only available for ${labels}` })
+            },
+          },
+        ]
+      }
+      return []
+    },
+  },
+})
 ```
 
 ### Internationalization with Dynamic Content

package/dist/docs/phoenix/admin.mdx

@@ -421,49 +421,34 @@ export const handler = webhookBuilder
 
 The publishing workflow validates admin state, transforms entities, and stores JSON to S3. Configurators access published data via `ctx.publishedData` in expressions.
 
-For implementation examples, see `packages/demos/demo-finalize/src/handlers/map-published-revision-data.ts`.
+For implementation examples, see `packages/demos/demo-catalog-builder/src/handlers/map-published-chunked-data.ts`.
 
 For technical details about data transformation and storage, see [Data Sources - Published Data](?path=/docs/phoenix-data-sources--docs#published-data).
 
 ## Web Component Integration
 
-Admin functionality integrates through the configurator builder rather than requiring separate web component setup.
+Admin functionality is part of the same application as the configurator and needs no separate web component setup.
 
-### Configurator Builder Setup
+### Registering Admin Components
 
-In phx-cli projects, frontend entry is auto-generated in `.phoenix/`. Admin components are registered through `src/admin/components/`:
+The frontend entry is generated into `.phoenix/`, so a project never calls the configurator builder itself. Every file
+in `src/admin/components/` is picked up by its location and its default export is registered as admin components:
 
 ```typescript
 // src/admin/components/admin-components.tsx
-import { configuratorBuilder } from '.phoenix/frontend.js'
-import { customAdminOptics } from './optics.js'
-import { NotAuthenticatedPage } from '../pages/NotAuthenticatedPage.js'
-
-const config = configuratorBuilder
-  .withComponentOptics(customConfiguratorComponents)
-  .withAdminComponentOptics(customAdminOptics) // Register admin components
-  .buildConfig({
-    deploymentId: phx.runtimeConfig.DEPLOYMENT_ID,
-    persistence: {
-      type: 'server',
-      serverUrl: phx.runtimeConfig.SERVER_URL,
-    },
-    ui: {
-      notAuthenticatedPage: <NotAuthenticatedPage />, // Show when user not authenticated
-    },
-    // ... other config
-  })
+// ... customAdminOptics as defined in the example above
 
-phx.frontend.mountApplication(config)
+export default customAdminOptics
 ```
 
-Admin component files go in `src/admin/components/` and are automatically discovered by phx-cli.
+The page shown to a user who is not authenticated is an element. Create it with
+`phx.frontend.createNotAuthenticatedPage(...)` in a file under `src/elements/`.
 
 ### Built-in Admin Integration
 
 Phoenix automatically provides admin functionality when:
 
-1. Admin components are registered via `withAdminComponentOptics()`
+1. Admin components are default-exported from files in `src/admin/components/`
 2. Admin configuration exists in `phoenix.config.ts`
 3. User has admin session token
 
@@ -515,4 +500,4 @@ Ready to implement admin functionality in your Phoenix project? Here's what to e
 - **[Sessions and Access](?path=/docs/phoenix-sessions-and-access--docs)** - Understand admin authentication and permissions
 - **[Connected Data Sources](?path=/docs/phoenix-connected-data-sources--docs)** - Wire `$data` entries to Google Sheets or Excel; requires the embedded admin mode
 
-For hands-on examples, check out the finalize demo (`packages/demos/demo-finalize/`) which shows spec-driven admin using `createAdminPages` for presets and recipes. This demo demonstrates the YAML-based admin approach with publishing workflows rather than custom admin UI components.
+For hands-on examples, check out the Catalog Builder demo (`packages/demos/demo-catalog-builder/`), which shows spec-driven admin pages over connected and generated data, custom catalog pages beside them, admin model migrations, and the publishing workflow.

package/dist/docs/phoenix/best-practices.mdx

@@ -5,6 +5,7 @@
 1. **YAML is king** - 99% of configuration should be in spec/\*.yaml files
 2. **Custom code locations** (in order of preference):
    - `src/expressions/` - Computed/derived properties
+   - `src/actions/` - Named domain operations declared under `actions:`
    - `src/invariants/` - Business rule constraints
    - `src/transformers/` - Automatic state fixers
    - `src/handlers/` - Event & lifecycle handlers

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

@@ -25,8 +25,9 @@ The configurator interface is generated in `.phoenix/configurator-interface.ts`:
 
 ```typescript
 // .phoenix/configurator-interface.ts (AUTO-GENERATED - DO NOT EDIT)
-import {'{'} createConfiguratorInterface {'}'} from '@salsita-ai/sdk/configurator'
-import {'{'} configuratorBuilder {'}'} from './domain.js'
+import { createConfiguratorInterface } from '@salsita-ai/sdk/configurator'
+
+import { configuratorBuilder } from './domain.js'
 
 export const configuratorInterface = createConfiguratorInterface(configuratorBuilder)
 
@@ -64,9 +65,9 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 Access the configurator interface via `phx.frontend`:
 
 ```typescript
-export const CustomComponent = () => {'{'}
+export const CustomComponent = () => {
   // Access domain systems
-  const {'{'} navigationSystem, storeSystem {'}'} = phx.frontend.useDomain()
+  const { navigationSystem, storeSystem } = phx.frontend.useDomain()
 
   // Entity state hooks
   const rootEntity = phx.frontend.useRootEntityState()
@@ -76,11 +77,11 @@ export const CustomComponent = () => {'{'}
   const selectEntity = phx.frontend.useSelectEntity()
 
   // Type-safe entity access
-  if (selectedEntity && Cabinet.is(selectedEntity)) {'{'}
+  if (selectedEntity && Cabinet.is(selectedEntity)) {
     // selectedEntity is now typed as $Cabinet
     console.log(selectedEntity.width, selectedEntity.$area)
-  {'}'}
-{'}'}
+  }
+}
 ```
 
 ## Core Hooks
@@ -90,16 +91,16 @@ The configurator interface provides 100+ hooks organized by category. Use TypeSc
 ### Domain & Application Context
 
 ```typescript
-const ExampleComponent = () => {'{'}
+const ExampleComponent = () => {
   // Core domain systems
-  const {'{'} navigationSystem, storeSystem, entitySystem {'}'} = phx.frontend.useDomain()
+  const { navigationSystem, storeSystem, entitySystem } = phx.frontend.useDomain()
 
   // Domain application context
-  const {'{'} configurationPersistSystem {'}'} = phx.frontend.useDomainApplication()
+  const { configurationPersistSystem } = phx.frontend.useDomainApplication()
 
   // Full configurator context
-  const {'{'} imageRenderingSystem {'}'} = phx.frontend.useConfigurator()
-{'}'}
+  const { imageRenderingSystem } = phx.frontend.useConfigurator()
+}
 ```
 
 ### State Subscriptions
@@ -209,7 +210,7 @@ const validity = phx.frontend.useStateValidity()
 const controlViolations = phx.frontend.useControlViolations(entityId, controlId)
 
 // Finalize violations
-const {'{'} disabled, hints {'}'} = phx.frontend.useFinalizeViolations()
+const { disabled, hints } = phx.frontend.useFinalizeViolations()
 
 // Map violations to hints
 const mapViolationHints = phx.frontend.useMapViolationHints()
@@ -284,89 +285,89 @@ The interface provides factory functions for creating handlers and providers:
 
 ```typescript
 // Runs early in app startup, before session auth
-const OnApplicationStart = phx.frontend.createOnApplicationStartProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnApplicationStart = phx.frontend.createOnApplicationStartProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after session auth, before domain data loading
-const OnSessionReady = phx.frontend.createOnSessionReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnSessionReady = phx.frontend.createOnSessionReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after published data is parsed, before frontend/backend loading
-const OnPublishedDataReady = phx.frontend.createOnPublishedDataReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnPublishedDataReady = phx.frontend.createOnPublishedDataReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after frontend collection and parsing, before backend loading
-const OnFrontendDataReady = phx.frontend.createOnFrontendDataReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnFrontendDataReady = phx.frontend.createOnFrontendDataReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after backend loading, before preset selection and configurator initialization
-const OnBackendDataReady = phx.frontend.createOnBackendDataReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnBackendDataReady = phx.frontend.createOnBackendDataReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Runs after routing and preset selection are ready
-const OnRoutingReady = phx.frontend.createOnRoutingReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnRoutingReady = phx.frontend.createOnRoutingReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 
 // Wraps OwnerUi and ReadUi pages
-const OnConfiguratorReady = phx.frontend.createOnConfiguratorReadyProvider(({'{'} children {'}'}) => {'{'}
-  return <YourProvider>{'{'}children{'}'}</YourProvider>
-{'}'})
+const OnConfiguratorReady = phx.frontend.createOnConfiguratorReadyProvider(({ children }) => {
+  return <YourProvider>{children}</YourProvider>
+})
 ```
 
 ### Data Handlers
 
 ```typescript
 // Collect frontend data during initialization
-const collectFrontendData = phx.frontend.createCollectFrontendDataHandler(async (context) => {'{'}
-  return {'{'} customData: await fetchCustomData() {'}'}
-{'}'})
+const collectFrontendData = phx.frontend.createCollectFrontendDataHandler(async context => {
+  return { customData: await fetchCustomData() }
+})
 
 // Override which published chunks are fetched by the frontend.
 // See Publishing page for full documentation.
-const filterPublishedChunks = phx.frontend.createFilterPublishedChunksHandler(() => {'{'}
+const filterPublishedChunks = phx.frontend.createFilterPublishedChunksHandler(() => {
   const session = phx.frontend.useSession()
 
-  return useMemo(() => {'{'}
+  return useMemo(() => {
     if (session.sessionPayload?.role === 'admin') return ['styling', 'catalog-na']
     return ['styling']
-  {'}'}, [session.sessionPayload?.role])
-{'}'})
+  }, [session.sessionPayload?.role])
+})
 
 // Runs after preset data is loaded
-const onPresetLoaded = phx.frontend.createOnPresetLoadedHandler((entities, presetData) => {'{'}
+const onPresetLoaded = phx.frontend.createOnPresetLoadedHandler((entities, presetData) => {
   // Can modify preset entities before rendering
   return entities
-{'}'})
+})
 
 // Intercept navigation to index/presets page
-const onGoToIndex = phx.frontend.createOnGoToIndexHandler(() => {'{'}
+const onGoToIndex = phx.frontend.createOnGoToIndexHandler(() => {
   // Custom logic before navigating
-{'}'})
+})
 ```
 
 ### UI Components
 
 ```typescript
 // Custom Phoenix layout element
-const MyLayoutElement = phx.frontend.createCustomPhoenixLayoutElement(() => {'{'}
+const MyLayoutElement = phx.frontend.createCustomPhoenixLayoutElement('MyLayoutElement', () => {
   return <div>Custom Layout</div>
-{'}'})
+})
 
 // Custom Phoenix entity element
-const MyEntityElement = phx.frontend.createCustomPhoenixEntityElement(() => {'{'}
+const MyEntityElement = phx.frontend.createCustomPhoenixEntityElement('MyEntityElement', () => {
   return <mesh>...</mesh>
-{'}'})
+})
 
 // Custom page when auth fails
-const NotAuthenticatedPage = phx.frontend.createNotAuthenticatedPage(() => {'{'}
+const NotAuthenticatedPage = phx.frontend.createNotAuthenticatedPage(() => {
   return <div>Please log in</div>
-{'}'})
+})
 ```
 
 ### Preset UI
@@ -383,21 +384,55 @@ const PresetAction = phx.frontend.createPresetPageAction(PresetHelpAction)
 const PresetOverlay = phx.frontend.createPresetDeviceNotSupported(SmallScreenNotice)
 ```
 
+### 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.
+
+```typescript
+// src/elements/ConfiguratorLayout.tsx
+import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+
+const SIDEBAR_WIDTH = 320
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', () => {
+  const { containerRef, safeAreaRef } = useSceneSafeArea()
+
+  return (
+    <div ref={containerRef} style={{ position: 'absolute', inset: 0 }}>
+      <LayoutSlots.Services />
+      <LayoutSlots.SharedCanvas />
+      <aside style={{ position: 'absolute', insetBlock: 0, insetInlineStart: 0, inlineSize: SIDEBAR_WIDTH }}>
+        Project sidebar
+      </aside>
+      <div
+        ref={safeAreaRef}
+        style={{ position: 'absolute', insetBlock: 0, insetInlineStart: SIDEBAR_WIDTH, insetInlineEnd: 0, pointerEvents: 'none' }}
+      />
+    </div>
+  )
+})
+```
+
+- `LayoutSlots.SharedCanvas` renders the scene. It is absolutely positioned and fills its nearest positioned ancestor, so the layout's root is positioned and covers the page. The layout positions its own UI above the canvas and after it in the markup, as the `aside` does; unpositioned content is painted under the canvas.
+- `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.
+- Any project layout element named `ConfiguratorLayout` takes over the page.
+
 ## TransformerBuilder
 
 Use `transformerBuilder` to create entity transformers:
 
 ```typescript
 // Create a transformer that runs when specific conditions are met
-const cabinetTransformer = phx.frontend.transformerBuilder
-  .when(Cabinet.is)
-  .do((cabinet, context) => {'{'}
-    // Transform cabinet data
-    return {'{'}
-      ...cabinet,
-      $computedField: calculateSomething(cabinet)
-    {'}'}
-  {'}'})
+const cabinetTransformer = phx.frontend.transformerBuilder.when(Cabinet.is).do((cabinet, context) => {
+  // Transform cabinet data
+  return {
+    ...cabinet,
+    $computedField: calculateSomething(cabinet),
+  }
+})
 ```
 
 **Note**: The deprecated `createTransformer` function should not be used for new implementations.
@@ -407,19 +442,19 @@ const cabinetTransformer = phx.frontend.transformerBuilder
 The `updates` factory creates type-safe entity updates:
 
 ```typescript
-const {'{'} storeSystem {'}'} = phx.frontend.useDomain()
+const { storeSystem } = phx.frontend.useDomain()
 
 // Create new entity
-const createUpdates = phx.frontend.updates.create({'{'}
+const createUpdates = phx.frontend.updates.create({
   type: 'Cabinet',
   width: 800,
   height: 2000,
-{'}'})
+})
 
 // Modify existing entity
-const modifyUpdates = phx.frontend.updates.modify(cabinetId, {'{'}
+const modifyUpdates = phx.frontend.updates.modify(cabinetId, {
   width: 1000,
-{'}'})
+})
 
 // Delete entity
 const deleteUpdates = phx.frontend.updates.delete(cabinetId)

package/dist/docs/phoenix/deployments.mdx

@@ -464,7 +464,7 @@ Error: Failed to upload to S3
 
 - Run `deployment:prepare` again to get fresh presigned URLs
 - Check that `.upload-links.json` exists and is readable
-- Use `--skipUpload` / `-su` flag to test without uploading assets
+- Use `--skipUpload` / `--su` flag to test without uploading assets
 
 ### "Server URL is required"
 

package/dist/docs/phoenix/domain-model.mdx

@@ -565,9 +565,13 @@ A relation pair can have at most one composition owner. For an ownership relatio
 Relations are validated when the application spec is parsed:
 
 - **Every relation must be declared from both sides.** A relation on `A` targeting `B` needs a counterpart declared on `B` (or on an alias containing `B`) pointing back at `A` — with the opposite kind (`direct` ↔ `indirect`, `allOfType` ↔ `allOfType`) and the same `field`. A missing or mismatched counterpart fails parsing with `RELATION_MISSING_COUNTERPART`. Self‑referencing relations (target is the declaring type) act as their own counterpart and are exempt.
+- **The field of a relation must hold references to the entities the relation relates to.** A `direct` relation reads a field of the entity it is declared on, and the field must reference exactly the entity types of the target. An `indirect` relation reads a field of the target, and the field must reference exactly the entity types the relation is declared on. A field that is not a `DomainEntityId` with `references` fails parsing with `RELATION_FIELD_NOT_REFERENCE`, and one that references other entity types with `RELATION_FIELD_REFERENCES_OTHER_TYPES`.
+- **The field of a `direct` relation must hold its references the way the cardinality needs.** `1-1` needs one reference that is never `null`, `0-1` one reference or `null`, and `0-N` or `1-N` an array of references. Anything else fails parsing with `RELATION_FIELD_CARDINALITY_MISMATCH`. An `indirect` relation takes any of the three, because its cardinality counts the entities that point back.
 - **At most one side may carry `composedOf: true`.** A pair may have one owner or no owner. Two owning sides fail parsing with `RELATION_COUNTERPART_COMPOSED_OF_MISMATCH` because the pair would define ownership in both directions.
 - **Every entity type must be reachable from the root** through `composedOf` edges, otherwise parsing fails with `RELATION_ENTITY_NOT_IN_COMPOSITION_TREE`.
 
+**What the field checks leave out.** A field whose schema states its type as text (`tsType`) or combines schemas with `allOf` is not checked, because the parser cannot tell what it holds. With a wrong field of that kind a `direct` relation fails when it is read, and an `indirect` relation finds no related entities and fails only if its cardinality requires one. When an alias holds the field, the relation is accepted if the field fits in at least one entity type of the alias.
+
 **Why both sides?** The two declarations feed two different runtime systems. The `direct` side owns the id field and generates the reference bookkeeping: dangling ids are pruned when the referenced entity is deleted, and ids are written on create and replace. The `composedOf: true` side generates the composition edge: cascade deletes, the scene hierarchy, and the reachability check. Because these can be different entities — a parent may collect children by reverse lookup (`indirect` + `composedOf: true`) while each child stores the id — dropping either declaration silently disables one of the systems: without the parent side, deleting the parent leaves its children orphaned; without the child side, deleted entities leave dangling ids behind. The missing side also cannot be generated automatically, because the stored id field is compatible with many different relations: the reverse accessor's name is public API, and its cardinality (`0-N`, `1-N`, or a `0-1` slot) changes the generated types, state validation, and UI affordances without changing the stored data at all. Requiring both declarations turns these mistakes into parse errors instead of runtime surprises, and the redundancy lets the parser cross‑check the pair — a typo in `field` or a doubled owner is caught immediately.
 
 ### Picking a relation kind

package/dist/docs/phoenix/expression-context.mdx

@@ -35,15 +35,23 @@ interface ExpressionContext<
 
   // System services
   readonly domain: Domain // Access to domain model and other entities
-  readonly componentReader: ComponentReader // Read component states across all entities
   readonly migrate: MigrateFunction // Data migration utilities
-  readonly sketchingProjections: SketchingProjections // Sketching system projections
-  readonly collisionProjections: CollisionProjections // Collision detection projections
+  readonly componentReader: ComponentReader // Read component states across all entities
+
+  // Projections
+  readonly positionProjections: PositionProjections // World matrices of scene entities
+  readonly sketchingProjections: SketchingProjections // Shapes and connections of a sketch
+  readonly collisionProjections: CollisionProjections // Collision meshes and collisions between entities
+  readonly constraintProjections: ConstraintProjections // Spatial constraints an entity violates
+  readonly snappingProjections: SnappingProjections // Snap points, edges, planes and matches
+  readonly projectedEntitiesProjections: ProjectedEntitiesProjections // Data of projected entities
 }
 ```
 
 The context includes data sources (session, published, frontend, backend), system services (domain access, component reader, projections), and application state (mode, role). Each part serves a different purpose in expression calculations.
 
+The SDK declares the context in two parts. `CoreExpressionContext` holds the mode, the role, the data sources, `domain` and `migrate`. `RuntimeExpressionContext` holds the component reader and the projections. An editor hover or a type error therefore shows `ctx` as `OpenExpressionContext<..., RuntimeExpressionContext<AnyDomainEntity>>`, which has the members listed above. A helper of your own that takes the context declares its parameter as `ExpressionContext` with the five types of your project.
+
 ### Configurator Modes
 
 The `mode` property indicates the current operational context of the configurator. Different modes enable different functionality and access levels. Expressions can check the mode to change their behavior.

package/dist/docs/phoenix/finalization.mdx

@@ -355,4 +355,4 @@ Now that you understand finalization workflows, explore these related topics:
 - **[Admin](?path=/docs/phoenix-admin--docs)** - Learn about admin finalization and published data generation
 - **[Best Practices](?path=/docs/phoenix-best-practices--docs)** - Follow proven patterns for finalization implementation
 
-For hands-on practice, explore the finalize demo in the **[Quickstart](?path=/docs/phoenix-quickstart--docs)** guide.
+For hands-on practice, explore the Precision demo (`packages/demos/demo-precision/`) for finalization resources — PDF, CSV, images, email attachments and callbacks — and the Catalog Builder demo (`packages/demos/demo-catalog-builder/`) for the finalization data lifecycle and access links.

package/dist/docs/phoenix/getting-started.mdx

@@ -86,7 +86,7 @@ For inspiration and real-world implementation patterns, examine deployed Salsita
 
 When you encounter challenges or need to implement specific features, use these resources in order:
 
-**AI-Powered Assistance**: Every Phoenix project ships `AGENTS.md` and Phoenix agent skills, so coding agents in your project already know the SDK conventions and CLI. Start by using AI coding assistants in the `configurator-phoenix` project. While they may not solve complex problems directly, they can point you toward relevant examples or search terms that will help you find the right solution.
+**AI-Powered Assistance**: Every Phoenix project ships Phoenix agent skills, so coding agents in your project already know the SDK conventions and CLI. Start by using AI coding assistants in the `configurator-phoenix` project. While they may not solve complex problems directly, they can point you toward relevant examples or search terms that will help you find the right solution.
 
 **Storybook Documentation**: Search the Phoenix Storybook for functionality similar to what you need. When you find relevant examples, examine the corresponding code in the configurator-phoenix stories to understand the implementation details.
 

package/dist/docs/phoenix/integration/headless-mode-external.mdx

@@ -51,11 +51,11 @@ For details on the server-side token exchange, see [Authentication](?path=/docs/
 
 The `power` attribute controls the configurator's state:
 
-| Value       | Behavior                                                                                                                                                 |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `"off"`     | Completely inactive. No rendering, no session, no network requests beyond loading the bundle.                                                            |
-| `"standby"` | Session initialized, assets preloaded (3D models, textures), but not rendered. Faster power-on, but consumes bandwidth and counts toward session quotas. |
-| `"on"`      | Fully active and visible.                                                                                                                                |
+| Value       | Behavior                                                                                                                                                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `"off"`     | Completely inactive. No rendering, no session, no network requests beyond loading the bundle.                                                                                                                            |
+| `"standby"` | Session initialized and any textures listed in `resourcesConfig.prefetchTextureUrls` prefetched; nothing is rendered and no models are loaded. Faster power-on, but consumes bandwidth and counts toward session quotas. |
+| `"on"`      | Fully active and visible.                                                                                                                                                                                                |
 
 A typical flow: power on at login (`"standby"`), then toggle between `"on"` and `"standby"` as the user opens and closes the configurator. Use `"off"` only before the user has authenticated.
 

package/dist/docs/phoenix/integration/widget-mode-external.mdx

@@ -28,11 +28,11 @@ The configurator fills its parent container. Set a height on the element or a wr
 
 The `power` attribute controls whether the configurator is active. It accepts three values:
 
-| Value       | Behavior                                                                                                                                                                                             |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `"off"`     | Configurator is completely inactive. No rendering, no session initialization, no network requests beyond loading the bundle. Lowest resource usage.                                                  |
-| `"standby"` | Configurator initializes its session and preloads assets (3D models, textures), but does not render. Subsequent power-on is faster, but consumes bandwidth and counts toward monthly session quotas. |
-| `"on"`      | Configurator is fully active and visible.                                                                                                                                                            |
+| Value       | Behavior                                                                                                                                                                                                                                              |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"off"`     | Configurator is completely inactive. No rendering, no session initialization, no network requests beyond loading the bundle. Lowest resource usage.                                                                                                   |
+| `"standby"` | Configurator initializes its session and prefetches any textures listed in `resourcesConfig.prefetchTextureUrls`, but does not render or load models. Subsequent power-on is faster, but consumes bandwidth and counts toward monthly session quotas. |
+| `"on"`      | Configurator is fully active and visible.                                                                                                                                                                                                             |
 
 ### Choosing the Initial Power