@jgengine/react 0.11.0 → 0.12.0

package/dist/hudThemePreview.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { AmmoCounter, ExperienceBar, HealthBar, ManaBar, ShieldBar } from "./bars.js";
+import { HudFrame } from "./hudFrame.js";
+import { HUD_THEME_PRESETS, defaultHudTheme, hudThemeVars } from "./hudTheme.js";
+/**
+ * A deterministic preset matrix for {@link HudTheme} (#1034): every genre preset × (bars + a themed
+ * frame + a slot row), rendered from static values. One `hudThemeVars(theme)` block per cell drives
+ * the atomic bars, the `HudFrame variation="themed"`, and the slot chrome together — proof that a
+ * single theme restyles all the shared chrome at once. Renders identically every time (screenshots).
+ */
+function Slot({ index }) {
+    return (_jsx("div", { style: {
+            width: 34,
+            height: 34,
+            background: "var(--jg-slot-bg, rgba(12,14,20,0.7))",
+            border: "var(--jg-slot-border, 1px solid rgba(255,255,255,0.12))",
+            borderRadius: "var(--jg-slot-radius, 8px)",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            fontSize: 10,
+            color: "var(--jg-bar-text, #f4f6fb)",
+            opacity: index === 0 ? 1 : 0.6,
+        }, children: index + 1 }));
+}
+function ThemeCell({ name, theme }) {
+    return (_jsx("div", { style: { ...hudThemeVars(theme), width: 260 }, children: _jsx(HudFrame, { variation: "themed", title: name, padding: 12, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 7 }, children: [_jsx(HealthBar, { value: 78, max: 100, label: "HP", width: "100%" }), _jsx(ManaBar, { value: 50, max: 80, label: "MP", width: "100%" }), _jsx(ShieldBar, { value: 30, max: 60, label: "SH", width: "100%" }), _jsx(ExperienceBar, { value: 4, max: 10, segments: 10, showValue: false, label: "XP", width: "100%" }), _jsx(AmmoCounter, { loaded: 17, reserve: 90, magazine: 30, width: "100%" }), _jsx("div", { style: { display: "flex", gap: 6, marginTop: 2 }, children: [0, 1, 2, 3].map((index) => (_jsx(Slot, { index: index }, index))) })] }) }) }));
+}
+/** Renders the default theme plus every genre preset as a deterministic matrix. */
+export function HudThemePreview({ className }) {
+    const cells = [
+        ["default", defaultHudTheme],
+        ...Object.entries(HUD_THEME_PRESETS),
+    ];
+    return (_jsx("div", { "data-hud-theme-preview": true, className: className, style: { display: "flex", gap: 18, flexWrap: "wrap", padding: 22, fontFamily: "system-ui, sans-serif", background: "#0e1216" }, children: cells.map(([name, theme]) => (_jsx(ThemeCell, { name: name, theme: theme }, name))) }));
+}

package/dist/iconTreatment.d.ts

