@jgengine/react 0.18.0 → 0.19.0

package/dist/hudSkin.js

@@ -0,0 +1,50 @@
+import { useEffect, useState } from "react";
+/** Converts a skin into the CSS variables consumed by shared HUD components. */
+export function hudSkinVars(skin) {
+    if (!skin)
+        return {};
+    const vars = {};
+    const material = (prefix, value) => {
+        if (!value)
+            return;
+        vars[`--jg-${prefix}-image`] = `url(${value.image})`;
+        vars[`--jg-${prefix}-slice`] = value.slice.join(" ");
+        if (value.scale !== undefined)
+            vars[`--jg-${prefix}-scale`] = String(value.scale);
+        if (value.fill !== undefined)
+            vars[`--jg-${prefix}-fill`] = value.fill ? "fill" : "";
+    };
+    material("frame", skin.frame);
+    material("slot", skin.slot);
+    if (skin.bar) {
+        vars["--jg-bar-skin-fill"] = skin.bar.fill;
+        vars["--jg-bar-skin-track"] = skin.bar.track;
+        if (skin.bar.cap)
+            vars["--jg-bar-skin-cap"] = `url(${skin.bar.cap})`;
+    }
+    if (skin.font) {
+        vars["--jg-skin-font"] = skin.font.family;
+        if (skin.font.pixel)
+            vars["--jg-skin-font-rendering"] = "pixelated";
+    }
+    if (skin.cursor)
+        vars["--jg-skin-cursor"] = `url(${skin.cursor}), auto`;
+    return vars;
+}
+/** Loads a skin font in browsers and reports when it is available. */
+export function useHudFont(skin) {
+    const [loaded, setLoaded] = useState(false);
+    useEffect(() => {
+        if (!skin?.font || typeof FontFace === "undefined") {
+            setLoaded(!skin?.font);
+            return;
+        }
+        const font = new FontFace(skin.font.family, `url(${skin.font.src})`, { weight: String(skin.font.weight ?? 400) });
+        let active = true;
+        font.load().then((face) => { document.fonts.add(face); if (active)
+            setLoaded(true); }).catch(() => { if (active)
+            setLoaded(false); });
+        return () => { active = false; };
+    }, [skin?.font?.family, skin?.font?.src, skin?.font?.weight]);
+    return loaded;
+}

package/dist/hudSkinPreview.d.ts

@@ -0,0 +1,4 @@
+/** Procedural two-skin fixture for visual regression captures. */
+export declare function HudSkinPreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/hudSkinPreview.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { HealthBar, ShieldBar } from "./bars.js";
+import { HudFrame } from "./hudFrame.js";
+import { hudTheme, hudThemeVars } from "./hudTheme.js";
+import { hudSkinVars } from "./hudSkin.js";
+function painted(color, dark) {
+    if (typeof document === "undefined")
+        return "";
+    const canvas = document.createElement("canvas");
+    canvas.width = 32;
+    canvas.height = 32;
+    const ctx = canvas.getContext("2d");
+    if (!ctx)
+        return "";
+    ctx.fillStyle = dark;
+    ctx.fillRect(0, 0, 32, 32);
+    ctx.strokeStyle = color;
+    ctx.lineWidth = 5;
+    ctx.strokeRect(3, 3, 26, 26);
+    return canvas.toDataURL("image/png");
+}
+function SkinCell({ title, skin }) {
+    const vars = { ...hudThemeVars(hudTheme({ skin })), ...hudSkinVars(skin) };
+    return _jsx("div", { style: { ...vars, width: 300 }, children: _jsx(HudFrame, { variation: "themed", title: title, padding: 14, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 10 }, children: [_jsx(HealthBar, { value: 78, max: 100, label: "HP", width: "100%" }), _jsx(ShieldBar, { value: 42, max: 60, label: "SH", width: "100%" }), _jsx("div", { style: { display: "flex", gap: 6 }, children: ["A", "B", "C", "D", "E"].map((label) => _jsx("div", { style: { width: 40, height: 40, display: "grid", placeItems: "center", color: "var(--jg-text)", border: "var(--jg-slot-border)", borderImage: "var(--jg-slot-image, none) var(--jg-slot-slice, 0) / var(--jg-slot-scale, 1)", background: "var(--jg-slot-bg)", borderRadius: "var(--jg-slot-radius)" }, children: label }, label)) })] }) }) });
+}
+/** Procedural two-skin fixture for visual regression captures. */
+export function HudSkinPreview({ className }) {
+    const skins = useMemo(() => [{ title: "painted cartoon", skin: { frame: { image: painted("#ffd166", "#7b3f00"), slice: [8, 8, 8, 8], fill: true }, slot: { image: painted("#66e3ff", "#12354a"), slice: [8, 8, 8, 8] }, bar: { fill: "linear-gradient(90deg,#ff6b6b,#ffd166)", track: "#24152a" } } }, { title: "thin dark overlay", skin: { frame: { image: painted("#8d99ae", "#11151c"), slice: [4, 4, 4, 4] }, slot: { image: painted("#566070", "#090b10"), slice: [4, 4, 4, 4] }, bar: { fill: "#8d99ae", track: "#090b10" } } }], []);
+    return _jsx("div", { className: className, "data-hud-skin-preview": true, style: { display: "flex", gap: 18, flexWrap: "wrap", padding: 22, background: "#0e1216", color: "#f5f7fa" }, children: skins.map((item) => _jsx(SkinCell, { ...item }, item.title)) });
+}

