@jgengine/react 0.13.0 → 0.15.0-next.0

package/dist/interactionPrompt.js

@@ -0,0 +1,112 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer } from "react";
+import { StaminaBar } from "./bars.js";
+import { KeyHint, Keycap } from "./keyHint.js";
+/**
+ * Subscribe to a {@link PromptRegistry} and re-`resolve` it whenever the player
+ * moves, returning the prompt to draw right now — or `null` when the player is
+ * out of range of every interactable. The registry notifies only on active-prompt
+ * *changes*, so this re-renders on transitions rather than every frame the hero
+ * moves. Feed it the player's `{ x, z }` position each frame; identical positions
+ * do no work.
+ *
+ * @capability use-interaction-prompt React hook binding a prompt registry to a moving player — resolves the nearest interactable prompt and returns the active one
+ */
+export function useInteractionPrompt(registry, playerPosition) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => registry.subscribe(bump), [registry]);
+    useEffect(() => {
+        registry.resolve(playerPosition);
+    }, [registry, playerPosition.x, playerPosition.z]);
+    return registry.active();
+}
+function resolveTheme(theme) {
+    return {
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        background: theme?.background ?? "rgba(15,20,28,0.86)",
+        border: theme?.border ?? "rgba(148,163,184,0.28)",
+        text: theme?.text ?? "#e2e8f0",
+        fontFamily: theme?.fontFamily ?? "ui-sans-serif, system-ui, sans-serif",
+    };
+}
+const ANCHOR_STYLE = {
+    "bottom-center": { bottom: "12%", left: "50%", transform: "translateX(-50%)" },
+    "top-center": { top: "12%", left: "50%", transform: "translateX(-50%)" },
+    center: { top: "50%", left: "50%", transform: "translate(-50%, -50%)" },
+};
+/** Bind to the registry either through the moving player, or passively on the active id. */
+function useActive(registry, playerPosition) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => registry.subscribe(bump), [registry]);
+    const px = playerPosition?.x;
+    const pz = playerPosition?.z;
+    useEffect(() => {
+        if (px !== undefined && pz !== undefined)
+            registry.resolve({ x: px, z: pz });
+    }, [registry, px, pz]);
+    return registry.active();
+}
+/**
+ * A screen-anchored "Press E to …" interaction callout that renders the active
+ * prompt of a {@link PromptRegistry}. It subscribes to the registry and — when
+ * given `playerPosition` — re-resolves as the hero moves, showing the nearest
+ * in-range interactable and switching to a closer/higher-priority one as they
+ * cross radii. Each display kind renders as itself: a `keybind` shows a key cap
+ * plus its label ("Press [E] Open"), a `gauge` shows a hold bar filling with
+ * `gaugeProgress`, and a `label` shows plain text. Presentation only — the
+ * registry never branches on a prompt's meaning; the game colors each via
+ * `accentFor` and maps action ids to key glyphs via `keyFor`. HudTheme-skinnable
+ * through `--jg-accent` and {@link InteractionPromptTheme}.
+ *
+ * @capability interaction-prompt-host screen-anchored "press E to…" callout rendering a prompt registry's active interactable — keybind cap+label, gauge hold bar, or plain label, theme- and per-prompt-accent skinnable
+ */
+export function InteractionPrompt({ registry, playerPosition, theme, accentFor, keyFor, gaugeProgress, anchor = "bottom-center", zIndex = 40, className, style, }) {
+    const prompt = useActive(registry, playerPosition);
+    if (prompt === null)
+        return null;
+    const t = resolveTheme(theme);
+    const accent = accentFor?.(prompt) ?? t.accent;
+    const display = prompt.prompt.display;
+    let body;
+    if (display.kind === "keybind") {
+        const glyph = keyFor?.(display.actionId) ?? "E";
+        body = (_jsxs(KeyHint, { style: { display: "inline-flex", alignItems: "center", gap: 10 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 600, letterSpacing: 0.4, opacity: 0.85 }, children: "Press" }), _jsx(Keycap, { style: {
+                        display: "inline-flex",
+                        minWidth: 26,
+                        justifyContent: "center",
+                        padding: "3px 8px",
+                        borderRadius: 6,
+                        border: `1px solid ${accent}`,
+                        background: "rgba(0,0,0,0.35)",
+                        color: accent,
+                        fontWeight: 800,
+                        fontSize: 14,
+                        boxShadow: `0 0 10px -2px ${accent}`,
+                    }, children: glyph }), display.label !== undefined ? (_jsx("span", { style: { fontSize: 15, fontWeight: 700 }, children: display.label })) : null] }));
+    }
+    else if (display.kind === "gauge") {
+        const progress = Math.max(0, Math.min(1, gaugeProgress?.(display.gaugeId) ?? 0));
+        body = (_jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: 10 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 600, letterSpacing: 0.4, opacity: 0.85 }, children: "Hold" }), _jsx(StaminaBar, { value: progress * 100, showValue: false, width: 140, fill: accent })] }));
+    }
+    else {
+        body = _jsx("span", { style: { fontSize: 15, fontWeight: 700 }, children: display.text });
+    }
+    return (_jsx("div", { className: className, "data-interaction-prompt": prompt.id, "data-prompt-kind": display.kind, style: {
+            position: "absolute",
+            ...ANCHOR_STYLE[anchor],
+            display: "flex",
+            alignItems: "center",
+            pointerEvents: "none",
+            padding: "9px 16px",
+            borderRadius: 12,
+            border: `1px solid ${t.border}`,
+            background: t.background,
+            color: t.text,
+            fontFamily: t.fontFamily,
+            boxShadow: `0 8px 24px rgba(0,0,0,0.4), 0 0 0 1px ${accent}22`,
+            backdropFilter: "blur(4px)",
+            whiteSpace: "nowrap",
+            zIndex,
+            ...style,
+        }, children: body }));
+}

