@kawaijs/runtime 0.1.11 → 0.1.13

package/dist/vm.js

@@ -1,32 +1,91 @@
 import { cloneState, createInitialState } from './state.js';
 import { HistoryManager } from './history.js';
-import { SaveManager } from './save.js';
-import { applySetOperation, evaluateCondition } from './evaluator.js';
+import { computeStoryHash, SaveManager } from './save.js';
+import { applySetOperation, evaluateCondition, interpolateVariables, isSafeKey, resolveSpriteZ } from './evaluator.js';
 export class StoryVM {
+    storyHash;
     story;
     state;
     snapshotStack = [];
     historyManager;
     saveManager;
+    maxSnapshots;
+    maxCallDepth;
+    maxInstructionsPerBurst;
     stateChangeListeners = new Set();
     audioEventListeners = new Set();
+    cameraEventListeners = new Set();
+    errorListeners = new Set();
+    tickListeners = new Set();
+    executionTrace = [];
+    virtualTimeMs = 0;
     isExecuting = false;
-    constructor(story, saveManager) {
+    constructor(story, saveManagerOrOptions) {
         this.story = story;
-        const startLabel = story.meta.startLabel ?? 'start';
+        this.storyHash = computeStoryHash(story);
+        const startLabel = story.meta?.startLabel ?? 'start';
         this.state = createInitialState(startLabel);
         this.historyManager = new HistoryManager();
-        this.saveManager = saveManager ?? new SaveManager();
+        let sm;
+        let maxSnaps = 250;
+        let maxDepth = 100;
+        let maxBurst = 10_000;
+        if (saveManagerOrOptions instanceof SaveManager) {
+            sm = saveManagerOrOptions;
+        }
+        else if (saveManagerOrOptions) {
+            sm = saveManagerOrOptions.saveManager;
+            if (typeof saveManagerOrOptions.maxSnapshots === 'number') {
+                maxSnaps = saveManagerOrOptions.maxSnapshots;
+            }
+            if (typeof saveManagerOrOptions.maxCallDepth === 'number') {
+                maxDepth = saveManagerOrOptions.maxCallDepth;
+            }
+            if (typeof saveManagerOrOptions.maxInstructionsPerBurst === 'number') {
+                maxBurst = saveManagerOrOptions.maxInstructionsPerBurst;
+            }
+        }
+        this.saveManager = sm ?? new SaveManager();
+        this.maxSnapshots = Math.max(1, maxSnaps);
+        this.maxCallDepth = Math.max(1, maxDepth);
+        this.maxInstructionsPerBurst = Math.max(1, maxBurst);
     }
     getState() {
         return this.state;
     }
+    getStory() {
+        return this.story;
+    }
     getHistoryManager() {
         return this.historyManager;
     }
     getSaveManager() {
         return this.saveManager;
     }
+    getExecutionTrace() {
+        return [...this.executionTrace];
+    }
+    clearExecutionTrace() {
+        this.executionTrace = [];
+    }
+    recordTrace(entry) {
+        this.executionTrace.push(entry);
+    }
+    getVirtualTime() {
+        return this.virtualTimeMs;
+    }
+    tick(deltaMs) {
+        if (deltaMs <= 0)
+            return;
+        this.virtualTimeMs += deltaMs;
+        for (const listener of this.tickListeners) {
+            listener(deltaMs, this.virtualTimeMs);
+        }
+    }
+    onTick(listener) {
+        this.tickListeners.add(listener);
+        return () => this.tickListeners.delete(listener);
+    }
     onStateChange(listener) {
         this.stateChangeListeners.add(listener);
         return () => this.stateChangeListeners.delete(listener);
@@ -35,13 +94,42 @@ export class StoryVM {
         this.audioEventListeners.add(listener);
         return () => this.audioEventListeners.delete(listener);
     }
-    start() {
-        const startLabel = this.story.meta.startLabel ?? 'start';
+    onCameraEvent(listener) {
+        this.cameraEventListeners.add(listener);
+        return () => this.cameraEventListeners.delete(listener);
+    }
+    onError(listener) {
+        this.errorListeners.add(listener);
+        return () => this.errorListeners.delete(listener);
+    }
+    emitCameraEvent(event) {
+        for (const listener of this.cameraEventListeners) {
+            listener(event);
+        }
+    }
+    emitError(error) {
+        for (const listener of this.errorListeners) {
+            try {
+                listener(error);
+            }
+            catch { }
+        }
+    }
+    start(atLabel) {
+        if (this.isExecuting) {
+            throw new Error('Cannot call start() while the story VM is already executing instructions.');
+        }
+        const startLabel = atLabel ?? this.story.meta?.startLabel ?? 'start';
         if (!this.story.labels[startLabel]) {
             throw new Error(`Cannot start story: Start label '${startLabel}' not found in story package.`);
         }
+        const prevMusic = this.state.audio.music;
+        this.recordTrace(`START ${startLabel}`);
         this.state = createInitialState(startLabel);
         this.snapshotStack = [];
+        this.virtualTimeMs = 0;
+        this.historyManager.clear();
+        this.resyncAudio(prevMusic);
         this.executeUntilWaiting();
     }
     /**
@@ -54,9 +142,40 @@ export class StoryVM {
             // Must make a choice; cannot advance automatically
             return;
         }
+        if (this.state.hotspots && this.state.hotspots.length > 0) {
+            // Must click a hotspot; stage click must not skip.
+            return;
+        }
+        if (this.state.pendingInput) {
+            // Must call submitInput(); clicking the stage must not skip the prompt.
+            return;
+        }
         this.state = {
             ...this.state,
-            isWaitingForInput: false
+            isWaitingForInput: false,
+            pendingPauseMs: null
+        };
+        this.executeUntilWaiting();
+    }
+    /**
+     * Completes a pending `input` prompt and continues the story.
+     */
+    submitInput(value) {
+        if (this.isExecuting || !this.state.pendingInput)
+            return;
+        const variable = this.state.pendingInput.variable;
+        const trimmed = String(value ?? '').trim();
+        this.recordTrace(`INPUT ${variable}="${trimmed}"`);
+        const nextVars = { ...this.state.variables };
+        if (isSafeKey(variable)) {
+            nextVars[variable] = trimmed;
+        }
+        this.state = {
+            ...this.state,
+            variables: nextVars,
+            pendingInput: null,
+            isWaitingForInput: false,
+            pendingPauseMs: null
         };
         this.executeUntilWaiting();
     }
@@ -68,27 +187,86 @@ export class StoryVM {
             return;
         }
         const choice = this.state.choices[choiceIndex];
+        this.recordTrace(`CHOOSE ${choiceIndex} (${choice.text}) -> ${choice.targetLabel}`);
+        if (!this.story.labels[choice.targetLabel]) {
+            const err = new Error(`Runtime Error: Choice target label '${choice.targetLabel}' is not defined in story.`);
+            this.emitError(err);
+            this.state = {
+                ...this.state,
+                choices: null,
+                hotspots: null,
+                pendingPauseMs: null,
+                isFinished: true,
+                isWaitingForInput: false
+            };
+            this.notifyStateChanged();
+            return;
+        }
         this.state = {
             ...this.state,
             choices: null,
+            hotspots: null,
             isWaitingForInput: false,
+            pendingPauseMs: null,
             currentLabel: choice.targetLabel,
             instructionPointer: 0
         };
         this.executeUntilWaiting();
     }
+    /**
+     * Selects a clickable hotspot and jumps to its target label.
+     */
+    selectHotspot(id) {
+        if (this.isExecuting || !this.state.hotspots || this.state.hotspots.length === 0) {
+            return;
+        }
+        const hotspot = this.state.hotspots.find((h) => h.id === id);
+        if (!hotspot)
+            return;
+        this.recordTrace(`HOTSPOT ${id} -> ${hotspot.targetLabel}`);
+        if (!this.story.labels[hotspot.targetLabel]) {
+            const err = new Error(`Runtime Error: Hotspot target label '${hotspot.targetLabel}' is not defined in story.`);
+            this.emitError(err);
+            this.state = {
+                ...this.state,
+                hotspots: null,
+                pendingPauseMs: null,
+                isFinished: true,
+                isWaitingForInput: false
+            };
+            this.notifyStateChanged();
+            return;
+        }
+        this.state = {
+            ...this.state,
+            hotspots: null,
+            choices: null,
+            isWaitingForInput: false,
+            pendingPauseMs: null,
+            windowVisible: true,
+            currentLabel: hotspot.targetLabel,
+            instructionPointer: 0
+        };
+        this.executeUntilWaiting();
+    }
     /**
      * Jumps directly to a label.
      */
     jump(labelName) {
+        if (this.isExecuting) {
+            throw new Error('Cannot call jump() while the story VM is already executing instructions.');
+        }
         if (!this.story.labels[labelName]) {
             throw new Error(`Target label '${labelName}' not found in story package.`);
         }
+        this.recordTrace(`JUMP_MANUAL ${labelName}`);
         this.state = {
             ...this.state,
             currentLabel: labelName,
             instructionPointer: 0,
             choices: null,
+            hotspots: null,
+            pendingPauseMs: null,
             isWaitingForInput: false
         };
         this.executeUntilWaiting();
@@ -100,12 +278,17 @@ export class StoryVM {
         if (this.snapshotStack.length <= 1) {
             return false;
         }
+        const prevMusic = this.state.audio.music;
         // Pop current snapshot
         this.snapshotStack.pop();
         // Restore previous snapshot
         const prev = this.snapshotStack[this.snapshotStack.length - 1];
         if (prev) {
             this.state = cloneState(prev.state);
+            const histLen = typeof prev.historyLength === 'number' ? prev.historyLength : this.historyManager.getLength();
+            this.historyManager.trimTo(histLen);
+            this.recordTrace(`ROLLBACK`);
+            this.resyncAudio(prevMusic);
             this.notifyStateChanged();
             return true;
         }
@@ -117,28 +300,94 @@ export class StoryVM {
     async save(slotId) {
         const currentSnapshot = this.captureSnapshot();
         const previewText = this.state.dialogue?.text ?? 'Game in progress';
-        await this.saveManager.saveSlot(slotId, currentSnapshot, previewText);
+        this.recordTrace(`SAVE slot_${slotId}`);
+        return await this.saveManager.saveSlot(slotId, currentSnapshot, previewText, this.storyHash, this.historyManager.getEntries());
     }
-    async load(slotId) {
-        const slot = await this.saveManager.loadSlot(slotId);
-        if (!slot)
-            return false;
+    async load(slotId, validateStoryHash = true) {
+        const res = await this.loadWithDetails(slotId, validateStoryHash);
+        return res.success;
+    }
+    async loadWithDetails(slotId, validateStoryHash = true) {
+        const res = await this.saveManager.loadSlot(slotId, validateStoryHash ? this.storyHash : undefined);
+        if (!res.success || !res.slot) {
+            return res;
+        }
+        this.applyLoadedSlot(res.slot, `LOAD slot_${slotId}`);
+        return res;
+    }
+    /**
+     * Restore from an in-memory SaveSlot (continue-links, imported saves).
+     * Validates storyHash when present on the slot.
+     */
+    loadFromSlot(slot, validateStoryHash = true) {
+        if (validateStoryHash && slot.storyHash && slot.storyHash !== this.storyHash) {
+            return { success: false, reason: 'incompatible_story', slot };
+        }
+        this.applyLoadedSlot(slot, `LOAD continue_${slot.id}`);
+        return { success: true, slot };
+    }
+    applyLoadedSlot(slot, traceLabel) {
+        const prevMusic = this.state.audio.music;
         this.state = cloneState(slot.snapshot.state);
-        this.snapshotStack = [slot.snapshot];
+        const restoredHistory = slot.historyEntries ?? [];
+        this.historyManager.replaceAll(restoredHistory);
+        const snap = {
+            ...slot.snapshot,
+            historyLength: typeof slot.snapshot.historyLength === 'number'
+                ? slot.snapshot.historyLength
+                : restoredHistory.length
+        };
+        this.snapshotStack = [snap];
+        this.recordTrace(traceLabel);
+        this.resyncAudio(prevMusic);
         this.notifyStateChanged();
-        return true;
+    }
+    /**
+     * Emit stop/play audio events so the presentation layer matches restored state
+     * after load or rollback (snapshots store track ids but not live Audio elements).
+     */
+    resyncAudio(previousMusic) {
+        this.emitAudioEvent({ action: 'stop', channel: 'voice' });
+        this.emitAudioEvent({ action: 'stop', channel: 'sound' });
+        const nextMusic = this.state.audio.music;
+        if (previousMusic === nextMusic) {
+            return;
+        }
+        if (nextMusic) {
+            this.emitAudioEvent({
+                action: 'play',
+                channel: 'music',
+                track: nextMusic,
+                loop: true
+            });
+        }
+        else {
+            this.emitAudioEvent({ action: 'stop', channel: 'music' });
+        }
     }
     executeUntilWaiting() {
         if (this.isExecuting)
             return;
         this.isExecuting = true;
         try {
+            let instructionsExecuted = 0;
             while (!this.state.isWaitingForInput && !this.state.isFinished) {
+                if (instructionsExecuted >= this.maxInstructionsPerBurst) {
+                    const err = new Error(`Runtime Error: Exceeded maximum of ${this.maxInstructionsPerBurst} instructions without waiting for input (possible infinite loop at label '${this.state.currentLabel}').`);
+                    this.emitError(err);
+                    this.state = {
+                        ...this.state,
+                        isFinished: true,
+                        isWaitingForInput: false
+                    };
+                    break;
+                }
                 const labelInstructions = this.story.labels[this.state.currentLabel];
                 if (!labelInstructions || this.state.instructionPointer >= labelInstructions.length) {
                     // Handle end of label: check call stack
                     if (this.state.callStack.length > 0) {
                         const topFrame = this.state.callStack[this.state.callStack.length - 1];
+                        this.recordTrace(`RETURN -> ${topFrame.returnLabel}:${topFrame.returnPointer}`);
                         this.state = {
                             ...this.state,
                             currentLabel: topFrame.returnLabel,
@@ -148,6 +397,7 @@ export class StoryVM {
                         continue;
                     }
                     // Story finished
+                    this.recordTrace('END');
                     this.state = {
                         ...this.state,
                         isFinished: true,
@@ -161,6 +411,7 @@ export class StoryVM {
                     instructionPointer: this.state.instructionPointer + 1
                 };
                 this.executeInstruction(inst);
+                instructionsExecuted++;
             }
             if (this.state.isWaitingForInput) {
                 this.recordSnapshot();
@@ -174,18 +425,26 @@ export class StoryVM {
     executeInstruction(inst) {
         switch (inst.type) {
             case 'scene': {
+                this.recordTrace(`SCENE ${inst.background}${inst.transition ? ` [${inst.transition}]` : ''}`);
                 this.state = {
                     ...this.state,
                     visual: {
                         background: inst.background,
                         transition: inst.transition ?? null,
-                        characters: {} // Clear characters on new scene
-                    }
+                        characters: {}, // Clear characters on new scene
+                        vfx: null,
+                        activeCG: null,
+                        defaultLayer: this.state.visual.defaultLayer
+                    },
+                    hotspots: null
                 };
                 break;
             }
             case 'show': {
+                this.recordTrace(`SHOW ${inst.character}${inst.expression ? ` ${inst.expression}` : ''}${inst.position ? ` at ${inst.position}` : ''}`);
                 const charDef = this.state.visual.characters[inst.character] ?? {};
+                const layer = inst.layer ?? charDef.layer ?? this.state.visual.defaultLayer ?? undefined;
+                const z = resolveSpriteZ(layer, inst.z ?? charDef.z);
                 this.state = {
                     ...this.state,
                     visual: {
@@ -194,7 +453,11 @@ export class StoryVM {
                             ...this.state.visual.characters,
                             [inst.character]: {
                                 expression: inst.expression ?? charDef.expression,
-                                position: inst.position ?? charDef.position ?? 'center'
+                                position: inst.position ?? charDef.position ?? 'center',
+                                transition: inst.transition ?? charDef.transition,
+                                layer,
+                                z,
+                                cssAnimation: charDef.cssAnimation
                             }
                         }
                     }
@@ -202,6 +465,7 @@ export class StoryVM {
                 break;
             }
             case 'hide': {
+                this.recordTrace(`HIDE ${inst.character}`);
                 const nextChars = { ...this.state.visual.characters };
                 delete nextChars[inst.character];
                 this.state = {
@@ -217,50 +481,236 @@ export class StoryVM {
                 const charDef = inst.speaker ? this.story.characters[inst.speaker] : undefined;
                 const displayName = charDef?.name ?? inst.speaker;
                 const color = charDef?.color;
+                const interpolatedText = interpolateVariables(inst.text, this.state.variables, {
+                    lang: this.state.lang,
+                    i18n: this.story.i18n
+                });
+                this.recordTrace(`DIALOGUE ${displayName ? `[${displayName}] ` : ''}${interpolatedText}`);
                 this.state = {
                     ...this.state,
                     dialogue: {
                         speaker: inst.speaker,
                         speakerDisplayName: displayName,
                         speakerColor: color,
-                        text: inst.text
+                        text: interpolatedText
                     },
+                    hotspots: null,
+                    pendingPauseMs: null,
                     isWaitingForInput: true
                 };
-                this.historyManager.addEntry(inst.speaker, displayName, inst.text);
+                this.historyManager.addEntry(inst.speaker, displayName, interpolatedText);
                 break;
             }
             case 'choice': {
+                const availableChoices = inst.choices
+                    .filter(choice => {
+                    if (!choice.condition)
+                        return true;
+                    return evaluateCondition(choice.condition, this.state.variables);
+                })
+                    .map(choice => ({
+                    ...choice,
+                    text: interpolateVariables(choice.text, this.state.variables, {
+                        lang: this.state.lang,
+                        i18n: this.story.i18n
+                    })
+                }));
+                this.recordTrace(`CHOICES [${availableChoices.map(c => c.text).join(', ')}]`);
+                if (availableChoices.length === 0) {
+                    // No visible choices — jump to menu fallthrough rather than soft-locking.
+                    const fallback = inst.fallbackLabel;
+                    const err = new Error('Runtime Warning: Choice menu evaluated to zero available options; continuing.');
+                    this.emitError(err);
+                    if (fallback && this.story.labels[fallback]) {
+                        this.state = {
+                            ...this.state,
+                            choices: null,
+                            pendingPauseMs: null,
+                            isWaitingForInput: false,
+                            currentLabel: fallback,
+                            instructionPointer: 0
+                        };
+                    }
+                    else {
+                        this.state = {
+                            ...this.state,
+                            choices: null,
+                            pendingPauseMs: null,
+                            isWaitingForInput: false
+                        };
+                    }
+                    break;
+                }
                 this.state = {
                     ...this.state,
-                    choices: inst.choices,
+                    choices: availableChoices,
+                    hotspots: null,
+                    pendingPauseMs: null,
                     isWaitingForInput: true
                 };
                 break;
             }
+            case 'vfx': {
+                this.recordTrace(`VFX ${inst.effect}${inst.intensity !== undefined ? ` ${inst.intensity}` : ''}${inst.color ? ` ${inst.color}` : ''}`);
+                if (inst.effect === 'stop') {
+                    this.state = {
+                        ...this.state,
+                        visual: {
+                            ...this.state.visual,
+                            vfx: null
+                        }
+                    };
+                    break;
+                }
+                const prev = this.state.visual.vfx;
+                // Tint is an overlay: keep rain/sakura/snow/fog particles running underneath.
+                if (inst.effect === 'tint') {
+                    const baseEffect = prev && prev.effect !== 'tint' && prev.effect !== 'stop' ? prev.effect : 'tint';
+                    this.state = {
+                        ...this.state,
+                        visual: {
+                            ...this.state.visual,
+                            vfx: {
+                                effect: baseEffect,
+                                intensity: prev?.intensity,
+                                color: inst.color ?? (typeof inst.intensity === 'string' ? inst.intensity : undefined)
+                            }
+                        }
+                    };
+                    break;
+                }
+                this.state = {
+                    ...this.state,
+                    visual: {
+                        ...this.state.visual,
+                        vfx: {
+                            effect: inst.effect,
+                            intensity: inst.intensity,
+                            // Preserve active tint color when switching weather effects
+                            color: prev?.color
+                        }
+                    }
+                };
+                break;
+            }
+            case 'camera': {
+                this.recordTrace(`CAMERA ${inst.action}${inst.duration !== undefined ? ` ${inst.duration}` : ''}`);
+                this.emitCameraEvent({
+                    action: inst.action,
+                    duration: inst.duration
+                });
+                break;
+            }
+            case 'pause': {
+                this.recordTrace(`PAUSE${inst.duration !== undefined ? ` ${inst.duration}` : ''}`);
+                // Duration is treated as milliseconds (matches README / parser examples like `pause 1200`).
+                this.state = {
+                    ...this.state,
+                    pendingPauseMs: inst.duration !== undefined && inst.duration > 0 ? inst.duration : null,
+                    isWaitingForInput: true
+                };
+                break;
+            }
+            case 'cg': {
+                const unlockKey = inst.unlockId || inst.image;
+                this.recordTrace(`CG ${inst.image}`);
+                const nextUnlocked = Object.assign(Object.create(null), this.state.unlockedCGs);
+                nextUnlocked[unlockKey] = true;
+                this.state = {
+                    ...this.state,
+                    visual: {
+                        ...this.state.visual,
+                        activeCG: inst.image
+                    },
+                    unlockedCGs: nextUnlocked
+                };
+                break;
+            }
             case 'jump': {
+                const target = inst.targetLabel;
+                this.recordTrace(`JUMP ${target}`);
+                if (!this.story.labels[target]) {
+                    const err = new Error(`Runtime Error: Jump target label '${target}' is not defined in story.`);
+                    this.emitError(err);
+                    this.state = {
+                        ...this.state,
+                        isFinished: true,
+                        isWaitingForInput: false
+                    };
+                    break;
+                }
                 this.state = {
                     ...this.state,
-                    currentLabel: inst.targetLabel,
+                    currentLabel: target,
+                    instructionPointer: 0
+                };
+                break;
+            }
+            case 'call': {
+                const target = inst.targetLabel;
+                this.recordTrace(`CALL ${target}`);
+                if (this.state.callStack.length >= this.maxCallDepth) {
+                    const err = new Error(`Runtime Error: Maximum call stack depth of ${this.maxCallDepth} exceeded.`);
+                    this.emitError(err);
+                    this.state = {
+                        ...this.state,
+                        isFinished: true,
+                        isWaitingForInput: false
+                    };
+                    break;
+                }
+                if (!this.story.labels[target]) {
+                    const err = new Error(`Runtime Error: Call target label '${target}' is not defined in story.`);
+                    this.emitError(err);
+                    this.state = {
+                        ...this.state,
+                        isFinished: true,
+                        isWaitingForInput: false
+                    };
+                    break;
+                }
+                this.state = {
+                    ...this.state,
+                    callStack: [
+                        ...this.state.callStack,
+                        {
+                            returnLabel: this.state.currentLabel,
+                            returnPointer: this.state.instructionPointer
+                        }
+                    ],
+                    currentLabel: target,
                     instructionPointer: 0
                 };
                 break;
             }
             case 'set': {
                 const currentVal = this.state.variables[inst.variable];
-                const nextVal = applySetOperation(currentVal, inst.operator, inst.value, this.state.variables);
+                const nextVal = applySetOperation(currentVal, inst.operator, inst.value, this.state.variables, inst.isVariable);
+                this.recordTrace(`SET ${inst.variable} ${inst.operator ?? '='} ${String(nextVal)}`);
+                const nextVars = Object.assign(Object.create(null), this.state.variables);
+                if (isSafeKey(inst.variable)) {
+                    nextVars[inst.variable] = nextVal;
+                }
                 this.state = {
                     ...this.state,
-                    variables: {
-                        ...this.state.variables,
-                        [inst.variable]: nextVal
-                    }
+                    variables: nextVars
                 };
                 break;
             }
             case 'branch': {
                 const conditionVal = evaluateCondition(inst.condition, this.state.variables);
                 const targetLabel = conditionVal ? inst.thenLabel : (inst.elseLabel ?? inst.thenLabel);
+                this.recordTrace(`BRANCH ${inst.condition} (${conditionVal}) -> ${targetLabel}`);
+                if (!this.story.labels[targetLabel]) {
+                    const err = new Error(`Runtime Error: Branch target label '${targetLabel}' is not defined in story.`);
+                    this.emitError(err);
+                    this.state = {
+                        ...this.state,
+                        isFinished: true,
+                        isWaitingForInput: false
+                    };
+                    break;
+                }
                 this.state = {
                     ...this.state,
                     currentLabel: targetLabel,
@@ -269,6 +719,7 @@ export class StoryVM {
                 break;
             }
             case 'play_audio': {
+                this.recordTrace(`PLAY_AUDIO ${inst.channel}:${inst.track}`);
                 this.emitAudioEvent({
                     action: 'play',
                     channel: inst.channel,
@@ -288,6 +739,7 @@ export class StoryVM {
                 break;
             }
             case 'stop_audio': {
+                this.recordTrace(`STOP_AUDIO ${inst.channel}`);
                 this.emitAudioEvent({
                     action: 'stop',
                     channel: inst.channel,
@@ -304,9 +756,162 @@ export class StoryVM {
                 }
                 break;
             }
+            case 'input': {
+                const prompt = interpolateVariables(inst.prompt, this.state.variables, {
+                    lang: this.state.lang,
+                    i18n: this.story.i18n
+                });
+                this.recordTrace(`INPUT_WAIT ${inst.variable} "${prompt}"`);
+                this.state = {
+                    ...this.state,
+                    pendingInput: { variable: inst.variable, prompt },
+                    choices: null,
+                    hotspots: null,
+                    pendingPauseMs: null,
+                    isWaitingForInput: true
+                };
+                break;
+            }
+            case 'window': {
+                this.recordTrace(`WINDOW ${inst.action}`);
+                this.state = {
+                    ...this.state,
+                    windowVisible: inst.action === 'show'
+                };
+                break;
+            }
+            case 'theme': {
+                const name = sanitizeCssToken(inst.name);
+                this.recordTrace(`THEME ${name}`);
+                this.state = {
+                    ...this.state,
+                    theme: name || null
+                };
+                break;
+            }
+            case 'style': {
+                const target = sanitizeCssToken(inst.target) || 'root';
+                const name = sanitizeCssToken(inst.name) || 'default';
+                this.recordTrace(`STYLE ${target}=${name}`);
+                this.state = {
+                    ...this.state,
+                    styleClasses: {
+                        ...this.state.styleClasses,
+                        [target]: name
+                    }
+                };
+                break;
+            }
+            case 'hotspot': {
+                const collected = [
+                    {
+                        id: inst.id,
+                        x: inst.x,
+                        y: inst.y,
+                        w: inst.w,
+                        h: inst.h,
+                        targetLabel: inst.targetLabel
+                    }
+                ];
+                const labelInstructions = this.story.labels[this.state.currentLabel] ?? [];
+                while (this.state.instructionPointer < labelInstructions.length) {
+                    const nextInst = labelInstructions[this.state.instructionPointer];
+                    if (!nextInst || nextInst.type !== 'hotspot')
+                        break;
+                    this.state = {
+                        ...this.state,
+                        instructionPointer: this.state.instructionPointer + 1
+                    };
+                    collected.push({
+                        id: nextInst.id,
+                        x: nextInst.x,
+                        y: nextInst.y,
+                        w: nextInst.w,
+                        h: nextInst.h,
+                        targetLabel: nextInst.targetLabel
+                    });
+                }
+                this.recordTrace(`HOTSPOTS [${collected.map((h) => h.id).join(', ')}]`);
+                this.state = {
+                    ...this.state,
+                    hotspots: collected,
+                    choices: null,
+                    pendingPauseMs: null,
+                    isWaitingForInput: true
+                };
+                break;
+            }
+            case 'layer': {
+                const name = sanitizeCssToken(inst.name) || 'master';
+                this.recordTrace(`LAYER ${name}`);
+                this.state = {
+                    ...this.state,
+                    visual: {
+                        ...this.state.visual,
+                        defaultLayer: name
+                    }
+                };
+                break;
+            }
+            case 'animate': {
+                const existing = this.state.visual.characters[inst.character];
+                if (!existing) {
+                    this.recordTrace(`ANIMATE skipped (missing ${inst.character})`);
+                    break;
+                }
+                const animName = sanitizeCssToken(inst.animation) || 'fade-in';
+                this.recordTrace(`ANIMATE ${inst.character} ${animName}`);
+                this.state = {
+                    ...this.state,
+                    visual: {
+                        ...this.state.visual,
+                        characters: {
+                            ...this.state.visual.characters,
+                            [inst.character]: {
+                                ...existing,
+                                cssAnimation: {
+                                    name: animName,
+                                    durationMs: inst.durationMs,
+                                    token: Date.now()
+                                }
+                            }
+                        }
+                    }
+                };
+                break;
+            }
+            case 'unlock': {
+                const catalog = this.story.achievements?.find((a) => a.id === inst.id);
+                const entry = {
+                    id: inst.id,
+                    title: inst.title ?? catalog?.title ?? inst.id,
+                    description: inst.description ?? catalog?.description,
+                    unlockedAt: Date.now()
+                };
+                this.recordTrace(`UNLOCK ${inst.id}`);
+                this.state = {
+                    ...this.state,
+                    achievements: {
+                        ...this.state.achievements,
+                        [inst.id]: entry
+                    }
+                };
+                this.persistAchievement(entry);
+                break;
+            }
+            case 'lang': {
+                const code = inst.code.trim().toLowerCase() || 'en';
+                this.recordTrace(`LANG ${code}`);
+                this.state = {
+                    ...this.state,
+                    lang: code
+                };
+                break;
+            }
             case 'return': {
                 if (this.state.callStack.length > 0) {
                     const topFrame = this.state.callStack[this.state.callStack.length - 1];
+                    this.recordTrace(`RETURN -> ${topFrame.returnLabel}:${topFrame.returnPointer}`);
                     this.state = {
                         ...this.state,
                         currentLabel: topFrame.returnLabel,
@@ -315,6 +920,7 @@ export class StoryVM {
                     };
                 }
                 else {
+                    this.recordTrace('END');
                     this.state = {
                         ...this.state,
                         isFinished: true,
@@ -329,14 +935,14 @@ export class StoryVM {
         return {
             id: `snap_${Date.now()}_${this.snapshotStack.length}`,
             timestamp: Date.now(),
-            state: cloneState(this.state)
+            state: cloneState(this.state),
+            historyLength: this.historyManager.getLength()
         };
     }
     recordSnapshot() {
         const snap = this.captureSnapshot();
         this.snapshotStack.push(snap);
-        // Limit snapshot history to last 50 steps
-        if (this.snapshotStack.length > 50) {
+        if (this.snapshotStack.length > this.maxSnapshots) {
             this.snapshotStack.shift();
         }
     }
@@ -351,5 +957,65 @@ export class StoryVM {
             listener(event);
         }
     }
+    persistAchievement(entry) {
+        if (typeof localStorage === 'undefined')
+            return;
+        try {
+            const key = `kawaijs_achievements_${this.storyHash}`;
+            const raw = localStorage.getItem(key);
+            const map = raw ? JSON.parse(raw) : {};
+            map[entry.id] = entry;
+            localStorage.setItem(key, JSON.stringify(map));
+        }
+        catch {
+            // ignore quota / private mode
+        }
+    }
+    /** Merge locally persisted achievements into the current state (call after start/load). */
+    hydrateAchievements() {
+        if (typeof localStorage === 'undefined')
+            return;
+        try {
+            const key = `kawaijs_achievements_${this.storyHash}`;
+            const raw = localStorage.getItem(key);
+            if (!raw)
+                return;
+            const map = JSON.parse(raw);
+            this.state = {
+                ...this.state,
+                achievements: {
+                    ...map,
+                    ...this.state.achievements
+                }
+            };
+            this.notifyStateChanged();
+        }
+        catch {
+            // ignore
+        }
+    }
+    /** Export achievements as a plain JSON-serializable object (itch / analytics). */
+    exportAchievementsJson() {
+        return {
+            storyHash: this.storyHash,
+            exportedAt: Date.now(),
+            achievements: Object.values(this.state.achievements)
+        };
+    }
+    /** Set active language for `{t:key}` lookups (also used by `?lang=`). */
+    setLang(code) {
+        const normalized = code.trim().toLowerCase() || 'en';
+        this.state = {
+            ...this.state,
+            lang: normalized
+        };
+        this.notifyStateChanged();
+    }
+}
+function sanitizeCssToken(raw) {
+    return String(raw ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '');
 }
 //# sourceMappingURL=vm.js.map