@jgengine/core 0.14.0 → 0.15.0

package/dist/ui/accessibility.js

@@ -0,0 +1,83 @@
+/** The out-of-the-box accessibility state (all assistance off, `textScale` 1). */
+export const DEFAULT_ACCESSIBILITY = {
+    reducedMotion: false,
+    highContrast: false,
+    textScale: 1,
+    colorblind: "none",
+    captions: false,
+};
+/** Minimum UI text scale. */
+export const TEXT_SCALE_MIN = 0.75;
+/** Maximum UI text scale. */
+export const TEXT_SCALE_MAX = 2;
+/** Clamp a text-scale multiplier into the supported `[TEXT_SCALE_MIN, TEXT_SCALE_MAX]` range. */
+export function clampTextScale(scale) {
+    if (Number.isNaN(scale))
+        return 1;
+    return Math.max(TEXT_SCALE_MIN, Math.min(TEXT_SCALE_MAX, scale));
+}
+/** Return `ms` when motion is allowed, or `reduced` (default 0) when `reducedMotion` is set — the animation-duration gate. */
+export function reducedMotionDuration(state, ms, reduced = 0) {
+    return state.reducedMotion ? reduced : ms;
+}
+/**
+ * `feColorMatrix` `values` strings for each colorblind mode — simulate how a
+ * viewer with that condition perceives color (and a grayscale mode). `"none"`
+ * maps to `null` (no filter). Consumed by the React `ColorblindFilters` defs.
+ */
+export const COLORBLIND_MATRICES = {
+    none: null,
+    protanopia: "0.567 0.433 0 0 0  0.558 0.442 0 0 0  0 0.242 0.758 0 0  0 0 0 1 0",
+    deuteranopia: "0.625 0.375 0 0 0  0.7 0.3 0 0 0  0 0.3 0.7 0 0  0 0 0 1 0",
+    tritanopia: "0.95 0.05 0 0 0  0 0.433 0.567 0 0  0 0.475 0.525 0 0  0 0 0 1 0",
+    grayscale: "0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0 0 0 1 0",
+};
+/**
+ * Serializable, observable store of accessibility preferences (reduced motion,
+ * high contrast, text scale, colorblind mode, captions). Genre-agnostic plumbing
+ * like input rebinding — a game binds these to its settings UI and adapts its
+ * presentation; `snapshot`/`restore` round-trip through a save or settings blob.
+ *
+ * @capability accessibility-store serializable, observable accessibility preferences (reduced motion, high contrast, text scale, colorblind mode, captions) a game binds to its settings and presentation
+ */
+export function createAccessibilityStore(initial = {}) {
+    let state = normalize({ ...DEFAULT_ACCESSIBILITY, ...initial });
+    const listeners = new Set();
+    function normalize(next) {
+        return { ...next, textScale: clampTextScale(next.textScale) };
+    }
+    function commit(next) {
+        const normalized = normalize(next);
+        if (normalized.reducedMotion === state.reducedMotion &&
+            normalized.highContrast === state.highContrast &&
+            normalized.textScale === state.textScale &&
+            normalized.colorblind === state.colorblind &&
+            normalized.captions === state.captions) {
+            return;
+        }
+        state = normalized;
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        get() {
+            return state;
+        },
+        set(patch) {
+            commit({ ...state, ...patch });
+        },
+        reset() {
+            commit({ ...DEFAULT_ACCESSIBILITY });
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return state;
+        },
+        restore(snapshot) {
+            commit({ ...DEFAULT_ACCESSIBILITY, ...snapshot });
+        },
+    };
+}

package/dist/ui/coachMarks.d.ts

