@jgengine/react 0.13.0 → 0.15.0-next.0

package/dist/modals.js

@@ -0,0 +1,168 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useReducer, useRef, } from "react";
+import { MODAL_CANCEL, MODAL_CONFIRM, } from "@jgengine/core/ui/modalStack";
+import { HudFrame } from "./hudFrame.js";
+/**
+ * Subscribe to a modal stack and re-render on every change, returning the active modal and depth.
+ *
+ * @capability use-modal-stack React hook binding a modal stack to a component — re-renders on push/pop/resolve
+ */
+export function useModalStack(stack) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => stack.subscribe(bump), [stack]);
+    return { top: stack.top(), depth: stack.depth() };
+}
+/** @internal Focusable descendants of `root`, in DOM order, skipping disabled/hidden ones. */
+function focusableWithin(root) {
+    const selector = 'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+    return Array.from(root.querySelectorAll(selector)).filter((el) => el.offsetParent !== null || el === document.activeElement);
+}
+/**
+ * Full-screen modal host: watches a stack, renders only the topmost modal centered over a dimmed
+ * backdrop, and manages accessibility — the panel is a `role="dialog" aria-modal`, focus moves into
+ * it on open and is trapped with Tab/Shift+Tab cycling, Escape and (optionally) a backdrop click
+ * cancel the top modal, and focus returns to the previously focused element on close. It renders
+ * nothing when the stack is empty. Skin the panel and backdrop via `HudTheme` tokens.
+ *
+ * @capability modal-host full-screen modal/dialog host over a modal stack — dimmed backdrop, focus trap, Esc/backdrop-to-cancel, aria-modal dialog
+ */
+export function ModalHost({ stack, children, showBackdrop = true, backdrop, closeOnBackdrop = true, closeOnEsc = true, zIndexBase = 80, className, style, }) {
+    const { top } = useModalStack(stack);
+    const panelRef = useRef(null);
+    const restoreRef = useRef(null);
+    const stepId = top?.id ?? null;
+    const controls = {
+        resolve: useCallback((result, payload) => stack.resolve(result, payload !== undefined ? { payload } : undefined), [stack]),
+        confirm: useCallback((payload) => stack.resolve(MODAL_CONFIRM, payload !== undefined ? { payload } : undefined), [stack]),
+        cancel: useCallback(() => stack.resolve(MODAL_CANCEL), [stack]),
+    };
+    // Move focus into the dialog on open; restore it on close.
+    useEffect(() => {
+        if (stepId === null || typeof document === "undefined")
+            return undefined;
+        restoreRef.current = document.activeElement;
+        const panel = panelRef.current;
+        if (panel !== null) {
+            const first = focusableWithin(panel)[0] ?? panel;
+            first.focus();
+        }
+        return () => {
+            restoreRef.current?.focus?.();
+        };
+    }, [stepId]);
+    if (top === null)
+        return null;
+    const dim = backdrop ?? "var(--jg-backdrop, rgba(4,7,12,0.62))";
+    const onKeyDown = (event) => {
+        if (closeOnEsc && event.key === "Escape") {
+            event.stopPropagation();
+            controls.cancel();
+            return;
+        }
+        if (event.key !== "Tab")
+            return;
+        const panel = panelRef.current;
+        if (panel === null)
+            return;
+        const focusable = focusableWithin(panel);
+        if (focusable.length === 0) {
+            event.preventDefault();
+            return;
+        }
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+        const active = document.activeElement;
+        if (event.shiftKey && active === first) {
+            event.preventDefault();
+            last.focus();
+        }
+        else if (!event.shiftKey && active === last) {
+            event.preventDefault();
+            first.focus();
+        }
+    };
+    return (_jsxs("div", { "data-modal-host": "", className: className, onKeyDown: onKeyDown, style: {
+            position: "fixed",
+            inset: 0,
+            zIndex: zIndexBase,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            pointerEvents: "auto",
+            ...style,
+        }, children: [showBackdrop ? (_jsx("div", { "data-modal-backdrop": "", onClick: closeOnBackdrop ? () => controls.cancel() : undefined, style: { position: "fixed", inset: 0, background: dim } })) : null, _jsx("div", { ref: panelRef, role: "dialog", "aria-modal": true, "aria-label": typeof top.payload === "object" && top.payload !== null && "title" in top.payload ? String(top.payload.title ?? top.kind) : top.kind, "data-modal": top.kind, "data-modal-id": top.id, tabIndex: -1, style: { position: "relative", pointerEvents: "auto", outline: "none", maxWidth: "calc(100vw - 32px)", maxHeight: "calc(100vh - 32px)" }, children: children(top, controls) })] }));
+}
+const DIALOG_TITLE = { margin: 0, fontSize: 17, fontWeight: 700, letterSpacing: 0.2 };
+const DIALOG_BODY = { margin: "10px 0 0", fontSize: 13.5, lineHeight: 1.55, color: "rgba(226,232,240,0.82)" };
+const BUTTON_ROW = { display: "flex", gap: 10, marginTop: 20, justifyContent: "flex-end" };
+const BUTTON_BASE = {
+    appearance: "none",
+    borderRadius: "var(--jg-slot-radius, 8px)",
+    border: "1px solid transparent",
+    fontSize: 13,
+    fontWeight: 600,
+    padding: "8px 16px",
+    cursor: "pointer",
+    font: "inherit",
+};
+function primaryButtonStyle(danger) {
+    return {
+        ...BUTTON_BASE,
+        background: danger ? "#e5484d" : "var(--jg-accent, #38bdf8)",
+        color: danger ? "#fff" : "#06121b",
+    };
+}
+const GHOST_BUTTON = {
+    ...BUTTON_BASE,
+    background: "var(--jg-slot-bg, rgba(148,163,184,0.12))",
+    color: "var(--jg-bar-text, #e2e8f0)",
+    border: "var(--jg-slot-border, 1px solid rgba(148,163,184,0.28))",
+};
+/**
+ * A generic two-button confirmation dialog — title, optional body, and Cancel / Confirm buttons over
+ * a `HudTheme`-token-driven {@link HudFrame}. Presentation-only: wire `onConfirm`/`onCancel` to a
+ * modal stack's `resolve` (typically inside a {@link ModalHost} render callback) and reskin via
+ * `HudTheme` tokens or `danger` for a destructive action. It interprets nothing — the game supplies
+ * the copy.
+ *
+ * @capability confirm-dialog generic themeable confirm/cancel dialog — title, body, two buttons, danger styling
+ */
+export function ConfirmDialog({ title, body, confirmLabel = "Confirm", cancelLabel = "Cancel", onConfirm, onCancel, danger = false, width = 360, className, style, }) {
+    return (_jsxs(HudFrame, { variation: "themed", width: width, padding: 20, interactive: true, className: className, style: style, children: [_jsx("h2", { "data-confirm-title": "", style: DIALOG_TITLE, children: title }), body !== undefined ? _jsx("p", { "data-confirm-body": "", style: DIALOG_BODY, children: body }) : null, _jsxs("div", { style: BUTTON_ROW, children: [_jsx("button", { type: "button", "data-confirm-cancel": "", onClick: onCancel, style: GHOST_BUTTON, children: cancelLabel }), _jsx("button", { type: "button", "data-confirm-accept": "", onClick: onConfirm, style: primaryButtonStyle(danger), children: confirmLabel })] })] }));
+}
+const PAUSE_TITLE = {
+    margin: "0 0 14px",
+    fontSize: 12,
+    fontWeight: 700,
+    letterSpacing: 2,
+    textTransform: "uppercase",
+    textAlign: "center",
+    color: "var(--jg-accent, #38bdf8)",
+};
+const PAUSE_ITEM_BASE = {
+    ...BUTTON_BASE,
+    display: "block",
+    width: "100%",
+    textAlign: "center",
+    padding: "10px 16px",
+    marginTop: 8,
+};
+/**
+ * A reskinnable pause-menu building block: a primary Resume button plus a game-filled list of slot
+ * items (Settings, Save, Quit, …), stacked in a `HudTheme`-token-driven {@link HudFrame}. It ships
+ * the common shape every game's pause screen needs and nothing genre-specific — the game supplies the
+ * title, item labels/order, and destructive styling, and reskins with `HudTheme` tokens. Drop it into
+ * a {@link ModalHost} keyed on a `"pause"` modal, or render it standalone.
+ *
+ * @capability pause-menu reskinnable pause-menu building block — Resume plus a game-filled Settings/Quit slot list, HudTheme-driven
+ */
+export function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }) {
+    return (_jsxs(HudFrame, { variation: "themed", width: width, padding: 20, interactive: true, className: className, style: style, children: [_jsx("div", { "data-pause-title": "", style: PAUSE_TITLE, children: title }), _jsx("button", { type: "button", "data-pause-resume": "", onClick: onResume, style: { ...PAUSE_ITEM_BASE, ...primaryButtonStyle(false), marginTop: 0 }, children: resumeLabel }), items.map((item) => (_jsx("button", { type: "button", "data-pause-item": item.id, onClick: item.onSelect, disabled: item.disabled, style: {
+                    ...PAUSE_ITEM_BASE,
+                    ...(item.danger
+                        ? { background: "transparent", color: "#f0787c", border: "1px solid rgba(229,72,77,0.5)" }
+                        : GHOST_BUTTON),
+                    opacity: item.disabled === true ? 0.5 : 1,
+                    cursor: item.disabled === true ? "not-allowed" : "pointer",
+                }, children: item.label }, item.id)))] }));
+}

