@jgengine/editor 0.12.0 → 0.14.0

package/dist/shell/BottomDock.d.ts

@@ -1,6 +1,7 @@
 import type { EditorSession } from "@jgengine/core/editor/index";
 import type { EditorAssetEntry } from "../AssetBrowser.js";
 import type { EditorHostApi } from "../session.js";
+import type { EditorUiStore } from "../uiStore.js";
 import type { EditorConsoleStore } from "./consoleStore.js";
 import type { BottomDockTab, BrowserViewMode } from "./layoutStore.js";
 import type { PerfHistoryStore } from "./perfHistory.js";
@@ -8,13 +9,14 @@ import type { PerfHistoryStore } from "./perfHistory.js";
  * Tabbed bottom dock: Content Browser, Console, Profiler, Animation (path flythrough scrub),
  * and the AI Assistant. Only the active tab's panel mounts, so hidden tools cost nothing per frame.
  */
-export declare function BottomDock({ tab, onSelectTab, onClose, assets, session, api, consoleStore, perfHistory, browserView, onSetBrowserView, onPlaceAsset, onImportModels, importBusy, }: {
+export declare function BottomDock({ tab, onSelectTab, onClose, assets, session, api, ui, consoleStore, perfHistory, browserView, onSetBrowserView, onPlaceAsset, onImportModels, importBusy, }: {
     tab: BottomDockTab;
     onSelectTab: (tab: BottomDockTab) => void;
     onClose: () => void;
     assets: readonly EditorAssetEntry[];
     session: EditorSession;
     api: EditorHostApi;
+    ui: EditorUiStore;
     consoleStore: EditorConsoleStore;
     perfHistory: PerfHistoryStore;
     browserView: BrowserViewMode;

package/dist/shell/BottomDock.js

@@ -11,7 +11,7 @@ import { IconButton, PanelTabs } from "./ui.js";
  * Tabbed bottom dock: Content Browser, Console, Profiler, Animation (path flythrough scrub),
  * and the AI Assistant. Only the active tab's panel mounts, so hidden tools cost nothing per frame.
  */
-export function BottomDock({ tab, onSelectTab, onClose, assets, session, api, consoleStore, perfHistory, browserView, onSetBrowserView, onPlaceAsset, onImportModels, importBusy, }) {
+export function BottomDock({ tab, onSelectTab, onClose, assets, session, api, ui, consoleStore, perfHistory, browserView, onSetBrowserView, onPlaceAsset, onImportModels, importBusy, }) {
     const consoleEntries = useSyncExternalStore(consoleStore.subscribe, consoleStore.getEntries, consoleStore.getEntries);
     const consoleErrorCount = consoleEntries.reduce((sum, entry) => (entry.severity === "error" ? sum + 1 : sum), 0);
     let content;
@@ -25,7 +25,7 @@ export function BottomDock({ tab, onSelectTab, onClose, assets, session, api, co
         content = _jsx(ProfilerPanel, { history: perfHistory });
     }
     else if (tab === "animation") {
-        content = _jsx(AnimationPanel, { session: session, api: api });
+        content = _jsx(AnimationPanel, { session: session, api: api, ui: ui, assets: assets });
     }
     else {
         content = _jsx(AgentPanel, { api: api, embedded: true });

package/dist/shell/TopAppBar.d.ts

@@ -8,8 +8,10 @@ export type TopBarSaveState = "idle" | "saving" | "saved" | "error";
  * edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the
  * runtime pause/step RPCs so mode switches keep shell chrome.
  */
-export declare function TopAppBar({ gameId, dirty, saveState, lastSavedAt, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: {
+export declare function TopAppBar({ gameId, onExitToGame, dirty, saveState, lastSavedAt, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: {
     gameId: string;
+    /** When set (editor summoned over a game), renders an "Exit to game" control that closes the editor. */
+    onExitToGame?: () => void;
     dirty: boolean;
     saveState: TopBarSaveState;
     /** Epoch ms of the last successful save this session; omit/null when never saved. */

package/dist/shell/TopAppBar.js

@@ -34,7 +34,7 @@ function SaveStatus({ dirty, saveState, lastSavedAt, }) {
  * edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the
  * runtime pause/step RPCs so mode switches keep shell chrome.
  */
-export function TopAppBar({ gameId, dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }) {
+export function TopAppBar({ gameId, onExitToGame, dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }) {
     const [menuOpen, setMenuOpen] = useState(false);
     const menuRef = useRef(null);
     useEffect(() => {
@@ -56,7 +56,7 @@ export function TopAppBar({ gameId, dirty, saveState, lastSavedAt = null, saveAv
         };
     }, [menuOpen]);
     const menuItem = `flex w-full items-center gap-2 rounded-[5px] px-2.5 py-1.5 text-left text-[12px] text-neutral-300 transition-colors hover:bg-cyan-500/15 hover:text-cyan-100 ${FOCUS_RING}`;
-    return (_jsxs("header", { className: `pointer-events-auto relative z-[60] flex h-12 shrink-0 items-center gap-2 border-b ${BORDER} bg-[#111318] px-2.5`, children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2.5", children: [_jsx("div", { className: "flex h-7 w-7 shrink-0 items-center justify-center rounded-[6px] bg-gradient-to-br from-cyan-500/30 to-indigo-500/25 text-[11px] font-bold tracking-wide text-cyan-200 ring-1 ring-inset ring-cyan-400/30", "aria-hidden": "true", children: "JG" }), _jsxs("div", { className: "min-w-0 leading-tight", children: [_jsx("div", { className: "truncate text-[13px] font-semibold text-neutral-100", children: gameId }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Scene Editor" })] }), _jsx("div", { className: "ml-1 hidden md:block", children: _jsx(SaveStatus, { dirty: dirty, saveState: saveState, lastSavedAt: lastSavedAt }) })] }), _jsx("div", { className: "flex flex-1 justify-center px-2", children: _jsxs("button", { type: "button", onClick: onOpenPalette, "aria-label": "Open command palette", className: `flex h-8 w-full max-w-[420px] items-center gap-2 rounded-[6px] border border-white/[0.08] bg-black/30 px-3 text-[12px] text-neutral-500 transition-colors hover:border-white/[0.14] hover:text-neutral-400 ${FOCUS_RING}`, children: [_jsx(Icon, { name: "search", size: 13 }), _jsx("span", { className: "min-w-0 flex-1 truncate text-left", children: "Search or run a command\u2026" }), _jsxs("span", { className: "hidden items-center gap-0.5 sm:flex", children: [_jsx(Kbd, { children: "Ctrl" }), _jsx(Kbd, { children: "K" })] })] }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [_jsx(IconButton, { icon: "undo", label: "Undo (Ctrl+Z)", onClick: onUndo, disabled: !canUndo, tone: "ghost" }), _jsx(IconButton, { icon: "redo", label: "Redo (Ctrl+Y)", onClick: onRedo, disabled: !canRedo, tone: "ghost" }), _jsx(ToolbarDivider, {}), _jsxs("button", { type: "button", onClick: onPlay, className: `flex h-8 items-center gap-1.5 rounded-[6px] bg-emerald-600 px-3.5 text-[12px] font-semibold text-white shadow-sm shadow-emerald-950/40 transition-colors hover:bg-emerald-500 ${FOCUS_RING}`, title: "Enter Play mode (F2+E toggles back)", children: [_jsx(Icon, { name: "play", size: 12 }), "Play"] }), _jsx(IconButton, { icon: "pause", label: "Pause \u2014 available in Play mode", disabled: true }), _jsx(IconButton, { icon: "step", label: "Step one frame \u2014 available in Play mode", disabled: true }), _jsx(ToolbarDivider, {}), _jsx(IconButton, { icon: "walk", label: "Walk the world", onClick: onWalk, tone: "ghost" }), _jsx(IconButton, { icon: "panel", label: "Lay out HUD panels", onClick: onHud, tone: "ghost" }), _jsx(ToolbarDivider, {}), saveAvailable ? (_jsxs("button", { type: "button", onClick: onSave, disabled: saveState === "saving", title: saveError ?? "Write the scene to the game's editor.scene.json (Ctrl+S)", className: `flex h-8 items-center gap-1.5 rounded-[6px] px-3 text-[12px] font-medium transition-colors ${FOCUS_RING} ${saveState === "error"
+    return (_jsxs("header", { className: `pointer-events-auto relative z-[60] flex h-12 shrink-0 items-center gap-2 border-b ${BORDER} bg-[#111318] px-2.5`, children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2.5", children: [onExitToGame !== undefined ? (_jsxs("button", { type: "button", onClick: onExitToGame, title: "Close the editor and return to the game (F2+Q)", className: `flex h-8 shrink-0 items-center gap-1.5 rounded-[6px] border border-white/[0.08] bg-black/30 pl-2 pr-2.5 text-[12px] text-neutral-300 transition-colors hover:border-white/[0.16] hover:bg-white/[0.06] hover:text-neutral-100 ${FOCUS_RING}`, children: [_jsx(Icon, { name: "chevronRight", size: 14, className: "rotate-180" }), "Exit to game"] })) : null, _jsx("div", { className: "flex h-7 w-7 shrink-0 items-center justify-center rounded-[6px] bg-gradient-to-br from-cyan-500/30 to-indigo-500/25 text-[11px] font-bold tracking-wide text-cyan-200 ring-1 ring-inset ring-cyan-400/30", "aria-hidden": "true", children: "JG" }), _jsxs("div", { className: "min-w-0 leading-tight", children: [_jsx("div", { className: "truncate text-[13px] font-semibold text-neutral-100", children: gameId }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Scene Editor" })] }), _jsx("div", { className: "ml-1 hidden md:block", children: _jsx(SaveStatus, { dirty: dirty, saveState: saveState, lastSavedAt: lastSavedAt }) })] }), _jsx("div", { className: "flex flex-1 justify-center px-2", children: _jsxs("button", { type: "button", onClick: onOpenPalette, "aria-label": "Open command palette", className: `flex h-8 w-full max-w-[420px] items-center gap-2 rounded-[6px] border border-white/[0.08] bg-black/30 px-3 text-[12px] text-neutral-500 transition-colors hover:border-white/[0.14] hover:text-neutral-400 ${FOCUS_RING}`, children: [_jsx(Icon, { name: "search", size: 13 }), _jsx("span", { className: "min-w-0 flex-1 truncate text-left", children: "Search or run a command\u2026" }), _jsxs("span", { className: "hidden items-center gap-0.5 sm:flex", children: [_jsx(Kbd, { children: "Ctrl" }), _jsx(Kbd, { children: "K" })] })] }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [_jsx(IconButton, { icon: "undo", label: "Undo (Ctrl+Z)", onClick: onUndo, disabled: !canUndo, tone: "ghost" }), _jsx(IconButton, { icon: "redo", label: "Redo (Ctrl+Y)", onClick: onRedo, disabled: !canRedo, tone: "ghost" }), _jsx(ToolbarDivider, {}), _jsxs("button", { type: "button", onClick: onPlay, className: `flex h-8 items-center gap-1.5 rounded-[6px] bg-emerald-600 px-3.5 text-[12px] font-semibold text-white shadow-sm shadow-emerald-950/40 transition-colors hover:bg-emerald-500 ${FOCUS_RING}`, title: "Enter Play mode (F2+E toggles back)", children: [_jsx(Icon, { name: "play", size: 12 }), "Play"] }), _jsx(IconButton, { icon: "pause", label: "Pause \u2014 available in Play mode", disabled: true }), _jsx(IconButton, { icon: "step", label: "Step one frame \u2014 available in Play mode", disabled: true }), _jsx(ToolbarDivider, {}), _jsx(IconButton, { icon: "walk", label: "Walk the world", onClick: onWalk, tone: "ghost" }), _jsx(IconButton, { icon: "panel", label: "Lay out HUD panels", onClick: onHud, tone: "ghost" }), _jsx(ToolbarDivider, {}), saveAvailable ? (_jsxs("button", { type: "button", onClick: onSave, disabled: saveState === "saving", title: saveError ?? "Write the scene to the game's editor.scene.json (Ctrl+S)", className: `flex h-8 items-center gap-1.5 rounded-[6px] px-3 text-[12px] font-medium transition-colors ${FOCUS_RING} ${saveState === "error"
                             ? "bg-rose-600/90 text-white hover:bg-rose-500"
                             : dirty
                                 ? "bg-cyan-600 text-white shadow-sm shadow-cyan-950/40 hover:bg-cyan-500"

package/dist/shell/clipPreview.d.ts

@@ -0,0 +1,85 @@
+import { type ClipRole } from "@jgengine/core/game/clipRoles";
+import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
+/**
+ * Editor viewport clip-preview model — pure logic, no JSX / R3F. Mirrors how `pathFlythrough.ts`
+ * splits the flythrough math out of {@link AnimationPanel}: derives a rigged asset's playable clip
+ * list and models a scrub/loop/speed playback driver that the viewport layer and the dock panel
+ * both consume. The actual mixer is the shell's `useModelAnimation`; this module only shapes the
+ * config it plays and the transitions the controls dispatch.
+ *
+ * @internal
+ */
+/** A rigged asset carrying animation clip names — the browser entry / catalog `ModelAssetRef`. */
+export interface ClipSourceRef {
+    readonly clips?: readonly string[];
+}
+/** One previewable clip with its detected semantic role (null when unclassified). */
+export interface ClipEntry {
+    readonly name: string;
+    readonly role: ClipRole | null;
+}
+/**
+ * Lists a rigged asset's clips with their classified roles, preserving catalog order. Empty when
+ * the ref carries no clips (not rigged, or clip metadata absent).
+ */
+export declare function clipEntriesFromRef(ref: ClipSourceRef | null | undefined): ClipEntry[];
+/** A rigged asset resolved for viewport preview: its catalog id, label, GLB url, and clip names. */
+export interface ClipPreviewSource {
+    readonly assetId: string;
+    readonly label: string;
+    readonly url: string;
+    readonly clips: readonly string[];
+}
+/**
+ * The live clip-preview session shared across panels via the editor UI store: which asset is being
+ * previewed, the playback driver, and the selected clip's measured duration (published by the
+ * viewport layer once its GLB loads; 0 while unknown).
+ */
+export interface ClipPreviewSession {
+    readonly source: ClipPreviewSource;
+    readonly driver: ClipPreviewState;
+    readonly duration: number;
+}
+/** Playback state of the clip preview driver. `time` is seconds into the clip. */
+export interface ClipPreviewState {
+    /** Clip currently loaded into the preview, or null when nothing is selected. */
+    clipName: string | null;
+    playing: boolean;
+    loop: boolean;
+    /** Playback rate multiplier; clamped to a sane preview range. */
+    speed: number;
+    /** Playhead position in seconds. Meaningful while paused/scrubbing. */
+    time: number;
+}
+/** Lowest / highest preview playback rate the speed control allows. */
+/** Lower bound for the clip-preview playback rate. */
+export declare const MIN_PREVIEW_SPEED = 0.1;
+/** Upper bound for the clip-preview playback rate. */
+export declare const MAX_PREVIEW_SPEED = 4;
+/** Fresh driver state for a clip (auto-plays when a clip is given, like the browser badge implies). */
+export declare function initialClipPreviewState(clipName?: string | null): ClipPreviewState;
+/** Switch to a different clip: resets the playhead and starts playing it. */
+export declare function selectPreviewClip(state: ClipPreviewState, clipName: string): ClipPreviewState;
+/** Sets whether the previewed clip is playing; pausing keeps the current scrub time. */
+export declare function setPreviewPlaying(state: ClipPreviewState, playing: boolean): ClipPreviewState;
+/** Toggles play/pause of the previewed clip without losing the scrub position. */
+export declare function togglePreviewPlaying(state: ClipPreviewState): ClipPreviewState;
+/** Sets whether the previewed clip loops when it reaches its end. */
+export declare function setPreviewLoop(state: ClipPreviewState, loop: boolean): ClipPreviewState;
+/** Sets the preview playback rate, clamped to [MIN_PREVIEW_SPEED, MAX_PREVIEW_SPEED]. */
+export declare function setPreviewSpeed(state: ClipPreviewState, speed: number): ClipPreviewState;
+/** Scrub to an absolute time (seconds). Pauses playback, matching the path-flythrough scrubber. */
+export declare function scrubPreview(state: ClipPreviewState, time: number): ClipPreviewState;
+/**
+ * Advances the playhead by `dt` seconds at the current speed, wrapping when looping and clamping
+ * (then stopping) at `duration` otherwise. No-op while paused, clip-less, or the duration is
+ * unknown (<= 0). Uses the same time += speed·dt formula the shell mixer runs, so a panel that ticks
+ * this in lockstep with the freerunning viewport mixer stays in sync.
+ */
+export declare function advancePreview(state: ClipPreviewState, dt: number, duration: number): ClipPreviewState;
+/**
+ * The `ModelConfig.animation` config the preview layer feeds to `useModelAnimation`. Playing yields
+ * a freerunning single-clip config (mixer owns the clock, no per-frame churn); paused yields a held
+ * `paused`+`time` pose so a scrub renders the exact frame. Returns undefined with no clip (bind pose).
+ */
+export declare function previewAnimationConfig(state: ClipPreviewState): ModelAnimationConfig | undefined;

package/dist/shell/clipPreview.js

@@ -0,0 +1,82 @@
+import { classifyClip } from "@jgengine/core/game/clipRoles";
+/**
+ * Lists a rigged asset's clips with their classified roles, preserving catalog order. Empty when
+ * the ref carries no clips (not rigged, or clip metadata absent).
+ */
+export function clipEntriesFromRef(ref) {
+    const clips = ref?.clips;
+    if (clips === undefined || clips.length === 0)
+        return [];
+    return clips.map((name) => ({ name, role: classifyClip(name) }));
+}
+/** Lowest / highest preview playback rate the speed control allows. */
+/** Lower bound for the clip-preview playback rate. */
+export const MIN_PREVIEW_SPEED = 0.1;
+/** Upper bound for the clip-preview playback rate. */
+export const MAX_PREVIEW_SPEED = 4;
+function clampSpeed(speed) {
+    if (!Number.isFinite(speed))
+        return 1;
+    return Math.max(MIN_PREVIEW_SPEED, Math.min(MAX_PREVIEW_SPEED, speed));
+}
+/** Fresh driver state for a clip (auto-plays when a clip is given, like the browser badge implies). */
+export function initialClipPreviewState(clipName = null) {
+    return { clipName, playing: clipName !== null, loop: true, speed: 1, time: 0 };
+}
+/** Switch to a different clip: resets the playhead and starts playing it. */
+export function selectPreviewClip(state, clipName) {
+    return { ...state, clipName, time: 0, playing: true };
+}
+/** Sets whether the previewed clip is playing; pausing keeps the current scrub time. */
+export function setPreviewPlaying(state, playing) {
+    if (state.clipName === null)
+        return { ...state, playing: false };
+    return { ...state, playing };
+}
+/** Toggles play/pause of the previewed clip without losing the scrub position. */
+export function togglePreviewPlaying(state) {
+    return setPreviewPlaying(state, !state.playing);
+}
+/** Sets whether the previewed clip loops when it reaches its end. */
+export function setPreviewLoop(state, loop) {
+    return { ...state, loop };
+}
+/** Sets the preview playback rate, clamped to [MIN_PREVIEW_SPEED, MAX_PREVIEW_SPEED]. */
+export function setPreviewSpeed(state, speed) {
+    return { ...state, speed: clampSpeed(speed) };
+}
+/** Scrub to an absolute time (seconds). Pauses playback, matching the path-flythrough scrubber. */
+export function scrubPreview(state, time) {
+    const next = Number.isFinite(time) ? Math.max(0, time) : 0;
+    return { ...state, time: next, playing: false };
+}
+/**
+ * Advances the playhead by `dt` seconds at the current speed, wrapping when looping and clamping
+ * (then stopping) at `duration` otherwise. No-op while paused, clip-less, or the duration is
+ * unknown (<= 0). Uses the same time += speed·dt formula the shell mixer runs, so a panel that ticks
+ * this in lockstep with the freerunning viewport mixer stays in sync.
+ */
+export function advancePreview(state, dt, duration) {
+    if (!state.playing || state.clipName === null || duration <= 0 || !Number.isFinite(dt) || dt <= 0) {
+        return state;
+    }
+    let next = state.time + state.speed * dt;
+    if (next >= duration) {
+        if (state.loop)
+            next %= duration;
+        else
+            return { ...state, time: duration, playing: false };
+    }
+    return { ...state, time: next };
+}
+/**
+ * The `ModelConfig.animation` config the preview layer feeds to `useModelAnimation`. Playing yields
+ * a freerunning single-clip config (mixer owns the clock, no per-frame churn); paused yields a held
+ * `paused`+`time` pose so a scrub renders the exact frame. Returns undefined with no clip (bind pose).
+ */
+export function previewAnimationConfig(state) {
+    if (state.clipName === null)
+        return undefined;
+    const base = { clip: state.clipName, loop: state.loop, timeScale: state.speed };
+    return state.playing ? base : { ...base, paused: true, time: state.time };
+}

package/dist/shell/scatterCoverage.d.ts

@@ -0,0 +1,22 @@
+import type { ParamSchema, ParsedParams, SceneKindCoverage, SceneKindObject } from "@jgengine/core/scene/sceneKinds";
+/** A patch to a single meta key, coalesced under a stable undo key (matches `SchemaInspector`). */
+type MetaPatch = (patch: Record<string, unknown>, coalesce: string) => void;
+/**
+ * The shared leading block for every scatterable kind (`grass_field` / `scatter` / `city`): one
+ * consistent Area → Assets → Density gesture. Renders the footprint Area readout, a compact summary
+ * of what fills it (the weighted palette, when the kind declares one), the single Density slider
+ * hoisted out of the schema body, and the kind's budget clamp-and-warn `note`. The rest of the kind's
+ * parameters render below via `SchemaInspector` (with the density key hidden). One module so grass,
+ * scatter, and city never re-derive the "how much stuff grows here" affordance.
+ * @internal — mounted by `InspectorPanel`'s `KindInspector` when a kind declares `coverage`.
+ */
+export declare function CoverageSection({ schema, coverage, object, params, note, accent, onMeta, }: {
+    schema: ParamSchema;
+    coverage: SceneKindCoverage;
+    object: SceneKindObject;
+    params: ParsedParams;
+    note?: string;
+    accent: string;
+    onMeta: MetaPatch;
+}): import("react").JSX.Element;
+export {};

package/dist/shell/scatterCoverage.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { scatterFootprintArea } from "@jgengine/core/world/scatterCoverage";
+import { MICRO_LABEL } from "./theme.js";
+const fmt = (n) => Math.round(n).toLocaleString();
+/** One-line summary of a weighted "what fills it" palette: count + the leading item ids. */
+function assetsSummary(entries) {
+    if (entries === undefined || entries.length === 0)
+        return null;
+    const ids = entries.map((entry) => entry.item).filter((item) => item.length > 0);
+    if (ids.length === 0)
+        return null;
+    const head = ids.slice(0, 4).join(", ");
+    const rest = ids.length > 4 ? ` +${ids.length - 4}` : "";
+    return `${ids.length} ${ids.length === 1 ? "type" : "types"} · ${head}${rest}`;
+}
+/**
+ * The shared leading block for every scatterable kind (`grass_field` / `scatter` / `city`): one
+ * consistent Area → Assets → Density gesture. Renders the footprint Area readout, a compact summary
+ * of what fills it (the weighted palette, when the kind declares one), the single Density slider
+ * hoisted out of the schema body, and the kind's budget clamp-and-warn `note`. The rest of the kind's
+ * parameters render below via `SchemaInspector` (with the density key hidden). One module so grass,
+ * scatter, and city never re-derive the "how much stuff grows here" affordance.
+ * @internal — mounted by `InspectorPanel`'s `KindInspector` when a kind declares `coverage`.
+ */
+export function CoverageSection({ schema, coverage, object, params, note, accent, onMeta, }) {
+    const area = scatterFootprintArea(object);
+    const densityField = schema.fields.find((field) => field.key === coverage.densityKey);
+    const density = typeof params[coverage.densityKey] === "number" ? params[coverage.densityKey] : 0;
+    const assets = coverage.assetsKey === undefined ? null : assetsSummary(params[coverage.assetsKey]);
+    return (_jsxs("div", { className: "space-y-2 rounded-lg border p-2.5", style: { borderColor: `${accent}26`, backgroundColor: `${accent}10` }, children: [_jsx("div", { className: "text-[9px] font-semibold uppercase tracking-[0.14em]", style: { color: accent }, children: "Coverage" }), _jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO_LABEL, children: "area" }), _jsx("span", { className: "text-cyan-200", children: area > 0 ? `${fmt(area)} m²` : "—" })] }), assets !== null ? (_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO_LABEL, children: "fills with" }), _jsx("span", { className: "min-w-0 truncate text-right text-[10px] text-neutral-300", title: assets, children: assets })] })) : null, densityField !== undefined && densityField.type === "range" ? (_jsxs("label", { className: "block space-y-1", children: [_jsxs("span", { className: "flex items-center justify-between", children: [_jsx("span", { className: MICRO_LABEL, children: densityField.label ?? densityField.key }), _jsxs("span", { className: "text-cyan-200", children: [density.toFixed(densityField.step !== undefined && densityField.step >= 1 ? 0 : 2), densityField.unit ?? ""] })] }), _jsx("input", { type: "range", min: densityField.min, max: densityField.max, step: densityField.step ?? (densityField.max - densityField.min) / 100, value: density, className: "w-full accent-emerald-400", "aria-label": `${densityField.label ?? densityField.key} density`, onChange: (event) => onMeta({ [coverage.densityKey]: Number(event.target.value) }, `kind:${coverage.densityKey}`) })] })) : null, note !== undefined && note.length > 0 ? _jsx("div", { className: "text-[10px] text-neutral-500", children: note }) : null] }));
+}

package/dist/uiStore.d.ts

@@ -1,5 +1,6 @@
 import type { EditorSession, EditorVec3, EditorVolumeShape } from "@jgengine/core/editor/index";
 import type { TerraformFalloff, TerraformShape } from "@jgengine/core/world/terraform";
+import type { ClipPreviewSession } from "./shell/clipPreview.js";
 /** Which top-level editor tool is active: object placement/selection, or terrain sculpting. */
 export type EditorTool = "select" | "terrain";
 /** A heightfield sculpt brush the terrain tool can apply. */
@@ -120,6 +121,11 @@ export interface EditorUiState {
     sculpt: SculptSettings;
     paint: PaintSettings;
     contextMenu: EditorContextMenuState | null;
+    /**
+     * Active viewport clip-preview session (rigged asset + playback driver), or null when nothing is
+     * previewing. Driven by the Animation dock's clip mode; rendered by `ClipPreviewLayer`.
+     */
+    clipPreview: ClipPreviewSession | null;
 }
 /** Subscribable store for the editor's transient UI state (gizmo, snapping, placement). */
 export interface EditorUiStore {

package/dist/uiStore.js

@@ -61,6 +61,7 @@ export function createEditorUiStore() {
         sculpt: { ...DEFAULT_SCULPT_SETTINGS },
         paint: { ...DEFAULT_PAINT_SETTINGS },
         contextMenu: null,
+        clipPreview: null,
     };
     const listeners = new Set();
     const emit = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/editor",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Scene/world/asset editor for JGengine — loaded lazily by the runner; never import from game entrypoints.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.12.0",
-    "@jgengine/react": "^0.12.0",
-    "@jgengine/shell": "^0.12.0"
+    "@jgengine/core": "^0.14.0",
+    "@jgengine/react": "^0.14.0",
+    "@jgengine/shell": "^0.14.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/SKILL.md

@@ -5,7 +5,7 @@ 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.
+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.
 
 ## 1. Establish the target
 
@@ -20,6 +20,8 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 
 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.
+
 ## 2. Select domains
 
 Load only rows the target needs. Do not preload every domain.
@@ -42,7 +44,8 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
-1. Search `capabilities.md` by intent; it maps needs to imports.
+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.
 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.

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.12.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.14.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -38,7 +38,7 @@
 - `WorldFeature` (type): type WorldFeature = | PlaceWorldFeature | ({ kind: "biomes" } & BiomesWorldConfig) | ({ kind: "voxel" } & VoxelWorldConfig) | ({ kind: "plots" } & PlotsWorldConfig) | ({ kind: "tilemap" } & TilemapWorldConfig) | EnvironmentWorldFeature | { kind: "flat" } — A declared world shape passed to `defineGame`. The preferred model is the place feature from `world()` (`@jgengine/core/world/place`): substrate + laws, with all dressing authored in the editor. The remaining members — biomes, voxel grid, plots, tilemap, environment, flat — are the legacy code-declared shapes kept for existing games.
 - `auditManifest` (function): function auditManifest(manifest: SceneOwnershipManifest): OwnershipDiagnostic[] — Audit every declaration in a manifest, keying diagnostics by each object's provenance id. An empty result means the manifest declares all of its content cleanly — every object is authored, generated, bakeable, or a reasoned runtime/transient object.
 - `biomes` (function): function biomes(config: BiomesWorldConfig): WorldFeature — Declares a biome-painted world — the whole-world alternative to a single `environment()` terrain.
-- `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style.
+- `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. Pass `along` to line road frontage instead of gridding around `position`.
 - `classifyOwnership` (function): function classifyOwnership(declaration: SceneOwnershipDeclaration): OwnershipVerdict — Resolve one declaration into a single boundary verdict.
 - `collectOwnershipDiagnostics` (function): function collectOwnershipDiagnostics(entries: Iterable<readonly [string, SceneOwnershipDeclaration]>): OwnershipDiagnostic[] — Audit a keyed set of declarations and return one diagnostic per object that breaks the boundary contract (a `reject` verdict carrying a `violation`). Deterministic: diagnostics come back in the iteration order of `entries`.
 - `contextVerb` (function): function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb — Builds a {@link ContextVerb} for a right-click menu entry.
@@ -209,11 +209,18 @@
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 
+## @jgengine/core/devtools/urlFlags
+
+- `readUrlFlag` (function): function readUrlFlag(param: string): boolean — True when `param` is present and not an explicit off value (`0`/`false`/`off`/`no`).
+- `readUrlParam` (function): function readUrlParam(param: string): string | null — The current query value of `param`, or null when absent (or no DOM).
+- `subscribeUrlChange` (function): function subscribeUrlChange(listener: () => void): () => void — Fires `listener` whenever the query string may have changed out from under a flag — browser back/forward (`popstate`). Manual address-bar edits reload the page, so initial reads cover those; this keeps in-app state honest across history navigation. Returns an unsubscribe.
+- `writeUrlParam` (function): function writeUrlParam(param: string, value: string | null): void — Sets `param` to `value`, or removes it when `value` is null, rewriting the URL in place with `history.replaceState` so the rest of the query and the hash survive and no history entry is pushed. No-ops without a DOM, and skips the write when the URL already matches.
+
 ## @jgengine/core/meta/changelog
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.12.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.14.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -276,7 +283,7 @@
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — ⚠ undocumented
 - `TelegraphInput` (interface): interface TelegraphInput — ⚠ undocumented
-- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`.
+- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst. The easy path is a named `preset` — `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`, `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color` yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
 - `WorldItemPickupResult` (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string } — ⚠ undocumented
 - `createGameContext` (function): function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext — ⚠ undocumented
 
@@ -307,7 +314,7 @@
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — ⚠ undocumented
 - `TelegraphInput` (interface): interface TelegraphInput — ⚠ undocumented
-- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`.
+- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst. The easy path is a named `preset` — `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`, `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color` yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
 - `WorldItemPickupResult` (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string } — ⚠ undocumented
 
 ## @jgengine/core/runtime/gameRuntime
@@ -322,6 +329,7 @@
 
 ## @jgengine/core/runtime/headlessRunner
 
+- `HeadlessCommandInterface` (interface): interface HeadlessCommandInterface — Canvas-free command/intent surface for {@link HeadlessRunner} — invoke a game's registered UI commands and read the resulting reactive state off `ctx`.
 - `HeadlessInput` (interface): interface HeadlessInput — One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame.
 - `HeadlessRunner` (interface): interface HeadlessRunner — A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole play path (time, input, `onTick`, behaviour nav, optional player movement) runs from `core` primitives alone, so a non-React host (a server tick, a test, a CLI replay) can play a real game and read its world snapshot. The shell's FrameDriver is one such driver bolted to `useFrame`; this is the same step distilled out of the render tree.
 - `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — ⚠ undocumented