@@ -0,0 +1,99 @@
+/** Where a coach-mark callout sits relative to its anchor (or `"center"` for an unanchored callout). */
+export type CoachMarkPlacement = "top" | "bottom" | "left" | "right" | "center";
+/** One onboarding hint: an ordered, optionally-anchored, optionally-gated callout. */
+export interface CoachMarkStep {
+    /** Stable id — also the key tracked in the persisted "seen" set. */
+    id: string;
+    title: string;
+    body?: string;
+    /**
+     * CSS selector (or a logical key the presenter resolves) for the element the
+     * callout points at. Omitted → the step renders as a centered callout.
+     */
+    anchor?: string;
+    /** Preferred side of the anchor. Default `"bottom"` when anchored, `"center"` otherwise. */
+    placement?: CoachMarkPlacement;
+    /**
+     * Serializable trigger id. While set, the step stays hidden until that id is
+     * in the sequence's satisfied set (see {@link CoachMarkSequence.satisfy}).
+     * Kept data-first — a string, not a function — so a whole sequence serializes.
+     */
+    condition?: string;
+}
+/** The active step plus its position, returned by {@link CoachMarkSequence.current}. */
+export interface CoachMarkView {
+    /** The step to render. */
+    step: CoachMarkStep;
+    /** 0-based position of this step within the full ordered list. */
+    index: number;
+    /** Total number of steps in the sequence. */
+    total: number;
+    /** Un-seen steps left, including this one (for an "N of M" style counter). */
+    remaining: number;
+}
+/** Serializable persisted state — the seen set (with timestamps) and satisfied triggers. */
+export interface CoachMarkSnapshot {
+    /** Ids of steps that have been advanced past, dismissed, or skipped. */
+    seen: readonly string[];
+    /** When each seen id was first marked, from the injected clock. */
+    seenAt: Readonly<Record<string, number>>;
+    /** Currently-satisfied trigger ids (gate state). */
+    satisfied: readonly string[];
+}
+/** Options for {@link createCoachMarkSequence}. */
+export interface CoachMarkSequenceOptions {
+    /** Ordered hint steps. */
+    steps: readonly CoachMarkStep[];
+    /** Injected clock (ms) used to timestamp when a step is marked seen. Default `Date.now`. */
+    now?: () => number;
+    /** Ids of steps already seen (e.g. restored from a save) so they never re-show. */
+    seen?: Iterable<string>;
+    /** Trigger ids already satisfied when the sequence starts. */
+    satisfied?: Iterable<string>;
+}
+/** An ordered, observable, serializable onboarding coach-mark run. */
+export interface CoachMarkSequence {
+    /** The configured steps, in order. */
+    readonly steps: readonly CoachMarkStep[];
+    /** First un-seen step whose condition (if any) is satisfied, or `null` when none is eligible. */
+    current(): CoachMarkView | null;
+    /** Mark the current step seen and return the next eligible step (or `null`). */
+    advance(): CoachMarkView | null;
+    /** Alias of {@link CoachMarkSequence.advance}. */
+    next(): CoachMarkView | null;
+    /** Mark a specific step seen so it never re-shows. */
+    dismiss(id: string): void;
+    /** Mark every step seen — "skip tour". */
+    skipAll(): void;
+    /** Add trigger ids to the satisfied set, un-gating any steps waiting on them. */
+    satisfy(...triggerIds: string[]): void;
+    /** Replace the satisfied trigger set wholesale (e.g. re-derived from game state). */
+    setSatisfied(triggerIds: Iterable<string>): void;
+    /** Whether the given trigger id is currently satisfied. */
+    isTriggerSatisfied(triggerId: string): boolean;
+    /** Whether a step id has been seen. */
+    isSeen(id: string): boolean;
+    /** Clock time a step was first seen, or `undefined` if not yet seen. */
+    seenAt(id: string): number | undefined;
+    /** True once every step has been seen. */
+    isComplete(): boolean;
+    /** How many steps remain un-seen (whether or not currently gated). */
+    remaining(): number;
+    /** Observe changes (advance, dismiss, satisfy, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): CoachMarkSnapshot;
+    /** Restore from a {@link CoachMarkSnapshot}. */
+    restore(snapshot: CoachMarkSnapshot): void;
+}
+/**
+ * An onboarding coach-mark run: an ordered sequence of hint steps, each shown as
+ * a centered callout or anchored to a UI element, with a persisted "seen" set so
+ * completed onboarding stays done across sessions, and data-first condition
+ * gating so a step waits until its trigger id is satisfied. Advance/skip/dismiss
+ * drive it; `snapshot`/`restore` round-trip the seen set through a save. Purely a
+ * model — a React host renders `current()`.
+ *
+ * @capability coach-marks ordered, gated, persist-once onboarding coach-marks/tutorial callouts — anchored or centered steps with a seen set and Next/Skip
+ */
+export declare function createCoachMarkSequence(options: CoachMarkSequenceOptions): CoachMarkSequence;