package/dist/notifications.d.ts

@@ -0,0 +1,39 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { NotificationEntry, NotificationStore } from "@jgengine/core/game/notifications";
+/** Subscribe to a notification store's live list. */
+export declare function useNotifications<TMeta = unknown>(store: NotificationStore<TMeta>): readonly NotificationEntry<TMeta>[];
+/** Props for {@link NotificationBell}. */
+export interface NotificationBellProps {
+    store: NotificationStore;
+    onClick?: () => void;
+    icon?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Notification bell — an icon button with an unread-count badge, bound to a
+ * notification store. Toggle a {@link NotificationCenter} panel from its click.
+ *
+ * @capability notification-bell icon button with a live unread-count badge over a notification store
+ */
+export declare function NotificationBell({ store, onClick, icon, className, style }: NotificationBellProps): ReactNode;
+/** Props for {@link NotificationCenter}. */
+export interface NotificationCenterProps {
+    store: NotificationStore;
+    title?: string;
+    emptyLabel?: string;
+    onClose?: () => void;
+    /** Format an entry's timestamp; default is a relative "2m ago" using the current time. */
+    formatTime?: (at: number) => string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Notification center panel — the scrollable log toasts don't provide: newest
+ * notifications with a kind-colored marker, title/body, relative time, and an
+ * unread highlight; a header with the unread count, mark-all-read, and clear.
+ * Clicking an entry marks it read. Bind it to a `createNotificationCenter`.
+ *
+ * @capability notification-center-panel scrollable notification log with kind markers, read tracking, relative time, and mark-all-read/clear
+ */
+export declare function NotificationCenter({ store, title, emptyLabel, onClose, formatTime, className, style, }: NotificationCenterProps): ReactNode;

package/dist/notifications.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+/** Subscribe to a notification store's live list. */
+export function useNotifications(store) {
+    return useSyncExternalStore(store.subscribe, store.list, store.list);
+}
+const KIND_COLOR = {
+    info: "#38bdf8",
+    success: "#4ade80",
+    warning: "#f59e0b",
+    danger: "#ef4444",
+};
+function kindColor(kind) {
+    return KIND_COLOR[kind] ?? "var(--jg-accent, #94a3b8)";
+}
+function defaultRelativeTime(at, nowMs) {
+    const seconds = Math.max(0, Math.round((nowMs - at) / 1000));
+    if (seconds < 60)
+        return "just now";
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.round(hours / 24)}d ago`;
+}
+/**
+ * Notification bell — an icon button with an unread-count badge, bound to a
+ * notification store. Toggle a {@link NotificationCenter} panel from its click.
+ *
+ * @capability notification-bell icon button with a live unread-count badge over a notification store
+ */
+export function NotificationBell({ store, onClick, icon = "🔔", className, style }) {
+    const list = useNotifications(store);
+    const unread = list.reduce((count, entry) => (entry.read ? count : count + 1), 0);
+    return (_jsxs("button", { type: "button", className: className, "data-notification-bell": true, onClick: onClick, style: {
+            position: "relative",
+            width: 40,
+            height: 40,
+            borderRadius: 10,
+            border: "1px solid var(--jg-ring, rgba(148,163,184,0.3))",
+            background: "rgba(17,22,30,0.85)",
+            color: "#e2e8f0",
+            fontSize: 18,
+            cursor: "pointer",
+            ...style,
+        }, children: [icon, unread > 0 ? (_jsx("span", { "data-notification-badge": true, style: {
+                    position: "absolute",
+                    top: -6,
+                    right: -6,
+                    minWidth: 18,
+                    height: 18,
+                    padding: "0 4px",
+                    borderRadius: 9999,
+                    background: "#ef4444",
+                    color: "#fff",
+                    fontSize: 11,
+                    fontWeight: 700,
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                }, children: unread > 99 ? "99+" : unread })) : null] }));
+}
+/**
+ * Notification center panel — the scrollable log toasts don't provide: newest
+ * notifications with a kind-colored marker, title/body, relative time, and an
+ * unread highlight; a header with the unread count, mark-all-read, and clear.
+ * Clicking an entry marks it read. Bind it to a `createNotificationCenter`.
+ *
+ * @capability notification-center-panel scrollable notification log with kind markers, read tracking, relative time, and mark-all-read/clear
+ */
+export function NotificationCenter({ store, title = "Notifications", emptyLabel = "You're all caught up.", onClose, formatTime, className, style, }) {
+    const list = useNotifications(store);
+    const unread = list.reduce((count, entry) => (entry.read ? count : count + 1), 0);
+    const nowMs = typeof Date !== "undefined" ? Date.now() : 0;
+    const time = formatTime ?? ((at) => defaultRelativeTime(at, nowMs));
+    const headerButton = {
+        border: "1px solid rgba(148,163,184,0.4)",
+        borderRadius: 6,
+        background: "transparent",
+        color: "rgba(226,232,240,0.85)",
+        fontSize: 11,
+        padding: "3px 8px",
+        cursor: "pointer",
+    };
+    return (_jsxs("div", { className: className, "data-notification-center": true, style: {
+            width: 300,
+            maxHeight: 420,
+            display: "flex",
+            flexDirection: "column",
+            borderRadius: 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",
+            boxShadow: "0 18px 44px rgba(0,0,0,0.5)",
+            ...style,
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 8, padding: "10px 12px", borderBottom: "1px solid rgba(148,163,184,0.2)" }, children: [_jsxs("span", { style: { fontSize: 12, fontWeight: 700, letterSpacing: 1.2, textTransform: "uppercase" }, children: [title, unread > 0 ? _jsxs("span", { style: { marginLeft: 6, color: "#f87171" }, children: ["(", unread, ")"] }) : null] }), _jsxs("span", { style: { display: "flex", gap: 6 }, children: [_jsx("button", { type: "button", "data-notification-mark-all": true, style: headerButton, onClick: () => store.markAllRead(), children: "Mark all read" }), _jsx("button", { type: "button", "data-notification-clear": true, style: headerButton, onClick: () => store.clear(), children: "Clear" }), onClose !== undefined ? _jsx("button", { type: "button", style: headerButton, onClick: onClose, children: "\u2715" }) : null] })] }), list.length === 0 ? (_jsx("p", { style: { margin: 0, padding: "16px 12px", fontSize: 12, color: "rgba(148,163,184,0.8)" }, children: emptyLabel })) : (_jsx("ul", { style: { listStyle: "none", margin: 0, padding: 6, overflowY: "auto", display: "flex", flexDirection: "column", gap: 4 }, children: list.map((entry) => (_jsx("li", { children: _jsxs("button", { type: "button", "data-notification": entry.id, "data-kind": entry.kind, "data-read": entry.read, onClick: () => store.markRead(entry.id), style: {
+                            width: "100%",
+                            display: "flex",
+                            gap: 9,
+                            padding: "8px 9px",
+                            borderRadius: 9,
+                            border: "1px solid transparent",
+                            background: entry.read ? "transparent" : "rgba(56,189,248,0.08)",
+                            color: "#e2e8f0",
+                            textAlign: "left",
+                            cursor: "pointer",
+                        }, children: [_jsx("span", { style: { marginTop: 5, width: 8, height: 8, flexShrink: 0, borderRadius: 9999, background: kindColor(entry.kind) } }), _jsxs("span", { style: { display: "flex", flexDirection: "column", gap: 2, minWidth: 0, flex: 1 }, children: [_jsxs("span", { style: { display: "flex", justifyContent: "space-between", gap: 8 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: entry.read ? 500 : 700 }, children: entry.title }), _jsx("span", { style: { fontSize: 10, color: "rgba(148,163,184,0.7)", whiteSpace: "nowrap" }, children: time(entry.at) })] }), entry.body !== undefined ? (_jsx("span", { style: { fontSize: 11, color: "rgba(203,213,225,0.75)" }, children: entry.body })) : null] })] }) }, entry.id))) }))] }));
+}

package/dist/objectiveBanner.d.ts

@@ -0,0 +1,62 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { ObjectiveBannerController, ObjectiveBannerView } from "@jgengine/core/ui/objectiveBanner";
+/**
+ * Subscribe to a banner controller, drive its clock on an animation frame (unless
+ * the game already ticks it), and return the banner to draw right now — or `null`
+ * when idle. Re-renders every frame while a banner is animating.
+ *
+ * @capability use-objective-banner React hook binding an objective-banner controller — advances its clock per frame and returns the current banner view
+ */
+export declare function useObjectiveBanner(controller: ObjectiveBannerController, animate?: boolean): ObjectiveBannerView | null;
+/** Reskin tokens for {@link ObjectiveBannerHost}. Per-`kind` overrides layer on top. */
+export interface ObjectiveBannerTheme {
+    /** Accent for the title glow and the divider rule. Default reads `--jg-accent`. */
+    accent?: string;
+    /** Title text color. Default near-white. */
+    title?: string;
+    /** Subtitle text color. */
+    subtitle?: string;
+    /** Font family for the banner. */
+    fontFamily?: string;
+    /** Title font size (CSS length). Default `"clamp(2.5rem, 8vw, 6rem)"`. */
+    titleSize?: string;
+    /** Subtitle font size (CSS length). Default `"clamp(1rem, 2.5vw, 1.5rem)"`. */
+    subtitleSize?: string;
+}
+/** Props for {@link ObjectiveBannerHost}. */
+export interface ObjectiveBannerHostProps {
+    /** The controller to render. */
+    controller: ObjectiveBannerController;
+    /** Base reskin tokens. */
+    theme?: ObjectiveBannerTheme;
+    /**
+     * Per-`kind` theme overrides, keyed by the free-string `kind` a game announces
+     * with ("victory", "defeat", "wave", …). The matching entry layers over `theme`,
+     * so a game colors each banner variant without the model interpreting `kind`.
+     */
+    kindThemes?: Record<string, ObjectiveBannerTheme>;
+    /**
+     * Drive `advance()` on an animation frame. Default `true`. Turn off if the game
+     * already advances the controller from its own tick.
+     */
+    animate?: boolean;
+    /** Dismiss the active banner when the overlay is clicked. Default `false`. */
+    dismissOnClick?: boolean;
+    /** Extra `z-index` for the overlay root. Default `50`. */
+    zIndex?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A full-screen overlay that renders an {@link ObjectiveBannerController} as the
+ * classic transient centered title stamp — "WAVE 3", "VICTORY", "OBJECTIVE
+ * COMPLETE" — flying in, holding, and fading out. It subscribes to the model,
+ * drives `advance()` on an animation frame (unless the game ticks it), and maps the
+ * current banner's phase + progress to opacity/scale/translate. Reskin the base
+ * look with {@link ObjectiveBannerTheme} and color each variant via `kindThemes`
+ * keyed on the game-owned `kind`. Presentation only: all timing and queueing live
+ * in the core model, and `kind` is never interpreted here.
+ *
+ * @capability objective-banner-host full-screen overlay that renders a core objective-banner controller as a fly-in / hold / fade-out centered title + subtitle stamp, theme- and per-kind-skinnable
+ */
+export declare function ObjectiveBannerHost({ controller, theme, kindThemes, animate, dismissOnClick, zIndex, className, style, }: ObjectiveBannerHostProps): ReactNode;

package/dist/objectiveBanner.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useReducer, useRef } from "react";
+/**
+ * Subscribe to a banner controller, drive its clock on an animation frame (unless
+ * the game already ticks it), and return the banner to draw right now — or `null`
+ * when idle. Re-renders every frame while a banner is animating.
+ *
+ * @capability use-objective-banner React hook binding an objective-banner controller — advances its clock per frame and returns the current banner view
+ */
+export function useObjectiveBanner(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;
+        const loop = () => {
+            if (!running)
+                return;
+            controller.advance();
+            rafRef.current = requestAnimationFrame(loop);
+        };
+        rafRef.current = requestAnimationFrame(loop);
+        return () => {
+            running = false;
+            cancelAnimationFrame(rafRef.current);
+        };
+    }, [controller, animate]);
+    return controller.current();
+}
+function resolveTheme(theme) {
+    return {
+        accent: theme?.accent ?? "var(--jg-accent, #38bdf8)",
+        title: theme?.title ?? "#f8fafc",
+        subtitle: theme?.subtitle ?? "rgba(226,232,240,0.85)",
+        fontFamily: theme?.fontFamily ?? "ui-sans-serif, system-ui, sans-serif",
+        titleSize: theme?.titleSize ?? "clamp(2.5rem, 8vw, 6rem)",
+        subtitleSize: theme?.subtitleSize ?? "clamp(1rem, 2.5vw, 1.5rem)",
+    };
+}
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+/** Ease-out cubic for the fly-in so it decelerates into place. */
+function easeOut(t) {
+    return 1 - (1 - t) ** 3;
+}
+/**
+ * The animated transform + opacity for a banner from its phase and progress. The
+ * banner flies up into place on the way `in`, holds fully visible, then lifts and
+ * fades on the way `out`. Presentation-only — nothing here reads `kind`.
+ */
+function bannerMotion(phase, progress) {
+    switch (phase) {
+        case "in": {
+            const e = easeOut(progress);
+            return { opacity: progress, translateY: lerp(36, 0, e), scale: lerp(0.82, 1, e) };
+        }
+        case "hold":
+            return { opacity: 1, translateY: 0, scale: 1 };
+        case "out":
+        default:
+            return { opacity: 1 - progress, translateY: lerp(0, -22, progress), scale: lerp(1, 1.06, progress) };
+    }
+}
+/**
+ * A full-screen overlay that renders an {@link ObjectiveBannerController} as the
+ * classic transient centered title stamp — "WAVE 3", "VICTORY", "OBJECTIVE
+ * COMPLETE" — flying in, holding, and fading out. It subscribes to the model,
+ * drives `advance()` on an animation frame (unless the game ticks it), and maps the
+ * current banner's phase + progress to opacity/scale/translate. Reskin the base
+ * look with {@link ObjectiveBannerTheme} and color each variant via `kindThemes`
+ * keyed on the game-owned `kind`. Presentation only: all timing and queueing live
+ * in the core model, and `kind` is never interpreted here.
+ *
+ * @capability objective-banner-host full-screen overlay that renders a core objective-banner controller as a fly-in / hold / fade-out centered title + subtitle stamp, theme- and per-kind-skinnable
+ */
+export function ObjectiveBannerHost({ controller, theme, kindThemes, animate = true, dismissOnClick = false, zIndex = 50, className, style, }) {
+    const view = useObjectiveBanner(controller, animate);
+    if (view === null)
+        return null;
+    const merged = { ...theme, ...kindThemes?.[view.kind] };
+    const t = resolveTheme(merged);
+    const motion = bannerMotion(view.phase, view.progress);
+    return (_jsx("div", { className: className, "data-objective-banner-host": "", onClick: dismissOnClick ? () => controller.skip() : undefined, style: {
+            position: "absolute",
+            inset: 0,
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            justifyContent: "center",
+            pointerEvents: dismissOnClick ? "auto" : "none",
+            zIndex,
+            fontFamily: t.fontFamily,
+            textAlign: "center",
+            ...style,
+        }, children: _jsxs("div", { "data-objective-banner": view.id, "data-kind": view.kind, "data-phase": view.phase, style: {
+                display: "flex",
+                flexDirection: "column",
+                alignItems: "center",
+                gap: "0.5em",
+                opacity: motion.opacity,
+                transform: `translateY(${motion.translateY}px) scale(${motion.scale})`,
+                willChange: "opacity, transform",
+            }, children: [_jsx("div", { "data-objective-banner-title": "", style: {
+                        margin: 0,
+                        fontSize: t.titleSize,
+                        fontWeight: 900,
+                        letterSpacing: "0.06em",
+                        textTransform: "uppercase",
+                        lineHeight: 1,
+                        color: t.title,
+                        textShadow: `0 0 0.35em ${t.accent}, 0 4px 24px rgba(0,0,0,0.6)`,
+                    }, children: view.title }), _jsx("div", { "aria-hidden": "true", style: {
+                        width: "min(40vw, 320px)",
+                        height: 2,
+                        background: `linear-gradient(90deg, transparent, ${t.accent}, transparent)`,
+                        opacity: 0.9,
+                    } }), view.subtitle !== undefined ? (_jsx("div", { "data-objective-banner-subtitle": "", style: {
+                        margin: 0,
+                        fontSize: t.subtitleSize,
+                        fontWeight: 600,
+                        letterSpacing: "0.14em",
+                        textTransform: "uppercase",
+                        color: t.subtitle,
+                        textShadow: "0 2px 12px rgba(0,0,0,0.6)",
+                    }, children: view.subtitle })) : null] }) }));
+}

package/dist/panels.d.ts

@@ -61,9 +61,15 @@ export declare function usePanels(defs: readonly PanelDef[], options?: UsePanels
  * map). Accessible: every window is a `role="dialog"` with an `aria-label` and a focusable close button;
  * ESC-close is wired by the manager. Unskinned — art-direct via `HudTheme` tokens and the `variation`.
  *
- * @capability panel-host render a manager's open windows as draggable, closable, z-stacked dialogs
+ * The host establishes its own stacking context at `zIndexBase` (default 40) so windows always paint
+ * *above* the HUD (stat bars, nameplates, frames typically sit at z 10–30) — no game should have to
+ * rediscover "my vitals bar bleeds through the open window" and wrap this in a `z-*` of its own. Per-
+ * window focus order still resolves inside that context, so clicking a window raises it over its peers.
+ * Raise `zIndexBase` to sit above a full-screen modal, or lower it to tuck windows beneath one.
+ *
+ * @capability panel-host render a manager's open windows as draggable, closable, z-stacked dialogs above the HUD
  */
-export declare function PanelHost({ manager, render, panels, variation, shape, width, className, windowClassName, windowStyle, bodyStyle, }: {
+export declare function PanelHost({ manager, render, panels, variation, shape, width, zIndexBase, className, windowClassName, windowStyle, bodyStyle, }: {
     manager: PanelsManager;
     /** Content for a panel by id. Takes precedence over `panels`. */
     render?: (id: string) => ReactNode;
@@ -73,6 +79,8 @@ export declare function PanelHost({ manager, render, panels, variation, shape, w
     shape?: HudFrameShape;
     /** Default window width (per-panel unless overridden by the panel content). */
     width?: number | string;
+    /** z-index of the host's stacking context — the floor every window paints above. Default 40 (above the HUD). */
+    zIndexBase?: number;
     className?: string;
     windowClassName?: string;
     windowStyle?: CSSProperties;

package/dist/panels.js

@@ -186,12 +186,18 @@ function cascade(index) {
  * map). Accessible: every window is a `role="dialog"` with an `aria-label` and a focusable close button;
  * ESC-close is wired by the manager. Unskinned — art-direct via `HudTheme` tokens and the `variation`.
  *
- * @capability panel-host render a manager's open windows as draggable, closable, z-stacked dialogs
+ * The host establishes its own stacking context at `zIndexBase` (default 40) so windows always paint
+ * *above* the HUD (stat bars, nameplates, frames typically sit at z 10–30) — no game should have to
+ * rediscover "my vitals bar bleeds through the open window" and wrap this in a `z-*` of its own. Per-
+ * window focus order still resolves inside that context, so clicking a window raises it over its peers.
+ * Raise `zIndexBase` to sit above a full-screen modal, or lower it to tuck windows beneath one.
+ *
+ * @capability panel-host render a manager's open windows as draggable, closable, z-stacked dialogs above the HUD
  */
-export function PanelHost({ manager, render, panels, variation, shape, width, className, windowClassName, windowStyle, bodyStyle, }) {
+export function PanelHost({ manager, render, panels, variation, shape, width, zIndexBase = 40, className, windowClassName, windowStyle, bodyStyle, }) {
     const open = orderedOpen(manager.state, manager.defs);
     const content = (id) => render !== undefined ? render(id) : (panels?.[id] ?? null);
-    return (_jsx("div", { "data-jg-panel-host": "", className: className, style: { position: "absolute", inset: 0, pointerEvents: "none" }, children: open.map((def, index) => (_jsx(WindowView, { title: def.title ?? def.id, ariaLabel: def.title ?? def.id, closable: def.closable !== false, onClose: () => manager.close(def.id), onFocus: () => manager.focus(def.id), onMove: (pos) => manager.move(def.id, pos), pos: manager.state.pos[def.id] ?? cascade(index), z: manager.state.z[def.id] ?? 1, width: width, variation: variation, shape: shape, className: windowClassName, style: windowStyle, bodyStyle: bodyStyle, children: content(def.id) }, def.id))) }));
+    return (_jsx("div", { "data-jg-panel-host": "", className: className, style: { position: "absolute", inset: 0, zIndex: zIndexBase, pointerEvents: "none" }, children: open.map((def, index) => (_jsx(WindowView, { title: def.title ?? def.id, ariaLabel: def.title ?? def.id, closable: def.closable !== false, onClose: () => manager.close(def.id), onFocus: () => manager.focus(def.id), onMove: (pos) => manager.move(def.id, pos), pos: manager.state.pos[def.id] ?? cascade(index), z: manager.state.z[def.id] ?? 1, width: width, variation: variation, shape: shape, className: windowClassName, style: windowStyle, bodyStyle: bodyStyle, children: content(def.id) }, def.id))) }));
 }
 /**
  * A single standalone window — title bar, close button, and title-bar drag over {@link HudFrame} chrome —

package/dist/photoMode.d.ts

@@ -0,0 +1,21 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { PhotoModeState, PhotoModeStore } from "@jgengine/core/ui/photoMode";
+/** Subscribe to a photo-mode store's live state. */
+export declare function usePhotoMode(store: PhotoModeStore): PhotoModeState;
+/** Props for {@link PhotoModeControls}. */
+export interface PhotoModeControlsProps {
+    store: PhotoModeStore;
+    /** Take the shot — wire to shell `captureCanvas` + `downloadImage`. */
+    onCapture?: () => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Photo-mode toolbar — a hide/show-HUD toggle, a capture button, and an exit
+ * button, bound to a `createPhotoModeStore`. Presentation-only: the game wires
+ * `onCapture` to shell `captureCanvas`/`downloadImage` and reads `hideHud` to
+ * drop its gameplay HUD.
+ *
+ * @capability photo-mode-controls photo-mode toolbar (hide-HUD toggle, capture, exit) bound to a photo-mode store
+ */
+export declare function PhotoModeControls({ store, onCapture, className, style }: PhotoModeControlsProps): ReactNode;

package/dist/photoMode.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+/** Subscribe to a photo-mode store's live state. */
+export function usePhotoMode(store) {
+    return useSyncExternalStore(store.subscribe, store.get, store.get);
+}
+const BTN = {
+    borderRadius: 8,
+    border: "1px solid rgba(148,163,184,0.4)",
+    background: "rgba(17,22,30,0.85)",
+    color: "#e2e8f0",
+    fontSize: 12,
+    fontWeight: 600,
+    padding: "6px 12px",
+    cursor: "pointer",
+};
+/**
+ * Photo-mode toolbar — a hide/show-HUD toggle, a capture button, and an exit
+ * button, bound to a `createPhotoModeStore`. Presentation-only: the game wires
+ * `onCapture` to shell `captureCanvas`/`downloadImage` and reads `hideHud` to
+ * drop its gameplay HUD.
+ *
+ * @capability photo-mode-controls photo-mode toolbar (hide-HUD toggle, capture, exit) bound to a photo-mode store
+ */
+export function PhotoModeControls({ store, onCapture, className, style }) {
+    const state = usePhotoMode(store);
+    return (_jsxs("div", { className: className, "data-photo-mode-controls": true, style: {
+            display: "inline-flex",
+            alignItems: "center",
+            gap: 8,
+            padding: 8,
+            borderRadius: 12,
+            background: "rgba(6,9,14,0.86)",
+            border: "1px solid var(--jg-ring, rgba(148,163,184,0.3))",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            ...style,
+        }, children: [_jsx("span", { style: { fontSize: 11, letterSpacing: 1.4, textTransform: "uppercase", color: "rgba(203,213,225,0.75)", padding: "0 4px" }, children: "\uD83D\uDCF7 Photo" }), _jsx("button", { type: "button", "data-photo-hide-hud": true, "aria-pressed": state.hideHud, onClick: () => store.setHideHud(!state.hideHud), style: { ...BTN, ...(state.hideHud ? { borderColor: "rgba(56,189,248,0.6)", color: "#bae6fd" } : {}) }, children: state.hideHud ? "HUD hidden" : "HUD shown" }), onCapture !== undefined ? (_jsx("button", { type: "button", "data-photo-capture": true, onClick: onCapture, style: { ...BTN, borderColor: "rgba(74,222,128,0.6)", color: "#bbf7d0" }, children: "Capture" })) : null, _jsx("button", { type: "button", "data-photo-exit": true, onClick: () => store.exit(), style: BTN, children: "Exit" })] }));
+}