@driftengine/core 3.61.0

package/dist/core/loadTracker.d.ts

@@ -0,0 +1,78 @@
+/** Aggregating everything an app is waiting on into one honest number. */
+/**
+ * One thing being waited for.
+ *
+ * `weight` is what makes the total mean anything. A progress bar that treats "decode 58 audio
+ * tracks" and "read a settings file" as half each spends most of its life at 50%, which is worse
+ * than no bar: it teaches a viewer that the bar is decoration. Weights are in whatever unit the
+ * caller likes as long as they are the same unit — bytes are the obvious one because they are
+ * usually known in advance, and a rough guess in "seconds this normally takes" also works.
+ */
+export interface LoadTask {
+    /** Stable, and not for showing: a caller maps it to whatever words its audience needs. */
+    readonly id: string;
+    readonly weight: number;
+    /** 0 to 1. */
+    fraction: number;
+    done: boolean;
+}
+export interface LoadSummary {
+    /** 0 to 1 across everything registered, weighted. */
+    readonly fraction: number;
+    /**
+     * The id of the task the caller should be talking about: the heaviest one still unfinished.
+     *
+     * Heaviest rather than first-registered, because that is the one a viewer is actually waiting
+     * for. Empty when nothing is outstanding.
+     */
+    readonly activeId: string;
+    readonly done: boolean;
+    readonly tasksDone: number;
+    readonly tasksTotal: number;
+}
+/**
+ * What an app is waiting on, as one weighted number.
+ *
+ * **Why this is in the engine.** Every consumer builds this, and every one of them builds it
+ * slightly wrong in the same way: a bar driven by whichever load happens to report last, or a
+ * fraction over a task count that jumps in sevenths, or a spinner that says nothing at all. None
+ * of that is a game's decision — it is arithmetic over a set of things with sizes — so it belongs
+ * here beside the things that produce the sizes. What stays with the consumer is every word: this
+ * hands back ids and numbers, because what to *call* a stage depends entirely on who is reading.
+ *
+ * **It holds no clock and no DOM.** A caller polls `summary` in its own frame, so a tracker works
+ * the same in a browser, a test and a headless bake.
+ *
+ * Deliberately small. It does not start work, own promises, retry, or time out: a task is
+ * something the caller is already doing, and all this knows is how big it is and how far along.
+ * Anything more would be a scheduler, which is a different thing with different failure modes.
+ */
+export declare class LoadTracker {
+    private readonly tasks;
+    /**
+     * Declare something to wait for, or re-declare it with a new weight.
+     *
+     * Registering the same id twice is deliberately allowed and is not a reset: a caller frequently
+     * learns the real size of a thing after starting it — a fetch that finally reports its
+     * `Content-Length`, a model whose manifest says how many parts are coming — and having to choose
+     * between a wrong weight and a lost fraction would be a bad choice to force.
+     */
+    add(id: string, weight: number): void;
+    /** How far along one task is, 0 to 1. Unknown ids are ignored rather than thrown at. */
+    report(id: string, fraction: number): void;
+    /** Mark one finished, whatever it last reported. */
+    finish(id: string): void;
+    /**
+     * A task that turned out not to be needed: dropped from the total rather than completed.
+     *
+     * The distinction matters for the number. An optional asset that is absent — no model baked, a
+     * track with no audio — is not 100% loaded, it is not part of this load at all, and counting it
+     * as finished makes the bar say a thing arrived that never did.
+     */
+    drop(id: string): void;
+    /** Nothing to wait for. A tracker with no tasks is done, which is the useful answer. */
+    get summary(): LoadSummary;
+    /** Every task, for a caller that wants to show a line each rather than one bar. */
+    get entries(): readonly LoadTask[];
+    clear(): void;
+}

package/dist/core/loadTracker.js

