@jgengine/react 0.13.0 → 0.15.0-next.0

package/dist/codex.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+const ALL = "__all";
+const MASK = "???";
+/**
+ * Codex / bestiary gallery — category tabs, a responsive grid of entry cards
+ * (discovered vs. locked, secret entries masked until found), and a header
+ * summarizing completion. Feed it `codex.list()`; wire `onSelect` to a detail
+ * pane.
+ *
+ * @capability codex-gallery codex/bestiary gallery with category tabs, discovered/locked cards, secret masking, and a completion header
+ */
+export function Codex({ entries, title = "Codex", columns = 3, maskSecrets = true, renderIcon, onSelect, emptyLabel = "Nothing discovered yet.", className, style, }) {
+    const categories = useMemo(() => {
+        const seen = [];
+        for (const entry of entries)
+            if (entry.category !== undefined && !seen.includes(entry.category))
+                seen.push(entry.category);
+        return seen;
+    }, [entries]);
+    const [tab, setTab] = useState(ALL);
+    const shown = tab === ALL ? entries : entries.filter((entry) => entry.category === tab);
+    const discovered = entries.reduce((count, entry) => (entry.discovered ? count + 1 : count), 0);
+    const tabStyle = (active) => ({
+        borderRadius: 6,
+        border: `1px solid ${active ? "rgba(56,189,248,0.6)" : "rgba(148,163,184,0.35)"}`,
+        background: active ? "rgba(56,189,248,0.2)" : "transparent",
+        color: active ? "#bae6fd" : "rgba(226,232,240,0.75)",
+        padding: "3px 9px",
+        fontSize: 11,
+        fontWeight: 600,
+        cursor: "pointer",
+    });
+    return (_jsxs("div", { className: className, "data-codex": true, style: {
+            width: columns * 116 + 28,
+            borderRadius: 14,
+            padding: 14,
+            background: "linear-gradient(160deg, rgba(20,24,32,0.97), rgba(11,14,19,0.97))",
+            border: "1px solid var(--jg-ring, rgba(148,163,184,0.32))",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            ...style,
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", marginBottom: 10 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 700, letterSpacing: 1.4, textTransform: "uppercase" }, children: title }), _jsxs("span", { style: { fontSize: 11, color: "rgba(203,213,225,0.75)", fontVariantNumeric: "tabular-nums" }, children: [discovered, "/", entries.length, " discovered"] })] }), categories.length > 0 ? (_jsxs("div", { style: { display: "flex", flexWrap: "wrap", gap: 5, marginBottom: 10 }, children: [_jsx("button", { type: "button", "data-codex-tab": ALL, style: tabStyle(tab === ALL), onClick: () => setTab(ALL), children: "All" }), categories.map((category) => (_jsx("button", { type: "button", "data-codex-tab": category, style: tabStyle(tab === category), onClick: () => setTab(category), children: category }, category)))] })) : null, shown.length === 0 ? (_jsx("p", { style: { margin: 0, fontSize: 12, color: "rgba(148,163,184,0.8)" }, children: emptyLabel })) : (_jsx("ul", { style: { listStyle: "none", margin: 0, padding: 0, display: "grid", gridTemplateColumns: `repeat(${columns}, 1fr)`, gap: 8 }, children: shown.map((entry) => {
+                    const masked = maskSecrets && entry.secret === true && !entry.discovered;
+                    const name = masked ? MASK : entry.name;
+                    const icon = renderIcon?.(entry) ?? (masked ? "🔒" : entry.discovered ? entry.icon ?? "📖" : "◻");
+                    return (_jsx("li", { children: _jsxs("button", { type: "button", "data-codex-entry": entry.id, "data-discovered": entry.discovered, onClick: () => onSelect?.(entry.id), style: {
+                                width: "100%",
+                                display: "flex",
+                                flexDirection: "column",
+                                alignItems: "center",
+                                gap: 4,
+                                padding: "12px 6px",
+                                borderRadius: 10,
+                                border: `1px solid ${entry.discovered ? "rgba(56,189,248,0.35)" : "rgba(148,163,184,0.2)"}`,
+                                background: entry.discovered ? "rgba(56,189,248,0.08)" : "rgba(148,163,184,0.05)",
+                                color: "#e2e8f0",
+                                cursor: onSelect !== undefined ? "pointer" : "default",
+                                opacity: entry.discovered ? 1 : 0.7,
+                            }, children: [_jsx("span", { style: { fontSize: 24, filter: entry.discovered ? "none" : "grayscale(1) brightness(0.7)" }, children: icon }), _jsx("span", { style: { fontSize: 11, fontWeight: entry.discovered ? 700 : 500, textAlign: "center" }, children: name }), entry.discovered && entry.description !== undefined ? (_jsx("span", { style: { fontSize: 10, color: "rgba(203,213,225,0.7)", textAlign: "center" }, children: entry.description })) : null] }) }, entry.id));
+                }) }))] }));
+}

