@vgai/engine 0.2.0 → 0.3.0

package/src/animation/theatre-object-binding.ts

@@ -0,0 +1,661 @@
+import type { ISheetObject, UnknownShorthandCompoundProps } from '@theatre/core';
+// Type-only import — matches `world2d/types.ts`'s own rule (the engine core
+// never VALUE-imports `pixi.js`; a caller supplies the constructed
+// Container/Sprite, this module only types against it).
+import type { Container } from 'pixi.js';
+// Type-only import of the SAME `postprocessing` package the engine's own
+// composer pipeline uses directly (`setup-renderer.ts`) — no wrapper.
+import type { BloomEffect, VignetteEffect } from 'postprocessing';
+import type * as THREE from 'three';
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock, ClockEvaluatorHandle } from './animation-clock';
+
+/**
+ * D3 — stable binding from a Theatre Sheet Object to a `THREE.Object3D`/
+ * camera (spec §10 D3, §5.3). This is the "thin integration code" the spec
+ * calls for: it reads a Theatre object's pull-based `.value` on every clock
+ * crossing and writes the (small, fixed) set of known sub-props straight
+ * onto the target's real Three.js properties. It is deliberately NOT a
+ * generic/arbitrary property-path evaluator — the only shapes understood are
+ * the ones declared below (`TransformProps`, `CameraLensProps`), matching
+ * "No arbitrary unsafe property-path evaluator is introduced" (D3 AC).
+ *
+ * Reads `sheetObject.value` rather than subscribing to Theatre's
+ * `onValuesChange` push channel — see `theatre-clock-binding.ts`'s module doc
+ * for why: `.value` is synchronously fresh immediately after
+ * `sequence.position` is set, while `onValuesChange` is batched on Theatre's
+ * own raf-driven ticker and is not delivered 1:1 with each synchronous clock
+ * seek (it may coalesce several writes into one notification, or — headless,
+ * no-raf — never fire at all).
+ *
+ * Object identity: a Theatre Sheet Object always carries both its stable,
+ * readable Theatre name (`sheetObject.address.objectKey`) and, since the
+ * caller supplies the bound `THREE.Object3D` directly, that object's own
+ * engine identity (`Object3D.uuid`/`.name`/`userData['entityId']`) — both are
+ * inspectable from the object references the binding already holds; nothing
+ * further to thread through.
+ *
+ * ## Remaining D3 channels: quaternion/material/light/post-processing/UI/Pixi
+ *
+ * The rest of the D3 AC's channel list (spec §10 D3: "Position,
+ * rotation/quaternion, scale, camera lens, material/light, post-processing,
+ * and selected UI properties have tested bindings") is implemented below,
+ * each as its own small, explicit, TYPED helper — never a generic
+ * property-path evaluator:
+ *
+ *  - `bindObject3DQuaternion` — `Object3D.quaternion`, authored as a plain
+ *    `{x,y,z,w}` compound (see `QuaternionProps`'s doc for the interpolation
+ *    caveat and why the binding always normalizes).
+ *  - `bindMaterialProperties` — `color`/`opacity`/`emissiveIntensity`/
+ *    `roughness`/`metalness` on a real `THREE.Material`, feature-detecting
+ *    which sub-props the concrete material subtype actually has.
+ *  - `bindLightProperties` — `intensity`/`color` on a real `THREE.Light`.
+ *  - `bindBloomEffect` / `bindVignetteEffect` — `intensity`/`opacity` and
+ *    `offset`/`darkness` on real `postprocessing` `BloomEffect`/
+ *    `VignetteEffect` instances (the SAME package `setup-renderer.ts` already
+ *    wires into the engine's composer — no new post-processing stack).
+ *  - `bindDomElementStyle` — `opacity`/`translateX`/`translateY` on a
+ *    DOM-style-writable target (`DomStyleTarget`, a narrow structural
+ *    interface a real `HTMLElement` satisfies with no adapter).
+ *  - `bindPixiContainerTransform` — `x`/`y`/`rotation`/`scaleX`/`scaleY`/
+ *    `alpha` on a real `PIXI.Container`/`PIXI.Sprite`.
+ *
+ * All of the above are proven against REAL target objects in
+ * `theatre-object-binding-d3.test.ts` — `BloomEffect`/`VignetteEffect`/
+ * `PIXI.Container`/`PIXI.Sprite` all construct and expose plain,
+ * synchronously-settable properties with no WebGL/canvas/renderer required,
+ * so nothing here is a mock of the underlying library. The one channel that
+ * genuinely cannot construct real headlessly in THIS repo's `environment:
+ * 'node'` vitest lane (`vitest.config.ts` — no DOM) is a real `HTMLElement`;
+ * `bindDomElementStyle` is typed against the narrow `DomStyleTarget`
+ * structural interface instead of full `HTMLElement`, and its test exercises
+ * a plain object literal shaped like one — the exact same binding code path
+ * a real `HTMLElement`/React-overlay ref runs through in a browser or a
+ * jsdom-backed test. Nothing here is deferred.
+ */
+
+/** Thrown when a binding is constructed with a missing/falsy target. */
+export class TheatreBindingError extends Error {
+  constructor(
+    message: string,
+    readonly objectKey: string,
+  ) {
+    super(message);
+    this.name = 'TheatreBindingError';
+  }
+}
+
+export interface Vector3Like {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/**
+ * The fixed shape a Theatre object must expose (as a subset) to drive an
+ * `Object3D`'s transform. Author it with e.g.
+ * `sheet.object('Hero', { position: { x: 0, y: 0, z: 0 }, rotation: { x: 0, y: 0, z: 0 }, scale: { x: 1, y: 1, z: 1 } })`.
+ * `rotation` is Euler angles in radians, XYZ order (matches `THREE.Euler`'s default).
+ */
+export interface TransformProps {
+  position?: Vector3Like;
+  rotation?: Vector3Like;
+  scale?: Vector3Like;
+}
+
+export interface TheatreObjectBindingOptions {
+  /**
+   * Which `AnimationClock` phase to apply values in. Defaults to
+   * `'preRender'` — the documented home for camera placement/material tick
+   * (`ARCHITECTURE.md`), and guaranteed by `PHASE_ORDER` to run after the
+   * `'animation'`-phase default of `bindClockToTheatreSequence`, so the
+   * sheet's sequence position is always current by the time this reads
+   * `sheetObject.value`, regardless of registration order.
+   */
+  phase?: SystemPhaseName;
+}
+
+export interface TheatreObjectBinding {
+  /** Removes the clock evaluator. The target keeps whatever value it last had. */
+  dispose(): void;
+}
+
+/**
+ * Shared disposer wiring for every binding below (same one-shot-dispose
+ * shape `bindObject3DTransform`/`bindCameraLens` each inline above) — pulled
+ * into one helper only because six more binding functions follow, to avoid
+ * repeating the identical five lines six more times. Behavior is identical
+ * to the inline version: idempotent `dispose()`, no further writes after.
+ */
+function toBinding(handle: ClockEvaluatorHandle): TheatreObjectBinding {
+  let disposed = false;
+  return {
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      handle.dispose();
+    },
+  };
+}
+
+/**
+ * Bind a Theatre Sheet Object's `position`/`rotation`/`scale` sub-props (any
+ * subset) to a `THREE.Object3D`. Whichever of the three keys are present on
+ * `sheetObject.value` are applied; missing keys are left untouched on the
+ * target.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindObject3DTransform<Props extends UnknownShorthandCompoundProps>(
+  clock: AnimationClock,
+  sheetObject: ISheetObject<Props>,
+  target: THREE.Object3D | null | undefined,
+  options: TheatreObjectBindingOptions = {},
+): TheatreObjectBinding {
+  if (!target) {
+    throw new TheatreBindingError(
+      `[bindObject3DTransform] missing target Object3D for Theatre object "${sheetObject.address.objectKey}"`,
+      sheetObject.address.objectKey,
+    );
+  }
+
+  const phase = options.phase ?? 'preRender';
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    const value = sheetObject.value as TransformProps;
+    if (value.position) {
+      target.position.set(value.position.x, value.position.y, value.position.z);
+    }
+    if (value.rotation) {
+      target.rotation.set(value.rotation.x, value.rotation.y, value.rotation.z);
+    }
+    if (value.scale) {
+      target.scale.set(value.scale.x, value.scale.y, value.scale.z);
+    }
+  });
+
+  let disposed = false;
+  return {
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      handle.dispose();
+    },
+  };
+}
+
+/**
+ * The fixed shape a Theatre object must expose (as a subset) to drive a
+ * `THREE.PerspectiveCamera`'s lens. Author it with e.g.
+ * `sheet.object('Lens', { fov: 50, near: 0.1, far: 1000 })`.
+ */
+export interface CameraLensProps {
+  fov?: number;
+  near?: number;
+  far?: number;
+}
+
+/**
+ * Bind a Theatre Sheet Object's `fov`/`near`/`far` sub-props (any subset) to
+ * a `THREE.PerspectiveCamera`'s lens, calling `updateProjectionMatrix()`
+ * whenever any of them change.
+ *
+ * @throws {TheatreBindingError} if `camera` is null/undefined at bind time.
+ */
+export function bindCameraLens<Props extends UnknownShorthandCompoundProps>(
+  clock: AnimationClock,
+  sheetObject: ISheetObject<Props>,
+  camera: THREE.PerspectiveCamera | null | undefined,
+  options: TheatreObjectBindingOptions = {},
+): TheatreObjectBinding {
+  if (!camera) {
+    throw new TheatreBindingError(
+      `[bindCameraLens] missing target PerspectiveCamera for Theatre object "${sheetObject.address.objectKey}"`,
+      sheetObject.address.objectKey,
+    );
+  }
+
+  const phase = options.phase ?? 'preRender';
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    const value = sheetObject.value as CameraLensProps;
+    let changed = false;
+    if (typeof value.fov === 'number' && camera.fov !== value.fov) {
+      camera.fov = value.fov;
+      changed = true;
+    }
+    if (typeof value.near === 'number' && camera.near !== value.near) {
+      camera.near = value.near;
+      changed = true;
+    }
+    if (typeof value.far === 'number' && camera.far !== value.far) {
+      camera.far = value.far;
+      changed = true;
+    }
+    if (changed) camera.updateProjectionMatrix();
+  });
+
+  let disposed = false;
+  return {
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      handle.dispose();
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Quaternion rotation
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface QuaternionLike {
+  x: number;
+  y: number;
+  z: number;
+  w: number;
+}
+
+/**
+ * The fixed shape a Theatre object must expose to drive an `Object3D`'s
+ * rotation as a quaternion — an alternative to `TransformProps.rotation`'s
+ * Euler angles for cases that need to avoid gimbal lock or author a rotation
+ * that doesn't decompose cleanly into per-axis Euler angles. Author it with
+ * e.g. `sheet.object('Hero', { quaternion: { x: 0, y: 0, z: 0, w: 1 } })` —
+ * the authored shape is Theatre's plain shorthand-compound of the SAME four
+ * fields `THREE.Quaternion` itself exposes (`x`/`y`/`z`/`w`); there is no
+ * VGAI-invented quaternion encoding.
+ *
+ * Theatre has no native quaternion/slerp track type — it interpolates each
+ * of `x`/`y`/`z`/`w` LINEARLY and independently, so a value read strictly
+ * BETWEEN two authored keyframes is a component-wise lerp, not a slerp, and
+ * is not guaranteed to be exactly unit length. `bindObject3DQuaternion`
+ * always calls `.normalize()` immediately after `.set(...)`, so the applied
+ * rotation is never a scaled/denormalized quaternion even mid-interpolation
+ * — but normalizing a lerp is not the same curve a true slerp would trace.
+ * For continuous cinematic rotation, prefer authoring dense keyframes (exact
+ * at each keyframe, close between nearby ones), or use
+ * `TransformProps.rotation`'s Euler channel instead (also only lerped
+ * per-axis by Theatre, but with no unit-length concern at all).
+ */
+export interface QuaternionProps {
+  quaternion?: QuaternionLike;
+}
+
+/**
+ * Bind a Theatre Sheet Object's `quaternion` sub-prop to a `THREE.Object3D`'s
+ * `.quaternion`. See `QuaternionProps`'s doc for the authored shape and its
+ * interpolation caveat.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindObject3DQuaternion<Props extends UnknownShorthandCompoundProps>(
+  clock: AnimationClock,
+  sheetObject: ISheetObject<Props>,
+  target: THREE.Object3D | null | undefined,
+  options: TheatreObjectBindingOptions = {},
+): TheatreObjectBinding {
+  if (!target) {
+    throw new TheatreBindingError(
+      `[bindObject3DQuaternion] missing target Object3D for Theatre object "${sheetObject.address.objectKey}"`,
+      sheetObject.address.objectKey,
+    );
+  }
+
+  const phase = options.phase ?? 'preRender';
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    const value = sheetObject.value as QuaternionProps;
+    if (value.quaternion) {
+      const { x, y, z, w } = value.quaternion;
+      target.quaternion.set(x, y, z, w);
+      target.quaternion.normalize();
+    }
+  });
+
+  return toBinding(handle);
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Material properties
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ColorLike {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/**
+ * A small, fixed, TYPED subset of `THREE.Material` properties — NOT an
+ * arbitrary property-path evaluator. `color` mirrors Theatre's own native
+ * `types.rgba(...)` value shape (`{r,g,b,a}`, 0-1 floats) minus alpha (use
+ * the separate `opacity` field, which is what `THREE.Material.opacity`
+ * itself already is). `emissiveIntensity`/`roughness`/`metalness` only exist
+ * on `THREE.MeshStandardMaterial`-family materials; `bindMaterialProperties`
+ * feature-detects each with an `in` check and silently skips any sub-prop
+ * the target material doesn't have (mirroring `bindObject3DTransform`'s
+ * "whichever subset is present" contract) rather than throwing.
+ */
+export interface MaterialProps {
+  color?: ColorLike;
+  opacity?: number;
+  emissiveIntensity?: number;
+  roughness?: number;
+  metalness?: number;
+}
+
+type ExtendedMaterial = THREE.Material & {
+  color?: THREE.Color;
+  emissiveIntensity?: number;
+  roughness?: number;
+  metalness?: number;
+};
+
+/**
+ * Bind a Theatre Sheet Object's `color`/`opacity`/`emissiveIntensity`/
+ * `roughness`/`metalness` sub-props (any subset the target material
+ * supports) to a `THREE.Material`.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindMaterialProperties<Props extends UnknownShorthandCompoundProps>(
+  clock: AnimationClock,
+  sheetObject: ISheetObject<Props>,
+  target: THREE.Material | null | undefined,
+  options: TheatreObjectBindingOptions = {},
+): TheatreObjectBinding {
+  if (!target) {
+    throw new TheatreBindingError(
+      `[bindMaterialProperties] missing target Material for Theatre object "${sheetObject.address.objectKey}"`,
+      sheetObject.address.objectKey,
+    );
+  }
+
+  const material = target as ExtendedMaterial;
+  const phase = options.phase ?? 'preRender';
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    const value = sheetObject.value as MaterialProps;
+    if (value.color && material.color) {
+      material.color.setRGB(value.color.r, value.color.g, value.color.b);
+    }
+    if (typeof value.opacity === 'number') {
+      material.opacity = value.opacity;
+    }
+    if (typeof value.emissiveIntensity === 'number' && 'emissiveIntensity' in material) {
+      material.emissiveIntensity = value.emissiveIntensity;
+    }
+    if (typeof value.roughness === 'number' && 'roughness' in material) {
+      material.roughness = value.roughness;
+    }
+    if (typeof value.metalness === 'number' && 'metalness' in material) {
+      material.metalness = value.metalness;
+    }
+  });
+
+  return toBinding(handle);
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Light properties
+// ─────────────────────────────────────────────────────────────────────────
+
+/** A small, fixed, TYPED subset of `THREE.Light` properties. */
+export interface LightProps {
+  intensity?: number;
+  color?: ColorLike;
+}
+
+/**
+ * Bind a Theatre Sheet Object's `intensity`/`color` sub-props (any subset)
+ * to a `THREE.Light`.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindLightProperties<Props extends UnknownShorthandCompoundProps>(
+  clock: AnimationClock,
+  sheetObject: ISheetObject<Props>,
+  target: THREE.Light | null | undefined,
+  options: TheatreObjectBindingOptions = {},
+): TheatreObjectBinding {
+  if (!target) {
+    throw new TheatreBindingError(
+      `[bindLightProperties] missing target Light for Theatre object "${sheetObject.address.objectKey}"`,
+      sheetObject.address.objectKey,
+    );
+  }
+
+  const phase = options.phase ?? 'preRender';
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    const value = sheetObject.value as LightProps;
+    if (typeof value.intensity === 'number') {
+      target.intensity = value.intensity;
+    }
+    if (value.color) {
+      target.color.setRGB(value.color.r, value.color.g, value.color.b);
+    }
+  });
+
+  return toBinding(handle);
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Post-processing (real `postprocessing` package effects — see module doc)
+// ─────────────────────────────────────────────────────────────────────────
+
+/** A small, fixed, TYPED subset of `postprocessing`'s `BloomEffect` properties. */
+export interface BloomEffectProps {
+  intensity?: number;
+  /** Effect blend opacity (`BloomEffect.blendMode.opacity.value`), 0-1. */
+  opacity?: number;
+}
+
+/**
+ * Bind a Theatre Sheet Object's `intensity`/`opacity` sub-props (any subset)
+ * to a real `postprocessing` `BloomEffect` — the SAME `postprocessing` npm
+ * package the engine's own composer pipeline already uses directly
+ * (`setup-renderer.ts`), not a new post-processing stack.
+ *
+ * @throws {TheatreBindingError} if `effect` is null/undefined at bind time.
+ */
+export function bindBloomEffect<Props extends UnknownShorthandCompoundProps>(
+  clock: AnimationClock,
+  sheetObject: ISheetObject<Props>,
+  effect: BloomEffect | null | undefined,
+  options: TheatreObjectBindingOptions = {},
+): TheatreObjectBinding {
+  if (!effect) {
+    throw new TheatreBindingError(
+      `[bindBloomEffect] missing target BloomEffect for Theatre object "${sheetObject.address.objectKey}"`,
+      sheetObject.address.objectKey,
+    );
+  }
+
+  const phase = options.phase ?? 'preRender';
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    const value = sheetObject.value as BloomEffectProps;
+    if (typeof value.intensity === 'number') {
+      effect.intensity = value.intensity;
+    }
+    if (typeof value.opacity === 'number') {
+      effect.blendMode.opacity.value = value.opacity;
+    }
+  });
+
+  return toBinding(handle);
+}
+
+/** A small, fixed, TYPED subset of `postprocessing`'s `VignetteEffect` properties. */
+export interface VignetteEffectProps {
+  offset?: number;
+  darkness?: number;
+}
+
+/**
+ * Bind a Theatre Sheet Object's `offset`/`darkness` sub-props (any subset) to
+ * a real `postprocessing` `VignetteEffect` — same package/no-wrapper note as
+ * `bindBloomEffect` above.
+ *
+ * @throws {TheatreBindingError} if `effect` is null/undefined at bind time.
+ */
+export function bindVignetteEffect<Props extends UnknownShorthandCompoundProps>(
+  clock: AnimationClock,
+  sheetObject: ISheetObject<Props>,
+  effect: VignetteEffect | null | undefined,
+  options: TheatreObjectBindingOptions = {},
+): TheatreObjectBinding {
+  if (!effect) {
+    throw new TheatreBindingError(
+      `[bindVignetteEffect] missing target VignetteEffect for Theatre object "${sheetObject.address.objectKey}"`,
+      sheetObject.address.objectKey,
+    );
+  }
+
+  const phase = options.phase ?? 'preRender';
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    const value = sheetObject.value as VignetteEffectProps;
+    if (typeof value.offset === 'number') {
+      effect.offset = value.offset;
+    }
+    if (typeof value.darkness === 'number') {
+      effect.darkness = value.darkness;
+    }
+  });
+
+  return toBinding(handle);
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Selected UI properties (DOM-style-writable target)
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * A minimal structural interface for a DOM-style-writable target — NOT the
+ * full `HTMLElement` API. A real `HTMLElement` (or a React ref's `.current`)
+ * satisfies this structurally with no adapter, since
+ * `CSSStyleDeclaration.opacity`/`.transform` are themselves plain strings.
+ * This repo's vitest lane runs `environment: 'node'` (`vitest.config.ts`,
+ * no DOM), so `theatre-object-binding-d3.test.ts` exercises
+ * `bindDomElementStyle` against a plain object literal shaped like `{
+ * style: { opacity: '', transform: '' } }` — the exact same binding code
+ * path a real `HTMLElement`/React-overlay ref runs through in a browser or a
+ * jsdom-backed test elsewhere in the stack.
+ */
+export interface DomStyleTarget {
+  style: {
+    opacity: string;
+    transform: string;
+  };
+}
+
+/**
+ * A small, fixed, TYPED set of DOM/React-overlay-friendly style properties:
+ * opacity plus a 2D translate. The two translate axes are combined into one
+ * CSS `transform` string, remembering whichever value was last authored on
+ * each axis so authoring only one axis doesn't reset the other to 0.
+ */
+export interface UIElementProps {
+  opacity?: number;
+  translateX?: number;
+  translateY?: number;
+}
+
+/**
+ * Bind a Theatre Sheet Object's `opacity`/`translateX`/`translateY`
+ * sub-props (any subset) to a DOM-style-writable target's inline style. See
+ * `DomStyleTarget`'s doc for how this is proven without a real browser DOM.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindDomElementStyle<Props extends UnknownShorthandCompoundProps>(
+  clock: AnimationClock,
+  sheetObject: ISheetObject<Props>,
+  target: DomStyleTarget | null | undefined,
+  options: TheatreObjectBindingOptions = {},
+): TheatreObjectBinding {
+  if (!target) {
+    throw new TheatreBindingError(
+      `[bindDomElementStyle] missing target DOM element for Theatre object "${sheetObject.address.objectKey}"`,
+      sheetObject.address.objectKey,
+    );
+  }
+
+  const phase = options.phase ?? 'preRender';
+  let lastTranslateX = 0;
+  let lastTranslateY = 0;
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    const value = sheetObject.value as UIElementProps;
+    if (typeof value.opacity === 'number') {
+      target.style.opacity = String(value.opacity);
+    }
+    if (typeof value.translateX === 'number') lastTranslateX = value.translateX;
+    if (typeof value.translateY === 'number') lastTranslateY = value.translateY;
+    if (typeof value.translateX === 'number' || typeof value.translateY === 'number') {
+      target.style.transform = `translate(${lastTranslateX}px, ${lastTranslateY}px)`;
+    }
+  });
+
+  return toBinding(handle);
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Pixi binding helper
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * A small, fixed, TYPED subset of `PIXI.Container` (and, since `PIXI.Sprite
+ * extends Container`, `PIXI.Sprite` too) transform/alpha properties.
+ * `rotation` is in radians (matches `Container.rotation`'s own unit).
+ */
+export interface PixiTransformProps {
+  x?: number;
+  y?: number;
+  rotation?: number;
+  scaleX?: number;
+  scaleY?: number;
+  alpha?: number;
+}
+
+/**
+ * Bind a Theatre Sheet Object's `x`/`y`/`rotation`/`scaleX`/`scaleY`/`alpha`
+ * sub-props (any subset) to a real `PIXI.Container`/`PIXI.Sprite` (reusing
+ * the world2d stack's own `pixi.js` dependency — see this module's
+ * type-only `pixi.js` import above and its doc note on why the engine core
+ * never value-imports it). Plain `Container`/`Sprite` construction needs no
+ * canvas/WebGL context, so this is proven against a REAL Pixi object in
+ * `theatre-object-binding-d3.test.ts`, not a stand-in.
+ *
+ * @throws {TheatreBindingError} if `target` is null/undefined at bind time.
+ */
+export function bindPixiContainerTransform<Props extends UnknownShorthandCompoundProps>(
+  clock: AnimationClock,
+  sheetObject: ISheetObject<Props>,
+  target: Container | null | undefined,
+  options: TheatreObjectBindingOptions = {},
+): TheatreObjectBinding {
+  if (!target) {
+    throw new TheatreBindingError(
+      `[bindPixiContainerTransform] missing target PIXI.Container for Theatre object "${sheetObject.address.objectKey}"`,
+      sheetObject.address.objectKey,
+    );
+  }
+
+  const phase = options.phase ?? 'preRender';
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    const value = sheetObject.value as PixiTransformProps;
+    if (typeof value.x === 'number') target.x = value.x;
+    if (typeof value.y === 'number') target.y = value.y;
+    if (typeof value.rotation === 'number') target.rotation = value.rotation;
+    if (typeof value.scaleX === 'number') target.scale.x = value.scaleX;
+    if (typeof value.scaleY === 'number') target.scale.y = value.scaleY;
+    if (typeof value.alpha === 'number') target.alpha = value.alpha;
+  });
+
+  return toBinding(handle);
+}