@@ -0,0 +1,106 @@
+/** Aggregating everything an app is waiting on into one honest number. */
+/**
+ * What an app is waiting on, as one weighted number.
+ *
+ * **Why this is in the engine.** Every consumer builds this, and every one of them builds it
+ * slightly wrong in the same way: a bar driven by whichever load happens to report last, or a
+ * fraction over a task count that jumps in sevenths, or a spinner that says nothing at all. None
+ * of that is a game's decision — it is arithmetic over a set of things with sizes — so it belongs
+ * here beside the things that produce the sizes. What stays with the consumer is every word: this
+ * hands back ids and numbers, because what to *call* a stage depends entirely on who is reading.
+ *
+ * **It holds no clock and no DOM.** A caller polls `summary` in its own frame, so a tracker works
+ * the same in a browser, a test and a headless bake.
+ *
+ * Deliberately small. It does not start work, own promises, retry, or time out: a task is
+ * something the caller is already doing, and all this knows is how big it is and how far along.
+ * Anything more would be a scheduler, which is a different thing with different failure modes.
+ */
+export class LoadTracker {
+    tasks = new Map();
+    /**
+     * Declare something to wait for, or re-declare it with a new weight.
+     *
+     * Registering the same id twice is deliberately allowed and is not a reset: a caller frequently
+     * learns the real size of a thing after starting it — a fetch that finally reports its
+     * `Content-Length`, a model whose manifest says how many parts are coming — and having to choose
+     * between a wrong weight and a lost fraction would be a bad choice to force.
+     */
+    add(id, weight) {
+        const existing = this.tasks.get(id);
+        const safeWeight = Number.isFinite(weight) && weight > 0 ? weight : 1;
+        if (existing === undefined) {
+            this.tasks.set(id, { id, weight: safeWeight, fraction: 0, done: false });
+            return;
+        }
+        this.tasks.set(id, {
+            id,
+            weight: safeWeight,
+            fraction: existing.fraction,
+            done: existing.done,
+        });
+    }
+    /** How far along one task is, 0 to 1. Unknown ids are ignored rather than thrown at. */
+    report(id, fraction) {
+        const task = this.tasks.get(id);
+        if (task === undefined)
+            return;
+        /*
+         * Clamped and guarded, because this is fed by arithmetic a caller did — a division by a total
+         * that has not arrived yet is one edit away, and a NaN here would spread to the whole bar and
+         * then to whatever the bar drives.
+         */
+        const safe = Number.isFinite(fraction) ? Math.min(1, Math.max(0, fraction)) : 0;
+        task.fraction = task.done ? 1 : safe;
+    }
+    /** Mark one finished, whatever it last reported. */
+    finish(id) {
+        const task = this.tasks.get(id);
+        if (task === undefined)
+            return;
+        task.fraction = 1;
+        task.done = true;
+    }
+    /**
+     * A task that turned out not to be needed: dropped from the total rather than completed.
+     *
+     * The distinction matters for the number. An optional asset that is absent — no model baked, a
+     * track with no audio — is not 100% loaded, it is not part of this load at all, and counting it
+     * as finished makes the bar say a thing arrived that never did.
+     */
+    drop(id) {
+        this.tasks.delete(id);
+    }
+    /** Nothing to wait for. A tracker with no tasks is done, which is the useful answer. */
+    get summary() {
+        let weighted = 0;
+        let total = 0;
+        let doneCount = 0;
+        let activeId = '';
+        let activeWeight = -1;
+        for (const task of this.tasks.values()) {
+            total += task.weight;
+            weighted += task.weight * (task.done ? 1 : task.fraction);
+            if (task.done)
+                doneCount++;
+            else if (task.weight > activeWeight) {
+                activeWeight = task.weight;
+                activeId = task.id;
+            }
+        }
+        return {
+            fraction: total > 0 ? Math.min(1, weighted / total) : 1,
+            activeId,
+            done: activeId === '',
+            tasksDone: doneCount,
+            tasksTotal: this.tasks.size,
+        };
+    }
+    /** Every task, for a caller that wants to show a line each rather than one bar. */
+    get entries() {
+        return [...this.tasks.values()];
+    }
+    clear() {
+        this.tasks.clear();
+    }
+}

