@dice-o-rolla/dice-engine 0.2.0 → 0.3.1

package/README.md

@@ -34,6 +34,38 @@ await engine.initialize();
 
 The main entry point depends on domain contracts rather than concrete Rapier or Three.js types.
 
+## Deterministic simulation and replay
+
+`simulate()` runs the configured physics adapter with a per-call seeded random source and returns a
+JSON-serializable `PhysicalRollTrace`. It does not render or emit the ordinary roll lifecycle events.
+Set `captureFrames: true` when the trace will be animated; otherwise the trace contains only its
+terminal frame.
+
+```ts
+const trace = await engine.simulate('2d20kh1', {
+  seed: 2026,
+  captureFrames: true,
+  frameIntervalSteps: 2,
+});
+
+await engine.replay(trace, {
+  theme: { material: 'matte', roughness: 0.85 },
+  signal: abortController.signal,
+});
+```
+
+`replay()` consumes the captured transforms without stepping physics. Its optional theme is applied
+through the normal engine theme state, and the terminal dice remain rendered until the next roll,
+replay, `clear()`, or `destroy()`. Simulation and replay require an idle engine because the facade
+owns one physics world, renderer, and frame scheduler. Replay cancellation rejects with
+`RollCancelledError`.
+
+Traces include producer and physics profile metadata, initial throw conditions, definition
+fingerprints, collision/impact events, and the immutable logical result. Replay validates registered
+definitions, final orientation-derived faces, and the aggregate total before rendering. Default
+trace limits are 1,200 frames, 60,000 die samples, and 20,000 events; customize them through
+`DiceEngineOptions.traceLimits`. `TraceLimitExceededError` identifies the rejected dimension.
+
 ## Visual presets and optional effects
 
 `registerVisualPreset()` associates a logical die with a validated physical geometry, scale, face
@@ -65,6 +97,10 @@ Keep/drop rolls retain every physical die in `result.dice` and expose the select
 Selection is applied before scoring, followed by integer modifiers. Paired `d%`, `d100`, and `d66`
 terms currently reject keep/drop and score operations.
 
+Engine-produced dice also contain immutable `provenance`: stable term, logical-die, and physical-die
+coordinates plus the settled face, inclusion state, and contribution. Consumers can explain a
+total without reparsing notation or depending on renderer state.
+
 Default resource limits reject oversized notation, more than 50 logical or physical dice, and more
 than eight pending rolls. Consumers may lower or explicitly raise these limits through
 `DiceEngineOptions.limits` after testing their target devices.
