Variables and state machines can reset with every scene (#164)

A shared variable or machine used to live either per object or for the
whole run. Levels need a third lifetime: shared like global, but built
fresh from the declarations whenever a scene is loaded.

- New scope `scene` for Variables assets and state machines. A missing
  field keeps the old meaning: `global` for assets, `local` for
  machines, so existing projects do not change.
- Returning to a scene that was visited before is fresh as well. There
  is no memory per scene.
- A `scene` machine announces its start state again after a scene swap,
  so `On state entered` in the new scene hears it. A global machine
  stays quiet because it never left its state.
- The rule lives in two pure functions in `sharedState.ts`
  (`carriedForward`, `restartedAssets`). BehaviorSystem only calls them.
- The inspector shows a Scope dropdown on Variables assets and a third
  step on the machine dropdown, with a note on what `scene` means.

Decisions:
- `scene` and `persistent` exclude each other (variant A). The choice
  dialog was cancelled, so this is an assumption to revisit. A
  scene-scoped asset hides the Persistent switch, and switching to
  `scene` drops the flag (undo restores it). The guard sits in
  `isPersistent` itself, so no path can save values the scope throws
  away anyway.

Findings:
- `clickText('Scene')` hits the Scene tab, not the menu entry. One e2e
  check was red because of that, and its partner was falsely green
  because it compared `undefined` with `undefined`. Both use `clickLast`
  now.

Tests:
- ./check.sh: 144 files, 2142 tests, CHECK EXIT 0 (before 143 / 2133)
- 9 new unit tests in tests/core/scene-scope.test.ts
- e2e 32 fresh: ALL PASSED, 17 checks
- e2e 1-3,17,18,26,32,35 fresh: ALL PASSED, 213 checks
- 3 new e2e checks (35: scene-scoped asset resets on swap, 32h: dropdown,
  note, hidden Persistent switch)
- Counter-checks bite: ignoring `restarted` fails 2 unit tests and the
  new check in 35, the old announcement rule fails 1, dropping the scope
  guard in `isPersistent` fails 1. Originals restored, cmp IDENTICAL.
- Check sum 1307 (1304 + 3) is computed. Last CI measurement: 1293.

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

src/core/commands/assetCommands.ts

@@ -15,7 +15,14 @@ import { isSoundFile } from '../model/sound';
 import { removeSubtrees } from '../model/hierarchy';
 import type { PropertyBag, PropertyValue } from '../model/Properties';
 import { findAssetOf, objectHolders, type Project } from '../model/Project';
-import { type Scope, scopeOf, setScope } from '../model/Scope';
+import {
+  type Scope,
+  scopeOf,
+  setScope,
+  setSharedScope,
+  type SharedScope,
+  sharedScopeOf,
+} from '../model/Scope';
 import type { SceneObject } from '../model/SceneObject';
 import { isTextureFile } from '../model/texture';
 import { coerceValue, defaultsFor } from '../properties/PropertySchema';
@@ -254,7 +261,16 @@ export class RenameAssetCommand implements Command {
   }
 }
 