package/dist/keybindingMenu.d.ts

@@ -0,0 +1,59 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { RebindSession } from "@jgengine/core/input/rebindSession";
+/**
+ * Subscribe to a rebind session and re-render on every change (capture, reset,
+ * arm/disarm, restore). Returns the session unchanged for convenient inline use.
+ *
+ * @capability use-rebind-session React hook that re-renders a component whenever a rebind session changes
+ */
+export declare function useRebindSession(session: RebindSession): RebindSession;
+/** Reskin tokens for {@link KeybindingMenu}. All fall back to HudTheme `--jg-*` vars. */
+export interface KeybindingMenuTheme {
+    /** Panel background. Default reads `--jg-frame-bg`. */
+    bg?: string;
+    /** Panel border. Default reads `--jg-frame-border`. */
+    border?: string;
+    /** Corner radius. Default reads `--jg-frame-radius`. */
+    radius?: string;
+    /** Row label text color. */
+    text?: string;
+    /** Muted text (hints, secondary). */
+    muted?: string;
+    /** Accent for the armed row + focus glow. Default reads `--jg-accent`. */
+    accent?: string;
+    /** Conflict highlight color. */
+    conflict?: string;
+    /** Font family. */
+    fontFamily?: string;
+}
+/** Props for {@link KeybindingMenu}. */
+export interface KeybindingMenuProps {
+    /** The rebind session to edit. */
+    session: RebindSession;
+    /** Reskin tokens (fall back to HudTheme). */
+    theme?: KeybindingMenuTheme;
+    /** Heading shown above the list. Default `"Controls"`. */
+    title?: ReactNode;
+    /** Label for the reset-all button. Default `"Reset All"`. */
+    resetAllLabel?: string;
+    /** Prompt shown in a row that is armed for capture. Default `"Press a key…"`. */
+    capturePrompt?: string;
+    /** Called after a successful rebind or reset — e.g. persist `session.overrides()`. */
+    onChange?: (session: RebindSession) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A drop-in controls-settings surface for a {@link RebindSession}: one row per
+ * action showing its label and current key glyph. Clicking a row arms capture
+ * ("Press a key…") and a window `keydown` listener feeds the pressed
+ * `event.code` to `session.capture`; rows that collide with another action show
+ * a conflict badge; each row has a Reset button and the panel has a Reset-all
+ * button. Presentation only — all conflict/capture/reset logic lives in the core
+ * session, and action ids/labels are the game's free strings. Reskin via
+ * {@link KeybindingMenuTheme} or ambient HudTheme tokens. A game owns its overall
+ * settings layout; this is the reusable controls block it drops in.
+ *
+ * @capability keybinding-menu drop-in controls-settings surface over a rebind session — click-to-capture rows with key glyphs, conflict badges, per-row and reset-all, HudTheme-skinnable
+ */
+export declare function KeybindingMenu({ session, theme, title, resetAllLabel, capturePrompt, onChange, className, style, }: KeybindingMenuProps): ReactNode;

package/dist/keybindingMenu.js

@@ -0,0 +1,146 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer } from "react";
+import { Keycap } from "./keyHint.js";
+/**
+ * Subscribe to a rebind session and re-render on every change (capture, reset,
+ * arm/disarm, restore). Returns the session unchanged for convenient inline use.
+ *
+ * @capability use-rebind-session React hook that re-renders a component whenever a rebind session changes
+ */
+export function useRebindSession(session) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => session.subscribe(bump), [session]);
+    return session;
+}
+function resolveTheme(theme) {
+    return {
+        bg: theme?.bg ?? "var(--jg-frame-bg, linear-gradient(180deg, rgba(20,24,32,0.92), rgba(10,12,16,0.95)))",
+        border: theme?.border ?? "var(--jg-frame-border, 1px solid rgba(255,255,255,0.12))",
+        radius: theme?.radius ?? "var(--jg-frame-radius, 12px)",
+        text: theme?.text ?? "#e8edf5",
+        muted: theme?.muted ?? "rgba(148,163,184,0.85)",
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        conflict: theme?.conflict ?? "#f87171",
+        fontFamily: theme?.fontFamily ?? "ui-sans-serif, system-ui, sans-serif",
+    };
+}
+/**
+ * A drop-in controls-settings surface for a {@link RebindSession}: one row per
+ * action showing its label and current key glyph. Clicking a row arms capture
+ * ("Press a key…") and a window `keydown` listener feeds the pressed
+ * `event.code` to `session.capture`; rows that collide with another action show
+ * a conflict badge; each row has a Reset button and the panel has a Reset-all
+ * button. Presentation only — all conflict/capture/reset logic lives in the core
+ * session, and action ids/labels are the game's free strings. Reskin via
+ * {@link KeybindingMenuTheme} or ambient HudTheme tokens. A game owns its overall
+ * settings layout; this is the reusable controls block it drops in.
+ *
+ * @capability keybinding-menu drop-in controls-settings surface over a rebind session — click-to-capture rows with key glyphs, conflict badges, per-row and reset-all, HudTheme-skinnable
+ */
+export function KeybindingMenu({ session, theme, title = "Controls", resetAllLabel = "Reset All", capturePrompt = "Press a key…", onChange, className, style, }) {
+    useRebindSession(session);
+    const t = resolveTheme(theme);
+    const rows = session.rows();
+    const capturing = session.capturingActionId();
+    // While armed, the next keydown anywhere reassigns the row (Escape cancels).
+    useEffect(() => {
+        if (capturing === null)
+            return;
+        const onKeyDown = (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            if (event.code === "Escape") {
+                session.cancelCapture();
+                return;
+            }
+            session.capture(event.code);
+            onChange?.(session);
+        };
+        window.addEventListener("keydown", onKeyDown, { capture: true });
+        return () => window.removeEventListener("keydown", onKeyDown, { capture: true });
+    }, [capturing, session, onChange]);
+    const anyConflict = session.hasConflicts();
+    return (_jsxs("div", { "data-keybinding-menu": "", className: className, style: {
+            pointerEvents: "auto",
+            display: "flex",
+            flexDirection: "column",
+            gap: 10,
+            width: "min(420px, 92vw)",
+            padding: "16px 18px",
+            background: t.bg,
+            border: t.border,
+            borderRadius: t.radius,
+            color: t.text,
+            fontFamily: t.fontFamily,
+            boxShadow: "0 12px 40px rgba(0,0,0,0.5)",
+            ...style,
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12 }, children: [_jsx("div", { style: { fontSize: 15, fontWeight: 800, letterSpacing: "0.08em", textTransform: "uppercase" }, children: title }), _jsx("button", { type: "button", "data-keybinding-reset-all": "", onClick: () => {
+                            session.resetAll();
+                            onChange?.(session);
+                        }, style: buttonStyle(t.muted, t.border), children: resetAllLabel })] }), anyConflict ? (_jsx("div", { style: { fontSize: 12, color: t.conflict, fontWeight: 600 }, children: "\u26A0 Some keys are bound to more than one action." })) : null, _jsx("div", { style: { display: "flex", flexDirection: "column", gap: 6 }, children: rows.map((row) => (_jsx(KeybindingRow, { row: row, armed: capturing === row.actionId, capturePrompt: capturePrompt, theme: t, onArm: () => session.beginCapture(row.actionId), onReset: () => {
+                        session.reset(row.actionId);
+                        onChange?.(session);
+                    } }, row.actionId))) })] }));
+}
+function KeybindingRow({ row, armed, capturePrompt, theme, onArm, onReset, }) {
+    const conflicted = row.conflictWith.length > 0;
+    return (_jsxs("div", { "data-keybinding-row": row.actionId, "data-armed": armed ? "" : undefined, "data-conflict": conflicted ? "" : undefined, style: {
+            display: "flex",
+            alignItems: "center",
+            gap: 10,
+            padding: "8px 10px",
+            borderRadius: 8,
+            background: armed ? "rgba(56,189,248,0.14)" : "rgba(255,255,255,0.03)",
+            border: `1px solid ${armed ? theme.accent : conflicted ? theme.conflict : "transparent"}`,
+            boxShadow: armed ? `0 0 0 1px ${theme.accent}, 0 0 14px rgba(56,189,248,0.35)` : "none",
+            transition: "background 120ms, border-color 120ms",
+        }, children: [_jsxs("div", { style: { flex: 1, minWidth: 0, fontSize: 14, fontWeight: 600, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }, children: [row.label, conflicted ? (_jsx("span", { "data-keybinding-conflict-badge": "", style: {
+                            marginLeft: 8,
+                            padding: "1px 7px",
+                            borderRadius: 999,
+                            fontSize: 10,
+                            fontWeight: 800,
+                            letterSpacing: "0.06em",
+                            textTransform: "uppercase",
+                            color: "#1a0808",
+                            background: theme.conflict,
+                        }, children: "Conflict" })) : null] }), _jsx("button", { type: "button", "data-keybinding-capture": "", onClick: onArm, style: {
+                    minWidth: 96,
+                    display: "flex",
+                    justifyContent: "center",
+                    cursor: "pointer",
+                    background: "transparent",
+                    border: "none",
+                    padding: 0,
+                }, children: armed ? (_jsx("span", { style: { fontSize: 12, fontWeight: 700, color: theme.accent }, children: capturePrompt })) : (_jsx(Keycap, { style: {
+                        minWidth: 34,
+                        padding: "3px 9px",
+                        borderRadius: 6,
+                        textAlign: "center",
+                        fontSize: 13,
+                        fontWeight: 700,
+                        color: conflicted ? theme.conflict : theme.text,
+                        background: "rgba(0,0,0,0.4)",
+                        border: `1px solid ${conflicted ? theme.conflict : "rgba(255,255,255,0.18)"}`,
+                        boxShadow: "inset 0 -2px 0 rgba(0,0,0,0.4)",
+                    }, children: row.bindingLabel || "—" })) }), _jsx("button", { type: "button", "data-keybinding-reset": "", onClick: onReset, disabled: row.isDefault, title: "Reset to default", style: {
+                    ...buttonStyle(theme.muted, theme.border),
+                    opacity: row.isDefault ? 0.35 : 1,
+                    cursor: row.isDefault ? "default" : "pointer",
+                    padding: "4px 8px",
+                    fontSize: 11,
+                }, children: "Reset" })] }));
+}
+function buttonStyle(color, border) {
+    return {
+        pointerEvents: "auto",
+        background: "rgba(255,255,255,0.05)",
+        border,
+        borderRadius: 8,
+        color,
+        fontSize: 12,
+        fontWeight: 600,
+        padding: "5px 10px",
+        cursor: "pointer",
+    };
+}