package/dist/hudTheme.d.ts

@@ -1,4 +1,6 @@
 import { type CSSProperties } from "react";
+import { type HudSkin } from "./hudSkin.js";
+export { hudSkinVars, type HudSkin } from "./hudSkin.js";
 /**
  * `HudTheme` (#1034, #1573): one token object that restyles every shared token-driven building
  * block at once — the atomic bars (#1033), frames, slots, the minimap ring, and the chrome the
@@ -106,6 +108,7 @@ export interface HudTheme {
     slot: HudThemeSlot;
     /** Minimap chrome ring color. */
     ring: string;
+    skin?: HudSkin;
 }
 /** Emits the CSS custom properties for a theme — spread onto any HUD ancestor to re-skin the subtree. */
 export declare function hudThemeVars(theme: HudTheme): CSSProperties;
@@ -122,6 +125,7 @@ export interface HudThemeOverrides {
     bar?: Partial<HudThemeBar>;
     slot?: Partial<HudThemeSlot>;
     ring?: string;
+    skin?: HudSkin;
 }
 /**
  * Builds a full {@link HudTheme} from per-group partials, filling the rest from

package/dist/hudTheme.js

@@ -1,8 +1,21 @@
 import {} from "react";
+import { hudSkinVars } from "./hudSkin.js";
+export { hudSkinVars } from "./hudSkin.js";
 /** Emits the CSS custom properties for a theme — spread onto any HUD ancestor to re-skin the subtree. */
 export function hudThemeVars(theme) {
     const { palette, surface, status, font, rarity, frame, bar, slot } = theme;
     return {
+        "--jg-frame-image": "none",
+        "--jg-frame-slice": "0",
+        "--jg-frame-scale": "1",
+        "--jg-frame-fill": "stretch",
+        "--jg-slot-image": "none",
+        "--jg-slot-slice": "0",
+        "--jg-slot-scale": "1",
+        "--jg-bar-skin-track": "none",
+        "--jg-bar-skin-fill": "none",
+        "--jg-skin-cursor": "auto",
+        ...hudSkinVars(theme.skin),
         // atomic-bar tokens (same names the bars read — #1033)
         "--jg-health": palette.health,
         "--jg-health-low": palette.healthLow,
@@ -146,6 +159,7 @@ export function hudTheme(overrides) {
         bar: { ...defaultHudTheme.bar, ...overrides.bar },
         slot: { ...defaultHudTheme.slot, ...overrides.slot },
         ring: overrides.ring ?? defaultHudTheme.ring,
+        skin: overrides.skin,
     };
 }
 const theme = hudTheme;

package/dist/index.d.ts

@@ -48,6 +48,8 @@ export * from "./panels.js";
 export * from "./characterSheet.js";
 export * from "./talentTree.js";
 export * from "./hudTheme.js";
+export * from "./hudSkin.js";
+export * from "./hudSkinPreview.js";
 export * from "./hudThemePreview.js";
 export * from "./hudFrame.js";
 export * from "./keyHint.js";

package/dist/index.js

@@ -48,6 +48,8 @@ export * from "./panels.js";
 export * from "./characterSheet.js";
 export * from "./talentTree.js";
 export * from "./hudTheme.js";
+export * from "./hudSkin.js";
+export * from "./hudSkinPreview.js";
 export * from "./hudThemePreview.js";
 export * from "./hudFrame.js";
 export * from "./keyHint.js";

package/dist/previewFixtures.js

@@ -2,6 +2,9 @@ import { BarsPreview } from "./barsPreview.js";
 import { HudThemePreview } from "./hudThemePreview.js";
 import { IconsPreview } from "./iconsPreview.js";
 import { StreetGeometryPreview } from "./streetGeometryPreview.js";
+import { SpriteClipPreview } from "./spriteClipPreview.js";
+import { TileLayerPreview } from "./tileLayerPreview.js";
+import { HudSkinPreview } from "./hudSkinPreview.js";
 /**
  * Registry of deterministic, engine-level preview fixtures — the *real* exported
  * `@jgengine/react` components (`HudThemePreview`, `BarsPreview`, `IconsPreview`, …) that render
@@ -35,6 +38,17 @@ export const PREVIEW_FIXTURES = {
         description: "Close-up welded road meshes for turns, unequal crossings, and five-way junctions.",
         component: StreetGeometryPreview,
     },
+    SpriteClipPreview: {
+        name: "SpriteClipPreview",
+        description: "A procedurally drawn two-frame atlas driven by the core sprite clip player.",
+        component: SpriteClipPreview,
+    },
+    TileLayerPreview: {
+        name: "TileLayerPreview",
+        description: "A procedural 3x3 atlas-backed tile layer preview.",
+        component: TileLayerPreview,
+    },
+    HudSkinPreview: { name: "HudSkinPreview", description: "Two procedural HUD skins applied to frames, bars, and inventory slots.", component: HudSkinPreview },
 };
 /** Sorted list of registered fixture names, for discovery/listing. */
 export function previewFixtureNames() {

package/dist/spriteClipPreview.d.ts

@@ -0,0 +1,6 @@
+/** Deterministic canvas-backed sprite clip fixture for renderer evidence.
+ * @internal
+ */
+export declare function SpriteClipPreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/spriteClipPreview.js

@@ -0,0 +1,72 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { createSpriteClipPlayer } from "@jgengine/core/render/sprite2d";
+/** Deterministic canvas-backed sprite clip fixture for renderer evidence.
+ * @internal
+ */
+export function SpriteClipPreview({ className }) {
+    const canvasRef = useRef(null);
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (canvas === null)
+            return;
+        canvas.width = 640;
+        canvas.height = 360;
+        const context = canvas.getContext("2d");
+        if (context === null)
+            return;
+        const atlasCanvas = document.createElement("canvas");
+        atlasCanvas.width = 64;
+        atlasCanvas.height = 32;
+        const atlasContext = atlasCanvas.getContext("2d");
+        if (atlasContext === null)
+            return;
+        for (const x of [0, 32]) {
+            atlasContext.fillStyle = "#172033";
+            atlasContext.fillRect(x, 0, 32, 32);
+            atlasContext.fillStyle = "#f4c95d";
+            atlasContext.beginPath();
+            atlasContext.arc(x + 16, 14, 9, 0, Math.PI * 2);
+            atlasContext.fill();
+            atlasContext.fillStyle = "#e76f51";
+            atlasContext.fillRect(x + 8, x === 0 ? 22 : 20, 16, 5);
+        }
+        const atlas = {
+            image: "fixture",
+            size: [64, 32],
+            frames: { idle0: { x: 0, y: 0, w: 32, h: 32 }, idle1: { x: 32, y: 0, w: 32, h: 32 } },
+            animations: { idle: { frames: ["idle0", "idle1"], fps: 2 } },
+        };
+        const player = createSpriteClipPlayer(atlas);
+        let previous = performance.now();
+        let animationFrame = 0;
+        const draw = (now) => {
+            player.advance(Math.min((now - previous) / 1000, 0.1));
+            previous = now;
+            const current = player.frame() ?? atlas.frames.idle0;
+            context.fillStyle = "#0e1216";
+            context.fillRect(0, 0, canvas.width, canvas.height);
+            context.fillStyle = "#e8edf2";
+            context.font = "700 18px system-ui";
+            context.fillText("SPRITE CLIP PREVIEW", 32, 42);
+            context.font = "14px system-ui";
+            context.fillStyle = "#9aa7b5";
+            context.fillText(`atlas frame ${player.snapshot().frameIndex + 1} / 2 · 2 fps`, 32, 68);
+            context.imageSmoothingEnabled = false;
+            context.drawImage(atlasCanvas, current.x, current.y, current.w, current.h, 256, 112, 128, 128);
+            context.strokeStyle = "#f4c95d";
+            context.strokeRect(256, 112, 128, 128);
+            context.fillStyle = "#9aa7b5";
+            context.font = "12px system-ui";
+            context.fillText("procedural atlas frames", 32, 300);
+            context.drawImage(atlasCanvas, 0, 0, 32, 32, 32, 312, 64, 64);
+            context.drawImage(atlasCanvas, 32, 0, 32, 32, 112, 312, 64, 64);
+            context.strokeStyle = "#f4c95d";
+            context.strokeRect(32 + player.snapshot().frameIndex * 80, 312, 64, 64);
+            animationFrame = requestAnimationFrame(draw);
+        };
+        animationFrame = requestAnimationFrame(draw);
+        return () => cancelAnimationFrame(animationFrame);
+    }, []);
+    return _jsx("canvas", { ref: canvasRef, className: className, style: { imageRendering: "pixelated", width: "100%", height: "100%" } });
+}