-/** A `global` machine keeps one current state for the whole run instead of one per behavior instance. */
+const SCOPE_LABELS: Record<Scope, string> = {
+  local: 'local',
+  global: 'global',
+  scene: 'per scene',
+};
+
+/**
+ * A `global` machine keeps one current state for the whole run instead of one per behavior
+ * instance; a `scene` machine shares one too, but starts over with every scene (#164).
+ */
 export class SetMachineScopeCommand implements Command {
   readonly label: string;
   private previous: Scope = 'local';
@@ -263,7 +279,7 @@ export class SetMachineScopeCommand implements Command {
     private readonly assetId: string,
     private readonly scope: Scope,
   ) {
-    this.label = `Make state machine ${scope}`;
+    this.label = `Make state machine ${SCOPE_LABELS[scope]}`;
   }
 
   execute(project: Project): void {
@@ -311,6 +327,44 @@ function setPersistent(asset: VariablesAsset, on: boolean): void {
   else delete asset.persistent;
 }
 
+/**
+ * How long one set of shared values lives: `global` for the whole run, `scene` built again from the
+ * declarations with every scene that is loaded (#164). Going to `scene` takes the persistent switch
+ * off, because the two say opposite things about the same values and the scope is what was just asked for.
+ */
+export class SetVariablesScopeCommand implements Command {
+  readonly label: string;
+  private previous: SharedScope = 'global';
+  private wasPersistent = false;
+
+  constructor(
+    private readonly assetId: string,
+    private readonly scope: SharedScope,
+  ) {
+    this.label = scope === 'scene' ? 'Make variables per scene' : 'Make variables global';
+  }
+
+  execute(project: Project): void {
+    const asset = this.target(project);
+    this.previous = sharedScopeOf(asset);
+    this.wasPersistent = asset.persistent === true;
+    setSharedScope(asset, this.scope);
+    if (this.scope === 'scene') setPersistent(asset, false);
+  }
+
+  undo(project: Project): void {
+    const asset = this.target(project);
+    setSharedScope(asset, this.previous);
+    setPersistent(asset, this.wasPersistent);
+  }
+
+  private target(project: Project): VariablesAsset {
+    const asset = findAssetOf(project, this.assetId, 'variables');
+    if (!asset) throw new CommandError(`Variables ${this.assetId} not found`);
+    return asset;
+  }
+}
+
 /**
  * Which state a machine starts in, as a state node's id – `''` takes the mark off again, and the
  * machine is back to starting in no state. Only one state can be the start because there is only

src/core/graph/savedValues.ts

@@ -1,6 +1,7 @@
 import type { VariablesAsset } from '../model/Asset';
 import type { PropertyBag, PropertyValue } from '../model/Properties';
 import type { Project } from '../model/Project';
+import { sharedScopeOf } from '../model/Scope';
 import { coerceValue } from '../properties/PropertySchema';
 
 /** What a save area holds: the values of each persistent Variables asset, keyed by asset id. */
@@ -15,8 +16,13 @@ export interface SaveArea {
   write(saved: SavedValues): void;
 }
 
+/**
+ * A `scene` asset is never persistent, whatever the flag says (#164): its values are thrown away
+ * with every scene, so there is nothing about them worth keeping between runs. Answered here rather
+ * than left to the commands, so no path can produce a saved value the scope would drop anyway.
+ */
 export function isPersistent(asset: VariablesAsset): boolean {
-  return asset.persistent === true;
+  return asset.persistent === true && sharedScopeOf(asset) !== 'scene';
 }
 
 function persistentAssets(project: Project): VariablesAsset[] {

src/core/graph/sharedState.ts

@@ -1,6 +1,6 @@
 import type { PropertyBag } from '../model/Properties';
 import type { Project } from '../model/Project';
-import { isGlobal } from '../model/Scope';
+import { isPerScene, isShared, sharedScopeOf } from '../model/Scope';
 import type { NodeContext, SharedState } from './NodeContext';
 import { startStateOf } from './stateMachine';
 
@@ -27,11 +27,40 @@ export function declaredVariables(project: Project): Record<string, PropertyBag>
 export function buildSharedState(project: Project): SharedState {
   const shared: SharedState = { variables: declaredVariables(project), states: {} };
   for (const asset of project.assets)
-    if (asset.type === 'statemachine' && isGlobal(asset))
+    if (asset.type === 'statemachine' && isShared(asset))
       shared.states[asset.id] = startStateOf(asset.graph, asset.start);
   return shared;
 }
 
+/**
+ * The state the next scene of the same run starts from: what is `global` travels as it stands,
+ * what is `scene` is built again from the declarations. Fresh bags rather than the carried ones,
+ * so the world before it cannot still be writing into what this one reads.
+ */
+export function carriedForward(project: Project, carried: Readonly<SharedState>): SharedState {
+  const fresh = buildSharedState(project);
+  const restarted = restartedAssets(project);
+  const next: SharedState = { variables: {}, states: {} };
+  for (const [id, bag] of Object.entries(fresh.variables))
+    next.variables[id] = restarted.has(id) ? bag : (carried.variables[id] ?? bag);
+  for (const [id, state] of Object.entries(fresh.states))
+    next.states[id] = restarted.has(id) ? state : (carried.states[id] ?? state);
+  return next;
+}
+
+/**
+ * The assets a scene swap starts over rather than hands on, by id: the `scene` Variables assets and
+ * the `scene` machines. Also what tells the new world which machines to announce an entry for.
+ */
+export function restartedAssets(project: Project): Set<string> {
+  const ids = new Set<string>();
+  for (const asset of project.assets) {
+    if (asset.type === 'variables' && sharedScopeOf(asset) === 'scene') ids.add(asset.id);
+    if (asset.type === 'statemachine' && isPerScene(asset)) ids.add(asset.id);
+  }
+  return ids;
+}
+
 /**
  * The start state of every machine that has a usable one, keyed by asset id. A machine without one
  * is absent, which is what keeps "no start" and "starts in a deleted state" the same thing.
@@ -80,7 +109,7 @@ export function variableBag(ctx: NodeContext, source: string): PropertyBag {
   return ctx.shared.variables[source] ?? {};
 }
 
-/** Where a machine's current state is kept: shared when the machine is `global`, else per instance. */
+/** Where a machine's current state is kept: shared unless the machine is `local`, else per instance. */
 export function stateBag(ctx: NodeContext, machineId: string): Record<string, string> {
   return machineId in ctx.shared.states ? ctx.shared.states : ctx.states;
 }

src/core/model/Asset.ts

@@ -43,11 +43,16 @@ export interface BehaviorAsset extends AssetBase {
  *
  * A `persistent` asset keeps its values past the end of the run (#166): the next run starts from
  * what the last one left, not from `props`. Absent is not persistent.
+ *
+ * `scope` says how long one set of values lives: absent is `global`, the whole run, and `scene`
+ * builds them again from the declarations with every scene that is loaded (#164). A `scene` asset
+ * is never persistent – what a scene swap throws away has nothing to keep between runs.
  */
 export interface VariablesAsset extends AssetBase {
   type: 'variables';
   variables: PropertyDef[];
   persistent?: boolean;
+  scope?: Scope;
 }
 
 /** Placed as a child of the object it belongs to; its position is the offset from that body. */
@@ -159,7 +164,8 @@ export interface AnimationAsset extends AssetBase {
 /**
  * The graph holds one `State` node per state and an edge per transition; a behavior reads the
  * machine's current state through `State branch` and moves it through `Set state` or `State transition`.
- * A `global` machine has one current state for the whole run instead of one per behavior instance.
+ * A `global` machine has one current state for the whole run instead of one per behavior instance;
+ * a `scene` machine shares one too, but starts over with every scene that is loaded (#164).
  *
  * `start` is the id of the state every instance begins in, empty when the machine has no start –
  * then it is in no state until `Set state` runs. It lives on the asset rather than on the node

src/core/model/Scope.ts

@@ -1,29 +1,60 @@
 /**
- * Whether a state machine keeps its current state per behavior instance or shares one for the whole
- * run. Everything was `local` before scopes existed, so a missing field means `local` and old
- * projects load unchanged. Variables are shared by living on a Variables asset instead (#91).
+ * How long a shared value lives. `local` is one per behavior instance, `global` one for the whole
+ * run, `scene` one per scene: rebuilt from the declarations whenever a scene is loaded, so what a
+ * level counts is gone with the level while a score is not (#164).
+ *
+ * Everything was `local` before scopes existed, so a missing field means `local` and old projects
+ * load unchanged. Variables are shared by living on a Variables asset instead (#91) – that asset is
+ * shared by its nature, so a missing field means `global` there (see `sharedScopeOf`).
  */
-export type Scope = 'local' | 'global';
+export type Scope = 'local' | 'global' | 'scene';
+
+/** The scopes of something that is shared either way: a Variables asset has no `local`. */
+export type SharedScope = 'global' | 'scene';
 
 export interface Scoped {
   scope?: Scope;
 }
 
 export function scopeOf(owner: Scoped): Scope {
-  return owner.scope === 'global' ? 'global' : 'local';
+  if (owner.scope === 'global') return 'global';
+  return owner.scope === 'scene' ? 'scene' : 'local';
 }
 
-export function isGlobal(owner: Scoped): boolean {
-  return owner.scope === 'global';
+/** Whether the value is shared at all: both `global` and `scene` are one value for many instances. */
+export function isShared(owner: Scoped): boolean {
+  return owner.scope === 'global' || owner.scope === 'scene';
 }
 
-/** Reads a scope out of loaded data, where anything but the one known word means `local`. */
+/** Whether a scene swap rebuilds the value instead of handing it over. */
+export function isPerScene(owner: Scoped): boolean {
+  return owner.scope === 'scene';
+}
+
+/** Reads a scope out of loaded data, where anything but the two known words means `local`. */
 export function readScope(raw: unknown): Scope {
-  return raw === 'global' ? 'global' : 'local';
+  if (raw === 'global') return 'global';
+  return raw === 'scene' ? 'scene' : 'local';
 }
 
-/** Keeps `local` out of the document: the field is present only when it says `global`. */
+/** Keeps `local` out of the document: the field is present only when it says more than that. */
 export function setScope(owner: Scoped, scope: Scope): void {
-  if (scope === 'global') owner.scope = 'global';
+  if (scope === 'local') delete owner.scope;
+  else owner.scope = scope;
+}
+
+/** The scope of something shared by nature, where a missing field is `global` rather than `local`. */
+export function sharedScopeOf(owner: Scoped): SharedScope {
+  return owner.scope === 'scene' ? 'scene' : 'global';
+}
+
+/** Reads the scope of something shared by nature out of loaded data. */
+export function readSharedScope(raw: unknown): SharedScope {
+  return raw === 'scene' ? 'scene' : 'global';
+}
+
+/** Keeps the default out of the document the other way round: only `scene` is written. */
+export function setSharedScope(owner: Scoped, scope: SharedScope): void {
+  if (scope === 'scene') owner.scope = 'scene';
   else delete owner.scope;
 }

src/core/store/serialize.ts

@@ -53,7 +53,7 @@ import {
   type Vec2,
 } from '../model/Properties';
 import { PROJECT_FORMAT_VERSION, type Project } from '../model/Project';
-import { readScope } from '../model/Scope';
+import { readScope, readSharedScope } from '../model/Scope';
 import type { SceneObject } from '../model/SceneObject';
 import {
   DEFAULT_FILL,
@@ -171,7 +171,9 @@ export function deserializeProject(raw: unknown, fallbackId = ''): Project {
       });
     } else if (type === 'variables') {
       const shared: VariablesAsset = { id, type, name, props, variables: variables.get(id) ?? [] };
-      if (a.persistent === true) shared.persistent = true;
+      // Scope first: a `scene` asset is never persistent, so the switch that cannot apply is dropped.
+      if (readSharedScope(a.scope) === 'scene') shared.scope = 'scene';
+      else if (a.persistent === true) shared.persistent = true;
       assets.push(shared);
     } else if (type === 'statemachine') {
       const machine: StateMachineAsset = {
@@ -181,7 +183,8 @@ export function deserializeProject(raw: unknown, fallbackId = ''): Project {
         props,
         graph: normalizeGraph(a.graph, (def) => def.type === STATE),
       };
-      if (readScope(a.scope) === 'global') machine.scope = 'global';
+      const scope = readScope(a.scope);
+      if (scope !== 'local') machine.scope = scope;
       // Kept as written even where it names no state any more: the same as a deleted start.
       if (typeof a.start === 'string' && a.start !== '') machine.start = a.start;
       assets.push(machine);