@jgengine/react 0.10.0 → 0.11.0

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;

package/dist/selectionHud.js

@@ -0,0 +1,182 @@
+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.
+ *
+ * @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`.
+ *
+ * @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",
+};
+/**
+ * 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 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/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.11.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.11.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/skills/jgengine/SKILL.md

@@ -0,0 +1,51 @@
+---
+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
+
+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 art direction
+- one observable completion scenario
+
+For a new in-repo game, scaffold with `bun run new:game <id> --name "Title"`. 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 |
+| --- | --- | --- |
+| 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 |
+
+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.
+
+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.