@open-core/framework 1.0.4-beta.1 → 1.0.5-beta.2

package/dist/runtime/client/services/cinematic.js

@@ -0,0 +1,798 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from 'tsyringe';
+import { IClientPlatformBridge } from '../adapter/platform-bridge';
+import { IClientRuntimeBridge } from '../adapter/runtime-bridge';
+import { CameraEffectsRegistry, } from './camera-effects.registry';
+import { Camera } from './camera';
+import { SceneBuilder } from './cinematic-builder';
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Structured validation error thrown when a cinematic definition is invalid.
+ */
+export class CinematicValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super([
+            'Invalid cinematic definition:',
+            ...issues.map((issue, index) => `  ${index + 1}. ${issue}`),
+        ].join('\n'));
+        this.issues = issues;
+        this.name = 'CinematicValidationError';
+    }
+}
+/**
+ * Mutable control handle for a running cinematic.
+ */
+export class CinematicHandle {
+    runtime;
+    result;
+    listeners = new Map();
+    constructor(runtime, 
+    /** Promise resolved when the cinematic finishes. */
+    result) {
+        this.runtime = runtime;
+        this.result = result;
+    }
+    /**
+     * Pauses timeline progression.
+     */
+    pause() {
+        if (this.runtime.paused)
+            return;
+        this.runtime.paused = true;
+        this.runtime.pauseStartedAt = Date.now();
+        this.emit('paused', undefined);
+    }
+    /**
+     * Resumes timeline progression.
+     */
+    resume() {
+        if (!this.runtime.paused)
+            return;
+        this.runtime.paused = false;
+        this.runtime.pauseStartedAt = null;
+        this.emit('resumed', undefined);
+    }
+    /**
+     * Cancels timeline execution.
+     */
+    cancel() {
+        this.runtime.cancelled = true;
+        this.runtime.interruptStatus = 'cancelled';
+    }
+    /**
+     * Requests skip as a cancellation with completed cleanup.
+     */
+    skip() {
+        this.cancel();
+    }
+    /**
+     * Applies an in-place patch to the live definition object.
+     */
+    edit(mutator) {
+        mutator(this.runtime.definition);
+    }
+    /**
+     * Inserts a shot at a specific index.
+     */
+    insertShot(index, shot) {
+        this.runtime.definition.shots.splice(Math.max(0, index), 0, shot);
+    }
+    /**
+     * Replaces a shot by id or no-ops when not found.
+     */
+    replaceShot(shotId, shot) {
+        const index = this.runtime.definition.shots.findIndex((entry) => entry.id === shotId);
+        if (index === -1)
+            return;
+        this.runtime.definition.shots[index] = shot;
+    }
+    /**
+     * Replaces global effects for the running definition.
+     */
+    setEffects(effects) {
+        this.runtime.definition.effects = effects;
+    }
+    /**
+     * Adds a global effect to the running definition.
+     */
+    addEffect(effect) {
+        if (!this.runtime.definition.effects) {
+            this.runtime.definition.effects = [];
+        }
+        this.runtime.definition.effects.push(effect);
+    }
+    /**
+     * Removes all global effects with a matching id.
+     */
+    removeEffect(effectId) {
+        const current = this.runtime.definition.effects ?? [];
+        this.runtime.definition.effects = current.filter((effect) => effect.id !== effectId);
+    }
+    /**
+     * Subscribes to runtime handle events.
+     */
+    on(eventName, handler) {
+        const handlers = this.listeners.get(eventName) ?? new Set();
+        handlers.add(handler);
+        this.listeners.set(eventName, handlers);
+        return () => {
+            handlers.delete(handler);
+        };
+    }
+    /**
+     * Emits an event to handle subscribers.
+     */
+    emit(eventName, payload) {
+        const handlers = this.listeners.get(eventName);
+        if (!handlers || handlers.size === 0)
+            return;
+        for (const handler of handlers.values()) {
+            ;
+            handler(payload);
+        }
+    }
+}
+/**
+ * High-level cinematic timeline API built on top of Camera.
+ */
+let Cinematic = class Cinematic {
+    camera;
+    platform;
+    runtimeBridge;
+    /**
+     * Exposes the registry so consumers can add custom effects and presets.
+     */
+    effects;
+    activeRuntime = null;
+    constructor(camera, effectsRegistry, platform, runtimeBridge) {
+        this.camera = camera;
+        this.platform = platform;
+        this.runtimeBridge = runtimeBridge;
+        this.effects = effectsRegistry;
+        if (!this.effects.has('fadeIn')) {
+            this.effects.registerBuiltins();
+        }
+        const currentResource = this.runtimeBridge.getCurrentResourceName();
+        this.runtimeBridge.on('onClientResourceStop', (resourceName) => {
+            if (resourceName !== currentResource)
+                return;
+            this.cancel();
+            this.camera.reset({ ease: false, easeTimeMs: 0 });
+        });
+    }
+    /**
+     * Creates a fluent cinematic scene builder bound to this service.
+     */
+    scene(id) {
+        return new SceneBuilder({
+            id,
+            start: (scene, options) => this.start(scene, options),
+        });
+    }
+    /**
+     * Starts a cinematic and returns a mutable runtime handle immediately.
+     */
+    start(scene, options = {}) {
+        const definition = scene.build();
+        this.validateDefinition(definition);
+        if (this.activeRuntime) {
+            this.activeRuntime.cancelled = true;
+            this.activeRuntime.interruptStatus = 'interrupted';
+        }
+        const runtime = {
+            definition,
+            options: {
+                skipControlId: options.skipControlId ?? 200,
+                cameraName: options.cameraName ?? 'DEFAULT_SCRIPTED_CAMERA',
+            },
+            camHandle: this.camera.create({
+                camName: options.cameraName ?? 'DEFAULT_SCRIPTED_CAMERA',
+                active: true,
+            }),
+            cancelled: false,
+            paused: false,
+            pauseStartedAt: null,
+            interruptStatus: null,
+        };
+        this.activeRuntime = runtime;
+        this.camera.setActive(runtime.camHandle, true);
+        this.camera.render(true, { ease: true, easeTimeMs: 250 });
+        let resolveResult = null;
+        let rejectResult = null;
+        const resultPromise = new Promise((resolve, reject) => {
+            resolveResult = resolve;
+            rejectResult = reject;
+        });
+        const handle = new CinematicHandle(runtime, resultPromise);
+        void this.run(runtime, handle)
+            .then((result) => {
+            if (result.status === 'completed') {
+                handle.emit('completed', result);
+            }
+            else if (result.status === 'interrupted') {
+                handle.emit('interrupted', result);
+            }
+            else {
+                handle.emit('cancelled', result);
+            }
+            resolveResult?.(result);
+        })
+            .catch((error) => {
+            rejectResult?.(error);
+        });
+        return handle;
+    }
+    /**
+     * Starts and awaits a cinematic timeline until completion.
+     */
+    async play(scene, options = {}) {
+        const handle = this.start(scene, options);
+        return handle.result;
+    }
+    /**
+     * Returns true when a cinematic timeline is running.
+     */
+    isRunning() {
+        return this.activeRuntime !== null;
+    }
+    /**
+     * Cancels the active cinematic if one exists.
+     */
+    cancel() {
+        if (!this.activeRuntime)
+            return;
+        this.activeRuntime.cancelled = true;
+        this.activeRuntime.interruptStatus = 'cancelled';
+    }
+    /**
+     * Registers a custom effect.
+     */
+    registerEffect(effect) {
+        this.effects.register(effect);
+    }
+    async run(runtime, handle) {
+        const ped = this.platform.getLocalPlayerPed();
+        try {
+            this.applyRuntimeFlags(runtime.definition, ped);
+            let shotIndex = 0;
+            while (shotIndex < runtime.definition.shots.length) {
+                if (runtime.cancelled) {
+                    break;
+                }
+                const shot = runtime.definition.shots[shotIndex];
+                const plannedDurationMs = shot.waitMs ?? shot.durationMs ?? 0;
+                const shotPayload = {
+                    shotIndex,
+                    totalShots: runtime.definition.shots.length,
+                    shotId: shot.id,
+                    kind: shot.waitMs ? 'wait' : 'motion',
+                    plannedDurationMs,
+                };
+                handle.emit('shotStart', shotPayload);
+                if (shot.waitMs && shot.waitMs > 0) {
+                    await this.waitStep(runtime, shot.waitMs);
+                    handle.emit('shotEnd', shotPayload);
+                    shotIndex += 1;
+                    continue;
+                }
+                const durationMs = shot.durationMs ?? 0;
+                if (durationMs <= 0) {
+                    handle.emit('shotEnd', shotPayload);
+                    shotIndex += 1;
+                    continue;
+                }
+                const nodes = await this.resolveShotNodes(shot, runtime.definition.anchors ?? {});
+                if (nodes.length === 0) {
+                    handle.emit('shotEnd', shotPayload);
+                    shotIndex += 1;
+                    continue;
+                }
+                const globalEffects = this.resolveGlobalEffects(runtime.definition);
+                const shotEffects = shot.effects ?? [];
+                const effects = this.buildRuntimeEffects([...globalEffects, ...shotEffects]);
+                await this.runShot(runtime, handle, shotIndex, shot, nodes, effects, durationMs);
+                handle.emit('shotEnd', shotPayload);
+                shotIndex += 1;
+            }
+            if (runtime.cancelled) {
+                return {
+                    status: runtime.interruptStatus ?? 'cancelled',
+                    definitionId: runtime.definition.id,
+                };
+            }
+            return {
+                status: 'completed',
+                definitionId: runtime.definition.id,
+            };
+        }
+        finally {
+            this.cleanupRuntime(runtime, ped);
+            if (this.activeRuntime === runtime) {
+                this.activeRuntime = null;
+            }
+        }
+    }
+    applyRuntimeFlags(definition, ped) {
+        if (definition.freezePlayer) {
+            this.platform.freezeEntityPosition(ped, true);
+        }
+        if (definition.invinciblePlayer) {
+            this.platform.setEntityInvincible(ped, true);
+        }
+        if (definition.hideHud) {
+            this.platform.displayHud(false);
+        }
+        if (definition.hideRadar) {
+            this.platform.displayRadar(false);
+        }
+    }
+    cleanupRuntime(runtime, ped) {
+        this.camera.stopPointing(runtime.camHandle);
+        this.camera.stopShaking(runtime.camHandle, true);
+        this.camera.render(false, { ease: true, easeTimeMs: 250 });
+        this.camera.destroy(runtime.camHandle, false);
+        if (runtime.definition.freezePlayer) {
+            this.platform.freezeEntityPosition(ped, false);
+        }
+        if (runtime.definition.invinciblePlayer) {
+            this.platform.setEntityInvincible(ped, false);
+        }
+        if (runtime.definition.hideHud) {
+            this.platform.displayHud(true);
+        }
+        if (runtime.definition.hideRadar) {
+            this.platform.displayRadar(true);
+        }
+        this.platform.clearTimecycleModifier();
+    }
+    resolveGlobalEffects(definition) {
+        const direct = definition.effects ?? [];
+        const presetRefs = (definition.effectPresets ?? []).flatMap((presetId) => this.effects.usePreset(presetId));
+        return [...presetRefs, ...direct];
+    }
+    buildRuntimeEffects(effectRefs) {
+        const effects = [];
+        for (const ref of effectRefs) {
+            const definition = this.effects.get(ref.id);
+            if (!definition)
+                continue;
+            const params = {
+                ...definition.defaults,
+                ...ref.params,
+            };
+            effects.push({
+                ref,
+                definition,
+                params,
+                active: false,
+            });
+        }
+        return effects;
+    }
+    async runShot(runtime, handle, shotIndex, shot, nodes, effects, durationMs) {
+        const start = this.runtimeBridge.getGameTimer();
+        let previousTime = start;
+        while (true) {
+            if (runtime.cancelled) {
+                await this.finalizeEffects(runtime, effects, 'cancelled', durationMs);
+                return;
+            }
+            if (runtime.paused) {
+                previousTime = this.runtimeBridge.getGameTimer();
+                await delay(0);
+                continue;
+            }
+            if (runtime.definition.skippable &&
+                this.platform.isControlJustPressed(0, runtime.options.skipControlId)) {
+                runtime.cancelled = true;
+                runtime.interruptStatus = 'cancelled';
+                await this.finalizeEffects(runtime, effects, 'cancelled', durationMs);
+                return;
+            }
+            const now = this.runtimeBridge.getGameTimer();
+            const elapsedMs = now - start;
+            const deltaMs = now - previousTime;
+            previousTime = now;
+            const normalized = this.applyEase(Math.min(elapsedMs / durationMs, 1), shot.ease ?? 'linear');
+            const node = this.sampleNode(nodes, normalized);
+            this.camera.setTransform(runtime.camHandle, {
+                position: node.position,
+                rotation: node.rotation,
+                fov: node.fov,
+            });
+            if (shot.lookAt) {
+                const lookTarget = await this.resolveLookAtTarget(shot.lookAt, runtime.definition.anchors ?? {}, normalized);
+                this.camera.pointAtCoords(runtime.camHandle, lookTarget);
+            }
+            else {
+                this.camera.stopPointing(runtime.camHandle);
+            }
+            await this.updateEffects(runtime, handle, shotIndex, shot.id, effects, elapsedMs, deltaMs, durationMs);
+            if (elapsedMs >= durationMs) {
+                await this.finalizeEffects(runtime, effects, 'completed', durationMs);
+                return;
+            }
+            await delay(0);
+        }
+    }
+    async waitStep(runtime, waitMs) {
+        const started = this.runtimeBridge.getGameTimer();
+        while (this.runtimeBridge.getGameTimer() - started < waitMs) {
+            if (runtime.cancelled)
+                return;
+            if (runtime.paused) {
+                await delay(0);
+                continue;
+            }
+            if (runtime.definition.skippable &&
+                this.platform.isControlJustPressed(0, runtime.options.skipControlId)) {
+                runtime.cancelled = true;
+                runtime.interruptStatus = 'cancelled';
+                return;
+            }
+            await delay(0);
+        }
+    }
+    async updateEffects(runtime, handle, shotIndex, shotId, effects, elapsedMs, deltaMs, totalDurationMs) {
+        for (const effect of effects) {
+            const fromMs = effect.ref.fromMs ?? 0;
+            const toMs = effect.ref.toMs ?? totalDurationMs;
+            const isActive = elapsedMs >= fromMs && elapsedMs <= toMs;
+            const windowDuration = Math.max(1, toMs - fromMs);
+            const normalized = Math.min(Math.max((elapsedMs - fromMs) / windowDuration, 0), 1);
+            const ctx = this.createEffectContext(runtime, elapsedMs, normalized, deltaMs);
+            if (isActive && !effect.active && effect.definition.setup) {
+                await effect.definition.setup(ctx, effect.params);
+                handle.emit('effectApplied', {
+                    effectId: effect.ref.id,
+                    shotIndex,
+                    shotId,
+                });
+            }
+            if (isActive && effect.definition.update) {
+                await effect.definition.update(ctx, effect.params);
+            }
+            if (!isActive && effect.active && effect.definition.teardown) {
+                await effect.definition.teardown(ctx, effect.params, 'completed');
+            }
+            effect.active = isActive;
+        }
+    }
+    async finalizeEffects(runtime, effects, reason, elapsedMs) {
+        for (const effect of effects) {
+            if (!effect.active || !effect.definition.teardown)
+                continue;
+            const ctx = this.createEffectContext(runtime, elapsedMs, 1, 0);
+            await effect.definition.teardown(ctx, effect.params, reason);
+            effect.active = false;
+        }
+    }
+    createEffectContext(runtime, elapsedMs, normalized, deltaMs) {
+        return {
+            camera: this.camera,
+            camHandle: runtime.camHandle,
+            elapsedMs,
+            normalized,
+            deltaMs,
+            drawSubtitle: (text) => {
+                this.platform.beginTextCommandDisplayText('STRING');
+                this.platform.addTextComponentSubstringPlayerName(text);
+                this.platform.endTextCommandDisplayText(0.5, 0.92);
+            },
+            drawLetterbox: (top, bottom, alpha = 230) => {
+                const topHeight = Math.max(0, Math.min(0.5, top));
+                const bottomHeight = Math.max(0, Math.min(0.5, bottom));
+                this.platform.drawRect(0.5, topHeight / 2, 1.0, topHeight, 0, 0, 0, alpha);
+                this.platform.drawRect(0.5, 1 - bottomHeight / 2, 1.0, bottomHeight, 0, 0, 0, alpha);
+            },
+        };
+    }
+    async resolveShotNodes(shot, anchors) {
+        if (shot.path && shot.path.length > 0) {
+            const nodes = [];
+            for (const pathNode of shot.path) {
+                nodes.push(await this.resolveCameraNode(pathNode, anchors));
+            }
+            return nodes;
+        }
+        if (shot.from && shot.to) {
+            return [
+                await this.resolveCameraNode(shot.from, anchors),
+                await this.resolveCameraNode(shot.to, anchors),
+            ];
+        }
+        if (shot.from) {
+            return [await this.resolveCameraNode(shot.from, anchors)];
+        }
+        return [];
+    }
+    async resolveCameraNode(node, anchors) {
+        const position = await this.resolvePosition(node, anchors);
+        return {
+            position,
+            rotation: node.rotation,
+            fov: node.fov,
+        };
+    }
+    async resolveLookAtTarget(input, anchors, normalized) {
+        if (!Array.isArray(input)) {
+            return this.resolvePosition(input, anchors);
+        }
+        if (input.length === 0) {
+            return { x: 0, y: 0, z: 0 };
+        }
+        if (input.length === 1) {
+            return this.resolvePosition(input[0], anchors);
+        }
+        const positions = [];
+        for (const target of input) {
+            positions.push(await this.resolvePosition(target, anchors));
+        }
+        return this.samplePosition(positions, normalized);
+    }
+    async resolvePosition(input, anchors) {
+        switch (input.type) {
+            case 'coords':
+                return { x: input.x, y: input.y, z: input.z };
+            case 'entity': {
+                const { x, y, z } = this.platform.getEntityCoords(input.entity);
+                return {
+                    x: x + (input.offset?.x ?? 0),
+                    y: y + (input.offset?.y ?? 0),
+                    z: z + (input.offset?.z ?? 0),
+                };
+            }
+            case 'entityBone': {
+                const { x, y, z } = this.platform.getWorldPositionOfEntityBone(input.entity, input.bone);
+                return {
+                    x: x + (input.offset?.x ?? 0),
+                    y: y + (input.offset?.y ?? 0),
+                    z: z + (input.offset?.z ?? 0),
+                };
+            }
+            case 'anchor': {
+                const anchor = anchors[input.name];
+                if (!anchor) {
+                    throw new Error(`Unknown cinematic anchor "${input.name}"`);
+                }
+                return {
+                    x: anchor.x + (input.offset?.x ?? 0),
+                    y: anchor.y + (input.offset?.y ?? 0),
+                    z: anchor.z + (input.offset?.z ?? 0),
+                };
+            }
+            case 'resolver':
+                return input.resolve();
+        }
+    }
+    validateDefinition(definition) {
+        const issues = [];
+        if (!Array.isArray(definition.shots) || definition.shots.length === 0) {
+            issues.push('`shots` must contain at least one shot.');
+        }
+        const seenShotIds = new Set();
+        for (let index = 0; index < definition.shots.length; index += 1) {
+            const shot = definition.shots[index];
+            const label = `Shot #${index + 1}`;
+            if (shot.id) {
+                if (seenShotIds.has(shot.id)) {
+                    issues.push(`${label} has duplicated id "${shot.id}".`);
+                }
+                seenShotIds.add(shot.id);
+            }
+            const isWait = typeof shot.waitMs === 'number';
+            const hasMotion = typeof shot.durationMs === 'number' || !!shot.from || !!shot.to || !!shot.path;
+            if (!isWait && !hasMotion) {
+                issues.push(`${label} must define either waitMs or camera motion data.`);
+            }
+            if (isWait) {
+                if (!Number.isFinite(shot.waitMs) || (shot.waitMs ?? 0) <= 0) {
+                    issues.push(`${label} waitMs must be a positive number.`);
+                }
+                if (shot.from || shot.to || shot.path || shot.durationMs) {
+                    issues.push(`${label} cannot mix waitMs with from/to/path/durationMs.`);
+                }
+            }
+            else {
+                if (!Number.isFinite(shot.durationMs) || (shot.durationMs ?? 0) <= 0) {
+                    issues.push(`${label} durationMs must be a positive number for motion shots.`);
+                }
+                const hasPath = !!shot.path && shot.path.length > 0;
+                const hasFromTo = !!shot.from || !!shot.to;
+                if (!hasPath && !hasFromTo) {
+                    issues.push(`${label} must define path or from/to.`);
+                }
+                if (shot.path && shot.path.length === 0) {
+                    issues.push(`${label} path cannot be empty.`);
+                }
+                if (shot.path && hasFromTo) {
+                    issues.push(`${label} cannot define both path and from/to.`);
+                }
+            }
+            if (shot.lookAt && Array.isArray(shot.lookAt) && shot.lookAt.length === 0) {
+                issues.push(`${label} lookAt array cannot be empty.`);
+            }
+            this.validatePositionNode(shot.from, definition.anchors ?? {}, `${label}.from`, issues);
+            this.validatePositionNode(shot.to, definition.anchors ?? {}, `${label}.to`, issues);
+            for (let pathIndex = 0; pathIndex < (shot.path?.length ?? 0); pathIndex += 1) {
+                this.validatePositionNode(shot.path?.[pathIndex], definition.anchors ?? {}, `${label}.path[${pathIndex}]`, issues);
+            }
+            const lookTargets = shot.lookAt
+                ? Array.isArray(shot.lookAt)
+                    ? shot.lookAt
+                    : [shot.lookAt]
+                : [];
+            for (let lookIndex = 0; lookIndex < lookTargets.length; lookIndex += 1) {
+                this.validatePositionNode(lookTargets[lookIndex], definition.anchors ?? {}, `${label}.lookAt[${lookIndex}]`, issues);
+            }
+            this.validateEffects(shot.effects ?? [], `${label}.effects`, issues);
+        }
+        const presets = definition.effectPresets ?? [];
+        for (const preset of presets) {
+            if (!this.effects.hasPreset(preset)) {
+                issues.push(`Unknown effect preset "${preset}".`);
+            }
+        }
+        this.validateEffects(definition.effects ?? [], 'effects', issues);
+        if (issues.length > 0) {
+            throw new CinematicValidationError(issues);
+        }
+    }
+    validateEffects(effects, scope, issues) {
+        for (let index = 0; index < effects.length; index += 1) {
+            const effect = effects[index];
+            const label = `${scope}[${index}]`;
+            if (!effect.id || typeof effect.id !== 'string') {
+                issues.push(`${label}.id must be a non-empty string.`);
+                continue;
+            }
+            if (!this.effects.has(effect.id)) {
+                issues.push(`${label} references unknown effect "${effect.id}".`);
+            }
+            if (effect.fromMs !== undefined && (!Number.isFinite(effect.fromMs) || effect.fromMs < 0)) {
+                issues.push(`${label}.fromMs must be a number >= 0.`);
+            }
+            if (effect.toMs !== undefined && (!Number.isFinite(effect.toMs) || effect.toMs < 0)) {
+                issues.push(`${label}.toMs must be a number >= 0.`);
+            }
+            if (effect.fromMs !== undefined &&
+                effect.toMs !== undefined &&
+                Number.isFinite(effect.fromMs) &&
+                Number.isFinite(effect.toMs) &&
+                effect.toMs < effect.fromMs) {
+                issues.push(`${label}.toMs must be greater than or equal to fromMs.`);
+            }
+        }
+    }
+    validatePositionNode(node, anchors, scope, issues) {
+        if (!node)
+            return;
+        if (node.type === 'anchor' && !anchors[node.name]) {
+            issues.push(`${scope} references unknown anchor "${node.name}".`);
+        }
+        if (node.type === 'coords') {
+            if (!Number.isFinite(node.x) || !Number.isFinite(node.y) || !Number.isFinite(node.z)) {
+                issues.push(`${scope} coords must be finite numbers.`);
+            }
+        }
+        if (node.type === 'entity' || node.type === 'entityBone') {
+            if (!Number.isFinite(node.entity) || node.entity < 0) {
+                issues.push(`${scope}.entity must be a valid entity handle number.`);
+            }
+        }
+        if (node.type === 'entityBone') {
+            if (!Number.isFinite(node.bone)) {
+                issues.push(`${scope}.bone must be a finite number.`);
+            }
+        }
+        if (node.type === 'resolver' && typeof node.resolve !== 'function') {
+            issues.push(`${scope}.resolve must be a function.`);
+        }
+    }
+    sampleNode(nodes, normalized) {
+        if (nodes.length === 1) {
+            return nodes[0];
+        }
+        const segmentCount = nodes.length - 1;
+        const scaled = Math.min(Math.max(normalized, 0), 1) * segmentCount;
+        const index = Math.min(Math.floor(scaled), segmentCount - 1);
+        const localT = scaled - index;
+        const current = nodes[index];
+        const next = nodes[index + 1];
+        return {
+            position: {
+                x: this.lerp(current.position.x, next.position.x, localT),
+                y: this.lerp(current.position.y, next.position.y, localT),
+                z: this.lerp(current.position.z, next.position.z, localT),
+            },
+            rotation: this.interpolateRotation(current.rotation, next.rotation, localT),
+            fov: this.interpolateFov(current.fov, next.fov, localT),
+        };
+    }
+    samplePosition(positions, normalized) {
+        if (positions.length === 1) {
+            return positions[0];
+        }
+        const segmentCount = positions.length - 1;
+        const scaled = Math.min(Math.max(normalized, 0), 1) * segmentCount;
+        const index = Math.min(Math.floor(scaled), segmentCount - 1);
+        const localT = scaled - index;
+        const current = positions[index];
+        const next = positions[index + 1];
+        return {
+            x: this.lerp(current.x, next.x, localT),
+            y: this.lerp(current.y, next.y, localT),
+            z: this.lerp(current.z, next.z, localT),
+        };
+    }
+    interpolateRotation(current, next, t) {
+        if (!current && !next) {
+            return undefined;
+        }
+        const from = current ?? next;
+        const to = next ?? current;
+        if (!from || !to) {
+            return undefined;
+        }
+        return {
+            x: this.lerp(from.x, to.x, t),
+            y: this.lerp(from.y, to.y, t),
+            z: this.lerp(from.z, to.z, t),
+        };
+    }
+    interpolateFov(current, next, t) {
+        if (typeof current !== 'number' && typeof next !== 'number') {
+            return undefined;
+        }
+        const from = typeof current === 'number' ? current : next;
+        const to = typeof next === 'number' ? next : current;
+        if (typeof from !== 'number' || typeof to !== 'number') {
+            return undefined;
+        }
+        return this.lerp(from, to, t);
+    }
+    lerp(a, b, t) {
+        return a + (b - a) * t;
+    }
+    applyEase(t, ease) {
+        const clamped = Math.min(Math.max(t, 0), 1);
+        switch (ease) {
+            case 'inSine':
+                return 1 - Math.cos((clamped * Math.PI) / 2);
+            case 'outSine':
+                return Math.sin((clamped * Math.PI) / 2);
+            case 'inOutSine':
+                return -(Math.cos(Math.PI * clamped) - 1) / 2;
+            case 'inCubic':
+                return clamped ** 3;
+            case 'outCubic':
+                return 1 - (1 - clamped) ** 3;
+            case 'inOutCubic':
+                return clamped < 0.5 ? 4 * clamped ** 3 : 1 - (-2 * clamped + 2) ** 3 / 2;
+            default:
+                return clamped;
+        }
+    }
+};
+Cinematic = __decorate([
+    injectable(),
+    __param(2, inject(IClientPlatformBridge)),
+    __param(3, inject(IClientRuntimeBridge)),
+    __metadata("design:paramtypes", [Camera,
+        CameraEffectsRegistry,
+        IClientPlatformBridge,
+        IClientRuntimeBridge])
+], Cinematic);
+export { Cinematic };