@jgengine/react 0.9.0 → 0.11.0

package/dist/map.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from "react";
 import type { FogField } from "@jgengine/core/world/fog";
 import { type MapMarker, type MarkerKindStyle, type MarkerSet } from "@jgengine/core/world/markers";
-import { type WorldXZ } from "@jgengine/core/world/minimap";
+import { type MinimapView, type WorldXZ } from "@jgengine/core/world/minimap";
 import { type MapCellStates, type MapRoute, type MapZone } from "@jgengine/core/world/mapLayers";
 export declare function useMarkers(markers: MarkerSet): readonly MapMarker[];
 export declare function useFog(fog: FogField): ReturnType<FogField["cells"]>;
@@ -40,8 +40,53 @@ export interface MapBounds {
  * Framed circular minimap: optional baked terrain background, reveal-on-event
  * fog overlay, categorized marker icons, and a facing arrow. Reads a core
  * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ *
+ * @capability minimap framed circular minimap with terrain bake, fog, markers, and facing arrow
  */
 export declare function Minimap({ markers, center, worldRadius, fog, size, facingYaw, rotate, kindStyles, background, mapBounds, routes, zones, cellStates, onWorldClick, className, title, children, }: MinimapProps): ReactNode;
+/** One dot (or, with `heading`, a rotated arrow) drawn by `MinimapChrome`. */
+export interface MinimapChromeMarker {
+    id: string;
+    position: WorldXZ | readonly [number, number, number];
+    /** Bearing (radians) to draw an arrow instead of a dot — pass `headingToBearing(yaw)` for the player/other facing blips. */
+    heading?: number;
+    color?: string;
+    radius?: number;
+    glyph?: string;
+    glyphColor?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    /** Clamp to the minimap edge when outside `view.worldRadius` (off-screen indicator); `false` hides it instead. Default `true`. */
+    clampToEdge?: boolean;
+}
+/** Props for `MinimapChrome`. */
+export interface MinimapChromeProps {
+    /** Shared with `projectToMinimap`/`clampToMinimapEdge` — pass `view.rotate` to keep a rotating map's arrows pointed correctly. */
+    view: MinimapView;
+    /** Ring outline (+ `cardinalLabel`). Default `false` — most games draw their own frame/panel around the chrome. */
+    frame?: boolean;
+    frameColor?: string;
+    frameStrokeWidth?: number;
+    /** Label drawn at the top of the ring when `frame` is on; `false` omits it. */
+    cardinalLabel?: string | false;
+    markers?: readonly MinimapChromeMarker[];
+    markerColor?: string;
+    markerRadius?: number;
+    className?: string;
+}
+/**
+ * Headless minimap chrome — nests inside a game's own `<svg>`: an optional
+ * ring frame, and edge-clamped marker dots that draw as directional arrows
+ * when a marker carries a `heading` (the compass-arrow / player-blip layer
+ * ~8 games were re-drawing by hand over `projectToMinimap`/`clampToMinimapEdge`).
+ * Renders a bare `<g>` — no background, panel, or title; compose your own
+ * content layer (routes, zones, terrain) as sibling SVG nodes for full control
+ * of z-order, or call `MinimapChrome` twice (once for `frame`, again for
+ * `markers`) to sandwich custom content between the ring and the blips.
+ *
+ * @capability minimap-chrome ring frame plus edge-clamped, heading-aware marker dots to nest inside a game's own `<svg>`
+ */
+export declare function MinimapChrome({ view, frame, frameColor, frameStrokeWidth, cardinalLabel, markers, markerColor, markerRadius, className, }: MinimapChromeProps): ReactNode;
 export interface CompassProps {
     /** Facing yaw (`rotationY`, forward = `(sin yaw, cos yaw)`) of the tracked entity — pass it raw, never pre-converted to a bearing. */
     facingYaw: number;
@@ -57,6 +102,29 @@ export interface CompassProps {
  * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
  */
 export declare function Compass({ facingYaw, center, markers, width, fov, kindStyles, className, }: CompassProps): ReactNode;
+/** Props for `MinimapPanel` — all `MinimapProps` plus the zone-label/clock header and compass slots. */
+export interface MinimapPanelProps extends MinimapProps {
+    /** Zone/area name slot rendered in the chrome header — the game supplies its own zone lookup. */
+    zoneLabel?: ReactNode;
+    /** Clock readout slot rendered in the chrome header — pair with `useGameClock()` + `calendar()`. */
+    clock?: ReactNode;
+    /** Compass strip beneath the circle. Default true; pass `false` to omit it entirely. */
+    showCompass?: boolean;
+    compassProps?: Partial<Omit<CompassProps, "className">>;
+    headerClassName?: string;
+    zoneLabelClassName?: string;
+    clockClassName?: string;
+    compassClassName?: string;
+}
+/**
+ * Composed circular-minimap chrome: optional zone-label + clock header above
+ * the `Minimap`, optional `Compass` strip below. Purely a wiring layer over
+ * the existing primitives — the game supplies the zone name and clock text,
+ * this only places them; omit either slot and the header disappears.
+ *
+ * @capability minimap-panel circular minimap with zone label, clock, and compass composed together
+ */
+export declare function MinimapPanel({ zoneLabel, clock, showCompass, compassProps, headerClassName, zoneLabelClassName, clockClassName, compassClassName, children, ...minimapProps }: MinimapPanelProps): ReactNode;
 export interface WorldMapProps {
     markers: MarkerSet;
     bounds: MapBounds;

package/dist/map.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useSyncExternalStore } from "react";
 import { DEFAULT_MARKER_KINDS, markerKindStyle, } from "@jgengine/core/world/markers";
 import { bearingToCardinal, clampToMinimapEdge, compassBearing, headingToBearing, projectToMinimap, relativeBearing, unprojectFromMinimap, } from "@jgengine/core/world/minimap";
@@ -78,6 +78,8 @@ export function useFog(fog) {
  * Framed circular minimap: optional baked terrain background, reveal-on-event
  * fog overlay, categorized marker icons, and a facing arrow. Reads a core
  * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ *
+ * @capability minimap framed circular minimap with terrain bake, fog, markers, and facing arrow
  */
 export function Minimap({ markers, center, worldRadius, fog, size = 176, facingYaw = 0, rotate = false, kindStyles = DEFAULT_MARKER_KINDS, background, mapBounds, routes, zones, cellStates, onWorldClick, className, title = "Map", children, }) {
     const markerList = useMarkers(markers);
@@ -162,6 +164,36 @@ export function Minimap({ markers, center, worldRadius, fog, size = 176, facingY
                                 return (_jsxs("g", { "data-marker-kind": marker.kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 7, fill: "rgba(2,6,12,0.55)" }), _jsx("text", { x: at.x, y: at.y + 3.5, textAnchor: "middle", fontSize: 10, fill: style.color, style: { fontWeight: 700 }, children: style.glyph })] }, marker.id));
                             }), _jsx("g", { transform: `translate(${half} ${half}) rotate(${(rotate ? 0 : bearing) * (180 / Math.PI)})`, children: _jsx("path", { d: "M0,-9 L6,7 L0,3 L-6,7 Z", fill: "#4ade80", stroke: "#052e16", strokeWidth: 0.75 }) })] }), _jsx("circle", { cx: half, cy: half, r: half - 1, fill: "none", stroke: "rgba(148,163,184,0.4)", strokeWidth: 1.5 }), _jsx("text", { x: half, y: 13, textAnchor: "middle", fontSize: 11, fill: "rgba(226,232,240,0.9)", style: { fontWeight: 700 }, children: "N" })] }), children] }));
 }