package/dist/ui/coachMarks.js

@@ -0,0 +1,126 @@
+/**
+ * An onboarding coach-mark run: an ordered sequence of hint steps, each shown as
+ * a centered callout or anchored to a UI element, with a persisted "seen" set so
+ * completed onboarding stays done across sessions, and data-first condition
+ * gating so a step waits until its trigger id is satisfied. Advance/skip/dismiss
+ * drive it; `snapshot`/`restore` round-trip the seen set through a save. Purely a
+ * model — a React host renders `current()`.
+ *
+ * @capability coach-marks ordered, gated, persist-once onboarding coach-marks/tutorial callouts — anchored or centered steps with a seen set and Next/Skip
+ */
+export function createCoachMarkSequence(options) {
+    const steps = [...options.steps];
+    const now = options.now ?? Date.now;
+    const seenAtMap = new Map();
+    let satisfied = new Set(options.satisfied ?? []);
+    const listeners = new Set();
+    for (const id of options.seen ?? []) {
+        if (!seenAtMap.has(id))
+            seenAtMap.set(id, now());
+    }
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function markSeen(id) {
+        if (seenAtMap.has(id))
+            return false;
+        seenAtMap.set(id, now());
+        return true;
+    }
+    function eligible(step) {
+        if (seenAtMap.has(step.id))
+            return false;
+        return step.condition === undefined || satisfied.has(step.condition);
+    }
+    function remaining() {
+        let count = 0;
+        for (const step of steps)
+            if (!seenAtMap.has(step.id))
+                count += 1;
+        return count;
+    }
+    function current() {
+        for (let index = 0; index < steps.length; index += 1) {
+            const step = steps[index];
+            if (eligible(step)) {
+                return { step, index, total: steps.length, remaining: remaining() };
+            }
+        }
+        return null;
+    }
+    return {
+        steps,
+        current,
+        advance() {
+            const active = current();
+            if (active !== null && markSeen(active.step.id))
+                notify();
+            return current();
+        },
+        next() {
+            return this.advance();
+        },
+        dismiss(id) {
+            if (markSeen(id))
+                notify();
+        },
+        skipAll() {
+            let changed = false;
+            for (const step of steps)
+                if (markSeen(step.id))
+                    changed = true;
+            if (changed)
+                notify();
+        },
+        satisfy(...triggerIds) {
+            let changed = false;
+            for (const id of triggerIds) {
+                if (!satisfied.has(id)) {
+                    satisfied.add(id);
+                    changed = true;
+                }
+            }
+            if (changed)
+                notify();
+        },
+        setSatisfied(triggerIds) {
+            satisfied = new Set(triggerIds);
+            notify();
+        },
+        isTriggerSatisfied(triggerId) {
+            return satisfied.has(triggerId);
+        },
+        isSeen(id) {
+            return seenAtMap.has(id);
+        },
+        seenAt(id) {
+            return seenAtMap.get(id);
+        },
+        isComplete() {
+            return steps.every((step) => seenAtMap.has(step.id));
+        },
+        remaining,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            const seen = [];
+            const seenAt = {};
+            for (const [id, at] of seenAtMap) {
+                seen.push(id);
+                seenAt[id] = at;
+            }
+            return { seen, seenAt, satisfied: [...satisfied] };
+        },
+        restore(snapshot) {
+            seenAtMap.clear();
+            for (const id of snapshot.seen) {
+                seenAtMap.set(id, snapshot.seenAt[id] ?? now());
+            }
+            satisfied = new Set(snapshot.satisfied);
+            notify();
+        },
+    };
+}

package/dist/ui/floatingText.d.ts