package/dist/standaloneChatPanel.d.ts

@@ -0,0 +1,38 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type ChatMessage } from "@jgengine/core/game/chat";
+import type { ChatSendOutcome } from "@jgengine/core/multiplayer/chatContract";
+type StatefulClass = string | ((expanded: boolean) => string);
+/** Message-store inputs and caller-owned styling for standalone chat. */
+export interface StandaloneChatPanelProps<T extends ChatMessage = ChatMessage> {
+    messages: readonly T[];
+    userId: string;
+    onSend: (body: string) => Promise<ChatSendOutcome | void> | ChatSendOutcome | void;
+    className?: StatefulClass;
+    logClassName?: StatefulClass;
+    inputClassName?: StatefulClass;
+    inputFieldClassName?: StatefulClass;
+    messageClassName?: string;
+    ownMessageClassName?: string;
+    style?: CSSProperties;
+    defaultExpanded?: boolean;
+    collapsedLimit?: number;
+    limit?: number;
+    maxLength?: number;
+    hotkeysEnabled?: boolean;
+    onFocus?: () => void;
+    placeholder?: string;
+    collapsedPlaceholder?: string;
+    emptyLabel?: ReactNode;
+    renderMessage?: (message: T, state: {
+        own: boolean;
+        expanded: boolean;
+        index: number;
+        count: number;
+    }) => ReactNode;
+}
+/**
+ * Headless chat interaction for external message stores. Prefer the ChatPanel entrypoint.
+ * @capability standalone-chat render persisted chat with focus controls and visible send failures
+ */
+export declare function StandaloneChatPanel<T extends ChatMessage>({ messages, userId, onSend, className, logClassName, inputClassName, inputFieldClassName, messageClassName, ownMessageClassName, style, defaultExpanded, collapsedLimit, limit, maxLength, hotkeysEnabled, onFocus, placeholder, collapsedPlaceholder, emptyLabel, renderMessage }: StandaloneChatPanelProps<T>): import("react").JSX.Element;
+export {};

