@jgengine/core 0.13.0 → 0.15.0-next.0

package/dist/game/notifications.js

@@ -0,0 +1,107 @@
+/**
+ * A persistent notification log with read/unread tracking — the "notification
+ * center" surface toasts don't cover. Newest-first, capped, serializable, and
+ * observable; a game pushes durable events (quest updates, trades, party news)
+ * here and a HUD renders the list + an unread badge. `snapshot`/`restore`
+ * round-trip through a save.
+ *
+ * @capability notification-center persistent, read-tracked notification log (newest-first, capped, serializable) behind an unread badge — the durable counterpart to transient toasts
+ */
+export function createNotificationCenter(options = {}) {
+    const now = options.now ?? Date.now;
+    const cap = options.cap ?? 100;
+    let entries = []; // newest-first
+    const listeners = new Set();
+    let cache = null;
+    let counter = 0;
+    function notify() {
+        cache = null;
+        for (const listener of listeners)
+            listener();
+    }
+    function generateId() {
+        counter += 1;
+        return `notice-${counter}`;
+    }
+    return {
+        push(input) {
+            const entry = {
+                id: input.id ?? generateId(),
+                kind: input.kind ?? "info",
+                title: input.title,
+                at: input.at ?? now(),
+                read: false,
+                ...(input.body !== undefined ? { body: input.body } : {}),
+                ...(input.meta !== undefined ? { meta: input.meta } : {}),
+            };
+            entries = [entry, ...entries.filter((existing) => existing.id !== entry.id)];
+            if (cap > 0 && entries.length > cap)
+                entries = entries.slice(0, cap);
+            notify();
+            return entry;
+        },
+        list(filter) {
+            if (filter === undefined) {
+                if (cache === null)
+                    cache = [...entries];
+                return cache;
+            }
+            return entries.filter((entry) => (filter.kind === undefined || entry.kind === filter.kind) &&
+                (filter.unreadOnly !== true || !entry.read));
+        },
+        unreadCount() {
+            let count = 0;
+            for (const entry of entries)
+                if (!entry.read)
+                    count += 1;
+            return count;
+        },
+        markRead(id) {
+            const entry = entries.find((candidate) => candidate.id === id);
+            if (entry === undefined || entry.read)
+                return;
+            entry.read = true;
+            notify();
+        },
+        markAllRead() {
+            let changed = false;
+            for (const entry of entries) {
+                if (!entry.read) {
+                    entry.read = true;
+                    changed = true;
+                }
+            }
+            if (changed)
+                notify();
+        },
+        remove(id) {
+            const next = entries.filter((entry) => entry.id !== id);
+            if (next.length === entries.length)
+                return false;
+            entries = next;
+            notify();
+            return true;
+        },
+        clear() {
+            if (entries.length === 0)
+                return;
+            entries = [];
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            if (cache === null)
+                cache = [...entries];
+            return cache;
+        },
+        restore(snapshot) {
+            entries = snapshot.map((entry) => ({ ...entry }));
+            if (cap > 0 && entries.length > cap)
+                entries = entries.slice(0, cap);
+            notify();
+        },
+    };
+}

package/dist/game/playableGame.d.ts

