@vgai/engine 0.2.0 → 0.3.0

package/dist/animation/theatre-director.js

@@ -0,0 +1,235 @@
+/**
+ * D4 — the Theatre "Director" convention (spec §10 D4, §5.3, §3.2).
+ *
+ * A `Director` is an ordinary Theatre Sheet Object, authored with Theatre's
+ * NATIVE `types.stringLiteral`/`types.boolean` vocabulary exactly as shown in
+ * spec §5.3 — this module never wraps or renames that API. It is a
+ * *convention* (a documented, stable shape) plus a thin binding, not a new
+ * animation format:
+ *
+ * ```ts
+ * import { types } from '@theatre/core';
+ * const director = sheet.object('Director', {
+ *   activeCamera: types.stringLiteral('wide', { wide: 'wide', close: 'close', gameplay: 'gameplay' }),
+ *   shot: types.stringLiteral('opening', { opening: 'opening', reveal: 'reveal', ending: 'ending' }),
+ *   letterbox: types.boolean(false),
+ *   // extensible: any additional directorial prop is carried through verbatim
+ *   // as `DirectorState.extras`, e.g.:
+ *   blendSeconds: types.number(0, { range: [0, Infinity] }),
+ * });
+ * ```
+ *
+ * `activeCamera`/`shot`/`letterbox` are required by the convention (spec §10
+ * D4 AC: "covers active camera, shot ID, letterbox, and optional directorial
+ * properties"). Anything else declared on the same Theatre object (exposure,
+ * grade, a blend-duration prop, ...) is an "optional directorial property" —
+ * it is read and surfaced verbatim through `DirectorState.extras`, never
+ * hardcoded here, which is what keeps the convention extensible without
+ * VGAI inventing a schema for it.
+ *
+ * ## Binding: pull-based, same lockstep pattern as D2/D3
+ *
+ * `bindDirectorToClock` follows exactly the `theatre-clock-binding.ts` /
+ * `theatre-object-binding.ts` pattern: it reads the Director object's
+ * pull-based `sheetObject.value` on every canonical-clock crossing (never
+ * Theatre's own batched `onValuesChange` push channel — see those modules'
+ * doc comments for why that would desync from a synchronous `clock.seek()`).
+ * Default phase is `'preRender'`, the same default `bindObject3DTransform`/
+ * `bindCameraLens` use, so — via `PHASE_ORDER`, not registration order — the
+ * Director always reads a sequence position that `bindClockToTheatreSequence`
+ * (registered at `'animation'`, which runs earlier) has already set for this
+ * crossing, regardless of which binding a caller sets up first.
+ *
+ * ## Seeking updates Director without firing gameplay cues
+ *
+ * This binding has NO concept of "seek" vs "advance" — unlike
+ * `CueRunner` (D5, `cinematic-cues.ts`), which deliberately distinguishes the
+ * two (via its own `seek()`/`advance()` wrapper methods) so a
+ * `firesDuringSeek: false` cue can be skipped on scrub. A Director value is
+ * *visual/directorial state*, not a gameplay consequence (spec §3.2: "Theatre
+ * carries visual/directorial values; ordinary TypeScript cues carry gameplay
+ * consequences") — it should always reflect the clock's current time,
+ * however the clock got there. Composing the two on the SAME
+ * `AnimationClock` (Director bound directly to the clock; cues bound through
+ * a `CueRunner` wrapping the same clock) is exactly what makes "seek updates
+ * Director but does not spuriously fire gameplay cues" fall out for free: a
+ * `CueRunner.seek(t)` call moves the one shared clock, which both this
+ * binding (always reacts) and the cue runner (gates on `firesDuringSeek`)
+ * observe on the same crossing. See `theatre-director.test.ts`'s
+ * "composes with D5" suite for the proof.
+ *
+ * ## Camera-ownership hook — the D6 seam
+ *
+ * Discrete `activeCamera` changes are exactly the moments a *camera
+ * ownership* system (D6, not built in this unit) needs to know about, to cut
+ * or blend the live gameplay camera to the Director's declared shot. This
+ * module does not own or perform any camera mutation — it only DETECTS a
+ * change in the Director's `activeCamera` value across successive
+ * evaluations and reports it through `onActiveCameraChange`
+ * (`CameraOwnershipHook`), a minimal, one-directional seam:
+ *
+ *  - fired once per detected `activeCamera` transition (never for a
+ *    no-op/unchanged evaluation, including a re-seek to the same time or a
+ *    seek that stays within the same shot's camera);
+ *  - the FIRST evaluation after bind is treated as an "assignment", not a
+ *    "cut from something" — `previousCameraKey` is `null` and `mode` is
+ *    forced to `'cut'` (there is nothing to blend FROM yet; D6 is expected
+ *    to use this event to perform its initial camera capture/placement);
+ *  - `mode`/`blendSeconds` are derived from an optional extra numeric prop on
+ *    the SAME Director object (`blendSecondsKey`, default `'blendSeconds'`)
+ *    — a positive value at the moment of the transition means `'blend'`
+ *    (with that duration), anything else means `'cut'`. This is the "expose
+ *    enough for a consumer to cut or blend" seam named in the D4 AC; the
+ *    ACTUAL blend implementation (interpolating the live camera pose over
+ *    `blendSeconds`) is D6's job, not this module's.
+ *
+ * ### `blendSeconds` MUST be authored as HOLD keyframes
+ *
+ * `blendSeconds` is read at the EXACT moment `activeCamera` is detected to
+ * change, whatever clock time that happens to land on. If `blendSeconds` is
+ * authored as an ordinary interpolating (bezier) track, a transition
+ * detected at a time that isn't exactly a keyframe position reads whatever
+ * partially-interpolated value the bezier curve has reached AT THAT MOMENT —
+ * not the value actually authored FOR that transition. Concretely: a cut
+ * authored at `t=3` with `blendSeconds=0`, followed by a blend authored at
+ * `t=6` with `blendSeconds=1.5`, makes the track interpolate from `0` to
+ * `1.5` across `[3, 6)`. If the `activeCamera` transition at `t=3` is first
+ * *observed* at some later non-keyframe time inside that span (e.g. a coarse
+ * seek from `t=2` straight to `t=4.5`, skipping past `t=3` without an
+ * intermediate evaluation), `blendSeconds` at `t=4.5` reads a nonzero,
+ * partially-interpolated value — misreporting an authored CUT as a partial
+ * BLEND.
+ *
+ * The fix is to author `blendSeconds` keyframes as Theatre HOLD keyframes
+ * (`connectedRight: false`, optionally also `type: 'hold'`) rather than the
+ * default interpolating bezier keyframes. `connectedRight: false` makes
+ * Theatre's own sequence evaluator hold the LEFT keyframe's value constant
+ * across the entire span up to (not including) the next keyframe, then snap
+ * — never partially interpolate. With `blendSeconds` authored this way, its
+ * value at ANY time within `[3, 6)` reads exactly `0` (the cut authored at
+ * `t=3`), and only reads `1.5` once the clock reaches `t=6` (the blend
+ * authored there) — correct regardless of which non-keyframe time a
+ * transition happens to first be observed at. See
+ * `fixtures/theatre-director-proof.theatre-project.json` (its `blendSeconds`
+ * track uses `connectedRight: false` on every keyframe) and
+ * `theatre-director.test.ts`'s "playback grid" suite, which proves this by
+ * evaluating a fine-grained, non-keyframe-aligned time grid across the whole
+ * span and asserting the reported `mode` never drifts from what was
+ * authored at the keyframe that produced the transition.
+ *
+ * D6 will most likely implement `CameraOwnershipHook` as (roughly) "capture
+ * gameplay camera pose once on the first `mode: 'cut'` event; on each
+ * subsequent event, cut or blend the owned camera to the shot named by
+ * `cameraKey`". Nothing above depends on that implementation existing —
+ * `onActiveCameraChange` is optional and this module works with no hook
+ * attached at all (Director values are still readable via `getState()`).
+ *
+ * ## Read API (SDK/CLI seam, B5)
+ *
+ * `readDirectorState` is a pure, synchronous read of whatever a Director
+ * Theatre object's CURRENT value is — no clock/binding required. It is what
+ * a later `cinematic.*` SDK/CLI operation (B5) would call to inspect Director
+ * state (e.g. "what shot is authored at time t") without needing to spin up
+ * a full runtime binding. `TheatreDirectorBinding.getState()` is the
+ * clock-driven equivalent — it returns the value read at bind time until the
+ * FIRST clock crossing occurs (not "the most recent crossing" — before any
+ * crossing there IS no crossing yet), and the value as of the most recent
+ * crossing thereafter.
+ *
+ * Authoring `Director` keyframes in Theatre Studio is a dev-only workflow
+ * (spec §10 D2: "Theatre Studio is available only in authoring/development
+ * contexts"); the committed project-state JSON is the source of truth this
+ * module reads in production — nothing here imports the Theatre Studio
+ * package (see `theatre-binding.test.ts`'s repo-wide grep proof of that).
+ */
+/** Thrown when a Theatre object does not conform to the Director convention. */
+export class TheatreDirectorError extends Error {
+    objectKey;
+    constructor(message, objectKey) {
+        super(message);
+        this.objectKey = objectKey;
+        this.name = 'TheatreDirectorError';
+    }
+}
+const REQUIRED_DIRECTOR_KEYS = new Set(['activeCamera', 'shot', 'letterbox']);
+/**
+ * Pure, synchronous read of a Director Theatre object's CURRENT value.
+ * No clock/binding involved — suitable for one-shot inspection (the later
+ * SDK/CLI read path, B5) as well as being the function
+ * `bindDirectorToClock` itself calls on every crossing.
+ *
+ * @throws {TheatreDirectorError} if the object's value does not conform to
+ *   the Director convention (missing/mistyped `activeCamera`/`shot`/`letterbox`).
+ */
+export function readDirectorState(sheetObject) {
+    const raw = sheetObject.value;
+    const objectKey = sheetObject.address.objectKey;
+    const activeCamera = raw['activeCamera'];
+    if (typeof activeCamera !== 'string') {
+        throw new TheatreDirectorError(`[readDirectorState] Director object "${objectKey}" is missing a string "activeCamera" prop — ` +
+            `declare it with types.stringLiteral(...) (spec §5.3/§10 D4)`, objectKey);
+    }
+    const shot = raw['shot'];
+    if (typeof shot !== 'string') {
+        throw new TheatreDirectorError(`[readDirectorState] Director object "${objectKey}" is missing a string "shot" prop — ` +
+            `declare it with types.stringLiteral(...) (spec §5.3/§10 D4)`, objectKey);
+    }
+    const letterbox = raw['letterbox'];
+    if (typeof letterbox !== 'boolean') {
+        throw new TheatreDirectorError(`[readDirectorState] Director object "${objectKey}" is missing a boolean "letterbox" prop — ` +
+            `declare it with types.boolean(...) (spec §5.3/§10 D4)`, objectKey);
+    }
+    const extras = {};
+    for (const key of Object.keys(raw)) {
+        if (!REQUIRED_DIRECTOR_KEYS.has(key))
+            extras[key] = raw[key];
+    }
+    return { activeCamera, shot, letterbox, extras: Object.freeze(extras) };
+}
+/**
+ * Bind a Director Theatre Sheet Object to `clock`: on every crossing, read
+ * its current value (`readDirectorState`) and, if `activeCamera` changed
+ * since the last evaluation, report the transition through
+ * `onActiveCameraChange` (the D6 seam). Returns a disposer and a `getState()`
+ * read API. See the module doc comment for the full contract.
+ */
+export function bindDirectorToClock(clock, sheetObject, options = {}) {
+    const phase = options.phase ?? 'preRender';
+    const blendSecondsKey = options.blendSecondsKey ?? 'blendSeconds';
+    let state = readDirectorState(sheetObject);
+    let previousCameraKey = null;
+    let hasEvaluatedOnClock = false;
+    function evaluate() {
+        state = readDirectorState(sheetObject);
+        const changed = !hasEvaluatedOnClock || state.activeCamera !== previousCameraKey;
+        if (changed) {
+            const blendRaw = state.extras[blendSecondsKey];
+            const blendSeconds = hasEvaluatedOnClock && typeof blendRaw === 'number' && blendRaw > 0 ? blendRaw : 0;
+            const mode = blendSeconds > 0 ? 'blend' : 'cut';
+            options.onActiveCameraChange?.({
+                cameraKey: state.activeCamera,
+                previousCameraKey: hasEvaluatedOnClock ? previousCameraKey : null,
+                mode,
+                blendSeconds,
+                shot: state.shot,
+            });
+            previousCameraKey = state.activeCamera;
+            hasEvaluatedOnClock = true;
+        }
+    }
+    const handle = clock.subscribe(phase, () => {
+        evaluate();
+    });
+    let disposed = false;
+    return {
+        getState() {
+            return state;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            handle.dispose();
+        },
+    };
+}