package/dist/killFeed.d.ts

@@ -0,0 +1,63 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { EventTicker, EventTickerView } from "@jgengine/core/game/eventTicker";
+/**
+ * Subscribe to an event ticker and re-render it on an animation frame (unless the game
+ * already ticks it), returning the live entries newest-first with `fade` applied. Driving
+ * the frame loop is what makes entries visibly fade and drop as they age out.
+ *
+ * @capability use-event-ticker React hook binding an event-ticker — re-renders per frame so entries fade and drop live, returning the current newest-first views
+ */
+export declare function useEventTicker(ticker: EventTicker, animate?: boolean): EventTickerView[];
+/** Per-`kind` styling for a kill-feed row — accent color and an optional icon. */
+export interface KillFeedKindStyle {
+    /** Accent color for the row's icon and left rule. */
+    accent?: string;
+    /** Free-string {@link GameIcon} name to show for this kind (overridden by an entry's own `icon`). */
+    icon?: string;
+    /** Text color for the row. Defaults to the theme text color. */
+    color?: string;
+}
+/** Reskin tokens for {@link KillFeed}. */
+export interface KillFeedTheme {
+    /** Row background. Default reads `--jg-frame-bg`. */
+    rowBg?: string;
+    /** Row text color. Default near-white. */
+    text?: string;
+    /** Fallback accent when a kind has none. Default reads `--jg-accent`. */
+    accent?: string;
+    /** Font family. */
+    fontFamily?: string;
+    /** Row corner radius. Default reads `--jg-frame-radius`. */
+    radius?: string;
+}
+/** Props for {@link KillFeed}. */
+export interface KillFeedProps {
+    /** The ticker to render. */
+    ticker: EventTicker;
+    /**
+     * Per-`kind` accent + icon, keyed by the free-string `kind` a game pushes with ("kill",
+     * "assist", "info", …). The matching entry styles that row; the model never interprets `kind`.
+     */
+    kindStyles?: Record<string, KillFeedKindStyle>;
+    /** Base reskin tokens. */
+    theme?: KillFeedTheme;
+    /** Icon size in px. Default `18`. */
+    iconSize?: number;
+    /** Drive re-render on an animation frame. Default `true`. Turn off if the game ticks it. */
+    animate?: boolean;
+    /** Extra `z-index` for the stack. Default `40`. */
+    zIndex?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A vertical event/kill-feed ticker: renders an {@link EventTicker}'s recent entries as a
+ * stack of rows, newest on top, each with its `fade` `0..1` mapped to opacity so entries dim
+ * and drop as they age out. Each row shows an optional per-kind (or per-entry) {@link GameIcon}
+ * and a per-kind accent color from `kindStyles`, styled with HudTheme tokens. Presentation
+ * only: all capping/timing lives in the core ticker, and the free-string `kind`/`text`/`icon`
+ * are never interpreted here — a game colors and icons each variant via `kindStyles`.
+ *
+ * @capability kill-feed vertical event/kill-feed ticker rendering a core event-ticker as a fading, newest-on-top stack of per-kind iconned, accent-colored rows over HudTheme tokens
+ */
+export declare function KillFeed({ ticker, kindStyles, theme, iconSize, animate, zIndex, className, style, }: KillFeedProps): ReactNode;

package/dist/killFeed.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer, useRef } from "react";
+import { GameIcon, isGameIconName } from "./gameIcons.js";
+/**
+ * Subscribe to an event ticker and re-render it on an animation frame (unless the game
+ * already ticks it), returning the live entries newest-first with `fade` applied. Driving
+ * the frame loop is what makes entries visibly fade and drop as they age out.
+ *
+ * @capability use-event-ticker React hook binding an event-ticker — re-renders per frame so entries fade and drop live, returning the current newest-first views
+ */
+export function useEventTicker(ticker, animate = true) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    const rafRef = useRef(0);
+    useEffect(() => ticker.subscribe(bump), [ticker]);
+    useEffect(() => {
+        if (!animate)
+            return;
+        let running = true;
+        const loop = () => {
+            if (!running)
+                return;
+            bump();
+            rafRef.current = requestAnimationFrame(loop);
+        };
+        rafRef.current = requestAnimationFrame(loop);
+        return () => {
+            running = false;
+            cancelAnimationFrame(rafRef.current);
+        };
+    }, [ticker, animate]);
+    return ticker.recent();
+}
+function resolveTheme(theme) {
+    return {
+        rowBg: theme?.rowBg ?? "var(--jg-frame-bg, rgba(12,16,22,0.82))",
+        text: theme?.text ?? "#f1f5f9",
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        fontFamily: theme?.fontFamily ?? "ui-sans-serif, system-ui, sans-serif",
+        radius: theme?.radius ?? "var(--jg-frame-radius, 8px)",
+    };
+}
+/**
+ * A vertical event/kill-feed ticker: renders an {@link EventTicker}'s recent entries as a
+ * stack of rows, newest on top, each with its `fade` `0..1` mapped to opacity so entries dim
+ * and drop as they age out. Each row shows an optional per-kind (or per-entry) {@link GameIcon}
+ * and a per-kind accent color from `kindStyles`, styled with HudTheme tokens. Presentation
+ * only: all capping/timing lives in the core ticker, and the free-string `kind`/`text`/`icon`
+ * are never interpreted here — a game colors and icons each variant via `kindStyles`.
+ *
+ * @capability kill-feed vertical event/kill-feed ticker rendering a core event-ticker as a fading, newest-on-top stack of per-kind iconned, accent-colored rows over HudTheme tokens
+ */
+export function KillFeed({ ticker, kindStyles, theme, iconSize = 18, animate = true, zIndex = 40, className, style, }) {
+    const entries = useEventTicker(ticker, animate);
+    const t = resolveTheme(theme);
+    return (_jsx("div", { className: className, "data-kill-feed": "", style: {
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "stretch",
+            gap: 6,
+            pointerEvents: "none",
+            fontFamily: t.fontFamily,
+            zIndex,
+            ...style,
+        }, children: entries.map((entry) => {
+            const kindStyle = kindStyles?.[entry.kind];
+            const accent = kindStyle?.accent ?? t.accent;
+            const iconName = entry.icon ?? kindStyle?.icon;
+            const opacity = 1 - entry.fade * 0.85;
+            return (_jsxs("div", { "data-kill-feed-row": entry.id, "data-kind": entry.kind, style: {
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 8,
+                    padding: "5px 10px",
+                    background: t.rowBg,
+                    borderLeft: `3px solid ${accent}`,
+                    borderRadius: t.radius,
+                    color: kindStyle?.color ?? t.text,
+                    fontSize: 13,
+                    fontWeight: 600,
+                    lineHeight: 1.2,
+                    whiteSpace: "nowrap",
+                    opacity,
+                    boxShadow: "0 2px 8px rgba(0,0,0,0.4)",
+                    transform: `translateX(${entry.fade * 8}px)`,
+                    willChange: "opacity, transform",
+                }, children: [iconName !== undefined && isGameIconName(iconName) ? (_jsx("span", { style: { color: accent, display: "flex", flexShrink: 0 }, children: _jsx(GameIcon, { name: iconName, size: iconSize }) })) : null, _jsx("span", { "data-kill-feed-text": "", children: entry.text })] }, entry.id));
+        }) }));
+}