+/**
+ * Headless minimap chrome — nests inside a game's own `<svg>`: an optional
+ * ring frame, and edge-clamped marker dots that draw as directional arrows
+ * when a marker carries a `heading` (the compass-arrow / player-blip layer
+ * ~8 games were re-drawing by hand over `projectToMinimap`/`clampToMinimapEdge`).
+ * Renders a bare `<g>` — no background, panel, or title; compose your own
+ * content layer (routes, zones, terrain) as sibling SVG nodes for full control
+ * of z-order, or call `MinimapChrome` twice (once for `frame`, again for
+ * `markers`) to sandwich custom content between the ring and the blips.
+ *
+ * @capability minimap-chrome ring frame plus edge-clamped, heading-aware marker dots to nest inside a game's own `<svg>`
+ */
+export function MinimapChrome({ view, frame = false, frameColor = "rgba(148,163,184,0.4)", frameStrokeWidth = 1.5, cardinalLabel = "N", markers = [], markerColor = "#e2e8f0", markerRadius = 5, className, }) {
+    const half = view.size / 2;
+    const rotate = view.rotate ?? 0;
+    return (_jsxs("g", { className: className, "data-minimap-chrome": true, children: [frame ? (_jsxs(_Fragment, { children: [_jsx("circle", { cx: half, cy: half, r: half - 1, fill: "none", stroke: frameColor, strokeWidth: frameStrokeWidth }), cardinalLabel !== false ? (_jsx("text", { x: half, y: 13, textAnchor: "middle", fontSize: 11, fill: frameColor, style: { fontWeight: 700 }, children: cardinalLabel })) : null] })) : null, markers.map((marker) => {
+                const projected = projectToMinimap(marker.position, view);
+                const clamp = marker.clampToEdge ?? true;
+                if (!projected.inside && !clamp)
+                    return null;
+                const at = projected.inside ? projected : clampToMinimapEdge(projected, view.size);
+                const color = marker.color ?? markerColor;
+                const radius = marker.radius ?? markerRadius;
+                if (marker.heading !== undefined) {
+                    const deg = (marker.heading - rotate) * (180 / Math.PI);
+                    return (_jsx("g", { "data-minimap-marker": marker.id, transform: `translate(${at.x} ${at.y}) rotate(${deg})`, children: _jsx("path", { d: `M0,${-radius} L${radius * 0.7},${radius * 0.8} L0,${radius * 0.35} L${-radius * 0.7},${radius * 0.8} Z`, fill: color, stroke: marker.strokeColor ?? "rgba(0,0,0,0.6)", strokeWidth: marker.strokeWidth ?? 0.75 }) }, marker.id));
+                }
+                return (_jsxs("g", { "data-minimap-marker": marker.id, children: [_jsx("circle", { cx: at.x, cy: at.y, r: radius, fill: color, stroke: marker.strokeColor, strokeWidth: marker.strokeWidth }), marker.glyph !== undefined ? (_jsx("text", { x: at.x, y: at.y + 3.5, textAnchor: "middle", fontSize: 10, fill: marker.glyphColor ?? "#0f172a", style: { fontWeight: 700 }, children: marker.glyph })) : null] }, marker.id));
+            })] }));
+}
 const NO_SUBSCRIBE = () => () => undefined;
 const NULL_CELLS = () => null;
 const EMPTY_MARKERS_VALUE = [];
