@jgengine/react 0.14.0 → 0.15.0-next.0

package/dist/streetGeometryPreview.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Deterministic close-up gallery of the shared road/junction mesh seam.
+ * @capability world-intersections inspect turns and junction meshes in a deterministic preview fixture
+ */
+export declare function StreetGeometryPreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/streetGeometryPreview.js

@@ -0,0 +1,119 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { buildIntersectionMarkings, buildTrimmedIntersections, } from "@jgengine/core/world/roads";
+const armRoad = (angle, width) => ({
+    path: [
+        [0, 0],
+        [Math.sin(angle) * 36, Math.cos(angle) * 36],
+    ],
+    width,
+});
+const cases = [
+    {
+        name: "90 degree turn",
+        streets: [armRoad(Math.PI / 2, 8), armRoad(0, 8)],
+        junction: { x: 0, z: 0, arms: [{ angle: Math.PI / 2, width: 8 }, { angle: 0, width: 8 }] },
+    },
+    {
+        name: "45 degree turn",
+        streets: [armRoad(Math.PI / 2, 8), armRoad(Math.PI / 4, 8)],
+        junction: { x: 0, z: 0, arms: [{ angle: Math.PI / 2, width: 8 }, { angle: Math.PI / 4, width: 8 }] },
+    },
+    {
+        name: "unequal T",
+        streets: [
+            { path: [[-36, 0], [0, 0], [36, 0]], width: 18 },
+            armRoad(0, 8),
+        ],
+        junction: {
+            x: 0,
+            z: 0,
+            arms: [{ angle: Math.PI / 2, width: 18 }, { angle: -Math.PI / 2, width: 18 }, { angle: 0, width: 8 }],
+        },
+    },
+    {
+        name: "unequal cross",
+        streets: [
+            { path: [[-36, 0], [0, 0], [36, 0]], width: 18 },
+            { path: [[0, -36], [0, 0], [0, 36]], width: 8 },
+        ],
+        junction: {
+            x: 0,
+            z: 0,
+            arms: [
+                { angle: Math.PI / 2, width: 18 },
+                { angle: -Math.PI / 2, width: 18 },
+                { angle: 0, width: 8 },
+                { angle: Math.PI, width: 8 },
+            ],
+        },
+    },
+    {
+        name: "five way",
+        streets: [
+            armRoad(0, 8),
+            armRoad(1.12, 18),
+            armRoad(2.42, 10),
+            armRoad(3.72, 14),
+            armRoad(5.05, 8),
+        ],
+        junction: {
+            x: 0,
+            z: 0,
+            arms: [
+                { angle: 0, width: 8 },
+                { angle: 1.12, width: 18 },
+                { angle: 2.42, width: 10 },
+                { angle: 3.72, width: 14 },
+                { angle: 5.05, width: 8 },
+            ],
+        },
+    },
+];
+function triangles(ribbon, scale, cx, cy) {
+    const result = [];
+    for (let i = 0; i < ribbon.indices.length; i += 3) {
+        const points = [];
+        for (let k = 0; k < 3; k += 1) {
+            const vertex = ribbon.indices[i + k] * 3;
+            points.push(`${cx + ribbon.positions[vertex] * scale},${cy + ribbon.positions[vertex + 2] * scale}`);
+        }
+        result.push(points.join(" "));
+    }
+    return result;
+}
+/**
+ * Deterministic close-up gallery of the shared road/junction mesh seam.
+ * @capability world-intersections inspect turns and junction meshes in a deterministic preview fixture
+ */
+export function StreetGeometryPreview({ className }) {
+    return (_jsx("div", { className: className, style: { minHeight: "100%", background: "radial-gradient(circle at 78% 68%, #25425a 0%, #142b40 28%, #0b1d2e 62%, #07131f 100%)", color: "#dbeafe", padding: 18, fontFamily: "ui-monospace, monospace" }, children: _jsxs("div", { style: { maxWidth: 1320, margin: "0 auto" }, children: [_jsx("h1", { style: { margin: "0 0 6px", fontSize: 24 }, children: "Street geometry close-ups" }), _jsx("p", { style: { margin: "0 0 20px", color: "#7dd3fc", fontSize: 13 }, children: "Compact carriageway-union junctions: 45\u00B0/90\u00B0 turns, unequal T, unequal cross, five-way. Pale = sidewalks; blue = pavement; cream = markings." }), _jsxs("div", { style: { display: "grid", gridTemplateColumns: "repeat(3, minmax(0, 1fr))", gap: 12 }, children: [cases.map((entry) => {
+                            const patternId = `grid-${entry.name.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
+                            const streets = entry.streets.map((street) => ({
+                                ...street,
+                                sidewalks: { left: 2.2, right: 2.2 },
+                                markings: { lines: [{ offset: 0, width: 0.2 }], stopLine: true },
+                            }));
+                            const geometry = buildTrimmedIntersections(streets, [entry.junction], () => 0, {
+                                curbReturnRadius: 2,
+                                apronMargin: 0.25,
+                                filletSegments: 10,
+                            });
+                            const surface = geometry.junctions[0];
+                            const markings = buildIntersectionMarkings(geometry, () => 0, {
+                                mouthClearance: 1.25,
+                                dashLength: 4.8,
+                                dashGap: 4,
+                            });
+                            let extent = 0;
+                            for (let i = 3; i < surface.positions.length; i += 3) {
+                                extent = Math.max(extent, Math.hypot(surface.positions[i], surface.positions[i + 2]));
+                            }
+                            return (_jsxs("section", { style: { background: "#10263a", border: "1px solid #285174", borderRadius: 10, overflow: "hidden" }, children: [_jsxs("div", { style: { padding: "8px 12px 3px", display: "flex", justifyContent: "space-between", gap: 8 }, children: [_jsx("strong", { style: { fontSize: 14 }, children: entry.name }), _jsxs("span", { style: { color: "#67e8f9", fontSize: 11 }, children: ["extent ", extent.toFixed(1)] })] }), _jsxs("svg", { viewBox: "0 0 280 205", role: "img", "aria-label": `${entry.name} road mesh`, style: { display: "block", width: "100%", height: "auto" }, children: [_jsx("defs", { children: _jsxs("pattern", { id: patternId, width: "20", height: "20", patternUnits: "userSpaceOnUse", children: [_jsx("rect", { width: "20", height: "20", fill: "#0d2234" }), _jsx("path", { d: "M 20 0 L 0 0 0 20", fill: "none", stroke: "#1d4b68", strokeWidth: "0.8" })] }) }), _jsx("rect", { width: "280", height: "205", fill: `url(#${patternId})` }), geometry.sidewalks.flatMap((ribbon, ri) => triangles(ribbon, 2.65, 140, 102).map((points, ti) => (_jsx("polygon", { points: points, fill: "#d8c9aa", stroke: "#d8c9aa", strokeWidth: "0.35" }, `s-r-${ri}-${ti}`)))), geometry.sidewalkAprons.flatMap((junction, ji) => triangles(junction, 2.65, 140, 102).map((points, ti) => (_jsx("polygon", { points: points, fill: "#d8c9aa", stroke: "#d8c9aa", strokeWidth: "0.35" }, `s-j-${ji}-${ti}`)))), geometry.ribbons.flatMap((ribbon, ri) => triangles(ribbon, 2.65, 140, 102).map((points, ti) => (_jsx("polygon", { points: points, fill: "#52677d", stroke: "#52677d", strokeWidth: "0.35" }, `r-${ri}-${ti}`)))), triangles(surface, 2.65, 140, 102).map((points, ti) => (_jsx("polygon", { points: points, fill: "#2479a4", stroke: "#2479a4", strokeWidth: "0.35" }, `j-${ti}`))), markings.flatMap((marking, mi) => triangles(marking, 2.65, 140, 102).map((points, ti) => (_jsx("polygon", { points: points, fill: "#f8fafc" }, `m-${mi}-${ti}`))))] })] }, entry.name));
+                        }), _jsxs("section", { style: { minHeight: 238, background: "linear-gradient(145deg, #18354c, #10263a)", border: "1px solid #356487", borderRadius: 10, padding: 18 }, children: [_jsx("strong", { style: { display: "block", marginBottom: 8, fontSize: 15 }, children: "Shared geometry contract" }), _jsx("p", { style: { margin: "0 0 14px", color: "#8ed8ef", fontSize: 12, lineHeight: 1.5 }, children: "Every panel is built from the same renderer-neutral meshes consumed by the Three.js city." }), [
+                                    ["#d8c9aa", "Sidewalk annulus", "No pavement overlap"],
+                                    ["#2479a4", "Junction apron", "Bounded by road widths"],
+                                    ["#f8fafc", "Lane guidance", "Mouth clearance + stop lines"],
+                                    ["#4ade80", "Terrain drape", "Every vertex sampled"],
+                                    ["#fbbf24", "Offset continuity", "Positive and negative"],
+                                ].map(([color, label, detail]) => (_jsxs("div", { style: { display: "grid", gridTemplateColumns: "12px 1fr auto", alignItems: "center", gap: 9, marginTop: 9, fontSize: 11 }, children: [_jsx("span", { style: { width: 10, height: 10, borderRadius: 2, background: color, boxShadow: `0 0 8px ${color}` } }), _jsx("span", { style: { color: "#e2edf5" }, children: label }), _jsx("span", { style: { color: "#82a9c2" }, children: detail })] }, label)))] })] })] }) }));
+}

package/dist/talentTree.d.ts

@@ -0,0 +1,60 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { TalentNodeDef, TalentTree as TalentTreeModel } from "@jgengine/core/game/talents";
+import { type TalentTreeView } from "@jgengine/core/game/talentTreeView";
+import { type GameIconName } from "./gameIcons.js";
+import { type HudFrameVariation } from "./hudFrame.js";
+/** How a node id resolves to display art: a built-in {@link GameIconName}, any node, or `null` for the default. */
+export type TalentIcon = GameIconName | ReactNode | null;
+/** Props for {@link TalentTree}. */
+export interface TalentTreeProps<TStat extends string = string> {
+    /**
+     * A precomputed render view (from `talentTreeView` or `talentTreeViewFrom`). Supply this to drive the
+     * widget from *any* unlock rule — a currency threshold, a level, a quest flag — not just point-spend.
+     * When given, `nodes`/`tree` are ignored. Otherwise pass `nodes` + `tree` for the point-spend path.
+     */
+    view?: TalentTreeView;
+    /** The tree's node definitions — the same array passed to `createTalentTree`. Used when `view` is omitted. */
+    nodes?: readonly TalentNodeDef<TStat>[];
+    /** The live talent-tree instance whose ranks/points drive node state. Used when `view` is omitted. */
+    tree?: TalentTreeModel<TStat>;
+    /** Fired with a node id when the player clicks a node that is currently allocatable. Wire it to your unlock/allocate effect (e.g. `tree.allocate`, or spend cash, or set a flag). */
+    onLearn?: (nodeId: string) => void;
+    /** Show the points-remaining badge in the frame header. Default `true`; pass `false` for trees with no point currency. */
+    showPoints?: boolean;
+    /** Resolve a node id to its icon. Default: keyword-match the id, else the node's initials. */
+    icon?: (nodeId: string) => TalentIcon;
+    /** Resolve a node id to a human label (tooltip title + accessible name). Default: the id. */
+    label?: (nodeId: string) => ReactNode;
+    /** Resolve a branch key to a column header. Default: the branch string (blank branch → no header). */
+    branchLabel?: (branch: string) => ReactNode;
+    /** Frame title. Default `Talents`. Pass `null` to render without a frame header. */
+    title?: ReactNode;
+    /** {@link HudFrame} skin. Default `themed`. */
+    variation?: HudFrameVariation;
+    /** Node tile diameter in px. Default 54. */
+    nodeSize?: number;
+    /** Horizontal gap between node columns in px. Default 30. */
+    columnGap?: number;
+    /** Vertical gap between tiers in px. Default 46. */
+    tierGap?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Drop-in talent / skill-tree widget over the existing progression model
+ * (`@jgengine/core/game/talents` + its `talentTreeView` selector). The game passes its node
+ * definitions and a live `createTalentTree` instance; the widget lays nodes out by branch column and
+ * prerequisite-depth tier, draws SVG prerequisite edges, styles each node learned/available/locked/maxed,
+ * shows an icon + rank badge, and calls `onLearn(nodeId)` when the player clicks a node that is
+ * currently allocatable. All layout, edge-drawing, and eligibility come from the model/selector — the
+ * widget never re-derives topology. Unskinned and HudTheme-token driven; node ids/branches are opaque
+ * game data the game supplies icons and labels for.
+ *
+ * For the point-spend path pass `nodes` + a live `tree`. To drive the tree from *any* other unlock
+ * rule (a currency threshold, a level, a quest flag), build a view with `talentTreeViewFrom` and pass
+ * it as `view` — the same widget then renders a money-gated upgrade tree or a condition-unlocked
+ * ability web, no renderer change.
+ *
+ * @capability talent-tree drop-in skill/talent/upgrade-tree widget — pass `nodes`+`tree` for point-spend or a precomputed `view` for any unlock rule; branch/tier layout, SVG prerequisite edges, learned/available/locked/maxed styling, icon + rank, onLearn
+ */
+export declare function TalentTree<TStat extends string = string>({ view: viewProp, nodes, tree, onLearn, icon, label, branchLabel, title, variation, nodeSize, columnGap, tierGap, showPoints, className, style, }: TalentTreeProps<TStat>): ReactNode;

package/dist/talentTree.js

@@ -0,0 +1,217 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { talentTreeView, } from "@jgengine/core/game/talentTreeView";
+import { GameIcon, iconForAction, iconForItemId, isGameIconName } from "./gameIcons.js";
+import { HudFrame } from "./hudFrame.js";
+const STATE_STYLE = {
+    locked: {
+        border: "1px solid rgba(148,163,184,0.28)",
+        bg: "var(--jg-slot-bg, rgba(12,14,20,0.72))",
+        opacity: 0.42,
+        glow: "none",
+    },
+    available: {
+        border: "2px solid var(--jg-accent, #38bdf8)",
+        bg: "var(--jg-slot-bg, rgba(12,14,20,0.72))",
+        opacity: 1,
+        glow: "0 0 0 3px color-mix(in srgb, var(--jg-accent, #38bdf8) 22%, transparent)",
+    },
+    learned: {
+        border: "2px solid var(--jg-accent, #38bdf8)",
+        bg: "color-mix(in srgb, var(--jg-accent, #38bdf8) 18%, rgba(12,14,20,0.8))",
+        opacity: 1,
+        glow: "0 0 10px color-mix(in srgb, var(--jg-accent, #38bdf8) 30%, transparent)",
+    },
+    maxed: {
+        border: "2px solid var(--jg-accent, #38bdf8)",
+        bg: "color-mix(in srgb, var(--jg-accent, #38bdf8) 34%, rgba(12,14,20,0.85))",
+        opacity: 1,
+        glow: "0 0 14px color-mix(in srgb, var(--jg-accent, #38bdf8) 45%, transparent)",
+    },
+};
+/** @internal Default icon: keyword-resolve the id through the shared game-icon rules, else render initials. */
+function DefaultNodeGlyph({ id, size }) {
+    const resolved = iconForItemId(id) ?? iconForAction(id);
+    if (resolved !== null)
+        return _jsx(GameIcon, { name: resolved, size: size });
+    const initials = id.replace(/[^a-zA-Z0-9]/g, "").slice(0, 2).toUpperCase() || "?";
+    return _jsx("span", { style: { fontSize: size * 0.5, fontWeight: 800, letterSpacing: 0.5 }, children: initials });
+}
+const BRANCH_GAP = 34;
+const HEADER_H = 22;
+/** @internal Assign each node a grid cell by branch column and tier row, then resolve to pixel centers. */
+function place(view, nodeSize, columnGap, tierGap) {
+    const cellW = nodeSize + columnGap;
+    const cellH = nodeSize + tierGap;
+    // Bucket nodes by branch, then by tier, to size each branch and slot nodes within a tier row.
+    const perBranch = new Map();
+    for (const branch of view.branches)
+        perBranch.set(branch, []);
+    for (const node of view.nodes)
+        perBranch.get(node.branch).push(node);
+    const x = new Map();
+    const y = new Map();
+    const headers = [];
+    const padX = columnGap / 2;
+    const padY = HEADER_H;
+    let colCursor = 0; // running column index across all branches
+    let branchIndex = 0;
+    for (const branch of view.branches) {
+        const branchNodes = perBranch.get(branch);
+        const byTier = new Map();
+        for (const node of branchNodes) {
+            const bucket = byTier.get(node.tier) ?? [];
+            bucket.push(node);
+            byTier.set(node.tier, bucket);
+        }
+        const branchWidth = Math.max(1, ...[...byTier.values()].map((b) => b.length));
+        const branchBaseX = padX + colCursor * cellW + branchIndex * BRANCH_GAP;
+        for (const [tier, bucket] of byTier) {
+            // Center this tier's nodes within the branch's column span.
+            const offset = (branchWidth - bucket.length) / 2;
+            bucket.forEach((node, i) => {
+                const cx = branchBaseX + (offset + i) * cellW + nodeSize / 2;
+                const cy = padY + tier * cellH + nodeSize / 2;
+                x.set(node.id, cx);
+                y.set(node.id, cy);
+            });
+        }
+        const cx = branchBaseX + (branchWidth * cellW) / 2;
+        headers.push({ branch, cx, top: 0 });
+        colCursor += branchWidth;
+        branchIndex += 1;
+    }
+    const totalCols = colCursor;
+    const width = padX * 2 + totalCols * cellW + Math.max(0, view.branches.length - 1) * BRANCH_GAP;
+    const height = padY + Math.max(1, view.tiers) * cellH;
+    return { x, y, width, height, headers };
+}
+/** @internal One SVG prerequisite edge, colored by whether it is currently met. */
+function Edge({ x1, y1, x2, y2, met }) {
+    return (_jsx("line", { x1: x1, y1: y1, x2: x2, y2: y2, stroke: met ? "var(--jg-accent, #38bdf8)" : "rgba(148,163,184,0.32)", strokeWidth: met ? 3 : 2, strokeLinecap: "round", strokeDasharray: met ? undefined : "5 6", opacity: met ? 0.9 : 0.7 }));
+}
+/** @internal A single talent node tile — icon, rank badge, state styling, click-to-learn. */
+function TalentNode({ node, cx, cy, size, glyph, label, onLearn, }) {
+    const s = STATE_STYLE[node.state];
+    const interactive = node.allocatable && onLearn !== undefined;
+    const showRank = node.maxRank > 1 || node.rank > 0;
+    const labelText = typeof label === "string" ? label : node.id;
+    return (_jsxs("button", { type: "button", "data-talent-node": node.id, "data-talent-state": node.state, "aria-label": `${labelText} — ${node.state}${node.maxRank > 1 ? `, rank ${node.rank} of ${node.maxRank}` : ""}`, title: labelText, disabled: !interactive, onClick: interactive ? () => onLearn(node.id) : undefined, style: {
+            position: "absolute",
+            left: cx - size / 2,
+            top: cy - size / 2,
+            width: size,
+            height: size,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            padding: 0,
+            borderRadius: "var(--jg-slot-radius, 12px)",
+            border: s.border,
+            background: s.bg,
+            color: "var(--jg-bar-text, #f4f6fb)",
+            opacity: s.opacity,
+            boxShadow: interactive ? `${s.glow}, 0 0 0 2px color-mix(in srgb, var(--jg-accent, #38bdf8) 40%, transparent)` : s.glow,
+            cursor: interactive ? "pointer" : "default",
+            pointerEvents: "auto",
+            boxSizing: "border-box",
+            transition: "box-shadow 120ms ease, opacity 120ms ease",
+        }, children: [_jsx("span", { "aria-hidden": true, style: { display: "flex", alignItems: "center", justifyContent: "center" }, children: glyph }), showRank ? (_jsxs("span", { "data-talent-rank": "", style: {
+                    position: "absolute",
+                    right: -6,
+                    bottom: -6,
+                    minWidth: 20,
+                    height: 18,
+                    padding: "0 4px",
+                    borderRadius: 9,
+                    background: node.state === "maxed" ? "var(--jg-accent, #38bdf8)" : "rgba(6,10,16,0.92)",
+                    color: node.state === "maxed" ? "#06121b" : "var(--jg-bar-text, #f4f6fb)",
+                    border: "1px solid var(--jg-accent, #38bdf8)",
+                    fontSize: 10.5,
+                    fontWeight: 800,
+                    fontVariantNumeric: "tabular-nums",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    boxSizing: "border-box",
+                }, children: [node.rank, "/", node.maxRank] })) : null] }));
+}
+/**
+ * Drop-in talent / skill-tree widget over the existing progression model
+ * (`@jgengine/core/game/talents` + its `talentTreeView` selector). The game passes its node
+ * definitions and a live `createTalentTree` instance; the widget lays nodes out by branch column and
+ * prerequisite-depth tier, draws SVG prerequisite edges, styles each node learned/available/locked/maxed,
+ * shows an icon + rank badge, and calls `onLearn(nodeId)` when the player clicks a node that is
+ * currently allocatable. All layout, edge-drawing, and eligibility come from the model/selector — the
+ * widget never re-derives topology. Unskinned and HudTheme-token driven; node ids/branches are opaque
+ * game data the game supplies icons and labels for.
+ *
+ * For the point-spend path pass `nodes` + a live `tree`. To drive the tree from *any* other unlock
+ * rule (a currency threshold, a level, a quest flag), build a view with `talentTreeViewFrom` and pass
+ * it as `view` — the same widget then renders a money-gated upgrade tree or a condition-unlocked
+ * ability web, no renderer change.
+ *
+ * @capability talent-tree drop-in skill/talent/upgrade-tree widget — pass `nodes`+`tree` for point-spend or a precomputed `view` for any unlock rule; branch/tier layout, SVG prerequisite edges, learned/available/locked/maxed styling, icon + rank, onLearn
+ */
+export function TalentTree({ view: viewProp, nodes, tree, onLearn, icon, label, branchLabel, title = "Talents", variation = "themed", nodeSize = 54, columnGap = 30, tierGap = 46, showPoints = true, className, style, }) {
+    if (viewProp === undefined && (nodes === undefined || tree === undefined)) {
+        throw new Error("TalentTree requires either a `view` prop or both `nodes` and `tree`.");
+    }
+    const view = viewProp ?? talentTreeView(nodes, tree);
+    const layout = place(view, nodeSize, columnGap, tierGap);
+    const resolveGlyph = (id) => {
+        const custom = icon?.(id);
+        if (custom === undefined || custom === null)
+            return _jsx(DefaultNodeGlyph, { id: id, size: nodeSize * 0.5 });
+        if (typeof custom === "string" && isGameIconName(custom))
+            return _jsx(GameIcon, { name: custom, size: nodeSize * 0.5 });
+        return custom;
+    };
+    const resolveLabel = (id) => label?.(id) ?? id;
+    const resolveBranch = (branch) => branchLabel?.(branch) ?? (branch === "" ? null : branch);
+    const centerOf = (id) => {
+        const x = layout.x.get(id);
+        const y = layout.y.get(id);
+        return x === undefined || y === undefined ? null : { x, y };
+    };
+    const body = (_jsxs("div", { "data-talent-tree": "", style: { position: "relative", width: layout.width, height: layout.height, margin: "0 auto" }, children: [layout.headers.map((header) => {
+                const text = resolveBranch(header.branch);
+                if (text === null)
+                    return null;
+                return (_jsx("div", { "data-talent-branch": header.branch, style: {
+                        position: "absolute",
+                        left: header.cx,
+                        top: header.top,
+                        transform: "translateX(-50%)",
+                        fontSize: 10,
+                        fontWeight: 700,
+                        letterSpacing: 1.4,
+                        textTransform: "uppercase",
+                        opacity: 0.7,
+                        color: "var(--jg-bar-text, #f4f6fb)",
+                        whiteSpace: "nowrap",
+                    }, children: text }, `h-${header.branch}`));
+            }), _jsx("svg", { width: layout.width, height: layout.height, style: { position: "absolute", inset: 0, pointerEvents: "none", overflow: "visible" }, "aria-hidden": true, children: view.nodes.flatMap((node) => {
+                    const to = centerOf(node.id);
+                    if (to === null)
+                        return [];
+                    return node.requires.flatMap((edge) => {
+                        const from = centerOf(edge.from);
+                        if (from === null)
+                            return [];
+                        return [
+                            _jsx(Edge, { x1: from.x, y1: from.y, x2: to.x, y2: to.y, met: edge.met }, `${edge.from}->${node.id}`),
+                        ];
+                    });
+                }) }), view.nodes.map((node) => {
+                const center = centerOf(node.id);
+                if (center === null)
+                    return null;
+                return (_jsx(TalentNode, { node: node, cx: center.x, cy: center.y, size: nodeSize, glyph: resolveGlyph(node.id), label: resolveLabel(node.id), ...(onLearn === undefined ? {} : { onLearn }) }, node.id));
+            })] }));
+    const pointsBadge = showPoints ? (_jsxs("span", { "data-talent-points": "", style: { fontVariantNumeric: "tabular-nums" }, children: [view.pointsAvailable, " pt", view.pointsAvailable === 1 ? "" : "s"] })) : undefined;
+    if (title === null) {
+        return (_jsx("div", { className: className, style: style, children: body }));
+    }
+    return (_jsx(HudFrame, { variation: variation, title: title, ...(pointsBadge === undefined ? {} : { aside: pointsBadge }), interactive: true, padding: 16, ...(className === undefined ? {} : { className }), ...(style === undefined ? {} : { style }), children: body }));
+}

package/dist/timerReadout.d.ts

@@ -0,0 +1,90 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { TimerRead, TimerSet } from "@jgengine/core/time/timerSet";
+/**
+ * Which value a readout leads with. `"auto"` follows the timer's direction —
+ * remaining for a countdown, elapsed for a countup charge.
+ */
+export type TimerReadoutSource = "auto" | "remaining" | "elapsed";
+/** Digital text format for a timer readout. */
+export type TimerFormat = "mm:ss" | "m:ss.d" | "ss.d";
+/**
+ * Format a millisecond duration as digital timer text — `mm:ss` (default),
+ * `m:ss.d` (with tenths), or `ss.d` (seconds + tenths). Negative inputs clamp
+ * to zero. No genre meaning: the same helper serves a round clock, a respawn
+ * countdown, or an ability charge readout.
+ *
+ * @capability timer-readout-format format milliseconds as digital timer text (mm:ss / m:ss.d / ss.d)
+ */
+export declare function formatTimerMs(ms: number, format?: TimerFormat): string;
+/**
+ * Subscribe to a single timer and re-read it every animation frame while
+ * mounted, so a HUD readout stays live without the game hand-rolling interval
+ * math. Reuses one read object (allocation-aware). Returns `null` for an unknown
+ * id. Pass `active={false}` to freeze the per-frame tick (e.g. an off-screen HUD).
+ *
+ * @capability use-timer React hook binding one timer to a component with a per-frame re-read
+ */
+export declare function useTimerRead(timer: TimerSet, id: string, active?: boolean): TimerRead | null;
+/** Props for {@link TimerReadout}. */
+export interface TimerReadoutProps {
+    /** The timer set to read from. */
+    timer: TimerSet;
+    /** Id of the timer to display (free string). */
+    id: string;
+    /** Which value to show. Default `"auto"` (remaining for countdown, elapsed for countup). */
+    source?: TimerReadoutSource;
+    /** Digital format. Default `"mm:ss"`. */
+    format?: TimerFormat;
+    /** Text shown when the timer id is unknown. Default `"--:--"`. */
+    placeholder?: string;
+    /** Freeze the per-frame tick when false. Default `true`. */
+    active?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A live digital timer readout (mm:ss / m:ss.d) driven off a {@link TimerSet}.
+ * It re-reads every frame and formats remaining or elapsed time — a round clock,
+ * a respawn countdown, or an ability charge, all the same widget. HudTheme-skinned
+ * via `--jg-bar-text`; reskin with `style` or the theme tokens.
+ *
+ * @capability timer-readout live digital mm:ss/m:ss.d timer readout bound to a TimerSet
+ */
+export declare function TimerReadout({ timer, id, source, format, placeholder, active, className, style, }: TimerReadoutProps): ReactNode;
+/** Props for {@link TimerRing}. */
+export interface TimerRingProps {
+    /** The timer set to read from. */
+    timer: TimerSet;
+    /** Id of the timer to display (free string). */
+    id: string;
+    /** Outer diameter in px. Default `72`. */
+    size?: number;
+    /** Ring stroke thickness in px. Default `8`. */
+    thickness?: number;
+    /**
+     * How the arc maps to time. `"fill"` (default) sweeps from empty to full as
+     * time passes (a charge/cooldown filling); `"drain"` starts full and empties
+     * (a countdown running out).
+     */
+    mode?: "fill" | "drain";
+    /** Ring color. Default the HudTheme accent token. */
+    color?: string;
+    /** Track (unfilled) color. Default the HudTheme bar-track token. */
+    trackColor?: string;
+    /** Optional center content (e.g. a {@link TimerReadout} or an icon). */
+    children?: ReactNode;
+    /** Freeze the per-frame tick when false. Default `true`. */
+    active?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A radial charge/cooldown ring driven off a {@link TimerSet}'s `progress01`.
+ * Re-reads every frame and sweeps an SVG arc as the timer advances — ability
+ * charge, cooldown wipe, respawn ring, capture progress, all the same widget.
+ * `mode` chooses filling vs. draining; center `children` can hold a readout.
+ * HudTheme-skinned via `--jg-accent` / `--jg-bar-track`.
+ *
+ * @capability timer-ring radial SVG charge/cooldown ring bound to a TimerSet's progress
+ */
+export declare function TimerRing({ timer, id, size, thickness, mode, color, trackColor, children, active, className, style, }: TimerRingProps): ReactNode;

package/dist/timerReadout.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer, useRef } from "react";
+function pad2(n) {
+    return n < 10 ? `0${n}` : `${n}`;
+}
+/**
+ * Format a millisecond duration as digital timer text — `mm:ss` (default),
+ * `m:ss.d` (with tenths), or `ss.d` (seconds + tenths). Negative inputs clamp
+ * to zero. No genre meaning: the same helper serves a round clock, a respawn
+ * countdown, or an ability charge readout.
+ *
+ * @capability timer-readout-format format milliseconds as digital timer text (mm:ss / m:ss.d / ss.d)
+ */
+export function formatTimerMs(ms, format = "mm:ss") {
+    const clamped = ms > 0 ? ms : 0;
+    const totalSeconds = clamped / 1000;
+    if (format === "ss.d") {
+        return `${Math.floor(totalSeconds)}.${Math.floor((clamped % 1000) / 100)}`;
+    }
+    const whole = Math.floor(totalSeconds);
+    const minutes = Math.floor(whole / 60);
+    const seconds = whole % 60;
+    if (format === "m:ss.d") {
+        const tenths = Math.floor((clamped % 1000) / 100);
+        return `${minutes}:${pad2(seconds)}.${tenths}`;
+    }
+    return `${pad2(minutes)}:${pad2(seconds)}`;
+}
+function pickValue(read, source) {
+    if (source === "remaining")
+        return read.remainingMs;
+    if (source === "elapsed")
+        return read.elapsedMs;
+    return read.direction === "up" ? read.elapsedMs : read.remainingMs;
+}
+const BLANK = {
+    id: "",
+    direction: "down",
+    remainingMs: 0,
+    elapsedMs: 0,
+    durationMs: 0,
+    progress01: 0,
+    running: false,
+    expired: false,
+};
+/**
+ * Subscribe to a single timer and re-read it every animation frame while
+ * mounted, so a HUD readout stays live without the game hand-rolling interval
+ * math. Reuses one read object (allocation-aware). Returns `null` for an unknown
+ * id. Pass `active={false}` to freeze the per-frame tick (e.g. an off-screen HUD).
+ *
+ * @capability use-timer React hook binding one timer to a component with a per-frame re-read
+ */
+export function useTimerRead(timer, id, active = true) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    const out = useRef({ ...BLANK });
+    useEffect(() => {
+        if (!active)
+            return;
+        let raf = 0;
+        const loop = () => {
+            bump();
+            raf = requestAnimationFrame(loop);
+        };
+        raf = requestAnimationFrame(loop);
+        return () => cancelAnimationFrame(raf);
+    }, [active]);
+    return timer.read(id, out.current);
+}
+/**
+ * A live digital timer readout (mm:ss / m:ss.d) driven off a {@link TimerSet}.
+ * It re-reads every frame and formats remaining or elapsed time — a round clock,
+ * a respawn countdown, or an ability charge, all the same widget. HudTheme-skinned
+ * via `--jg-bar-text`; reskin with `style` or the theme tokens.
+ *
+ * @capability timer-readout live digital mm:ss/m:ss.d timer readout bound to a TimerSet
+ */
+export function TimerReadout({ timer, id, source = "auto", format = "mm:ss", placeholder = "--:--", active = true, className, style, }) {
+    const read = useTimerRead(timer, id, active);
+    const text = read === null ? placeholder : formatTimerMs(pickValue(read, source), format);
+    return (_jsx("span", { className: className, style: {
+            fontVariantNumeric: "tabular-nums",
+            fontWeight: 700,
+            color: "var(--jg-bar-text, #e2e8f0)",
+            ...style,
+        }, children: text }));
+}
+/**
+ * A radial charge/cooldown ring driven off a {@link TimerSet}'s `progress01`.
+ * Re-reads every frame and sweeps an SVG arc as the timer advances — ability
+ * charge, cooldown wipe, respawn ring, capture progress, all the same widget.
+ * `mode` chooses filling vs. draining; center `children` can hold a readout.
+ * HudTheme-skinned via `--jg-accent` / `--jg-bar-track`.
+ *
+ * @capability timer-ring radial SVG charge/cooldown ring bound to a TimerSet's progress
+ */
+export function TimerRing({ timer, id, size = 72, thickness = 8, mode = "fill", color = "var(--jg-accent, #38bdf8)", trackColor = "var(--jg-bar-track, rgba(148,163,184,0.25))", children, active = true, className, style, }) {
+    const read = useTimerRead(timer, id, active);
+    const fill = read === null ? 0 : mode === "drain" ? 1 - read.progress01 : read.progress01;
+    const radius = (size - thickness) / 2;
+    const circumference = 2 * Math.PI * radius;
+    const dashOffset = circumference * (1 - Math.max(0, Math.min(1, fill)));
+    return (_jsxs("div", { className: className, style: { position: "relative", width: size, height: size, display: "inline-flex", ...style }, children: [_jsxs("svg", { width: size, height: size, viewBox: `0 0 ${size} ${size}`, style: { transform: "rotate(-90deg)" }, children: [_jsx("circle", { cx: size / 2, cy: size / 2, r: radius, fill: "none", stroke: trackColor, strokeWidth: thickness }), _jsx("circle", { cx: size / 2, cy: size / 2, r: radius, fill: "none", stroke: color, strokeWidth: thickness, strokeLinecap: "round", strokeDasharray: circumference, strokeDashoffset: dashOffset })] }), children !== undefined && (_jsx("div", { style: {
+                    position: "absolute",
+                    inset: 0,
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    fontSize: Math.max(11, size * 0.2),
+                }, children: children }))] }));
+}