package/dist/standaloneChatPanel.js

@@ -0,0 +1,55 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { DEFAULT_CHAT_BODY_LENGTH } from "@jgengine/core/game/chat";
+const classFor = (value, expanded) => typeof value === "function" ? value(expanded) : value;
+/**
+ * Headless chat interaction for external message stores. Prefer the ChatPanel entrypoint.
+ * @capability standalone-chat render persisted chat with focus controls and visible send failures
+ */
+export function StandaloneChatPanel({ messages, userId, onSend, className, logClassName, inputClassName, inputFieldClassName, messageClassName, ownMessageClassName, style, defaultExpanded = false, collapsedLimit = 3, limit = 50, maxLength = DEFAULT_CHAT_BODY_LENGTH, hotkeysEnabled = true, onFocus, placeholder = "Message the world...", collapsedPlaceholder = "Enter to chat", emptyLabel = "Press Enter to chat", renderMessage }) {
+    const [expanded, setExpanded] = useState(defaultExpanded);
+    const [draft, setDraft] = useState("");
+    const [failure, setFailure] = useState(null);
+    const [sending, setSending] = useState(false);
+    const inputRef = useRef(null);
+    const logRef = useRef(null);
+    useEffect(() => {
+        if (!hotkeysEnabled)
+            return;
+        const handleKey = (event) => {
+            if (event.defaultPrevented || event.isComposing || event.key !== "Enter")
+                return;
+            if (event.target?.closest?.("input, textarea, select, button, [contenteditable]:not([contenteditable=false])"))
+                return;
+            event.preventDefault();
+            inputRef.current?.focus({ preventScroll: true });
+        };
+        window.addEventListener("keydown", handleKey);
+        return () => window.removeEventListener("keydown", handleKey);
+    }, [hotkeysEnabled]);
+    useEffect(() => {
+        if (expanded && logRef.current !== null)
+            logRef.current.scrollTop = logRef.current.scrollHeight;
+    }, [expanded, messages.length]);
+    const visible = messages.slice(-Math.max(1, expanded ? limit : collapsedLimit));
+    return _jsxs("section", { "data-chat-panel": true, "data-expanded": expanded, className: classFor(className, expanded), style: style, children: [_jsx("div", { role: "log", "aria-live": "polite", ref: logRef, className: classFor(logClassName, expanded), children: visible.length === 0 ? emptyLabel : visible.map((message, index) => {
+                    const own = message.fromUserId === userId;
+                    return _jsx("div", { "data-own-message": own || undefined, className: [messageClassName, own ? ownMessageClassName : undefined].filter(Boolean).join(" "), children: renderMessage?.(message, { own, expanded, index, count: visible.length }) ?? _jsxs(_Fragment, { children: [message.fromUserId, ": ", message.body] }) }, message.id);
+                }) }), _jsx("form", { className: classFor(inputClassName, expanded), onSubmit: (event) => {
+                    event.preventDefault();
+                    if (sending || draft.trim().length === 0)
+                        return;
+                    const body = draft;
+                    setSending(true);
+                    setFailure(null);
+                    void Promise.resolve().then(() => onSend(body)).then((outcome) => {
+                        if (outcome && !outcome.ok)
+                            setFailure(outcome.reason ?? "Could not send message");
+                        else
+                            setDraft((current) => current === body ? "" : current);
+                    }).catch((error) => setFailure(error instanceof Error ? error.message : "Could not send message")).finally(() => setSending(false));
+                }, children: _jsx("input", { ref: inputRef, "aria-label": "Chat message", "aria-busy": sending, className: classFor(inputFieldClassName, expanded), value: draft, maxLength: maxLength, placeholder: expanded ? placeholder : collapsedPlaceholder, onChange: (event) => setDraft(event.target.value), onFocus: () => { onFocus?.(); setExpanded(true); }, onBlur: () => setExpanded(false), onKeyDown: (event) => { if (event.key === "Escape") {
+                        event.currentTarget.blur();
+                        event.stopPropagation();
+                    } } }) }), failure !== null && _jsx("p", { role: "alert", children: failure })] });
+}