@@ -140,6 +140,22 @@ export interface ModelMaterialOverride {
     emissiveIntensity?: number;
     /** Real PBR texture maps applied over the model's material — see {@link ModelMaterialMaps}. */
     maps?: ModelMaterialMaps;
+    /**
+     * Fresnel rim light: a bright edge where the surface turns away from the viewer. This is what
+     * separates an actor from ground of the same value — a body lit only by the scene's own key sits
+     * in the terrain's tonal band at range and reads as a smudge, however well its albedo is chosen.
+     * Omit for no rim.
+     */
+    rim?: ModelRimLight;
+}
+/** Fresnel rim-light term added on top of a model's lighting — see {@link ModelMaterialOverride.rim}. */
+export interface ModelRimLight {
+    /** Rim colour. Default "#ffffff". */
+    color?: string;
+    /** Rim brightness. 0 disables it; ~0.3 is a subtle read, ~1.5 is a hard sci-fi edge. Default 0.6. */
+    strength?: number;
+    /** Falloff exponent: higher confines the rim to the extreme edge. Default 2.5. */
+    power?: number;
 }
 /** Parents a prop/weapon model to a named bone or node on the host model's rig — a sword on `handslot.r`, a spellbook offhand — following the bone's animated transform each frame. */
 export interface ModelAttachment {
@@ -221,6 +237,14 @@ export interface DirectionalLightingConfig {
     shadowMapSize?: number;
     /** Half-extent of the orthographic shadow camera in world units — sized to the shadowed area. Default 40. */
     shadowCameraSize?: number;
+    /**
+     * Cascade count for cascaded shadow maps (CSM). When `> 1` and `castShadow`, the shell mounts
+     * three.js CSM so outdoor scenes keep shadows past a single ortho frustum. Default `1` (legacy
+     * single map). Typical outdoor value: `3` or `4`.
+     */
+    cascades?: number;
+    /** Max far plane for CSM cascades in world units. Default 200. */
+    shadowMaxFar?: number;
     /** Shadow depth bias to fight acne. Default -0.0004. */
     shadowBias?: number;
     /** Shadow normal bias to fight peter-panning. Default 0.02. */
@@ -258,8 +282,16 @@ export interface PlayerMovementConfig {
     axis?: "x" | "z";
     /** Cell size for mode "grid". Default 1. */
     cellSize?: number;
-    /** Collide the walking player against placed scene objects (unit-box AABBs) even without `collision.voxel`. Default false. */
+    /**
+     * Collide the walking player against placed scene objects' blocking colliders even without
+     * `collision.voxel`. Default **true** — a placed object with a blocking physical collider stops,
+     * supports, and is stood upon by the player; set `false` to walk through everything (ghost/spectator
+     * modes, pure-board presentations). Objects that should never block should carry non-blocking
+     * colliders instead of relying on this switch.
+     */
     collideObjects?: boolean;
+    /** Tallest object ledge stepped up while walking (and largest drop still snapped down instead of falling). Default 0.4. */
+    stepHeight?: number;
     /** Intercepts each frame's resolved position before the pose commits (and before onTick): return a replacement [x,y,z] to constrain or redirect the step, or nothing to accept it. */
     beforeCommit?: (frame: MovementCommitFrame) => readonly [number, number, number] | undefined | void;
     /** Gates the built-in sprint (`runSpeedMultiplier`) behind live game state — a stamina stat, an encumbrance check (#282.3). Called each frame while sprint is held; `false` walks. */
@@ -297,7 +329,12 @@ export interface PresentationEffectsConfig {
     vfx?: boolean;
     /** Floating combat text (damage numbers, etc.). Default true. */
     floatText?: boolean;
-    /** Projectile tracer lines. Default true. */
+    /**
+     * Straight muzzle→impact tracer lines for direct-fire shots. Opt-in (default false): unlike the
+     * other channels, a missing `tracers` key leaves them OFF, because `fireProjectile` is a generic
+     * seam and a tracer is only meaningful for a game that fires direct, bullet-like projectiles.
+     * Arced/exploding shots (grenades, launchers) never draw a tracer even when this is on.
+     */
     tracers?: boolean;
     /** Trauma-driven combat camera shake. Default true. */
     shake?: boolean;

package/dist/game/quest.d.ts

@@ -99,6 +99,32 @@ export interface QuestJournal {
  * @capability quest-log track accepted quests and their per-objective progress
  */
 export declare function createQuestJournal(deps: QuestJournalDeps): QuestJournal;
+/** One objective as a tracker/HUD reads it — label + progress toward its count. */
+export interface TrackedObjectiveView {
+    id: string;
+    /** Human label (e.g. "Defeat 3 wraiths"); falls back to the objective id. */
+    label: string;
+    count: number;
+    progress: number;
+    complete: boolean;
+}
+/** A quest as a tracker/HUD reads it — title, status, and per-objective progress. */
+export interface TrackedQuestView {
+    id: string;
+    title: string;
+    status: QuestStatus;
+    objectives: TrackedObjectiveView[];
+}
+/** Default objective label: a readable "verb count noun" from a {@link QuestObjective}. */
+export declare function defaultObjectiveLabel(objective: QuestObjective): string;
+/**
+ * Join a quest's static {@link QuestDef} with a player's live {@link QuestInstance}
+ * into a flat, renderer-free view a HUD tracker draws (title, status, labelled
+ * objective progress). Pass `label` to override the derived objective text.
+ *
+ * @capability quest-tracker-view join a QuestDef + live QuestInstance into a flat labelled view for a quest/objective HUD tracker
+ */
+export declare function describeTrackedQuest(def: QuestDef, instance: QuestInstance, label?: (objective: QuestObjective) => string): TrackedQuestView;
 export interface QuestAcceptOptions {
     hasUnlock?(id: string): boolean;
 }

package/dist/game/quest.js

@@ -259,6 +259,37 @@ export function createQuestJournal(deps) {
         },
     };
 }
+/** Default objective label: a readable "verb count noun" from a {@link QuestObjective}. */
+export function defaultObjectiveLabel(objective) {
+    const noun = objective.target ?? objective.item ?? objective.id;
+    const verb = objective.kind === "kill" ? "Defeat" : objective.kind === "collect" ? "Collect" : objective.kind;
+    return `${verb} ${objective.count} ${noun}`;
+}
+/**
+ * Join a quest's static {@link QuestDef} with a player's live {@link QuestInstance}
+ * into a flat, renderer-free view a HUD tracker draws (title, status, labelled
+ * objective progress). Pass `label` to override the derived objective text.
+ *
+ * @capability quest-tracker-view join a QuestDef + live QuestInstance into a flat labelled view for a quest/objective HUD tracker
+ */
+export function describeTrackedQuest(def, instance, label = defaultObjectiveLabel) {
+    const defs = new Map(def.objectives.map((objective) => [objective.id, objective]));
+    return {
+        id: def.id,
+        title: def.title,
+        status: instance.status,
+        objectives: instance.objectives.map((progress) => {
+            const source = defs.get(progress.id);
+            return {
+                id: progress.id,
+                label: source === undefined ? progress.id : label(source),
+                count: progress.count,
+                progress: progress.progress,
+                complete: progress.complete,
+            };
+        }),
+    };
+}
 export function applyQuestRewards(rewards, appliers) {
     for (const entry of rewards.items ?? []) {
         const fail = appliers.grantItem?.(entry.inventory, entry.item, entry.count);

package/dist/game/runDraft.js

@@ -1,4 +1,5 @@
 import { pickWeighted } from "../world/scatterItems.js";
+import { resolveRng } from "../random/resolveRng.js";
 export function createRunModifierStack(offers) {
     const byId = new Map();
     for (const offer of offers) {
@@ -75,7 +76,7 @@ export function createRunModifierStack(offers) {
  */
 export function createRunDraft(config) {
     const stack = createRunModifierStack(config.offers);
-    const defaultRng = config.rng ?? Math.random;
+    const defaultRng = resolveRng(config.rng, "createRunDraft");
     return {
         present(count, rng = defaultRng) {
             const pool = config.offers.filter((offer) => !stack.atMax(offer.id));

package/dist/game/saveSlots.d.ts

@@ -0,0 +1,102 @@
+/**
+ * One entry in a {@link SaveSlots} index: a save/profile slot's *display*
+ * metadata, not its payload. The real save data lives in a `createSaveStore`
+ * slot; this record is only what a save-select menu renders — an id, an optional
+ * player-facing `name`, whether the slot is `empty`, when it was last written
+ * (`savedAt`), and a free-string `meta` bag the game fills with whatever the
+ * menu should show (level, playtime, location, chapter, a thumbnail ref, …).
+ * `meta` keys are opaque to this model — it never reads or branches on them.
+ */
+export interface SaveSlotMeta {
+    /** Stable slot id — pair it with the same slot in the game's `createSaveStore`. */
+    id: string;
+    /** Player-facing label (character name, save title). `undefined` until named. */
+    name?: string;
+    /** `true` when no save occupies this slot — the menu shows a "New Game" affordance. */
+    empty: boolean;
+    /** Clock time (ms) of the last {@link SaveSlots.write}, or `undefined` while empty. */
+    savedAt?: number;
+    /**
+     * Free-string display fields the game owns and the menu renders as chips —
+     * e.g. `{ chapter: "The Drowned Keep", playtime: "4h 12m", level: 8 }`. The
+     * model never interprets these keys; they are pure passthrough to the renderer.
+     */
+    meta: Record<string, string | number>;
+}
+/** What a {@link SaveSlots.write} stamps onto a slot — a name and/or a fresh `meta` bag. */
+export interface SaveSlotWrite {
+    /** Player-facing label for the slot. Omit to keep the existing name. */
+    name?: string;
+    /** Replacement free-string display fields. Omit to keep the existing `meta`. */
+    meta?: Record<string, string | number>;
+}
+/** How a {@link createSaveSlots} index is wired. */
+export interface SaveSlotsConfig {
+    /** Injected clock (ms) used to stamp `savedAt`. Default `Date.now`. */
+    now?: () => number;
+    /**
+     * Initial slots, in menu order. Any slot omitting `empty` is treated as empty.
+     * When `capacity` is set and this is shorter, the list is padded with empty
+     * slots (`slot-1`, `slot-2`, …) up to `capacity`.
+     */
+    slots?: SaveSlotMeta[];
+    /**
+     * Fixed number of slots the menu shows. When set, the index is padded with
+     * empty slots up to this count and never grows past it. Omit for an
+     * open-ended list that only holds the slots you seed.
+     */
+    capacity?: number;
+}
+/** Serializable state of a {@link SaveSlots} index, for save/restore. */
+export interface SaveSlotsSnapshot {
+    /** The slots in menu order. */
+    slots: SaveSlotMeta[];
+    /** The fixed capacity, or `undefined` for an open-ended list. */
+    capacity: number | undefined;
+}
+/**
+ * A serializable, observable index of save/profile slot *metadata* that a
+ * save-select menu renders. It complements `createSaveStore` (which owns the
+ * actual save payload and named slots) by carrying the per-slot display fields
+ * the store does not: name, empty flag, last-saved time, and a free-string
+ * `meta` bag the game fills. Nothing here is genre-specific.
+ */
+export interface SaveSlots {
+    /**
+     * Stamp a slot as written: sets `empty=false`, records `savedAt` via the
+     * injected clock, and applies the given `name`/`meta`. Creates the slot if it
+     * does not exist (subject to `capacity`). Returns the resulting slot record.
+     */
+    write(id: string, write?: SaveSlotWrite): SaveSlotMeta;
+    /** Mark a slot empty, dropping its `name`, `savedAt`, and `meta`. Returns the cleared record, or `null` if the id is unknown. */
+    clear(id: string): SaveSlotMeta | null;
+    /** Rename a slot without touching its `savedAt`/`meta`. Returns the updated record, or `null` if the id is unknown. */
+    rename(id: string, name: string): SaveSlotMeta | null;
+    /** The slot with this id, or `null`. The returned record is a copy — mutating it does not affect the index. */
+    get(id: string): SaveSlotMeta | null;
+    /** All slots in menu order (copies). Powers the save-select grid. */
+    list(): SaveSlotMeta[];
+    /** The newest non-empty slot (highest `savedAt`), or `null` when every slot is empty — powers "Continue". */
+    mostRecent(): SaveSlotMeta | null;
+    /** Observe any change (write/clear/rename/restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): SaveSlotsSnapshot;
+    /** Restore from a {@link SaveSlotsSnapshot}, replacing all slots. */
+    restore(snapshot: SaveSlotsSnapshot): void;
+}
+/**
+ * Create a {@link SaveSlots} index — the serializable, observable list of
+ * save/profile slot metadata a save-select menu renders. It is a thin companion
+ * to `createSaveStore`: the store owns the real save payload keyed by slot, this
+ * owns only the display fields (name, empty, last-saved, and a free-string
+ * `meta` bag) the menu shows. `write` stamps a slot saved on the injected clock,
+ * `clear` empties one, `rename` relabels one, `mostRecent()` returns the newest
+ * non-empty slot to power a "Continue" button, and `list()` feeds the New /
+ * Continue / Load / Delete grid. `meta` keys are free strings the game owns —
+ * the model never interprets them — and `snapshot`/`restore` round-trips the
+ * whole index through a save.
+ *
+ * @capability save-slots serializable save-slot / profile metadata index — write/clear/rename/mostRecent over free-string per-slot meta, powering New/Continue/Load/Delete menus, with snapshot/restore
+ */
+export declare function createSaveSlots(config?: SaveSlotsConfig): SaveSlots;

package/dist/game/saveSlots.js

@@ -0,0 +1,136 @@
+function emptySlot(id) {
+    return { id, empty: true, meta: {} };
+}
+function cloneSlot(slot) {
+    return {
+        id: slot.id,
+        name: slot.name,
+        empty: slot.empty,
+        savedAt: slot.savedAt,
+        meta: { ...slot.meta },
+    };
+}
+function normalizeSlot(slot) {
+    const empty = slot.empty ?? true;
+    return {
+        id: slot.id,
+        name: slot.name,
+        empty,
+        savedAt: empty ? undefined : slot.savedAt,
+        meta: empty ? {} : { ...(slot.meta ?? {}) },
+    };
+}
+/**
+ * Create a {@link SaveSlots} index — the serializable, observable list of
+ * save/profile slot metadata a save-select menu renders. It is a thin companion
+ * to `createSaveStore`: the store owns the real save payload keyed by slot, this
+ * owns only the display fields (name, empty, last-saved, and a free-string
+ * `meta` bag) the menu shows. `write` stamps a slot saved on the injected clock,
+ * `clear` empties one, `rename` relabels one, `mostRecent()` returns the newest
+ * non-empty slot to power a "Continue" button, and `list()` feeds the New /
+ * Continue / Load / Delete grid. `meta` keys are free strings the game owns —
+ * the model never interprets them — and `snapshot`/`restore` round-trips the
+ * whole index through a save.
+ *
+ * @capability save-slots serializable save-slot / profile metadata index — write/clear/rename/mostRecent over free-string per-slot meta, powering New/Continue/Load/Delete menus, with snapshot/restore
+ */
+export function createSaveSlots(config = {}) {
+    const now = config.now ?? Date.now;
+    let capacity = config.capacity;
+    const slots = (config.slots ?? []).map(normalizeSlot);
+    const seen = new Set(slots.map((slot) => slot.id));
+    if (capacity !== undefined) {
+        let n = 1;
+        while (slots.length < capacity) {
+            let id = `slot-${n}`;
+            while (seen.has(id)) {
+                n += 1;
+                id = `slot-${n}`;
+            }
+            seen.add(id);
+            slots.push(emptySlot(id));
+            n += 1;
+        }
+    }
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function indexOf(id) {
+        return slots.findIndex((slot) => slot.id === id);
+    }
+    return {
+        write(id, write) {
+            let i = indexOf(id);
+            if (i === -1) {
+                if (capacity !== undefined && slots.length >= capacity) {
+                    throw new Error(`save-slots: cannot create slot "${id}" — capacity ${capacity} reached`);
+                }
+                slots.push(emptySlot(id));
+                i = slots.length - 1;
+            }
+            const slot = slots[i];
+            slot.empty = false;
+            slot.savedAt = now();
+            if (write?.name !== undefined)
+                slot.name = write.name;
+            if (write?.meta !== undefined)
+                slot.meta = { ...write.meta };
+            notify();
+            return cloneSlot(slot);
+        },
+        clear(id) {
+            const i = indexOf(id);
+            if (i === -1)
+                return null;
+            const slot = slots[i];
+            slot.empty = true;
+            slot.name = undefined;
+            slot.savedAt = undefined;
+            slot.meta = {};
+            notify();
+            return cloneSlot(slot);
+        },
+        rename(id, name) {
+            const i = indexOf(id);
+            if (i === -1)
+                return null;
+            const slot = slots[i];
+            slot.name = name;
+            notify();
+            return cloneSlot(slot);
+        },
+        get(id) {
+            const i = indexOf(id);
+            return i === -1 ? null : cloneSlot(slots[i]);
+        },
+        list() {
+            return slots.map(cloneSlot);
+        },
+        mostRecent() {
+            let best = null;
+            for (const slot of slots) {
+                if (slot.empty)
+                    continue;
+                if (best === null || (slot.savedAt ?? 0) > (best.savedAt ?? 0))
+                    best = slot;
+            }
+            return best === null ? null : cloneSlot(best);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { slots: slots.map(cloneSlot), capacity };
+        },
+        restore(snapshot) {
+            capacity = snapshot.capacity;
+            slots.length = 0;
+            for (const slot of snapshot.slots)
+                slots.push(normalizeSlot(slot));
+            notify();
+        },
+    };
+}

package/dist/game/talentTreeView.d.ts

@@ -0,0 +1,106 @@
+import type { TalentNodeDef, TalentTree } from "./talents.js";
+/**
+ * Render state of a talent node, derived from its rank and prerequisite satisfaction.
+ * - `locked` — rank 0 and at least one prerequisite unmet; cannot be trained yet.
+ * - `available` — rank 0, every prerequisite met; ready to take a first point.
+ * - `learned` — at least one rank invested, but below `maxRank`.
+ * - `maxed` — fully invested (`rank === maxRank`).
+ */
+export type TalentNodeState = "locked" | "available" | "learned" | "maxed";
+/** One prerequisite edge into a node — the source node, the rank it demands, and whether that is met. */
+export interface TalentEdgeView {
+    /** Prerequisite node id (edge source). */
+    from: string;
+    /** Rank the prerequisite must reach for this edge to be satisfied. */
+    rank: number;
+    /** Whether the prerequisite currently sits at or above the required rank. */
+    met: boolean;
+}
+/** A per-node view for rendering: grid placement (tier/branch), rank, state, and inbound prerequisite edges. */
+export interface TalentNodeView {
+    /** Stable node id (matches the {@link TalentNodeDef}). */
+    id: string;
+    /** Branch key the node belongs to (`""` when the def has none) — a free string the game styles/columns by. */
+    branch: string;
+    /** 0-based prerequisite depth: `0` for a root, else `1 + max(tier of prerequisites)`. Drives row/tier layout. */
+    tier: number;
+    /** Points currently invested in the node. */
+    rank: number;
+    /** Maximum points the node accepts. */
+    maxRank: number;
+    /** Derived render state (see {@link TalentNodeState}). */
+    state: TalentNodeState;
+    /** Whether a point can be spent on the node right now (mirrors `tree.canAllocate(id).ok`). */
+    allocatable: boolean;
+    /** Inbound prerequisite edges, in definition order. */
+    requires: readonly TalentEdgeView[];
+}
+/** A whole-tree render view: placed nodes plus branch/tier extents and point totals. */
+export interface TalentTreeView {
+    /** Every node, in definition order, with its render placement and state. */
+    nodes: readonly TalentNodeView[];
+    /** Distinct branch keys, in first-seen (definition) order — the natural column order. */
+    branches: readonly string[];
+    /** Number of tiers, i.e. `max(tier) + 1` (0 when the tree is empty). */
+    tiers: number;
+    /** Points the player still has to spend. */
+    pointsAvailable: number;
+    /** Points already invested across the tree. */
+    pointsSpent: number;
+}
+/**
+ * Per-node status a game supplies to build a view from *any* unlock rule — not just point-spend.
+ * A game computes these from whatever it wants (a currency threshold, a level, a quest flag, a
+ * skill-point pool, nothing at all) so the same widget renders a buy-with-points talent tree, a
+ * money-gated upgrade tree, or a condition-unlocked ability web without changing the renderer.
+ */
+export interface TalentNodeStatus {
+    /** Points/levels invested in the node — `0` means "not taken yet"; a binary unlock uses `0`/`1`. */
+    rank: number;
+    /**
+     * Whether the node can be taken right now under the game's own rule (enough points, enough cash,
+     * a level reached, a flag set, …). Drives the `available` state and whether the widget fires
+     * `onLearn` for it. The view never interprets *why* — that stays the game's decision.
+     */
+    allocatable: boolean;
+}
+/** Optional overall point totals for the view header; omit (or 0) for trees that spend no point currency. */
+export interface TalentPointTotals {
+    /** Points the player still has to spend. Default `0`. */
+    pointsAvailable?: number;
+    /** Points already invested across the tree. Default `0`. */
+    pointsSpent?: number;
+}
+/**
+ * Build a flat, serializable render view of a node graph from a caller-supplied per-node status,
+ * decoupled from any particular progression model. For each node the game returns its `rank` and
+ * whether it is `allocatable` *right now* under whatever rule it likes — a skill-point pool, a cash
+ * threshold, a level gate, a quest flag, or nothing. The builder places every node by branch +
+ * prerequisite-depth tier, tags it learned/available/locked/maxed (`available` when rank 0 and every
+ * prerequisite is met — see below), and resolves inbound prerequisite edges (each `met` when the
+ * source node's supplied rank meets the demand). This is the general escape hatch behind
+ * {@link talentTreeView}: it lets the same widget render a buy-with-points talent tree, a money-gated
+ * upgrade tree, or a condition-unlocked ability web without the renderer changing. It never interprets
+ * what a node *means* — ids, branches, and ranks stay opaque game data.
+ *
+ * `state` is derived purely from the supplied `rank` vs `maxRank` and prerequisite satisfaction, so a
+ * node the game considers takeable-by-condition surfaces as `available` (rank 0, prerequisites met)
+ * and the widget only fires `onLearn` for nodes whose `allocatable` the game returned `true`.
+ *
+ * @capability talent-tree-view-from build a placed talent/upgrade-tree render view from any per-node unlock rule (points, currency, level, flag) — branch/tier layout, learned/available/locked/maxed state, prerequisite edges
+ */
+export declare function talentTreeViewFrom<TStat extends string = string>(nodes: readonly TalentNodeDef<TStat>[], status: (node: TalentNodeDef<TStat>) => TalentNodeStatus, totals?: TalentPointTotals): TalentTreeView;
+/**
+ * Project the existing talent model (`createTalentTree`) into a flat, serializable render view: every
+ * node placed by branch + prerequisite-depth tier, tagged learned/available/locked/maxed, with its
+ * inbound prerequisite edges (and whether each is met) and whether a point can be spent right now. It is
+ * a pure read over the node defs plus a live {@link TalentTree}, so a React/canvas widget can lay out
+ * nodes, draw edges, and gate clicks without re-deriving topology or re-interpreting eligibility. The
+ * model still owns allocation, requirements, and point rules — this only reshapes them for drawing, and
+ * never interprets what a node *means* (ids, branches, and ranks stay opaque game data). This is the
+ * point-spend adapter over {@link talentTreeViewFrom}; pass a custom status to that builder instead to
+ * drive the tree from a currency, level, or any other unlock rule.
+ *
+ * @capability talent-tree-view flatten a talent tree into a placed, per-node render view — branch/tier layout, learned/available/locked/maxed state, prerequisite edges
+ */
+export declare function talentTreeView<TStat extends string = string>(nodes: readonly TalentNodeDef<TStat>[], tree: TalentTree<TStat>): TalentTreeView;