Variables assets can keep their values from one run to the next (#166)

A game needs a high score or an unlocked level to survive the end of
a run. As agreed in the issue there are no save or load nodes. A
Variables asset gets a switch instead, and the existing Variables
nodes read and write the values as before.

- A "Persistent" checkbox in the Variables inspector. Toggling it is
  one undo step, and absent means not persistent.
- The behavior system loads the saved values at start and writes them
  after every frame that changed one, so a closed tab loses nothing.
- Values live in localStorage per project, not in the project file.
  Another browser or person starts fresh.
- Play and "Run in editor" save apart, so trying a behavior in the
  editor leaves the Play save alone.
- Saved values are read through the current declaration. A removed
  variable drops out, a new one starts from its default, and a changed
  kind is converted.
- "Clear saved values" in the inspector clears this asset in both
  areas. The main menu gets "Clear saved data" for the whole project.
  Clearing takes effect from the next run on.

Decisions:
- The switch covers the whole asset, not single variables. Mixing
  both means two assets.
- A changed default in the inspector shows only after the save is
  cleared. That is what persistent means.

Findings:
- The first e2e run died at "debug hook present" right after a Vulkan
  error from Chrome. The second run passed, so it was a GPU flake at
  start-up.

Tests:
- ./check.sh: 140 files, 2070 tests, exit 0 (before 138 / 2055).
- 15 new unit tests in tests/core/saved-values.test.ts and
  tests/editor/saves.test.ts.
- GM_STEPS=32,46 fresh: ALL PASSED, 24 checks. Six new checks in
  module 32 go through the UI. Module 46 knows the new menu entry.
- Counter-checks both fail as expected. Loading switched off: 2 unit
  tests and 2 e2e checks fail. Editor run writing into the Play area:
  1 e2e check fails.
- Check total 1278 (1272 measured by CI at bbbf341, plus 6).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tests/core/saved-values.test.ts

@@ -0,0 +1,160 @@
+/**
+ * A persistent Variables asset keeps its values past the end of the run (#166): the next run starts
+ * where the last one left off, from whatever area it is handed – played and editor runs get their own.
+ */
+import { describe, expect, it } from 'vitest';
+import { SetVariablesPersistentCommand } from '../../src/core/commands/assetCommands';
+import { AddVariableCommand, RemoveVariableCommand } from '../../src/core/commands/variableCommands';
+import { restoreSaved, type SaveArea, type SavedValues, VARIABLES_PARAM } from '../../src/core/graph';
+import type { VariablesAsset } from '../../src/core/model/Asset';
+import { deserializeProject, serializeProject } from '../../src/core/store/serialize';
+import {
+  graphEditor,
+  makeBehavior,
+  makeSpriteScene,
+  makeVariables,
+  place,
+  type SceneFixture,
+  startWorld,
+} from '../helpers';
+
+/** An area in memory that counts its writes. */
+function memoryArea(): SaveArea & { saved: SavedValues; writes: number } {
+  const area = {
+    saved: {} as SavedValues,
+    writes: 0,
+    read: () => structuredClone(area.saved),
+    write: (saved: SavedValues) => {
+      area.writes++;
+      area.saved = structuredClone(saved);
+    },
+  };
+  return area;
+}
+
+/** One object whose behavior adds one to `score` of the asset on start. */
+function counting(persistent = true) {
+  const f = makeSpriteScene();
+  const shared = makeVariables(f, 'Progress', ['score']);
+  if (persistent) f.stack.execute(new SetVariablesPersistentCommand(shared.id, true));
+  const behavior = makeBehavior(f, 'Counter');
+  const editor = graphEditor(f, behavior);
+  const params = { [VARIABLES_PARAM]: shared.id };
+  const start = editor.addNode('OnStart');
+  const read = editor.variables(['score'], { params });
+  const add = editor.addNode('Add', { b: 1 });
+  const write = editor.variables(['score'], { write: true, params });
+  editor.wire([
+    [start, 'exec', write, 'exec'],
+    [read, 'score', add, 'a'],
+    [add, 'result', write, 'score'],
+  ]);
+  place(f, behavior.id, { x: 0, y: 0 });
+  return { f, shared };
+}
+
+function run(f: SceneFixture, saves: SaveArea) {
+  const started = startWorld(f, { behaviors: true, saves });
+  started.frame();
+  return started;
+}
+
+const scoreOf = (started: ReturnType<typeof run>, id: string) =>
+  started.behaviors!.shared.variables[id]!.score;
+
+describe('a persistent Variables asset', () => {
+  it('starts the next run where the last one ended', () => {
+    const { f, shared } = counting();
+    const area = memoryArea();
+    expect(scoreOf(run(f, area), shared.id)).toBe(1);
+    expect(scoreOf(run(f, area), shared.id)).toBe(2);
+    expect(area.saved).toEqual({ [shared.id]: { score: 2 } });
+  });
+
+  it('keeps played and editor runs apart', () => {
+    const { f, shared } = counting();
+    const played = memoryArea();
+    const editor = memoryArea();
+    run(f, played);
+    run(f, played);
+    expect(scoreOf(run(f, editor), shared.id)).toBe(1);
+    expect(played.saved[shared.id]!.score).toBe(2);
+  });
+
+  it('writes only in a frame that changed something', () => {
+    const { f } = counting();
+    const area = memoryArea();
+    const started = run(f, area);
+    const after = area.writes;
+    started.frame();
+    started.frame();
+    expect(after).toBe(1);
+    expect(area.writes).toBe(1);
+  });
+
+  it('starts from the declared value again once the save is gone', () => {
+    const { f, shared } = counting();
+    const area = memoryArea();
+    run(f, area);
+    area.saved = {};
+    expect(scoreOf(run(f, area), shared.id)).toBe(1);
+  });
+});
+
+describe('a Variables asset that is not persistent', () => {
+  it('neither reads nor writes a save', () => {
+    const { f, shared } = counting(false);
+    const area = memoryArea();
+    area.saved = { [shared.id]: { score: 40 } };
+    expect(scoreOf(run(f, area), shared.id)).toBe(1);
+    expect(area.writes).toBe(0);
+  });
+});
+
+describe('restoring a save', () => {
+  function project() {
+    const f = makeSpriteScene();
+    const shared = makeVariables(f, 'Progress', ['score', 'lives']);
+    f.stack.execute(new SetVariablesPersistentCommand(shared.id, true));
+    return { f, shared };
+  }
+
+  it('follows the declaration as it is now, not as it was saved', () => {
+    const { f, shared } = project();
+    f.stack.execute(new RemoveVariableCommand(shared.id, 'lives'));
+    f.stack.execute(new AddVariableCommand(shared.id, 'name', 'text'));
+    const variables = { [shared.id]: { score: 0, name: '' } };
+    restoreSaved(f.project, variables, { [shared.id]: { score: '12', lives: 3, name: 7 } });
+    // A key no longer declared stays out, and each value takes the kind declared today.
+    expect(variables[shared.id]).toEqual({ score: 12, name: '7' });
+  });
+
+  it('leaves a key the save does not name at its declared value', () => {
+    const { f, shared } = project();
+    const variables = { [shared.id]: { score: 0, lives: 3 } };
+    restoreSaved(f.project, variables, { [shared.id]: { score: 5 } });
+    expect(variables[shared.id]).toEqual({ score: 5, lives: 3 });
+  });
+});
+
+describe('the persistent switch', () => {
+  it('is one undo step', () => {
+    const f = makeSpriteScene();
+    const shared = makeVariables(f, 'Progress', ['score']);
+    f.stack.execute(new SetVariablesPersistentCommand(shared.id, true));
+    expect(shared.persistent).toBe(true);
+    f.stack.undo();
+    expect(shared.persistent).toBeUndefined();
+  });
+
+  it('survives saving and loading', () => {
+    const f = makeSpriteScene();
+    const shared = makeVariables(f, 'Progress', ['score']);
+    f.stack.execute(new SetVariablesPersistentCommand(shared.id, true));
+    const loaded = deserializeProject(JSON.parse(JSON.stringify(serializeProject(f.project))));
+    const asset = loaded.assets.find(
+      (a): a is VariablesAsset => a.id === shared.id && a.type === 'variables',
+    );
+    expect(asset?.persistent).toBe(true);
+  });
+});

tests/editor/saves.test.ts

@@ -0,0 +1,70 @@
+/** The browser side of #166: one stored entry per project and area, cleared per asset or per project. */
+import { describe, expect, it } from 'vitest';
+import { clearSaved, hasSaved, saveArea, saveKey } from '../../src/editor/saves';
+
+function memoryStore() {
+  const items = new Map<string, string>();
+  return {
+    items,
+    getItem: (key: string) => items.get(key) ?? null,
+    setItem: (key: string, value: string) => void items.set(key, value),
+    removeItem: (key: string) => void items.delete(key),
+  };
+}
+
+describe('save areas', () => {
+  it('keep projects and areas apart', () => {
+    const store = memoryStore();
+    saveArea('p1', 'play', store).write({ a: { score: 1 } });
+    saveArea('p1', 'editor', store).write({ a: { score: 2 } });
+    saveArea('p2', 'play', store).write({ a: { score: 3 } });
+    expect(saveArea('p1', 'play', store).read()).toEqual({ a: { score: 1 } });
+    expect(saveArea('p1', 'editor', store).read()).toEqual({ a: { score: 2 } });
+    expect(saveArea('p2', 'play', store).read()).toEqual({ a: { score: 3 } });
+  });
+
+  it('leave an asset the run does not write as it was', () => {
+    const store = memoryStore();
+    const area = saveArea('p1', 'play', store);
+    area.write({ a: { score: 1 }, b: { coins: 4 } });
+    area.write({ a: { score: 2 } });
+    expect(area.read()).toEqual({ a: { score: 2 }, b: { coins: 4 } });
+  });
+
+  it('read an unreadable entry as nothing saved', () => {
+    const store = memoryStore();
+    store.setItem(saveKey('p1', 'play'), '{broken');
+    expect(saveArea('p1', 'play', store).read()).toEqual({});
+    store.setItem(saveKey('p1', 'play'), JSON.stringify({ a: 5, b: { score: 1 } }));
+    expect(saveArea('p1', 'play', store).read()).toEqual({ b: { score: 1 } });
+  });
+
+  it('keep working without storage', () => {
+    const area = saveArea('p1', 'play', null);
+    area.write({ a: { score: 1 } });
+    expect(area.read()).toEqual({});
+  });
+});
+
+describe('clearing saved data', () => {
+  it('forgets one asset in both areas and keeps the others', () => {
+    const store = memoryStore();
+    saveArea('p1', 'play', store).write({ a: { score: 1 }, b: { coins: 4 } });
+    saveArea('p1', 'editor', store).write({ a: { score: 2 } });
+    clearSaved('p1', 'a', store);
+    expect(saveArea('p1', 'play', store).read()).toEqual({ b: { coins: 4 } });
+    expect(hasSaved('p1', 'a', store)).toBe(false);
+    expect(store.items.has(saveKey('p1', 'editor'))).toBe(false);
+  });
+
+  it('forgets the whole project and leaves other projects alone', () => {
+    const store = memoryStore();
+    saveArea('p1', 'play', store).write({ a: { score: 1 } });
+    saveArea('p1', 'editor', store).write({ a: { score: 2 } });
+    saveArea('p2', 'play', store).write({ a: { score: 3 } });
+    expect(hasSaved('p1', undefined, store)).toBe(true);
+    clearSaved('p1', undefined, store);
+    expect(hasSaved('p1', undefined, store)).toBe(false);
+    expect(hasSaved('p2', undefined, store)).toBe(true);
+  });
+});

tests/helpers.ts

@@ -31,6 +31,7 @@ import type { SceneObject } from '../src/core/model/SceneObject';
 import { deserializeProject, serializeProject } from '../src/core/store/serialize';
 import type { AudioSink } from '../src/runtime/systems/Audio';
 import { BehaviorSystem, type TimeScaled } from '../src/runtime/systems/BehaviorSystem';
+import type { SaveArea } from '../src/core/graph/savedValues';
 import { readyPhysics } from '../src/runtime/physics/engine';
 import { PhysicsSystem } from '../src/runtime/physics/PhysicsSystem';
 import { CollisionSystem } from '../src/runtime/systems/CollisionSystem';
@@ -299,6 +300,8 @@ export interface WorldOptions {
   audio?: AudioSink;
   /** The clock `Set time scale` turns; without one the run is treated like the editor run. */
   clock?: TimeScaled;
+  /** Where persistent Variables assets keep their values; without one nothing outlives the run. */
+  saves?: SaveArea;
 }
 
 export interface StartedWorld {
@@ -334,6 +337,7 @@ export function startWorld(fixture: SceneFixture, options: WorldOptions = {}): S
         animations,
         audio: options.audio,
         clock: options.clock,
+        saves: options.saves,
       })
     : null;
   if (behaviors) world.addSystem(behaviors);