@@ -78,6 +114,8 @@ and final. See the canonical
 [lifecycle and runtime contract](https://github.com/creepiest-space/dice-o-rolla/blob/main/docs/engine.md).
 Consumers upgrading from `0.1` should also review the
 [0.2 migration notes](https://github.com/creepiest-space/dice-o-rolla/blob/main/docs/migration-0.2.md).
+Consumers upgrading from `0.2` should review the
+[0.3 migration notes](https://github.com/creepiest-space/dice-o-rolla/blob/main/docs/migration-0.3.md).
 
 ## License
 

package/dist/dice-engine.d.ts

@@ -1,13 +1,15 @@
 import { TypedEventEmitter } from '@dice-o-rolla/dice-core';
 import type { RollResult } from '@dice-o-rolla/dice-core';
 import { type RendererViewport, type VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
-import type { DiceEngineEvents, DiceEngineFacade, DiceEngineOptions, DiceTheme, RegisterEngineVisualPresetOptions, RollOptions } from './types.js';
+import type { DiceEngineEvents, DiceEngineFacade, DiceEngineOptions, DiceTheme, PhysicalRollTrace, RegisterEngineVisualPresetOptions, ReplayOptions, RollOptions, SimulateOptions } from './types.js';
 import { type PhysicalDieType } from './visual-presets.js';
 export declare class DiceEngine extends TypedEventEmitter<DiceEngineEvents> implements DiceEngineFacade {
     #private;
     constructor(options: DiceEngineOptions);
     initialize(): Promise<void>;
     roll(notation: string, options?: RollOptions): Promise<RollResult>;
+    simulate(notation: string, options: SimulateOptions): Promise<PhysicalRollTrace>;
+    replay(trace: PhysicalRollTrace, options?: ReplayOptions): Promise<void>;
     cancel(sessionId?: string): boolean;
     clear(): void;
     resize(viewport: RendererViewport): void;

package/dist/dice-engine.js

@@ -1,9 +1,10 @@
-import { createRollResult, getNotationModifier, isDieType, mathRandomSource, parseNotation, TypedEventEmitter, } from '@dice-o-rolla/dice-core';
+import { createRollResult, getNotationModifier, isDieType, mathRandomSource, parseNotation, SeededRandomSource, TypedEventEmitter, } from '@dice-o-rolla/dice-core';
 import { getDieGeometry, hasDieGeometry, resolveFace } from '@dice-o-rolla/dice-geometry';
 import { SettlingDetector, ThrowGenerator } from '@dice-o-rolla/dice-physics';
 import { createVisualPresetDescriptor, VisualPresetRegistry, } from '@dice-o-rolla/dice-renderer';
 import { DEFAULT_THEME, defaultFrameScheduler } from './defaults.js';
-import { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, } from './errors.js';
+import { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, TraceLimitExceededError, } from './errors.js';
+import { DICE_ENGINE_VERSION } from './version.js';
 import { getStandardVisualPresetId, isPhysicalDieType, PHYSICAL_DIE_TYPES, STANDARD_VISUAL_PRESETS, } from './visual-presets.js';
 const DEFAULT_SETTLING = {
     linearVelocityThreshold: 0.08,
@@ -48,6 +49,11 @@ const DEFAULT_LIMITS = Object.freeze({
     maxQueuedRolls: 8,
 });
 const DEFAULT_COLLISION_EVENTS = Object.freeze({ enabled: false, maxEventsPerFrame: 32 });
+const DEFAULT_TRACE_LIMITS = Object.freeze({
+    maxFrames: 1_200,
+    maxSamples: 60_000,
+    maxEvents: 20_000,
+});
 const D100_TENS_LABELS = Object.freeze({
     1: 10,
     2: 20,
@@ -89,6 +95,82 @@ function mergeFaceLabels(preset, roll) {
         return preset;
     return Object.freeze({ ...preset, ...roll });
 }
+function snapshotFrame(dice, elapsedSeconds) {
+    return Object.freeze({
+        elapsedSeconds,
+        dice: Object.freeze(dice.map((die) => Object.freeze({
+            id: die.id,
+            position: Object.freeze({ ...die.current.position }),
+            quaternion: Object.freeze({ ...die.current.quaternion }),
+        }))),
+    });
+}
+function getFrameDie(frame, id) {
+    const die = frame.dice.find((candidate) => candidate.id === id);
+    if (die === undefined)
+        throw new TypeError(`Trace frame is missing die "${id}"`);
+    return die;
+}
+function freezeVector(value) {
+    return Object.freeze({ ...value });
+}
+function freezeThrowParameters(parameters) {
+    return Object.freeze({
+        position: freezeVector(parameters.position),
+        quaternion: freezeVector(parameters.quaternion),
+        impulse: freezeVector(parameters.impulse),
+        torqueImpulse: freezeVector(parameters.torqueImpulse),
+    });
+}
+function cloneRange(range) {
+    return Object.freeze({ ...range });
+}
+function cloneVectorRange(range) {
+    return Object.freeze({ x: cloneRange(range.x), y: cloneRange(range.y), z: cloneRange(range.z) });
+}
+function definitionFingerprint(geometry, preset, effectiveFaceLabels) {
+    const serialized = JSON.stringify({
+        geometry: {
+            id: geometry.id,
+            vertices: geometry.vertices,
+            faces: geometry.faces,
+            faceDefinitions: geometry.faceDefinitions,
+        },
+        preset: {
+            id: preset.id,
+            dieType: preset.dieType,
+            geometryId: preset.geometryId,
+            scale: preset.scale ?? 1,
+            faceLabels: preset.faceLabels ?? null,
+            effectiveFaceLabels: effectiveFaceLabels ?? null,
+            valueMap: preset.valueMap ?? null,
+            skinId: preset.skinId ?? null,
+            soundPackId: preset.soundPackId ?? null,
+        },
+    });
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < serialized.length; index += 1) {
+        hash ^= serialized.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fnv1a32:${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+function snapshotTraceProfile(options) {
+    return Object.freeze({
+        fixedStepSeconds: options.fixedStepSeconds,
+        settling: Object.freeze({ ...options.settling }),
+        throw: Object.freeze({
+            position: cloneVectorRange(options.throw.position),
+            impulse: cloneVectorRange(options.throw.impulse),
+            torqueImpulse: cloneVectorRange(options.throw.torqueImpulse),
+        }),
+        tray: Object.freeze({
+            ...options.tray,
+            material: Object.freeze({ ...options.tray.material }),
+        }),
+        diceMaterial: Object.freeze({ ...options.diceMaterial }),
+    });
+}
 function assertPositive(value, name) {
     if (!Number.isFinite(value) || value <= 0) {
         throw new RangeError(`${name} must be a positive finite number`);
@@ -107,10 +189,12 @@ export class DiceEngine extends TypedEventEmitter {
     #fixedStepSeconds;
     #maxFrameDeltaSeconds;
     #settling;
+    #throwOptions;
     #throwGenerator;
     #tray;
     #diceMaterial;
     #limits;
+    #traceLimits;
     #collisionEvents;
     #visualPresets = new VisualPresetRegistry(STANDARD_VISUAL_PRESETS);
     #visualPresetIds = new Map();
@@ -118,10 +202,12 @@ export class DiceEngine extends TypedEventEmitter {
     #displayedDieIds = new Set();
     #dieEvents = new Map();
     #active;
+    #replay;
     #frameToken;
     #lastFrameMs = 0;
     #accumulatorSeconds = 0;
     #nextSessionId = 1;
+    #nextSimulationId = 1;
     #initialization;
     #initialized = false;
     #destroyed = false;
@@ -137,10 +223,12 @@ export class DiceEngine extends TypedEventEmitter {
         assertPositive(this.#fixedStepSeconds, 'fixedStepSeconds');
         assertPositive(this.#maxFrameDeltaSeconds, 'maxFrameDeltaSeconds');
         this.#settling = options.settling ?? DEFAULT_SETTLING;
-        this.#throwGenerator = new ThrowGenerator(options.random ?? mathRandomSource, options.throw ?? DEFAULT_THROW);
+        this.#throwOptions = options.throw ?? DEFAULT_THROW;
+        this.#throwGenerator = new ThrowGenerator(options.random ?? mathRandomSource, this.#throwOptions);
         this.#tray = options.tray ?? DEFAULT_TRAY;
         this.#diceMaterial = options.diceMaterial ?? DEFAULT_DICE_MATERIAL;
         this.#limits = Object.freeze({ ...DEFAULT_LIMITS, ...options.limits });
+        this.#traceLimits = Object.freeze({ ...DEFAULT_TRACE_LIMITS, ...options.traceLimits });
         this.#collisionEvents = Object.freeze({
             ...DEFAULT_COLLISION_EVENTS,
             ...options.collisionEvents,
@@ -154,6 +242,13 @@ export class DiceEngine extends TypedEventEmitter {
         ]) {
             assertPositiveSafeInteger(value, `limits.${name}`);
         }
+        for (const [name, value] of [
+            ['maxFrames', this.#traceLimits.maxFrames],
+            ['maxSamples', this.#traceLimits.maxSamples],
+            ['maxEvents', this.#traceLimits.maxEvents],
+        ]) {
+            assertPositiveSafeInteger(value, `traceLimits.${name}`);
+        }
         for (const type of PHYSICAL_DIE_TYPES) {
             this.#visualPresetIds.set(type, getStandardVisualPresetId(type));
         }
@@ -185,6 +280,8 @@ export class DiceEngine extends TypedEventEmitter {
     roll(notation, options = {}) {
         try {
             this.#assertReady();
+            if (this.#replay !== undefined)
+                throw new Error('Cannot roll while a trace replay is active');
             if ((options.mode ?? 'queue') !== 'queue') {
                 throw new RangeError('Only queue roll mode is currently supported');
             }
@@ -209,8 +306,234 @@ export class DiceEngine extends TypedEventEmitter {
             return Promise.reject(error);
         }
     }
+    async simulate(notation, options) {
+        this.#assertReady();
+        this.#assertExclusiveOperationAvailable('simulate');
+        if (notation.length > this.#limits.maxNotationLength) {
+            throw new RollLimitExceededError('notation-length', this.#limits.maxNotationLength, notation.length);
+        }
+        const parsed = parseNotation(notation);
+        this.#assertSupportedAndWithinLimits(parsed);
+        const frameIntervalSteps = options.frameIntervalSteps ?? 1;
+        assertPositiveSafeInteger(frameIntervalSteps, 'frameIntervalSteps');
+        const random = new SeededRandomSource(options.seed);
+        const throwGenerator = new ThrowGenerator(random, this.#throwOptions);
+        const simulationId = `simulation-${this.#nextSimulationId++}`;
+        this.#removeDisplayedDice();
+        this.#physics.clear();
+        const dice = [];
+        let trace;
+        let failure;
+        try {
+            this.#physics.setCollisionEventsEnabled(true);
+            this.#physics.drainCollisionEvents();
+            this.#physics.drainImpactEvents();
+            dice.push(...this.#createSimulationDice(parsed, simulationId, throwGenerator));
+            const captureFrames = options.captureFrames === true;
+            const frames = [];
+            const events = [];
+            if (captureFrames)
+                this.#appendTraceFrame(frames, dice, 0);
+            let elapsedSeconds = 0;
+            let stepIndex = 0;
+            while (dice.some((die) => die.result === undefined)) {
+                for (const die of dice)
+                    die.previous = die.current;
+                this.#physics.step(this.#fixedStepSeconds);
+                stepIndex += 1;
+                elapsedSeconds += this.#fixedStepSeconds;
+                for (const collision of this.#physics.drainCollisionEvents()) {
+                    this.#appendTraceEvent(events, {
+                        kind: 'collision',
+                        elapsedSeconds,
+                        dieId: collision.dieId,
+                        ...(collision.otherDieId === undefined ? {} : { otherDieId: collision.otherDieId }),
+                        started: collision.started,
+                    });
+                }
+                for (const impact of this.#physics.drainImpactEvents()) {
+                    this.#appendTraceEvent(events, {
+                        kind: 'impact',
+                        elapsedSeconds,
+                        dieId: impact.dieId,
+                        ...(impact.otherDieId === undefined ? {} : { otherDieId: impact.otherDieId }),
+                        force: impact.force,
+                    });
+                }
+                for (const die of dice) {
+                    die.current = die.body.getState();
+                    if (die.result !== undefined)
+                        continue;
+                    const settling = die.detector.update(die.current, this.#fixedStepSeconds * 1_000);
+                    if (settling === 'timed-out')
+                        throw new RollTimeoutError(simulationId);
+                    if (settling === 'settled') {
+                        const geometry = getDieGeometry(die.geometryType);
+                        die.result = this.#createDieResult(die, resolveFace(geometry, die.current.quaternion));
+                    }
+                }
+                const allSettled = dice.every((die) => die.result !== undefined);
+                if (captureFrames && (stepIndex % frameIntervalSteps === 0 || allSettled)) {
+                    if (frames.at(-1)?.elapsedSeconds !== elapsedSeconds) {
+                        this.#appendTraceFrame(frames, dice, elapsedSeconds);
+                    }
+                }
+            }
+            if (!captureFrames)
+                this.#appendTraceFrame(frames, dice, elapsedSeconds);
+            const result = createRollResult({
+                id: simulationId,
+                notation,
+                dice: this.#applyRollRules(dice),
+                modifier: getNotationModifier(parsed),
+                startedAt: 0,
+                completedAt: elapsedSeconds * 1_000,
+            });
+            trace = Object.freeze({
+                version: 1,
+                producer: Object.freeze({
+                    name: '@dice-o-rolla/dice-engine',
+                    version: DICE_ENGINE_VERSION,
+                }),
+                notation,
+                seed: options.seed,
+                fixedStepSeconds: this.#fixedStepSeconds,
+                frameIntervalSteps,
+                durationSeconds: elapsedSeconds,
+                profile: snapshotTraceProfile({
+                    fixedStepSeconds: this.#fixedStepSeconds,
+                    settling: this.#settling,
+                    throw: this.#throwOptions,
+                    tray: this.#tray,
+                    diceMaterial: this.#diceMaterial,
+                }),
+                dice: Object.freeze(dice.map((die) => Object.freeze({
+                    id: die.id,
+                    type: die.type,
+                    presetId: die.preset.id,
+                    geometryId: die.geometryType,
+                    definitionFingerprint: definitionFingerprint(getDieGeometry(die.geometryType), die.preset, die.faceLabels),
+                    scale: die.preset.scale ?? 1,
+                    ...(die.faceLabels === undefined
+                        ? {}
+                        : { faceLabels: Object.freeze({ ...die.faceLabels }) }),
+                    initial: freezeThrowParameters(die.initial),
+                }))),
+                frames: Object.freeze(frames),
+                events: Object.freeze(events),
+                result,
+            });
+        }
+        catch (error) {
+            failure = error;
+        }
+        const cleanupErrors = this.#removeSimulationDice(dice);
+        try {
+            this.#physics.setCollisionEventsEnabled(this.#collisionEvents.enabled);
+        }
+        catch (error) {
+            cleanupErrors.push(error);
+        }
+        if (failure !== undefined) {
+            if (cleanupErrors.length === 0)
+                throw failure;
+            throw new AggregateError([failure, ...cleanupErrors], `Simulation ${simulationId} failed`, {
+                cause: failure,
+            });
+        }
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError(cleanupErrors, `Failed to clean up ${simulationId}`);
+        }
+        if (trace === undefined)
+            throw new Error(`Simulation ${simulationId} produced no trace`);
+        this.#assertValidTrace(trace);
+        return trace;
+    }
+    replay(trace, options = {}) {
+        try {
+            this.#assertReady();
+            this.#assertExclusiveOperationAvailable('replay');
+            this.#assertValidTrace(trace);
+            if (options.signal?.aborted === true) {
+                return Promise.reject(new RollCancelledError(trace.result.id));
+            }
+            this.#removeDisplayedDice();
+            if (options.theme !== undefined)
+                this.setTheme(options.theme);
+            const firstFrame = trace.frames[0];
+            const createdIds = [];
+            try {
+                for (const die of trace.dice) {
+                    const frameDie = getFrameDie(firstFrame, die.id);
+                    this.#renderer.createDie({
+                        id: die.id,
+                        presetId: die.presetId,
+                        geometryId: die.geometryId,
+                        scale: die.scale,
+                        ...(die.faceLabels === undefined ? {} : { faceLabels: die.faceLabels }),
+                        previous: frameDie,
+                        current: frameDie,
+                    });
+                    createdIds.push(die.id);
+                    const preset = this.#visualPresets.get(die.presetId);
+                    const event = Object.freeze({
+                        sessionId: trace.result.id,
+                        dieId: die.id,
+                        dieType: die.type,
+                        presetId: die.presetId,
+                        ...(preset.skinId === undefined ? {} : { skinId: preset.skinId }),
+                        ...(preset.soundPackId === undefined ? {} : { soundPackId: preset.soundPackId }),
+                    });
+                    this.#dieEvents.set(die.id, event);
+                    this.emit('die:spawn', event);
+                }
+            }
+            catch (error) {
+                for (const id of createdIds) {
+                    this.#dieEvents.delete(id);
+                    this.#renderer.removeDie(id);
+                }
+                throw error;
+            }
+            let resolve;
+            let reject;
+            const promise = new Promise((resolvePromise, rejectPromise) => {
+                resolve = resolvePromise;
+                reject = rejectPromise;
+            });
+            const abortListener = options.signal === undefined ? undefined : () => this.#cancelReplay();
+            if (abortListener !== undefined) {
+                options.signal?.addEventListener('abort', abortListener, { once: true });
+            }
+            const replay = {
+                trace,
+                resolve,
+                reject,
+                createdIds,
+                nextEventIndex: 0,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+                ...(abortListener === undefined ? {} : { abortListener }),
+            };
+            this.#replay = replay;
+            try {
+                this.#scheduleReplayFrame();
+            }
+            catch (error) {
+                this.#finishReplay(replay, error);
+            }
+            return promise;
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
     cancel(sessionId) {
         this.#assertAlive();
+        if (this.#replay !== undefined &&
+            (sessionId === undefined || this.#replay.trace.result.id === sessionId)) {
+            this.#cancelReplay();
+            return true;
+        }
         if (this.#active !== undefined &&
             (sessionId === undefined || this.#active.task.session.id === sessionId)) {
             const task = this.#active.task;
@@ -226,6 +549,8 @@ export class DiceEngine extends TypedEventEmitter {
     }
     clear() {
         this.#assertAlive();
+        if (this.#replay !== undefined)
+            this.#cancelReplay();
         this.#frameToken?.cancel();
         this.#frameToken = undefined;
         if (this.#active !== undefined) {
@@ -321,6 +646,8 @@ export class DiceEngine extends TypedEventEmitter {
         this.#destroyed = true;
         this.#frameToken?.cancel();
         this.#frameToken = undefined;
+        if (this.#replay !== undefined)
+            this.#cancelReplay();
         if (this.#active !== undefined) {
             const task = this.#active.task;
             this.#active = undefined;
@@ -404,7 +731,7 @@ export class DiceEngine extends TypedEventEmitter {
     #createDice(task) {
         const dice = [];
         let index = 0;
-        const specs = this.#createPhysicalSpecs(task);
+        const specs = this.#createPhysicalSpecs(task.parsed, task.session.id);
         const totalDice = specs.length;
         try {
             for (const spec of specs) {
@@ -432,11 +759,15 @@ export class DiceEngine extends TypedEventEmitter {
                     type: spec.type,
                     geometryType: spec.geometryType,
                     preset: spec.preset,
+                    termId: spec.termId,
                     expressionIndex: spec.expressionIndex,
+                    dieIndex: spec.dieIndex,
+                    physicalIndex: spec.physicalIndex,
                     ...(spec.selection === undefined ? {} : { selection: spec.selection }),
                     ...(spec.scoreRules === undefined ? {} : { scoreRules: spec.scoreRules }),
                     ...(spec.component === undefined ? {} : { component: spec.component }),
                     ...(faceLabels === undefined ? {} : { faceLabels }),
+                    initial: generated,
                     body,
                     detector: new SettlingDetector(this.#settling),
                     previous: state,
@@ -469,12 +800,101 @@ export class DiceEngine extends TypedEventEmitter {
             });
         }
     }
-    #createPhysicalSpecs(task) {
+    #createSimulationDice(parsed, simulationId, throwGenerator) {
+        const dice = [];
+        const specs = this.#createPhysicalSpecs(parsed, simulationId);
+        const totalDice = specs.length;
+        try {
+            for (const [index, spec] of specs.entries()) {
+                const geometry = getDieGeometry(spec.geometryType);
+                const faceLabels = mergeFaceLabels(spec.preset.faceLabels, spec.faceLabels);
+                const id = `${simulationId}:die-${index}`;
+                const generated = throwGenerator.generate();
+                const position = this.#placeDie(generated.position, index, totalDice);
+                const body = this.#physics.createDie({
+                    id,
+                    type: spec.geometryType,
+                    collider: {
+                        kind: 'convex-hull',
+                        vertices: geometry.vertices.map(([x, y, z]) => ({ x, y, z })),
+                    },
+                    scale: spec.preset.scale ?? 1,
+                    mass: 1,
+                    material: this.#diceMaterial,
+                    position,
+                    quaternion: generated.quaternion,
+                });
+                const state = body.getState();
+                const die = {
+                    id,
+                    type: spec.type,
+                    geometryType: spec.geometryType,
+                    preset: spec.preset,
+                    termId: spec.termId,
+                    expressionIndex: spec.expressionIndex,
+                    dieIndex: spec.dieIndex,
+                    physicalIndex: spec.physicalIndex,
+                    ...(spec.selection === undefined ? {} : { selection: spec.selection }),
+                    ...(spec.scoreRules === undefined ? {} : { scoreRules: spec.scoreRules }),
+                    ...(spec.component === undefined ? {} : { component: spec.component }),
+                    ...(faceLabels === undefined ? {} : { faceLabels }),
+                    initial: generated,
+                    body,
+                    detector: new SettlingDetector(this.#settling),
+                    previous: state,
+                    current: state,
+                };
+                dice.push(die);
+                body.applyImpulse(generated.impulse, generated.torqueImpulse);
+            }
+            return dice;
+        }
+        catch (error) {
+            const cleanupErrors = this.#removeSimulationDice(dice);
+            if (cleanupErrors.length === 0)
+                throw error;
+            throw new AggregateError([error, ...cleanupErrors], 'Failed to create simulation dice', {
+                cause: error,
+            });
+        }
+    }
+    #removeSimulationDice(dice) {
+        const errors = [];
+        for (const die of dice) {
+            try {
+                this.#physics.removeDie(die.id);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        return errors;
+    }
+    #appendTraceFrame(frames, dice, elapsedSeconds) {
+        const frameCount = frames.length + 1;
+        if (frameCount > this.#traceLimits.maxFrames) {
+            throw new TraceLimitExceededError('frames', this.#traceLimits.maxFrames, frameCount);
+        }
+        const sampleCount = frameCount * dice.length;
+        if (sampleCount > this.#traceLimits.maxSamples) {
+            throw new TraceLimitExceededError('samples', this.#traceLimits.maxSamples, sampleCount);
+        }
+        frames.push(snapshotFrame(dice, elapsedSeconds));
+    }
+    #appendTraceEvent(events, event) {
+        const eventCount = events.length + 1;
+        if (eventCount > this.#traceLimits.maxEvents) {
+            throw new TraceLimitExceededError('events', this.#traceLimits.maxEvents, eventCount);
+        }
+        events.push(Object.freeze(event));
+    }
+    #createPhysicalSpecs(parsed, sessionId) {
         const specs = [];
         let groupIndex = 0;
-        for (const [expressionIndex, expression] of task.parsed.expressions.entries()) {
+        for (const [expressionIndex, expression] of parsed.expressions.entries()) {
             if (expression.kind === 'modifier')
                 continue;
+            const termId = `term-${expressionIndex}`;
             if (expression.kind === 'dice') {
                 const type = `d${expression.sides}`;
                 if (!isDieType(type))
@@ -487,7 +907,10 @@ export class DiceEngine extends TypedEventEmitter {
                         type,
                         geometryType: this.#getPresetGeometryType(preset),
                         preset,
+                        termId,
                         expressionIndex,
+                        dieIndex: count,
+                        physicalIndex: specs.length,
                         ...(expression.selection === undefined ? {} : { selection: expression.selection }),
                         ...(expression.score === undefined ? {} : { scoreRules: expression.score }),
                     });
@@ -495,14 +918,17 @@ export class DiceEngine extends TypedEventEmitter {
                 continue;
             }
             for (let count = 0; count < expression.count; count += 1) {
-                const groupId = `${task.session.id}:group-${groupIndex++}`;
+                const groupId = `${sessionId}:group-${groupIndex++}`;
                 if (expression.type === 'd100') {
                     const preset = this.getVisualPreset('d10');
                     specs.push({
                         type: 'd100',
                         geometryType: this.#getPresetGeometryType(preset),
                         preset,
+                        termId,
                         expressionIndex,
+                        dieIndex: count,
+                        physicalIndex: specs.length,
                         component: { groupId, groupType: 'd100', role: 'tens' },
                         faceLabels: D100_TENS_LABELS,
                     });
@@ -510,7 +936,10 @@ export class DiceEngine extends TypedEventEmitter {
                         type: 'd10',
                         geometryType: this.#getPresetGeometryType(preset),
                         preset,
+                        termId,
                         expressionIndex,
+                        dieIndex: count,
+                        physicalIndex: specs.length,
                         component: { groupId, groupType: 'd100', role: 'units' },
                     });
                     continue;
@@ -520,7 +949,10 @@ export class DiceEngine extends TypedEventEmitter {
                     type: 'd6',
                     geometryType: this.#getPresetGeometryType(preset),
                     preset,
+                    termId,
                     expressionIndex,
+                    dieIndex: count,
+                    physicalIndex: specs.length,
                     component: { groupId, groupType: 'd66', role: 'tens' },
                     faceLabels: D66_TENS_LABELS,
                 });
@@ -528,7 +960,10 @@ export class DiceEngine extends TypedEventEmitter {
                     type: 'd6',
                     geometryType: this.#getPresetGeometryType(preset),
                     preset,
+                    termId,
                     expressionIndex,
+                    dieIndex: count,
+                    physicalIndex: specs.length,
                     component: { groupId, groupType: 'd66', role: 'units' },
                 });
             }
@@ -558,6 +993,130 @@ export class DiceEngine extends TypedEventEmitter {
             this.#runFrame(timestampMs);
         });
     }
+    #scheduleReplayFrame() {
+        if (this.#replay === undefined || this.#frameToken !== undefined)
+            return;
+        this.#frameToken = this.#scheduler.request((timestampMs) => {
+            this.#frameToken = undefined;
+            this.#runReplayFrame(timestampMs);
+        });
+    }
+    #runReplayFrame(timestampMs) {
+        const replay = this.#replay;
+        if (replay === undefined)
+            return;
+        try {
+            replay.startMs ??= timestampMs;
+            const elapsedSeconds = Math.max(0, (timestampMs - replay.startMs) / 1_000);
+            const frames = replay.trace.frames;
+            const finalFrame = frames.at(-1);
+            if (frames.length === 1 || elapsedSeconds >= finalFrame.elapsedSeconds) {
+                this.#dispatchReplayEvents(replay, Number.POSITIVE_INFINITY);
+                this.#renderReplayPair(replay.trace, finalFrame, finalFrame, 1);
+                this.#completeReplay(replay);
+                return;
+            }
+            let nextIndex = frames.findIndex((frame) => frame.elapsedSeconds > elapsedSeconds);
+            if (nextIndex < 0)
+                nextIndex = frames.length - 1;
+            const previous = frames[Math.max(0, nextIndex - 1)];
+            const current = frames[nextIndex];
+            const duration = current.elapsedSeconds - previous.elapsedSeconds;
+            const alpha = duration <= 0 ? 1 : (elapsedSeconds - previous.elapsedSeconds) / duration;
+            this.#dispatchReplayEvents(replay, elapsedSeconds);
+            this.#renderReplayPair(replay.trace, previous, current, alpha);
+            this.#scheduleReplayFrame();
+        }
+        catch (error) {
+            this.#finishReplay(replay, error);
+        }
+    }
+    #renderReplayPair(trace, previous, current, alpha) {
+        for (const die of trace.dice) {
+            this.#renderer.updateDie({
+                id: die.id,
+                presetId: die.presetId,
+                geometryId: die.geometryId,
+                scale: die.scale,
+                ...(die.faceLabels === undefined ? {} : { faceLabels: die.faceLabels }),
+                previous: getFrameDie(previous, die.id),
+                current: getFrameDie(current, die.id),
+            });
+        }
+        this.#renderer.render(alpha);
+    }
+    #dispatchReplayEvents(replay, elapsedSeconds) {
+        while (replay.nextEventIndex < replay.trace.events.length) {
+            const traceEvent = replay.trace.events[replay.nextEventIndex];
+            if (traceEvent.elapsedSeconds > elapsedSeconds)
+                return;
+            replay.nextEventIndex += 1;
+            const visual = this.#dieEvents.get(traceEvent.dieId);
+            if (visual === undefined)
+                continue;
+            if (traceEvent.kind === 'collision') {
+                this.emit('die:collision', Object.freeze({
+                    ...visual,
+                    ...(traceEvent.otherDieId === undefined ? {} : { otherDieId: traceEvent.otherDieId }),
+                    started: traceEvent.started,
+                }));
+            }
+            else {
+                this.emit('die:impact', Object.freeze({
+                    ...visual,
+                    ...(traceEvent.otherDieId === undefined ? {} : { otherDieId: traceEvent.otherDieId }),
+                    force: traceEvent.force,
+                }));
+            }
+        }
+    }
+    #completeReplay(replay) {
+        this.#finishReplay(replay);
+    }
+    #cancelReplay() {
+        const replay = this.#replay;
+        if (replay === undefined)
+            return;
+        this.#frameToken?.cancel();
+        this.#frameToken = undefined;
+        this.#finishReplay(replay, new RollCancelledError(replay.trace.result.id));
+    }
+    #finishReplay(replay, error) {
+        if (this.#replay !== replay)
+            return;
+        this.#replay = undefined;
+        if (replay.signal !== undefined && replay.abortListener !== undefined) {
+            replay.signal.removeEventListener('abort', replay.abortListener);
+        }
+        if (error === undefined) {
+            for (const id of replay.createdIds)
+                this.#displayedDieIds.add(id);
+            replay.resolve();
+            return;
+        }
+        const reason = error instanceof RollCancelledError ? 'cancelled' : 'failed';
+        const cleanupErrors = this.#removeDiceByIdSafely(replay.createdIds, reason);
+        if (cleanupErrors.length === 0)
+            replay.reject(error);
+        else {
+            replay.reject(new AggregateError([error, ...cleanupErrors], 'Trace replay failed', { cause: error }));
+        }
+    }
+    #removeDiceByIdSafely(ids, reason) {
+        const errors = [];
+        for (const id of ids) {
+            try {
+                this.#removeDie(id, reason);
+            }
+            catch (error) {
+                if (error instanceof AggregateError)
+                    errors.push(...error.errors);
+                else
+                    errors.push(error);
+            }
+        }
+        return errors;
+    }
     #runFrame(timestampMs) {
         const active = this.#active;
         if (active === undefined)
@@ -631,10 +1190,23 @@ export class DiceEngine extends TypedEventEmitter {
     }
     #createDieResult(die, faceValue) {
         const mappedValue = die.preset.valueMap?.[faceValue] ?? faceValue;
+        const provenance = {
+            termId: die.termId,
+            termIndex: die.expressionIndex,
+            dieIndex: die.dieIndex,
+            physicalIndex: die.physicalIndex,
+            state: 'included',
+            faceValue: mappedValue,
+        };
         if (die.component === undefined) {
             if (die.type === 'd100')
                 throw new Error('A d100 result requires percentile component data');
-            return Object.freeze({ id: die.id, type: die.type, value: mappedValue });
+            return Object.freeze({
+                id: die.id,
+                type: die.type,
+                value: mappedValue,
+                provenance: Object.freeze({ ...provenance, contribution: mappedValue }),
+            });
         }
         const { groupId, groupType, role } = die.component;
         const digit = groupType === 'd100' ? mappedValue % 10 : mappedValue;
@@ -643,6 +1215,7 @@ export class DiceEngine extends TypedEventEmitter {
             type: die.type,
             value: role === 'tens' ? digit * 10 : digit,
             component: Object.freeze({ groupId, groupType, role, faceValue: mappedValue }),
+            provenance: Object.freeze(provenance),
         });
     }
     #completeActive(active) {
@@ -709,10 +1282,18 @@ export class DiceEngine extends TypedEventEmitter {
             if (die.result.component !== undefined) {
                 throw new Error(`Paired die ${die.id} cannot use keep/drop or score rules`);
             }
+            const provenance = die.result.provenance;
+            if (provenance === undefined)
+                throw new Error(`Die ${die.id} has no result provenance`);
             return Object.freeze({
                 ...die.result,
                 ...(included === undefined ? {} : { included }),
                 ...(score === undefined ? {} : { score }),
+                provenance: Object.freeze({
+                    ...provenance,
+                    state: included === false ? 'discarded' : 'included',
+                    contribution: included === false ? 0 : (score ?? die.result.value),
+                }),
             });
         });
     }
@@ -839,6 +1420,197 @@ export class DiceEngine extends TypedEventEmitter {
             task.signal.removeEventListener('abort', task.abortListener);
         }
     }
+    #assertExclusiveOperationAvailable(operation) {
+        if (this.#active !== undefined || this.#queue.length > 0 || this.#replay !== undefined) {
+            throw new Error(`Cannot ${operation} while the engine is busy`);
+        }
+    }
+    #assertValidTrace(trace) {
+        if (trace.version !== 1)
+            throw new TypeError(`Unsupported physical roll trace version`);
+        if (trace.producer.name !== '@dice-o-rolla/dice-engine') {
+            throw new TypeError('Trace producer metadata is invalid');
+        }
+        if (trace.producer.version !== DICE_ENGINE_VERSION) {
+            throw new TypeError(`Trace producer version ${trace.producer.version} is incompatible with ${DICE_ENGINE_VERSION}`);
+        }
+        if (!Number.isSafeInteger(trace.seed))
+            throw new TypeError('Trace seed must be a safe integer');
+        assertPositive(trace.fixedStepSeconds, 'trace.fixedStepSeconds');
+        assertPositiveSafeInteger(trace.frameIntervalSteps, 'trace.frameIntervalSteps');
+        if (trace.profile.fixedStepSeconds !== trace.fixedStepSeconds) {
+            throw new TypeError('Trace profile fixed step does not match its envelope');
+        }
+        const profileValidators = [
+            new SettlingDetector(trace.profile.settling),
+            new ThrowGenerator(new SeededRandomSource(trace.seed), trace.profile.throw),
+        ];
+        void profileValidators;
+        for (const [name, value] of [
+            ['tray.width', trace.profile.tray.width],
+            ['tray.depth', trace.profile.tray.depth],
+            ['tray.wallHeight', trace.profile.tray.wallHeight],
+            ['tray.wallThickness', trace.profile.tray.wallThickness],
+        ]) {
+            assertPositive(value, `trace.profile.${name}`);
+        }
+        for (const [name, value] of [
+            ['tray.material.friction', trace.profile.tray.material.friction],
+            ['tray.material.restitution', trace.profile.tray.material.restitution],
+            ['diceMaterial.friction', trace.profile.diceMaterial.friction],
+            ['diceMaterial.restitution', trace.profile.diceMaterial.restitution],
+            ['diceMaterial.linearDamping', trace.profile.diceMaterial.linearDamping],
+            ['diceMaterial.angularDamping', trace.profile.diceMaterial.angularDamping],
+        ]) {
+            if (!Number.isFinite(value) || value < 0) {
+                throw new RangeError(`trace.profile.${name} must be a non-negative finite number`);
+            }
+        }
+        if (!Number.isFinite(trace.durationSeconds) || trace.durationSeconds < 0) {
+            throw new RangeError('trace.durationSeconds must be a non-negative finite number');
+        }
+        if (trace.frames.length === 0)
+            throw new TypeError('Trace must contain at least one frame');
+        if (trace.dice.length === 0)
+            throw new TypeError('Trace must contain at least one die');
+        if (trace.frames.length > this.#traceLimits.maxFrames) {
+            throw new TraceLimitExceededError('frames', this.#traceLimits.maxFrames, trace.frames.length);
+        }
+        const sampleCount = trace.frames.length * trace.dice.length;
+        if (sampleCount > this.#traceLimits.maxSamples) {
+            throw new TraceLimitExceededError('samples', this.#traceLimits.maxSamples, sampleCount);
+        }
+        if (trace.events.length > this.#traceLimits.maxEvents) {
+            throw new TraceLimitExceededError('events', this.#traceLimits.maxEvents, trace.events.length);
+        }
+        if (trace.result.notation !== trace.notation) {
+            throw new TypeError('Trace result notation does not match its envelope');
+        }
+        const ids = new Set();
+        for (const die of trace.dice) {
+            if (ids.has(die.id))
+                throw new TypeError(`Trace contains duplicate die id "${die.id}"`);
+            ids.add(die.id);
+            if (!isDieType(die.type) || !isDieType(die.geometryId) || !hasDieGeometry(die.geometryId)) {
+                throw new TypeError(`Trace die "${die.id}" has an unsupported type or geometry`);
+            }
+            assertPositive(die.scale, `trace die "${die.id}" scale`);
+            const preset = this.#visualPresets.get(die.presetId);
+            if (preset === undefined) {
+                throw new TypeError(`Trace requires unregistered visual preset "${die.presetId}"`);
+            }
+            if (preset.geometryId !== die.geometryId) {
+                throw new TypeError(`Trace geometry does not match visual preset "${die.presetId}"`);
+            }
+            if ((preset.scale ?? 1) !== die.scale) {
+                throw new TypeError(`Trace scale does not match visual preset "${die.presetId}"`);
+            }
+            const fingerprint = definitionFingerprint(getDieGeometry(die.geometryId), preset, die.faceLabels);
+            if (die.definitionFingerprint !== fingerprint) {
+                throw new TypeError(`Trace definition fingerprint mismatch for "${die.id}"`);
+            }
+            this.#assertFiniteTraceTransform(die.initial, `trace die "${die.id}" initial`);
+            for (const [name, value] of Object.entries({
+                impulseX: die.initial.impulse.x,
+                impulseY: die.initial.impulse.y,
+                impulseZ: die.initial.impulse.z,
+                torqueX: die.initial.torqueImpulse.x,
+                torqueY: die.initial.torqueImpulse.y,
+                torqueZ: die.initial.torqueImpulse.z,
+            })) {
+                if (!Number.isFinite(value))
+                    throw new RangeError(`${name} must be finite`);
+            }
+        }
+        let previousElapsed = -1;
+        for (const frame of trace.frames) {
+            if (!Number.isFinite(frame.elapsedSeconds) ||
+                frame.elapsedSeconds < 0 ||
+                frame.elapsedSeconds < previousElapsed) {
+                throw new RangeError('Trace frame times must be finite, non-negative, and ordered');
+            }
+            previousElapsed = frame.elapsedSeconds;
+            if (frame.dice.length !== trace.dice.length) {
+                throw new TypeError('Every trace frame must contain every die exactly once');
+            }
+            const frameIds = new Set();
+            for (const die of frame.dice) {
+                if (!ids.has(die.id) || frameIds.has(die.id)) {
+                    throw new TypeError(`Trace frame contains an unknown or duplicate die id "${die.id}"`);
+                }
+                frameIds.add(die.id);
+                this.#assertFiniteTraceTransform(die, `trace frame die "${die.id}"`);
+            }
+        }
+        const finalFrame = trace.frames.at(-1);
+        if (Math.abs(finalFrame.elapsedSeconds - trace.durationSeconds) > 1e-9) {
+            throw new RangeError('Trace final frame must match trace duration');
+        }
+        let previousEventTime = -1;
+        for (const event of trace.events) {
+            if (event.kind !== 'collision' && event.kind !== 'impact') {
+                throw new TypeError('Trace event kind is invalid');
+            }
+            if (!ids.has(event.dieId) || (event.otherDieId !== undefined && !ids.has(event.otherDieId))) {
+                throw new TypeError('Trace event references an unknown die');
+            }
+            if (!Number.isFinite(event.elapsedSeconds) ||
+                event.elapsedSeconds < previousEventTime ||
+                event.elapsedSeconds > trace.durationSeconds) {
+                throw new RangeError('Trace event times must be finite, ordered, and inside the trace');
+            }
+            previousEventTime = event.elapsedSeconds;
+            if (event.kind === 'collision' && typeof event.started !== 'boolean') {
+                throw new TypeError('Trace collision state must be boolean');
+            }
+            if (event.kind === 'impact' && (!Number.isFinite(event.force) || event.force < 0)) {
+                throw new RangeError('Trace impact force must be a non-negative finite number');
+            }
+        }
+        const resultDice = new Map(trace.result.dice.map((die) => [die.id, die]));
+        if (resultDice.size !== trace.dice.length || trace.result.dice.length !== trace.dice.length) {
+            throw new TypeError('Trace result must contain every physical die exactly once');
+        }
+        for (const die of trace.dice) {
+            const result = resultDice.get(die.id);
+            if (result === undefined)
+                throw new TypeError(`Trace result is missing die "${die.id}"`);
+            if (!isDieType(die.geometryId)) {
+                throw new TypeError(`Trace die "${die.id}" has an unsupported geometry`);
+            }
+            const preset = this.#visualPresets.get(die.presetId);
+            const resolved = resolveFace(getDieGeometry(die.geometryId), getFrameDie(finalFrame, die.id).quaternion);
+            const mapped = preset.valueMap?.[resolved] ?? resolved;
+            const reportedFace = result.component?.faceValue ?? result.value;
+            if (mapped !== reportedFace) {
+                throw new TypeError(`Trace final orientation does not match result die "${die.id}"`);
+            }
+        }
+        const verifiedResult = createRollResult({
+            id: trace.result.id,
+            notation: trace.result.notation,
+            dice: trace.result.dice,
+            modifier: trace.result.modifier,
+            startedAt: trace.result.startedAt,
+            completedAt: trace.result.completedAt,
+        });
+        if (verifiedResult.total !== trace.result.total) {
+            throw new TypeError('Trace result total does not match its dice and modifier');
+        }
+    }
+    #assertFiniteTraceTransform(transform, description) {
+        if (![
+            transform.position.x,
+            transform.position.y,
+            transform.position.z,
+            transform.quaternion.x,
+            transform.quaternion.y,
+            transform.quaternion.z,
+            transform.quaternion.w,
+        ].every(Number.isFinite)) {
+            throw new RangeError(`${description} transform must contain finite values`);
+        }
+    }
     #assertSupportedAndWithinLimits(parsed) {
         let logicalDice = 0;
         let physicalDice = 0;

package/dist/errors.d.ts

@@ -16,3 +16,10 @@ export declare class RollLimitExceededError extends RangeError {
     readonly actual: number;
     constructor(limit: RollLimit, maximum: number, actual: number);
 }
+export type TraceLimit = 'events' | 'frames' | 'samples';
+export declare class TraceLimitExceededError extends RangeError {
+    readonly limit: TraceLimit;
+    readonly maximum: number;
+    readonly actual: number;
+    constructor(limit: TraceLimit, maximum: number, actual: number);
+}

package/dist/errors.js

@@ -32,3 +32,15 @@ export class RollLimitExceededError extends RangeError {
         this.actual = actual;
     }
 }
+export class TraceLimitExceededError extends RangeError {
+    limit;
+    maximum;
+    actual;
+    constructor(limit, maximum, actual) {
+        super(`Physical roll trace exceeds ${limit} limit of ${maximum} (received ${actual})`);
+        this.name = 'TraceLimitExceededError';
+        this.limit = limit;
+        this.maximum = maximum;
+        this.actual = actual;
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { DiceEngine } from './dice-engine.js';
-export { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, } from './errors.js';
-export type { RollLimit } from './errors.js';
-export type { DiceEngineEvents, DiceEngineFacade, DiceEngineLimits, DiceEngineOptions, DiceCollisionEvent, DiceImpactEvent, DiceCollisionEventOptions, DiceMaterialType, DiceRemovalReason, DiceRemoveEvent, DiceTheme, DiceVisualEvent, FrameScheduler, FrameToken, RegisterEngineVisualPresetOptions, RollOptions, } from './types.js';
+export { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, TraceLimitExceededError, } from './errors.js';
+export type { RollLimit, TraceLimit } from './errors.js';
+export type { DiceEngineEvents, DiceEngineFacade, DiceEngineLimits, DiceEngineOptions, DiceCollisionEvent, DiceImpactEvent, DiceCollisionEventOptions, DiceMaterialType, DiceRemovalReason, DiceRemoveEvent, DiceTheme, DiceTraceLimits, DiceVisualEvent, FrameScheduler, FrameToken, PhysicalRollFrame, PhysicalRollFrameDie, PhysicalRollTrace, PhysicalRollTraceCollisionEvent, PhysicalRollTraceDie, PhysicalRollTraceEvent, PhysicalRollTraceImpactEvent, PhysicalRollTraceProducer, PhysicalRollTraceProfile, RegisterEngineVisualPresetOptions, ReplayOptions, RollOptions, SimulateOptions, } from './types.js';
 export { getStandardVisualPresetId, PHYSICAL_DIE_TYPES, STANDARD_VISUAL_PRESETS, type PhysicalDieType, } from './visual-presets.js';
+export { DICE_ENGINE_VERSION } from './version.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { DiceEngine } from './dice-engine.js';
-export { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, } from './errors.js';
+export { DiceEngineDestroyedError, RollCancelledError, RollLimitExceededError, RollTimeoutError, TraceLimitExceededError, } from './errors.js';
 export { getStandardVisualPresetId, PHYSICAL_DIE_TYPES, STANDARD_VISUAL_PRESETS, } from './visual-presets.js';
+export { DICE_ENGINE_VERSION } from './version.js';

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { DieResult, RandomSource, RollMode, RollResult, RollSession } from '@dice-o-rolla/dice-core';
+import type { DieResult, DieType, QuaternionLike, RandomSource, RollMode, RollResult, RollSession, Vector3Like } from '@dice-o-rolla/dice-core';
 import type { DicePhysicsMaterial, PhysicsWorld, SettlingOptions, ThrowGeneratorOptions, TrayOptions } from '@dice-o-rolla/dice-physics';
 import type { DiceRenderer, RendererTheme, RendererViewport } from '@dice-o-rolla/dice-renderer';
 import type { RegisterVisualPresetOptions, VisualPresetDescriptor } from '@dice-o-rolla/dice-renderer';
@@ -15,6 +15,86 @@ export interface RollOptions {
     readonly mode?: RollMode;
     readonly signal?: AbortSignal;
 }
+export interface SimulateOptions {
+    readonly seed: number;
+    readonly captureFrames?: boolean;
+    /** Capture one frame every N fixed simulation steps. */
+    readonly frameIntervalSteps?: number;
+}
+export interface ReplayOptions {
+    readonly theme?: Partial<DiceTheme>;
+    readonly signal?: AbortSignal;
+}
+export interface PhysicalRollFrameDie {
+    readonly id: string;
+    readonly position: Vector3Like;
+    readonly quaternion: QuaternionLike;
+}
+export interface PhysicalRollFrame {
+    readonly elapsedSeconds: number;
+    readonly dice: readonly PhysicalRollFrameDie[];
+}
+export interface PhysicalRollTraceDie {
+    readonly id: string;
+    readonly type: DieType;
+    readonly presetId: string;
+    readonly geometryId: string;
+    readonly definitionFingerprint: string;
+    readonly scale: number;
+    readonly faceLabels?: Readonly<Record<number, string | number>>;
+    readonly initial: {
+        readonly position: Vector3Like;
+        readonly quaternion: QuaternionLike;
+        readonly impulse: Vector3Like;
+        readonly torqueImpulse: Vector3Like;
+    };
+}
+export interface PhysicalRollTraceCollisionEvent {
+    readonly kind: 'collision';
+    readonly elapsedSeconds: number;
+    readonly dieId: string;
+    readonly otherDieId?: string;
+    readonly started: boolean;
+}
+export interface PhysicalRollTraceImpactEvent {
+    readonly kind: 'impact';
+    readonly elapsedSeconds: number;
+    readonly dieId: string;
+    readonly otherDieId?: string;
+    readonly force: number;
+}
+export type PhysicalRollTraceEvent = PhysicalRollTraceCollisionEvent | PhysicalRollTraceImpactEvent;
+export interface PhysicalRollTraceProfile {
+    readonly fixedStepSeconds: number;
+    readonly settling: SettlingOptions;
+    readonly throw: ThrowGeneratorOptions;
+    readonly tray: TrayOptions;
+    readonly diceMaterial: DicePhysicsMaterial;
+}
+export interface PhysicalRollTraceProducer {
+    readonly name: '@dice-o-rolla/dice-engine';
+    readonly version: string;
+}
+/** JSON-serializable, renderer-neutral output of a deterministic physical simulation. */
+export interface PhysicalRollTrace {
+    readonly version: 1;
+    readonly producer: PhysicalRollTraceProducer;
+    readonly notation: string;
+    readonly seed: number;
+    readonly fixedStepSeconds: number;
+    readonly frameIntervalSteps: number;
+    readonly durationSeconds: number;
+    readonly profile: PhysicalRollTraceProfile;
+    readonly dice: readonly PhysicalRollTraceDie[];
+    readonly frames: readonly PhysicalRollFrame[];
+    readonly events: readonly PhysicalRollTraceEvent[];
+    readonly result: RollResult;
+}
+export interface DiceTraceLimits {
+    readonly maxFrames: number;
+    readonly maxSamples: number;
+    readonly maxEvents: number;
+}
 export interface RegisterEngineVisualPresetOptions extends RegisterVisualPresetOptions {
     readonly makeDefault?: boolean;
 }
@@ -80,6 +160,7 @@ export interface DiceEngineOptions {
     readonly diceMaterial?: DicePhysicsMaterial;
     readonly theme?: Partial<DiceTheme>;
     readonly limits?: Partial<DiceEngineLimits>;
+    readonly traceLimits?: Partial<DiceTraceLimits>;
     readonly visualPresets?: readonly VisualPresetDescriptor[];
     readonly visualPresetIds?: Partial<Readonly<Record<PhysicalDieType, string>>>;
     readonly collisionEvents?: Partial<DiceCollisionEventOptions>;
@@ -87,6 +168,8 @@ export interface DiceEngineOptions {
 export interface DiceEngineFacade {
     initialize(): Promise<void>;
     roll(notation: string, options?: RollOptions): Promise<RollResult>;
+    simulate(notation: string, options: SimulateOptions): Promise<PhysicalRollTrace>;
+    replay(trace: PhysicalRollTrace, options?: ReplayOptions): Promise<void>;
     cancel(sessionId?: string): boolean;
     clear(): void;
     resize(viewport: RendererViewport): void;

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** Runtime package version used in portable trace provenance. */
+export declare const DICE_ENGINE_VERSION = "0.3.1";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** Runtime package version used in portable trace provenance. */
+export const DICE_ENGINE_VERSION = '0.3.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dice-o-rolla/dice-engine",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Framework-neutral physical dice engine with Rapier and Three.js browser adapters.",
   "keywords": [
     "dice",
@@ -47,12 +47,12 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@dice-o-rolla/dice-core": "0.2.0",
-    "@dice-o-rolla/dice-geometry": "0.2.0",
-    "@dice-o-rolla/dice-physics": "0.2.0",
-    "@dice-o-rolla/dice-physics-rapier": "0.2.0",
-    "@dice-o-rolla/dice-renderer": "0.2.0",
-    "@dice-o-rolla/dice-renderer-three": "0.2.0"
+    "@dice-o-rolla/dice-core": "0.3.1",
+    "@dice-o-rolla/dice-geometry": "0.3.1",
+    "@dice-o-rolla/dice-physics": "0.3.1",
+    "@dice-o-rolla/dice-physics-rapier": "0.3.1",
+    "@dice-o-rolla/dice-renderer": "0.3.1",
+    "@dice-o-rolla/dice-renderer-three": "0.3.1"
   },
   "engines": {
     "node": ">=20.0.0"