@jgengine/core 0.36.0 → 0.38.0

package/dist/physics/physicsBackendConformance.js

@@ -38,6 +38,23 @@ export function runPhysicsBackendConformance(create, harness) {
         expect(state.position[1]).toBeLessThan(0.7);
         expect(Math.abs(state.velocity[1])).toBeLessThan(0.5);
     });
+    test("the same wall-clock time simulates the same distance at 30, 60 and 144 fps", () => {
+        // A backend that honours `fixedDt` as one step per call simulates `fixedDt * fps` seconds per
+        // second of real time — half speed at 30 fps, 2.4x at 144 fps. Horizontal travel ignores the
+        // integrator, so the distance is exactly `v * realSeconds` for any backend that accumulates.
+        const backend = create();
+        const travelled = [];
+        for (const fps of [30, 60, 144]) {
+            const ball = backend.addBody({ shape: { kind: "sphere", radius: 0.2 }, position: [0, 8, 0], velocity: [10, 0, 0] });
+            for (let i = 0; i < fps; i += 1)
+                backend.step(1 / fps);
+            travelled.push(backend.body(ball).position[0]);
+            backend.removeBody(ball);
+        }
+        const spread = Math.max(...travelled) - Math.min(...travelled);
+        expect(travelled[1]).toBeGreaterThan(8);
+        expect(spread).toBeLessThan(0.2);
+    });
     test("raycast reports the floor with an upward normal and the right distance", () => {
         const backend = create();
         const ground = floor(backend);

package/dist/physics/physicsWorld.d.ts

@@ -276,6 +276,13 @@ export declare class PhysicsWorld {
     getStats(): PhysicsStats;
     private substep;
     private constrainBounds;
+    /**
+     * Coulomb friction against the bounds floor, using the same `friction` coefficient a contact
+     * applies: horizontal speed bleeds by `friction * |gravity| * dt` per substep. The old
+     * multiplicative form (`* (1 - friction)` every substep) removed 60 × 40% per second, so a body
+     * on the world floor stopped ~6× shorter than the same body on a static floor collider.
+     */
+    private applyFloorFriction;
     /**
      * Walk every broadphase cell body `i`'s AABB overlaps, invoking `visit(cell)` once per cell. The
      * cell-range math (six `cellCoord` calls plus the row-major triple loop) lives here so the count

package/dist/physics/physicsWorld.js

@@ -565,7 +565,7 @@ export class PhysicsWorld {
             this.posX[i] += this.velX[i] * dt;
             this.posY[i] += this.velY[i] * dt;
             this.posZ[i] += this.velZ[i] * dt;
-            this.constrainBounds(i);
+            this.constrainBounds(i, dt, true);
         }
         this.buildGrid();
         const iterations = this.solverIterations;
@@ -575,10 +575,10 @@ export class PhysicsWorld {
                 this.solveJoints(dt);
         }
         for (let a = 0; a < this.awakeCount; a += 1)
-            this.constrainBounds(this.awakeList[a]);
+            this.constrainBounds(this.awakeList[a], dt, false);
         this.updateSleep();
     }
-    constrainBounds(i) {
+    constrainBounds(i, dt, frictionPass) {
         const min = this.bounds.min;
         const max = this.bounds.max;
         const e = this.restitution;
@@ -613,9 +613,8 @@ export class PhysicsWorld {
             this.posY[i] = loY;
             if (this.velY[i] < 0)
                 this.velY[i] = -this.velY[i] < rt ? 0 : this.velY[i] * -e;
-            const tf = 1 - this.friction;
-            this.velX[i] *= tf;
-            this.velZ[i] *= tf;
+            if (frictionPass)
+                this.applyFloorFriction(i, dt);
         }
         else if (this.posY[i] > hiY) {
             this.posY[i] = hiY;
@@ -623,6 +622,28 @@ export class PhysicsWorld {
                 this.velY[i] = this.velY[i] < rt ? 0 : -this.velY[i] * e;
         }
     }
+    /**
+     * Coulomb friction against the bounds floor, using the same `friction` coefficient a contact
+     * applies: horizontal speed bleeds by `friction * |gravity| * dt` per substep. The old
+     * multiplicative form (`* (1 - friction)` every substep) removed 60 × 40% per second, so a body
+     * on the world floor stopped ~6× shorter than the same body on a static floor collider.
+     */
+    applyFloorFriction(i, dt) {
+        const decel = this.friction * Math.abs(this.gravity) * dt;
+        if (!(decel > 0))
+            return;
+        const vx = this.velX[i];
+        const vz = this.velZ[i];
+        const speed = Math.sqrt(vx * vx + vz * vz);
+        if (speed <= decel) {
+            this.velX[i] = 0;
+            this.velZ[i] = 0;
+            return;
+        }
+        const keep = (speed - decel) / speed;
+        this.velX[i] = vx * keep;
+        this.velZ[i] = vz * keep;
+    }
     /**
      * Walk every broadphase cell body `i`'s AABB overlaps, invoking `visit(cell)` once per cell. The
      * cell-range math (six `cellCoord` calls plus the row-major triple loop) lives here so the count

package/dist/run/runLoop.d.ts

@@ -19,6 +19,28 @@ export interface RunOffer<T> {
     changeId: string | null;
     change: T | null;
 }
+/** One change a run could open with, in the shape a choice screen shows: the id and its payload. */
+export interface RunChoice<T> {
+    id: string;
+    change: T;
+}
+/** What the loop reports about the run it is playing, for a capture or devtools read. */
+export interface RunReadout {
+    /** The run in progress, or the last settled run when none is open. */
+    run: number;
+    /** What the run in progress carries and can still lose. */
+    carried: number;
+    banked: number;
+    lost: number;
+    /** The best single bank across the career. */
+    best: number;
+    /** The change the run in progress opened with, or the one the next run is offered. */
+    offered: string | null;
+}
+/** Read-only handle a capture or devtools uses to prove a run loop is live, not merely imported. */
+export interface RunProbe {
+    read(): RunReadout;
+}
 /** Everything a run loop stores as plain JSON: the run in progress plus lifetime totals. */
 export interface RunLoopState {
     /** The run in progress, or `0` before the first `start`. */
@@ -66,6 +88,17 @@ export interface RunLoop<T> {
     haul(): number;
     /** The run in progress's offer, or the offer the next `start` would open. */
     offer(): RunOffer<T>;
+    /**
+     * Up to `count` distinct changes the next run could open with, drawn weighted and in draw order,
+     * so a game can offer a choice instead of the single change {@link RunOffer} names. `choose` takes one.
+     */
+    present(count: number): RunChoice<T>[];
+    /**
+     * Open the next run around `changeId` (or around no change for `null`), which is how a presented
+     * choice becomes the change the run carries. Returns false for an id this loop's table does not
+     * carry, leaving the offer untouched.
+     */
+    choose(changeId: string | null): boolean;
     /**
      * Close the run in progress: bank the haul scaled by `multiplier`, or lose it. Throws when no run
      * is open, so a double settle cannot bank the same haul twice.
@@ -80,9 +113,30 @@ 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.
+ * 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.
+ *
+ * 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 bank or lose what a run carries, with one deterministic change per run
+ * @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>;
+/**
+ * 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.
+ *
+ * @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,84 +8,114 @@ 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.
+ * 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 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.
-        const pool = fresh.length > 0 ? fresh : eligible;
-        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 };
-    }
-    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,
-        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);
         },
     };
 }
+const RUN_PROBE_KEY = "__jgengineRun";
+/**
+ * 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.
+ *
+ * @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;
+    const probe = {
+        read() {
+            const state = loop.snapshot();
+            return {
+                run: state.run,
+                carried: state.haul,
+                banked: state.bankedTotal,
+                lost: state.lostTotal,
+                best: state.bestHaul,
+                offered: loop.offer().changeId,
+            };
+        },
+    };
+    scope[RUN_PROBE_KEY] = probe;
+    return () => {
+        if (scope[RUN_PROBE_KEY] === probe)
+            delete scope[RUN_PROBE_KEY];
+    };
+}

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];
+    };
+}