@@ -0,0 +1,50 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type GameIconName } from "./gameIcons.js";
+/**
+ * `IconTreatment` (#1035): a procedural painted-icon face — a glyph over a school-keyed radial
+ * gradient, with a vignette inset shadow, a top gloss highlight, and optional count/keycap badges.
+ * Turns the engine's flat white `GameIcon` glyphs (and game-icons.net SVGs) into painted ability /
+ * item icons that read as AAA slots, not debug UI. Theme-aware: the frame reads the `--jg-slot-*`
+ * and `--jg-accent` `HudTheme` tokens (#1034), so a theme change re-skins every treated icon.
+ *
+ * @capability hud-icons painted-icon treatment for hotbar/action slots — glyph + gradient + count badge
+ */
+/** Element/school palette key — drives the radial gradient behind the glyph. */
+export type IconSchool = "fire" | "frost" | "arcane" | "nature" | "holy" | "tech" | "shadow" | "steel" | "neutral";
+/** Infers an {@link IconSchool} from an item id (keyword match); `neutral` when nothing matches. */
+export declare function schoolForItem(itemId: string): IconSchool;
+/** Infers an {@link IconSchool} from an action id (keyword match); `neutral` when nothing matches. */
+export declare function schoolForAction(action: string): IconSchool;
+/** Props for {@link IconTreatment}. */
+export interface IconTreatmentProps {
+    /** A `GameIcon` name to render as the glyph. */
+    icon?: GameIconName;
+    /** Or an explicit glyph node (a game-icons.net SVG, an `<img>`, custom art). Wins over `icon`. */
+    glyph?: ReactNode;
+    /** School/element gradient behind the glyph. Default `neutral`. */
+    school?: IconSchool;
+    /** Face size in px. Default 44. */
+    size?: number;
+    /** Stack count — a badge is drawn when > 1. */
+    count?: number;
+    /** Keycap/hotkey drawn top-left. */
+    keycap?: string;
+    /** Active/selected ring using `--jg-accent`. */
+    active?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/** A painted icon face — gradient + vignette + gloss behind a glyph, with count/keycap badges. */
+export declare function IconTreatment({ icon, glyph, school, size, count, keycap, active, className, style, }: IconTreatmentProps): import("react").JSX.Element;
+/** Maps an item id to a treated icon — resolves a `GameIcon` glyph and an inferred school. */
+export declare function treatedItemIcon(itemId: string, options?: {
+    size?: number;
+    count?: number;
+    keycap?: string;
+}): ReactNode;
+/** A ready-made `ActionButton` `renderIcon` that paints the action's `GameIcon` with a treatment. */
+export declare function treatedActionIcon(action: {
+    id?: string;
+    label?: string;
+    icon?: ReactNode;
+}, size?: number): ReactNode;

package/dist/iconTreatment.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { GameIcon, iconForAction, iconForItemId } from "./gameIcons.js";
+const SCHOOL_GRADIENT = {
+    fire: ["#ff8a3d", "#661805"],
+    frost: ["#8fe3ff", "#0e3357"],
+    arcane: ["#c58cff", "#341552"],
+    nature: ["#8fe36b", "#194013"],
+    holy: ["#ffe08a", "#6b4d0f"],
+    tech: ["#5fe0c8", "#0c3f3a"],
+    shadow: ["#9a7bd0", "#1b0d2b"],
+    steel: ["#c8d0da", "#333b45"],
+    neutral: ["#9aa3ad", "#242a31"],
+};
+const SCHOOL_RULES = [
+    [["fire", "flame", "burn", "lava", "ember", "molotov", "torch"], "fire"],
+    [["frost", "ice", "freeze", "snow", "water", "aqua", "chill"], "frost"],
+    [["arcane", "magic", "mana", "rune", "spell", "mystic", "void"], "arcane"],
+    [["nature", "leaf", "poison", "vine", "earth", "herb", "wood", "beast"], "nature"],
+    [["holy", "light", "heal", "divine", "bless", "sun", "cleric"], "holy"],
+    [["tech", "laser", "cyber", "robot", "energy", "plasma", "gadget"], "tech"],
+    [["shadow", "dark", "curse", "necro", "death", "blood", "demon"], "shadow"],
+    [["sword", "axe", "hammer", "spear", "dagger", "armor", "shield", "gun", "bow", "metal", "steel"], "steel"],
+];
+function schoolFrom(text) {
+    const lower = text.toLowerCase();
+    for (const [keys, school] of SCHOOL_RULES) {
+        if (keys.some((key) => lower.includes(key)))
+            return school;
+    }
+    return "neutral";
+}
+/** Infers an {@link IconSchool} from an item id (keyword match); `neutral` when nothing matches. */
+export function schoolForItem(itemId) {
+    return schoolFrom(itemId);
+}
+/** Infers an {@link IconSchool} from an action id (keyword match); `neutral` when nothing matches. */
+export function schoolForAction(action) {
+    return schoolFrom(action);
+}
+/** A painted icon face — gradient + vignette + gloss behind a glyph, with count/keycap badges. */
+export function IconTreatment({ icon, glyph, school = "neutral", size = 44, count, keycap, active = false, className, style, }) {
+    const [g0, g1] = SCHOOL_GRADIENT[school];
+    const content = glyph ?? (icon !== undefined ? _jsx(GameIcon, { name: icon, size: Math.round(size * 0.58), color: "#fdfdff" }) : null);
+    return (_jsxs("div", { className: className, "data-icon-treatment": school, style: {
+            position: "relative",
+            width: size,
+            height: size,
+            borderRadius: "var(--jg-slot-radius, 9px)",
+            background: `radial-gradient(circle at 38% 30%, ${g0}, ${g1})`,
+            border: active ? "1px solid var(--jg-accent, #38bdf8)" : "var(--jg-slot-border, 1px solid rgba(255,255,255,0.16))",
+            boxShadow: active
+                ? "0 0 0 1px var(--jg-accent, #38bdf8), 0 0 10px rgba(56,189,248,0.5), inset 0 -6px 12px rgba(0,0,0,0.5)"
+                : "inset 0 -7px 13px rgba(0,0,0,0.55), inset 0 2px 3px rgba(255,255,255,0.2)",
+            overflow: "hidden",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            boxSizing: "border-box",
+            ...style,
+        }, children: [_jsx("div", { style: { position: "absolute", inset: 0, background: "linear-gradient(180deg, rgba(255,255,255,0.3), rgba(255,255,255,0) 46%)", pointerEvents: "none" } }), _jsx("div", { style: { position: "absolute", inset: 0, borderRadius: "inherit", boxShadow: "inset 0 0 12px rgba(0,0,0,0.55)", pointerEvents: "none" } }), content, keycap !== undefined ? (_jsx("span", { style: { position: "absolute", top: 1, left: 4, fontSize: 9, fontWeight: 700, color: "#fff", opacity: 0.75, textShadow: "0 1px 2px rgba(0,0,0,0.9)" }, children: keycap })) : null, count !== undefined && count > 1 ? (_jsx("span", { "data-count": true, style: {
+                    position: "absolute",
+                    bottom: 1,
+                    right: 3,
+                    fontSize: 11,
+                    fontWeight: 800,
+                    color: "#fff",
+                    fontVariantNumeric: "tabular-nums",
+                    textShadow: "0 1px 2px #000, 0 0 3px #000",
+                }, children: count })) : null] }));
+}
+/** Maps an item id to a treated icon — resolves a `GameIcon` glyph and an inferred school. */
+export function treatedItemIcon(itemId, options = {}) {
+    const icon = iconForItemId(itemId) ?? undefined;
+    return (_jsx(IconTreatment, { ...(icon === undefined ? {} : { icon }), school: schoolForItem(itemId), ...(options.size === undefined ? {} : { size: options.size }), ...(options.count === undefined ? {} : { count: options.count }), ...(options.keycap === undefined ? {} : { keycap: options.keycap }) }));
+}
+/** A ready-made `ActionButton` `renderIcon` that paints the action's `GameIcon` with a treatment. */
+export function treatedActionIcon(action, size = 40) {
+    const key = action.id ?? action.label ?? "";
+    const named = iconForAction(key);
+    if (named === null)
+        return action.icon ?? null;
+    return _jsx(IconTreatment, { icon: named, school: schoolForAction(key), size: size });
+}

package/dist/iconsPreview.d.ts

@@ -0,0 +1,4 @@
+/** Renders the school-gradient row and a treated-icon hotbar — the deterministic #1035 fixture. */
+export declare function IconsPreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/iconsPreview.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { IconTreatment } from "./iconTreatment.js";
+/**
+ * A deterministic showcase of the painted {@link IconTreatment} (#1035): a school row (one gradient
+ * each) and a mock hotbar of treated item icons with count badges and an active slot. Static, so it
+ * screenshots identically every time. This is the before/after evidence vs. raw `itemId` text slots.
+ */
+const SCHOOLS = [
+    ["fire", "bomb"],
+    ["frost", "wand"],
+    ["arcane", "staff"],
+    ["nature", "bow"],
+    ["holy", "shield"],
+    ["tech", "gun"],
+    ["shadow", "dagger"],
+    ["steel", "sword"],
+];
+const HOTBAR = [
+    { icon: "sword", school: "steel" },
+    { icon: "bow", school: "nature" },
+    { icon: "bomb", school: "fire", count: 12 },
+    { icon: "shield", school: "holy" },
+    { icon: "staff", school: "arcane" },
+    { icon: "wand", school: "frost", count: 3 },
+];
+/** Renders the school-gradient row and a treated-icon hotbar — the deterministic #1035 fixture. */
+export function IconsPreview({ className }) {
+    return (_jsxs("div", { "data-icons-preview": true, className: className, style: { display: "flex", flexDirection: "column", gap: 22, padding: 26, background: "#0e1216", fontFamily: "system-ui, sans-serif", color: "#e8edf2" }, children: [_jsxs("div", { children: [_jsx("div", { style: { fontSize: 11, fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", opacity: 0.6, marginBottom: 8 }, children: "school gradients" }), _jsx("div", { style: { display: "flex", gap: 10 }, children: SCHOOLS.map(([school, icon]) => (_jsx(IconTreatment, { icon: icon, school: school, size: 52 }, school))) })] }), _jsxs("div", { children: [_jsx("div", { style: { fontSize: 11, fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", opacity: 0.6, marginBottom: 8 }, children: "hotbar \u2014 treated icons + count badges (slot 1 active)" }), _jsx("div", { style: { display: "flex", gap: 6 }, children: HOTBAR.map((entry, index) => (_jsx(IconTreatment, { icon: entry.icon, school: entry.school, size: 50, keycap: String(index + 1), active: index === 0, ...(entry.count === undefined ? {} : { count: entry.count }) }, index))) })] })] }));
+}

package/dist/index.d.ts

@@ -10,6 +10,14 @@ export * from "./settings.js";
 export * from "./save.js";
 export * from "./components.js";
 export * from "./hud.js";
+export * from "./bars.js";
+export * from "./barsPreview.js";
+export * from "./iconTreatment.js";
+export * from "./iconsPreview.js";
+export * from "./slots.js";
+export * from "./hudTheme.js";
+export * from "./hudThemePreview.js";
+export * from "./hudFrame.js";
 export * from "./keyHint.js";
 export * from "./startScreen.js";
 export * from "./engineStore.js";
@@ -18,6 +26,7 @@ export * from "./cards.js";
 export * from "./actionHud.js";
 export * from "./selectionHud.js";
 export * from "./hudLayout.js";
+export * from "./hudLayoutPersist.js";
 export * from "./hudViewport.js";
 export * from "./gameViewport.js";
 export * from "./rotateDevice.js";

package/dist/index.js

@@ -10,6 +10,14 @@ export * from "./settings.js";
 export * from "./save.js";
 export * from "./components.js";
 export * from "./hud.js";
+export * from "./bars.js";
+export * from "./barsPreview.js";
+export * from "./iconTreatment.js";
+export * from "./iconsPreview.js";
+export * from "./slots.js";
+export * from "./hudTheme.js";
+export * from "./hudThemePreview.js";
+export * from "./hudFrame.js";
 export * from "./keyHint.js";
 export * from "./startScreen.js";
 export * from "./engineStore.js";
@@ -18,6 +26,7 @@ export * from "./cards.js";
 export * from "./actionHud.js";
 export * from "./selectionHud.js";
 export * from "./hudLayout.js";
+export * from "./hudLayoutPersist.js";
 export * from "./hudViewport.js";
 export * from "./gameViewport.js";
 export * from "./rotateDevice.js";

package/dist/map.d.ts

@@ -1,12 +1,16 @@
-import { type ReactNode } from "react";
+import { type CSSProperties, type ReactNode } from "react";
 import type { FogField } from "@jgengine/core/world/fog";
-import { type MapMarker, type MarkerKindStyle, type MarkerSet } from "@jgengine/core/world/markers";
+import { type MapMarker, type MarkerCollection, type MarkerKindStyle, type MarkerSource, type MarkerSet, type MarkerView } from "@jgengine/core/world/markers";
 import { type MinimapView, type WorldXZ } from "@jgengine/core/world/minimap";
 import { type MapCellStates, type MapRoute, type MapZone } from "@jgengine/core/world/mapLayers";
-export declare function useMarkers(markers: MarkerSet): readonly MapMarker[];
+/** Subscribe to a native marker set or external marker source, or read a static marker array. */
+export declare function useMarkers<TMeta = unknown>(markers: MarkerSet<TMeta>): readonly MapMarker<TMeta>[];
+export declare function useMarkers<TMarker extends MarkerView>(markers: readonly TMarker[] | MarkerSource<TMarker>): readonly TMarker[];
+export declare function useMarkers(markers: MarkerCollection): readonly MarkerView[];
 export declare function useFog(fog: FogField): ReturnType<FogField["cells"]>;
 export interface MinimapProps {
-    markers: MarkerSet;
+    /** Static views, an external marker source, or a native JGengine MarkerSet. */
+    markers: MarkerCollection;
     center: WorldXZ;
     worldRadius: number;
     fog?: FogField;
@@ -27,6 +31,8 @@ export interface MinimapProps {
     /** Click-to-pin seam (#285.6): receives the clicked world XZ via `unprojectFromMinimap`. */
     onWorldClick?: (world: WorldXZ) => void;
     className?: string;
+    /** Caller-owned outer chrome overrides, applied after the built-in defaults. */
+    style?: CSSProperties;
     title?: string;
     children?: ReactNode;
 }
@@ -38,12 +44,13 @@ export interface MapBounds {
 }
 /**
  * Framed circular minimap: optional baked terrain background, reveal-on-event
- * fog overlay, categorized marker icons, and a facing arrow. Reads a core
- * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ * fog overlay, categorized marker icons, and a facing arrow. Reads static
+ * marker views, an external marker source, or a native `MarkerSet`; supply
+ * your own `kindStyles` palette to reskin. Does not require `GameProvider`.
  *
  * @capability minimap framed circular minimap with terrain bake, fog, markers, and facing arrow
  */
-export declare function Minimap({ markers, center, worldRadius, fog, size, facingYaw, rotate, kindStyles, background, mapBounds, routes, zones, cellStates, onWorldClick, className, title, children, }: MinimapProps): ReactNode;
+export declare function Minimap({ markers, center, worldRadius, fog, size, facingYaw, rotate, kindStyles, background, mapBounds, routes, zones, cellStates, onWorldClick, className, style, title, children, }: MinimapProps): ReactNode;
 /** One dot (or, with `heading`, a rotated arrow) drawn by `MinimapChrome`. */
 export interface MinimapChromeMarker {
     id: string;
@@ -91,7 +98,7 @@ export interface CompassProps {
     /** Facing yaw (`rotationY`, forward = `(sin yaw, cos yaw)`) of the tracked entity — pass it raw, never pre-converted to a bearing. */
     facingYaw: number;
     center?: WorldXZ;
-    markers?: MarkerSet;
+    markers?: MarkerCollection;
     width?: number;
     fov?: number;
     kindStyles?: Record<string, MarkerKindStyle>;
@@ -99,7 +106,8 @@ export interface CompassProps {
 }
 /**
  * Horizontal compass strip centered on the player's facing direction, with the
- * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
+ * eight cardinals and optional marker pips from static views, an external
+ * source, or a native `MarkerSet`.
  */
 export declare function Compass({ facingYaw, center, markers, width, fov, kindStyles, className, }: CompassProps): ReactNode;
 /** Props for `MinimapPanel` — all `MinimapProps` plus the zone-label/clock header and compass slots. */
@@ -125,8 +133,62 @@ export interface MinimapPanelProps extends MinimapProps {
  * @capability minimap-panel circular minimap with zone label, clock, and compass composed together
  */
 export declare function MinimapPanel({ zoneLabel, clock, showCompass, compassProps, headerClassName, zoneLabelClassName, clockClassName, compassClassName, children, ...minimapProps }: MinimapPanelProps): ReactNode;
+/** A colored span across the {@link MinimapTrack} rail, given by 0..1 `start`/`end` fractions (e.g. from core `trackFraction`). */
+export interface MinimapTrackSpan {
+    id: string;
+    /** 0..1 fraction where the span starts. */
+    start: number;
+    /** 0..1 fraction where the span ends. */
+    end: number;
+    /** Fill color; defaults to a translucent white. */
+    color?: string;
+    /** Tooltip / accessible label for the span. */
+    label?: string;
+}
+/** A point marker on the {@link MinimapTrack} rail at a 0..1 fraction (e.g. a gate, the exit, or the player). */
+export interface MinimapTrackPip {
+    id: string;
+    /** 0..1 fraction along the rail. */
+    at: number;
+    /** Marker color; defaults to the rail foreground. */
+    color?: string;
+    /** Accessible label for the marker. */
+    label?: string;
+    /** Tooltip text (rendered as the `title` attribute). */
+    title?: string;
+    /** Silhouette: `gate` (thin tall bar) or a `dot`/`exit`/`player` circle of increasing size (default `dot`). */
+    shape?: "gate" | "dot" | "exit" | "player";
+}
+/** Props for {@link MinimapTrack}. */
+export interface MinimapTrackProps {
+    /** Colored zone spans painted along the rail. */
+    spans?: readonly MinimapTrackSpan[];
+    /** Point markers (gates, exit, player) placed by 0..1 fraction. */
+    pips?: readonly MinimapTrackPip[];
+    /** Rail width (default `100%`). */
+    width?: number | string;
+    /** Rail thickness in px (default 12). */
+    height?: number;
+    /** Rail track color (default `rgba(255,255,255,0.10)`). */
+    railColor?: string;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+/**
+ * Horizontal linear track minimap — a rounded progress rail with colored zone
+ * `spans` and gate/exit/player `pips` positioned by 0..1 fraction. The
+ * structural counterpart to the radial {@link Minimap} for corridor/route
+ * games: fractions are supplied by the caller (via core `trackFraction`), so it
+ * reads no store and stays presentation-only, sharing chrome with the radial
+ * minimap.
+ *
+ * @capability minimap-track-hud horizontal linear track minimap (corridor/route progress) — colored zone spans and gate/player pips positioned by 0..1 fraction, sharing chrome with the radial Minimap
+ */
+export declare function MinimapTrack({ spans, pips, width, height, railColor, className, style, children, }: MinimapTrackProps): ReactNode;
 export interface WorldMapProps {
-    markers: MarkerSet;
+    /** Static views, an external marker source, or a native JGengine MarkerSet. */
+    markers: MarkerCollection;
     bounds: MapBounds;
     player?: WorldXZ;
     /** Facing yaw (`rotationY`, forward = `(sin yaw, cos yaw)`) of the player — pass it raw, never pre-converted to a bearing. */

package/dist/map.js

@@ -68,20 +68,42 @@ function cellStateNodes(layers, project, scale, keyPrefix) {
     }
     return nodes;
 }
+function markerAccess(markers) {
+    if (Array.isArray(markers)) {
+        const snapshot = markers;
+        return { subscribe: NO_SUBSCRIBE, getSnapshot: () => snapshot, getServerSnapshot: () => snapshot };
+    }
+    if ("getSnapshot" in markers) {
+        const source = markers;
+        return {
+            subscribe: (listener) => source.subscribe(listener),
+            getSnapshot: () => source.getSnapshot(),
+            getServerSnapshot: () => (source.getServerSnapshot ?? source.getSnapshot).call(source),
+        };
+    }
+    const markerSet = markers;
+    return {
+        subscribe: (listener) => markerSet.subscribe(listener),
+        getSnapshot: () => markerSet.snapshot(),
+        getServerSnapshot: () => markerSet.snapshot(),
+    };
+}
 export function useMarkers(markers) {
-    return useSyncExternalStore(markers.subscribe, markers.snapshot, markers.snapshot);
+    const access = useMemo(() => markerAccess(markers), [markers]);
+    return useSyncExternalStore(access.subscribe, access.getSnapshot, access.getServerSnapshot);
 }
 export function useFog(fog) {
     return useSyncExternalStore(fog.subscribe, fog.cells, fog.cells);
 }
 /**
  * Framed circular minimap: optional baked terrain background, reveal-on-event
- * fog overlay, categorized marker icons, and a facing arrow. Reads a core
- * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ * fog overlay, categorized marker icons, and a facing arrow. Reads static
+ * marker views, an external marker source, or a native `MarkerSet`; supply
+ * your own `kindStyles` palette to reskin. Does not require `GameProvider`.
  *
  * @capability minimap framed circular minimap with terrain bake, fog, markers, and facing arrow
  */
-export function Minimap({ markers, center, worldRadius, fog, size = 176, facingYaw = 0, rotate = false, kindStyles = DEFAULT_MARKER_KINDS, background, mapBounds, routes, zones, cellStates, onWorldClick, className, title = "Map", children, }) {
+export function Minimap({ markers, center, worldRadius, fog, size = 176, facingYaw = 0, rotate = false, kindStyles = DEFAULT_MARKER_KINDS, background, mapBounds, routes, zones, cellStates, onWorldClick, className, style, title = "Map", children, }) {
     const markerList = useMarkers(markers);
     const fogCells = useSyncExternalStore(fog?.subscribe ?? NO_SUBSCRIBE, fog?.cells ?? NULL_CELLS, fog?.cells ?? NULL_CELLS);
     const bearing = headingToBearing(facingYaw);
@@ -93,7 +115,7 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, facingY
     };
     const half = size / 2;
     const clipId = `mm-clip-${size}`;
-    const sorted = [...markerList].sort((a, b) => markerKindStyle(a.kind, kindStyles).priority - markerKindStyle(b.kind, kindStyles).priority);
+    const sorted = useMemo(() => [...markerList].sort((a, b) => markerKindStyle(a.kind, kindStyles).priority - markerKindStyle(b.kind, kindStyles).priority), [markerList, kindStyles]);
     const fogImage = useMemo(() => {
         if (fogCells === null)
             return null;
@@ -117,10 +139,12 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, facingY
             borderRadius: 14,
             padding: 8,
             background: "linear-gradient(160deg, rgba(24,28,36,0.94), rgba(12,15,20,0.94))",
-            border: "1px solid rgba(148,163,184,0.28)",
+            // Ring color reads the shared HudTheme `--jg-ring` token (#1034); fallback = the built-in ring.
+            border: "1px solid var(--jg-ring, rgba(148,163,184,0.28))",
             boxShadow: "0 10px 30px rgba(0,0,0,0.45)",
             color: "#e2e8f0",
             fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            ...style,
         }, children: [_jsxs("div", { style: {
                     display: "flex",
                     justifyContent: "space-between",
@@ -158,10 +182,11 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, facingY
                                     ...routeNodes(routes, projectXZ, "mm"),
                                 ];
                             })(), _jsx("circle", { cx: half, cy: half, r: half - 1, fill: "none", stroke: "rgba(148,163,184,0.12)" }), sorted.map((marker) => {
-                                const style = markerKindStyle(marker.kind, kindStyles);
+                                const kind = marker.kind ?? "marker";
+                                const style = markerKindStyle(kind, kindStyles);
                                 const projected = projectToMinimap(marker.position, view);
                                 const at = projected.inside ? projected : clampToMinimapEdge(projected, size);
-                                return (_jsxs("g", { "data-marker-kind": marker.kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 7, fill: "rgba(2,6,12,0.55)" }), _jsx("text", { x: at.x, y: at.y + 3.5, textAnchor: "middle", fontSize: 10, fill: style.color, style: { fontWeight: 700 }, children: style.glyph })] }, marker.id));
+                                return (_jsxs("g", { "data-marker-kind": kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 7, fill: "rgba(2,6,12,0.55)" }), _jsx("text", { x: at.x, y: at.y + 3.5, textAnchor: "middle", fontSize: 10, fill: style.color, style: { fontWeight: 700 }, children: style.glyph })] }, marker.id));
                             }), _jsx("g", { transform: `translate(${half} ${half}) rotate(${(rotate ? 0 : bearing) * (180 / Math.PI)})`, children: _jsx("path", { d: "M0,-9 L6,7 L0,3 L-6,7 Z", fill: "#4ade80", stroke: "#052e16", strokeWidth: 0.75 }) })] }), _jsx("circle", { cx: half, cy: half, r: half - 1, fill: "none", stroke: "rgba(148,163,184,0.4)", strokeWidth: 1.5 }), _jsx("text", { x: half, y: 13, textAnchor: "middle", fontSize: 11, fill: "rgba(226,232,240,0.9)", style: { fontWeight: 700 }, children: "N" })] }), children] }));
 }
 /**
@@ -197,7 +222,6 @@ export function MinimapChrome({ view, frame = false, frameColor = "rgba(148,163,
 const NO_SUBSCRIBE = () => () => undefined;
 const NULL_CELLS = () => null;
 const EMPTY_MARKERS_VALUE = [];
-const EMPTY_MARKERS = () => EMPTY_MARKERS_VALUE;
 const COMPASS_TICKS = [
     { cardinal: "N", bearing: 0 },
     { cardinal: "NE", bearing: Math.PI / 4 },
@@ -210,10 +234,11 @@ const COMPASS_TICKS = [
 ];
 /**
  * Horizontal compass strip centered on the player's facing direction, with the
- * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
+ * eight cardinals and optional marker pips from static views, an external
+ * source, or a native `MarkerSet`.
  */
 export function Compass({ facingYaw, center, markers, width = 340, fov = (Math.PI * 2) / 3, kindStyles = DEFAULT_MARKER_KINDS, className, }) {
-    const markerList = useSyncExternalStore(markers?.subscribe ?? NO_SUBSCRIBE, markers?.snapshot ?? EMPTY_MARKERS, markers?.snapshot ?? EMPTY_MARKERS);
+    const markerList = useMarkers(markers ?? EMPTY_MARKERS_VALUE);
     const facingBearing = headingToBearing(facingYaw);
     const half = fov / 2;
     const toX = (bearing) => {
@@ -259,8 +284,9 @@ export function Compass({ facingYaw, center, markers, width = 340, fov = (Math.P
                     const x = toX(bearing);
                     if (x === null)
                         return null;
-                    const style = markerKindStyle(marker.kind, kindStyles);
-                    return (_jsx("span", { "data-compass-marker": marker.kind, style: {
+                    const kind = marker.kind ?? "marker";
+                    const style = markerKindStyle(kind, kindStyles);
+                    return (_jsx("span", { "data-compass-marker": kind, style: {
                             position: "absolute",
                             left: x,
                             bottom: 2,
@@ -293,6 +319,48 @@ export function MinimapPanel({ zoneLabel, clock, showCompass = true, compassProp
                     fontFamily: "ui-sans-serif, system-ui, sans-serif",
                 }, children: [zoneLabel !== undefined ? (_jsx("span", { className: zoneLabelClassName, "data-minimap-chrome-zone": true, style: { fontSize: 12, fontWeight: 700 }, children: zoneLabel })) : (_jsx("span", {})), clock !== undefined ? (_jsx("span", { className: clockClassName, "data-minimap-chrome-clock": true, style: { fontSize: 11, color: "rgba(226,232,240,0.75)" }, children: clock })) : null] })) : null, _jsx(Minimap, { ...minimapProps, children: children }), showCompass ? (_jsx("div", { className: compassClassName, "data-minimap-chrome-compass": true, style: { marginTop: 6 }, children: _jsx(Compass, { facingYaw: minimapProps.facingYaw ?? 0, center: minimapProps.center, markers: minimapProps.markers, width: minimapProps.size ?? 176, ...compassProps }) })) : null] }));
 }
+const TRACK_PIP_DIAMETER = {
+    dot: 6,
+    exit: 8,
+    player: 12,
+};
+/**
+ * Horizontal linear track minimap — a rounded progress rail with colored zone
+ * `spans` and gate/exit/player `pips` positioned by 0..1 fraction. The
+ * structural counterpart to the radial {@link Minimap} for corridor/route
+ * games: fractions are supplied by the caller (via core `trackFraction`), so it
+ * reads no store and stays presentation-only, sharing chrome with the radial
+ * minimap.
+ *
+ * @capability minimap-track-hud horizontal linear track minimap (corridor/route progress) — colored zone spans and gate/player pips positioned by 0..1 fraction, sharing chrome with the radial Minimap
+ */
+export function MinimapTrack({ spans = [], pips = [], width = "100%", height = 12, railColor = "rgba(255,255,255,0.10)", className, style, children, }) {
+    return (_jsxs("div", { className: className, "data-minimap-track": true, style: { position: "relative", width, height, borderRadius: 9999, background: railColor, ...style }, children: [spans.map((span) => (_jsx("div", { "data-track-span": span.id, title: span.label, style: {
+                    position: "absolute",
+                    top: 0,
+                    bottom: 0,
+                    left: `${span.start * 100}%`,
+                    width: `${(span.end - span.start) * 100}%`,
+                    background: span.color ?? "rgba(255,255,255,0.25)",
+                    opacity: 0.4,
+                    borderRadius: 9999,
+                } }, span.id))), pips.map((pip) => {
+                const shape = pip.shape ?? "dot";
+                const color = pip.color ?? "#f4f6fb";
+                const common = {
+                    position: "absolute",
+                    top: "50%",
+                    left: `${pip.at * 100}%`,
+                    transform: "translate(-50%, -50%)",
+                    background: color,
+                };
+                if (shape === "gate") {
+                    return (_jsx("div", { "data-track-pip": pip.id, "data-pip-shape": "gate", title: pip.title ?? pip.label, style: { ...common, width: 3, height: height + 6, borderRadius: 2 } }, pip.id));
+                }
+                const diameter = TRACK_PIP_DIAMETER[shape];
+                return (_jsx("div", { "data-track-pip": pip.id, "data-pip-shape": shape, title: pip.title ?? pip.label, style: { ...common, width: diameter, height: diameter, borderRadius: 9999, border: "1px solid rgba(0,0,0,0.6)" } }, pip.id));
+            }), children] }));
+}
 function WorldMapFogImage({ fogCells, project, worldW, worldD, width, mapH, }) {
     const fogImage = useMemo(() => {
         if (fogCells === null)
@@ -361,8 +429,9 @@ export function WorldMap({ markers, bounds, player, facingYaw = 0, fog, backgrou
                         ];
                     })(), markerList.map((marker) => {
                         const at = project(marker.position[0], marker.position[2]);
-                        const style = markerKindStyle(marker.kind, kindStyles);
-                        return (_jsxs("g", { "data-world-marker": marker.kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 9, fill: "rgba(2,6,12,0.6)", stroke: style.color, strokeWidth: 1.2 }), _jsx("text", { x: at.x, y: at.y + 4, textAnchor: "middle", fontSize: 12, fill: style.color, style: { fontWeight: 700 }, children: style.glyph }), marker.label !== undefined ? (_jsx("text", { x: at.x + 12, y: at.y + 4, fontSize: 11, fill: "rgba(226,232,240,0.85)", children: marker.label })) : null] }, marker.id));
+                        const kind = marker.kind ?? "marker";
+                        const style = markerKindStyle(kind, kindStyles);
+                        return (_jsxs("g", { "data-world-marker": kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 9, fill: "rgba(2,6,12,0.6)", stroke: style.color, strokeWidth: 1.2 }), _jsx("text", { x: at.x, y: at.y + 4, textAnchor: "middle", fontSize: 12, fill: style.color, style: { fontWeight: 700 }, children: style.glyph }), marker.label !== undefined ? (_jsx("text", { x: at.x + 12, y: at.y + 4, fontSize: 11, fill: "rgba(226,232,240,0.85)", children: marker.label })) : null] }, marker.id));
                     }), player !== undefined
                         ? (() => {
                             const at = project(player[0], player[1]);

package/dist/selectionHud.d.ts

@@ -35,6 +35,9 @@ export declare function useSelectionView(members: readonly EntitySummaryDef[], o
  * A compact current/max vital meter for an entity summary; tone maps to a colour ramp. Reuse it as
  * the vital row inside {@link EntitySummary} or any custom entity panel.
  *
+ * @deprecated The `tone`/`vital`-API umbrella is retired (#1033). Use the atomic, purpose-named,
+ * token-themed bars from `@jgengine/react/bars` (`HealthBar`, `ShieldBar`, `ManaBar`, …) and compose
+ * your own panel — each does one readout and restyles globally via the shared `--jg-*` tokens.
  * @capability vital-bar compact current/max vital meter for an entity summary
  */
 export declare function VitalBar({ vital, width, showLabel, className, style, }: {
@@ -67,6 +70,9 @@ export declare function EntityPortrait({ entity, selected, size, vitalId, tabInd
  * "who is selected" summary a single-selection or the head of a multi-selection shows. Swap the vital
  * rows via `renderVital`.
  *
+ * @deprecated Bundling a whole vitals array in one component is the combo anti-pattern #1033 retires.
+ * Compose your own summary — name/tags plus the atomic `@jgengine/react/bars` (`HealthBar`, …) you
+ * need — so no engine component packages multiple readouts by default. Kept during migration.
  * @capability entity-summary primary selected-entity detail panel (name, tags, vitals)
  */
 export declare function EntitySummary({ entity, renderVital, className, style, }: {
@@ -111,12 +117,12 @@ export declare function SelectionCollectionChrome({ model, itemSize, gap, window
     style?: CSSProperties;
 }): import("react").JSX.Element;
 /**
- * The batteries-included default: a skinned glass panel composing {@link EntitySummary} for the
- * primary member beside {@link SelectionCollectionChrome} for the rest. Pass `members` (or a prebuilt
- * `model`) and it renders a working RTS-style selection panel; every sub-renderer stays swappable, and
- * a game that wants a different frame composes the hook and chrome directly.
+ * Convenience composition: skinned glass panel with {@link EntitySummary} for the primary member
+ * beside {@link SelectionCollectionChrome} for the rest — demos/scaffold only, not a finished game
+ * face. Pass `members` (or a prebuilt `model`); swap sub-renderers or compose the headless pieces
+ * under game-owned chrome for product UI.
  *
- * @capability selection-panel drop-in selection panel: primary summary beside a portrait strip / group chips
+ * @capability selection-panel optional selection-panel composition: summary + portrait strip / group chips
  */
 export declare function SelectionPanel({ members, model: providedModel, groupThreshold, labelOf, windowSize, renderPrimary, renderMember, renderVital, onFocusChange, className, style, }: {
     members?: readonly EntitySummaryDef[];