@jgengine/react 0.10.0 → 0.12.0

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

@@ -5,11 +5,28 @@ export * from "./chatBubbles.js";
 export * from "./voice.js";
 export * from "./social.js";
 export * from "./hooks.js";
+export * from "./store.js";
 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";
 export * from "./dragLayer.js";
+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

@@ -5,11 +5,28 @@ export * from "./chatBubbles.js";
 export * from "./voice.js";
 export * from "./social.js";
 export * from "./hooks.js";
+export * from "./store.js";
 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";
 export * from "./dragLayer.js";
+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/keyHint.d.ts

@@ -0,0 +1,30 @@
+import { type CSSProperties, type ReactNode } from "react";
+/**
+ * A single keyboard/mouse key rendered as a cap. Tagged `data-jg-kbd` so tooling
+ * can find it; on its own it stays visible (hiding a lone cap would strand its
+ * label). Wrap keys + their meaning in `KeyHint` to make the whole hint vanish
+ * on touch.
+ *
+ * @capability keycap styled keyboard/mouse key cap for control hints
+ */
+export declare function Keycap({ children, className, style, }: {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * Wraps a keyboard/mouse control hint (a cap plus what it does). Renders nothing
+ * on coarse-pointer devices — a touchscreen has no keyboard, so the hint is
+ * noise and only fights the on-screen controls for space. The `data-jg-kbd-hint`
+ * marker is also hidden by an engine stylesheet as a hydration-safe backstop, so
+ * a hint stays hidden on touch even before this component's effect runs. Put the
+ * touch equivalent (a `TouchControls` dock, a tappable button) on the coarse
+ * branch instead.
+ *
+ * @capability key-hint keyboard/mouse control hint that hides itself on touch
+ */
+export declare function KeyHint({ children, className, style, }: {
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element | null;

package/dist/keyHint.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+import { useDisplayProfile } from "./display.js";
+/**
+ * A single keyboard/mouse key rendered as a cap. Tagged `data-jg-kbd` so tooling
+ * can find it; on its own it stays visible (hiding a lone cap would strand its
+ * label). Wrap keys + their meaning in `KeyHint` to make the whole hint vanish
+ * on touch.
+ *
+ * @capability keycap styled keyboard/mouse key cap for control hints
+ */
+export function Keycap({ children, className, style, }) {
+    return (_jsx("kbd", { "data-jg-kbd": "", className: className, style: style, children: children }));
+}
+/**
+ * Wraps a keyboard/mouse control hint (a cap plus what it does). Renders nothing
+ * on coarse-pointer devices — a touchscreen has no keyboard, so the hint is
+ * noise and only fights the on-screen controls for space. The `data-jg-kbd-hint`
+ * marker is also hidden by an engine stylesheet as a hydration-safe backstop, so
+ * a hint stays hidden on touch even before this component's effect runs. Put the
+ * touch equivalent (a `TouchControls` dock, a tappable button) on the coarse
+ * branch instead.
+ *
+ * @capability key-hint keyboard/mouse control hint that hides itself on touch
+ */
+export function KeyHint({ children, className, style, }) {
+    const { coarsePointer } = useDisplayProfile();
+    if (coarsePointer)
+        return null;
+    return (_jsx("span", { "data-jg-kbd-hint": "", className: className, style: style, children: children }));
+}

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 WorldXZ } from "@jgengine/core/world/minimap";
+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,15 +44,61 @@ 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;
+    position: WorldXZ | readonly [number, number, number];
+    /** Bearing (radians) to draw an arrow instead of a dot — pass `headingToBearing(yaw)` for the player/other facing blips. */
+    heading?: number;
+    color?: string;
+    radius?: number;
+    glyph?: string;
+    glyphColor?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    /** Clamp to the minimap edge when outside `view.worldRadius` (off-screen indicator); `false` hides it instead. Default `true`. */
+    clampToEdge?: boolean;
+}
+/** Props for `MinimapChrome`. */
+export interface MinimapChromeProps {
+    /** Shared with `projectToMinimap`/`clampToMinimapEdge` — pass `view.rotate` to keep a rotating map's arrows pointed correctly. */
+    view: MinimapView;
+    /** Ring outline (+ `cardinalLabel`). Default `false` — most games draw their own frame/panel around the chrome. */
+    frame?: boolean;
+    frameColor?: string;
+    frameStrokeWidth?: number;
+    /** Label drawn at the top of the ring when `frame` is on; `false` omits it. */
+    cardinalLabel?: string | false;
+    markers?: readonly MinimapChromeMarker[];
+    markerColor?: string;
+    markerRadius?: number;
+    className?: string;
+}
+/**
+ * Headless minimap chrome — nests inside a game's own `<svg>`: an optional
+ * ring frame, and edge-clamped marker dots that draw as directional arrows
+ * when a marker carries a `heading` (the compass-arrow / player-blip layer
+ * ~8 games were re-drawing by hand over `projectToMinimap`/`clampToMinimapEdge`).
+ * Renders a bare `<g>` — no background, panel, or title; compose your own
+ * content layer (routes, zones, terrain) as sibling SVG nodes for full control
+ * of z-order, or call `MinimapChrome` twice (once for `frame`, again for
+ * `markers`) to sandwich custom content between the ring and the blips.
+ *
+ * @capability minimap-chrome ring frame plus edge-clamped, heading-aware marker dots to nest inside a game's own `<svg>`
+ */
+export declare function MinimapChrome({ view, frame, frameColor, frameStrokeWidth, cardinalLabel, markers, markerColor, markerRadius, className, }: MinimapChromeProps): ReactNode;
 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>;
@@ -54,11 +106,89 @@ 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. */
+export interface MinimapPanelProps extends MinimapProps {
+    /** Zone/area name slot rendered in the chrome header — the game supplies its own zone lookup. */
+    zoneLabel?: ReactNode;
+    /** Clock readout slot rendered in the chrome header — pair with `useGameClock()` + `calendar()`. */
+    clock?: ReactNode;
+    /** Compass strip beneath the circle. Default true; pass `false` to omit it entirely. */
+    showCompass?: boolean;
+    compassProps?: Partial<Omit<CompassProps, "className">>;
+    headerClassName?: string;
+    zoneLabelClassName?: string;
+    clockClassName?: string;
+    compassClassName?: string;
+}
+/**
+ * Composed circular-minimap chrome: optional zone-label + clock header above
+ * the `Minimap`, optional `Compass` strip below. Purely a wiring layer over
+ * the existing primitives — the game supplies the zone name and clock text,
+ * this only places them; omit either slot and the header disappears.
+ *
+ * @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. */