package/dist/map.d.ts

@@ -2,7 +2,7 @@ import { type CSSProperties, type ReactNode } from "react";
 import type { FogField } from "@jgengine/core/world/fog";
 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";
+import { type MapCellStates, type MapLayerTone, type MapRoute, type MapZone } from "@jgengine/core/world/mapLayers";
 /** 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[];
@@ -210,9 +210,130 @@ export interface WorldMapProps {
     title?: string;
     onClose?: () => void;
 }
+/** Pan/zoom transform applied to a {@link WorldMapSurface}'s content group. */
+export interface MapViewport {
+    /** Uniform zoom factor; 1 = fit. */
+    scale: number;
+    /** Content-group translation in canvas px. */
+    tx: number;
+    ty: number;
+}
+/** Props for {@link WorldMapSurface}. */
+export interface WorldMapSurfaceProps {
+    markers: MarkerCollection;
+    bounds: MapBounds;
+    player?: WorldXZ;
+    facingYaw?: number;
+    fog?: FogField;
+    background?: string;
+    /** Content layout width in px (world bounds map into this). */
+    width?: number;
+    /** Content layout height; defaults to the bounds aspect ratio. */
+    height?: number;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    routes?: readonly MapRoute[];
+    zones?: readonly MapZone[];
+    cellStates?: readonly MapCellStates[];
+    onWorldClick?: (world: WorldXZ) => void;
+    /** Outer `<svg>` pixel size; defaults to the content `width`/`height` (no viewport). */
+    canvasWidth?: number;
+    canvasHeight?: number;
+    /** Pan/zoom transform; identity when omitted. Click math inverts it before unprojecting. */
+    viewport?: MapViewport;
+    style?: CSSProperties;
+}
+/**
+ * The bare top-down map `<svg>` shared by {@link WorldMap} (framed panel) and
+ * {@link FullscreenMap} (pan/zoom overlay): baked terrain background, fog, map
+ * layers, markers with labels, and the player arrow, drawn under an optional
+ * viewport transform. Rectangular linear projection over the world `bounds`.
+ */
+export declare function WorldMapSurface({ markers, bounds, player, facingYaw, fog, background, width, height, kindStyles, routes, zones, cellStates, onWorldClick, canvasWidth, canvasHeight, viewport, style, }: WorldMapSurfaceProps): ReactNode;
 /**
  * Full-bounds top-down world map (the "press M" overlay): baked terrain
  * background, reveal-on-event fog, all markers with labels, and the player.
- * Rectangular linear projection over the supplied world `bounds`.
+ * Rectangular linear projection over the supplied world `bounds`. Framed panel
+ * wrapper over {@link WorldMapSurface}.
  */
 export declare function WorldMap({ markers, bounds, player, facingYaw, fog, background, width, height, kindStyles, routes, zones, cellStates, onWorldClick, className, title, onClose, }: WorldMapProps): ReactNode;
