@jgengine/editor 0.13.0 → 0.14.0

package/dist/shell/AnimationPanel.d.ts

@@ -1,17 +1,19 @@
 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";
 /**
- * Animation dock: path flythrough scrubber over authored scene polylines.
- *
- * Scope (honest, no fake NLE):
- * - Scrub / play the editor orbit camera along document paths via {@link EditorHostApi.setFocusTarget}.
- * - Uses real path points + `@jgengine/core` path-follow sampling — not invented keyframes.
- * - Out of scope: clip authoring, keyframe curves, scene-kind param animation, director cinematics
- *   stored outside the scene document.
+ * Animation dock with two modes:
+ * - **Path** — scrub/play the editor orbit camera along authored scene polylines (real path points,
+ *   no fabricated keyframes).
+ * - **Clips** — preview a rigged asset's animation clips in the viewport (scrub, loop, speed) via the
+ *   shell mixer, either a placed instance's asset or any rigged catalog asset.
  *
  * @internal
  */
-export declare function AnimationPanel({ session, api }: {
+export declare function AnimationPanel({ session, api, ui, assets, }: {
     session: EditorSession;
     api: EditorHostApi;
+    ui: EditorUiStore;
+    assets: readonly EditorAssetEntry[];
 }): import("react").JSX.Element;

package/dist/shell/AnimationPanel.js

@@ -1,23 +1,123 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useStoreSelector } from "../useStoreSelector.js";
+import { markerCatalogId } from "@jgengine/core/world/authoredObjects";
+import { shallowArrayEqual, useStoreSelector } from "../useStoreSelector.js";
+import { advancePreview, clipEntriesFromRef, initialClipPreviewState, MAX_PREVIEW_SPEED, MIN_PREVIEW_SPEED, scrubPreview, selectPreviewClip, setPreviewLoop, setPreviewSpeed, togglePreviewPlaying, } from "./clipPreview.js";
 import { listScrubbablePaths, samplePathAt } from "./pathFlythrough.js";
 import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./theme.js";
 import { EmptyState, IconButton } from "./ui.js";
 /** Default world-units/sec when playing a path flythrough preview. */
 const DEFAULT_PLAY_SPEED = 8;
+/** Rigged asset entries (carry animation clips) for the clip-preview picker. */
+function riggedAssets(assets) {
+    return assets.filter((entry) => entry.url !== undefined && entry.clips !== undefined && entry.clips.length > 0);
+}
 /**
- * Animation dock: path flythrough scrubber over authored scene polylines.
- *
- * Scope (honest, no fake NLE):
- * - Scrub / play the editor orbit camera along document paths via {@link EditorHostApi.setFocusTarget}.
- * - Uses real path points + `@jgengine/core` path-follow sampling — not invented keyframes.
- * - Out of scope: clip authoring, keyframe curves, scene-kind param animation, director cinematics
- *   stored outside the scene document.
+ * Animation dock with two modes:
+ * - **Path** — scrub/play the editor orbit camera along authored scene polylines (real path points,
+ *   no fabricated keyframes).
+ * - **Clips** — preview a rigged asset's animation clips in the viewport (scrub, loop, speed) via the
+ *   shell mixer, either a placed instance's asset or any rigged catalog asset.
  *
  * @internal
  */
-export function AnimationPanel({ session, api }) {
+export function AnimationPanel({ session, api, ui, assets, }) {
+    const rigged = useMemo(() => riggedAssets(assets), [assets]);
+    // Default to clips only when the scene has rigged assets but no scrubbable path yet.
+    const paths = useStoreSelector(session, (state) => state.document.paths);
+    const [mode, setMode] = useState(() => rigged.length > 0 && listScrubbablePaths(paths).length === 0 ? "clips" : "path");
+    // Tear down the viewport preview whenever the panel leaves clip mode or unmounts.
+    useEffect(() => {
+        if (mode !== "clips" && ui.getState().clipPreview !== null)
+            ui.patch({ clipPreview: null });
+    }, [mode, ui]);
+    useEffect(() => () => {
+        if (ui.getState().clipPreview !== null)
+            ui.patch({ clipPreview: null });
+    }, [ui]);
+    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col", children: [_jsx("div", { className: "flex h-8 shrink-0 items-center gap-1.5 border-b border-white/[0.06] px-2", children: _jsx("div", { className: "flex items-center gap-0.5", role: "tablist", "aria-label": "Animation mode", children: [
+                        ["path", "Path flythrough"],
+                        ["clips", "Clip preview"],
+                    ].map(([id, label]) => (_jsx("button", { type: "button", role: "tab", "aria-selected": mode === id, className: `rounded-[5px] px-2 py-0.5 text-[10px] uppercase tracking-wider transition-colors ${FOCUS_RING} ${mode === id ? "bg-cyan-500/15 text-cyan-200" : "text-neutral-500 hover:text-neutral-300"}`, onClick: () => setMode(id), children: label }, id))) }) }), mode === "path" ? (_jsx(PathFlythrough, { session: session, api: api })) : (_jsx(ClipPreview, { session: session, ui: ui, rigged: rigged }))] }));
+}
+/** Clip-preview mode: pick a rigged asset (placed instance or catalog) and play its clips in the viewport. */
+function ClipPreview({ session, ui, rigged, }) {
+    const preview = useStoreSelector(ui, (state) => state.clipPreview);
+    const selection = useStoreSelector(session, (state) => state.selection, shallowArrayEqual);
+    // A placed marker in the selection that resolves to a rigged catalog asset — offer to preview it.
+    const selectedRigged = useMemo(() => {
+        const document = session.getState().document;
+        for (const id of selection) {
+            const marker = document.markers.find((entry) => entry.id === id);
+            if (marker === undefined)
+                continue;
+            const catalogId = markerCatalogId(marker);
+            if (catalogId === null)
+                continue;
+            const asset = rigged.find((entry) => entry.id === catalogId);
+            if (asset !== undefined)
+                return asset;
+        }
+        return null;
+    }, [selection, rigged, session]);
+    const startPreview = useCallback((asset) => {
+        if (asset.url === undefined || asset.clips === undefined)
+            return;
+        const firstClip = asset.clips[0] ?? null;
+        ui.patch({
+            clipPreview: {
+                source: { assetId: asset.id, label: asset.label, url: asset.url, clips: asset.clips },
+                driver: initialClipPreviewState(firstClip),
+                duration: 0,
+            },
+        });
+    }, [ui]);
+    const updateDriver = useCallback((next) => {
+        const current = ui.getState().clipPreview;
+        if (current === null)
+            return;
+        ui.patch({ clipPreview: { ...current, driver: next } });
+    }, [ui]);
+    // While playing with a known clip duration, advance the driver each frame (freerunning mixer + slider in sync).
+    const previewRef = useRef(preview);
+    previewRef.current = preview;
+    const playing = preview?.driver.playing ?? false;
+    useEffect(() => {
+        if (!playing)
+            return;
+        let frame = 0;
+        let last = performance.now();
+        const tick = (now) => {
+            const dt = Math.min(0.05, Math.max(0, (now - last) / 1000));
+            last = now;
+            const current = previewRef.current;
+            if (current === null || !current.driver.playing)
+                return;
+            const next = advancePreview(current.driver, dt, current.duration);
+            if (next !== current.driver)
+                ui.patch({ clipPreview: { ...current, driver: next } });
+            frame = requestAnimationFrame(tick);
+        };
+        frame = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(frame);
+    }, [playing, ui, preview?.duration, preview?.source.assetId]);
+    if (rigged.length === 0) {
+        return (_jsx(EmptyState, { icon: "film", title: "Clip preview", badge: "Rigged assets", description: "Preview animation clips in the viewport. No rigged assets in this game's catalog \u2014 imported/catalog models carrying animation clips (\u25B6 badge in the Content Browser) show up here." }));
+    }
+    const source = preview?.source ?? null;
+    const driver = preview?.driver ?? null;
+    const duration = preview?.duration ?? 0;
+    const clipEntries = clipEntriesFromRef(source);
+    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col", children: [_jsxs("div", { className: "flex h-7 shrink-0 items-center gap-1.5 border-b border-white/[0.06] px-2", children: [_jsx("span", { className: "text-[10px] uppercase tracking-wider text-neutral-500", children: "Clip preview" }), _jsxs("span", { className: `text-[10px] text-neutral-600 ${NUMERIC}`, children: [rigged.length, " rigged asset", rigged.length === 1 ? "" : "s", " \u00B7 viewport playback"] }), selectedRigged !== null && selectedRigged.id !== source?.assetId ? (_jsx("button", { type: "button", className: `ml-auto rounded-[5px] border border-cyan-400/30 bg-cyan-500/15 px-2 py-0.5 text-[10px] text-cyan-200 transition-colors hover:bg-cyan-500/25 ${FOCUS_RING}`, onClick: () => startPreview(selectedRigged), title: `Preview the selected placement's rig (${selectedRigged.label})`, children: "Preview selection" })) : null] }), _jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-2 overflow-auto p-3", children: [_jsxs("label", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Rigged asset" }), _jsxs("select", { className: `${INPUT_CLS} h-8 px-2 text-[12px]`, value: source?.assetId ?? "", "aria-label": "Preview asset", onChange: (event) => {
+                                    const asset = rigged.find((entry) => entry.id === event.target.value);
+                                    if (asset !== undefined)
+                                        startPreview(asset);
+                                }, children: [_jsx("option", { value: "", disabled: true, children: "Select a rigged asset\u2026" }), rigged.map((asset) => (_jsxs("option", { value: asset.id, children: [asset.label, " \u00B7 ", asset.clips?.length ?? 0, " clips"] }, asset.id)))] })] }), source === null || driver === null ? (_jsx("p", { className: "text-[10px] leading-relaxed text-neutral-600", children: "Pick a rigged asset above (or select a placed instance and press \u201CPreview selection\u201D) to play its clips at the camera focus point." })) : (_jsxs(_Fragment, { children: [_jsxs("label", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Clip" }), _jsx("select", { className: `${INPUT_CLS} h-8 px-2 text-[12px]`, value: driver.clipName ?? "", "aria-label": "Preview clip", onChange: (event) => updateDriver(selectPreviewClip(driver, event.target.value)), children: clipEntries.map((entry) => (_jsxs("option", { value: entry.name, children: [entry.name, entry.role === null ? "" : ` · ${entry.role}`] }, entry.name))) })] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(IconButton, { icon: driver.playing ? "pause" : "play", label: driver.playing ? "Pause clip" : "Play clip", size: 14, active: driver.playing, disabled: driver.clipName === null, onClick: () => updateDriver(togglePreviewPlaying(driver)) }), _jsx("button", { type: "button", className: `rounded-[5px] border px-2 py-0.5 text-[10px] uppercase tracking-wider transition-colors ${FOCUS_RING} ${driver.loop
+                                            ? "border-cyan-400/30 bg-cyan-500/15 text-cyan-200"
+                                            : "border-white/[0.07] bg-white/[0.02] text-neutral-500 hover:text-neutral-300"}`, "aria-pressed": driver.loop, "aria-label": driver.loop ? "Loop on" : "Loop off", onClick: () => updateDriver(setPreviewLoop(driver, !driver.loop)), children: "Loop" }), _jsxs("div", { className: "ml-auto flex items-center gap-1.5", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Speed" }), _jsx("input", { type: "range", min: MIN_PREVIEW_SPEED, max: MAX_PREVIEW_SPEED, step: 0.05, value: driver.speed, "aria-label": "Playback speed", className: `h-2 w-24 accent-cyan-400 ${FOCUS_RING}`, onChange: (event) => updateDriver(setPreviewSpeed(driver, Number(event.target.value))) }), _jsxs("span", { className: `w-8 text-right text-[10px] text-neutral-400 ${NUMERIC}`, children: [driver.speed.toFixed(2), "\u00D7"] })] })] }), _jsxs("label", { className: "flex flex-col gap-1", children: [_jsxs("div", { className: "flex items-center justify-between text-[9px] uppercase tracking-wider text-neutral-600", children: [_jsx("span", { children: "Scrub" }), _jsxs("span", { className: NUMERIC, children: [driver.time.toFixed(2), duration > 0 ? ` / ${duration.toFixed(2)}` : "", " s"] })] }), _jsx("input", { type: "range", min: 0, max: duration > 0 ? duration : 1, step: 0.01, value: Math.min(driver.time, duration > 0 ? duration : 1), "aria-label": "Clip time", disabled: driver.clipName === null || duration <= 0, className: `h-2 w-full accent-cyan-400 ${FOCUS_RING}`, onChange: (event) => updateDriver(scrubPreview(driver, Number(event.target.value))) })] }), _jsxs("p", { className: "text-[10px] leading-relaxed text-neutral-600", children: ["Plays the selected clip on ", source.label, " at the camera focus point. Same mixer the game runs at play time. Authoring lives in the inspector\u2019s Animation section on a placed instance."] })] }))] })] }));
+}
+/** Path flythrough mode: scrub the orbit camera along authored scene polylines. */
+function PathFlythrough({ session, api }) {
     const paths = useStoreSelector(session, (state) => state.document.paths);
     const scrubbable = useMemo(() => listScrubbablePaths(paths), [paths]);
     const [selectedId, setSelectedId] = useState(null);
@@ -114,11 +214,11 @@ export function AnimationPanel({ session, api }) {
         };
     }, [playing, selected, applyProgress, session]);
     if (scrubbable.length === 0) {
-        return (_jsx(EmptyState, { icon: "film", title: "Path flythrough", badge: "Scoped", description: "Scope: scrub the orbit camera along authored scene paths (routes, roads, patrols). Draw a path with 2+ points via Add \u2192 path/road, then open this tab. Keyframe clip authoring and scene-kind param animation are not in scope." }));
+        return (_jsx(EmptyState, { icon: "film", title: "Path flythrough", badge: "Scoped", description: "Scope: scrub the orbit camera along authored scene paths (routes, roads, patrols). Draw a path with 2+ points via Add \u2192 path/road, then open this tab. Switch to Clip preview above to play a rigged asset's animations." }));
     }
     const lengthLabel = selected === null ? "—" : selected.length < 10 ? `${selected.length.toFixed(1)} m` : `${Math.round(selected.length)} m`;
     const distance = selected === null || selected.length <= 0 ? 0 : progress * selected.length;
-    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col", children: [_jsxs("div", { className: "flex h-8 shrink-0 items-center gap-1.5 border-b border-white/[0.06] px-2", children: [_jsx("span", { className: "text-[10px] uppercase tracking-wider text-neutral-500", children: "Path flythrough" }), _jsxs("span", { className: `text-[10px] text-neutral-600 ${NUMERIC}`, children: [scrubbable.length, " path", scrubbable.length === 1 ? "" : "s", " \u00B7 camera follows scrub"] }), _jsxs("div", { className: "ml-auto flex items-center gap-1", children: [_jsx(IconButton, { icon: playing ? "pause" : "play", label: playing ? "Pause flythrough" : "Play flythrough", size: 12, active: playing, disabled: selected === null || selected.length <= 0, onClick: () => setPlaying((value) => !value) }), _jsx("button", { type: "button", className: `rounded-[5px] border px-2 py-0.5 text-[10px] uppercase tracking-wider transition-colors ${FOCUS_RING} ${loop
+    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col", children: [_jsxs("div", { className: "flex h-7 shrink-0 items-center gap-1.5 border-b border-white/[0.06] px-2", children: [_jsx("span", { className: "text-[10px] uppercase tracking-wider text-neutral-500", children: "Path flythrough" }), _jsxs("span", { className: `text-[10px] text-neutral-600 ${NUMERIC}`, children: [scrubbable.length, " path", scrubbable.length === 1 ? "" : "s", " \u00B7 camera follows scrub"] }), _jsxs("div", { className: "ml-auto flex items-center gap-1", children: [_jsx(IconButton, { icon: playing ? "pause" : "play", label: playing ? "Pause flythrough" : "Play flythrough", size: 12, active: playing, disabled: selected === null || selected.length <= 0, onClick: () => setPlaying((value) => !value) }), _jsx("button", { type: "button", className: `rounded-[5px] border px-2 py-0.5 text-[10px] uppercase tracking-wider transition-colors ${FOCUS_RING} ${loop
                                     ? "border-cyan-400/30 bg-cyan-500/15 text-cyan-200"
                                     : "border-white/[0.07] bg-white/[0.02] text-neutral-500 hover:text-neutral-300"}`, "aria-pressed": loop, "aria-label": loop ? "Loop on" : "Loop off", onClick: () => setLoop((value) => !value), children: "Loop" })] })] }), _jsxs("div", { className: "flex min-h-0 flex-1 gap-3 overflow-auto p-3", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsxs("label", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Path" }), _jsx("select", { className: `${INPUT_CLS} h-8 px-2 text-[12px]`, value: selected?.id ?? "", "aria-label": "Flythrough path", onChange: (event) => onSelectPath(event.target.value), children: scrubbable.map((entry) => (_jsxs("option", { value: entry.id, children: [entry.label, " \u00B7 ", entry.kind, " \u00B7 ", entry.pointCount, " pts"] }, entry.id))) })] }), _jsxs("label", { className: "flex flex-col gap-1", children: [_jsxs("div", { className: "flex items-center justify-between text-[9px] uppercase tracking-wider text-neutral-600", children: [_jsx("span", { children: "Progress" }), _jsxs("span", { className: NUMERIC, children: [(progress * 100).toFixed(0), "% \u00B7 ", distance.toFixed(1), " / ", lengthLabel.replace(" m", ""), " m"] })] }), _jsx("input", { type: "range", min: 0, max: 1, step: 0.001, value: progress, "aria-label": "Flythrough progress", disabled: selected === null || selected.length <= 0, className: `h-2 w-full accent-cyan-400 ${FOCUS_RING}`, onChange: (event) => onScrub(Number(event.target.value)) })] }), _jsxs("p", { className: "text-[10px] leading-relaxed text-neutral-600", children: ["Scope: real path points only \u2014 no fabricated keyframes. Play moves the orbit focus along the polyline at", " ", DEFAULT_PLAY_SPEED, " u/s. Edit points in the viewport or inspector."] })] }), _jsxs("div", { className: "flex w-40 shrink-0 flex-col gap-1.5", children: [_jsx(Meta, { label: "Kind", value: selected?.kind ?? "—" }), _jsx(Meta, { label: "Points", value: selected === null ? "—" : String(selected.pointCount) }), _jsx(Meta, { label: "Length", value: lengthLabel }), _jsx(Meta, { label: "At", value: selectedPath === undefined
                                     ? "—"

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/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.13.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.13.0",
-    "@jgengine/react": "^0.13.0",
-    "@jgengine/shell": "^0.13.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.
@@ -43,7 +45,7 @@ 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.
+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.13.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
 
@@ -220,7 +220,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.13.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