package/dist/core/loop.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Fixed-timestep game loop with render interpolation.
+ *
+ * Simulation always advances in `fixedDt` increments (determinism requirement,
+ * see AGENTS.md); rendering runs once per animation frame and receives the
+ * interpolation factor `alpha` in [0, 1) between the two most recent sim states.
+ */
+export interface LoopHooks {
+    /**
+     * Advance the simulation by exactly `dt` seconds.
+     *
+     * `tick` counts fixed steps from `LoopOptions.startTick`, and it is the identity every
+     * networked and recorded thing indexes by: an input belongs to a tick, a snapshot is of a tick,
+     * a desync begins at a tick. `AGENTS.md` already states the contract it makes concrete — "time
+     * is a tick count the caller supplies" — and the loop was the one place that knew the count and
+     * did not hand it over, so a caller wanting one kept a second counter beside this callback and
+     * hoped the two agreed.
+     *
+     * A caller with no use for it takes one argument and is unaffected.
+     */
+    simulate(dt: number, tick: number): void;
+    /**
+     * Draw one frame. `alpha` interpolates prev→current sim state.
+     *
+     * `frameDt` is clamped by `maxFrameTime` and is the one to animate against:
+     * a stall must not advance the wind by a minute when the page comes back.
+     *
+     * `wallDt` is the same gap with nothing done to it, and it exists for the
+     * diagnostics. A clamped delta cannot tell a device that took a quarter second
+     * from a browser that waited a second before asking — both arrive as 0.25 —
+     * and three bug reports were filed on that ambiguity before anyone could see it.
+     * Nothing that animates should read it.
+     */
+    /**
+     * @param frame What the frame source delivered, when it delivers anything.
+     *
+     * `undefined` under the window, which is every frame outside a session. An immersive session
+     * hands over the object every pose in that frame is read from, and it is valid only for the
+     * duration of this call. Typed `unknown` because core does not name an `XRFrame`; the package
+     * that does narrows it. An implementation written before this parameter existed still satisfies
+     * the interface, which is why it was added at the end rather than anywhere more readable.
+     */
+    render(alpha: number, frameDt: number, wallDt: number, frame?: unknown): void;
+    /**
+     * Whether the simulation should advance this frame. Absent means always.
+     *
+     * Pause is expressed here rather than by stopping the loop, so a paused game
+     * keeps rendering — the world stays on screen behind the menu instead of
+     * freezing on whatever the last frame happened to be.
+     */
+    shouldSimulate?: () => boolean;
+    /**
+     * Whether this frame is worth drawing at all. Absent means always.
+     *
+     * For the clip export, and it is not an optimisation. A clip is a fixed 60
+     * frames a second; a display running at 144 offers 2.4 animation frames per
+     * clip frame, and the recorder can only take one of them — so the other 1.4
+     * are a full render of a 1080x1920 frame that is thrown away, competing for the
+     * GPU with the one that is kept. Worse, on a 100 Hz display no frame lands
+     * near enough to every slot and the capture rate falls to 50: the file then
+     * claims 60 fps while holding 50, which is precisely the stutter this exists to
+     * remove.
+     *
+     * Skipped time is not lost — it is added to the `frameDt` the next drawn frame
+     * receives, so anything smoothing against it sees real elapsed time.
+     *
+     * **The 60 above is the example and not a limit**, which is worth saying because every sentence
+     * of it names one. This hook is a predicate the caller supplies, so the rate is whatever the
+     * caller returns true at, and `FramePacer` takes the rate it paces to as a constructor argument:
+     * `new FramePacer(30)` is a thirty-a-second export and needs nothing here. A consumer capturing
+     * at 60 and dropping every other frame is paying a full render per discarded frame for a rate the
+     * pacer would have given them.
+     */
+    shouldRender?: () => boolean;
+}
+export interface LoopOptions {
+    fixedDt?: number;
+    /** Clamp for pathological frames (tab switch, debugger) to avoid a sim spiral. */
+    maxFrameTime?: number;
+    /**
+     * The tick number the first fixed step reports. Zero unless a caller says otherwise.
+     *
+     * A participant joining a session in progress is told the host's tick and has to agree with it,
+     * because every input and every snapshot is addressed by that number. Starting at zero and
+     * adding an offset at each use is the same arithmetic done in more places, and one of them
+     * eventually forgets.
+     */
+    startTick?: number;
+    /**
+     * Who asks for the next frame, and what that frame carries.
+     *
+     * **The window, unless a session is driving.** An immersive session produces frames on the
+     * headset's clock through `session.requestAnimationFrame`, at whatever rate its display runs, and
+     * the callback carries the frame object every pose in that frame is read from. A loop calling the
+     * window's `requestAnimationFrame` inside a session draws at the page's rate into a display that
+     * wanted something else, which is the difference between presence and motion sickness.
+     *
+     * Optional and defaulting to the window, so no existing caller changes.
+     *
+     * `frame` is `unknown` deliberately. This file is `@driftengine/core`'s clock and has no business
+     * naming an `XRFrame`, which lives in a package core does not depend on; `@driftengine/xr`
+     * narrows it at the one place that reads it. What core owns is that *something* arrived with the
+     * frame and is handed to `render` unread.
+     */
+    frameSource?: FrameSource;
+}
+/**
+ * A source of animation frames. `window` satisfies it, and so does an `XRSession`.
+ *
+ * Structural rather than a class, because both of the things that satisfy it are somebody else's:
+ * one is the browser's and one is a runtime's.
+ */
+export interface FrameSource {
+    requestAnimationFrame(callback: (timeMs: number, frame?: unknown) => void): number;
+    cancelAnimationFrame(handle: number): void;
+}
+/** Starts the loop immediately. Returns a stop function. */
+export declare function startLoop(hooks: LoopHooks, options?: LoopOptions): () => void;