@@ -240,6 +272,27 @@ export function Compass({ facingYaw, center, markers, width = 340, fov = (Math.P
                 })
                 : null] }));
 }
+/**
+ * Composed circular-minimap chrome: optional zone-label + clock header above
+ * the `Minimap`, optional `Compass` strip below. Purely a wiring layer over
+ * the existing primitives — the game supplies the zone name and clock text,
+ * this only places them; omit either slot and the header disappears.
+ *
+ * @capability minimap-panel circular minimap with zone label, clock, and compass composed together
+ */
+export function MinimapPanel({ zoneLabel, clock, showCompass = true, compassProps, headerClassName, zoneLabelClassName, clockClassName, compassClassName, children, ...minimapProps }) {
+    const hasHeader = zoneLabel !== undefined || clock !== undefined;
+    return (_jsxs("div", { "data-minimap-chrome": true, children: [hasHeader ? (_jsxs("div", { className: headerClassName, "data-minimap-chrome-header": true, style: {
+                    display: "flex",
+                    justifyContent: "space-between",
+                    alignItems: "baseline",
+                    gap: 8,
+                    marginBottom: 4,
+                    width: minimapProps.size ?? 176,
+                    color: "#e2e8f0",
+                    fontFamily: "ui-sans-serif, system-ui, sans-serif",
+                }, children: [zoneLabel !== undefined ? (_jsx("span", { className: zoneLabelClassName, "data-minimap-chrome-zone": true, style: { fontSize: 12, fontWeight: 700 }, children: zoneLabel })) : (_jsx("span", {})), clock !== undefined ? (_jsx("span", { className: clockClassName, "data-minimap-chrome-clock": true, style: { fontSize: 11, color: "rgba(226,232,240,0.75)" }, children: clock })) : null] })) : null, _jsx(Minimap, { ...minimapProps, children: children }), showCompass ? (_jsx("div", { className: compassClassName, "data-minimap-chrome-compass": true, style: { marginTop: 6 }, children: _jsx(Compass, { facingYaw: minimapProps.facingYaw ?? 0, center: minimapProps.center, markers: minimapProps.markers, width: minimapProps.size ?? 176, ...compassProps }) })) : null] }));
+}
 function WorldMapFogImage({ fogCells, project, worldW, worldD, width, mapH, }) {
     const fogImage = useMemo(() => {
         if (fogCells === null)

package/dist/provider.d.ts

@@ -5,3 +5,5 @@ export declare function GameProvider({ context, children }: {
     children?: ReactNode;
 }): import("react").JSX.Element;
 export declare function useGameContext(): GameContext;
+/** The game context if a `GameProvider` is present, otherwise `null` — for chrome that may render outside a running game (showcases, previews). */
+export declare function useOptionalGameContext(): GameContext | null;

package/dist/provider.js

@@ -10,3 +10,7 @@ export function useGameContext() {
         throw new Error("useGameContext must be used within <GameProvider>");
     return ctx;
 }
+/** The game context if a `GameProvider` is present, otherwise `null` — for chrome that may render outside a running game (showcases, previews). */
+export function useOptionalGameContext() {
+    return useContext(GameReactContext);
+}

package/dist/rotateDevice.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Engine-owned rotate-device screen. A polished, non-dismissible full-viewport
+ * gate shown when a game requires an orientation the device isn't in. It owns
+ * the visible viewport (visualViewport-sized), respects safe areas, blocks all
+ * pointer/touch input to the game beneath, and is themeable through `--jg-*`
+ * tokens. Reduced-motion respected. This is game UI, not a website toast.
+ */
+import type { CSSProperties, ReactNode } from "react";
+import type { LayoutOrientation } from "@jgengine/core/ui/orientation";
+/** Full-viewport, non-dismissible rotate-device gate shown when a game requires an orientation the device isn't in. */
+export declare function RotateDeviceScreen({ title, description, requiredOrientation, accent, icon, className, style, }: {
+    /** Short headline. */
+    title?: string;
+    /** One concise explanatory line. Defaults from `requiredOrientation`. */
+    description?: string;
+    /** Orientation the game needs. Drives the rotation animation direction. */
+    requiredOrientation?: LayoutOrientation;
+    /** Illustration/token color. */
+    accent?: string;
+    /** Custom illustration; defaults to an animated phone glyph. */
+    icon?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/rotateDevice.js

@@ -0,0 +1,83 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const STYLE_ID = "jg-rotate-device-style";
+const ROTATE_CSS = `
+.jg-rotate-root {
+  position: fixed;
+  inset: 0;
+  z-index: 2147483000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--jg-visual-viewport-width, 100vw);
+  height: var(--jg-visual-viewport-height, 100dvh);
+  min-height: var(--jg-visual-viewport-height, 100vh);
+  padding: calc(env(safe-area-inset-top, 0px) + 24px) calc(env(safe-area-inset-right, 0px) + 24px)
+    calc(env(safe-area-inset-bottom, 0px) + 24px) calc(env(safe-area-inset-left, 0px) + 24px);
+  color: var(--jg-text, #f4f4f6);
+  background:
+    radial-gradient(120% 120% at 50% 0%, var(--jg-accent-dim, rgba(120, 130, 160, 0.18)), transparent 60%),
+    var(--jg-surface, #0b0d13);
+  touch-action: none;
+  user-select: none;
+  -webkit-user-select: none;
+  overflow: hidden;
+}
+.jg-rotate-inner {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 22px;
+  text-align: center;
+  max-width: 22rem;
+}
+.jg-rotate-phone {
+  transform-origin: 50% 50%;
+}
+.jg-rotate-title {
+  margin: 0;
+  font: 700 clamp(1.25rem, 5vw, 1.75rem) / 1.15 system-ui, -apple-system, "Segoe UI", sans-serif;
+  letter-spacing: -0.01em;
+}
+.jg-rotate-desc {
+  margin: 0;
+  font: 400 clamp(0.9rem, 3.4vw, 1.05rem) / 1.5 system-ui, -apple-system, "Segoe UI", sans-serif;
+  color: var(--jg-text-dim, rgba(244, 244, 246, 0.66));
+}
+@media (prefers-reduced-motion: no-preference) {
+  .jg-rotate-phone--to-landscape { animation: jg-rotate-to-landscape 2.6s cubic-bezier(0.65, 0, 0.35, 1) infinite; }
+  .jg-rotate-phone--to-portrait { animation: jg-rotate-to-portrait 2.6s cubic-bezier(0.65, 0, 0.35, 1) infinite; }
+}
+@keyframes jg-rotate-to-landscape {
+  0%, 22% { transform: rotate(0deg); }
+  55%, 78% { transform: rotate(-90deg); }
+  100% { transform: rotate(-90deg); }
+}
+@keyframes jg-rotate-to-portrait {
+  0%, 22% { transform: rotate(-90deg); }
+  55%, 78% { transform: rotate(0deg); }
+  100% { transform: rotate(0deg); }
+}
+`;
+function ensureStyle() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(STYLE_ID) !== null)
+        return;
+    const el = document.createElement("style");
+    el.id = STYLE_ID;
+    el.textContent = ROTATE_CSS;
+    document.head.appendChild(el);
+}
+function PhoneGlyph({ accent }) {
+    return (_jsxs("svg", { width: "96", height: "96", viewBox: "0 0 96 96", fill: "none", "aria-hidden": true, focusable: "false", children: [_jsx("rect", { x: "34", y: "10", width: "28", height: "52", rx: "6", stroke: accent, strokeWidth: "3", fill: "none" }), _jsx("rect", { x: "39", y: "18", width: "18", height: "34", rx: "2", fill: accent, opacity: "0.22" }), _jsx("circle", { cx: "48", cy: "57.5", r: "1.8", fill: accent }), _jsx("path", { d: "M22 74a30 30 0 0 1 52 0", stroke: accent, strokeWidth: "3", strokeLinecap: "round", fill: "none", opacity: "0.5" }), _jsx("path", { d: "M70 68l6 8-10 1z", fill: accent, opacity: "0.5" })] }));
+}
+/** Full-viewport, non-dismissible rotate-device gate shown when a game requires an orientation the device isn't in. */
+export function RotateDeviceScreen({ title = "Turn your device", description, requiredOrientation = "landscape", accent = "var(--jg-accent, #8ea2ff)", icon, className, style, }) {
+    ensureStyle();
+    const line = description ??
+        (requiredOrientation === "landscape"
+            ? "Rotate to landscape to play."
+            : "Rotate to portrait to play.");
+    const spin = requiredOrientation === "landscape" ? "jg-rotate-phone--to-landscape" : "jg-rotate-phone--to-portrait";
+    return (_jsx("div", { className: className === undefined ? "jg-rotate-root" : `jg-rotate-root ${className}`, style: style, "data-jg-orientation-gate": requiredOrientation, role: "dialog", "aria-modal": "true", "aria-label": title, onPointerDownCapture: (e) => e.stopPropagation(), onTouchStartCapture: (e) => e.stopPropagation(), children: _jsxs("div", { className: "jg-rotate-inner", children: [_jsx("div", { className: `jg-rotate-phone ${spin}`, children: icon ?? _jsx(PhoneGlyph, { accent: accent }) }), _jsx("h2", { className: "jg-rotate-title", children: title }), _jsx("p", { className: "jg-rotate-desc", children: line })] }) }));
+}

package/dist/save.d.ts

@@ -0,0 +1,25 @@
+import type { SaveStatus, SaveStore } from "@jgengine/core/game/saveStore";
+/** The reactive slice of a {@link SaveStore} returned by {@link useSaveStore} — the live value plus bound save actions, all re-rendering on change. */
+export interface SaveStoreView<T> {
+    value: T;
+    status: SaveStatus;
+    slot: string;
+    /** True while the initial `load()` is in flight — gate a loading screen on it. */
+    loading: boolean;
+    /** True while a write is in flight — show a "Saving…" indicator. */
+    saving: boolean;
+    set: (value: T) => void;
+    patch: (mutate: (previous: T) => T) => void;
+    save: () => Promise<void>;
+    clear: () => Promise<void>;
+}
+/**
+ * Bind a {@link SaveStore} to React: returns the live `value` and `status` and
+ * re-renders whenever either changes. By default it calls `load()` once on
+ * mount (pass `{ load: false }` to hydrate yourself). The same hook works for
+ * offline (localStorage) and cloud (Convex/DB) saves — only the store's backend
+ * differs.
+ */
+export declare function useSaveStore<T>(store: SaveStore<T>, options?: {
+    load?: boolean;
+}): SaveStoreView<T>;

package/dist/save.js

@@ -0,0 +1,37 @@
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+/**
+ * Bind a {@link SaveStore} to React: returns the live `value` and `status` and
+ * re-renders whenever either changes. By default it calls `load()` once on
+ * mount (pass `{ load: false }` to hydrate yourself). The same hook works for
+ * offline (localStorage) and cloud (Convex/DB) saves — only the store's backend
+ * differs.
+ */
+export function useSaveStore(store, options) {
+    useSyncExternalStore(store.subscribe, store.revision, store.revision);
+    const shouldLoad = options?.load !== false;
+    const loadedFor = useRef(null);
+    useEffect(() => {
+        if (!shouldLoad)
+            return;
+        if (loadedFor.current === store)
+            return;
+        loadedFor.current = store;
+        void store.load();
+    }, [store, shouldLoad]);
+    const set = useCallback((value) => store.set(value), [store]);
+    const patch = useCallback((mutate) => void store.patch(mutate), [store]);
+    const save = useCallback(() => store.save(), [store]);
+    const clear = useCallback(() => store.clear(), [store]);
+    const status = store.status();
+    return {
+        value: store.value(),
+        status,
+        slot: store.slot(),
+        loading: status === "loading",
+        saving: status === "saving",
+        set,
+        patch,
+        save,
+        clear,
+    };
+}

package/dist/selectSnapshot.d.ts

@@ -3,5 +3,7 @@ export type SelectCache<TSnapshot, TSelected> = {
     snapshot: TSnapshot;
     value: TSelected;
 };
+/** @internal */
 export declare function createSelectCache<TSnapshot, TSelected>(): SelectCache<TSnapshot, TSelected>;
+/** @internal */
 export declare function readSelectSnapshot<TSnapshot, TSelected>(cache: SelectCache<TSnapshot, TSelected>, snapshot: TSnapshot, select: (snapshot: TSnapshot) => TSelected, isEqual?: (previous: TSelected, next: TSelected) => boolean): TSelected;

package/dist/selectSnapshot.js

@@ -1,6 +1,8 @@
+/** @internal */
 export function createSelectCache() {
     return { ready: false, snapshot: undefined, value: undefined };
 }
+/** @internal */
 export function readSelectSnapshot(cache, snapshot, select, isEqual = Object.is) {
     if (cache.ready && Object.is(cache.snapshot, snapshot))
         return cache.value;

package/dist/selectionHud.d.ts

@@ -0,0 +1,133 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type EntitySummaryDef, type EntityVital, type SelectionGroup, type SelectionView, type SelectionWindow } from "@jgengine/core/ui/selectionModel";
+/** A minimal keyboard-event shape — a real `KeyboardEvent`/React synthetic satisfies it. */
+export interface SelectionKeyEvent {
+    key: string;
+    preventDefault(): void;
+}
+/** Options for {@link useSelectionView}. */
+export interface UseSelectionViewOptions {
+    /** Member count above which `grouped` flips true (default 12). */
+    groupThreshold?: number;
+    /** Map a member `kind` to a display label for its group. */
+    labelOf?: (kind: string) => string;
+    /** Fired when the focused (primary) member changes. */
+    onFocusChange?: (id: string) => void;
+}
+/** The live selection model returned by {@link useSelectionView}. */
+export interface SelectionModel {
+    view: SelectionView;
+    focusId: string | null;
+    setFocus: (id: string) => void;
+    onKeyDown: (event: SelectionKeyEvent) => void;
+    /** A virtualization window over the members, for a large selection strip. */
+    window: (scroll: number, size: number) => SelectionWindow;
+}
+/**
+ * The DATA/HOOK layer: summarize a selected-entity list into a live model with a focused primary,
+ * ordered members, same-kind groups, keyboard focus stepping, and a virtualization window.
+ * Rendering-agnostic — feed it to {@link SelectionPanel} or read the `view` directly.
+ *
+ * @capability selection-model headless multi-entity selection model with primary focus, grouping, and virtualization
+ */
+export declare function useSelectionView(members: readonly EntitySummaryDef[], options?: UseSelectionViewOptions): SelectionModel;
+/**
+ * A compact current/max vital meter for an entity summary; tone maps to a colour ramp. Reuse it as
+ * the vital row inside {@link EntitySummary} or any custom entity panel.
+ *
+ * @capability vital-bar compact current/max vital meter for an entity summary
+ */
+export declare function VitalBar({ vital, width, showLabel, className, style, }: {
+    vital: EntityVital;
+    width?: number;
+    showLabel?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * A selectable entity portrait tile — icon/initials, an optional thin health strip, and complete
+ * selected/hover/focus states as a real `<button>` (`aria-pressed`). The unit-of-a-selection chrome;
+ * swap the face via `renderIcon`. Accessible and keyboard-focusable.
+ *
+ * @capability entity-portrait selectable entity portrait tile with vitals and selected/focus states
+ */
+export declare function EntityPortrait({ entity, selected, size, vitalId, tabIndex, onSelect, renderIcon, className, style, }: {
+    entity: EntitySummaryDef;
+    selected?: boolean;
+    size?: number;
+    vitalId?: string;
+    tabIndex?: number;
+    onSelect?: (id: string) => void;
+    renderIcon?: (entity: EntitySummaryDef) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * The primary-entity detail chrome — name, tags, and full vital bars for the focused member. The
+ * "who is selected" summary a single-selection or the head of a multi-selection shows. Swap the vital
+ * rows via `renderVital`.
+ *
+ * @capability entity-summary primary selected-entity detail panel (name, tags, vitals)
+ */
+export declare function EntitySummary({ entity, renderVital, className, style, }: {
+    entity: EntitySummaryDef;
+    renderVital?: (vital: EntityVital) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * A same-kind selection chip — icon plus count — for the grouped large-selection view. The default
+ * chrome {@link SelectionCollectionChrome} renders per group; swap it via `renderGroup`.
+ *
+ * @capability selection-group-chip same-kind selection chip (icon + count) for a grouped selection
+ */
+export declare function SelectionGroupChip({ group, onSelect, renderIcon, className, style, }: {
+    group: SelectionGroup;
+    onSelect?: (group: SelectionGroup) => void;
+    renderIcon?: (group: SelectionGroup) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * The composable RENDERER for the member collection: a portrait strip for a small selection, or the
+ * same-kind group chips once the model is `grouped`. Roving tabindex + arrow-key focus. Swap
+ * `renderMember`/`renderGroup` for custom chrome, or read the model and lay it out yourself. No panel
+ * skin — a behavior/accessibility layer only.
+ *
+ * @capability selection-collection accessible portrait-strip / group-chip renderer over a selection model
+ */
+export declare function SelectionCollectionChrome({ model, itemSize, gap, windowSize, scroll, ariaLabel, renderMember, renderGroup, onGroupSelect, className, style, }: {
+    model: SelectionModel;
+    itemSize?: number;
+    gap?: number;
+    /** Cap the mounted portraits; the model virtualizes past this many members. */
+    windowSize?: number;
+    scroll?: number;
+    ariaLabel?: string;
+    renderMember?: (entity: EntitySummaryDef, selected: boolean) => ReactNode;
+    renderGroup?: (group: SelectionGroup) => ReactNode;
+    onGroupSelect?: (group: SelectionGroup) => void;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * The batteries-included default: a skinned glass panel composing {@link EntitySummary} for the
+ * primary member beside {@link SelectionCollectionChrome} for the rest. Pass `members` (or a prebuilt
+ * `model`) and it renders a working RTS-style selection panel; every sub-renderer stays swappable, and
+ * a game that wants a different frame composes the hook and chrome directly.
+ *
+ * @capability selection-panel drop-in selection panel: primary summary beside a portrait strip / group chips
+ */
+export declare function SelectionPanel({ members, model: providedModel, groupThreshold, labelOf, windowSize, renderPrimary, renderMember, renderVital, onFocusChange, className, style, }: {
+    members?: readonly EntitySummaryDef[];
+    model?: SelectionModel;
+    groupThreshold?: number;
+    labelOf?: (kind: string) => string;
+    windowSize?: number;
+    renderPrimary?: (entity: EntitySummaryDef) => ReactNode;
+    renderMember?: (entity: EntitySummaryDef, selected: boolean) => ReactNode;
+    renderVital?: (vital: EntityVital) => ReactNode;
+    onFocusChange?: (id: string) => void;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element | null;