+/** Props for {@link FullscreenMap}. */
+export interface FullscreenMapProps extends Omit<WorldMapSurfaceProps, "canvasWidth" | "canvasHeight" | "viewport" | "width" | "height" | "style"> {
+    /** Render nothing when false. Default true. */
+    open?: boolean;
+    /** Content layout width in px before zoom; height derives from the bounds aspect. Default 900. */
+    contentWidth?: number;
+    /** Zoom bounds. Default 0.5 / 8. */
+    minScale?: number;
+    maxScale?: number;
+    title?: string;
+    onClose?: () => void;
+    /**
+     * Interaction mode. `"pan"` (default) drags to pan and click-to-place fires
+     * `onWorldClick`; `"draw"` drags to paint a freehand stroke, committed to
+     * `onStrokeComplete` (panning and click-to-place are suppressed).
+     */
+    tool?: "pan" | "draw";
+    /** Called with a finished freehand stroke (world-XZ points) in `"draw"` mode — wire to an annotation layer's `addStroke`. */
+    onStrokeComplete?: (points: readonly WorldXZ[]) => void;
+    /** Tone of the in-progress stroke while drawing. Default `"info"`. */
+    drawTone?: MapLayerTone;
+    /** Width (map px) of the in-progress stroke. Default 3. */
+    drawWidth?: number;
+    /** Overlay chrome drawn above the map (legend, tool palette, hints). */
+    children?: ReactNode;
+    overlayClassName?: string;
+    overlayStyle?: CSSProperties;
+}
+/**
+ * Fullscreen pan/zoom world-map overlay — the enlarged "press M" map. Wheel to
+ * zoom (toward the cursor), drag to pan, and click to place (wire `onWorldClick`
+ * to a waypoint/annotation store). Switch `tool` to `"draw"` to freehand-draw
+ * strokes committed to `onStrokeComplete` (wire to `createAnnotationLayer`).
+ * Reuses {@link WorldMapSurface} for rendering, so terrain bake, fog, routes,
+ * zones, markers, and the player arrow all appear; a drag never fires
+ * `onWorldClick`. Compose a {@link MapLegend} or tool palette via `children`.
+ *
+ * @capability fullscreen-map fullscreen pan/zoom world-map overlay over WorldMapSurface — wheel-zoom, drag-pan, click-to-place, and a freehand draw tool (onStrokeComplete)
+ */
+export declare function FullscreenMap({ open, bounds, contentWidth, minScale, maxScale, title, onClose, onWorldClick, tool, onStrokeComplete, drawTone, drawWidth, children, overlayClassName, overlayStyle, ...surfaceProps }: FullscreenMapProps): ReactNode;
+/** Props for {@link MapLegend}. */
+export interface MapLegendProps {
+    /** Marker kinds to key, in order. */
+    kinds: readonly string[];
+    /** Human labels per kind; falls back to the kind id. */
+    labels?: Record<string, string>;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    title?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Marker-kind key for a map/minimap — glyph + color swatch per kind, labelled.
+ * Reads the same `kindStyles` the map renders with, so the legend can never
+ * drift from the pins.
+ *
+ * @capability map-legend marker-kind key (glyph + color + label per kind) sharing the map's kindStyles
+ */
+export declare function MapLegend({ kinds, labels, kindStyles, title, className, style, }: MapLegendProps): ReactNode;
+/** Props for {@link WaypointArrow}. */
+export interface WaypointArrowProps {
+    /** Bearing to the target relative to facing (radians); 0 = dead ahead. From `WaypointStore.guidance().relative`. */
+    relative: number;
+    /** XZ distance in world units; renders a readout when supplied. */
+    distance?: number;
+    label?: string;
+    /** Format the distance readout; defaults to whole units + "m". */
+    formatDistance?: (distance: number) => string;
+    size?: number;
+    color?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * On-screen guide arrow to the tracked waypoint — a HUD compass needle rotated
+ * by the facing-relative bearing, with an optional label and distance readout.
+ * Pair with `WaypointStore.guidance(playerXZ, facingYaw)`.
+ *
+ * @capability waypoint-arrow on-screen HUD guide arrow to a tracked waypoint, rotated by facing-relative bearing with a distance readout
+ */
+export declare function WaypointArrow({ relative, distance, label, formatDistance, size, color, className, style, }: WaypointArrowProps): ReactNode;