@jgengine/react 0.14.0 → 0.15.0

package/dist/accessibility.d.ts

@@ -0,0 +1,39 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type AccessibilityState, type AccessibilityStore } from "@jgengine/core/ui/accessibility";
+interface AccessibilityContextValue {
+    state: AccessibilityState;
+    store: AccessibilityStore;
+}
+/** Read the live accessibility state + its store; throws without an {@link AccessibilityProvider} above. */
+export declare function useAccessibility(): AccessibilityContextValue;
+/**
+ * Hidden SVG `<defs>` holding the `feColorMatrix` colorblind filters that
+ * `AccessibilityProvider` references by `filter: url(#jg-cb-<mode>)`. Rendered
+ * automatically inside the provider; export standalone for custom roots.
+ *
+ * @capability colorblind-filters SVG feColorMatrix defs (protanopia/deuteranopia/tritanopia/grayscale) referenced by the accessibility colorblind filter
+ */
+export declare function ColorblindFilters(): ReactNode;
+/**
+ * Apply accessibility preferences to a subtree: exposes `--jg-text-scale` for
+ * text to scale off, sets `data-reduced-motion` / `data-high-contrast` /
+ * `data-colorblind` / `data-captions` for CSS to respond to, and wraps the tree
+ * in the selected colorblind `feColorMatrix` filter. Reads a
+ * `createAccessibilityStore` and re-renders on change; provides the state to
+ * `useAccessibility`.
+ *
+ * @capability accessibility-provider apply accessibility preferences to a subtree — text-scale CSS var, reduced-motion/high-contrast/colorblind/captions data attrs, and the colorblind color-matrix filter
+ */
+export declare function AccessibilityProvider({ store, children, className, style, }: {
+    store: AccessibilityStore;
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): ReactNode;
+/**
+ * OS "reduce motion" preference (`prefers-reduced-motion: reduce`) as a live
+ * boolean — SSR-safe (defaults false). Use it to seed an accessibility store's
+ * `reducedMotion` default.
+ */
+export declare function usePrefersReducedMotion(): boolean;
+export {};

package/dist/accessibility.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useSyncExternalStore } from "react";
+import { COLORBLIND_MATRICES, } from "@jgengine/core/ui/accessibility";
+const AccessibilityContext = createContext(null);
+const FILTER_MODES = [
+    "protanopia",
+    "deuteranopia",
+    "tritanopia",
+    "grayscale",
+];
+/** Read the live accessibility state + its store; throws without an {@link AccessibilityProvider} above. */
+export function useAccessibility() {
+    const value = useContext(AccessibilityContext);
+    if (value === null)
+        throw new Error("useAccessibility must be used within an <AccessibilityProvider>");
+    return value;
+}
+/**
+ * Hidden SVG `<defs>` holding the `feColorMatrix` colorblind filters that
+ * `AccessibilityProvider` references by `filter: url(#jg-cb-<mode>)`. Rendered
+ * automatically inside the provider; export standalone for custom roots.
+ *
+ * @capability colorblind-filters SVG feColorMatrix defs (protanopia/deuteranopia/tritanopia/grayscale) referenced by the accessibility colorblind filter
+ */
+export function ColorblindFilters() {
+    return (_jsx("svg", { "aria-hidden": true, width: 0, height: 0, style: { position: "absolute" }, "data-colorblind-filters": true, children: _jsx("defs", { children: FILTER_MODES.map((mode) => (_jsx("filter", { id: `jg-cb-${mode}`, colorInterpolationFilters: "sRGB", children: _jsx("feColorMatrix", { type: "matrix", values: COLORBLIND_MATRICES[mode] ?? "" }) }, mode))) }) }));
+}
+/**
+ * Apply accessibility preferences to a subtree: exposes `--jg-text-scale` for
+ * text to scale off, sets `data-reduced-motion` / `data-high-contrast` /
+ * `data-colorblind` / `data-captions` for CSS to respond to, and wraps the tree
+ * in the selected colorblind `feColorMatrix` filter. Reads a
+ * `createAccessibilityStore` and re-renders on change; provides the state to
+ * `useAccessibility`.
+ *
+ * @capability accessibility-provider apply accessibility preferences to a subtree — text-scale CSS var, reduced-motion/high-contrast/colorblind/captions data attrs, and the colorblind color-matrix filter
+ */
+export function AccessibilityProvider({ store, children, className, style, }) {
+    const state = useSyncExternalStore(store.subscribe, store.get, store.get);
+    const rootStyle = { ...style };
+    rootStyle["--jg-text-scale"] = String(state.textScale);
+    if (state.colorblind !== "none")
+        rootStyle.filter = `url(#jg-cb-${state.colorblind})`;
+    return (_jsx(AccessibilityContext.Provider, { value: { state, store }, children: _jsxs("div", { className: className, "data-accessibility": true, "data-reduced-motion": state.reducedMotion, "data-high-contrast": state.highContrast, "data-colorblind": state.colorblind, "data-captions": state.captions, style: rootStyle, children: [_jsx(ColorblindFilters, {}), children] }) }));
+}
+/**
+ * OS "reduce motion" preference (`prefers-reduced-motion: reduce`) as a live
+ * boolean — SSR-safe (defaults false). Use it to seed an accessibility store's
+ * `reducedMotion` default.
+ */
+export function usePrefersReducedMotion() {
+    return useSyncExternalStore((listener) => {
+        if (typeof window === "undefined" || typeof window.matchMedia !== "function")
+            return () => undefined;
+        const query = window.matchMedia("(prefers-reduced-motion: reduce)");
+        query.addEventListener("change", listener);
+        return () => query.removeEventListener("change", listener);
+    }, () => typeof window !== "undefined" && typeof window.matchMedia === "function"
+        ? window.matchMedia("(prefers-reduced-motion: reduce)").matches
+        : false, () => false);
+}