package/dist/animation/theatre-object-binding.d.ts

@@ -0,0 +1,305 @@
+import type { ISheetObject, UnknownShorthandCompoundProps } from '@theatre/core';
+import type { Container } from 'pixi.js';
+import type { BloomEffect, VignetteEffect } from 'postprocessing';
+import type * as THREE from 'three';
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock } 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 declare class TheatreBindingError extends Error {
+    readonly objectKey: string;
+    constructor(message: string, objectKey: string);
+}
+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;
+}
+/**
+ * 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 declare function bindObject3DTransform<Props extends UnknownShorthandCompoundProps>(clock: AnimationClock, sheetObject: ISheetObject<Props>, target: THREE.Object3D | null | undefined, options?: TheatreObjectBindingOptions): TheatreObjectBinding;
+/**
+ * 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 declare function bindCameraLens<Props extends UnknownShorthandCompoundProps>(clock: AnimationClock, sheetObject: ISheetObject<Props>, camera: THREE.PerspectiveCamera | null | undefined, options?: TheatreObjectBindingOptions): TheatreObjectBinding;
+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 declare function bindObject3DQuaternion<Props extends UnknownShorthandCompoundProps>(clock: AnimationClock, sheetObject: ISheetObject<Props>, target: THREE.Object3D | null | undefined, options?: TheatreObjectBindingOptions): TheatreObjectBinding;
+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;
+}
+/**
+ * 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 declare function bindMaterialProperties<Props extends UnknownShorthandCompoundProps>(clock: AnimationClock, sheetObject: ISheetObject<Props>, target: THREE.Material | null | undefined, options?: TheatreObjectBindingOptions): TheatreObjectBinding;
+/** 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 declare function bindLightProperties<Props extends UnknownShorthandCompoundProps>(clock: AnimationClock, sheetObject: ISheetObject<Props>, target: THREE.Light | null | undefined, options?: TheatreObjectBindingOptions): TheatreObjectBinding;
+/** 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 declare function bindBloomEffect<Props extends UnknownShorthandCompoundProps>(clock: AnimationClock, sheetObject: ISheetObject<Props>, effect: BloomEffect | null | undefined, options?: TheatreObjectBindingOptions): TheatreObjectBinding;
+/** 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 declare function bindVignetteEffect<Props extends UnknownShorthandCompoundProps>(clock: AnimationClock, sheetObject: ISheetObject<Props>, effect: VignetteEffect | null | undefined, options?: TheatreObjectBindingOptions): TheatreObjectBinding;
+/**
+ * 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 declare function bindDomElementStyle<Props extends UnknownShorthandCompoundProps>(clock: AnimationClock, sheetObject: ISheetObject<Props>, target: DomStyleTarget | null | undefined, options?: TheatreObjectBindingOptions): TheatreObjectBinding;
+/**
+ * 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 declare function bindPixiContainerTransform<Props extends UnknownShorthandCompoundProps>(clock: AnimationClock, sheetObject: ISheetObject<Props>, target: Container | null | undefined, options?: TheatreObjectBindingOptions): TheatreObjectBinding;
+//# sourceMappingURL=theatre-object-binding.d.ts.map

package/dist/animation/theatre-object-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theatre-object-binding.d.ts","sourceRoot":"","sources":["../../src/animation/theatre-object-binding.ts"],"names":[],"mappings":"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"}