@vgai/engine 0.5.0 → 0.5.2

package/dist/animation/theatre-director.js

@@ -1,235 +0,0 @@
-/**
- * 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

@@ -1,305 +0,0 @@
-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

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