package/dist/achievements.d.ts

@@ -0,0 +1,50 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { AchievementTracker, AchievementView } from "@jgengine/core/game/achievements";
+/**
+ * Subscribe a component to an achievement tracker's live view list. The list
+ * keeps a stable identity between changes, so this re-renders only on unlock or
+ * progress — not every frame.
+ */
+export declare function useAchievements(tracker: AchievementTracker): readonly AchievementView[];
+/** Props for {@link AchievementToast}. */
+export interface AchievementToastProps {
+    name: string;
+    description?: string;
+    /** Icon/glyph node the game supplies; the engine never picks art. */
+    icon?: ReactNode;
+    points?: number;
+    /** Small heading above the name. Default `"Achievement Unlocked"`. */
+    heading?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * The unlock-moment banner — icon, "Achievement Unlocked" heading, name, and
+ * optional points. Purely presentational; pair the game's `onUnlock` seam with
+ * a toast queue and render one of these per entry.
+ *
+ * @capability achievement-toast unlock-moment banner (icon, heading, name, points) for an achievement toast queue
+ */
+export declare function AchievementToast({ name, description, icon, points, heading, className, style, }: AchievementToastProps): ReactNode;
+/** Props for {@link AchievementGallery}. */
+export interface AchievementGalleryProps {
+    achievements: readonly AchievementView[];
+    title?: string;
+    /** Render secret + still-locked achievements as masked "???". Default true. */
+    maskSecrets?: boolean;
+    /** Optional per-achievement icon; falls back to the def `icon` glyph then a lock/trophy. */
+    renderIcon?: (achievement: AchievementView) => ReactNode;
+    columns?: number;
+    emptyLabel?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Achievement/trophy gallery — a responsive grid of cards showing unlocked vs.
+ * locked state, a progress bar for counter achievements, and a header summary
+ * of completion and score. Secret+locked entries mask their name/description.
+ * Feed it `useAchievements(tracker)`.
+ *
+ * @capability achievement-gallery responsive achievement/trophy grid with unlocked/locked state, counter progress bars, secret masking, and a completion/score header
+ */
+export declare function AchievementGallery({ achievements, title, maskSecrets, renderIcon, columns, emptyLabel, className, style, }: AchievementGalleryProps): ReactNode;

package/dist/achievements.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+/**
+ * Subscribe a component to an achievement tracker's live view list. The list
+ * keeps a stable identity between changes, so this re-renders only on unlock or
+ * progress — not every frame.
+ */
+export function useAchievements(tracker) {
+    return useSyncExternalStore(tracker.subscribe, tracker.list, tracker.list);
+}
+/**
+ * The unlock-moment banner — icon, "Achievement Unlocked" heading, name, and
+ * optional points. Purely presentational; pair the game's `onUnlock` seam with
+ * a toast queue and render one of these per entry.
+ *
+ * @capability achievement-toast unlock-moment banner (icon, heading, name, points) for an achievement toast queue
+ */
+export function AchievementToast({ name, description, icon, points, heading = "Achievement Unlocked", className, style, }) {
+    return (_jsxs("div", { className: className, "data-achievement-toast": true, style: {
+            display: "flex",
+            alignItems: "center",
+            gap: 12,
+            minWidth: 240,
+            padding: "10px 14px",
+            borderRadius: 12,
+            background: "linear-gradient(160deg, rgba(30,26,14,0.96), rgba(16,13,8,0.96))",
+            border: "1px solid var(--jg-rarity-legendary, rgba(245,158,11,0.55))",
+            boxShadow: "0 12px 34px rgba(0,0,0,0.5)",
+            color: "#f8fafc",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            ...style,
+        }, children: [_jsx("div", { "data-achievement-toast-icon": true, style: {
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    width: 40,
+                    height: 40,
+                    borderRadius: 10,
+                    background: "rgba(245,158,11,0.16)",
+                    border: "1px solid rgba(245,158,11,0.4)",
+                    fontSize: 20,
+                    flexShrink: 0,
+                }, children: icon ?? "🏆" }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 1, minWidth: 0 }, children: [_jsx("span", { style: { fontSize: 9, letterSpacing: 1.6, textTransform: "uppercase", color: "rgba(245,158,11,0.85)" }, children: heading }), _jsx("span", { style: { fontSize: 14, fontWeight: 700, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }, children: name }), description !== undefined ? (_jsx("span", { style: { fontSize: 11, color: "rgba(226,232,240,0.7)" }, children: description })) : null] }), points !== undefined ? (_jsx("span", { style: { marginLeft: "auto", fontSize: 13, fontWeight: 700, color: "var(--jg-rarity-legendary, #f59e0b)", fontVariantNumeric: "tabular-nums" }, children: points })) : null] }));
+}
+const MASK = "???";
+/**
+ * Achievement/trophy gallery — a responsive grid of cards showing unlocked vs.
+ * locked state, a progress bar for counter achievements, and a header summary
+ * of completion and score. Secret+locked entries mask their name/description.
+ * Feed it `useAchievements(tracker)`.
+ *
+ * @capability achievement-gallery responsive achievement/trophy grid with unlocked/locked state, counter progress bars, secret masking, and a completion/score header
+ */
+export function AchievementGallery({ achievements, title = "Achievements", maskSecrets = true, renderIcon, columns = 2, emptyLabel = "No achievements yet.", className, style, }) {
+    const unlockedCount = achievements.filter((a) => a.unlocked).length;
+    const score = achievements.reduce((sum, a) => sum + (a.unlocked ? a.points ?? 0 : 0), 0);
+    const hasPoints = achievements.some((a) => a.points !== undefined);
+    return (_jsxs("div", { className: className, "data-achievement-gallery": true, style: {
+            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.3))",
+            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: [unlockedCount, "/", achievements.length, hasPoints ? ` · ${score} pts` : ""] })] }), achievements.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(${Math.max(1, columns)}, minmax(0, 1fr))`,
+                    gap: 8,
+                }, children: achievements.map((achievement) => {
+                    const masked = maskSecrets && achievement.secret === true && !achievement.unlocked;
+                    const name = masked ? MASK : achievement.name;
+                    const description = masked ? "Hidden achievement" : achievement.description;
+                    const showProgress = !achievement.unlocked && achievement.target !== undefined && achievement.target > 0;
+                    const icon = renderIcon?.(achievement) ?? (masked ? "🔒" : achievement.icon ?? (achievement.unlocked ? "🏆" : "◻"));
+                    return (_jsxs("li", { "data-achievement": achievement.id, "data-unlocked": achievement.unlocked, style: {
+                            display: "flex",
+                            gap: 10,
+                            padding: 10,
+                            borderRadius: 10,
+                            background: achievement.unlocked ? "rgba(245,158,11,0.10)" : "rgba(148,163,184,0.06)",
+                            border: `1px solid ${achievement.unlocked ? "rgba(245,158,11,0.4)" : "rgba(148,163,184,0.18)"}`,
+                            opacity: achievement.unlocked ? 1 : 0.75,
+                        }, children: [_jsx("div", { style: { fontSize: 20, width: 26, textAlign: "center", flexShrink: 0 }, children: icon }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 2, minWidth: 0, flex: 1 }, children: [_jsxs("span", { style: { fontSize: 13, fontWeight: 700, color: achievement.unlocked ? "#f8fafc" : "rgba(226,232,240,0.85)" }, children: [name, achievement.points !== undefined && !masked ? (_jsx("span", { style: { marginLeft: 6, fontSize: 10, color: "rgba(245,158,11,0.85)", fontWeight: 600 }, children: achievement.points })) : null] }), description !== undefined ? (_jsx("span", { style: { fontSize: 11, color: "rgba(203,213,225,0.7)" }, children: description })) : null, showProgress ? (_jsx("div", { "data-achievement-progress": true, style: { marginTop: 3, height: 5, borderRadius: 9999, background: "rgba(148,163,184,0.2)", overflow: "hidden" }, children: _jsx("div", { style: {
+                                                width: `${Math.round(achievement.fraction * 100)}%`,
+                                                height: "100%",
+                                                borderRadius: 9999,
+                                                background: "var(--jg-accent, #f59e0b)",
+                                            } }) })) : null] })] }, achievement.id));
+                }) }))] }));
+}

package/dist/cameraShake.d.ts

@@ -0,0 +1,52 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { CameraShakeController } from "@jgengine/core/vfx/cameraShake";
+import { type HudFrameVariation } from "./hudFrame.js";
+/** A live read of a camera-shake controller: current trauma `0..1` and the last game-owned `kind`. */
+export interface CameraShakeReadout {
+    /** Current trauma in `[0, 1]`. */
+    trauma: number;
+    /** The last free-string `kind` handed to the controller, or `undefined`. */
+    kind: string | undefined;
+}
+/**
+ * Subscribe to a camera-shake controller and re-render on every change (add /
+ * decay / clear). Optionally drives `update()` on an animation frame so the trauma
+ * meter bleeds down live even when no game loop ticks the controller. Returns the
+ * current trauma + kind for a HUD readout.
+ *
+ * @capability use-camera-shake React hook binding a camera-shake controller — subscribes for live trauma/kind and can self-drive its decay on a frame loop
+ */
+export declare function useCameraShake(controller: CameraShakeController, animate?: boolean): CameraShakeReadout;
+/** Props for {@link CameraShakeMeter}. */
+export interface CameraShakeMeterProps {
+    /** The controller to read. */
+    controller: CameraShakeController;
+    /**
+     * Drive the controller's decay on an animation frame so the meter bleeds down
+     * live. Default `false` — leave off when a shell consumer already ticks
+     * `update()` each frame (the usual case), on to make the panel self-sufficient.
+     */
+    animate?: boolean;
+    /** Header label. Default `"CAMERA SHAKE"`. */
+    title?: string;
+    /**
+     * Human labels per game-owned `kind`, so the readout can show "Explosion" for a
+     * `"explosion"` impact. The model never interprets `kind`; this is pure display.
+     */
+    kindLabels?: Record<string, string>;
+    /** Frame skin. Default `"glass"`. */
+    variation?: HudFrameVariation;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A drop-in HUD panel that visualizes a core {@link CameraShakeController}: a
+ * trauma meter (reusing the shared {@link StaminaBar} building block) plus a live
+ * percentage and the current impact `kind` label. Presentation only — it reads the
+ * controller and never interprets `kind`, mapping it through `kindLabels` for
+ * display. A shell component applies the same controller's `offset()` to the
+ * camera; this panel is the on-screen readout of how much shake is in flight.
+ *
+ * @capability camera-shake-meter HUD readout for a core camera-shake controller — a trauma meter plus current impact-kind label, reskinnable and kind-labelled
+ */
+export declare function CameraShakeMeter({ controller, animate, title, kindLabels, variation, className, style, }: CameraShakeMeterProps): ReactNode;

package/dist/cameraShake.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer, useRef } from "react";
+import { StaminaBar } from "./bars.js";
+import { HudFrame } from "./hudFrame.js";
+/**
+ * Subscribe to a camera-shake controller and re-render on every change (add /
+ * decay / clear). Optionally drives `update()` on an animation frame so the trauma
+ * meter bleeds down live even when no game loop ticks the controller. Returns the
+ * current trauma + kind for a HUD readout.
+ *
+ * @capability use-camera-shake React hook binding a camera-shake controller — subscribes for live trauma/kind and can self-drive its decay on a frame loop
+ */
+export function useCameraShake(controller, animate = true) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    const rafRef = useRef(0);
+    useEffect(() => controller.subscribe(bump), [controller]);
+    useEffect(() => {
+        if (!animate)
+            return;
+        let running = true;
+        let last = performance.now();
+        const loop = () => {
+            if (!running)
+                return;
+            const nowMs = performance.now();
+            controller.update((nowMs - last) / 1000);
+            last = nowMs;
+            rafRef.current = requestAnimationFrame(loop);
+        };
+        rafRef.current = requestAnimationFrame(loop);
+        return () => {
+            running = false;
+            cancelAnimationFrame(rafRef.current);
+        };
+    }, [controller, animate]);
+    return { trauma: controller.trauma(), kind: controller.kind() };
+}
+/**
+ * A drop-in HUD panel that visualizes a core {@link CameraShakeController}: a
+ * trauma meter (reusing the shared {@link StaminaBar} building block) plus a live
+ * percentage and the current impact `kind` label. Presentation only — it reads the
+ * controller and never interprets `kind`, mapping it through `kindLabels` for
+ * display. A shell component applies the same controller's `offset()` to the
+ * camera; this panel is the on-screen readout of how much shake is in flight.
+ *
+ * @capability camera-shake-meter HUD readout for a core camera-shake controller — a trauma meter plus current impact-kind label, reskinnable and kind-labelled
+ */
+export function CameraShakeMeter({ controller, animate = false, title = "CAMERA SHAKE", kindLabels, variation = "glass", className, style, }) {
+    const { trauma, kind } = useCameraShake(controller, animate);
+    const pct = Math.round(trauma * 100);
+    const kindLabel = kind === undefined ? "—" : kindLabels?.[kind] ?? kind;
+    return (_jsx(HudFrame, { className: className, variation: variation, title: title, aside: _jsxs("span", { style: { fontVariantNumeric: "tabular-nums", opacity: 0.85 }, children: [pct, "%"] }), padding: 12, width: 240, style: style, children: _jsxs("div", { "data-camera-shake-meter": "", style: { display: "flex", flexDirection: "column", gap: 8 }, children: [_jsx(StaminaBar, { value: pct, max: 100, label: "TRAUMA", fill: "#f97316", showValue: false, width: "100%" }), _jsxs("div", { "data-camera-shake-kind": kind ?? "", style: { display: "flex", justifyContent: "space-between", fontSize: 12, opacity: 0.85 }, children: [_jsx("span", { style: { textTransform: "uppercase", letterSpacing: 0.4, opacity: 0.7 }, children: "Last impact" }), _jsx("span", { style: { fontWeight: 700 }, children: kindLabel })] })] }) }));
+}

package/dist/coachMarks.d.ts

@@ -0,0 +1,72 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { CoachMarkSequence, CoachMarkView } from "@jgengine/core/ui/coachMarks";
+/**
+ * Subscribe to a coach-mark sequence and re-render on every change, returning the
+ * current step view (or `null` when the tour is complete or waiting on a gate).
+ *
+ * @capability use-coach-marks React hook binding a coach-mark sequence to a component — re-renders on advance/skip/gate changes
+ */
+export declare function useCoachMarks(sequence: CoachMarkSequence): CoachMarkView | null;
+/** Reskin tokens for {@link CoachMarkHost} / {@link CoachMark}. */
+export interface CoachMarkTheme {
+    /** Accent for the counter, Next button, and pointer. Default reads `--jg-accent`. */
+    accent?: string;
+    /** Callout background. */
+    background?: string;
+    /** Callout text color. */
+    text?: string;
+    /** Dim color for the backdrop / spotlight. */
+    backdrop?: string;
+    /** Callout corner radius (px). */
+    radius?: number;
+}
+/** Props for {@link CoachMark}. */
+export interface CoachMarkProps {
+    /** The step view to render (from `sequence.current()` / {@link useCoachMarks}). */
+    view: CoachMarkView;
+    /** Absolute-position style computed for the callout (see {@link CoachMarkHost}). */
+    positionStyle?: CSSProperties;
+    onNext: () => void;
+    onSkip: () => void;
+    nextLabel?: string;
+    doneLabel?: string;
+    skipLabel?: string;
+    theme?: CoachMarkTheme;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A single coach-mark callout — title, body, an "N of M" counter, a Next/Got-it
+ * button, and a Skip-tour link. Presentation-only; position it with
+ * `positionStyle` or drop it into {@link CoachMarkHost}. Reskin via {@link CoachMarkTheme}.
+ *
+ * @capability coach-mark single onboarding callout — title/body, N-of-M counter, Next + Skip controls, theme-reskinnable
+ */
+export declare function CoachMark({ view, positionStyle, onNext, onSkip, nextLabel, doneLabel, skipLabel, theme, className, style, }: CoachMarkProps): ReactNode;
+/** Props for {@link CoachMarkHost}. */
+export interface CoachMarkHostProps {
+    /** The sequence to drive. */
+    sequence: CoachMarkSequence;
+    /** Resolve a step's `anchor` string to a DOM element. Default: `document.querySelector`. */
+    resolveAnchor?: (anchor: string) => Element | null;
+    /** Dim the rest of the screen and spotlight the anchor. Default `true`. */
+    showBackdrop?: boolean;
+    /** Fired the first time the tour reports complete (no eligible step). */
+    onComplete?: () => void;
+    nextLabel?: string;
+    doneLabel?: string;
+    skipLabel?: string;
+    theme?: CoachMarkTheme;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Full-screen coach-mark host: watches a sequence, positions the current step's
+ * callout beside its anchored element (or centered when unanchored) via
+ * `getBoundingClientRect`, and draws an optional dimmed backdrop with a spotlight
+ * cutout around the anchor. Next advances, Skip ends the tour — both persist so
+ * hints never re-show. Reskin with {@link CoachMarkTheme}.
+ *
+ * @capability coach-mark-host full-screen onboarding coach-mark host — anchored/centered callout, dimmed spotlight backdrop, Next/Skip wired to the sequence
+ */
+export declare function CoachMarkHost({ sequence, resolveAnchor, showBackdrop, onComplete, nextLabel, doneLabel, skipLabel, theme, className, style, }: CoachMarkHostProps): ReactNode;

package/dist/coachMarks.js

@@ -0,0 +1,136 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useReducer, useState } from "react";
+/**
+ * Subscribe to a coach-mark sequence and re-render on every change, returning the
+ * current step view (or `null` when the tour is complete or waiting on a gate).
+ *
+ * @capability use-coach-marks React hook binding a coach-mark sequence to a component — re-renders on advance/skip/gate changes
+ */
+export function useCoachMarks(sequence) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => sequence.subscribe(bump), [sequence]);
+    return sequence.current();
+}
+function resolveTheme(theme) {
+    return {
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        background: theme?.background ?? "linear-gradient(160deg, rgba(20,24,32,0.98), rgba(11,14,19,0.98))",
+        text: theme?.text ?? "#e2e8f0",
+        backdrop: theme?.backdrop ?? "rgba(4,7,12,0.62)",
+        radius: theme?.radius ?? 14,
+    };
+}
+const CALLOUT_WIDTH = 288;
+const GAP = 14;
+function calloutStyle(rect, placement) {
+    if (rect === null || placement === "center") {
+        return { top: "50%", left: "50%", transform: "translate(-50%, -50%)" };
+    }
+    switch (placement) {
+        case "top":
+            return { top: rect.top - GAP, left: rect.left + rect.width / 2, transform: "translate(-50%, -100%)" };
+        case "left":
+            return { top: rect.top + rect.height / 2, left: rect.left - GAP, transform: "translate(-100%, -50%)" };
+        case "right":
+            return { top: rect.top + rect.height / 2, left: rect.right + GAP, transform: "translate(0, -50%)" };
+        case "bottom":
+        default:
+            return { top: rect.bottom + GAP, left: rect.left + rect.width / 2, transform: "translate(-50%, 0)" };
+    }
+}
+/**
+ * A single coach-mark callout — title, body, an "N of M" counter, a Next/Got-it
+ * button, and a Skip-tour link. Presentation-only; position it with
+ * `positionStyle` or drop it into {@link CoachMarkHost}. Reskin via {@link CoachMarkTheme}.
+ *
+ * @capability coach-mark single onboarding callout — title/body, N-of-M counter, Next + Skip controls, theme-reskinnable
+ */
+export function CoachMark({ view, positionStyle, onNext, onSkip, nextLabel = "Next", doneLabel = "Got it", skipLabel = "Skip tour", theme, className, style, }) {
+    const t = resolveTheme(theme);
+    const last = view.remaining <= 1;
+    return (_jsxs("div", { className: className, "data-coach-mark": view.step.id, style: {
+            position: "fixed",
+            width: CALLOUT_WIDTH,
+            maxWidth: "calc(100vw - 24px)",
+            boxSizing: "border-box",
+            padding: 16,
+            borderRadius: t.radius,
+            background: t.background,
+            border: "1px solid var(--jg-ring, rgba(148,163,184,0.32))",
+            color: t.text,
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            boxShadow: "0 20px 50px rgba(0,0,0,0.55)",
+            pointerEvents: "auto",
+            ...positionStyle,
+            ...style,
+        }, children: [_jsxs("div", { "data-coach-mark-counter": true, style: { fontSize: 10, letterSpacing: 1.4, textTransform: "uppercase", fontWeight: 700, color: t.accent }, children: [view.index + 1, " of ", view.total] }), _jsx("div", { "data-coach-mark-title": true, style: { marginTop: 6, fontSize: 15, fontWeight: 700 }, children: view.step.title }), view.step.body !== undefined ? (_jsx("p", { "data-coach-mark-body": true, style: { margin: "6px 0 0", fontSize: 12.5, lineHeight: 1.5, color: "rgba(203,213,225,0.85)" }, children: view.step.body })) : null, _jsxs("div", { style: { marginTop: 14, display: "flex", alignItems: "center", justifyContent: "space-between", gap: 10 }, children: [_jsx("button", { type: "button", "data-coach-mark-skip": true, onClick: onSkip, style: {
+                            border: "none",
+                            background: "transparent",
+                            color: "rgba(148,163,184,0.85)",
+                            fontSize: 11.5,
+                            cursor: "pointer",
+                            padding: 0,
+                            textDecoration: "underline",
+                        }, children: skipLabel }), _jsx("button", { type: "button", "data-coach-mark-next": true, onClick: onNext, style: {
+                            border: "1px solid transparent",
+                            borderRadius: 8,
+                            background: t.accent,
+                            color: "#06121b",
+                            fontSize: 12.5,
+                            fontWeight: 700,
+                            padding: "6px 14px",
+                            cursor: "pointer",
+                        }, children: last ? doneLabel : nextLabel })] })] }));
+}
+/**
+ * Full-screen coach-mark host: watches a sequence, positions the current step's
+ * callout beside its anchored element (or centered when unanchored) via
+ * `getBoundingClientRect`, and draws an optional dimmed backdrop with a spotlight
+ * cutout around the anchor. Next advances, Skip ends the tour — both persist so
+ * hints never re-show. Reskin with {@link CoachMarkTheme}.
+ *
+ * @capability coach-mark-host full-screen onboarding coach-mark host — anchored/centered callout, dimmed spotlight backdrop, Next/Skip wired to the sequence
+ */
+export function CoachMarkHost({ sequence, resolveAnchor, showBackdrop = true, onComplete, nextLabel, doneLabel, skipLabel, theme, className, style, }) {
+    const view = useCoachMarks(sequence);
+    const [rect, setRect] = useState(null);
+    const anchor = view?.step.anchor;
+    const stepId = view?.step.id;
+    useLayoutEffect(() => {
+        if (view === null && onComplete !== undefined && sequence.isComplete())
+            onComplete();
+    }, [view, onComplete, sequence]);
+    useLayoutEffect(() => {
+        if (anchor === undefined || typeof document === "undefined") {
+            setRect(null);
+            return;
+        }
+        const resolve = resolveAnchor ?? ((selector) => document.querySelector(selector));
+        const measure = () => {
+            const el = resolve(anchor);
+            setRect(el !== null ? el.getBoundingClientRect() : null);
+        };
+        measure();
+        window.addEventListener("resize", measure);
+        window.addEventListener("scroll", measure, true);
+        return () => {
+            window.removeEventListener("resize", measure);
+            window.removeEventListener("scroll", measure, true);
+        };
+    }, [anchor, stepId, resolveAnchor]);
+    if (view === null)
+        return null;
+    const t = resolveTheme(theme);
+    const placement = view.step.placement ?? (view.step.anchor !== undefined ? "bottom" : "center");
+    const spotlight = showBackdrop && rect !== null;
+    return (_jsxs("div", { className: className, "data-coach-mark-host": true, style: { position: "fixed", inset: 0, zIndex: 60, pointerEvents: "none", ...style }, children: [showBackdrop ? (spotlight ? (_jsx("div", { "data-coach-mark-spotlight": true, style: {
+                    position: "fixed",
+                    top: rect.top - 6,
+                    left: rect.left - 6,
+                    width: rect.width + 12,
+                    height: rect.height + 12,
+                    borderRadius: 10,
+                    boxShadow: `0 0 0 9999px ${t.backdrop}`,
+                    pointerEvents: "auto",
+                } })) : (_jsx("div", { "data-coach-mark-backdrop": true, style: { position: "fixed", inset: 0, background: t.backdrop, pointerEvents: "auto" } }))) : null, _jsx(CoachMark, { view: view, positionStyle: calloutStyle(rect, placement), onNext: () => sequence.advance(), onSkip: () => sequence.skipAll(), nextLabel: nextLabel, doneLabel: doneLabel, skipLabel: skipLabel, theme: theme })] }));
+}

package/dist/codex.d.ts

@@ -0,0 +1,25 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { CodexEntryView } from "@jgengine/core/game/codex";
+/** Props for {@link Codex}. */
+export interface CodexProps {
+    entries: readonly CodexEntryView[];
+    title?: string;
+    columns?: number;
+    /** Mask name/description of secret + undiscovered entries as "???". Default true. */
+    maskSecrets?: boolean;
+    /** Optional per-entry icon; falls back to the def `icon` glyph, a lock, or a silhouette dot. */
+    renderIcon?: (entry: CodexEntryView) => ReactNode;
+    onSelect?: (id: string) => void;
+    emptyLabel?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * 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 declare function Codex({ entries, title, columns, maskSecrets, renderIcon, onSelect, emptyLabel, className, style, }: CodexProps): ReactNode;