package/dist/tileLayerPreview.d.ts

@@ -0,0 +1,4 @@
+/** Deterministic canvas-backed tile-layer fixture for textured tile presentation evidence. */
+export declare function TileLayerPreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/tileLayerPreview.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+/** Deterministic canvas-backed tile-layer fixture for textured tile presentation evidence. */
+export function TileLayerPreview({ className }) {
+    const canvasRef = useRef(null);
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        const context = canvas?.getContext("2d");
+        if (canvas === null || context == null)
+            return;
+        canvas.width = 640;
+        canvas.height = 360;
+        context.fillStyle = "#0e1216";
+        context.fillRect(0, 0, canvas.width, canvas.height);
+        context.fillStyle = "#e8edf2";
+        context.font = "700 18px system-ui";
+        context.fillText("TEXTURED TILE LAYER PREVIEW", 32, 42);
+        context.font = "14px system-ui";
+        context.fillStyle = "#9aa7b5";
+        context.fillText("3 × 3 procedural atlas map · one layer", 32, 68);
+        const colors = { a: "#355070", b: "#6b705c", c: "#3a86a8" };
+        const map = ["aba", "bcb", "aba"];
+        const size = 72;
+        for (let row = 0; row < map.length; row += 1) {
+            for (let column = 0; column < map[row].length; column += 1) {
+                context.fillStyle = colors[map[row][column]];
+                context.fillRect(212 + column * size, 104 + row * size, size - 2, size - 2);
+            }
+        }
+        context.strokeStyle = "#f4c95d";
+        context.strokeRect(212, 104, size * 3 - 2, size * 3 - 2);
+        context.fillStyle = "#9aa7b5";
+        context.font = "12px system-ui";
+        context.fillText("procedural atlas tiles · floor / wall / water", 32, 344);
+    }, []);
+    return _jsx("canvas", { ref: canvasRef, className: className, style: { imageRendering: "pixelated", width: "100%", height: "100%" } });
+}

