@jgengine/react 0.10.0 → 0.12.0

package/dist/selectionHud.js

@@ -0,0 +1,188 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo, useState, } from "react";
+import { moveSelectionFocus, selectionWindow, summarizeSelection, } from "@jgengine/core/ui/selectionModel";
+/**
+ * Composable React renderers over the headless selection view model
+ * (`@jgengine/core/ui/selectionModel`) — the data/renderer/chrome split for an RTS selection panel, a
+ * party frame, or a squad summary. `useSelectionView` is the DATA/HOOK layer (summary + focus +
+ * virtualization), `EntityPortrait`/`EntitySummary`/`SelectionCollectionChrome` are composable
+ * renderers, and `SelectionPanel` is the batteries-included default. A game supplies the entity data
+ * from wherever selection lives and swaps renderer or chrome without forking the logic.
+ */
+/** A move that steps the selection focus by keyboard/controller. */
+const SELECTION_KEYS = {
+    ArrowRight: "next",
+    ArrowDown: "next",
+    ArrowLeft: "prev",
+    ArrowUp: "prev",
+    Home: "first",
+    End: "last",
+};
+/**
+ * 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 function useSelectionView(members, options) {
+    const [focusId, setFocusId] = useState(null);
+    const summarizeOptions = useMemo(() => {
+        const opts = {};
+        if (focusId !== null)
+            opts.primaryId = focusId;
+        if (options?.groupThreshold !== undefined)
+            opts.groupThreshold = options.groupThreshold;
+        if (options?.labelOf !== undefined)
+            opts.labelOf = options.labelOf;
+        return opts;
+    }, [focusId, options?.groupThreshold, options?.labelOf]);
+    const view = useMemo(() => summarizeSelection(members, summarizeOptions), [members, summarizeOptions]);
+    const setFocus = useCallback((id) => {
+        setFocusId(id);
+        options?.onFocusChange?.(id);
+    }, [options]);
+    const onKeyDown = useCallback((event) => {
+        const dir = SELECTION_KEYS[event.key];
+        if (dir === undefined)
+            return;
+        const next = moveSelectionFocus(view.count, view.focusIndex, dir);
+        const nextMember = view.members[next];
+        if (nextMember !== undefined)
+            setFocus(nextMember.id);
+        event.preventDefault();
+    }, [view, setFocus]);
+    const windowFn = useCallback((scroll, size) => selectionWindow(members, scroll, size), [members]);
+    return { view, focusId, setFocus, onKeyDown, window: windowFn };
+}
+const VITAL_TONES = {
+    health: ["#22c55e", "#4ade80"],
+    shield: ["#0891b2", "#22d3ee"],
+    energy: ["#2563eb", "#60a5fa"],
+    neutral: ["#64748b", "#94a3b8"],
+};
+/**
+ * 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.
+ *
+ * @deprecated The `tone`/`vital`-API umbrella is retired (#1033). Use the atomic, purpose-named,
+ * token-themed bars from `@jgengine/react/bars` (`HealthBar`, `ShieldBar`, `ManaBar`, …) and compose
+ * your own panel — each does one readout and restyles globally via the shared `--jg-*` tokens.
+ * @capability vital-bar compact current/max vital meter for an entity summary
+ */
+export function VitalBar({ vital, width = 120, showLabel = true, className, style, }) {
+    const denom = vital.max <= 0 ? 1 : vital.max;
+    const fraction = Math.max(0, Math.min(1, vital.current / denom));
+    const [from, to] = VITAL_TONES[vital.tone ?? "neutral"] ?? VITAL_TONES.neutral;
+    return (_jsxs("div", { className: className, "data-vital": vital.id, style: { width, ...style }, children: [showLabel ? (_jsxs("div", { style: { display: "flex", fontSize: 10, opacity: 0.75, marginBottom: 2 }, children: [_jsx("span", { children: vital.label ?? vital.id }), _jsxs("span", { style: { marginLeft: "auto", fontVariantNumeric: "tabular-nums" }, children: [Math.round(vital.current), "/", Math.round(vital.max)] })] })) : null, _jsx("div", { style: { height: 6, borderRadius: 999, background: "rgba(255,255,255,0.12)", overflow: "hidden" }, children: _jsx("div", { style: { width: `${fraction * 100}%`, height: "100%", background: `linear-gradient(90deg, ${from}, ${to})` } }) })] }));
+}
+const PORTRAIT_BASE = {
+    position: "relative",
+    boxSizing: "border-box",
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    border: "1px solid rgba(255,255,255,0.14)",
+    borderRadius: 8,
+    background: "rgba(14,17,22,0.72)",
+    color: "#eef2f8",
+    cursor: "pointer",
+    userSelect: "none",
+    padding: 2,
+};
+/**
+ * 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 function EntityPortrait({ entity, selected = false, size = 44, vitalId = "health", tabIndex, onSelect, renderIcon, className, style, }) {
+    const vital = entity.vitals?.find((v) => v.id === vitalId) ?? entity.vitals?.[0];
+    return (_jsxs("button", { type: "button", className: className, "data-entity-id": entity.id, "data-selected": selected ? "" : undefined, "aria-pressed": selected, "aria-label": entity.name ?? entity.id, title: entity.name ?? entity.id, tabIndex: tabIndex, onClick: () => onSelect?.(entity.id), style: {
+            ...PORTRAIT_BASE,
+            width: size,
+            height: size,
+            borderColor: selected ? "rgba(56,189,248,0.95)" : "rgba(255,255,255,0.14)",
+            boxShadow: selected ? "0 0 0 2px rgba(56,189,248,0.6)" : "none",
+            ...style,
+        }, children: [_jsx("span", { "data-entity-icon": true, "aria-hidden": true, style: { fontSize: renderIcon ? undefined : 16 }, children: renderIcon ? renderIcon(entity) : (entity.icon ?? (entity.name ?? entity.id).slice(0, 2)) }), vital !== undefined ? (_jsx("div", { style: { position: "absolute", left: 3, right: 3, bottom: 3, height: 3, borderRadius: 999, background: "rgba(255,255,255,0.12)", overflow: "hidden" }, children: _jsx("div", { style: {
+                        width: `${Math.max(0, Math.min(1, vital.max <= 0 ? 0 : vital.current / vital.max)) * 100}%`,
+                        height: "100%",
+                        background: (VITAL_TONES[vital.tone ?? "health"] ?? VITAL_TONES.neutral)[0],
+                    } }) })) : null] }));
+}
+/**
+ * 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`.
+ *
+ * @deprecated Bundling a whole vitals array in one component is the combo anti-pattern #1033 retires.
+ * Compose your own summary — name/tags plus the atomic `@jgengine/react/bars` (`HealthBar`, …) you
+ * need — so no engine component packages multiple readouts by default. Kept during migration.
+ * @capability entity-summary primary selected-entity detail panel (name, tags, vitals)
+ */
+export function EntitySummary({ entity, renderVital, className, style, }) {
+    return (_jsxs("div", { className: className, "data-entity-summary": entity.id, style: { display: "flex", flexDirection: "column", gap: 4, minWidth: 140, ...style }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: 6 }, children: [_jsx("strong", { style: { fontSize: 14 }, children: entity.name ?? entity.id }), entity.kind !== undefined ? (_jsx("span", { style: { fontSize: 10, textTransform: "uppercase", letterSpacing: 0.4, opacity: 0.6 }, children: entity.kind })) : null] }), entity.tags !== undefined && entity.tags.length > 0 ? (_jsx("div", { style: { display: "flex", flexWrap: "wrap", gap: 4 }, children: entity.tags.map((tag) => (_jsx("span", { style: { fontSize: 9, padding: "1px 5px", borderRadius: 999, background: "rgba(255,255,255,0.1)" }, children: tag }, tag))) })) : null, (entity.vitals ?? []).map((vital) => (_jsx("div", { children: renderVital ? renderVital(vital) : _jsx(VitalBar, { vital: vital }) }, vital.id)))] }));
+}
+/**
+ * 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 function SelectionGroupChip({ group, onSelect, renderIcon, className, style, }) {
+    return (_jsxs("button", { type: "button", className: className, "data-selection-group": group.kind, "aria-label": `${group.count} ${group.label}`, title: `${group.count} ${group.label}`, onClick: () => onSelect?.(group), style: { ...PORTRAIT_BASE, width: 44, height: 44, ...style }, children: [_jsx("span", { "aria-hidden": true, style: { fontSize: 16 }, children: renderIcon ? renderIcon(group) : (group.icon ?? group.label.slice(0, 2)) }), _jsx("span", { style: { position: "absolute", right: 2, bottom: 1, fontSize: 10, fontWeight: 700 }, children: group.count })] }));
+}
+/**
+ * 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 function SelectionCollectionChrome({ model, itemSize = 44, gap = 4, windowSize, scroll = 0, ariaLabel = "Selection", renderMember, renderGroup, onGroupSelect, className, style, }) {
+    const { view } = model;
+    const rovingId = model.focusId ?? view.primary?.id ?? null;
+    const containerStyle = { display: "flex", flexWrap: "wrap", gap };
+    if (view.grouped) {
+        return (_jsx("div", { role: "group", "aria-label": ariaLabel, className: className, "data-selection-groups": "", style: { ...containerStyle, ...style }, children: view.groups.map((group) => renderGroup ? (_jsx("div", { children: renderGroup(group) }, group.kind)) : (_jsx(SelectionGroupChip, { group: group, onSelect: onGroupSelect }, group.kind))) }));
+    }
+    const win = windowSize !== undefined ? model.window(scroll, windowSize) : { start: 0, end: view.count, items: view.members };
+    return (_jsx("div", { role: "listbox", "aria-label": ariaLabel, "aria-orientation": "horizontal", className: className, "data-selection-strip": "", onKeyDown: model.onKeyDown, style: { ...containerStyle, ...style }, children: win.items.map((entity) => {
+            const selected = view.primary?.id === entity.id;
+            if (renderMember !== undefined) {
+                return (_jsx("div", { role: "option", "aria-selected": selected, children: renderMember(entity, selected) }, entity.id));
+            }
+            return (_jsx("div", { role: "option", "aria-selected": selected, children: _jsx(EntityPortrait, { entity: entity, selected: selected, size: itemSize, tabIndex: rovingId === entity.id ? 0 : -1, onSelect: model.setFocus }) }, entity.id));
+        }) }));
+}
+const PANEL = {
+    padding: 8,
+    borderRadius: 12,
+    background: "rgba(10,12,16,0.6)",
+    backdropFilter: "blur(6px)",
+    WebkitBackdropFilter: "blur(6px)",
+    border: "1px solid rgba(255,255,255,0.1)",
+    boxShadow: "0 4px 16px rgba(0,0,0,0.35)",
+    color: "#eef2f8",
+    font: "500 12px/1.2 ui-sans-serif, system-ui, sans-serif",
+};
+/**
+ * Convenience composition: skinned glass panel with {@link EntitySummary} for the primary member
+ * beside {@link SelectionCollectionChrome} for the rest — demos/scaffold only, not a finished game
+ * face. Pass `members` (or a prebuilt `model`); swap sub-renderers or compose the headless pieces
+ * under game-owned chrome for product UI.
+ *
+ * @capability selection-panel optional selection-panel composition: summary + portrait strip / group chips
+ */
+export function SelectionPanel({ members, model: providedModel, groupThreshold, labelOf, windowSize, renderPrimary, renderMember, renderVital, onFocusChange, className, style, }) {
+    const ownModel = useSelectionView(members ?? [], { groupThreshold, labelOf, onFocusChange });
+    const model = providedModel ?? ownModel;
+    const { view } = model;
+    if (view.count === 0)
+        return null;
+    return (_jsxs("div", { className: className, "data-selection-panel": "", style: { ...PANEL, display: "flex", gap: 12, alignItems: "flex-start", ...style }, children: [view.primary !== null ? (_jsx("div", { children: renderPrimary ? renderPrimary(view.primary) : _jsx(EntitySummary, { entity: view.primary, renderVital: renderVital }) })) : null, view.count > 1 ? (_jsx(SelectionCollectionChrome, { model: model, windowSize: windowSize, renderMember: renderMember, style: { maxWidth: 320 } })) : null] }));
+}