package/dist/comboMeter.d.ts

@@ -0,0 +1,63 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { ComboMeter, ComboMeterView } from "@jgengine/core/combat/comboMeter";
+/**
+ * Subscribe to a combo meter and re-render it each animation frame so the decay
+ * window bar drains live, returning the pooled view to draw right now. Reading the
+ * view each frame advances the meter's clock and fires window expiry, so a combo
+ * that times out visibly drops even with no further hits. The returned object is
+ * the model's pooled view — read its fields immediately, do not retain it.
+ *
+ * @capability use-combo-meter React hook binding a combo meter — re-renders per frame so the decay-window bar drains live and returns the current combo view
+ */
+export declare function useComboMeter(meter: ComboMeter, animate?: boolean): ComboMeterView;
+/** Reskin tokens for {@link ComboMeterHud}. */
+export interface ComboMeterTheme {
+    /** Accent used when no tier is active (below the first threshold). Default reads `--jg-accent`. */
+    accent?: string;
+    /** Combo count text color. Default near-white. */
+    count?: string;
+    /** Tier label + multiplier text color. Default reads the active tier color. */
+    label?: string;
+    /** Font family. Default the HUD sans stack. */
+    fontFamily?: string;
+    /** Count font size (CSS length). Default `"clamp(2rem, 6vw, 4rem)"`. */
+    countSize?: string;
+}
+/** Props for {@link ComboMeterHud}. */
+export interface ComboMeterHudProps {
+    /** The combo meter to render. */
+    meter: ComboMeter;
+    /**
+     * Per-tier color keyed by the free-string tier id the game configured
+     * ("good"/"great"/"savage", …). The active tier's color drives the count glow,
+     * label, and draining window bar. Missing ids fall back to the accent.
+     */
+    tierColors?: Record<string, string>;
+    /** Base reskin tokens. */
+    theme?: ComboMeterTheme;
+    /**
+     * Drive re-renders on an animation frame so the window bar drains live. Default
+     * `true`. Turn off if the game already re-renders the HUD each frame.
+     */
+    animate?: boolean;
+    /** Hide the whole HUD while the combo count is zero. Default `true`. */
+    hideWhenEmpty?: boolean;
+    /** Width of the draining window bar (any CSS length). Default `220`. */
+    barWidth?: number | string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A drop-in HUD for a core {@link ComboMeter}: the big live combo count ("×12"),
+ * the current free-string tier label, the derived score multiplier, and a draining
+ * window bar (reusing the shared atomic bar) that empties as the decay window runs
+ * out and re-fills on every hit. The active tier's color — supplied by the game via
+ * `tierColors`, keyed on the free-string tier id the model never interprets — drives
+ * the count glow, the label, and the bar fill, so a game reskins the escalation
+ * ("good" → "great" → "savage") without the engine hardcoding any tier meaning.
+ * Presentation only: all counting, timing, tiers, and the multiplier live in the
+ * core model.
+ *
+ * @capability combo-meter-hud drop-in HUD for a core combo meter — big live count, free-string tier label, derived multiplier, and a draining decay-window bar, per-tier colored from a caller map and HudTheme-token skinnable
+ */
+export declare function ComboMeterHud({ meter, tierColors, theme, animate, hideWhenEmpty, barWidth, className, style, }: ComboMeterHudProps): ReactNode;

package/dist/comboMeter.js

@@ -0,0 +1,93 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer, useRef } from "react";
+import { StaminaBar } from "./bars.js";
+/**
+ * Subscribe to a combo meter and re-render it each animation frame so the decay
+ * window bar drains live, returning the pooled view to draw right now. Reading the
+ * view each frame advances the meter's clock and fires window expiry, so a combo
+ * that times out visibly drops even with no further hits. The returned object is
+ * the model's pooled view — read its fields immediately, do not retain it.
+ *
+ * @capability use-combo-meter React hook binding a combo meter — re-renders per frame so the decay-window bar drains live and returns the current combo view
+ */
+export function useComboMeter(meter, animate = true) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    const rafRef = useRef(0);
+    useEffect(() => meter.subscribe(bump), [meter]);
+    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);
+        };
+    }, [meter, animate]);
+    return meter.view();
+}
+function resolveTheme(theme) {
+    return {
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        count: theme?.count ?? "#f8fafc",
+        label: theme?.label,
+        fontFamily: theme?.fontFamily ?? "ui-sans-serif, system-ui, sans-serif",
+        countSize: theme?.countSize ?? "clamp(2rem, 6vw, 4rem)",
+    };
+}
+/**
+ * A drop-in HUD for a core {@link ComboMeter}: the big live combo count ("×12"),
+ * the current free-string tier label, the derived score multiplier, and a draining
+ * window bar (reusing the shared atomic bar) that empties as the decay window runs
+ * out and re-fills on every hit. The active tier's color — supplied by the game via
+ * `tierColors`, keyed on the free-string tier id the model never interprets — drives
+ * the count glow, the label, and the bar fill, so a game reskins the escalation
+ * ("good" → "great" → "savage") without the engine hardcoding any tier meaning.
+ * Presentation only: all counting, timing, tiers, and the multiplier live in the
+ * core model.
+ *
+ * @capability combo-meter-hud drop-in HUD for a core combo meter — big live count, free-string tier label, derived multiplier, and a draining decay-window bar, per-tier colored from a caller map and HudTheme-token skinnable
+ */
+export function ComboMeterHud({ meter, tierColors, theme, animate = true, hideWhenEmpty = true, barWidth = 220, className, style, }) {
+    const view = useComboMeter(meter, animate);
+    const t = resolveTheme(theme);
+    if (hideWhenEmpty && view.count <= 0)
+        return null;
+    const tierColor = view.tier !== null ? tierColors?.[view.tier] ?? t.accent : t.accent;
+    const labelColor = t.label ?? tierColor;
+    return (_jsxs("div", { className: className, "data-combo-meter": "", "data-combo-tier": view.tier ?? "", "data-combo-count": view.count, style: {
+            display: "inline-flex",
+            flexDirection: "column",
+            alignItems: "flex-start",
+            gap: 6,
+            fontFamily: t.fontFamily,
+            ...style,
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: 12 }, children: [_jsxs("span", { "data-combo-count-value": "", style: {
+                            fontSize: t.countSize,
+                            fontWeight: 900,
+                            lineHeight: 1,
+                            letterSpacing: "0.02em",
+                            fontVariantNumeric: "tabular-nums",
+                            color: t.count,
+                            textShadow: `0 0 0.4em ${tierColor}, 0 3px 14px rgba(0,0,0,0.6)`,
+                        }, children: ["\u00D7", view.count] }), view.tier !== null ? (_jsx("span", { "data-combo-tier-label": "", style: {
+                            fontSize: "clamp(0.9rem, 2.4vw, 1.4rem)",
+                            fontWeight: 800,
+                            letterSpacing: "0.14em",
+                            textTransform: "uppercase",
+                            color: labelColor,
+                            textShadow: "0 2px 10px rgba(0,0,0,0.6)",
+                        }, children: view.tier })) : null] }), _jsxs("div", { style: { display: "flex", alignItems: "center", gap: 10 }, children: [_jsx(StaminaBar, { value: view.fraction * 100, max: 100, fill: tierColor, showValue: false, width: barWidth, shape: "pill" }), _jsxs("span", { "data-combo-multiplier": "", style: {
+                            fontSize: 14,
+                            fontWeight: 800,
+                            fontVariantNumeric: "tabular-nums",
+                            color: labelColor,
+                            textShadow: "0 1px 6px rgba(0,0,0,0.6)",
+                        }, children: [view.multiplier.toFixed(2), "\u00D7 score"] })] })] }));
+}