package/dist/useServerSession.d.ts

@@ -0,0 +1,11 @@
+import { type GameRuntimeTransport } from "@jgengine/core/runtime/transport";
+/**
+ * Joins a host and exposes a retryable blocking state until membership is confirmed.
+ * @capability server-session join a multiplayer host with status, retry, and teardown
+ */
+export declare function useServerSession(transport: GameRuntimeTransport, gameId: string, preferredServerId?: string): {
+    serverId: string | null;
+    status: "joining" | "joined" | "failed";
+    failureReason: string | null;
+    retry: () => void;
+};

package/dist/useServerSession.js

@@ -0,0 +1,39 @@
+import { useCallback, useEffect, useState } from "react";
+import { createTransportSessionId } from "@jgengine/core/runtime/transport";
+/**
+ * Joins a host and exposes a retryable blocking state until membership is confirmed.
+ * @capability server-session join a multiplayer host with status, retry, and teardown
+ */
+export function useServerSession(transport, gameId, preferredServerId) {
+    const [attempt, setAttempt] = useState(0);
+    const [session, setSession] = useState({ serverId: null, status: "joining", failureReason: null });
+    const retry = useCallback(() => setAttempt((value) => value + 1), []);
+    useEffect(() => {
+        let disposed = false;
+        let serverId = null;
+        const sessionId = createTransportSessionId();
+        setSession({ serverId: null, status: "joining", failureReason: null });
+        void transport.joinServer({ gameId, serverId: preferredServerId, sessionId }).then((result) => {
+            if (!result.ok) {
+                if (!disposed)
+                    setSession({ serverId: null, status: "failed", failureReason: result.reason });
+                return;
+            }
+            if (disposed) {
+                void transport.leaveServer({ serverId: result.serverId, sessionId }).catch(() => undefined);
+                return;
+            }
+            serverId = result.serverId;
+            setSession({ serverId, status: "joined", failureReason: null });
+        }).catch((error) => {
+            if (!disposed)
+                setSession({ serverId: null, status: "failed", failureReason: error instanceof Error ? error.message : "Connection failed" });
+        });
+        return () => {
+            disposed = true;
+            if (serverId !== null)
+                void transport.leaveServer({ serverId, sessionId }).catch(() => undefined);
+        };
+    }, [transport, gameId, preferredServerId, attempt]);
+    return { ...session, retry };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "React UI layer for JGengine: GameProvider, hooks, and headless primitives over @jgengine/core.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.18.0"
+    "@jgengine/core": "^0.19.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/skills/ce-handoff/SKILL.md

@@ -143,7 +143,7 @@ When sufficient, return a concise orientation: objective, progress, decisions, c
 
 ## JGengine notes
 
-- Multi-session engine work often spans `docs/plans/`, GitHub issues, and stacked PRs — point at those; do not paste full plan bodies.
+- Multi-session engine work spans GitHub issues and PRs — point at those; do not paste full plan bodies.
 - Prefer `bun run agent:bootstrap --check` status, branch names, and PR links as state anchors.
 - Local parallelism uses `.claude/worktrees/`; never invent `C:\tmp\…` Codex-shared trees.
-- Papercuts and durable process changes belong in `PAPERCUTS.md` / skills, not only the handoff.
+- Durable process changes belong in skills, not only the handoff.

package/skills/jgengine/SKILL.md

@@ -5,10 +5,14 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 # JGengine intake and router
 
-Read the JGengine README for package truth, commands, layering, and license — the repo-root [`README.md`](../../../README.md) in the monorepo, or [jgengine.com](https://jgengine.com) from a scaffolded consumer project (where the relative link does not resolve). This skill decides what to load; it is not an engine manual.
+This skill decides what to load; it is not an engine manual. Package map, commands, layering, and license live in the JGengine README (repo-root [`README.md`](../../../README.md) in the monorepo, [jgengine.com](https://jgengine.com) from a created project); open it when you need one of those facts.
+
+A created project installs only `jgengine`, `jgengine-editor`, `jgengine-verify`, `game-design`, and `jgengine-ui`. Run `npx jgengine skills -p --all` before loading any other domain named below. Those projects do not ship `api.md`; read exact signatures from the `.d.ts` files under `node_modules/@jgengine/<pkg>/dist/`.
 
 ## 1. Establish the target
 
+For greenfield builds, write `src/art-direction.md` before any code.
+
 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
@@ -18,7 +22,7 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 - HUD/menu states and **custom** UI art direction (compose shipped building blocks + HudTheme; no unskinned stock 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/*`.
+Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player model, editor scene); a grid, card, tile, or other board game with no 3D scene takes `create --2d` (a `board` world drawn by GameUI over `@jgengine/core/puzzle/cellGrid`). 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/*`.
 
 For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
 
@@ -44,9 +48,9 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
-0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search `capabilities.md` by intent; it maps needs to imports. Outside the monorepo (or before a domain skill is even loaded), `npx jgengine find <intent>` greps every shipped capability index at once and prints the primitive + import — reach for it the moment you're tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. If you're writing a `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob, a shipped drop-in almost certainly exists (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
-2. Open `api.md` only when exact signatures or export inventory are needed.
+0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) (`combat-loop`, `loot`, `world-drops`, `click-target`, `ability-bar`, `hitscan-weapon`, `rolled-gear`, `enter-vehicle` and more); `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
+1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); in the monorepo, `grep -i "<intent>" .claude/skills/*/capabilities.md` does the same. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
+2. Open `api.md` (monorepo) or the package `.d.ts` only when exact signatures are needed; grep it, never read it whole.
 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.