package/dist/core/loop.js

@@ -0,0 +1,84 @@
+import { framesHeld } from './bootGate.js';
+/** Starts the loop immediately. Returns a stop function. */
+export function startLoop(hooks, options = {}) {
+    const fixedDt = options.fixedDt ?? 1 / 60;
+    const maxFrameTime = options.maxFrameTime ?? 0.25;
+    let last = performance.now();
+    let accumulator = 0;
+    /**
+     * Fixed steps taken, offset by `startTick`.
+     *
+     * **It counts steps and not frames, and it never moves while paused.** A tick is a unit of
+     * simulation, so a paused game that keeps rendering is at the same tick for as long as the menu
+     * is open — which is what makes the number usable as an index into a recording.
+     */
+    let tick = Math.trunc(options.startTick ?? 0);
+    let rafId = 0;
+    /** Frame time banked by animation frames that were not drawn. */
+    let undrawnDt = 0;
+    /** The same bank, unclamped. See `LoopHooks.render`. */
+    let undrawnWallDt = 0;
+    /*
+     * Read once and held. A session that ends mid-loop is a consumer stopping this loop and starting
+     * another, because the two run at different rates and share no accumulator worth carrying across.
+     */
+    const source = options.frameSource ?? {
+        requestAnimationFrame: (callback) => requestAnimationFrame(callback),
+        cancelAnimationFrame: (handle) => {
+            cancelAnimationFrame(handle);
+        },
+    };
+    const frame = (now, xrFrame) => {
+        rafId = source.requestAnimationFrame(frame);
+        /*
+         * **Held: draw nothing, advance nothing, and bank nothing.**
+         *
+         * The engine badge holds the screen for a few seconds after the first frame reaches it, and
+         * a game left running behind an opaque plate is a game whose opening seconds nobody sees —
+         * an intro that plays to a black rectangle, a cue that is already three seconds in when the
+         * plate lifts. Freezing on the drawn frame is what makes the badge a hold rather than a
+         * theft.
+         *
+         * `last` moves with the clock so the wait is not banked. Without that line every held frame
+         * accumulates, and the resume replays the whole hold in one step: the same failure the pause
+         * above drops its accumulator for, arrived at from a different direction.
+         */
+        if (framesHeld()) {
+            last = now;
+            accumulator = 0;
+            return;
+        }
+        let frameDt = (now - last) / 1000;
+        last = now;
+        const wallDt = frameDt;
+        if (frameDt > maxFrameTime)
+            frameDt = maxFrameTime;
+        accumulator += frameDt;
+        // Paused: drop the banked time rather than keeping it. Holding it would
+        // replay the whole pause in one resume frame, and every one of those ticks
+        // would land in a run timer that M4 turns into a leaderboard entry.
+        if (hooks.shouldSimulate !== undefined && !hooks.shouldSimulate()) {
+            accumulator = 0;
+        }
+        else {
+            while (accumulator >= fixedDt) {
+                hooks.simulate(fixedDt, tick);
+                tick += 1;
+                accumulator -= fixedDt;
+            }
+        }
+        if (hooks.shouldRender !== undefined && !hooks.shouldRender()) {
+            undrawnDt += frameDt;
+            undrawnWallDt += wallDt;
+            return;
+        }
+        /* Handed on unread. See `LoopOptions.frameSource` for why core does not look inside it. */
+        hooks.render(accumulator / fixedDt, frameDt + undrawnDt, wallDt + undrawnWallDt, xrFrame);
+        undrawnDt = 0;
+        undrawnWallDt = 0;
+    };
+    rafId = source.requestAnimationFrame(frame);
+    return () => {
+        source.cancelAnimationFrame(rafId);
+    };
+}