@@ -0,0 +1,114 @@
+/** A world-space anchor `[x, y, z]` a floating-text entry rises from. */
+export type FloatingTextPosition = readonly [number, number, number];
+/**
+ * One text pop to spawn: what to say, where in the world, and how it moves and
+ * fades. Everything but `position` and `text` is optional and falls back to the
+ * field's defaults. `kind` is a free-form tag (`"damage"`, `"heal"`, `"crit"`,
+ * `"xp"`, `"gold"`, `"bark"`, …) the presentation layer styles — the model never
+ * interprets it, so nothing here is combat- or genre-specific.
+ */
+export interface FloatingTextDef {
+    /** World anchor the text rises from. */
+    position: FloatingTextPosition;
+    /** The text to show. */
+    text: string;
+    /** Free-form style tag the game colors/skins. Default `"default"`. */
+    kind?: string;
+    /** Optional CSS color hint carried straight through to the view (presentation may override per `kind`). */
+    color?: string;
+    /** Relative scale multiplier (before the birth pop-in). Default 1. */
+    size?: number;
+    /** Upward world-Y speed in units/second. Default = field `defaultRise`. */
+    rise?: number;
+    /** Horizontal world-X speed in units/second (signed). Default: a small seeded jitter in `±driftJitter`. */
+    drift?: number;
+    /** Lifetime in seconds. Default = field `defaultLifetime`. */
+    lifetime?: number;
+}
+/** Construction options for {@link createFloatingTextField}. */
+export interface FloatingTextFieldConfig {
+    /** Hard cap on live entries; the pool never grows past this. When full, the oldest entry is recycled. Default 64. */
+    max?: number;
+    /** Injected wall clock in ms, stamped on each entry's `bornAt`. Default `Date.now`; inject for deterministic tests. */
+    now?: () => number;
+    /** Seed for the horizontal-drift jitter stream — same seed + same calls reproduce identical motion. Default `"floating-text"`. */
+    seed?: string | number;
+    /** Default lifetime in seconds when a def omits `lifetime`. Default 1.4. */
+    defaultLifetime?: number;
+    /** Default upward speed in units/second when a def omits `rise`. Default 1.2. */
+    defaultRise?: number;
+    /** Max magnitude of the seeded horizontal drift used when a def omits `drift`. Default 0.6. */
+    driftJitter?: number;
+    /** Fraction of life spent on the birth scale pop-in (0.6→1). Default 0.16. */
+    popIn?: number;
+    /** Fraction of life over which alpha fades to 0 at the end. Default 0.4. */
+    fadeFraction?: number;
+}
+/** A live entry resolved for rendering: current world position and fade/scale over life. */
+export interface FloatingTextView {
+    /** Stable, monotonically increasing id assigned at emit — usable as a React key. */
+    id: number;
+    /** Current world position with rise (Y) and drift (X) applied. */
+    position: FloatingTextPosition;
+    /** The text to show. */
+    text: string;
+    /** The style tag (resolved; `"default"` when the def omitted `kind`). */
+    kind: string;
+    /** The def's color hint, if any. */
+    color?: string;
+    /** Resolved scale: base `size` times the current birth pop-in factor. */
+    size: number;
+    /** Opacity `0..1`, full until the fade window then easing to 0. */
+    alpha: number;
+    /** Age as a fraction of lifetime, `0..1`. */
+    progress: number;
+    /** Wall-clock ms the entry was emitted (from the injected `now`). */
+    bornAt: number;
+}
+/** Serializable state for save/restore and deterministic replay. */
+export interface FloatingTextSnapshot {
+    seed: number;
+    nextId: number;
+    count: number;
+    /** Numeric per-entry columns, flattened `count * NUMERIC_STRIDE`. */
+    data: number[];
+    /** Per-entry text. */
+    text: string[];
+    /** Per-entry kind. */
+    kind: string[];
+    /** Per-entry color (empty string = none). */
+    color: string[];
+}
+/** A live, dt-driven field of world-anchored floating text. */
+export interface FloatingTextField {
+    /** Spawn one entry; returns its id. When the pool is full the oldest live entry is recycled. */
+    emit(def: FloatingTextDef): number;
+    /** Advance every entry by `dt` seconds: age, rise, drift, and reap the expired. */
+    update(dt: number): void;
+    /** Snapshot of the live entries resolved for rendering (a fresh array each call). */
+    active(): FloatingTextView[];
+    /** Live entry count. */
+    count(): number;
+    /** Remove every entry (keeps the seed stream and id counter). */
+    clear(): void;
+    /** Subscribe to changes (emit/update/clear/restore); returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    snapshot(): FloatingTextSnapshot;
+    restore(snapshot: FloatingTextSnapshot): void;
+}
+/**
+ * A generic, allocation-aware field of world-anchored floating text: damage
+ * numbers, heals, crits, XP/gold gains, status pops, dialogue barks — anything a
+ * game wants to say at a point in the world for a moment. It is dt-driven (call
+ * `update(dt)` each frame) and deterministic: the only randomness is the
+ * horizontal drift jitter, which flows from the injected `seed`, so the same seed
+ * and the same emit/update sequence reproduce identical motion, and
+ * `snapshot`/`restore` round-trips the live pool. The model owns only the
+ * spawn → rise/drift → fade → reap lifecycle: `kind` is a free string and `color`
+ * a passthrough hint, so nothing here couples to combat or any genre. Presentation
+ * (projecting each entry to the screen and styling it per `kind`) lives in
+ * `@jgengine/react`'s `FloatingText`.
+ *
+ * @capability floating-text deterministic pooled world-anchored floating combat text / damage numbers with rise, drift, fade, and serializable state
+ */
+export declare function createFloatingTextField(config?: FloatingTextFieldConfig): FloatingTextField;

package/dist/ui/floatingText.js

@@ -0,0 +1,203 @@
+import { hashString, randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+/** Columns per entry in the numeric SoA pool: id, ox, oy, oz, age, life, rise, drift, size. */
+const NUMERIC_STRIDE = 9;
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * A generic, allocation-aware field of world-anchored floating text: damage
+ * numbers, heals, crits, XP/gold gains, status pops, dialogue barks — anything a
+ * game wants to say at a point in the world for a moment. It is dt-driven (call
+ * `update(dt)` each frame) and deterministic: the only randomness is the
+ * horizontal drift jitter, which flows from the injected `seed`, so the same seed
+ * and the same emit/update sequence reproduce identical motion, and
+ * `snapshot`/`restore` round-trips the live pool. The model owns only the
+ * spawn → rise/drift → fade → reap lifecycle: `kind` is a free string and `color`
+ * a passthrough hint, so nothing here couples to combat or any genre. Presentation
+ * (projecting each entry to the screen and styling it per `kind`) lives in
+ * `@jgengine/react`'s `FloatingText`.
+ *
+ * @capability floating-text deterministic pooled world-anchored floating combat text / damage numbers with rise, drift, fade, and serializable state
+ */
+export function createFloatingTextField(config = {}) {
+    const max = Math.max(1, Math.floor(config.max ?? 64));
+    const now = config.now ?? (() => Date.now());
+    const defaultLifetime = config.defaultLifetime ?? 1.4;
+    const defaultRise = config.defaultRise ?? 1.2;
+    const driftJitter = config.driftJitter ?? 0.6;
+    const popIn = clamp01(config.popIn ?? 0.16);
+    const fadeFraction = clamp01(config.fadeFraction ?? 0.4);
+    // Numeric SoA columns.
+    const id = new Float64Array(max);
+    const ox = new Float32Array(max);
+    const oy = new Float32Array(max);
+    const oz = new Float32Array(max);
+    const age = new Float32Array(max);
+    const life = new Float32Array(max);
+    const rise = new Float32Array(max);
+    const drift = new Float32Array(max);
+    const size = new Float32Array(max);
+    const bornAt = new Float64Array(max);
+    // String columns (strings can't live in a typed array).
+    const text = new Array(max).fill("");
+    const kind = new Array(max).fill("");
+    const color = new Array(max).fill(undefined);
+    let live = 0;
+    let nextId = 1;
+    let seed = randomSeedFrom(typeof config.seed === "number" ? config.seed : hashString(String(config.seed ?? "floating-text")));
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function rand() {
+        const [value, next] = stepRandomSeed(seed);
+        seed = next;
+        return value;
+    }
+    /** Index of the oldest live entry (highest age) — the one recycled when the pool is full. */
+    function oldestIndex() {
+        let best = 0;
+        for (let i = 1; i < live; i++)
+            if (age[i] > age[best])
+                best = i;
+        return best;
+    }
+    function writeEntry(i, def) {
+        const entryId = nextId++;
+        id[i] = entryId;
+        ox[i] = def.position[0];
+        oy[i] = def.position[1];
+        oz[i] = def.position[2];
+        age[i] = 0;
+        life[i] = Math.max(0.0001, def.lifetime ?? defaultLifetime);
+        rise[i] = def.rise ?? defaultRise;
+        // A seeded per-entry drift keeps stacked numbers from overlapping; still deterministic.
+        drift[i] = def.drift ?? (rand() * 2 - 1) * driftJitter;
+        size[i] = def.size ?? 1;
+        bornAt[i] = now();
+        text[i] = def.text;
+        kind[i] = def.kind ?? "default";
+        color[i] = def.color;
+        return entryId;
+    }
+    function swapRemove(i) {
+        const last = live - 1;
+        if (i !== last) {
+            id[i] = id[last];
+            ox[i] = ox[last];
+            oy[i] = oy[last];
+            oz[i] = oz[last];
+            age[i] = age[last];
+            life[i] = life[last];
+            rise[i] = rise[last];
+            drift[i] = drift[last];
+            size[i] = size[last];
+            bornAt[i] = bornAt[last];
+            text[i] = text[last];
+            kind[i] = kind[last];
+            color[i] = color[last];
+        }
+        live--;
+    }
+    /** Current scale (base times birth pop-in) for entry `i`. */
+    function resolveScale(i) {
+        const t = clamp01(age[i] / life[i]);
+        const pop = popIn > 0 && t < popIn ? 0.6 + 0.4 * (t / popIn) : 1;
+        return size[i] * pop;
+    }
+    /** Current alpha (full until the fade window, then easing to 0) for entry `i`. */
+    function resolveAlpha(i) {
+        const t = clamp01(age[i] / life[i]);
+        if (fadeFraction <= 0)
+            return 1;
+        const fadeStart = 1 - fadeFraction;
+        return t <= fadeStart ? 1 : clamp01((1 - t) / fadeFraction);
+    }
+    const field = {
+        emit(def) {
+            const i = live < max ? live++ : oldestIndex();
+            const entryId = writeEntry(i, def);
+            notify();
+            return entryId;
+        },
+        update(dt) {
+            if (dt <= 0)
+                return;
+            for (let i = live - 1; i >= 0; i--) {
+                age[i] += dt;
+                if (age[i] >= life[i]) {
+                    swapRemove(i);
+                }
+            }
+            notify();
+        },
+        active() {
+            const views = [];
+            for (let i = 0; i < live; i++) {
+                const a = age[i];
+                views.push({
+                    id: id[i],
+                    position: [ox[i] + drift[i] * a, oy[i] + rise[i] * a, oz[i]],
+                    text: text[i],
+                    kind: kind[i],
+                    color: color[i],
+                    size: resolveScale(i),
+                    alpha: resolveAlpha(i),
+                    progress: clamp01(a / life[i]),
+                    bornAt: bornAt[i],
+                });
+            }
+            return views;
+        },
+        count() {
+            return live;
+        },
+        clear() {
+            live = 0;
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            const data = [];
+            const outText = [];
+            const outKind = [];
+            const outColor = [];
+            for (let i = 0; i < live; i++) {
+                data.push(id[i], ox[i], oy[i], oz[i], age[i], life[i], rise[i], drift[i], size[i]);
+                outText.push(text[i]);
+                outKind.push(kind[i]);
+                outColor.push(color[i] ?? "");
+            }
+            return { seed: seed, nextId, count: live, data, text: outText, kind: outKind, color: outColor };
+        },
+        restore(snapshot) {
+            seed = randomSeedFrom(snapshot.seed);
+            nextId = snapshot.nextId;
+            live = Math.min(max, snapshot.count);
+            for (let i = 0; i < live; i++) {
+                const o = i * NUMERIC_STRIDE;
+                id[i] = snapshot.data[o];
+                ox[i] = snapshot.data[o + 1];
+                oy[i] = snapshot.data[o + 2];
+                oz[i] = snapshot.data[o + 3];
+                age[i] = snapshot.data[o + 4];
+                life[i] = snapshot.data[o + 5];
+                rise[i] = snapshot.data[o + 6];
+                drift[i] = snapshot.data[o + 7];
+                size[i] = snapshot.data[o + 8];
+                // bornAt is presentational only; it is not round-tripped, so re-stamp on restore.
+                bornAt[i] = now();
+                text[i] = snapshot.text[i];
+                kind[i] = snapshot.kind[i];
+                const c = snapshot.color[i];
+                color[i] = c === undefined || c === "" ? undefined : c;
+            }
+            notify();
+        },
+    };
+    return field;
+}