@jgengine/core 0.10.0 → 0.12.0

package/dist/puzzle/nonogram.js

@@ -0,0 +1,136 @@
+/** Run lengths of the filled cells in a boolean line — the clue a solved line yields.
+ * @internal
+ */
+export function runLengths(line) {
+    const runs = [];
+    let run = 0;
+    for (const cell of line) {
+        if (cell) {
+            run += 1;
+        }
+        else if (run > 0) {
+            runs.push(run);
+            run = 0;
+        }
+    }
+    if (run > 0)
+        runs.push(run);
+    return runs;
+}
+/** Row and column clues derived from a solution grid — the puzzle a solved board poses.
+ * @internal
+ */
+export function deriveClues(solution) {
+    const width = solution[0]?.length ?? 0;
+    const rows = solution.map((row) => runLengths(row));
+    const cols = [];
+    for (let c = 0; c < width; c += 1)
+        cols.push(runLengths(solution.map((row) => row[c] ?? false)));
+    return { rows, cols };
+}
+/**
+ * Constraint-propagate one line against its `clue`: intersect every clue-consistent arrangement, forcing a
+ * cell `filled` when it is filled in all of them and `empty` when empty in all, leaving the rest `unknown`.
+ * Returns the tightened line, or `null` on contradiction (no arrangement fits the current cells) — the
+ * per-line deduction step at the heart of every nonogram/picross solver.
+  * @internal
+  */
+export function solveLine(line, clue) {
+    const n = line.length;
+    const everFilled = new Array(n).fill(false);
+    const everEmpty = new Array(n).fill(false);
+    const current = new Array(n).fill(false);
+    let arrangements = 0;
+    const record = () => {
+        arrangements += 1;
+        for (let k = 0; k < n; k += 1) {
+            if (current[k])
+                everFilled[k] = true;
+            else
+                everEmpty[k] = true;
+        }
+    };
+    const place = (pos, clueIndex) => {
+        if (clueIndex === clue.length) {
+            for (let k = pos; k < n; k += 1)
+                if (line[k] === "filled")
+                    return;
+            record();
+            return;
+        }
+        const len = clue[clueIndex];
+        for (let start = pos; start + len <= n; start += 1) {
+            let gapHasFilled = false;
+            for (let k = pos; k < start; k += 1)
+                if (line[k] === "filled") {
+                    gapHasFilled = true;
+                    break;
+                }
+            let runOk = true;
+            for (let k = start; k < start + len; k += 1)
+                if (line[k] === "empty") {
+                    runOk = false;
+                    break;
+                }
+            const separatorOk = start + len >= n || line[start + len] !== "filled";
+            if (!gapHasFilled && runOk && separatorOk) {
+                for (let k = start; k < start + len; k += 1)
+                    current[k] = true;
+                place(start + len + 1, clueIndex + 1);
+                for (let k = start; k < start + len; k += 1)
+                    current[k] = false;
+            }
+            if (line[start] === "filled")
+                break;
+        }
+    };
+    place(0, 0);
+    if (arrangements === 0)
+        return null;
+    const out = line.slice();
+    for (let k = 0; k < n; k += 1) {
+        if (everFilled[k] && !everEmpty[k])
+            out[k] = "filled";
+        else if (everEmpty[k] && !everFilled[k])
+            out[k] = "empty";
+    }
+    return out;
+}
+/**
+ * Solve a nonogram from its row and column clues by iterated line propagation until the board stops
+ * changing. `solved` is true iff the board is fully determined without guessing — the standard test for
+ * whether a nonogram is fair. Returns `solved: false` with a partial board on contradiction or ambiguity.
+  * @internal
+  */
+export function solveNonogram(rows, cols) {
+    const height = rows.length;
+    const width = cols.length;
+    const board = Array.from({ length: height }, () => new Array(width).fill("unknown"));
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (let r = 0; r < height; r += 1) {
+            const solved = solveLine(board[r], rows[r]);
+            if (solved === null)
+                return { solved: false, board };
+            for (let c = 0; c < width; c += 1)
+                if (solved[c] !== board[r][c]) {
+                    board[r][c] = solved[c];
+                    changed = true;
+                }
+        }
+        for (let c = 0; c < width; c += 1) {
+            const column = board.map((row) => row[c]);
+            const solved = solveLine(column, cols[c]);
+            if (solved === null)
+                return { solved: false, board };
+            for (let r = 0; r < height; r += 1)
+                if (solved[r] !== board[r][c]) {
+                    board[r][c] = solved[r];
+                    changed = true;
+                }
+        }
+    }
+    const solved = board.every((row) => row.every((cell) => cell !== "unknown"));
+    return { solved, board };
+}