package/dist/components.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from "react";
 import { evaluateSkillCheck, } from "@jgengine/core/interaction/skillCheck";
 import { pendingQteStep } from "@jgengine/core/interaction/qte";
+import { lootDropsOf } from "@jgengine/core/game/events";
 import { rollCheck } from "@jgengine/core/stats/rollCheck";
 import { dialogueSlot } from "@jgengine/core/game/dialogue";
 import { useGameContext } from "./provider.js";
@@ -142,9 +143,9 @@ export function CaptureOdds({ chance, className, fillClassName, }) {
     return (_jsxs("div", { className: className, role: "progressbar", "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": percent, "data-capture-odds": percent, children: [_jsx("div", { className: fillClassName, style: { width: `${percent}%`, height: "100%" } }), _jsxs("span", { "data-capture-odds-label": true, style: { position: "relative", zIndex: 1 }, children: [percent, "%"] })] }));
 }
 function defaultToast(entry) {
-    const data = entry.data;
-    if (data?.drops !== undefined) {
-        return data.drops.map((drop) => `${drop.item ?? drop.currency ?? "item"} ×${drop.count}`).join("  ");
+    const drops = lootDropsOf(entry.data);
+    if (drops.length > 0) {
+        return drops.map((drop) => `${drop.item ?? drop.currency ?? "item"} ×${drop.count}`).join("  ");
     }
     return typeof entry.data === "string" ? entry.data : JSON.stringify(entry.data);
 }

package/dist/creditsScreen.d.ts

@@ -0,0 +1,19 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { CreditsDocument, CreditsEntry } from "@jgengine/core/game/credits";
+/**
+ * Renders a {@link CreditsDocument} as headed sections of credited lines. Skinned entirely through
+ * the `--jg-*` HudTheme tokens, so it inherits the game's look from the surrounding theme block;
+ * pass `renderEntry` to art-direct the line itself. Links render only when an entry carries `href`,
+ * and always open in a new tab with `noreferrer`.
+ *
+ * This is a building block, not a finished credits screen — the game owns placement, backdrop, the
+ * back affordance, and whether it scrolls or rolls.
+ *
+ * @capability credits-screen drop-in credits view over a CreditsDocument — headed sections, optional links, HudTheme-skinned
+ */
+export declare function CreditsScreen({ document, className, style, renderEntry, }: {
+    document: CreditsDocument;
+    className?: string;
+    style?: CSSProperties;
+    renderEntry?: (entry: CreditsEntry, index: number) => ReactNode;
+}): ReactNode;

package/dist/creditsScreen.js

@@ -0,0 +1,31 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+/**
+ * Renders a {@link CreditsDocument} as headed sections of credited lines. Skinned entirely through
+ * the `--jg-*` HudTheme tokens, so it inherits the game's look from the surrounding theme block;
+ * pass `renderEntry` to art-direct the line itself. Links render only when an entry carries `href`,
+ * and always open in a new tab with `noreferrer`.
+ *
+ * This is a building block, not a finished credits screen — the game owns placement, backdrop, the
+ * back affordance, and whether it scrolls or rolls.
+ *
+ * @capability credits-screen drop-in credits view over a CreditsDocument — headed sections, optional links, HudTheme-skinned
+ */
+export function CreditsScreen({ document, className, style, renderEntry, }) {
+    return (_jsxs("div", { className: className, "data-jg": "credits-screen", style: { display: "flex", flexDirection: "column", gap: 22, color: "var(--jg-text, #f5f7fa)", ...style }, children: [document.title !== undefined && (_jsx("h2", { style: {
+                    margin: 0,
+                    fontFamily: "var(--jg-font-display, inherit)",
+                    fontSize: 26,
+                    fontWeight: 800,
+                    letterSpacing: "0.24em",
+                    textTransform: "uppercase",
+                }, children: document.title })), document.sections.map((section) => (_jsxs("section", { "data-jg": "credits-section", style: { display: "flex", flexDirection: "column", gap: 8 }, children: [_jsx("h3", { style: {
+                            margin: 0,
+                            fontFamily: "var(--jg-font-display, inherit)",
+                            fontSize: 11,
+                            fontWeight: 700,
+                            letterSpacing: "0.24em",
+                            textTransform: "uppercase",
+                            color: "var(--jg-accent, #38bdf8)",
+                        }, children: section.heading }), section.entries.map((entry, index) => (_jsx("div", { "data-jg": "credits-entry", style: { display: "flex", gap: 10, alignItems: "baseline" }, children: renderEntry !== undefined ? (renderEntry(entry, index)) : (_jsxs(_Fragment, { children: [entry.href === undefined ? (_jsx("span", { style: { fontSize: 14 }, children: entry.label })) : (_jsx("a", { href: entry.href, target: "_blank", rel: "noreferrer", style: { fontSize: 14, color: "inherit", textDecoration: "underline" }, children: entry.label })), entry.detail !== undefined && (_jsx("span", { style: { fontSize: 12, color: "var(--jg-text-dim, #94a3b8)" }, children: entry.detail }))] })) }, `${entry.label}-${index}`)))] }, section.heading))), document.notice !== undefined && (_jsx("p", { style: { margin: 0, fontSize: 12, color: "var(--jg-text-dim, #94a3b8)", whiteSpace: "pre-line" }, children: document.notice }))] }));
+}

package/dist/cutscene.d.ts

@@ -0,0 +1,66 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { SequenceDirector, SequenceState } from "@jgengine/core/scene/sequenceDirector";
+/** The live playback state plus bound controls returned by {@link useSequenceDirector}. */
+export interface SequenceDirectorBinding extends SequenceState {
+    /** Start or resume playback. */
+    play: () => void;
+    /** Freeze the playhead. */
+    pause: () => void;
+    /** Fast-forward to the end, emitting remaining cues. */
+    skip: () => void;
+    /** Jump the playhead to `ms`. */
+    seek: (ms: number) => void;
+    /** Halt and rewind to the start. */
+    stop: () => void;
+}
+/**
+ * Bind a {@link SequenceDirector} to a component: subscribe to its state, and while
+ * it is playing run a `requestAnimationFrame` loop that ticks the director each frame
+ * off the same injected clock — so a game drops in one hook and the cutscene advances
+ * itself. Returns the current playback state (playhead, progress, playing/done) plus
+ * bound `play`/`pause`/`skip`/`seek`/`stop`. Cue side effects belong on
+ * `director.onCue`, not here — the hook never interprets a cue.
+ *
+ * @capability use-sequence-director React hook that drives a cutscene director's per-frame tick loop and exposes playhead/progress + play/pause/skip controls
+ */
+export declare function useSequenceDirector(director: SequenceDirector): SequenceDirectorBinding;
+/** Reskin tokens for {@link CutsceneLetterbox}. */
+export interface CutsceneLetterboxTheme {
+    /** Cinematic bar color. Default solid black. */
+    barColor?: string;
+    /** Height of each bar as a fraction of the viewport height, in `[0, 0.5]`. Default `0.12`. */
+    barFraction?: number;
+    /** Caption panel background. */
+    captionBackground?: string;
+    /** Caption text color. */
+    captionText?: string;
+    /** Skip button accent. Default reads `--jg-accent`. */
+    accent?: string;
+}
+/** Props for {@link CutsceneLetterbox}. */
+export interface CutsceneLetterboxProps {
+    /** When `true`, the cinematic bars are drawn in; when `false` they retract off-screen. */
+    active: boolean;
+    /** Optional caption / dialogue node shown centered above the lower bar. */
+    caption?: ReactNode;
+    /** Skip handler. When provided, a Skip button renders in the top bar. */
+    onSkip?: () => void;
+    /** Skip button label. Default `"Skip"`. */
+    skipLabel?: string;
+    /** Elapsed fraction `[0, 1]` for the thin progress line under the caption; omit to hide it. */
+    progress?: number;
+    /** Reskin tokens. */
+    theme?: CutsceneLetterboxTheme;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A drop-in cinematic letterbox overlay: black bars slide in top and bottom while a
+ * cutscene is `active`, an optional caption/dialogue line sits above the lower bar with
+ * an optional progress line, and a Skip button rides the top bar. Presentation only —
+ * it never touches the director; wire `active`/`caption`/`progress`/`onSkip` from
+ * {@link useSequenceDirector} and your `onCue` handler. Reskin via {@link CutsceneLetterboxTheme}.
+ *
+ * @capability cutscene-letterbox reskinnable cinematic letterbox + skip overlay for a cutscene — animated bars, caption/dialogue slot, progress line, Skip button
+ */
+export declare function CutsceneLetterbox({ active, caption, onSkip, skipLabel, progress, theme, className, style, }: CutsceneLetterboxProps): ReactNode;

package/dist/cutscene.js

@@ -0,0 +1,132 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer } from "react";
+/**
+ * Bind a {@link SequenceDirector} to a component: subscribe to its state, and while
+ * it is playing run a `requestAnimationFrame` loop that ticks the director each frame
+ * off the same injected clock — so a game drops in one hook and the cutscene advances
+ * itself. Returns the current playback state (playhead, progress, playing/done) plus
+ * bound `play`/`pause`/`skip`/`seek`/`stop`. Cue side effects belong on
+ * `director.onCue`, not here — the hook never interprets a cue.
+ *
+ * @capability use-sequence-director React hook that drives a cutscene director's per-frame tick loop and exposes playhead/progress + play/pause/skip controls
+ */
+export function useSequenceDirector(director) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => director.subscribe(bump), [director]);
+    const playing = director.state().playing;
+    useEffect(() => {
+        if (!playing || typeof requestAnimationFrame === "undefined")
+            return;
+        let raf = 0;
+        const frame = () => {
+            director.tick();
+            raf = requestAnimationFrame(frame);
+        };
+        raf = requestAnimationFrame(frame);
+        return () => cancelAnimationFrame(raf);
+    }, [director, playing]);
+    const state = director.state();
+    return {
+        ...state,
+        play: () => director.play(),
+        pause: () => director.pause(),
+        skip: () => director.skip(),
+        seek: (ms) => director.seek(ms),
+        stop: () => director.stop(),
+    };
+}
+function resolveTheme(theme) {
+    return {
+        barColor: theme?.barColor ?? "#000",
+        barFraction: Math.max(0, Math.min(0.5, theme?.barFraction ?? 0.12)),
+        captionBackground: theme?.captionBackground ?? "rgba(6,9,14,0.62)",
+        captionText: theme?.captionText ?? "#f1f5f9",
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+    };
+}
+/**
+ * A drop-in cinematic letterbox overlay: black bars slide in top and bottom while a
+ * cutscene is `active`, an optional caption/dialogue line sits above the lower bar with
+ * an optional progress line, and a Skip button rides the top bar. Presentation only —
+ * it never touches the director; wire `active`/`caption`/`progress`/`onSkip` from
+ * {@link useSequenceDirector} and your `onCue` handler. Reskin via {@link CutsceneLetterboxTheme}.
+ *
+ * @capability cutscene-letterbox reskinnable cinematic letterbox + skip overlay for a cutscene — animated bars, caption/dialogue slot, progress line, Skip button
+ */
+export function CutsceneLetterbox({ active, caption, onSkip, skipLabel = "Skip", progress, theme, className, style, }) {
+    const t = resolveTheme(theme);
+    const barHeight = `${(t.barFraction * 100).toFixed(3)}vh`;
+    const shift = active ? "0%" : "-100%";
+    const shiftDown = active ? "0%" : "100%";
+    return (_jsxs("div", { className: className, "data-cutscene-letterbox": active ? "active" : "idle", style: {
+            position: "fixed",
+            inset: 0,
+            zIndex: 70,
+            pointerEvents: "none",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            ...style,
+        }, children: [_jsx("div", { "data-cutscene-bar": "top", style: {
+                    position: "absolute",
+                    top: 0,
+                    left: 0,
+                    right: 0,
+                    height: barHeight,
+                    background: t.barColor,
+                    transform: `translateY(${shift})`,
+                    transition: "transform 500ms cubic-bezier(0.22,1,0.36,1)",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "flex-end",
+                    padding: "0 20px",
+                }, children: onSkip !== undefined ? (_jsxs("button", { type: "button", "data-cutscene-skip": true, onClick: onSkip, style: {
+                        pointerEvents: "auto",
+                        display: "inline-flex",
+                        alignItems: "center",
+                        gap: 6,
+                        border: "1px solid rgba(148,163,184,0.4)",
+                        borderRadius: 8,
+                        background: "rgba(15,23,42,0.7)",
+                        color: t.accent,
+                        fontSize: 12.5,
+                        fontWeight: 700,
+                        letterSpacing: 0.4,
+                        padding: "6px 14px",
+                        cursor: "pointer",
+                    }, children: [skipLabel, " ", _jsx("span", { "aria-hidden": true, style: { opacity: 0.8 }, children: "\u23ED" })] })) : null }), _jsx("div", { "data-cutscene-bar": "bottom", style: {
+                    position: "absolute",
+                    bottom: 0,
+                    left: 0,
+                    right: 0,
+                    height: barHeight,
+                    background: t.barColor,
+                    transform: `translateY(${shiftDown})`,
+                    transition: "transform 500ms cubic-bezier(0.22,1,0.36,1)",
+                } }), active && (caption !== undefined || progress !== undefined) ? (_jsxs("div", { "data-cutscene-caption": true, style: {
+                    position: "absolute",
+                    left: "50%",
+                    bottom: `calc(${barHeight} + 28px)`,
+                    transform: "translateX(-50%)",
+                    maxWidth: "min(78vw, 720px)",
+                    textAlign: "center",
+                    color: t.captionText,
+                }, children: [caption !== undefined ? (_jsx("div", { style: {
+                            background: t.captionBackground,
+                            borderRadius: 12,
+                            padding: "12px 20px",
+                            fontSize: 18,
+                            lineHeight: 1.5,
+                            textShadow: "0 2px 12px rgba(0,0,0,0.7)",
+                            boxShadow: "0 10px 40px rgba(0,0,0,0.45)",
+                        }, children: caption })) : null, progress !== undefined ? (_jsx("div", { "data-cutscene-progress": true, style: {
+                            marginTop: 10,
+                            height: 3,
+                            borderRadius: 3,
+                            background: "rgba(148,163,184,0.25)",
+                            overflow: "hidden",
+                        }, children: _jsx("div", { style: {
+                                height: "100%",
+                                width: `${Math.max(0, Math.min(1, progress)) * 100}%`,
+                                background: t.accent,
+                                transition: "width 120ms linear",
+                            } }) })) : null] })) : null] }));
+}