package/dist/skillCheckPaint.d.ts

@@ -1,4 +1,6 @@
 import type { SkillCheckConfig, SkillCheckResult } from "@jgengine/core/interaction/skillCheck";
 import type { QteStep } from "@jgengine/core/interaction/qte";
+/** @internal */
 export declare function paintSkillCheckDom(root: HTMLElement, zone: HTMLElement, marker: HTMLElement, config: SkillCheckConfig, result: SkillCheckResult): void;
+/** @internal */
 export declare function paintQteStepDom(elements: ReadonlyMap<string, HTMLElement>, steps: readonly QteStep[], elapsed: number, activeId: string | null, stepClassName?: string, activeClassName?: string, doneClassName?: string): void;

package/dist/skillCheckPaint.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function paintSkillCheckDom(root, zone, marker, config, result) {
     const zoneLeft = (result.zone.start / config.trackWidth) * 100;
     const zoneWidth = ((result.zone.end - result.zone.start) / config.trackWidth) * 100;
@@ -8,6 +9,7 @@ export function paintSkillCheckDom(root, zone, marker, config, result) {
     root.dataset.inZone = result.success ? "true" : "false";
     root.dataset.timedOut = result.timedOut ? "true" : "false";
 }
+/** @internal */
 export function paintQteStepDom(elements, steps, elapsed, activeId, stepClassName, activeClassName, doneClassName) {
     for (const step of steps) {
         const el = elements.get(step.id);

package/dist/slots.d.ts

@@ -0,0 +1,44 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type IconSchool } from "./iconTreatment.js";
+import type { GameIconName } from "./gameIcons.js";
+/**
+ * Atomic, purpose-named slot grids (#1033): one component per category — `EquipmentSlots`,
+ * `WeaponSlots`, `ArmorSlots`, `PotionSlots` — never a mega inventory that bundles every category.
+ * Each renders a grid of painted {@link IconTreatment} tiles (glyph + gradient + count badge) for
+ * filled slots and a themed placeholder for empty ones, all reading the shared `--jg-slot-*` /
+ * `--jg-accent` HudTheme tokens (#1034). Composition stays the game's; the engine ships the grid.
+ *
+ * @capability hud-slots atomic themed equipment/weapon/armor/potion slot grids with painted icons
+ */
+/** One slot's content — a `GameIcon` glyph (or custom node), school tint, count, keycap, active flag. */
+export interface SlotItem {
+    icon?: GameIconName;
+    glyph?: ReactNode;
+    school?: IconSchool;
+    count?: number;
+    keycap?: string;
+    active?: boolean;
+    /** Accessible label / tooltip. */
+    label?: string;
+}
+/** Props shared by every atomic slot grid. */
+export interface SlotGridProps {
+    /** Slots in order; `null` (or a slot with no icon/glyph) renders an empty placeholder. */
+    items: readonly (SlotItem | null)[];
+    /** Tile size in px. Default 44. */
+    size?: number;
+    /** Grid columns; default = one row (all slots). */
+    columns?: number;
+    /** Gap between tiles in px. Default 6. */
+    gap?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Worn-gear slots (head/chest/hands/…): one atomic grid, painted icons, themed from tokens. */
+export declare function EquipmentSlots(props: SlotGridProps): import("react").JSX.Element;
+/** Weapon loadout slots. */
+export declare function WeaponSlots(props: SlotGridProps): import("react").JSX.Element;
+/** Armor piece slots. */
+export declare function ArmorSlots(props: SlotGridProps): import("react").JSX.Element;
+/** Consumable (health/shield potion) slots. */
+export declare function PotionSlots(props: SlotGridProps): import("react").JSX.Element;

package/dist/slots.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+import { IconTreatment } from "./iconTreatment.js";
+function EmptySlot({ size }) {
+    return (_jsx("div", { "data-slot-empty": "", style: {
+            width: size,
+            height: size,
+            borderRadius: "var(--jg-slot-radius, 9px)",
+            background: "var(--jg-slot-bg, rgba(12,14,20,0.5))",
+            border: "var(--jg-slot-border, 1px solid rgba(255,255,255,0.1))",
+            boxShadow: "inset 0 2px 6px rgba(0,0,0,0.45)",
+            boxSizing: "border-box",
+        } }));
+}
+function SlotGrid({ category, items, size = 44, columns, gap = 6, className, style }) {
+    const cols = columns ?? items.length;
+    return (_jsx("div", { "data-slots": category, className: className, style: { display: "grid", gridTemplateColumns: `repeat(${Math.max(1, cols)}, ${size}px)`, gap, ...style }, children: items.map((item, index) => {
+            const filled = item !== null && (item.icon !== undefined || item.glyph !== undefined);
+            return filled ? (_jsx(IconTreatment, { ...(item.icon === undefined ? {} : { icon: item.icon }), ...(item.glyph === undefined ? {} : { glyph: item.glyph }), school: item.school ?? "neutral", size: size, ...(item.count === undefined ? {} : { count: item.count }), ...(item.keycap === undefined ? {} : { keycap: item.keycap }), active: item.active ?? false }, index)) : (_jsx(EmptySlot, { size: size }, index));
+        }) }));
+}
+/** Worn-gear slots (head/chest/hands/…): one atomic grid, painted icons, themed from tokens. */
+export function EquipmentSlots(props) {
+    return _jsx(SlotGrid, { category: "equipment", ...props });
+}
+/** Weapon loadout slots. */
+export function WeaponSlots(props) {
+    return _jsx(SlotGrid, { category: "weapon", ...props });
+}
+/** Armor piece slots. */
+export function ArmorSlots(props) {
+    return _jsx(SlotGrid, { category: "armor", ...props });
+}
+/** Consumable (health/shield potion) slots. */
+export function PotionSlots(props) {
+    return _jsx(SlotGrid, { category: "potion", ...props });
+}

package/dist/startScreen.d.ts

@@ -0,0 +1,62 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type ActionCodesMap } from "@jgengine/core/input/actionBindings";
+/**
+ * One row of a control legend. Name the game action(s) whose bound key(s) to
+ * show (`action`) so the glyphs come straight from the keybind map — never
+ * re-typed — or give literal `keys` for controls that live outside the map
+ * (`"Mouse"`, `"LMB"`). `label` says what the control does.
+ */
+export interface ControlHint {
+    action?: string | readonly string[];
+    keys?: string | readonly string[];
+    label: string;
+    separator?: string;
+}
+/**
+ * Renders a controls legend whose key glyphs come from the game's keybind map,
+ * so bindings live in one place and never drift from a hand-typed table. Hides
+ * itself on coarse-pointer devices (a touchscreen has no keyboard) via the same
+ * `data-jg-kbd-hint` marker as `KeyHint`. Headless: every part carries a
+ * `className` slot and `data-*` hook; pass `renderKey`/`renderRow` to fully own
+ * the markup.
+ *
+ * @capability controls-list keybind-derived control legend that hides on touch
+ */
+export declare function ControlsList({ bindings, controls, hideOnCoarsePointer, separator, className, rowClassName, keysClassName, keyClassName, separatorClassName, labelClassName, renderKey, renderRow, }: {
+    bindings?: ActionCodesMap;
+    controls: readonly ControlHint[];
+    hideOnCoarsePointer?: boolean;
+    separator?: string;
+    className?: string;
+    rowClassName?: string;
+    keysClassName?: string;
+    keyClassName?: string;
+    separatorClassName?: string;
+    labelClassName?: string;
+    renderKey?: (key: string, index: number) => ReactNode;
+    renderRow?: (row: {
+        keys: readonly string[];
+        label: string;
+    }, index: number) => ReactNode;
+}): ReactNode;
+/** Which corner of a `StartScreen` the opt-in settings slot is pinned to. */
+export type StartScreenCorner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/**
+ * Composable title/attract-screen scaffold: a full-bleed `data-jg-menu` overlay
+ * that positions and centers the game's own content, with an opt-in settings
+ * corner. It imposes no look — the game supplies the title, art, and buttons as
+ * children and styles the container through `className`/`style` (per the
+ * composable-chrome rule: a placement hook, not a mandated menu).
+ *
+ * @capability start-screen headless title/attract overlay the game fills and skins
+ */
+export declare function StartScreen({ open, className, style, children, settings, settingsPlacement, settingsClassName, settingsWrapperClassName, }: {
+    open?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+    settings?: boolean | ReactNode;
+    settingsPlacement?: StartScreenCorner;
+    settingsClassName?: string;
+    settingsWrapperClassName?: string;
+}): ReactNode;

package/dist/startScreen.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
+import { actionLabel } from "@jgengine/core/input/actionBindings";
+import { useDisplayProfile } from "./display.js";
+import { Keycap } from "./keyHint.js";
+import { SettingsTrigger } from "./settings.js";
+function toArray(value) {
+    if (value === undefined)
+        return [];
+    return typeof value === "string" ? [value] : value;
+}
+function resolveKeys(hint, bindings) {
+    const literal = toArray(hint.keys);
+    if (literal.length > 0)
+        return [...literal];
+    if (bindings === undefined)
+        return [];
+    const glyphs = [];
+    for (const action of toArray(hint.action)) {
+        const glyph = actionLabel(bindings, action);
+        if (glyph !== null)
+            glyphs.push(glyph);
+    }
+    return glyphs;
+}
+/**
+ * Renders a controls legend whose key glyphs come from the game's keybind map,
+ * so bindings live in one place and never drift from a hand-typed table. Hides
+ * itself on coarse-pointer devices (a touchscreen has no keyboard) via the same
+ * `data-jg-kbd-hint` marker as `KeyHint`. Headless: every part carries a
+ * `className` slot and `data-*` hook; pass `renderKey`/`renderRow` to fully own
+ * the markup.
+ *
+ * @capability controls-list keybind-derived control legend that hides on touch
+ */
+export function ControlsList({ bindings, controls, hideOnCoarsePointer = true, separator = " / ", className, rowClassName, keysClassName, keyClassName, separatorClassName, labelClassName, renderKey, renderRow, }) {
+    const { coarsePointer } = useDisplayProfile();
+    if (hideOnCoarsePointer && coarsePointer)
+        return null;
+    const rows = controls.map((hint) => ({ keys: resolveKeys(hint, bindings), label: hint.label, separator: hint.separator }));
+    return (_jsx("div", { "data-jg-controls": "", "data-jg-kbd-hint": hideOnCoarsePointer ? "" : undefined, className: className, children: rows.map((row, index) => renderRow !== undefined ? (_jsx(Fragment, { children: renderRow(row, index) }, index)) : (_jsxs("div", { "data-jg-control": "", className: rowClassName, children: [_jsx("span", { "data-jg-control-keys": "", className: keysClassName, children: row.keys.map((key, keyIndex) => (_jsxs(Fragment, { children: [keyIndex > 0 ? (_jsx("span", { "data-jg-control-sep": "", className: separatorClassName, children: row.separator ?? separator })) : null, renderKey !== undefined ? renderKey(key, keyIndex) : _jsx(Keycap, { className: keyClassName, children: key })] }, keyIndex))) }), _jsx("span", { "data-jg-control-label": "", className: labelClassName, children: row.label })] }, index))) }));
+}
+const CORNER_STYLE = {
+    "top-left": { position: "absolute", top: 0, left: 0 },
+    "top-right": { position: "absolute", top: 0, right: 0 },
+    "bottom-left": { position: "absolute", bottom: 0, left: 0 },
+    "bottom-right": { position: "absolute", bottom: 0, right: 0 },
+};
+/**
+ * Composable title/attract-screen scaffold: a full-bleed `data-jg-menu` overlay
+ * that positions and centers the game's own content, with an opt-in settings
+ * corner. It imposes no look — the game supplies the title, art, and buttons as
+ * children and styles the container through `className`/`style` (per the
+ * composable-chrome rule: a placement hook, not a mandated menu).
+ *
+ * @capability start-screen headless title/attract overlay the game fills and skins
+ */
+export function StartScreen({ open = true, className, style, children, settings, settingsPlacement = "top-right", settingsClassName, settingsWrapperClassName, }) {
+    if (!open)
+        return null;
+    return (_jsxs("div", { "data-jg-menu": "", "data-screen": "start", className: className, style: style, children: [settings !== undefined && settings !== false ? (_jsx("div", { "data-jg-menu-settings": "", className: settingsWrapperClassName, style: settingsWrapperClassName === undefined ? CORNER_STYLE[settingsPlacement] : undefined, children: settings === true ? _jsx(SettingsTrigger, { className: settingsClassName }) : settings })) : null, children] }));
+}

package/dist/store.d.ts

@@ -0,0 +1,24 @@
+import type { StoreHandle } from "@jgengine/core/store/defineStore";
+import type { KeyedStoreHandle } from "@jgengine/core/store/defineKeyedStore";
+/**
+ * Subscribe a component to a typed store slot defined with `defineStore`. Returns the current value
+ * (or the definition's initial before any write), re-rendering only when the slot changes — the
+ * cast-free, boilerplate-free replacement for a hand-written `useGameStore((ctx) => ctx.game.store.get(KEY) as T)`.
+ *
+ * Pass a `selector` to read a derived slice with its own equality, so a HUD that watches one field
+ * doesn't re-render on every unrelated store write.
+ */
+export declare function useStore<T>(handle: StoreHandle<T>): T;
+export declare function useStore<T, S>(handle: StoreHandle<T>, selector: (value: T) => S, isEqual?: (previous: S, next: S) => boolean): S;
+/**
+ * Subscribe a component to one owner's slot of a typed keyed-family store defined with
+ * `defineKeyedStore`. Returns the current value for `id` (or the definition's initial before any
+ * write for that id), re-rendering only when that owner's slot changes — the cast-free,
+ * boilerplate-free replacement for a hand-written
+ * `useGameStore((ctx) => ctx.game.store.get(`prefix:${id}`) as T)`.
+ *
+ * Pass a `selector` to read a derived slice with its own equality, so a HUD that watches one field
+ * of one owner's state doesn't re-render on every unrelated store write.
+ */
+export declare function useKeyedStore<T>(handle: KeyedStoreHandle<T>, id: string): T;
+export declare function useKeyedStore<T, S>(handle: KeyedStoreHandle<T>, id: string, selector: (value: T) => S, isEqual?: (previous: S, next: S) => boolean): S;

package/dist/store.js

@@ -0,0 +1,9 @@
+import { useGameStore } from "./hooks.js";
+export function useStore(handle, selector, isEqual = Object.is) {
+    const select = selector;
+    return useGameStore((ctx) => (select === undefined ? handle.read(ctx) : select(handle.read(ctx))), select === undefined ? Object.is : isEqual);
+}
+export function useKeyedStore(handle, id, selector, isEqual = Object.is) {
+    const select = selector;
+    return useGameStore((ctx) => (select === undefined ? handle.read(ctx, id) : select(handle.read(ctx, id))), select === undefined ? Object.is : isEqual);
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@jgengine/react",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "React UI layer for JGengine: GameProvider, hooks, and headless primitives over @jgengine/core.",
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "repository": {
@@ -13,7 +13,7 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "llms.txt"
+    "skills"
   ],
   "exports": {
     ".": {
@@ -31,7 +31,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.10.0"
+    "@jgengine/core": "^0.12.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/skills/jgengine/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: jgengine
+description: Route game work to the smallest useful JGengine guidance set.
+---
+
+# JGengine intake and router
+
+Read the repository [README](../../../README.md) for package truth, commands, layering, and license. This skill decides what to load; it is not an engine manual.
+
+## 1. Establish the target
+
+Treat the pitch as a unique composition of needs, not a genre to fill in — never reach for a genre kit, preset, archetype, or class template ("default sports car", "default RPG", "default FPS") in the SDK or skills (see [AGENTS.md](../../../AGENTS.md)). Use `game-design` to turn the pitch into a testable player promise, verbs, loops, progression, failure, and completion scenario. Use `level-design` when play depends on authored spaces, routes, encounters, exploration, or spatial pacing. Capture only decisions that change architecture:
+
+- player point of view and controls
+- world shape and authored content
+- core loop, interaction, combat, and progression
+- solo, local, hosted, or persistent multiplayer
+- HUD/menu states and **custom** UI art direction (every game owns its presentation — no stock drop-in face)
+- one observable completion scenario
+
+For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+
+## 2. Select domains
+
+Load only rows the target needs. Do not preload every domain.
+
+| Need | Skill | Owner |
+| --- | --- | --- |
+| player promise, pillars, verbs, loops, economy, progression, balance | `game-design` | experience and rule intent |
+| metrics, topology, encounters, navigation, spatial pacing | `level-design` | playable space intent |
+| scene placement, terrain painting, paths, asset authoring | `jgengine-editor` | editor document and authoring tools |
+| runtime world, movement, input, interaction, AI, navigation, audio | `jgengine-world` | spatial simulation and world runtime |
+| game state, systems, inventory, crafting, quests, economy, turns | `jgengine-gameplay` | non-combat rules and state |
+| targeting, stats, damage, effects, abilities, projectiles, loot | `jgengine-combat` | combat resolution |
+| HUD, menus, layout, accessibility, touch presentation | `jgengine-ui` | player-facing interface |
+| models, sprites, materials, audio files, source licensing | `jgengine-assets` | asset discovery and catalogs |
+| authority, transport, replication, sessions, host persistence | `jgengine-multiplayer` | network topology and persistence adapters |
+
+World content routes editor-first: any request that adds, moves, restyles, or removes something visible in the world — however phrased ("design this world", "place the enemies", "make it look better") — starts in `jgengine-editor`; the other domains consume the authored document. Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
+
+## 3. Discover before designing
+
+Within each selected domain:
+
+1. Search `capabilities.md` by intent; it maps needs to imports.
+2. Open `api.md` only when exact signatures or export inventory are needed.
+3. Open the linked reference only for a deeper recipe or trap.
+4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.
+
+If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.
+
+## 4. Build and finish
+
+Keep scene coordinates in the editor document, state serializable, randomness injected, and hot-path work bounded. Use `jgengine-verify` for evidence appropriate to the change. Inside this monorepo, `workflow` owns issue/PR completion. Visual polish work also uses the `jgengine-ui` quality reference.