package/dist/random/nameGen.d.ts

@@ -14,5 +14,10 @@ export interface NameGenerator {
     name(): string;
 }
 export declare function pickFrom(rng: () => number, bank: readonly string[]): string;
+/**
+ * Generate procedural names from templates and word banks with an injected random source.
+ *
+ * @capability name-generator generate procedural names from templates and word banks
+ */
 export declare function createNameGenerator(options: NameGeneratorOptions): NameGenerator;
 export declare function fillTemplate(template: string, vars: Record<string, () => string> | Record<string, string>): string;

package/dist/random/nameGen.js

@@ -3,6 +3,11 @@ export function pickFrom(rng, bank) {
         throw new Error("pickFrom: bank must not be empty");
     return bank[Math.floor(rng() * bank.length)];
 }
+/**
+ * Generate procedural names from templates and word banks with an injected random source.
+ *
+ * @capability name-generator generate procedural names from templates and word banks
+ */
 export function createNameGenerator(options) {
     const { rng, syllables } = options;
     const minSyllables = Math.max(1, options.minSyllables ?? 2);

package/dist/random/pick.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pick one item uniformly at random from `items` using `rng` (a `() => number` in `[0, 1)`); returns undefined when empty.
+ *
+ * @capability weighted-pick pick one item from a set with an injected random source
+ */
+export declare function pickUniform<T>(rng: () => number, items: readonly T[]): T | undefined;
+/** Pick one item with probability proportional to `weightOf(item)`; skips non-positive weights, returns undefined when nothing is eligible. */
+export declare function pickWeighted<T>(rng: () => number, items: readonly T[], weightOf: (item: T) => number): T | undefined;

package/dist/random/pick.js

@@ -0,0 +1,31 @@
+/**
+ * Pick one item uniformly at random from `items` using `rng` (a `() => number` in `[0, 1)`); returns undefined when empty.
+ *
+ * @capability weighted-pick pick one item from a set with an injected random source
+ */
+export function pickUniform(rng, items) {
+    if (items.length === 0)
+        return undefined;
+    return items[Math.min(items.length - 1, Math.floor(rng() * items.length))];
+}
+/** Pick one item with probability proportional to `weightOf(item)`; skips non-positive weights, returns undefined when nothing is eligible. */
+export function pickWeighted(rng, items, weightOf) {
+    let total = 0;
+    for (const item of items) {
+        const weight = weightOf(item);
+        if (weight > 0)
+            total += weight;
+    }
+    if (total <= 0)
+        return undefined;
+    let roll = rng() * total;
+    for (const item of items) {
+        const weight = weightOf(item);
+        if (weight <= 0)
+            continue;
+        roll -= weight;
+        if (roll <= 0)
+            return item;
+    }
+    return items[items.length - 1];
+}

package/dist/random/rng.d.ts

@@ -1,4 +1,29 @@
-/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
+/**
+ * Deterministic 32-bit FNV-1a hash of a string → unsigned int. Same text, same number, on every
+ * platform — the stable seed behind per-id jitter, spread offsets, and content-addressed variation.
+ */
+export declare function hashString(text: string): number;
+/**
+ * Opaque, serializable PRNG cursor for state machines that must persist their own random stream
+ * (a spawn director, a heat/pursuit meter) instead of holding a closure — the state round-trips
+ * through save/load and multiplayer sync, so it can't carry a function. Never read or do
+ * arithmetic on the raw value directly; thread it through {@link stepRandomSeed} only.
+ */
+export type RandomSeed = number & {
+    readonly __randomSeed: unique symbol;
+};
+/** Wraps an already-integer seed (e.g. a `config.seed`) as a {@link RandomSeed} — no hashing. */
+export declare function randomSeedFrom(seed: number): RandomSeed;
+/**
+ * One step of the {@link seededRng} recurrence in pure (seed in, seed out) form — the same
+ * mulberry32-style generator, shared by every state machine that persists its own PRNG cursor
+ * instead of closing over a generator.
+ */
+export declare function stepRandomSeed(seed: RandomSeed): readonly [value: number, next: RandomSeed];
+/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
+ *
+ * @capability seeded-random injected deterministic randomness for game logic — never `Math.random` in a simulation
+ */
 export declare function seededRng(seed: string | number): () => number;
 /** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */
 export declare function seededStreams(seed: string | number): (stream: string) => () => number;

package/dist/random/rng.js

@@ -1,5 +1,8 @@
-function hashSeed(seed) {
-    const text = typeof seed === "number" ? seed.toString() : seed;
+/**
+ * Deterministic 32-bit FNV-1a hash of a string → unsigned int. Same text, same number, on every
+ * platform — the stable seed behind per-id jitter, spread offsets, and content-addressed variation.
+ */
+export function hashString(text) {
     let h = 2166136261 >>> 0;
     for (let i = 0; i < text.length; i++) {
         h ^= text.charCodeAt(i);
@@ -7,15 +10,35 @@ function hashSeed(seed) {
     }
     return h >>> 0;
 }
-/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
+function hashSeed(seed) {
+    return hashString(typeof seed === "number" ? seed.toString() : seed);
+}
+/** Wraps an already-integer seed (e.g. a `config.seed`) as a {@link RandomSeed} — no hashing. */
+export function randomSeedFrom(seed) {
+    return (seed | 0);
+}
+/**
+ * One step of the {@link seededRng} recurrence in pure (seed in, seed out) form — the same
+ * mulberry32-style generator, shared by every state machine that persists its own PRNG cursor
+ * instead of closing over a generator.
+ */
+export function stepRandomSeed(seed) {
+    const next = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(next ^ (next >>> 15), 1 | next);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    const value = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    return [value, next];
+}
+/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
+ *
+ * @capability seeded-random injected deterministic randomness for game logic — never `Math.random` in a simulation
+ */
 export function seededRng(seed) {
-    let a = hashSeed(seed) >>> 0;
+    let cursor = randomSeedFrom(hashSeed(seed));
     return () => {
-        a = (a + 0x6d2b79f5) >>> 0;
-        let t = a;
-        t = Math.imul(t ^ (t >>> 15), t | 1);
-        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        const [value, next] = stepRandomSeed(cursor);
+        cursor = next;
+        return value;
     };
 }
 /** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */

package/dist/random/seedLink.d.ts

@@ -1,5 +1,9 @@
 export declare const DEFAULT_SEED_PARAM = "seed";
+/** @internal */
 export declare function withSeedParam(url: string, seed: string | number, param?: string): string;
+/** @internal */
 export declare function seedFromSearch(search: string, param?: string): string | null;
+/** @internal */
 export declare function seedFromUrl(url: string, param?: string): string | null;
+/** @internal */
 export declare function dailySeed(nowMs: number, salt?: string): string;

package/dist/random/seedLink.js

@@ -8,6 +8,7 @@ function splitUrl(url) {
     const query = queryIndex === -1 ? "" : rest.slice(queryIndex + 1);
     return { base, query, hash };
 }
+/** @internal */
 export function withSeedParam(url, seed, param = DEFAULT_SEED_PARAM) {
     const { base, query, hash } = splitUrl(url);
     const params = new URLSearchParams(query);
@@ -15,16 +16,19 @@ export function withSeedParam(url, seed, param = DEFAULT_SEED_PARAM) {
     const queryString = params.toString();
     return `${base}${queryString ? `?${queryString}` : ""}${hash ? `#${hash}` : ""}`;
 }
+/** @internal */
 export function seedFromSearch(search, param = DEFAULT_SEED_PARAM) {
     const normalized = search.startsWith("?") ? search.slice(1) : search;
     const params = new URLSearchParams(normalized);
     const value = params.get(param);
     return value === null || value === "" ? null : value;
 }
+/** @internal */
 export function seedFromUrl(url, param = DEFAULT_SEED_PARAM) {
     const { query } = splitUrl(url);
     return seedFromSearch(query, param);
 }
+/** @internal */
 export function dailySeed(nowMs, salt) {
     const date = new Date(nowMs);
     const year = date.getUTCFullYear().toString().padStart(4, "0");

package/dist/relation/keyedValues.d.ts

@@ -0,0 +1,54 @@
+/** Optional inclusive `[min, max]` clamp applied after a write. Omit an edge for unbounded. */
+export interface NumericBounds {
+    readonly min?: number;
+    readonly max?: number;
+}
+/** Clamp a scalar to `bounds` (identity when `bounds` is omitted). Pure — touches no record. */
+export declare function clampValue(value: number, bounds?: NumericBounds): number;
+/** Current value for `key`, or `fallback` (default `0`) when the record has no entry. */
+export declare function getValue(record: Record<string, number>, key: string, fallback?: number): number;
+/**
+ * Set `key` to `value` (clamped to `bounds`), writing the record in place. Returns the stored value.
+ *
+ * @capability set a bounded keyed value in a caller-owned serializable record
+ */
+export declare function setValue(record: Record<string, number>, key: string, value: number, bounds?: NumericBounds): number;
+/** Add `delta` to `key` (clamped to `bounds`), writing the record in place. Returns the stored value. */
+export declare function addValue(record: Record<string, number>, key: string, delta: number, bounds?: NumericBounds): number;
+/**
+ * Step `key` toward `target` by at most `maxDelta` without overshooting, then clamp
+ * to `bounds`. Writes in place and returns the stored value.
+ *
+ * @capability move a keyed value toward a target by a bounded step
+ */
+export declare function towardValue(record: Record<string, number>, key: string, target: number, maxDelta: number, bounds?: NumericBounds): number;
+/**
+ * Decay `key` toward a `rest` value (default `0`) by `rate` per call — the common
+ * "relationships cool off" / "heat fades" drift. Thin wrapper over {@link towardValue}.
+ */
+export declare function driftValue(record: Record<string, number>, key: string, rate: number, rest?: number, bounds?: NumericBounds): number;
+/** Canonicalizes a two-part relation identity into a single delimiter-safe record key. */
+export interface PairKeyCodec {
+    /** `true` when order matters (a→b differs from b→a); `false` sorts the pair first. */
+    readonly directed: boolean;
+    /** Encode a pair into one record key. Undirected codecs canonicalize by sorting the two ids. */
+    key(a: string, b: string): string;
+    /** Recover the pair from a key. Undirected keys come back in canonical (sorted) order. */
+    parse(key: string): [string, string];
+}
+/** Direction and delimiter policy for {@link createPairKeyCodec}. */
+export interface PairKeyOptions {
+    /** `true` for ordered relations (rivalry-from, owes-to); default `false` (mutual). */
+    readonly directed?: boolean;
+    /** Single-character delimiter between encoded ids (default `"|"`). Collisions are escaped, not forbidden. */
+    readonly separator?: string;
+}
+/**
+ * Build a pair-key codec for keyed relation values. Ids are escaped before joining,
+ * so any id (including ones containing the separator or a backslash) round-trips
+ * through {@link PairKeyCodec.key} → {@link PairKeyCodec.parse} without collision.
+ * Undirected codecs (the default) canonicalize so `key(a, b) === key(b, a)`.
+ *
+ * @capability build a serializable directed/undirected pair key that resists delimiter collisions
+ */
+export declare function createPairKeyCodec(options?: PairKeyOptions): PairKeyCodec;

package/dist/relation/keyedValues.js

@@ -0,0 +1,115 @@
+/**
+ * Pure, serialization-friendly numeric operations over a caller-owned record of
+ * keyed values, plus delimiter-safe pair-key codecs for directed and undirected
+ * relations.
+ *
+ * No hidden state and no social semantics: the record, its bounds, drift rates,
+ * and keys are all caller data. Operations mutate the passed record in place and
+ * return the resulting value, so a game keeps one plain `Record<string, number>`
+ * it can serialize with `JSON.stringify` and restore verbatim. Pair keys are the
+ * injectable canonicalizer — compose `codec.key(a, b)` into any of the ops below.
+ */
+import { clamp, moveTowards } from "../math/scalar.js";
+function applyBounds(value, bounds) {
+    return clamp(value, bounds?.min ?? Number.NEGATIVE_INFINITY, bounds?.max ?? Number.POSITIVE_INFINITY);
+}
+/** Clamp a scalar to `bounds` (identity when `bounds` is omitted). Pure — touches no record. */
+export function clampValue(value, bounds) {
+    return applyBounds(value, bounds);
+}
+/** Current value for `key`, or `fallback` (default `0`) when the record has no entry. */
+export function getValue(record, key, fallback = 0) {
+    const stored = record[key];
+    return stored === undefined ? fallback : stored;
+}
+/**
+ * Set `key` to `value` (clamped to `bounds`), writing the record in place. Returns the stored value.
+ *
+ * @capability set a bounded keyed value in a caller-owned serializable record
+ */
+export function setValue(record, key, value, bounds) {
+    const next = applyBounds(value, bounds);
+    record[key] = next;
+    return next;
+}
+/** Add `delta` to `key` (clamped to `bounds`), writing the record in place. Returns the stored value. */
+export function addValue(record, key, delta, bounds) {
+    return setValue(record, key, getValue(record, key) + delta, bounds);
+}
+/**
+ * Step `key` toward `target` by at most `maxDelta` without overshooting, then clamp
+ * to `bounds`. Writes in place and returns the stored value.
+ *
+ * @capability move a keyed value toward a target by a bounded step
+ */
+export function towardValue(record, key, target, maxDelta, bounds) {
+    const step = maxDelta > 0 ? maxDelta : 0;
+    return setValue(record, key, moveTowards(getValue(record, key), target, step), bounds);
+}
+/**
+ * Decay `key` toward a `rest` value (default `0`) by `rate` per call — the common
+ * "relationships cool off" / "heat fades" drift. Thin wrapper over {@link towardValue}.
+ */
+export function driftValue(record, key, rate, rest = 0, bounds) {
+    return towardValue(record, key, rest, rate, bounds);
+}
+const ESCAPE = "\\";
+function escapeComponent(value, separator) {
+    let out = "";
+    for (const ch of value) {
+        if (ch === ESCAPE || ch === separator)
+            out += ESCAPE;
+        out += ch;
+    }
+    return out;
+}
+function splitEscaped(key, separator) {
+    const parts = [];
+    let current = "";
+    let escaped = false;
+    for (const ch of key) {
+        if (escaped) {
+            current += ch;
+            escaped = false;
+        }
+        else if (ch === ESCAPE) {
+            escaped = true;
+        }
+        else if (ch === separator) {
+            parts.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    parts.push(current);
+    return [parts[0] ?? "", parts[1] ?? ""];
+}
+/**
+ * Build a pair-key codec for keyed relation values. Ids are escaped before joining,
+ * so any id (including ones containing the separator or a backslash) round-trips
+ * through {@link PairKeyCodec.key} → {@link PairKeyCodec.parse} without collision.
+ * Undirected codecs (the default) canonicalize so `key(a, b) === key(b, a)`.
+ *
+ * @capability build a serializable directed/undirected pair key that resists delimiter collisions
+ */
+export function createPairKeyCodec(options = {}) {
+    const directed = options.directed ?? false;
+    const separator = options.separator ?? "|";
+    if (separator.length !== 1) {
+        throw new Error(`pair-key separator must be a single character, got ${JSON.stringify(separator)}`);
+    }
+    if (separator === ESCAPE)
+        throw new Error("pair-key separator cannot be the escape character '\\'");
+    return {
+        directed,
+        key(a, b) {
+            const [first, second] = directed || a <= b ? [a, b] : [b, a];
+            return `${escapeComponent(first, separator)}${separator}${escapeComponent(second, separator)}`;
+        },
+        parse(key) {
+            return splitEscaped(key, separator);
+        },
+    };
+}

package/dist/relation/thresholds.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Generic threshold-crossing detection over ordered numeric boundaries.
+ *
+ * Deliberately relationship-agnostic and stateless: the same helper reports
+ * reputation-tier transitions, meter milestones, temperature bands, ecosystem
+ * pressure, difficulty ramps, or any value moving across labelled cut points.
+ * Callers pass `before`/`after` and receive the crossings between them, so the
+ * logic never lives inside a ledger or owns hidden state.
+ */
+export type ThresholdDirection = "up" | "down";
+/** A labelled cut point on the value axis. `Id` is caller-owned (string, enum, or a policy object). */
+export interface ThresholdBoundary<Id = string> {
+    /** Stable identifier reported when this boundary is crossed. */
+    readonly id: Id;
+    /** Numeric position of the boundary on the value axis. */
+    readonly at: number;
+}
+/** A single boundary transition between a `before` and `after` value. */
+export interface ThresholdCrossing<Id = string> {
+    readonly id: Id;
+    readonly at: number;
+    readonly direction: ThresholdDirection;
+}
+/** Exact-boundary and dead-band policy for {@link crossThresholds}. */
+export interface CrossThresholdsOptions {
+    /**
+     * When true (default) a boundary is *occupied* at `value >= at`; when false it
+     * is occupied only at `value > at`. Controls exact-boundary semantics: with the
+     * default, landing exactly on `at` counts as an upward crossing and keeps you
+     * above on the way down.
+     */
+    readonly inclusive?: boolean;
+    /**
+     * Symmetric dead-band (clamped to `>= 0`). An upward crossing of `at` requires
+     * reaching `at + hysteresis`; a downward crossing requires falling below
+     * `at - hysteresis`. Suppresses flapping when a value oscillates around a
+     * boundary. Defaults to `0` (no dead-band).
+     */
+    readonly hysteresis?: number;
+}
+/**
+ * Report every boundary crossed moving from `before` to `after`.
+ *
+ * Upward moves yield `up` crossings in ascending `at` order; downward moves yield
+ * `down` crossings in descending order. Large jumps report every boundary passed;
+ * a zero-width move reports nothing. Boundaries need not be pre-sorted.
+ *
+ * @capability detect fire-once threshold/milestone/tier crossings when a value moves
+ */
+export declare function crossThresholds<Id>(boundaries: readonly ThresholdBoundary<Id>[], before: number, after: number, options?: CrossThresholdsOptions): ThresholdCrossing<Id>[];
+/**
+ * The highest boundary at-or-below `value` — the band the value currently sits in.
+ * Returns `null` when `value` is below every boundary. Boundaries need not be sorted.
+ *
+ * Tier labels stay caller policy: pass an `Id` object carrying whatever label,
+ * relation, or colour the game needs.
+ *
+ * @capability resolve the current tier/band label for a keyed or scalar value
+ */
+export declare function tierAt<Id>(boundaries: readonly ThresholdBoundary<Id>[], value: number, options?: {
+    readonly inclusive?: boolean;
+}): ThresholdBoundary<Id> | null;

package/dist/relation/thresholds.js

@@ -0,0 +1,62 @@
+/**
+ * Generic threshold-crossing detection over ordered numeric boundaries.
+ *
+ * Deliberately relationship-agnostic and stateless: the same helper reports
+ * reputation-tier transitions, meter milestones, temperature bands, ecosystem
+ * pressure, difficulty ramps, or any value moving across labelled cut points.
+ * Callers pass `before`/`after` and receive the crossings between them, so the
+ * logic never lives inside a ledger or owns hidden state.
+ */
+/**
+ * Report every boundary crossed moving from `before` to `after`.
+ *
+ * Upward moves yield `up` crossings in ascending `at` order; downward moves yield
+ * `down` crossings in descending order. Large jumps report every boundary passed;
+ * a zero-width move reports nothing. Boundaries need not be pre-sorted.
+ *
+ * @capability detect fire-once threshold/milestone/tier crossings when a value moves
+ */
+export function crossThresholds(boundaries, before, after, options = {}) {
+    if (after === before)
+        return [];
+    const inclusive = options.inclusive ?? true;
+    const margin = options.hysteresis !== undefined && options.hysteresis > 0 ? options.hysteresis : 0;
+    const rising = after > before;
+    const occupied = (value, edge) => (inclusive ? value >= edge : value > edge);
+    const crossings = [];
+    for (const boundary of boundaries) {
+        if (rising) {
+            const edge = boundary.at + margin;
+            if (!occupied(before, edge) && occupied(after, edge)) {
+                crossings.push({ id: boundary.id, at: boundary.at, direction: "up" });
+            }
+        }
+        else {
+            const edge = boundary.at - margin;
+            if (occupied(before, edge) && !occupied(after, edge)) {
+                crossings.push({ id: boundary.id, at: boundary.at, direction: "down" });
+            }
+        }
+    }
+    crossings.sort((a, b) => (rising ? a.at - b.at : b.at - a.at));
+    return crossings;
+}
+/**
+ * The highest boundary at-or-below `value` — the band the value currently sits in.
+ * Returns `null` when `value` is below every boundary. Boundaries need not be sorted.
+ *
+ * Tier labels stay caller policy: pass an `Id` object carrying whatever label,
+ * relation, or colour the game needs.
+ *
+ * @capability resolve the current tier/band label for a keyed or scalar value
+ */
+export function tierAt(boundaries, value, options = {}) {
+    const inclusive = options.inclusive ?? true;
+    let match = null;
+    for (const boundary of boundaries) {
+        const occupied = inclusive ? value >= boundary.at : value > boundary.at;
+        if (occupied && (match === null || boundary.at > match.at))
+            match = boundary;
+    }
+    return match;
+}

package/dist/render/color.d.ts

@@ -0,0 +1,12 @@
+/** Split a `#rrggbb` hex color into its `[r, g, b]` channels (0–255).
+ * @internal
+ */
+export declare function hexToRgb(hex: string): readonly [number, number, number];
+/** Combine `[r, g, b]` channels (0–255, rounded) into a `#rrggbb` hex string.
+ * @internal
+ */
+export declare function rgbToHex(r: number, g: number, b: number): string;
+/** Interpolate between two `#rrggbb` colors by fraction `t`, clamped to the endpoints.
+ * @internal
+ */
+export declare function mixHex(from: string, to: string, t: number): string;

package/dist/render/color.js

@@ -0,0 +1,26 @@
+/** Split a `#rrggbb` hex color into its `[r, g, b]` channels (0–255).
+ * @internal
+ */
+export function hexToRgb(hex) {
+    const value = Number.parseInt(hex.slice(1), 16);
+    return [(value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff];
+}
+/** Combine `[r, g, b]` channels (0–255, rounded) into a `#rrggbb` hex string.
+ * @internal
+ */
+export function rgbToHex(r, g, b) {
+    const value = ((Math.round(r) & 0xff) << 16) | ((Math.round(g) & 0xff) << 8) | (Math.round(b) & 0xff);
+    return `#${value.toString(16).padStart(6, "0")}`;
+}
+/** Interpolate between two `#rrggbb` colors by fraction `t`, clamped to the endpoints.
+ * @internal
+ */
+export function mixHex(from, to, t) {
+    if (t <= 0)
+        return from;
+    if (t >= 1)
+        return to;
+    const [fr, fg, fb] = hexToRgb(from);
+    const [tr, tg, tb] = hexToRgb(to);
+    return rgbToHex(fr + (tr - fr) * t, fg + (tg - fg) * t, fb + (tb - fb) * t);
+}