@jgengine/core 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -26,6 +26,69 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.38.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.38.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.35.0`; `@jgengine/github` is `0.25.0`.
+- Composing a session loop directly: pass your rule as `settle`, `carries: false` when nothing is carried, and your authored options as `offers`. `createRunLoop` is removed one minor release after Beacon Bastion and Drift Foundry stop using it.
+
+### Added
+
+- `GameMenu` and `GamePauseMenu` (`@jgengine/react/gameMenu`): a full-bleed menu surface over the live scene or drifting key art, with a token-sized logo, an animated navigable verb list, a generated selection tick and a detail pane per verb. The document scroll is locked while it is open, so the surface is exactly the viewport at any size.
+- Panes for the detail slot: `ContinuePane`, `NewCharacterPane`, `SaveSlotsPane` (slot cards with a `meta.thumbnail`, playtime, progress, timestamp and a two-press delete) and `CreditsPane` (`@jgengine/react/gameMenuSaves`).
+- `shrinkCapture` (`@jgengine/react/saveThumbnail`) turns a `captureCanvas` frame into a card-sized thumbnail data URL.
+- `createSessionLoop` (`@jgengine/core/run/sessionLoop`) is one session loop for every game: a session opens, may carry a quantity, closes at its boundary, and the game's own `settle` callback decides what happens to what it carried. `carries: false` for a session with nothing at stake, and an optional `offers` table (with `present`/`choose`) for a game whose next session opens with an authored change; without a table nothing is drawn. `installSessionProbe` reports the live session on `window.__jgengineRun`.
+
+### Changed
+
+- `switchSlot(slot, { flush: false })` (`@jgengine/core/game/gameSave`) loads a slot without first writing the live state over it. Opening a save from a menu uses it so Continue cannot overwrite the save it resumes.
+- The dev runner's registry and environment modules import outside Vite, so a test or tool can read them.
+- `createRunLoop` is now a thin composition of `createSessionLoop` and is deprecated: bank-or-lose and a per-run change table are one game type's rules, so they live in the composition instead of the base. Its API, state shape and tests are unchanged. One difference: the option draw is seeded under `:offer:` rather than `:run:` (`seededRng(\`${seed}:offer:${index}\`)`), so a career that keeps its seed draws a different change on a given session than 0.37.0 did for the same seed. Ids, payloads and saves stay valid: a saved `changeId` still restores the same change.
+
+### Fixed
+
+- `shoot` fails instead of writing a PNG when the whole frame is one flat colour, and when a scene is still behind its loading cover. Both used to write a plausible screenshot that read as evidence of a rendered frame.
+- The editor's play-mode pixel test waits for the warmup cover to clear before screenshotting. It shot the cover, so it read `0.9988` one-colour locally and passed in CI where the race fell the other way.
+- `shoot` prints the WebGL2 renderer it draws with and fails the capture outright when the launched browser has none.
+
+Root cause: capture readiness was trusted to mean "the scene has rendered", but a loading cover and a canvas that never committed both photograph as a flat frame, and nothing measured the frame after the fact. Headless Chrome on this PC was never the problem: it renders with the GPU (`ANGLE (NVIDIA GeForce RTX 3070, D3D11)`) and with SwiftShader when asked.
+
+Before: `bun run shoot --url <flat canvas page>` exited 0 and wrote a one-colour PNG, and `packages/editor/src/CreatorApp.test.ts` failed locally at `dominantColorShare 0.9988`.
+After: the same shoot exits 1 with `the whole frame is one flat color (100.0%) - no scene reached the capture - nothing was written`, and the editor test passes in 12s with sky and ground in the PNG.
+
+Cost: forcing SwiftShader on the same game shot costs 2.4x the capture (16.0s vs 6.7s warm, beacon-bastion play at half size), so the launch keeps the native GPU. The two checks add about 10ms to a shot.
+
+Verification:
+- `bun test scripts/shot-metrics.test.ts` - pass
+- `bun test packages/editor/src/CreatorApp.test.ts` - pass
+- `bun run shoot beacon-bastion --mode play --size half` - exit 0, scene renders
+- `bun run shoot --url <flat canvas page>` - exit 1, no PNG written
+- `bun run verify:fast` - pass
+
+The CI reliability fix this lane also carried (a browser setup hook shorter than Playwright's launch default) is #2335, so either change can be reverted without the other.
+- The publish workflow's last step no longer reports a whole release as unpublished because it ran seconds after `npm publish`. `check:release-artifacts --wait <seconds>` re-checks while the only failures are absent packages (no metadata, version missing, tarball 404) and gives up when the budget runs out; a wrong version in the tarball, a missing subpath or a main entry that will not import still fails on the first check. The 0.37.0 publish run failed this step at 04:48 listing all 13 packages, then npm served every one of them. The step now passes `-- --wait 300`.
+- A Playwright test file's `beforeAll` now outlives the Chrome launch it waits on, and `browser-test-budget` rejects a file that leaves the hook at or under Playwright's 30 s launch default. On `test (g)` in #2326 the hook's 30 s budget and that default expired together, so CI reported only `(unnamed) hook timed out` beside `killed 1 dangling process` and nothing named the launch.
+- `packages/react/src/dialogBehavior.test.ts` gives its browser navigation its own 20 s deadline and one retry inside a 60 s hook.
+
+Root cause: Bun prints a `beforeAll` timeout as an unnamed hook timeout, so a setup budget equal to Playwright's own 30 s launch default reports the anonymous timer instead of the launch that stalled.
+
+Before: `test (g)` on #2326 reported `(fail) (unnamed) [30001.51ms] ^ a beforeEach/afterEach hook timed out` and `killed 1 dangling process`.
+After: a stall now surfaces as Playwright's own `Timeout ... exceeded`, and `bun scripts/browser-test-budget.ts` names any file whose setup hook sits at or under the launch default.
+
+Verification:
+- `bun scripts/browser-test-budget.ts` - pass, and the new rule names the unraised files on the previous tip
+- `bun test scripts/browser-test-budget.test.ts` - pass
+- `bun test packages/react/src/dialogBehavior.test.ts packages/react/src/scrollRail.test.ts packages/shell/src/settingsBoundary.test.ts` - pass
+- `bun run verify:fast` - pass
+- A prop placed at runtime honours its model's `variants` levels. `StaticObjectModels` applied the level switch only inside its batched branch, so a prop placed with `scene.object.place` — Harbor Heat's palm line — drew its full asset at every camera distance: 15 palms at 9,134 triangles each, and pointing the far level at a dispatch booth changed nothing on screen. `IsolatedEntityModel` now mounts `SingleVariantModel`, which asks the same `createModelVariantSelector` and `lodBandIndex` authority the batched path uses, at the prop's own camera distance, and keeps only the active level mounted so both levels never draw at once. The switch carries the selector's hysteresis, warms every level at mount, measures only the near level, and reads the placement from the scene store through scratch vectors, so a frame allocates nothing. One palm past 60 m draws 4,110 triangles instead of 9,134 (5,024 saved, 45% of the full level).
+
+- `singleVariantLevel` and `singleVariantModel` (`@jgengine/shell` internal, `render/singleVariantLod`) are the isolated path's level decision and the model it draws, so a fixture pins the same switch the component runs.
+
+`bun test packages/shell/src/render/singleVariantLod.test.ts` — 6 pass. With the old render decision restored, the wiring test fails (`Expected: SingleVariantModel, Received: EntityModel`).
+`bun --cwd=packages/shell run test` — 1,229 pass, 0 fail.
+`bun --cwd=packages/shell run check-types` — clean.
+
 ## 0.37.0
 
 ### Migrate

package/dist/game/gameSave.d.ts

@@ -102,8 +102,14 @@ export interface GameSave {
     save(): Promise<void>;
     /** Read the active slot and apply every section to its system. */
     load(): Promise<GameSaveDocument>;
-    /** Flush the current slot, switch, and load the next one. */
-    switchSlot(slot: string): Promise<GameSaveDocument>;
+    /**
+     * Switch the active slot and load it. By default the live state is flushed into the slot being
+     * left first; pass `{ flush: false }` when opening a save from a menu, where the live state is
+     * either empty or already the slot being opened and flushing would overwrite the save.
+     */
+    switchSlot(slot: string, options?: {
+        flush?: boolean;
+    }): Promise<GameSaveDocument>;
     /**
      * Read a slot's document without applying it to the live systems — the save-select menu's data
      * source. Returns `null` for an empty slot.

package/dist/game/gameSave.js

@@ -137,8 +137,9 @@ export function createGameSave(config) {
             apply(document);
             return document;
         },
-        async switchSlot(slot) {
-            store.set(capture());
+        async switchSlot(slot, options) {
+            if (options?.flush !== false)
+                store.set(capture());
             const document = await store.switchSlot(slot);
             apply(document);
             return document;

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.37.0";
+export declare const VERSION = "0.38.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,42 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.37.0";
+export const VERSION = "0.38.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.38.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.38.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.35.0`; `@jgengine/github` is `0.25.0`.",
+            "Composing a session loop directly: pass your rule as `settle`, `carries: false` when nothing is carried, and your authored options as `offers`. `createRunLoop` is removed one minor release after Beacon Bastion and Drift Foundry stop using it.",
+        ],
+        added: [
+            "`GameMenu` and `GamePauseMenu` (`@jgengine/react/gameMenu`): a full-bleed menu surface over the live scene or drifting key art, with a token-sized logo, an animated navigable verb list, a generated selection tick and a detail pane per verb. The document scroll is locked while it is open, so the surface is exactly the viewport at any size.",
+            "Panes for the detail slot: `ContinuePane`, `NewCharacterPane`, `SaveSlotsPane` (slot cards with a `meta.thumbnail`, playtime, progress, timestamp and a two-press delete) and `CreditsPane` (`@jgengine/react/gameMenuSaves`).",
+            "`shrinkCapture` (`@jgengine/react/saveThumbnail`) turns a `captureCanvas` frame into a card-sized thumbnail data URL.",
+            "`createSessionLoop` (`@jgengine/core/run/sessionLoop`) is one session loop for every game: a session opens, may carry a quantity, closes at its boundary, and the game's own `settle` callback decides what happens to what it carried. `carries: false` for a session with nothing at stake, and an optional `offers` table (with `present`/`choose`) for a game whose next session opens with an authored change; without a table nothing is drawn. `installSessionProbe` reports the live session on `window.__jgengineRun`.",
+        ],
+        changed: [
+            "`switchSlot(slot, { flush: false })` (`@jgengine/core/game/gameSave`) loads a slot without first writing the live state over it. Opening a save from a menu uses it so Continue cannot overwrite the save it resumes.",
+            "The dev runner's registry and environment modules import outside Vite, so a test or tool can read them.",
+            "`createRunLoop` is now a thin composition of `createSessionLoop` and is deprecated: bank-or-lose and a per-run change table are one game type's rules, so they live in the composition instead of the base. Its API, state shape and tests are unchanged. One difference: the option draw is seeded under `:offer:` rather than `:run:` (`seededRng(\\`${seed}:offer:${index}\\`)`), so a career that keeps its seed draws a different change on a given session than 0.37.0 did for the same seed. Ids, payloads and saves stay valid: a saved `changeId` still restores the same change.",
+            "`shoot` fails instead of writing a PNG when the whole frame is one flat colour, and when a scene is still behind its loading cover. Both used to write a plausible screenshot that read as evidence of a rendered frame.",
+            "The editor's play-mode pixel test waits for the warmup cover to clear before screenshotting. It shot the cover, so it read `0.9988` one-colour locally and passed in CI where the race fell the other way.",
+            "`shoot` prints the WebGL2 renderer it draws with and fails the capture outright when the launched browser has none.",
+            "`bun test scripts/shot-metrics.test.ts` - pass",
+            "`bun test packages/editor/src/CreatorApp.test.ts` - pass",
+            "`bun run shoot beacon-bastion --mode play --size half` - exit 0, scene renders",
+            "`bun run shoot --url <flat canvas page>` - exit 1, no PNG written",
+            "`bun run verify:fast` - pass",
+            "The publish workflow's last step no longer reports a whole release as unpublished because it ran seconds after `npm publish`. `check:release-artifacts --wait <seconds>` re-checks while the only failures are absent packages (no metadata, version missing, tarball 404) and gives up when the budget runs out; a wrong version in the tarball, a missing subpath or a main entry that will not import still fails on the first check. The 0.37.0 publish run failed this step at 04:48 listing all 13 packages, then npm served every one of them. The step now passes `-- --wait 300`.",
+            "A Playwright test file's `beforeAll` now outlives the Chrome launch it waits on, and `browser-test-budget` rejects a file that leaves the hook at or under Playwright's 30 s launch default. On `test (g)` in #2326 the hook's 30 s budget and that default expired together, so CI reported only `(unnamed) hook timed out` beside `killed 1 dangling process` and nothing named the launch.",
+            "`packages/react/src/dialogBehavior.test.ts` gives its browser navigation its own 20 s deadline and one retry inside a 60 s hook.",
+            "`bun scripts/browser-test-budget.ts` - pass, and the new rule names the unraised files on the previous tip",
+            "`bun test scripts/browser-test-budget.test.ts` - pass",
+            "`bun test packages/react/src/dialogBehavior.test.ts packages/react/src/scrollRail.test.ts packages/shell/src/settingsBoundary.test.ts` - pass",
+            "`bun run verify:fast` - pass",
+            "A prop placed at runtime honours its model's `variants` levels. `StaticObjectModels` applied the level switch only inside its batched branch, so a prop placed with `scene.object.place` — Harbor Heat's palm line — drew its full asset at every camera distance: 15 palms at 9,134 triangles each, and pointing the far level at a dispatch booth changed nothing on screen. `IsolatedEntityModel` now mounts `SingleVariantModel`, which asks the same `createModelVariantSelector` and `lodBandIndex` authority the batched path uses, at the prop's own camera distance, and keeps only the active level mounted so both levels never draw at once. The switch carries the selector's hysteresis, warms every level at mount, measures only the near level, and reads the placement from the scene store through scratch vectors, so a frame allocates nothing. One palm past 60 m draws 4,110 triangles instead of 9,134 (5,024 saved, 45% of the full level).",
+            "`singleVariantLevel` and `singleVariantModel` (`@jgengine/shell` internal, `render/singleVariantLod`) are the isolated path's level decision and the model it draws, so a fixture pins the same switch the component runs.",
+        ],
+        removed: [],
+    },
     "0.37.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.37.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.34.0`; `@jgengine/github` is `0.24.0`.",

package/dist/run/runLoop.d.ts

@@ -113,12 +113,20 @@ export interface RunLoop<T> {
  * A run's haul banks when it ends in a bank and is lost when it ends in a loss; the money itself stays
  * with the game (pair it with `progression/careerBank`). After each settled run the loop draws the next
  * run's change from `changes`: eligible when `after <= completed`, never the change just played unless
- * it is the only one eligible, weighted by `weight`. The draw is `seededRng(seed:run:N)`, so the same
- * seed and the same run history give the same sequence, before or after a save/load. `present(count)`
- * draws several of those changes for a choice screen and `choose(id)` adopts the pick as the next run's
- * change.
+ * it is the only one eligible, weighted by `weight`. The draw is seeded, so the same seed and the same
+ * run history give the same sequence, before or after a save/load. `present(count)` draws several of
+ * those changes for a choice screen and `choose(id)` adopts the pick as the next run's change.
  *
- * @capability run-loop bank or lose what a run carries, with one deterministic change per run
+ * This is a composition of `createSessionLoop` (`run/sessionLoop`): the session loop owns opening,
+ * carrying, closing and restoring, and this module supplies the two things that make it a roguelike -
+ * a `settle` that banks or loses the haul, and a change table the next run can open with.
+ *
+ * @deprecated Bank-or-lose and a per-run change table are one game type's rules, not the engine's.
+ * Compose `createSessionLoop` with your own `settle` and `offers` instead. Kept unchanged for the two
+ * adopters (Beacon Bastion, Drift Foundry) that pin 0.37.0. Removal path: delete this module one minor
+ * release after both compose `createSessionLoop` directly.
+ *
+ * @capability run-loop deprecated roguelike composition of session-loop - bank or lose what a run carries, with one deterministic change per run
  */
 export declare function createRunLoop<T>(config: RunLoopConfig<T>): RunLoop<T>;
 /**
@@ -126,6 +134,9 @@ export declare function createRunLoop<T>(config: RunLoopConfig<T>): RunLoop<T>;
  * the live run, what it carries, what it banked or lost and the change it offers. Reads only; it never
  * starts, settles or changes a run. Returns the uninstaller.
  *
- * @capability run-loop bank or lose what a run carries, with one deterministic change per run
+ * @deprecated Ships with {@link createRunLoop}; compose `installSessionProbe` from `run/sessionLoop`
+ * when you compose the session loop directly.
+ *
+ * @capability run-loop deprecated roguelike composition of session-loop - bank or lose what a run carries, with one deterministic change per run
  */
 export declare function installRunProbe<T>(loop: RunLoop<T>): () => void;

package/dist/run/runLoop.js

@@ -1,5 +1,4 @@
-import { pickWeighted } from "../random/pick.js";
-import { seededRng } from "../random/rng.js";
+import { createSessionLoop } from "./sessionLoop.js";
 function positive(value) {
     return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
 }
@@ -9,113 +8,79 @@ function positive(value) {
  * A run's haul banks when it ends in a bank and is lost when it ends in a loss; the money itself stays
  * with the game (pair it with `progression/careerBank`). After each settled run the loop draws the next
  * run's change from `changes`: eligible when `after <= completed`, never the change just played unless
- * it is the only one eligible, weighted by `weight`. The draw is `seededRng(seed:run:N)`, so the same
- * seed and the same run history give the same sequence, before or after a save/load. `present(count)`
- * draws several of those changes for a choice screen and `choose(id)` adopts the pick as the next run's
- * change.
+ * it is the only one eligible, weighted by `weight`. The draw is seeded, so the same seed and the same
+ * run history give the same sequence, before or after a save/load. `present(count)` draws several of
+ * those changes for a choice screen and `choose(id)` adopts the pick as the next run's change.
  *
- * @capability run-loop bank or lose what a run carries, with one deterministic change per run
+ * This is a composition of `createSessionLoop` (`run/sessionLoop`): the session loop owns opening,
+ * carrying, closing and restoring, and this module supplies the two things that make it a roguelike -
+ * a `settle` that banks or loses the haul, and a change table the next run can open with.
+ *
+ * @deprecated Bank-or-lose and a per-run change table are one game type's rules, not the engine's.
+ * Compose `createSessionLoop` with your own `settle` and `offers` instead. Kept unchanged for the two
+ * adopters (Beacon Bastion, Drift Foundry) that pin 0.37.0. Removal path: delete this module one minor
+ * release after both compose `createSessionLoop` directly.
+ *
+ * @capability run-loop deprecated roguelike composition of session-loop - bank or lose what a run carries, with one deterministic change per run
  */
 export function createRunLoop(config) {
-    const table = config.changes ?? [];
-    const known = new Set();
-    for (const change of table) {
-        if (known.has(change.id))
-            throw new Error(`run change "${change.id}" is declared twice`);
-        known.add(change.id);
-    }
-    let run = 0;
-    let completed = 0;
-    let haul = 0;
-    let changeId = null;
     let bankedTotal = 0;
     let lostTotal = 0;
     let bestHaul = 0;
-    function drawFor(index, previous) {
-        const pool = poolFor(index, previous);
-        const rng = seededRng(`${config.seed}:run:${index}`);
-        const drawn = pickWeighted(rng, pool, (change) => change.weight ?? 1) ?? null;
-        return { run: index, changeId: drawn?.id ?? null, change: drawn?.value ?? null };
-    }
-    /** The changes run `index` may open with: `after`-eligible, and never the one just played while others remain. */
-    function poolFor(index, previous) {
-        const eligible = table.filter((change) => (change.after ?? 0) <= index - 1);
-        const fresh = eligible.filter((change) => change.id !== previous);
-        // A one-entry table still offers its change rather than nothing.
-        return fresh.length > 0 ? fresh : eligible;
-    }
-    function offer() {
-        // An open run's change was adopted at `start`, so the offer repeats it instead of redrawing.
-        if (run > completed) {
-            const adopted = table.find((change) => change.id === changeId);
-            return { run, changeId, change: adopted?.value ?? null };
-        }
-        return drawFor(completed + 1, changeId);
-    }
-    return {
-        start() {
-            if (run > completed)
-                return offer();
-            const next = offer();
-            run = next.run;
-            haul = 0;
-            changeId = next.changeId;
-            return next;
-        },
-        carry(amount) {
-            haul += positive(amount);
-            return haul;
-        },
-        haul: () => haul,
-        offer,
-        present(count) {
-            const index = run > completed ? run : completed + 1;
-            const remaining = poolFor(index, changeId);
-            const drawn = [];
-            const wanted = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;
-            const rng = seededRng(`${config.seed}:present:${index}`);
-            while (drawn.length < wanted && remaining.length > 0) {
-                const picked = pickWeighted(rng, remaining, (change) => change.weight ?? 1);
-                if (picked === undefined)
-                    break;
-                drawn.push({ id: picked.id, change: picked.value });
-                remaining.splice(remaining.indexOf(picked), 1);
-            }
-            return drawn;
-        },
-        choose(nextChangeId) {
-            if (nextChangeId !== null && !known.has(nextChangeId))
-                return false;
-            // A settled loop has no run to adopt the pick, so the pick opens the next one.
-            if (run <= completed) {
-                run = completed + 1;
-                haul = 0;
-            }
-            changeId = nextChangeId;
-            return true;
-        },
-        settle(outcome, multiplier) {
-            if (run <= completed)
-                throw new Error("run loop: no run is open to settle");
-            const settledHaul = haul;
-            const scale = Number.isFinite(multiplier) ? Math.max(0, multiplier ?? 1) : 1;
-            const banked = outcome === "banked" ? Math.round(settledHaul * scale) : 0;
-            const lost = outcome === "lost" ? settledHaul : 0;
+    const loop = createSessionLoop({
+        kind: "run",
+        seed: config.seed,
+        offers: config.changes,
+        settle: ({ carried, input }) => {
+            const scale = Number.isFinite(input.multiplier) ? Math.max(0, input.multiplier ?? 1) : 1;
+            const banked = input.outcome === "banked" ? Math.round(carried * scale) : 0;
+            const lost = input.outcome === "lost" ? carried : 0;
             bankedTotal += banked;
             lostTotal += lost;
             bestHaul = Math.max(bestHaul, banked);
-            completed = run;
-            haul = 0;
-            return { outcome, haul: settledHaul, banked, lost, completed, bestHaul, next: drawFor(completed + 1, changeId) };
+            return { banked, lost };
+        },
+    });
+    const offerOf = (offer) => ({
+        run: offer.session,
+        changeId: offer.optionId,
+        change: offer.option,
+    });
+    return {
+        start: () => offerOf(loop.start()),
+        carry: (amount) => loop.carry(amount),
+        haul: () => loop.carried(),
+        offer: () => offerOf(loop.offer()),
+        present: (count) => loop.present(count).map((choice) => ({ id: choice.id, change: choice.value })),
+        choose: (changeId) => loop.choose(changeId),
+        settle(outcome, multiplier) {
+            if (loop.phase() !== "open")
+                throw new Error("run loop: no run is open to settle");
+            const settlement = loop.settle({ outcome, multiplier });
+            return {
+                outcome,
+                haul: settlement.carried,
+                banked: settlement.result.banked,
+                lost: settlement.result.lost,
+                completed: settlement.closed,
+                bestHaul,
+                next: offerOf(settlement.next),
+            };
+        },
+        snapshot() {
+            const state = loop.snapshot();
+            return {
+                run: state.session,
+                completed: state.closed,
+                haul: state.carried,
+                changeId: state.optionId,
+                bankedTotal,
+                lostTotal,
+                bestHaul,
+            };
         },
-        snapshot: () => ({ run, completed, haul, changeId, bankedTotal, lostTotal, bestHaul }),
         restore(next) {
-            run = Math.max(0, Math.floor(next.run));
-            completed = Math.max(0, Math.floor(next.completed));
-            if (run < completed)
-                run = completed;
-            haul = positive(next.haul);
-            changeId = next.changeId !== null && known.has(next.changeId) ? next.changeId : null;
+            loop.restore({ session: next.run, closed: next.completed, carried: next.haul, optionId: next.changeId });
             bankedTotal = positive(next.bankedTotal);
             lostTotal = positive(next.lostTotal);
             bestHaul = positive(next.bestHaul);
@@ -128,7 +93,10 @@ const RUN_PROBE_KEY = "__jgengineRun";
  * the live run, what it carries, what it banked or lost and the change it offers. Reads only; it never
  * starts, settles or changes a run. Returns the uninstaller.
  *
- * @capability run-loop bank or lose what a run carries, with one deterministic change per run
+ * @deprecated Ships with {@link createRunLoop}; compose `installSessionProbe` from `run/sessionLoop`
+ * when you compose the session loop directly.
+ *
+ * @capability run-loop deprecated roguelike composition of session-loop - bank or lose what a run carries, with one deterministic change per run
  */
 export function installRunProbe(loop) {
     const scope = globalThis;

package/dist/run/sessionLoop.d.ts

@@ -0,0 +1,152 @@
+/** Where a session stands: not opened yet, in progress, or closed at its boundary. */
+export type SessionPhase = "idle" | "open" | "closed";
+/**
+ * One option the next session may open with. `T` is the game's own payload (a tighter rival line, an
+ * unlocked part, a shorter route) - the loop only draws and remembers which id was drawn.
+ */
+export interface SessionOfferOption<T> {
+    id: string;
+    value: T;
+    /** Relative draw weight (default `1`); a non-positive weight is never drawn. */
+    weight?: number;
+    /** Sessions that must close before this option can be drawn (default `0`). */
+    after?: number;
+}
+/** The option a session opens with, and which session it is. */
+export interface SessionOffer<T> {
+    /** 1-based session number: `1` is the first session, before any boundary has closed. */
+    session: number;
+    optionId: string | null;
+    option: T | null;
+}
+/** One option the next session could open with, in the shape a choice screen shows. */
+export interface SessionChoice<T> {
+    id: string;
+    value: T;
+}
+/** The session closing, handed to a game's own `settle`. */
+export interface SettlingSession<I = void> {
+    /** 1-based number of the session closing. */
+    session: number;
+    /** The quantity the session carried to its boundary; `0` when the game carries nothing. */
+    carried: number;
+    /** The game's own reason for closing, passed to `settle`. */
+    input: I;
+}
+/** What closing one session did, and what the next session opens with. */
+export interface SessionSettlement<R = void, T = never> {
+    /** The session that closed. */
+    session: number;
+    /** The quantity it carried to its boundary. */
+    carried: number;
+    /** Sessions closed so far. */
+    closed: number;
+    /** What the game's `settle` returned. */
+    result: R;
+    /** The option the next session opens with. */
+    next: SessionOffer<T>;
+}
+/** What the loop reports about the session it is playing, for a capture or devtools read. */
+export interface SessionReadout {
+    /** The session in progress, or the last one started when none is open. */
+    session: number;
+    phase: SessionPhase;
+    /** What a session is in this game, or `null` when the game did not say. */
+    kind: string | null;
+    /** What the session in progress carries. */
+    carried: number;
+    closed: number;
+    /** The option the session in progress opened with, or the one the next session is offered. */
+    offered: string | null;
+}
+/** Read-only handle a capture or devtools uses to prove a session loop is live, not merely imported. */
+export interface SessionProbe {
+    read(): SessionReadout;
+}
+/** Everything a session loop stores as plain JSON. */
+export interface SessionLoopState {
+    /** The session in progress, or the last one started; `0` before the first `start`. */
+    session: number;
+    /** Sessions whose boundary has closed; also the number `after` gates are read against. */
+    closed: number;
+    /** The quantity the session in progress carries. */
+    carried: number;
+    /** The option the session in progress opened with, or the one the next session opens with. */
+    optionId: string | null;
+}
+/** Configuration for {@link createSessionLoop}. */
+export interface SessionLoopConfig<T = never, I = void, R = void> {
+    /** What a session is, for the readout: `"day"`, `"shift"`, `"wave"`. */
+    kind?: string;
+    /** Whether a session carries a quantity (default `true`); `false` makes {@link SessionLoop.carry} inert. */
+    carries?: boolean;
+    /**
+     * What the boundary does with what the session carried: the game's own rule, so bank, lose, keep and
+     * nothing are all one callback. Omitted means closing a session only closes it.
+     */
+    settle?: (session: SettlingSession<I>) => R;
+    /** Authored options the next session may open with. Omitted means sessions never open with one. */
+    offers?: readonly SessionOfferOption<T>[];
+    /** Seed for the option draw (default `"session"`): the same seed and history replay the same sequence. */
+    seed?: string | number;
+}
+/**
+ * One session's lifecycle: open it, carry a quantity, close it at its boundary, and optionally open
+ * the next one with an option the game authored.
+ */
+export interface SessionLoop<T = never, I = void, R = void> {
+    /** What a session is in this game, or `null` when the game did not say. */
+    kind(): string | null;
+    /** Open the next session and hand back its offer. Calling it on an open session returns that session's offer and keeps what it carries. */
+    start(): SessionOffer<T>;
+    /** Add to what the session in progress carries; negative or non-finite amounts are ignored. Returns what it carries. */
+    carry(amount: number): number;
+    /** What the session in progress carries. */
+    carried(): number;
+    /** Whether no session has opened, one is open, or the last one closed. */
+    phase(): SessionPhase;
+    /** The open session's offer, or the offer the next `start` would open with. */
+    offer(): SessionOffer<T>;
+    /**
+     * Up to `count` distinct options the next session could open with, drawn weighted and in draw order,
+     * so a game can offer a choice instead of the single option {@link SessionOffer} names. `choose` takes one.
+     */
+    present(count: number): SessionChoice<T>[];
+    /**
+     * Open the next session around `optionId` (or around no option for `null`), which is how a presented
+     * choice becomes the option the session carries. Returns false for an id this loop's table does not
+     * carry, leaving the offer untouched.
+     */
+    choose(optionId: string | null): boolean;
+    /**
+     * Close the session in progress and hand what it carried to the game's `settle` rule. Throws when no
+     * session is open, so a double close cannot settle the same quantity twice.
+     */
+    settle(input?: I): SessionSettlement<R, T>;
+    snapshot(): SessionLoopState;
+    restore(next: SessionLoopState): void;
+}
+/**
+ * The shared shape of a game session, with the game's own rules supplied as config: a session opens,
+ * it may carry a quantity, its boundary closes it, and the game's `settle` callback decides what
+ * happens to what it carried. A park day, a night shift and a wave are the same base with a different
+ * `settle`, a different `kind` and, where nothing is at stake, `carries: false`.
+ *
+ * `offers` is optional and defaults to nothing, so a game whose sessions never differ says nothing:
+ * sessions open plain. A game that wants its next session to open with an authored change supplies the
+ * table and gets the same draw rules everywhere - eligible when `after <= closed`, never the option
+ * just played unless it is the only one eligible, weighted by `weight`, drawn as
+ * `seededRng(seed:offer:N)` so the same seed and history replay the same sequence before or after a
+ * save/load. `present(count)` draws several for a choice screen and `choose(id)` adopts the pick.
+ *
+ * @capability session-loop open and close a game session, settle the quantity it carried and optionally draw the next session's authored option
+ */
+export declare function createSessionLoop<T = never, I = void, R = void>(config?: SessionLoopConfig<T, I, R>): SessionLoop<T, I, R>;
+/**
+ * Publish the loop's own readout on `window.__jgengineRun`, so a capture or devtools probe can state
+ * which session is live, its phase, what it carries and the option it offers. Reads only; it never
+ * starts, closes or changes a session. Returns the uninstaller.
+ *
+ * @capability session-loop open and close a game session, settle the quantity it carried and optionally draw the next session's authored option
+ */
+export declare function installSessionProbe<T, I, R>(loop: SessionLoop<T, I, R>): () => void;

package/dist/run/sessionLoop.js

@@ -0,0 +1,151 @@
+import { pickWeighted } from "../random/pick.js";
+import { seededRng } from "../random/rng.js";
+function positive(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function count(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+ * The shared shape of a game session, with the game's own rules supplied as config: a session opens,
+ * it may carry a quantity, its boundary closes it, and the game's `settle` callback decides what
+ * happens to what it carried. A park day, a night shift and a wave are the same base with a different
+ * `settle`, a different `kind` and, where nothing is at stake, `carries: false`.
+ *
+ * `offers` is optional and defaults to nothing, so a game whose sessions never differ says nothing:
+ * sessions open plain. A game that wants its next session to open with an authored change supplies the
+ * table and gets the same draw rules everywhere - eligible when `after <= closed`, never the option
+ * just played unless it is the only one eligible, weighted by `weight`, drawn as
+ * `seededRng(seed:offer:N)` so the same seed and history replay the same sequence before or after a
+ * save/load. `present(count)` draws several for a choice screen and `choose(id)` adopts the pick.
+ *
+ * @capability session-loop open and close a game session, settle the quantity it carried and optionally draw the next session's authored option
+ */
+export function createSessionLoop(config = {}) {
+    const table = config.offers ?? [];
+    const carries = config.carries !== false;
+    const seed = config.seed ?? "session";
+    const known = new Set();
+    for (const option of table) {
+        if (known.has(option.id))
+            throw new Error(`session option "${option.id}" is declared twice`);
+        known.add(option.id);
+    }
+    let session = 0;
+    let closed = 0;
+    let carried = 0;
+    let optionId = null;
+    const isOpen = () => session > closed;
+    function poolFor(index, previous) {
+        const eligible = table.filter((option) => (option.after ?? 0) <= index - 1);
+        const fresh = eligible.filter((option) => option.id !== previous);
+        // A one-entry table still offers its option rather than nothing.
+        return fresh.length > 0 ? fresh : eligible;
+    }
+    function drawFor(index, previous) {
+        const rng = seededRng(`${seed}:offer:${index}`);
+        const drawn = pickWeighted(rng, poolFor(index, previous), (option) => option.weight ?? 1) ?? null;
+        return { session: index, optionId: drawn?.id ?? null, option: drawn?.value ?? null };
+    }
+    function offer() {
+        // An open session's option was adopted at `start` or `choose`, so the offer repeats it instead of redrawing.
+        if (isOpen()) {
+            const adopted = table.find((option) => option.id === optionId);
+            return { session, optionId, option: adopted?.value ?? null };
+        }
+        return drawFor(closed + 1, optionId);
+    }
+    return {
+        kind: () => config.kind ?? null,
+        start() {
+            if (isOpen())
+                return offer();
+            const next = offer();
+            session = next.session;
+            carried = 0;
+            optionId = next.optionId;
+            return next;
+        },
+        carry(amount) {
+            if (carries)
+                carried += positive(amount);
+            return carried;
+        },
+        carried: () => carried,
+        phase: () => (session === 0 && closed === 0 ? "idle" : isOpen() ? "open" : "closed"),
+        offer,
+        present(wanted) {
+            const index = isOpen() ? session : closed + 1;
+            const remaining = poolFor(index, optionId);
+            const drawn = [];
+            const take = Number.isFinite(wanted) ? Math.max(0, Math.floor(wanted)) : 0;
+            const rng = seededRng(`${seed}:present:${index}`);
+            while (drawn.length < take && remaining.length > 0) {
+                const picked = pickWeighted(rng, remaining, (option) => option.weight ?? 1);
+                if (picked === undefined)
+                    break;
+                drawn.push({ id: picked.id, value: picked.value });
+                remaining.splice(remaining.indexOf(picked), 1);
+            }
+            return drawn;
+        },
+        choose(nextOptionId) {
+            if (nextOptionId !== null && !known.has(nextOptionId))
+                return false;
+            // A closed loop has no session to adopt the pick, so the pick opens the next one.
+            if (!isOpen()) {
+                session = closed + 1;
+                carried = 0;
+            }
+            optionId = nextOptionId;
+            return true;
+        },
+        settle(input) {
+            if (!isOpen())
+                throw new Error("session loop: no session is open to settle");
+            const settling = { session, carried, input: input };
+            const result = config.settle === undefined ? undefined : config.settle(settling);
+            closed = session;
+            carried = 0;
+            return { session: settling.session, carried: settling.carried, closed, result, next: drawFor(closed + 1, optionId) };
+        },
+        snapshot: () => ({ session, closed, carried, optionId }),
+        restore(next) {
+            session = count(next.session);
+            closed = count(next.closed);
+            if (session < closed)
+                session = closed;
+            carried = carries ? positive(next.carried) : 0;
+            optionId = next.optionId !== null && known.has(next.optionId) ? next.optionId : null;
+        },
+    };
+}
+const SESSION_PROBE_KEY = "__jgengineRun";
+/**
+ * Publish the loop's own readout on `window.__jgengineRun`, so a capture or devtools probe can state
+ * which session is live, its phase, what it carries and the option it offers. Reads only; it never
+ * starts, closes or changes a session. Returns the uninstaller.
+ *
+ * @capability session-loop open and close a game session, settle the quantity it carried and optionally draw the next session's authored option
+ */
+export function installSessionProbe(loop) {
+    const scope = globalThis;
+    const probe = {
+        read() {
+            const state = loop.snapshot();
+            return {
+                session: state.session,
+                phase: loop.phase(),
+                kind: loop.kind(),
+                carried: state.carried,
+                closed: state.closed,
+                offered: loop.offer().optionId,
+            };
+        },
+    };
+    scope[SESSION_PROBE_KEY] = probe;
+    return () => {
+        if (scope[SESSION_PROBE_KEY] === probe)
+            delete scope[SESSION_PROBE_KEY];
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.37.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.38.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.37.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.38.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-gameplay/api.md

@@ -2699,6 +2699,22 @@
 - `createRunLoop` (function): function createRunLoop<T>(config: RunLoopConfig<T>): RunLoop<T> — Bank-or-lose between runs, with one deterministic change per run drawn from an authored table.
 - `installRunProbe` (function): function installRunProbe<T>(loop: RunLoop<T>): () => void — Publish the loop's own readout on `window.__jgengineRun`, so a capture or devtools probe can state the live run, what it carries, what it banked or lost and the change it offers. Reads only; it never starts, settles or changes a run. Returns the uninstaller.
 
+## @jgengine/core/run/sessionLoop
+
+- `SessionChoice` (interface): interface SessionChoice<T> — One option the next session could open with, in the shape a choice screen shows.
+- `SessionLoop` (interface): interface SessionLoop<T = never, I = void, R = void> — One session's lifecycle: open it, carry a quantity, close it at its boundary, and optionally open the next one with an option the game authored.
+- `SessionLoopConfig` (interface): interface SessionLoopConfig<T = never, I = void, R = void> — Configuration for {@link createSessionLoop}.
+- `SessionLoopState` (interface): interface SessionLoopState — Everything a session loop stores as plain JSON.
+- `SessionOffer` (interface): interface SessionOffer<T> — The option a session opens with, and which session it is.
+- `SessionOfferOption` (interface): interface SessionOfferOption<T> — One option the next session may open with. `T` is the game's own payload (a tighter rival line, an unlocked part, a shorter route) - the loop only draws and remembers which id was drawn.
+- `SessionPhase` (type): type SessionPhase = "idle" | "open" | "closed" — Where a session stands: not opened yet, in progress, or closed at its boundary.
+- `SessionProbe` (interface): interface SessionProbe — Read-only handle a capture or devtools uses to prove a session loop is live, not merely imported.
+- `SessionReadout` (interface): interface SessionReadout — What the loop reports about the session it is playing, for a capture or devtools read.
+- `SessionSettlement` (interface): interface SessionSettlement<R = void, T = never> — What closing one session did, and what the next session opens with.
+- `SettlingSession` (interface): interface SettlingSession<I = void> — The session closing, handed to a game's own `settle`.
+- `createSessionLoop` (function): function createSessionLoop<T = never, I = void, R = void>(config: SessionLoopConfig<T, I, R> = {}): SessionLoop<T, I, R> — The shared shape of a game session, with the game's own rules supplied as config: a session opens, it may carry a quantity, its boundary closes it, and the game's `settle` callback decides what happens to what it carried. A park day, a night shift and a wave are the same base with a different `settle`, a different `kind` and, where nothing is at stake, `carries: false`.
+- `installSessionProbe` (function): function installSessionProbe<T, I, R>(loop: SessionLoop<T, I, R>): () => void — Publish the loop's own readout on `window.__jgengineRun`, so a capture or devtools probe can state which session is live, its phase, what it carries and the option it offers. Reads only; it never starts, closes or changes a session. Returns the uninstaller.
+
 ## @jgengine/core/session/contestedChannel
 
 - `ContestReaction` (type): type ContestReaction = "pause" | "decay" — ⚠ undocumented

package/skills/jgengine-gameplay/capabilities.md

@@ -649,7 +649,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `rerollRules` (function) · `import { rerollRules } from "@jgengine/core/gameplay"`
 - `selectRules` (function) · `import { selectRules } from "@jgengine/core/gameplay"`
 
-## run-loop — bank or lose what a run carries, with one deterministic change per run
+## run-loop — deprecated roguelike composition of session-loop - bank or lose what a run carries, with one deterministic change per run
 
 - `createRunLoop` (function) · `import { createRunLoop } from "@jgengine/core/run/runLoop"`
 - `installRunProbe` (function) · `import { installRunProbe } from "@jgengine/core/run/runLoop"`
@@ -678,6 +678,11 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `seededRng` (function) · `import { seededRng } from "@jgengine/core/gameplay"`
 
+## session-loop — open and close a game session, settle the quantity it carried and optionally draw the next session's authored option
+
+- `createSessionLoop` (function) · `import { createSessionLoop } from "@jgengine/core/run/sessionLoop"`
+- `installSessionProbe` (function) · `import { installSessionProbe } from "@jgengine/core/run/sessionLoop"`
+
 ## set — a bounded keyed value in a caller-owned serializable record
 
 - `setValue` (function) · `import { setValue } from "@jgengine/core/gameplay"`