@jgengine/react 0.18.0 → 0.18.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-The lockstep game SDK set is `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`
+The lockstep game SDK set is `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets}`
 (this file’s 0.x.y releases). The CLI package `jgengine` and `@jgengine/github` use
 **separate** version lines and may lag. Format follows [Keep a Changelog](https://keepachangelog.com);
 each release **leads with a Migrate block** — the concrete steps to move a game
@@ -17,6 +17,13 @@ between (`--json` for structured output).
 
 ## [Unreleased]
 
+### Fixed
+
+- Separate SDK publication validation from external Games quality checks while retaining the full local and main-branch gates.
+
+- Correct foot-IK endpoint recomputation after hip rotation; verify reachable targets and clamping without changing bone lengths.
+- Restore release CI prerequisites and make catalog-loader tests independent of the external Games checkout.
+
 <!--
 Every PR that changes `packages/*/src` records its consumer-facing change here, so
 the next release's notes are complete by construction. Add a bullet under the right
@@ -26,6 +33,106 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.18.1
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.18.1`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.15.1`; `@jgengine/github` is `0.5.1`.
+- Declare `topology: "shared"` on runtime definitions. Shared Convex hosts migrate the bounded legacy roster into indexed membership and per-player session rows; use `getServerCapacity` for stable lobby subscriptions.
+- Put every command's read scope on its definition. Omitted scopes now load the actor and no chunks; explicitly request whole-world reads only where needed. Trusted host mutations can compose writes through `helpers.runCommand`.
+- Handle typed join outcomes (`ok` and `reason`) or use `useServerSession` and `JoinGate`. Pass runtimes to `jgengineCronSpecs`; tick registration requires an actual tick hook.
+- Declare currency precision with `decimals` and remove game-side cent conversions. Public amounts stay in major units and wallet writes round through integer minor units.
+- Replace custom presence, chat, territory and tick batching with `createWorldPresenceStore`, chat helpers, chunk territory, and `forEachOnlinePlayer`. Legacy claim backfills must finish before removing their old schema.
+
+### Added
+
+- Indexed shared membership and capacity rows, bounded neighborhood poses with 100 ms server/client gates, durable rate limits, authenticated diagnostics and bounded retention.
+- Territory footprint planning and atomic placement claims, chat validation and headless chat/join/territory surfaces, elapsed accrual, safe quantities, and player-profile reset through the initializer.
+- An explicit `--patch` release option.
+
+### Added
+
+- Added smooth interpolation for remote presence player poses.
+- WS ping/pong messages and client RTT sampling on the backend object.
+- Added skin-backed HUD chrome variables, font loading, and the procedural `HudSkinPreview` fixture.
+
+- Core gamepad snapshot model, deadzone/curve resolver, and controller glyph labels.
+- Shell gamepad source polls connected pads, merges analog actions, supports synthetic `?gamepad=1` input, and exposes `ctx.input.rumble`.
+- Core action context stacks layer gameplay, menus, and passthrough overlays with snapshot/restore; shell action tracking now respects the active context.
+- Shell audio now supports listener orientation and per-sound Web Audio panners. `setListenerPose` accepts `{ position, forward, up }`; bare positions remain supported for one release.
+- Core perception tracks deterministic sight, hearing, occlusion, and bounded observation memory for AI.
+- `syncWorldColliders` now keeps terrain and static object colliders synchronized with a physics backend.
+- Core decision graphs provide deterministic selector, sequence, condition, action, and utility runtimes with snapshot/restore.
+- Core behavior descriptors can run registered decision graphs at the interest-scheduler cadence.
+- Core navigation meshes provide deterministic polygon routing, off-mesh links, closest-point queries, and nav raycasts.
+- WS sessions now issue resume tickets and retain disconnected memberships for a 15-second grace window, allowing reconnects to rejoin without replacing player state.
+- Shell entity sprites can play atlas-backed sprite clips while preserving raw texture sprites.
+- Tilemap layers can render atlas-backed textured tiles as one instanced quad mesh with parallax.
+- Core pixel-perfect orthographic frustum and pixel-grid camera snapping are available to shell cameras.
+- Core sprite atlas adapters and deterministic 2D sprite clip playback primitives.
+- `src/art-direction.md` scaffold and `check-art-direction` gate for created games.
+- Host-authoritative shell sessions now expose each accepted world frame to the local prediction buffer, reconciling and snapping the possessed pose only when drift exceeds its threshold.
+- Shared GLTF loader configuration for Draco and KTX2-compressed assets, with CDN defaults and renderer capability detection.
+- Material map overrides now support metalness, emissive, and height maps on standard and physical materials.
+- Presentation and editor documents now accept gradient, HDRI/EXR, and cube-map environment sources.
+- Authored `light` markers now feed bounded point/spot punctual lights with an eight-light default budget and editor warning.
+- Graphics profiles now resolve per-tier render scale, shadow budgets, culling distance, particles, cascades, and post stages; games can override them with `defineGame({ graphics })`.
+- `defineGame({ physics: { backend } })` now adopts a capsule character controller for shell/headless movement and registers the backend simulation after movement, including floor collision and step-up behavior.
+- Added the `physics-probe` dev scene for Rapier crate, ragdoll, and vehicle motion.
+- Assets now expose import-spec validation and magic-byte classification for supported source files.
+- Hosted WS sessions now support spectator joins, viewer roles, throttled low-priority snapshot modules, and default command rate limits.
+- `@jgengine/navbake` bakes deterministic navigation meshes and editor documents can store named bake data.
+- Core tactical queries derive cover points and score bounded candidate positions.
+- Added createSnapshotBuffer for delayed snapshot interpolation.
+
+### Migrate
+
+- `AudioEngine.setListenerPose` now accepts `{ position, forward, up }`. Bare `Vec3` positions remain compatible for one release and use forward `[0, 0, -1]` with up `[0, 1, 0]`.
+- **Hosted world stores are asynchronous.** Implement `HostedWorldStore.load()` and `save()` as `Promise`-returning methods and construct persisted sessions with `createHostedWorldSessionAsync`; synchronous tests can keep using `memoryWorldStore`.
+- **Look presets now default to `neutral`.** Games that relied on the previous implicit cinematic
+  sky/post stack should set `look: "photoreal"` (or keep `look: "cinematic"`) explicitly.
+
+- **`ServerTickPlan.due` is `{ id, runs }[]` instead of a repeated id list.** `planServerTick` repeated a system id once per missed interval, and the obvious way to consume that — `due.includes(id)` or a `Set` — ran the system once while the returned anchor had already advanced by every repeat, silently dropping the catch-up work. A host now reads `runs` (or `tickRunCount(plan, id)`) and loops that many times.
+- **`CommandDef.validate` / `CommandDef.apply` take a fourth argument, `nowMs`.** Existing implementations that ignore it are unaffected. Commands that took a `now` in their `input` should read this instead — the client supplied the old one.
+
+### Changed
+
+- Hosted game runner queues authoritative inputs by simulation tick and applies the in-force frame each fixed step.
+- Create scaffolds now use a 60 Hz simulation with interpolation enabled by default.
+
+- Rigged `ModelConfig` entries can opt into shell foot IK with named thigh/shin/foot bones; the driver raycasts the shared scene terrain, solves each chain, and fades corrections while airborne.
+
+- Animation graph clips may carry root-bone position tracks; states with `rootMotion: true` return the sampled displacement and the shell applies it to the entity while restoring the root bone's bind translation.
+
+- Added renderer-free two-bone, FABRIK, and look-at inverse-kinematics solvers to `@jgengine/core`.
+
+- Shell model animation now routes states and one-shots through the shared animation graph runtime.
+
+- CI now clones the external games repository with `GAMES_CLONE_TOKEN` and runs the game shape, content, front-end, art-direction, and feel gates against it; those gates fail loudly in CI when the checkout is missing while remaining no-ops locally.
+
+- `jgengine create` now accepts `--player`, `--ground`, and `--scene` so generated games can choose their model, terrain ground, and empty or starter scene.
+
+- **Directional shadow frustum config actually reaches the GPU.** `shadowCameraSize` on a single (non-cascaded) shadow light was silently inert: the shell wrote the bounds through R3F pierced props and nothing refreshed the shadow camera's projection matrix, so three rendered depth with its default ~10-unit box at the world origin — the reason no open-world game had cast shadows away from spawn. The shell now syncs the projection (and reallocates the shadow map when `shadowMapSize` changes). `bloom.threshold`'s doc also now states it measures raw HDR before the exposure stage.
+- **CSM (`cascades > 1`) no longer over-lights streamed meshes or clobbers material shaders.** Cascade scoping is injected per material, but the scan ran every 30 frames, so a model that streamed in rendered lit by every cascade light at once (a cascades× sun) until the next scan — a sub-second flash on desktop, the whole shot on capture rigs. The scan now runs every frame behind a WeakSet, and `setupMaterial` chains with a material's own `onBeforeCompile` (rim light, detail maps) instead of replacing it.
+
+- **The host's wall clock reaches the runtime hooks.** `RuntimeInitContext` (so `onInit`, `onNewPlayer`, and `onTick` alike) carries `nowMs`, the host timestamp for that call. Anything keyed to real time — a UTC date rollover, a `lastTickAt` anchor read by non-tick code, an RNG seed or `createdAt` stamp — reads it rather than accumulating `dtSeconds` against an epoch persisted in the snapshot, which drifts by whatever the tick loses to stalls and `maxCatchUp` clamping. `GameRuntime.hydrate` takes an optional `nowMs`; `tick`, `joinPlayer`, and `runCommand` take an optional trailing `nowMs`. All default to `Date.now()`, and the shipped WS and Convex hosts pass the timestamp they already computed to plan the tick.
+- **Imported models cast and receive shadows.** `cloneModelScene` never set `castShadow`/`receiveShadow` on a GLB's meshes (only the magenta fallback box had them), so every catalog model in every game rendered shadowless however the lights were configured. Cloned models now default to `ModelConfig.shadows: "both"`; set `"cast"`, `"receive"`, or `"none"` per model (foliage cards, decals, viewmodels).
+- **`jgengine create` installs `game-design` and `jgengine-ui` by default.** The minimal skill set was intake, editor, and verify, so a real project never saw the greenfield design contract or the UI art-direction template unless someone ran `jgengine skills --all`; `MINIMAL_GAME_SKILLS` now carries both.
+
+### Added
+
+- **Host-authoritative world replication over WS.** Hosted sessions expose revision-cursor pulls, so server subscribers receive compact world diffs and automatically recover with a fresh baseline after missed revisions; viewer-specific projections still receive per-viewer baselines.
+- **Animation graph — `ModelAnimationConfig.graph` and `@jgengine/core/anim/animGraph`.** A serializable, layered animation state machine: `clip`, `blend1D`, and `blend2D` states, transitions as data (parameter comparisons, consumed triggers, exit times, crossfade durations), masked and additive layers, and clip events. `createAnimGraphRuntime` is headless and owns every clip's playback time and weight, so the shell's mixer only seeks and weights actions (`useModelAnimation` takes the graph path when `graph` is set) and a headless host or test advances the same graph without three.js. The shell feeds the entity's smoothed ground speed as `speed`, merges parameters from the entity blackboard key `ANIM_PARAMS_KEY`, arms triggers from `entity.animation` / `combat.hitReaction` / `entity.died`, and emits the new `animation.event` for clip events (foot plants, hit frames). `locomotionGraph()` builds the previous idle/walk/run plus one-shot behavior as one authored graph.
+- **`PhysicsBackend` — one interface over interchangeable rigid-body solvers.** `@jgengine/core/physics/physicsBackend` defines bodies (`BodyDesc` with a box / sphere / capsule / convex / trimesh / heightfield shape union, quaternion rotation, angular velocity, layers and mask, CCD flag), joints, `raycast`, `shapecast`, `overlap`, contact events, and `snapshot`/`restore` with stable handles; `capabilities` says what a backend really does. `createPhysicsWorldBackend` puts the zero-dependency `PhysicsWorld` behind it (translation-only, non-box shapes collide as their bounding box, warned once), and `runPhysicsBackendConformance` is the behavioral contract any adapter runs. `createCharacterController` (`@jgengine/core/movement/characterController`) is the first consumer: a capsule collide-and-slide controller with step-up, slope limit, ceiling test, crouch with headroom check, ground snapping, and moving-platform carry, pure over any backend and retunable during play.
+- **Fixed-step simulation with render interpolation — `defineGame({ simulation: { hz } })` and `ctx.sim`.** Every driver (shell frame, HUD-only, headless runner, authoritative host) now steps through one `SimLoop` (`@jgengine/core/runtime/simLoop`): a fixed `hz` accumulates real time and runs equal-dt steps behind a catch-up cap (`maxCatchUpSteps`, default 5) instead of spiralling; the default stays `"variable"` (one step per frame) so existing games are unchanged until they opt in. Under a fixed rate the shell renders entities at `ctx.sim.renderPose(id)` — the pose interpolated between the previous and current step (`@jgengine/core/runtime/poseInterpolation`), with teleports past `snapDistance` snapping — so a 20 Hz sim no longer stutters. `ctx.sim.tick()` counts steps and `InputFrame.tick` carries it over the wire; `ctx.sim.addStage({ phase, run })` inserts per-step work before movement, after movement, or after `onTick` (the hook a physics backend or netcode buffer registers through). System fixed-rate groups gain the same substep cap. For replay and rollback: `seededRng` streams expose `state()`/`restore()` (`rngStateOf`/`restoreRng` for any `ctx.rng`), `createSimSnapshotRegistry`/`createContextSimSnapshot` capture world, clock, loop, and rng cursor together, `createInputRecorder` logs frames by tick, and `HeadlessRunner` gains `snapshot()`/`restore()`/`tick()` — a test proves that replaying recorded input from a snapshot reproduces every entity pose.
+- **City and street races share one generator.** `extractCircuitRoute` lifts a sealed-off race lap from a city street network; city rules, editor baking, playground modes, and the shell renderer carry the same street dials through the resulting race surface and junction dressing.
+- **`ctx.particles` — the game-reachable particle seam.** Game logic queues one-shot bursts (`ctx.particles.burst(config, count)`) and keyed standing emitters (`attach`/`retune`/`detach`, with `follow` to track a scene entity) as plain serializable data (`@jgengine/core/vfx/particleDirector`); the shell auto-mounts a renderer that turns them into pooled GPU point clouds via the existing `createParticleSystem`/`ParticleField`, caps pool sizes by graphics quality (low 128 / medium 256 / high 512 per effect, degrading density instead of dropping effects), and reaps finished bursts. Dust, sparks, exhaust, and debris no longer require forking the shell; headless tests assert the requested effects straight off the director.
+- **`resolveSourceWalkerStep(source, cache, position, stepX, stepZ, options)`** (`@jgengine/core/movement/solidObstacles`) — `resolveWalkerStep` with no `GameContext`, for movement rules that live in a pure package with no React or three.js. `SolidObstacleSource`, `ObstacleReachCache`, `createObstacleReachCache`, `sourceObstacleReach`, `sourceObstaclesNear`, and `slideStep` are public alongside it instead of `@internal`, so a game no longer has to push the resolver up into its app layer and inject it back down. `resolveWalkerStep`'s doc now states that it already resolves X and Z separately, so a caller doing its own axis-split must hand it one axis per call.
+- **`tickRunCount(plan, id)`** (`@jgengine/core/time/serverTick`) — how many runs a plan owes a system, or 0 when it is not due.
+- **`grass()` exposes the clump/lighting knobs its shader already had.** `GrassEnvironmentConfig` gains optional `bladeBend`, `tuftRadius`, `colorVariation`, and `normalLift`, forwarded by the shell's environment renderer — a world descriptor can now author bushy wind-combed scrub instead of the fixed lawn-blade look; defaults unchanged.
+- **`TerrainDetailConfig.sweeps`** — the detail shader's two macro colour sweeps (sun-dried patches, cooler wet pockets) take per-world RGB multipliers instead of hardcoded meadow tints. The old green-leaning "lush pocket" default painted moss onto arid/ashen biomes; defaults are unchanged, so a desert world should set warm/neutral `sweeps` explicitly.
+- **`@jgengine/rapier`** — a Rapier-backed `PhysicsBackend` adapter with native capsules, shapecasts, rotation, CCD, joints, and collision queries.
+
 ## 0.18.0
 
 ### Migrate
@@ -165,13 +272,18 @@ At publish, rename this heading to the new version and mirror the entries into
 - **`advanceStepCadence` (`@jgengine/core/audio/stepCadence`) — distance-driven footstep timing.** Pure state-in/state-out: feed it the ground distance a mover covered this frame and it reports how many steps landed and which foot led, so foley stays locked to distance instead of a wall-clock timer that desyncs the moment speed changes. Configurable stride, per-advance `strideScale` for crouch/sprint, and a shorter first step from rest so walking off is heard immediately.
 - **`resolveMusicState` (`@jgengine/core/audio/musicState`) — combat-reactive soundtrack selection.** The engine could already crossfade themes but nothing decided *when*, so every game re-handrolled the threshold and got a track that flapped as one enemy walked in and out of range. Give it a tier ladder (intensity → theme) and it resolves the theme to play: escalation is immediate, de-escalation waits for the tier's `holdMs` and needs intensity to fall a `release` margin below the tier it is leaving. Pure and serialisable.
 - **Synth voices take a `sustain` (`ToneVoice`/`NoiseVoice`).** Seconds held at full gain before the decay. Default 0 preserves every existing patch. Without it there was no way to author a *sustained* sound at all: every voice decayed to silence inside its duration, so a patch rendered once and looped as an ambient bed pulsed audibly once per loop. Set `sustain` to `duration` for a flat wind, rain, or machine-hum bed that loops seamlessly.
-
+- **A street race is a section of a city, sealed off.** `extractCircuitRoute(network, rules)` (`@jgengine/core/world/raceCircuit`) lifts a closed lap out of an existing street network — the same asphalt the open world already drives on — and seals every side street leaving it. Returns checkpoints ready for `raceTrack()`, start/finish, grid, corners, kerbs, and sectors. Circuit-mode networks take the same path (their loop edges are the cycle). The city volume kind gains a Race group (`race`, `raceLapLength`, `raceArterial`, …) that resolves a world-space `ResolvedRace` on `ResolvedCity.race`; `CityRenderer` draws the lap surface, kerbs, start/finish, grid, and barrier seals. Playground adds a Street race mode over the same shared slider set.
+- **Parked vehicles and junction signals on a city district.** `CityRules.parkedCars` / `signals` seed curb and pad fleets plus mast-arm signals (arterials) and sign posts (the rest); `ResolvedCity.vehicles` / `signals` hand them to `CityRenderer`.
 - **`ModelMaterialOverride.rim` — a fresnel rim light on any entity/object model.** `{ color, strength, power }` adds a bright edge where the surface turns away from the viewer, patched into the material's own shader so it shadows, fogs, and tonemaps with the body rather than floating in front of it. This is the standard fix for an actor that shares a value band with its ground: no albedo choice separates a body from terrain lit by the same key, but an edge does. Omit for no rim (default).
 
 ### Fixed
 
 - **Noise voices longer than the shared noise buffer no longer go silent partway through.** The 1-second buffer is sampled from a random offset, so any `NoiseVoice` whose duration exceeded the remainder ran off the end and finished in silence — invisible on short impact bursts, fatal for anything sustained. The source now wraps; the voice still ends on time.
 
+- **CityRenderer junctions use the welded carriageway-union seam end-to-end.** District roads go through `buildTrimmedIntersections` + `buildIntersectionMarkings` with the same compact opts as StreetGeometryPreview / playground (`curbReturnRadius: 2`, `apronMargin: 0.25`). Plaza hull aprons, fallback discs, and fat zebra ladders are gone; race resurfacing stops at junction mouths so welded patches stay visible.
+- **Denser urban fabric for metro/Manhattan districts.** Commercial class setbacks/spacing tighten toward a streetwall; slabs/towers pick L-plans and mid-block courts; dense blocks push footprints to the curb and paint courtyards as hard courts rather than lawn leftovers.
+- **City and track are one slider surface again.** `CityRules` and the editor `generate_streets` bake now forward every `StreetNetworkRules` dial (`elevation`, `maxGrade`, `compactness`, `sidewalkWidth`, `outline`, `residentialBranches`); `check-street-rule-parity` fails CI if either drifts. Playground no longer hides layout sliders when you switch modes — modes are presets over one shared set.
+- **City facades dissolve their window stripes before they alias into speckled static**, and ground floors now read as storefronts rather than repeating floor 30. Block interiors paint developed fabric instead of raw lawn, and crosswalks only land at real junctions.
 - **`terrain({ detail: { material: { tint } } })` separates a ground texture's grain from its hue.** A detail material's colour map used to replace the terrain's authored colour outright, so the biome palette, macro sweeps, and slope-rock blend under it were painted over and a whole region flattened to the texture's single hue — despite the API documenting that it "blends with, never replaces". `tint` defaults to 1 (the existing behaviour, so no shipped game changes); drop it toward 0 to keep the authored colour and take only the map's light and shade.
 - **`sky({ gradientExponent, cloudiness })` are now authorable — and `sky()` no longer silently drops them.** `gradientExponent` controls how fast the gradient reaches `zenithColor` off the horizon (default 0.65, unchanged): below 1 pulls the zenith hue down into the frame, which is what an eye-level camera in flat terrain actually needs — at the default the sky reads as one horizon-coloured wash however saturated the authored zenith is. `cloudiness` (default 0.35, unchanged) is the procedural cloud-band opacity.
 - **A model that throws while rendering is now reported instead of vanishing (#1588).** `ModelFallbackBoundary` swapped in its fallback (usually nothing) and stayed silent: `probes.fallbacks` stayed empty, no warning was logged, and an entity simply disappeared. It now reports a new `renderError` fallback cause on every failed render and warns once with the model url and the caught error.

package/dist/bars.js

@@ -87,6 +87,7 @@ function BarView({ fraction, valueText, config, label, width = 200, segments, en
             height: cssVar("height"),
             border: `${cssVar("frameWidth")} solid ${cssVar("frame")}`,
             background: cssVar("track"),
+            backgroundImage: "var(--jg-bar-skin-track, none)",
             boxShadow: cssVar("bevel"),
             overflow: "hidden",
             boxSizing: "border-box",
@@ -95,7 +96,7 @@ function BarView({ fraction, valueText, config, label, width = 200, segments, en
                     position: "absolute",
                     inset: 0,
                     width: `${fraction * 100}%`,
-                    background: fill,
+                    background: "var(--jg-bar-skin-fill, " + fill + ")",
                     transition: "width 160ms ease",
                 } }), _jsx("div", { style: {
                     position: "absolute",

package/dist/chat.d.ts

@@ -1,3 +1,4 @@
+import { type StandaloneChatPanelProps } from "./standaloneChatPanel.js";
 import { type ReactNode } from "react";
 import type { ChatMessage } from "@jgengine/core/game/chat";
 import type { ChatSync, ChatTransport } from "@jgengine/core/multiplayer/chatContract";
@@ -7,11 +8,12 @@ import type { ChatSync, ChatTransport } from "@jgengine/core/multiplayer/chatCon
  * render or inside useMemo — so subscriptions survive re-renders.
  */
 export declare function chatTransportFromSync(sync: ChatSync): ChatTransport;
-export declare function ChatLog({ channelId, limit, className, messageClassName, renderMessage, }: {
+export declare function ChatLog({ channelId, limit, className, messageClassName, ownMessageClassName, renderMessage, }: {
     channelId: string;
     limit?: number;
     className?: string;
     messageClassName?: string;
+    ownMessageClassName?: string;
     renderMessage?: (message: ChatMessage) => ReactNode;
 }): import("react").JSX.Element;
 export declare function ChatInput({ channelId, className, inputClassName, buttonClassName, placeholder, sendLabel, onSent, onRejected, }: {
@@ -33,16 +35,19 @@ export declare function ChannelTabs({ channels, active, onSelect, className, tab
     activeTabClassName?: string;
     renderTab?: (channelId: string, isActive: boolean) => ReactNode;
 }): import("react").JSX.Element | null;
-export declare function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, renderTab, onRejected, }: {
+declare function ContextChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, ownMessageClassName, defaultExpanded, toggleLabel, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, renderTab, onRejected, }: {
     channels?: readonly string[];
     initialChannel?: string;
     limit?: number;
     className?: string;
+    defaultExpanded?: boolean;
+    toggleLabel?: ReactNode;
     tabsClassName?: string;
     tabClassName?: string;
     activeTabClassName?: string;
     logClassName?: string;
     messageClassName?: string;
+    ownMessageClassName?: string;
     inputClassName?: string;
     inputFieldClassName?: string;
     sendButtonClassName?: string;
@@ -52,3 +57,6 @@ export declare function ChatPanel({ channels, initialChannel, limit, className,
     renderTab?: (channelId: string, isActive: boolean) => ReactNode;
     onRejected?: (reason: string) => void;
 }): import("react").JSX.Element | null;
+/** Chat behavior over a game context or externally supplied server messages. */
+export declare function ChatPanel<T extends ChatMessage = ChatMessage>(props: Parameters<typeof ContextChatPanel>[0] | StandaloneChatPanelProps<T>): import("react").JSX.Element;
+export {};

package/dist/chat.js

@@ -1,4 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { StandaloneChatPanel } from "./standaloneChatPanel.js";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { useGameContext } from "./provider.js";
 import { useChat } from "./hooks.js";
@@ -24,7 +25,8 @@ export function chatTransportFromSync(sync) {
         },
     };
 }
-export function ChatLog({ channelId, limit, className, messageClassName, renderMessage, }) {
+export function ChatLog({ channelId, limit, className, messageClassName, ownMessageClassName, renderMessage, }) {
+    const ctx = useGameContext();
     const messages = useChat(channelId, limit === undefined ? undefined : { limit });
     const scrollRef = useRef(null);
     useEffect(() => {
@@ -32,11 +34,12 @@ export function ChatLog({ channelId, limit, className, messageClassName, renderM
         if (node !== null)
             node.scrollTop = node.scrollHeight;
     }, [messages.length]);
-    return (_jsx("div", { ref: scrollRef, className: className, "data-chat-log": channelId, children: messages.map((message) => (_jsx("div", { className: messageClassName, "data-chat-message": true, "data-from": message.fromUserId, children: renderMessage !== undefined ? (renderMessage(message)) : (_jsxs(_Fragment, { children: [_jsx("span", { "data-chat-from": true, children: message.fromUserId }), _jsx("span", { "data-chat-body": true, children: message.body })] })) }, message.id))) }));
+    return (_jsx("div", { ref: scrollRef, className: className, "data-chat-log": channelId, children: messages.map((message) => (_jsx("div", { className: [messageClassName, message.fromUserId === ctx.player.userId ? ownMessageClassName : undefined].filter(Boolean).join(" "), "data-own-message": message.fromUserId === ctx.player.userId || undefined, "data-chat-message": true, "data-from": message.fromUserId, children: renderMessage !== undefined ? (renderMessage(message)) : (_jsxs(_Fragment, { children: [_jsx("span", { "data-chat-from": true, children: message.fromUserId }), _jsx("span", { "data-chat-body": true, children: message.body })] })) }, message.id))) }));
 }
 export function ChatInput({ channelId, className, inputClassName, buttonClassName, placeholder, sendLabel, onSent, onRejected, }) {
     const ctx = useGameContext();
     const [value, setValue] = useState("");
+    const [failure, setFailure] = useState(null);
     const chat = ctx.game.chat;
     if (chat === undefined)
         return null;
@@ -44,13 +47,15 @@ export function ChatInput({ channelId, className, inputClassName, buttonClassNam
         event.preventDefault();
         const result = chat.send(ctx.player.userId, channelId, value);
         if ("reason" in result) {
+            setFailure(result.reason);
             onRejected?.(result.reason);
             return;
         }
+        setFailure(null);
         setValue("");
         onSent?.(result.message);
     };
-    return (_jsxs("form", { className: className, "data-chat-input": channelId, onSubmit: submit, children: [_jsx("input", { className: inputClassName, type: "text", value: value, placeholder: placeholder, onChange: (event) => setValue(event.target.value) }), _jsx("button", { type: "submit", className: buttonClassName, "data-chat-send": true, children: sendLabel ?? "Send" })] }));
+    return (_jsxs("form", { className: className, "data-chat-input": channelId, onSubmit: submit, children: [_jsx("input", { className: inputClassName, type: "text", "aria-label": "Chat message", maxLength: 240, value: value, placeholder: placeholder, onChange: (event) => setValue(event.target.value) }), failure !== null && _jsx("p", { role: "alert", children: failure }), _jsx("button", { type: "submit", className: buttonClassName, "data-chat-send": true, children: sendLabel ?? "Send" })] }));
 }
 export function ChannelTabs({ channels, active, onSelect, className, tabClassName, activeTabClassName, renderTab, }) {
     const ctx = useGameContext();
@@ -66,12 +71,47 @@ export function ChannelTabs({ channels, active, onSelect, className, tabClassNam
             return (_jsx("button", { type: "button", role: "tab", "aria-selected": isActive, className: classes.length > 0 ? classes : undefined, "data-channel": channelId, onClick: () => onSelect(channelId), children: renderTab !== undefined ? renderTab(channelId, isActive) : channelId }, channelId));
         }) }));
 }
-export function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, renderTab, onRejected, }) {
+function ContextChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, ownMessageClassName, defaultExpanded = true, toggleLabel = "Chat", inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, renderTab, onRejected, }) {
     const ctx = useGameContext();
     const chat = ctx.game.chat;
     const ids = channels ?? chat?.channels().map((def) => def.id) ?? [];
     const [active, setActive] = useState(initialChannel ?? ids[0] ?? "global");
+    const [expanded, setExpanded] = useState(defaultExpanded);
+    const panelRef = useRef(null);
+    const focusPending = useRef(false);
+    useEffect(() => {
+        if (chat === undefined)
+            return;
+        const onKey = (event) => {
+            if (event.defaultPrevented || event.isComposing || event.key !== "Enter")
+                return;
+            const target = event.target;
+            if (target?.closest("input, textarea, select, button, [contenteditable]:not([contenteditable=false])"))
+                return;
+            event.preventDefault();
+            focusPending.current = true;
+            setExpanded(true);
+            panelRef.current?.querySelector("input")?.focus();
+        };
+        document.addEventListener("keydown", onKey);
+        return () => document.removeEventListener("keydown", onKey);
+    }, [chat]);
+    useEffect(() => {
+        if (expanded && focusPending.current) {
+            panelRef.current?.querySelector("input")?.focus();
+            focusPending.current = false;
+        }
+    }, [expanded]);
     if (chat === undefined)
         return null;
-    return (_jsxs("section", { className: className, "data-chat-panel": true, children: [_jsx(ChannelTabs, { channels: ids, active: active, onSelect: setActive, className: tabsClassName, tabClassName: tabClassName, activeTabClassName: activeTabClassName, renderTab: renderTab }), _jsx(ChatLog, { channelId: active, limit: limit, className: logClassName, messageClassName: messageClassName, renderMessage: renderMessage }), _jsx(ChatInput, { channelId: active, className: inputClassName, inputClassName: inputFieldClassName, buttonClassName: sendButtonClassName, placeholder: placeholder, onRejected: onRejected })] }));
+    return (_jsxs("section", { ref: panelRef, className: className, "data-chat-panel": true, "data-expanded": expanded, onKeyDown: (event) => {
+            if (event.key === "Escape") {
+                event.target.blur();
+                event.stopPropagation();
+            }
+        }, children: [_jsx("button", { type: "button", "aria-expanded": expanded, onClick: () => setExpanded((value) => !value), children: toggleLabel }), expanded && _jsxs(_Fragment, { children: [_jsx(ChannelTabs, { channels: ids, active: active, onSelect: setActive, className: tabsClassName, tabClassName: tabClassName, activeTabClassName: activeTabClassName, renderTab: renderTab }), _jsx(ChatLog, { channelId: active, limit: limit, className: logClassName, messageClassName: messageClassName, ownMessageClassName: ownMessageClassName, renderMessage: renderMessage }), _jsx(ChatInput, { channelId: active, className: inputClassName, inputClassName: inputFieldClassName, buttonClassName: sendButtonClassName, placeholder: placeholder, onRejected: onRejected })] })] }));
+}
+/** Chat behavior over a game context or externally supplied server messages. */
+export function ChatPanel(props) {
+    return "messages" in props ? _jsx(StandaloneChatPanel, { ...props }) : _jsx(ContextChatPanel, { ...props });
 }

package/dist/hudFrame.js

@@ -15,6 +15,8 @@ export function hudFrameStyle(variation = "glass", shape = "rounded") {
             border: "var(--jg-frame-border, 1px solid rgba(255,255,255,0.10))",
             borderRadius: "var(--jg-frame-radius, 10px)",
             boxShadow: "var(--jg-frame-glow, 0 4px 16px rgba(0,0,0,0.35))",
+            borderImage: "var(--jg-frame-image, none) var(--jg-frame-slice, 0) / var(--jg-frame-scale, 1) var(--jg-frame-fill, stretch)",
+            cursor: "var(--jg-skin-cursor, auto)",
             color: "var(--jg-bar-text, #f4f6fb)",
             fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
         }

package/dist/hudSkin.d.ts

@@ -0,0 +1,29 @@
+import { type CSSProperties } from "react";
+/** Optional raster-backed materials for shared HUD chrome. */
+export interface HudSkinMaterial {
+    image: string;
+    slice: [number, number, number, number];
+    scale?: number;
+    fill?: boolean;
+}
+/** A game-authored visual skin layered over a {@link HudTheme}. */
+export interface HudSkin {
+    frame?: HudSkinMaterial;
+    slot?: HudSkinMaterial;
+    bar?: {
+        fill: string;
+        track: string;
+        cap?: string;
+    };
+    font?: {
+        family: string;
+        src: string;
+        weight?: number;
+        pixel?: boolean;
+    };
+    cursor?: string;
+}
+/** Converts a skin into the CSS variables consumed by shared HUD components. */
+export declare function hudSkinVars(skin?: HudSkin): CSSProperties;
+/** Loads a skin font in browsers and reports when it is available. */
+export declare function useHudFont(skin?: HudSkin): boolean;

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;