package/dist/core/messageQueue.d.ts

@@ -0,0 +1,61 @@
+/**
+ * One transient message at a time, in priority order.
+ *
+ * Games fire events in bursts — finishing a run can produce three at once — and
+ * three notifications stacked on top of each other is worse than one, because
+ * the player reads none of them. This holds the backlog and hands back a single
+ * current message, so the presentation layer never has to decide what to drop.
+ *
+ * Pure state and no DOM: what a notification *looks* like is the game's, and
+ * the part with rules worth pinning down is which one is on screen.
+ */
+export interface QueuedMessage {
+    /** Identity, used to collapse a repeat of the same event. */
+    readonly id: string;
+    /** Higher wins, both for ordering and for interrupting. */
+    readonly priority: number;
+    /** How long it holds the screen once current. */
+    readonly durationMs: number;
+}
+export interface MessageQueueOptions {
+    /**
+     * How long the same id is ignored after being shown.
+     *
+     * The realistic source of duplicates is a caller pushing from a per-frame
+     * check rather than an edge — sixty identical toasts a second, a bug that
+     * presents as the interface freezing on one message.
+     */
+    readonly dedupeWindowMs?: number;
+    /**
+     * Backlog ceiling. Without one, a caller pushing in a loop grows the queue
+     * forever and the player spends the next minute watching notifications from
+     * something that happened once.
+     */
+    readonly maxPending?: number;
+}
+export declare class MessageQueue<T extends QueuedMessage = QueuedMessage> {
+    private readonly pending;
+    private readonly lastShown;
+    private readonly dedupeWindowMs;
+    private readonly maxPending;
+    private showing;
+    private showingUntil;
+    constructor(options?: MessageQueueOptions);
+    get current(): T | null;
+    push(message: T): void;
+    /**
+     * Advance. Returns a message only on the frame it becomes current, so the
+     * caller can render it once rather than diffing against what it drew last.
+     */
+    update(nowMs: number): T | null;
+    /** Drop everything, including what is on screen — as a restart must. */
+    clear(): void;
+    private show;
+    private takeBest;
+    /**
+     * Index of the highest-priority pending message, dropping recent repeats on
+     * the way past. Ties go to the earliest, so equally important events arrive
+     * in the order they actually happened.
+     */
+    private bestIndex;
+}

package/dist/core/messageQueue.js

@@ -0,0 +1,104 @@
+export class MessageQueue {
+    pending = [];
+    lastShown = new Map();
+    dedupeWindowMs;
+    maxPending;
+    showing = null;
+    showingUntil = 0;
+    constructor(options = {}) {
+        this.dedupeWindowMs = options.dedupeWindowMs ?? 900;
+        this.maxPending = options.maxPending ?? 6;
+    }
+    get current() {
+        return this.showing;
+    }
+    push(message) {
+        this.pending.push(message);
+        if (this.pending.length <= this.maxPending)
+            return;
+        // Drop the least important rather than the oldest: a backlog that has
+        // overflowed is exactly when the one thing that mattered must survive.
+        let worst = 0;
+        for (let i = 1; i < this.pending.length; i++) {
+            const candidate = this.pending[i];
+            const incumbent = this.pending[worst];
+            if (candidate === undefined || incumbent === undefined)
+                continue;
+            if (candidate.priority < incumbent.priority)
+                worst = i;
+        }
+        this.pending.splice(worst, 1);
+    }
+    /**
+     * Advance. Returns a message only on the frame it becomes current, so the
+     * caller can render it once rather than diffing against what it drew last.
+     */
+    update(nowMs) {
+        if (this.showing !== null) {
+            /*
+             * Peeked, not taken. Removing the challenger and pushing it back when it
+             * loses reordered the backlog on every single frame, so two equally
+             * important messages arrived in whichever order the frame boundary
+             * happened to fall — which is not an order at all.
+             */
+            const challenger = this.pending[this.bestIndex(nowMs)];
+            // Something more important interrupts; anything else waits its turn. A
+            // personal best arriving during a minor toast is the moment of the run,
+            // and making it queue behind one buries it.
+            if (challenger !== undefined && challenger.priority > this.showing.priority) {
+                const taken = this.takeBest(nowMs);
+                if (taken !== null) {
+                    this.pending.push(this.showing);
+                    return this.show(taken, nowMs);
+                }
+            }
+            if (nowMs < this.showingUntil)
+                return null;
+            this.showing = null;
+        }
+        const next = this.takeBest(nowMs);
+        return next === null ? null : this.show(next, nowMs);
+    }
+    /** Drop everything, including what is on screen — as a restart must. */
+    clear() {
+        this.pending.length = 0;
+        this.lastShown.clear();
+        this.showing = null;
+        this.showingUntil = 0;
+    }
+    show(message, nowMs) {
+        this.showing = message;
+        this.showingUntil = nowMs + message.durationMs;
+        this.lastShown.set(message.id, nowMs);
+        return message;
+    }
+    takeBest(nowMs) {
+        const index = this.bestIndex(nowMs);
+        if (index < 0)
+            return null;
+        return this.pending.splice(index, 1)[0] ?? null;
+    }
+    /**
+     * Index of the highest-priority pending message, dropping recent repeats on
+     * the way past. Ties go to the earliest, so equally important events arrive
+     * in the order they actually happened.
+     */
+    bestIndex(nowMs) {
+        let best = -1;
+        for (let i = 0; i < this.pending.length; i++) {
+            const candidate = this.pending[i];
+            if (candidate === undefined)
+                continue;
+            const shownAt = this.lastShown.get(candidate.id);
+            if (shownAt !== undefined && nowMs - shownAt < this.dedupeWindowMs) {
+                this.pending.splice(i, 1);
+                i--;
+                continue;
+            }
+            const incumbent = this.pending[best];
+            if (incumbent === undefined || candidate.priority > incumbent.priority)
+                best = i;
+        }
+        return best;
+    }
+}