package/dist/damageDirection.d.ts

@@ -0,0 +1,51 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { DamageDirectionTracker, DamageIndicator } from "@jgengine/core/vfx/damageDirection";
+/**
+ * Subscribe to a damage-direction tracker and animate. Because indicators fade
+ * continuously on a clock (not just on discrete events), this drives a
+ * `requestAnimationFrame` loop while any indicator is live and stops when the
+ * screen is clear, then wakes again on the next hit. Returns the tracker's
+ * current `active()` array (reused between frames — copy if you retain it).
+ *
+ * @capability use-damage-direction React hook that animates a damage-direction tracker's fade with requestAnimationFrame and re-renders its live indicators
+ */
+export declare function useDamageDirection(tracker: DamageDirectionTracker): readonly DamageIndicator[];
+/** Reskin tokens for {@link DamageDirectionOverlay}. */
+export interface DamageDirectionTheme {
+    /** Fallback arc color when a `kind` isn't in {@link DamageDirectionOverlayProps.colors}. Default reads `--jg-health` (danger red). */
+    color?: string;
+    /** Radius of the arc band from screen center, in px. Default `120`. */
+    radius?: number;
+    /** Angular half-width of each arc, in radians. Default `0.42` (~48° wide). */
+    arcSpread?: number;
+    /** Arc stroke thickness in px at full intensity. Default `18`. */
+    thickness?: number;
+    /** Extra px an arc pushes outward as it flares (scale feel). Default `18`. */
+    flare?: number;
+}
+/** Props for {@link DamageDirectionOverlay}. */
+export interface DamageDirectionOverlayProps {
+    /** The tracker to visualize. */
+    tracker: DamageDirectionTracker;
+    /** Per-`kind` arc colors, e.g. `{ fire: "#ff7a1a", crit: "#ffd23f" }`. Falls back to the theme color. */
+    colors?: Record<string, string>;
+    /** Draw a small dot at screen center so bearings read against a fixed reference. Default `true`. */
+    showReticle?: boolean;
+    /** Reskin tokens. */
+    theme?: DamageDirectionTheme;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A drop-in "hit-from" overlay: transient red (by default) arcs that flare around
+ * a center reticle in the direction each recent hit came from and fade out over
+ * time, driven entirely by a {@link DamageDirectionTracker}. Opacity and outward
+ * push scale with each indicator's eased intensity; color comes from the hit's
+ * `kind` (via `colors`) or the theme's danger color. Renders full-screen,
+ * `pointer-events: none`, so it never intercepts input — a game drops it into its
+ * HUD and calls `tracker.registerHit(...)` on damage. Reskin via
+ * {@link DamageDirectionTheme}.
+ *
+ * @capability damage-direction-overlay drop-in hit-from damage-direction overlay — SVG arcs flaring around a center reticle toward each recent hit and fading over time, colored per `kind`/HudTheme, pointer-events none
+ */
+export declare function DamageDirectionOverlay({ tracker, colors, showReticle, theme, className, style, }: DamageDirectionOverlayProps): ReactNode;

package/dist/damageDirection.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer, useRef } from "react";
+/**
+ * Subscribe to a damage-direction tracker and animate. Because indicators fade
+ * continuously on a clock (not just on discrete events), this drives a
+ * `requestAnimationFrame` loop while any indicator is live and stops when the
+ * screen is clear, then wakes again on the next hit. Returns the tracker's
+ * current `active()` array (reused between frames — copy if you retain it).
+ *
+ * @capability use-damage-direction React hook that animates a damage-direction tracker's fade with requestAnimationFrame and re-renders its live indicators
+ */
+export function useDamageDirection(tracker) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    const rafRef = useRef(null);
+    useEffect(() => {
+        let stopped = false;
+        const tick = () => {
+            if (stopped)
+                return;
+            bump();
+            rafRef.current = tracker.count() > 0 ? requestAnimationFrame(tick) : null;
+        };
+        // Any change (new hit, clear, restore) paints immediately and (re)starts the
+        // fade loop if it had idled — so a hit shows even when rAF is throttled.
+        const off = tracker.subscribe(() => {
+            bump();
+            if (rafRef.current === null)
+                rafRef.current = requestAnimationFrame(tick);
+        });
+        if (tracker.count() > 0)
+            rafRef.current = requestAnimationFrame(tick);
+        return () => {
+            stopped = true;
+            off();
+            if (rafRef.current !== null)
+                cancelAnimationFrame(rafRef.current);
+        };
+    }, [tracker]);
+    return tracker.active();
+}
+const VIEWBOX = 300;
+const CENTER = VIEWBOX / 2;
+/** SVG path for an annular arc segment centered on the reticle at `angle` (radians, 0 = up, clockwise). */
+function arcPath(angle, radius, half, thickness) {
+    const inner = Math.max(0, radius - thickness / 2);
+    const outer = radius + thickness / 2;
+    // Screen bearing: 0 rad points up (−Y), increasing clockwise.
+    const a0 = angle - half;
+    const a1 = angle + half;
+    const p = (a, r) => [
+        CENTER + Math.sin(a) * r,
+        CENTER - Math.cos(a) * r,
+    ];
+    const [ox0, oy0] = p(a0, outer);
+    const [ox1, oy1] = p(a1, outer);
+    const [ix1, iy1] = p(a1, inner);
+    const [ix0, iy0] = p(a0, inner);
+    const large = a1 - a0 > Math.PI ? 1 : 0;
+    return [
+        `M ${ox0.toFixed(2)} ${oy0.toFixed(2)}`,
+        `A ${outer} ${outer} 0 ${large} 1 ${ox1.toFixed(2)} ${oy1.toFixed(2)}`,
+        `L ${ix1.toFixed(2)} ${iy1.toFixed(2)}`,
+        `A ${inner} ${inner} 0 ${large} 0 ${ix0.toFixed(2)} ${iy0.toFixed(2)}`,
+        "Z",
+    ].join(" ");
+}
+/**
+ * A drop-in "hit-from" overlay: transient red (by default) arcs that flare around
+ * a center reticle in the direction each recent hit came from and fade out over
+ * time, driven entirely by a {@link DamageDirectionTracker}. Opacity and outward
+ * push scale with each indicator's eased intensity; color comes from the hit's
+ * `kind` (via `colors`) or the theme's danger color. Renders full-screen,
+ * `pointer-events: none`, so it never intercepts input — a game drops it into its
+ * HUD and calls `tracker.registerHit(...)` on damage. Reskin via
+ * {@link DamageDirectionTheme}.
+ *
+ * @capability damage-direction-overlay drop-in hit-from damage-direction overlay — SVG arcs flaring around a center reticle toward each recent hit and fading over time, colored per `kind`/HudTheme, pointer-events none
+ */
+export function DamageDirectionOverlay({ tracker, colors, showReticle = true, theme, className, style, }) {
+    const indicators = useDamageDirection(tracker);
+    const color = theme?.color ?? "var(--jg-health, #e5484d)";
+    const radius = theme?.radius ?? 120;
+    const arcSpread = theme?.arcSpread ?? 0.42;
+    const thickness = theme?.thickness ?? 18;
+    const flare = theme?.flare ?? 18;
+    return (_jsx("div", { className: className, "data-damage-direction": true, style: { position: "fixed", inset: 0, zIndex: 55, pointerEvents: "none", ...style }, children: _jsxs("svg", { viewBox: `0 0 ${VIEWBOX} ${VIEWBOX}`, preserveAspectRatio: "xMidYMid meet", "aria-hidden": true, style: {
+                position: "absolute",
+                top: "50%",
+                left: "50%",
+                width: (radius + thickness + flare) * 2,
+                height: (radius + thickness + flare) * 2,
+                transform: "translate(-50%, -50%)",
+                overflow: "visible",
+            }, children: [indicators.map((indicator, i) => {
+                    const eased = indicator.intensity;
+                    if (eased <= 0)
+                        return null;
+                    const fill = colors?.[indicator.kind] ?? color;
+                    const r = radius + flare * eased;
+                    const th = thickness * (0.55 + 0.45 * eased);
+                    return (_jsx("path", { "data-damage-arc": indicator.kind, d: arcPath(indicator.angle, r, arcSpread, th), fill: fill, opacity: Math.min(1, 0.15 + 0.85 * eased), style: { filter: `drop-shadow(0 0 ${6 * eased}px ${fill})` } }, i));
+                }), showReticle ? (_jsx("circle", { "data-damage-reticle": true, cx: CENTER, cy: CENTER, r: 3.5, fill: "none", stroke: "var(--jg-ring, rgba(226,232,240,0.7))", strokeWidth: 2 })) : null] }) }));
+}