@salsita-ai/sdk 0.0.0-stage → 0.49.0-develop.cbee856178

package/dist/docs/3d-scene/rendering/basic.mdx

@@ -0,0 +1,925 @@
+# Rendering - Basic 3D Objects
+
+- [Use case](#use-case)
+- [Guide](#guide)
+- [Example](#example)
+- [Test cases](#test-cases)
+- [Complete Implementation](#complete-implementation)
+
+## Use case
+
+These rendering components form the foundation for displaying 3D content in any configurator. Whether you're building furniture configurators, product customizers, or other applications that visualize domain entities in 3D space, you'll use these components to make your entities visible in the scene.
+
+Most configurators load 3D models from GLTF/GLB files using `sceneEntityRemoteObject`, then position and transform them with `sceneEntityObjectProperties` for individual objects and `sceneEntityProperties` for entire entity groups. For advanced cases where you need simple geometry or procedural shapes, `sceneEntityCustomObjectComponent` lets you create THREE.js objects directly in code.
+
+## Guide
+
+This guide shows how to build a complete 3D entity using rendering components. We'll start with loading models from files (the most common approach), then cover positioning and transforms, and finally show how to create custom THREE.js objects for advanced use cases.
+
+### Loading Models from Files
+
+For most configurators, you'll load 3D models created in software like Blender. Use `sceneEntityRemoteObject` to load GLTF or GLB files:
+
+```yaml
+components:
+  Boxes:
+    sceneEntityRemoteObject:
+      cube1:
+        fileUrl: '/models/cube.gltf'
+        objectName: 'Cube'
+        dimensionUnit: 'm'
+      cube2:
+        fileUrl: '/models/cube.gltf'
+        objectName: 'Cube'
+        dimensionUnit: 'm'
+```
+
+The `fileUrl` points to the model file (relative to your public directory), `objectName` specifies which object within the GLTF file to extract (GLTF files can contain multiple objects), and `dimensionUnit` indicates the unit system the model was created in.
+
+This is the preferred way to add 3D content since artists can create detailed models in 3D software, and you simply load them in the configurator.
+
+### Positioning Objects
+
+After loading objects (whether from files or custom), use `sceneEntityObjectProperties` in YAML to position each instance. This component sets transforms (position, rotation, scale) for individual object instances within an entity.
+
+Each object instance is identified by its instance name (the key used when defining the object). You can set static values or bind to dynamic properties using `$read`. These transforms apply directly to the individual THREE.js object, not the entity's group wrapper.
+
+Position values use your application's base data unit (typically millimeters). See the [Dimensions](?path=/docs/phoenix-dimensions--docs) documentation for details on unit configuration. Rotation values are specified in radians (2π radians = 360 degrees):
+
+```yaml
+components:
+  Boxes:
+    sceneEntityObjectProperties:
+      cube1: # Instance name targeting this specific object
+        offsetX: -2000 # -2000mm in base unit
+        offsetY: 0
+        offsetZ: -2000
+        rotationX: 0.7853981633974483 # π/4 radians = 45 degrees
+        rotationY: 0.7853981633974483
+        rotationZ: 0.7853981633974483
+```
+
+Available transform properties include `offsetX`/`offsetY`/`offsetZ` for position (in base data unit), `rotationX`/`rotationY`/`rotationZ` for rotation (in radians), and `scaleX`/`scaleY`/`scaleZ` for scale.
+
+Remote objects can use additional features like morph target influences. Morph targets (called "shape keys" in Blender) are predefined deformations in the 3D model that you can animate by setting influence values from 0 to 1:
+
+```yaml
+components:
+  Boxes:
+    sceneEntityObjectProperties:
+      cube1: # Targets the cube1 object instance
+        offsetX: -2000
+        offsetZ: -2000
+        rotationX: 0.7853981633974483
+        morphTargetInfluences:
+          Width: # Name of the morph target from the 3D model
+            value:
+              $read: $box1OpenedScaled
+            scaleZero: 0 # When value=0, morph influence is 0 (closed)
+            scaleOne: 2 # When value=2, morph influence is 1 (fully open)
+```
+
+### Entity-Level Transforms
+
+While `sceneEntityObjectProperties` positions individual object instances, `sceneEntityProperties` applies transforms to the entire entity as a unit. These transforms are applied to the THREE.js Group that wraps all objects belonging to the entity, moving or rotating everything together.
+
+All position values use your application's base data unit (typically millimeters), and rotation values are in radians:
+
+```yaml
+components:
+  Train:
+    sceneEntityProperties:
+      main:
+        offsetX:
+          $read: offsetX
+        offsetY:
+          $read: offsetY
+        offsetZ:
+          $read: offsetZ
+        rotationX:
+          $read: trainRotation # Rotation in radians
+```
+
+Entity-level transforms compose with object-level transforms. If the Train entity's Group has `offsetX: 1000` and the cabin object has `offsetX: 1500`, the cabin appears at world position 2500. This two-level system lets you position individual parts relative to each other using `sceneEntityObjectProperties`, then move the entire assembly as one unit using `sceneEntityProperties`.
+
+The `main` instance name is a convention for the primary transform instance of an entity.
+
+### Creating Custom THREE.js Objects
+
+For advanced use cases where you need procedural geometry or simple shapes that don't require external model files, create custom objects programmatically using THREE.js in your frontend code.
+
+Define helper functions that create and return THREE.js objects. Use `memoEval` to wrap these functions for performance - it memoizes the object creation so THREE.js meshes are only instantiated once:
+
+```typescript
+import * as THREE from 'three'
+
+import { memoEval, sceneEntityCustomObjectComponent } from '@salsita-ai/sdk/domain'
+
+import { attachComponent, defineFrontend } from '../domain/index.js'
+
+const createCabinObject = () => {
+  const geometry = new THREE.BoxGeometry(2, 2.25, 1.5)
+  const material = new THREE.MeshStandardMaterial({ color: 'firebrick' })
+  const mesh = new THREE.Mesh(geometry, material)
+
+  mesh.scale.setScalar(1000)
+
+  return { object: mesh }
+}
+
+export default defineFrontend({
+  components: [
+    attachComponent
+      .withComponent(sceneEntityCustomObjectComponent, 'cabin')
+      .withEntity('Train')
+      .attach(memoEval(() => [], createCabinObject)),
+  ],
+})
+```
+
+The first argument to `memoEval` specifies dependencies - an empty array means the object is created once and reused. The helper function returns an object with an `object` property containing the THREE.js mesh.
+
+Custom objects can be positioned using `sceneEntityObjectProperties` just like remote objects. The Train entity in this example uses seven custom objects (cabin, nose, chimney, and four wheels) positioned with dynamic bindings:
+
+```yaml
+components:
+  Train:
+    sceneEntityObjectProperties:
+      cabin:
+        offsetX: 1500
+        offsetY: 1400
+        offsetZ: 0
+      Wheel1:
+        offsetX: -2000
+        offsetY: 500
+        rotationX: 1.5707963267948966
+        rotationY:
+          $read: wheelRotation
+```
+
+Using `$read` lets you bind transforms to entity state - in this example, all four wheels share the same `wheelRotation` property so they rotate together.
+
+### Working Together
+
+The complete rendering pattern:
+
+1. Load models using `sceneEntityRemoteObject` in YAML for artist-created assets (preferred approach)
+2. Position each object instance using `sceneEntityObjectProperties` in YAML, setting static positions and binding dynamic transforms to entity state
+3. Apply entity-level transforms with `sceneEntityProperties` to move or rotate the entire entity as a unit
+4. For advanced cases, create custom objects with `sceneEntityCustomObjectComponent` in frontend code when you need procedural geometry
+
+The Boxes entity demonstrates the standard pattern: remote objects loaded from GLTF files, positioned and animated through `sceneEntityObjectProperties`. The Train entity shows the advanced pattern with custom THREE.js objects.
+
+## Example
+
+## Test cases
+
+Verify these behaviors when implementing rendering components:
+
+- Custom THREE.js objects render in the 3D scene with correct geometry and materials
+- Entity-level transforms move or rotate the entire entity as a single unit
+- Object-level transforms position individual parts correctly relative to the entity origin
+- Remote objects load GLTF/GLB models and display them in the scene
+- Dynamic property bindings update in real-time (like synchronized wheel rotation)
+- Scale transforms affect object sizes appropriately in all three dimensions
+- Morph target influences animate remote objects when configured (demonstrated by the opening boxes)
+
+## TypeScript Interfaces
+
+The rendering components are built on strongly-typed interfaces that ensure type safety:
+
+### SceneEntityRemoteObjectComponentState
+
+```typescript
+/**
+ * Configuration for loading 3D models from GLTF/GLB files.
+ */
+export type SceneEntityRemoteObjectComponentState = {
+  /**
+   * Path to the GLTF file that includes the loaded object.
+   * Relative to your public directory.
+   * @example '/models/cube.gltf'
+   */
+  readonly fileUrl: string
+
+  /**
+   * Name of the object to be loaded from the GLTF file.
+   * GLTF files can contain multiple objects - this specifies which one to extract.
+   * @example 'Cube' | 'ChairSeat' | 'WheelAssembly'
+   */
+  readonly objectName: string
+
+  /**
+   * Object dimensions used in the GLTF file.
+   * If not provided, the application's distanceDataUnit will be used.
+   * @example 'm' | 'mm' | 'inch'
+   */
+  readonly dimensionUnit?: DimensionUnit
+}
+```
+
+### SceneEntityObjectPropertiesComponentState
+
+```typescript
+/**
+ * Transform properties and visual settings for individual object instances.
+ * Applies to both remote objects and custom objects.
+ *
+ * These transforms are applied directly to the specific THREE.js object identified by the instance name,
+ * not to the entity's Group wrapper. They position objects relative to the entity's coordinate system.
+ */
+export type SceneEntityObjectPropertiesComponentState = {
+  /**
+   * Controls object visibility in the scene.
+   */
+  readonly visible?: boolean
+
+  /**
+   * Offset along x axis in mm.
+   */
+  readonly offsetX?: number
+
+  /**
+   * Offset along y axis in mm.
+   */
+  readonly offsetY?: number
+
+  /**
+   * Offset along z axis in mm.
+   */
+  readonly offsetZ?: number
+
+  /**
+   * Rotation along x axis in radians.
+   * @example Math.PI / 4 for 45 degrees, Math.PI / 2 for 90 degrees
+   */
+  readonly rotationX?: number
+
+  /**
+   * Rotation along y axis in radians.
+   */
+  readonly rotationY?: number
+
+  /**
+   * Rotation along z axis in radians.
+   */
+  readonly rotationZ?: number
+
+  /**
+   * Scale along the x axis.
+   * @example 2 for double size, 0.5 for half size
+   */
+  readonly scaleX?: number
+
+  /**
+   * Scale along the y axis.
+   */
+  readonly scaleY?: number
+
+  /**
+   * Scale along the z axis.
+   */
+  readonly scaleZ?: number
+
+  /**
+   * Morph target influences to be applied to the object or any of its descendants.
+   * Each key is the name of the morph target, and the value is the influence to be applied to it.
+   * If the object (or its descendants) has a corresponding morph target, the influence will be applied to it.
+   *
+   * Morph targets are predefined deformations in 3D models (called "shape keys" in Blender).
+   * They allow you to animate between different shapes by setting influence values from 0 to 1.
+   *
+   * @example { Width: { value: 0.5, scaleZero: 0, scaleOne: 1 } }
+   */
+  readonly morphTargetInfluences?: Record<string, MorphTargetInfluence>
+
+  /**
+   * When true (the default), the object will only be rendered when it is inside the camera's frustum.
+   * Set to false for objects whose size changes significantly through morphing or objects always visible.
+   */
+  readonly frustumCulled?: boolean
+
+  /**
+   * When set to false, the object will be skipped from rendering by removing it from layer 0.
+   * Different from visible:false because the object can still be used for camera fitting and highlighting.
+   * @default true
+   */
+  readonly rendered?: boolean
+
+  /**
+   * When set to false, the object will be skipped from mouse interactions by removing it from layer 1.
+   * Primary use-cases are performance optimization and replacing objects with invisible bounding boxes.
+   * @default true
+   */
+  readonly interactive?: boolean
+
+  /**
+   * Whether the object casts shadows.
+   * @default false
+   */
+  readonly castShadow?: boolean
+
+  /**
+   * Whether the object receives shadows.
+   * @default false
+   */
+  readonly receiveShadow?: boolean
+
+  /**
+   * When set to `true`, selection highlighting is disabled for this object.
+   * The object remains selectable but no visual highlight effect is applied.
+   * The object also won't be faded when other objects are selected.
+   * @default false
+   */
+  readonly highlightingDisabled?: boolean
+}
+
+/**
+ * Defines a morph target influence for animating 3D models.
+ * Morph targets (shape keys in Blender) are predefined deformations that can be animated.
+ */
+export interface MorphTargetInfluence {
+  /**
+   * Source value in an arbitrary scale.
+   * This is typically bound to a domain property.
+   */
+  readonly value: number
+
+  /**
+   * Value of `value` that corresponds to the 0 influence (closed/minimum state).
+   * When value equals scaleZero, the morph target has 0 influence.
+   */
+  readonly scaleZero: number
+
+  /**
+   * Value of `value` that corresponds to the 1 influence (open/maximum state).
+   * When value equals scaleOne, the morph target has full (1.0) influence.
+   */
+  readonly scaleOne: number
+}
+```
+
+### SceneEntityPropertiesComponentState
+
+```typescript
+/**
+ * Transform properties that apply to the entire entity as a unit.
+ * These compose with object-level transforms.
+ *
+ * These transforms are applied to the THREE.js Group that wraps all objects of the entity.
+ * When you move or rotate the entity, all its objects move together as a single assembly.
+ *
+ * Position values use the application's base data unit (typically millimeters).
+ * See Dimensions documentation for unit configuration details.
+ *
+ * Rotation values are in radians (2π radians = 360 degrees).
+ */
+export type SceneEntityPropertiesComponentState = {
+  /**
+   * Offset along x axis in the application's base data unit (typically mm).
+   */
+  readonly offsetX?: number
+
+  /**
+   * Offset along y axis in the application's base data unit (typically mm).
+   */
+  readonly offsetY?: number
+
+  /**
+   * Offset along z axis in the application's base data unit (typically mm).
+   */
+  readonly offsetZ?: number
+
+  /**
+   * Rotation along x axis in radians.
+   * @example Math.PI / 4 for 45 degrees, Math.PI for 180 degrees
+   */
+  readonly rotationX?: number
+
+  /**
+   * Rotation along y axis in radians.
+   */
+  readonly rotationY?: number
+
+  /**
+   * Rotation along z axis in radians.
+   */
+  readonly rotationZ?: number
+
+  /**
+   * Scale along the x axis.
+   */
+  readonly scaleX?: number
+
+  /**
+   * Scale along the y axis.
+   */
+  readonly scaleY?: number
+
+  /**
+   * Scale along the z axis.
+   */
+  readonly scaleZ?: number
+}
+```
+
+### SceneEntityObjectComponentState
+
+```typescript
+/**
+ * Configuration for custom THREE.js objects created programmatically.
+ * Used with sceneEntityCustomObjectComponent in frontend code.
+ */
+export type SceneEntityObjectComponentState = {
+  /**
+   * THREE.js Object3D instance to be rendered in the scene.
+   * Can be any THREE.js object: Mesh, Group, Line, Points, etc.
+   */
+  readonly object: Object3D
+}
+```
+
+## Complete Implementation
+
+{/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}
+
+<details>
+<summary>Click to view the complete implementation files</summary>
+
+### ./spec/domain.yaml
+
+```yaml
+model:
+  latest:
+    entityTypes:
+      - Scene
+      - Train
+      - Boxes
+    aliases:
+      RootEntity:
+        - Scene
+      Shape:
+        - Train
+        - Boxes
+    shapes:
+      Scene:
+        offsetX:
+          type: number
+
+          maximum: 10000
+        rotationX:
+          type: number
+
+      Train:
+        offsetX:
+          type: number
+
+        offsetY:
+          type: number
+
+        offsetZ:
+          type: number
+
+        wheelRotation:
+          type: number
+
+        trainRotation:
+          type: number
+
+      Boxes:
+        box1Opened:
+          type: number
+        box2Opened:
+          type: number
+        box3Opened:
+          type: number
+        box4Opened:
+          type: number
+
+relations:
+  Scene:
+    $shapes:
+      kind: allOfType
+      target: Shape
+      cardinality: 0-N
+      composedOf: true
+  Shape:
+    $scene:
+      kind: allOfType
+      target: Scene
+      cardinality: 1-1
+      composedOf: false
+
+presets:
+  - rootEntityType: 'Scene'
+    initialDomainEntities:
+      - id: 'Scene-1'
+        type: 'Scene'
+        offsetX: 0
+        rotationX: 0
+      - id: 'Train-1'
+        type: 'Train'
+        offsetX: 0
+        offsetY: 0
+        offsetZ: 0
+        wheelRotation: 0
+        trainRotation: 0
+      - id: 'Boxes-1'
+        type: 'Boxes'
+        box1Opened: 0.2
+        box2Opened: 0.9
+        box3Opened: 1.5
+        box4Opened: 2
+
+components:
+  Scene:
+    applicationConfig:
+      default:
+        layout: 'universal'
+        miniSidebar: true
+        splitSidebar: true
+    sceneEntityProperties:
+      main:
+        offsetX:
+          $read: offsetX
+        rotationX:
+          $read: rotationX
+    distanceDimension:
+      offsetX:
+        min: -10000
+        max: 10000
+        value:
+          $bind: offsetX
+    angleDimension:
+      rotationX:
+        min: -1.5707963267948966
+        max: 1.5707963267948966
+        value:
+          $bind: rotationX
+        decimalPlaces: 1
+  Boxes:
+    sceneEntityRemoteObject:
+      cube1:
+        fileUrl: '/models/cube.gltf'
+        objectName: 'Cube'
+        dimensionUnit: 'm'
+      cube2:
+        fileUrl: '/models/cube.gltf'
+        objectName: 'Cube'
+        dimensionUnit: 'm'
+      cube3:
+        fileUrl: '/models/cube.gltf'
+        objectName: 'Cube'
+        dimensionUnit: 'm'
+      cube4:
+        fileUrl: '/models/cube.gltf'
+        objectName: 'Cube'
+        dimensionUnit: 'm'
+    sceneEntityObjectProperties:
+      cube1:
+        offsetX: -2000
+        offsetY: 0
+        offsetZ: -2000
+        rotationX: 0.7853981633974483
+        rotationY: 0.7853981633974483
+        rotationZ: 0.7853981633974483
+        morphTargetInfluences:
+          Width:
+            value:
+              $read: $box1OpenedScaled
+            scaleZero: 0
+            scaleOne: 2
+      cube2:
+        offsetX: 2000
+        offsetY: 0
+        offsetZ: 2000
+        rotationX: -0.7853981633974483
+        rotationY: -0.7853981633974483
+        rotationZ: -0.7853981633974483
+        morphTargetInfluences:
+          Width:
+            value:
+              $read: $box2OpenedScaled
+            scaleZero: 0
+            scaleOne: 2
+      cube3:
+        offsetX: -2000
+        offsetY: 0
+        offsetZ: 2000
+        rotationX: -0.7853981633974483
+        rotationY: -0.7853981633974483
+        rotationZ: -0.7853981633974483
+        morphTargetInfluences:
+          Width:
+            value:
+              $read: $box3OpenedScaled
+            scaleZero: 0
+            scaleOne: 2
+      cube4:
+        offsetX: 2000
+        offsetY: 0
+        offsetZ: -2000
+        morphTargetInfluences:
+          Width:
+            value:
+              $read: $box4OpenedScaled
+            scaleZero: 0
+            scaleOne: 2
+    sceneEntityProperties:
+      main:
+        offsetX: -9000
+    genericDimension:
+      box1Opened:
+        min: 0
+        max: 100
+        unit: '%'
+        value:
+          $bind: box1Opened
+      box2Opened:
+        min: 0
+        max: 200
+        unit: '%'
+        value:
+          $bind: box2Opened
+      box3Opened:
+        min: -100
+        max: 200
+        unit: '%'
+        value:
+          $bind: box3Opened
+      box4Opened:
+        min: 0
+        max: 400
+        unit: '%'
+        value:
+          $bind: box4Opened
+    detail:
+      main:
+        title: 'Bunch of Boxes!'
+        subtitle: 'It is here so you can see it!'
+        description: 'Beautiful Boxes that are loaded from file with some morphing!'
+    selectable:
+      main: {}
+  Train:
+    sceneEntityProperties:
+      main:
+        offsetX:
+          $read: offsetX
+        offsetY:
+          $read: offsetY
+        offsetZ:
+          $read: offsetZ
+        rotationX:
+          $read: trainRotation
+    sceneEntityObjectProperties:
+      cabin:
+        offsetX: 1500
+        offsetY: 1400
+        offsetZ: 0
+      Nose:
+        offsetX: -1000
+        offsetY: 1000
+        offsetZ: 0
+        rotationZ: 1.5707963267948966
+      Chimney:
+        offsetX: -2000
+        offsetY: 1900
+      Wheel1:
+        offsetX: -2000
+        offsetY: 500
+        rotationX: 1.5707963267948966
+        rotationY:
+          $read: wheelRotation
+      Wheel2:
+        offsetX: -1000
+        offsetY: 500
+        rotationX: 1.5707963267948966
+        rotationY:
+          $read: wheelRotation
+      Wheel3:
+        offsetX: 0
+        offsetY: 500
+        rotationX: 1.5707963267948966
+        rotationY:
+          $read: wheelRotation
+      Wheel4:
+        offsetX: 1500
+        offsetY: 900
+        scaleX: 2
+        scaleY: 1.25
+        scaleZ: 2
+        rotationX: 1.5707963267948966
+        rotationY:
+          $read: wheelRotation
+    distanceDimension:
+      offsetX:
+        min: -10000
+        max: 10000
+        value:
+          $bind: offsetX
+      offsetY:
+        min: -10000
+        max: 10000
+        value:
+          $bind: offsetY
+      offsetZ:
+        min: -10000
+        max: 10000
+        value:
+          $bind: offsetZ
+    angleDimension:
+      wheelRotation:
+        min: -1.5707963267948966
+        max: 1.5707963267948966
+        value:
+          $bind: wheelRotation
+        decimalPlaces: 1
+      rotationX:
+        min: -1.5707963267948966
+        max: 1.5707963267948966
+        value:
+          $bind: trainRotation
+        decimalPlaces: 1
+    detail:
+      main:
+        title: 'Train Truck!'
+        subtitle: 'It is here so you can see it!'
+        description: 'Beautiful custom Train to showcase rendering.'
+    selectable:
+      main: {}
+```
+
+### ./src/components/components.tsx
+
+```tsx
+import * as THREE from 'three'
+
+import { memoEval, propertyPageComponent, sceneEntityObjectComponent } from '@salsita-ai/sdk/domain'
+import { AngleDimensionSlider, DistanceDimensionSlider, GenericDimensionSlider } from '@salsita-ai/sdk/react'
+import { PropertyContainer } from '@salsita-ai/sdk/ui'
+
+import { phx } from '../../.phoenix/phx.js'
+
+const createCabinObject = () => {
+  const geometry = new THREE.BoxGeometry(2, 2.25, 1.5)
+  const material = new THREE.MeshStandardMaterial({ color: 'firebrick' })
+  const mesh = new THREE.Mesh(geometry, material)
+
+  mesh.scale.setScalar(1000)
+
+  return {
+    object: mesh,
+  }
+}
+
+const createNoseObject = () => {
+  const geometry = new THREE.CylinderGeometry(0.75, 0.75, 3, 12)
+  const material = new THREE.MeshStandardMaterial({ color: 'firebrick' })
+  const mesh = new THREE.Mesh(geometry, material)
+
+  mesh.scale.setScalar(1000)
+
+  return {
+    object: mesh,
+  }
+}
+
+const createChimneyObject = () => {
+  const geometry = new THREE.CylinderGeometry(0.3, 0.1, 0.5)
+  const material = new THREE.MeshStandardMaterial({ color: 'darkslategray' })
+  const mesh = new THREE.Mesh(geometry, material)
+
+  mesh.scale.setScalar(1000)
+
+  return {
+    object: mesh,
+  }
+}
+
+const createWheelObject = () => {
+  const geometry = new THREE.CylinderGeometry(0.4, 0.4, 1.75, 8)
+  const material = new THREE.MeshStandardMaterial({ color: 'darkslategray' })
+  const mesh = new THREE.Mesh(geometry, material)
+
+  mesh.scale.setScalar(1000)
+
+  return {
+    object: mesh,
+  }
+}
+
+export default [
+  // Scene property page
+  phx.domain.attachComponent
+    .withComponent(propertyPageComponent, 'main')
+    .withEntity('Scene')
+    .attach(s => ({
+      page: (
+        <div>
+          <PropertyContainer.Item title="Dimension X">
+            <DistanceDimensionSlider entityId={s.id} instanceName="offsetX" />
+          </PropertyContainer.Item>
+          <PropertyContainer.Item title="Rotation X">
+            <AngleDimensionSlider entityId={s.id} instanceName="rotationX" />
+          </PropertyContainer.Item>
+        </div>
+      ),
+    })),
+
+  // Boxes property page
+  phx.domain.attachComponent
+    .withComponent(propertyPageComponent, 'box')
+    .withEntity('Boxes')
+    .attach(s => ({
+      page: (
+        <div>
+          <PropertyContainer.Item title="Box 1 opened">
+            <GenericDimensionSlider entityId={s.id} instanceName="box1Opened" />
+          </PropertyContainer.Item>
+          <PropertyContainer.Item title="Box 2 opened">
+            <GenericDimensionSlider entityId={s.id} instanceName="box2Opened" />
+          </PropertyContainer.Item>
+          <PropertyContainer.Item title="Box 3 opened">
+            <GenericDimensionSlider entityId={s.id} instanceName="box3Opened" />
+          </PropertyContainer.Item>
+          <PropertyContainer.Item title="Box 4 opened">
+            <GenericDimensionSlider entityId={s.id} instanceName="box4Opened" />
+          </PropertyContainer.Item>
+        </div>
+      ),
+    })),
+
+  // Train custom THREE.js objects
+  phx.domain.attachComponent
+    .withComponent(sceneEntityObjectComponent, 'cabin')
+    .withEntity('Train')
+    .attach(memoEval(() => [], createCabinObject)),
+  phx.domain.attachComponent
+    .withComponent(sceneEntityObjectComponent, 'Nose')
+    .withEntity('Train')
+    .attach(memoEval(() => [], createNoseObject)),
+  phx.domain.attachComponent
+    .withComponent(sceneEntityObjectComponent, 'Chimney')
+    .withEntity('Train')
+    .attach(memoEval(() => [], createChimneyObject)),
+  phx.domain.attachComponent
+    .withComponent(sceneEntityObjectComponent, 'Wheel1')
+    .withEntity('Train')
+    .attach(memoEval(() => [], createWheelObject)),
+  phx.domain.attachComponent
+    .withComponent(sceneEntityObjectComponent, 'Wheel2')
+    .withEntity('Train')
+    .attach(memoEval(() => [], createWheelObject)),
+  phx.domain.attachComponent
+    .withComponent(sceneEntityObjectComponent, 'Wheel3')
+    .withEntity('Train')
+    .attach(memoEval(() => [], createWheelObject)),
+  phx.domain.attachComponent
+    .withComponent(sceneEntityObjectComponent, 'Wheel4')
+    .withEntity('Train')
+    .attach(memoEval(() => [], createWheelObject)),
+
+  // Train property page
+  phx.domain.attachComponent
+    .withComponent(propertyPageComponent, 'train')
+    .withEntity('Train')
+    .attach(s => ({
+      page: (
+        <div>
+          <PropertyContainer.Item title="Offset X">
+            <DistanceDimensionSlider entityId={s.id} instanceName="offsetX" />
+          </PropertyContainer.Item>
+          <PropertyContainer.Item title="Offset Y">
+            <DistanceDimensionSlider entityId={s.id} instanceName="offsetY" />
+          </PropertyContainer.Item>
+          <PropertyContainer.Item title="Offset Z">
+            <DistanceDimensionSlider entityId={s.id} instanceName="offsetZ" />
+          </PropertyContainer.Item>
+          <PropertyContainer.Item title="Wheel Rotation">
+            <AngleDimensionSlider entityId={s.id} instanceName="wheelRotation" />
+          </PropertyContainer.Item>
+          <PropertyContainer.Item title="Train Rotation">
+            <AngleDimensionSlider entityId={s.id} instanceName="rotationX" />
+          </PropertyContainer.Item>
+        </div>
+      ),
+    })),
+]
+```
+
+### ./src/expressions/boxes.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomExpressions({
+  Boxes: {
+    $box1OpenedScaled: s => s.box1Opened / 100,
+    $box2OpenedScaled: s => s.box2Opened / 100,
+    $box3OpenedScaled: s => s.box3Opened / 100,
+    $box4OpenedScaled: s => s.box4Opened / 100,
+  },
+})
+```
+
+</details>