package/dist/core/onceSet.d.ts

@@ -0,0 +1,27 @@
+import type { KeyValueStore } from './storage.ts';
+/**
+ * A persisted set of one-time flags: tutorial prompts, first-run hints,
+ * "you have seen this" markers.
+ *
+ * One key holding a set rather than a key per flag, because a game accumulates
+ * dozens of these and a key each turns a player's save into a junk drawer that
+ * cannot be cleared in one action.
+ *
+ * Where it persists is the store's problem. When the store cannot keep
+ * anything, flags last the session — showing a tutorial once per visit is mildly
+ * annoying, while never showing it strands a player who arrived from a link
+ * with no idea what the controls are.
+ */
+export declare class OnceSet {
+    private readonly key;
+    private readonly store;
+    private readonly seen;
+    constructor(key: string, store?: KeyValueStore);
+    has(id: string): boolean;
+    /** True the first time only. Marks the flag as a side effect. */
+    claim(id: string): boolean;
+    mark(id: string): void;
+    /** Forget everything — "show me the tutorial again". */
+    clear(): void;
+    private persist;
+}

package/dist/core/onceSet.js

@@ -0,0 +1,62 @@
+import { defaultStore } from './storage.js';
+/**
+ * A persisted set of one-time flags: tutorial prompts, first-run hints,
+ * "you have seen this" markers.
+ *
+ * One key holding a set rather than a key per flag, because a game accumulates
+ * dozens of these and a key each turns a player's save into a junk drawer that
+ * cannot be cleared in one action.
+ *
+ * Where it persists is the store's problem. When the store cannot keep
+ * anything, flags last the session — showing a tutorial once per visit is mildly
+ * annoying, while never showing it strands a player who arrived from a link
+ * with no idea what the controls are.
+ */
+export class OnceSet {
+    key;
+    store;
+    seen;
+    constructor(key, store = defaultStore()) {
+        this.key = key;
+        this.store = store;
+        this.seen = new Set(readIds(store, key));
+    }
+    has(id) {
+        return this.seen.has(id);
+    }
+    /** True the first time only. Marks the flag as a side effect. */
+    claim(id) {
+        if (this.seen.has(id))
+            return false;
+        this.mark(id);
+        return true;
+    }
+    mark(id) {
+        if (this.seen.has(id))
+            return;
+        this.seen.add(id);
+        this.persist();
+    }
+    /** Forget everything — "show me the tutorial again". */
+    clear() {
+        this.seen.clear();
+        this.persist();
+    }
+    persist() {
+        this.store.write(this.key, JSON.stringify([...this.seen]));
+    }
+}
+function readIds(store, key) {
+    const raw = store.read(key);
+    if (raw === null)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((id) => typeof id === 'string');
+    }
+    catch {
+        return [];
+    }
+}