@jgengine/editor 0.13.0 → 0.15.0-next.0

package/dist/shell/HierarchyPanel.js

@@ -44,10 +44,8 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
     const [query, setQuery] = useState("");
     const [collapsedKinds, setCollapsedKinds] = useState({});
     const [collapsedNodes, setCollapsedNodes] = useState({});
-    const [visibilityTick, setVisibilityTick] = useState(0);
-    useEffect(() => api.subscribeVisibility(() => setVisibilityTick((value) => value + 1)), [api]);
-    void visibilityTick;
-    const visibility = api.getVisibility();
+    const visibilityStore = useMemo(() => ({ getState: api.getVisibility, subscribe: api.subscribeVisibility }), [api]);
+    const visibility = useStoreSelector(visibilityStore, (v) => v);
     const rows = useMemo(() => flattenOutliner(document, { view, query, collapsedKinds, collapsedNodes }), [document, view, query, collapsedKinds, collapsedNodes]);
     const total = document.markers.length + document.volumes.length + document.paths.length + document.annotations.length;
     const scrollRef = useRef(null);
@@ -79,15 +77,8 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
     const [activeId, setActiveId] = useState(null);
     const [renamingId, setRenamingId] = useState(null);
     const [renameDraft, setRenameDraft] = useState("");
-    const renameInputRef = useRef(null);
-    useEffect(() => {
-        if (activeId !== null && !navigableIds.includes(activeId))
-            setActiveId(navigableIds[0] ?? null);
-    }, [activeId, navigableIds]);
-    useEffect(() => {
-        if (renamingId !== null)
-            renameInputRef.current?.focus();
-    }, [renamingId]);
+    // Raw intent clamped at read time: a filtered-away active row falls back to the first row.
+    const effectiveActiveId = activeId === null ? null : navigableIds.includes(activeId) ? activeId : (navigableIds[0] ?? null);
     const focusTree = () => {
         scrollRef.current?.focus({ preventScroll: true });
     };
@@ -129,7 +120,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
     const onListFocus = () => {
         if (renamingId !== null)
             return;
-        if (activeId !== null && navigableIds.includes(activeId))
+        if (effectiveActiveId !== null)
             return;
         const seed = selectedId !== undefined && navigableIds.includes(selectedId)
             ? selectedId
@@ -142,7 +133,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
             return;
         if (navigableIds.length === 0)
             return;
-        const currentIndex = activeId === null ? -1 : navigableIds.indexOf(activeId);
+        const currentIndex = effectiveActiveId === null ? -1 : navigableIds.indexOf(effectiveActiveId);
         if (event.key === "ArrowDown" || event.key === "ArrowUp") {
             event.preventDefault();
             const delta = event.key === "ArrowDown" ? 1 : -1;
@@ -164,17 +155,17 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
             activateId(navigableIds[navigableIds.length - 1], event.shiftKey);
             return;
         }
-        if (event.key === "Enter" && activeId !== null) {
+        if (event.key === "Enter" && effectiveActiveId !== null) {
             event.preventDefault();
-            api.handle({ method: "camera_goto", id: activeId });
+            api.handle({ method: "camera_goto", id: effectiveActiveId });
             return;
         }
-        if (event.key === "F2" && activeId !== null) {
+        if (event.key === "F2" && effectiveActiveId !== null) {
             event.preventDefault();
-            const row = rows.find((entry) => (entry.type === "kindItem" && entry.ids[0] === activeId) ||
-                (entry.type === "treeItem" && entry.id === activeId));
+            const row = rows.find((entry) => (entry.type === "kindItem" && entry.ids[0] === effectiveActiveId) ||
+                (entry.type === "treeItem" && entry.id === effectiveActiveId));
             if (row !== undefined && (row.type === "kindItem" || row.type === "treeItem")) {
-                beginRename(activeId, row.label);
+                beginRename(effectiveActiveId, row.label);
             }
         }
     };
@@ -245,7 +236,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
             return;
         session.dispatch({ type: "setObjectFlags", ids: [...ids], patch: { locked: true } });
     };
-    const activeDescendant = hierarchyActiveDescendantId(activeId, navigableIds);
+    const activeDescendant = hierarchyActiveDescendantId(effectiveActiveId, navigableIds);
     return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "space-y-1.5 border-b border-white/[0.06] p-2", children: [_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsxs("div", { className: "relative min-w-0 flex-1", children: [_jsx(Icon, { name: "search", size: 12, className: "pointer-events-none absolute left-2 top-1/2 -translate-y-1/2 text-neutral-600" }), _jsx("input", { type: "search", value: query, onChange: (event) => setQuery(event.target.value), placeholder: "Search\u2026", "aria-label": "Search scene objects", className: `h-7 w-full pl-7 pr-2 ${INPUT_CLS}` })] }), _jsx(IconButton, { icon: "plus", label: "Add object\u2026", onClick: onAdd })] }), _jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx(Segmented, { ariaLabel: "Outliner grouping", value: view, onChange: setView, options: [
                                     { value: "kind", label: "By kind", icon: "layers" },
                                     { value: "tree", label: "Tree", icon: "folder" },
@@ -273,7 +264,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
                                 const hidden = rowHidden(row.ids);
                                 const collectionOnlyLock = locked &&
                                     row.ids.every((id) => isEditorObjectCollectionLocked(document, id) && !isEditorObjectSelfLocked(document, id));
-                                const active = activeId === primaryId;
+                                const active = effectiveActiveId === primaryId;
                                 const renaming = renamingId === primaryId && row.ids.length === 1;
                                 return (_jsxs("div", { id: hierarchyRowDomId(primaryId), role: "treeitem", "aria-selected": rowSelected, "aria-level": 2, style: { height: ROW_HEIGHT }, className: `group flex w-full items-center gap-0.5 rounded-[5px] pl-6 pr-0.5 text-[11px] transition-colors ${dropActive
                                         ? "bg-cyan-500/25 ring-1 ring-inset ring-cyan-300/50"
@@ -294,7 +285,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
                                                 event.preventDefault();
                                                 setActiveId(primaryId);
                                                 onRowContextMenu?.({ clientX: event.clientX, clientY: event.clientY }, primaryId);
-                                            }, children: [_jsx(Icon, { name: kindIcon(row.kind), size: 13, className: `shrink-0 ${rowSelected || active ? "text-cyan-300" : "text-neutral-500"}` }), renaming ? (_jsx("input", { ref: renameInputRef, value: renameDraft, onChange: (event) => setRenameDraft(event.target.value), onBlur: commitRename, onKeyDown: (event) => {
+                                            }, children: [_jsx(Icon, { name: kindIcon(row.kind), size: 13, className: `shrink-0 ${rowSelected || active ? "text-cyan-300" : "text-neutral-500"}` }), renaming ? (_jsx("input", { autoFocus: true, value: renameDraft, onChange: (event) => setRenameDraft(event.target.value), onBlur: commitRename, onKeyDown: (event) => {
                                                         event.stopPropagation();
                                                         if (event.key === "Enter") {
                                                             event.preventDefault();
@@ -331,7 +322,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
                             const hidden = isEditorObjectHidden(document, row.id);
                             const collectionOnlyLock = isEditorObjectCollectionLocked(document, row.id) && !isEditorObjectSelfLocked(document, row.id);
                             const dragging = draggingObjectId === row.id;
-                            const active = activeId === row.id;
+                            const active = effectiveActiveId === row.id;
                             const renaming = renamingId === row.id;
                             const expanded = row.hasChildren ? collapsedNodes[row.id] !== true : undefined;
                             return (_jsxs("div", { id: hierarchyRowDomId(row.id), role: "treeitem", "aria-selected": rowSelected, "aria-level": row.depth + 1, "aria-expanded": expanded, style: { height: ROW_HEIGHT, paddingLeft: `${row.depth * 12}px` }, className: `group flex items-center ${hidden ? "opacity-55" : ""}`, children: [row.hasChildren ? (_jsx("button", { type: "button", tabIndex: -1, "aria-label": collapsedNodes[row.id] === true ? "Expand children" : "Collapse children", className: `flex h-4 w-4 shrink-0 items-center justify-center text-neutral-500 transition-colors hover:text-neutral-200 ${FOCUS_RING}`, onMouseDown: preventFocusSteal, onClick: () => setCollapsedNodes((previous) => ({ ...previous, [row.id]: !(previous[row.id] === true) })), children: _jsx(Icon, { name: collapsedNodes[row.id] === true ? "chevronRight" : "chevronDown", size: 10 }) })) : (_jsx("span", { className: "w-4 shrink-0", "aria-hidden": "true" })), _jsxs("button", { type: "button", tabIndex: -1, draggable: true, className: `flex h-full min-w-0 flex-1 items-center gap-1.5 truncate rounded-[5px] px-1.5 text-left text-[11px] transition-colors ${FOCUS_RING} ${materialDrop || reparentDrop
@@ -364,7 +355,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
                                             if (commitMaterialDrop(event, [row.id]))
                                                 return;
                                             commitReparentDrop(event, row.id);
-                                        }, children: [_jsx(Icon, { name: kindIcon(row.kind), size: 13, className: `shrink-0 ${rowSelected || active ? "text-cyan-300" : "text-neutral-500"}` }), renaming ? (_jsx("input", { ref: renameInputRef, value: renameDraft, onChange: (event) => setRenameDraft(event.target.value), onBlur: commitRename, onKeyDown: (event) => {
+                                        }, children: [_jsx(Icon, { name: kindIcon(row.kind), size: 13, className: `shrink-0 ${rowSelected || active ? "text-cyan-300" : "text-neutral-500"}` }), renaming ? (_jsx("input", { autoFocus: true, value: renameDraft, onChange: (event) => setRenameDraft(event.target.value), onBlur: commitRename, onKeyDown: (event) => {
                                                     event.stopPropagation();
                                                     if (event.key === "Enter") {
                                                         event.preventDefault();

package/dist/shell/PlayModeBar.d.ts

@@ -1,4 +1,11 @@
+import type { RuntimePlayControl } from "@jgengine/core/editor/index";
 import type { EditorHostApi } from "../session.js";
+/**
+ * Subscribe to the host runtime play-control (pause / pending steps) as an external store.
+ * Shared by the play-mode chrome pieces so none of them hand-rolls a `setState` mirror.
+ * @internal
+ */
+export declare function usePlayControl(api: EditorHostApi): RuntimePlayControl;
 /**
  * Slim shell chrome for Play mode — same app-bar language as edit mode so switching modes
  * does not feel like an app swap. Pause / Resume / Step drive the existing runtime play

package/dist/shell/PlayModeBar.js

@@ -1,8 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { useMemo } from "react";
+import { useStoreSelector } from "../useStoreSelector.js";
 import { Icon } from "./icons.js";
 import { BORDER, FOCUS_RING } from "./theme.js";
 import { IconButton, ToolbarDivider } from "./ui.js";
+/**
+ * Subscribe to the host runtime play-control (pause / pending steps) as an external store.
+ * Shared by the play-mode chrome pieces so none of them hand-rolls a `setState` mirror.
+ * @internal
+ */
+export function usePlayControl(api) {
+    const store = useMemo(() => ({ getState: api.getPlayControl, subscribe: api.subscribePlayControl }), [api]);
+    return useStoreSelector(store, (play) => play);
+}
 /**
  * Slim shell chrome for Play mode — same app-bar language as edit mode so switching modes
  * does not feel like an app swap. Pause / Resume / Step drive the existing runtime play
@@ -10,8 +20,7 @@ import { IconButton, ToolbarDivider } from "./ui.js";
  * @internal
  */
 export function PlayModeBar({ gameId, api, onExit, }) {
-    const [play, setPlay] = useState(() => api.getPlayControl());
-    useEffect(() => api.subscribePlayControl(setPlay), [api]);
+    const play = usePlayControl(api);
     const pause = () => {
         api.handle({ method: "runtime_pause" });
     };

package/dist/shell/SceneToolbar.js

@@ -112,11 +112,15 @@ export function SceneToolbar({ tool, gizmoMode, gizmoSpace, gizmoPivot, snapMode
                     ? "border-cyan-400/30 bg-cyan-500/15 text-cyan-100"
                     : "border-white/[0.07] bg-[#191d24] text-neutral-300 hover:bg-[#1f242d]"}`, children: [_jsx(Icon, { name: "camera", size: 12 }), cameraProjection === "perspective" ? "Persp" : "Ortho"] }), _jsx(ToolbarDivider, {}), _jsxs("div", { className: "relative", children: [_jsxs("button", { type: "button", onClick: () => setAddOpen((value) => !value), "aria-expanded": addOpen, className: `flex h-7 items-center gap-1.5 rounded-[5px] px-2.5 text-[12px] font-medium transition-colors ${FOCUS_RING} ${addOpen || placementActive
                             ? "bg-cyan-600 text-white shadow-sm shadow-cyan-950/40"
-                            : "border border-white/[0.07] bg-[#191d24] text-neutral-200 hover:bg-[#1f242d]"}`, children: [_jsx(Icon, { name: "plus", size: 12 }), "Add"] }), _jsxs(MenuShell, { open: addOpen, onClose: () => setAddOpen(false), children: [_jsx("div", { className: `px-2 pb-1 pt-1.5 ${MICRO_LABEL}`, children: "Markers" }), WELL_KNOWN_MARKER_KINDS.map((kind) => (_jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "marker", kind }), children: kind }, kind))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: "Volumes" }), ADD_VOLUME_ENTRIES.map((entry) => (_jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick(entry.tool), children: entry.label }, entry.label))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: "Studios" }), studioKinds.map((definition) => (_jsxs("button", { type: "button", className: `${MENU_ITEM}`, style: { color: definition.accent ?? "#34d399" }, onClick: () => pick(definition.target === "path"
-                                    ? { tool: "path", kind: definition.kind }
-                                    : definition.target === "volume"
-                                        ? { tool: "volume", kind: definition.kind, shape: "box" }
-                                        : { tool: "marker", kind: definition.kind }), children: [definition.label, definition.target === "path" ? (definition.pathShape === "line" ? " (draw line)" : " (lasso)") : ""] }, definition.kind))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: "Paths & notes" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "path", kind: "route" }), children: "Draw path (route)" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "path", kind: "road" }), children: "Draw road" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "note" }), children: "Note" })] })] }), _jsx("div", { className: "ml-auto flex items-center gap-1", children: _jsxs("button", { type: "button", onClick: onOpenAssistant, className: `flex h-7 items-center gap-1.5 rounded-[5px] px-2.5 text-[12px] transition-colors ${FOCUS_RING} ${assistantOpen
+                            : "border border-white/[0.07] bg-[#191d24] text-neutral-200 hover:bg-[#1f242d]"}`, children: [_jsx(Icon, { name: "plus", size: 12 }), "Add"] }), _jsxs(MenuShell, { open: addOpen, onClose: () => setAddOpen(false), children: [_jsx("div", { className: `px-2 pb-1 pt-1.5 ${MICRO_LABEL}`, children: "Markers" }), WELL_KNOWN_MARKER_KINDS.map((kind) => (_jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "marker", kind }), children: kind }, kind))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: "Volumes" }), ADD_VOLUME_ENTRIES.map((entry) => (_jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick(entry.tool), children: entry.label }, entry.label))), [...studioKinds.reduce((groups, definition) => {
+                                    const category = definition.addCategory ?? "Studios";
+                                    (groups.get(category) ?? groups.set(category, []).get(category)).push(definition);
+                                    return groups;
+                                }, new Map())].map(([category, defs]) => (_jsxs("div", { children: [_jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: category }), defs.map((definition) => (_jsxs("button", { type: "button", className: `${MENU_ITEM}`, style: { color: definition.accent ?? "#34d399" }, onClick: () => pick(definition.target === "path"
+                                            ? { tool: "path", kind: definition.kind }
+                                            : definition.target === "volume"
+                                                ? { tool: "volume", kind: definition.kind, shape: "box" }
+                                                : { tool: "marker", kind: definition.kind }), children: [definition.label, definition.target === "path" ? (definition.pathShape === "line" ? " (draw line)" : " (lasso)") : ""] }, definition.kind)))] }, category))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: "Paths & notes" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "path", kind: "route" }), children: "Draw path (route)" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "path", kind: "road" }), children: "Draw road" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "note" }), children: "Note" })] })] }), _jsx("div", { className: "ml-auto flex items-center gap-1", children: _jsxs("button", { type: "button", onClick: onOpenAssistant, className: `flex h-7 items-center gap-1.5 rounded-[5px] px-2.5 text-[12px] transition-colors ${FOCUS_RING} ${assistantOpen
                         ? "border border-violet-400/40 bg-violet-500/20 text-violet-100"
                         : "border border-white/[0.07] bg-[#191d24] text-neutral-300 hover:bg-[#1f242d] hover:text-neutral-100"}`, title: "AI assistant \u2014 drives the scene through the same RPC and undo as the toolbar", children: [_jsx(Icon, { name: "sparkle", size: 13 }), "AI"] }) })] }));
 }

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/fields.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from "react";
+import { useRef, useState } from "react";
 import { AXIS_COLORS, FOCUS_RING, INPUT_CLS, NUMERIC } from "./theme.js";
 /** Pixels of pointer drag per `step` of value change when scrubbing an axis chip. */
 const DRAG_PX_PER_STEP = 4;
@@ -15,14 +15,12 @@ function formatValue(value, precision) {
  * values on change and re-normalizes its text on blur. Invalid text never commits.
  */
 export function AxisNumberField({ axis, label, value, onCommit, step = 0.1, precision = 3, disabled = false, mixed = false, }) {
-    const [text, setText] = useState(() => (mixed ? "—" : formatValue(value, precision)));
+    // `text` only exists while the input has focus; otherwise the shown value derives from props.
+    const [text, setText] = useState("");
     const [editing, setEditing] = useState(false);
     const inputRef = useRef(null);
     const dragRef = useRef(null);
-    useEffect(() => {
-        if (!editing)
-            setText(mixed ? "—" : formatValue(value, precision));
-    }, [value, precision, editing, mixed]);
+    const formatted = mixed ? "—" : formatValue(value, precision);
     const commitText = (raw) => {
         if (raw === "—" || raw.trim().length === 0)
             return;
@@ -69,7 +67,10 @@ export function AxisNumberField({ axis, label, value, onCommit, step = 0.1, prec
         }
     };
     const colors = axis !== undefined ? AXIS_COLORS[axis] : null;
-    return (_jsxs("label", { title: `Drag to adjust ${label} · Alt-click or focus input to type`, onPointerDown: onScrubPointerDown, onPointerMove: onScrubPointerMove, onPointerUp: onScrubPointerUp, className: `flex min-w-0 flex-1 cursor-ew-resize items-center overflow-hidden rounded-[5px] border border-white/[0.08] bg-black/30 focus-within:border-cyan-400/50 ${editing ? "cursor-text" : ""}`, children: [_jsxs("span", { className: `relative flex h-6.5 w-6 shrink-0 select-none items-center justify-center border-r border-white/[0.06] bg-white/[0.03] text-[10px] font-semibold uppercase ${colors !== null ? colors.text : "text-neutral-500"}`, children: [colors !== null ? _jsx("span", { className: `absolute inset-y-0 left-0 w-0.5 ${colors.bar}` }) : null, label] }), _jsx("input", { ref: inputRef, type: "text", inputMode: "decimal", value: text, disabled: disabled, "aria-label": label, onFocus: () => setEditing(true), onDoubleClick: (event) => {
+    return (_jsxs("label", { title: `Drag to adjust ${label} · Alt-click or focus input to type`, onPointerDown: onScrubPointerDown, onPointerMove: onScrubPointerMove, onPointerUp: onScrubPointerUp, className: `flex min-w-0 flex-1 cursor-ew-resize items-center overflow-hidden rounded-[5px] border border-white/[0.08] bg-black/30 focus-within:border-cyan-400/50 ${editing ? "cursor-text" : ""}`, children: [_jsxs("span", { className: `relative flex h-6.5 w-6 shrink-0 select-none items-center justify-center border-r border-white/[0.06] bg-white/[0.03] text-[10px] font-semibold uppercase ${colors !== null ? colors.text : "text-neutral-500"}`, children: [colors !== null ? _jsx("span", { className: `absolute inset-y-0 left-0 w-0.5 ${colors.bar}` }) : null, label] }), _jsx("input", { ref: inputRef, type: "text", inputMode: "decimal", value: editing ? text : formatted, disabled: disabled, "aria-label": label, onFocus: () => {
+                    setText(formatted);
+                    setEditing(true);
+                }, onDoubleClick: (event) => {
                     event.stopPropagation();
                     event.currentTarget.select();
                 }, onChange: (event) => {
@@ -78,7 +79,6 @@ export function AxisNumberField({ axis, label, value, onCommit, step = 0.1, prec
                 }, onBlur: (event) => {
                     setEditing(false);
                     commitText(event.target.value);
-                    setText(formatValue(Number.isFinite(Number(event.target.value)) ? Number(event.target.value) : value, precision));
                 }, onKeyDown: (event) => {
                     if (event.key === "Enter")
                         event.currentTarget.blur();

package/dist/shell/glbThumbnailCache.js

@@ -15,6 +15,16 @@ const MAX_CONCURRENT = 1;
 const cache = new Map();
 const queue = [];
 let active = 0;
+/** Shared idle snapshot — one stable identity for every "no thumbnail yet" case. */
+const IDLE_STATE = { status: "idle", dataUrl: null };
+/**
+ * Last snapshot handed out per URL. `getGlbThumbnailState` is the `getSnapshot`
+ * for `useSyncExternalStore`, which requires a referentially stable result while
+ * the underlying state is unchanged: returning a fresh object literal every call
+ * makes React's post-commit consistency check ("Maximum update depth exceeded")
+ * fire forever. We reuse the prior object until status/dataUrl actually changes.
+ */
+const snapshots = new Map();
 let renderer = null;
 let scene = null;
 let camera = null;
@@ -32,6 +42,7 @@ export function resetGlbThumbnailLoader() {
 /** @internal Clear cache + dispose GPU resources (tests / hot dispose). */
 export function clearGlbThumbnailCache() {
     cache.clear();
+    snapshots.clear();
     queue.length = 0;
     active = 0;
     disposeRenderer();
@@ -132,6 +143,7 @@ function evictIfNeeded() {
         if (entry.status !== "ready")
             continue;
         cache.delete(key);
+        snapshots.delete(key);
         if (cache.size <= MAX_CACHE)
             return;
     }
@@ -193,15 +205,34 @@ function pump() {
  */
 export function getGlbThumbnailState(url) {
     if (url === undefined || url.length === 0)
-        return { status: "idle", dataUrl: null };
+        return IDLE_STATE;
     const entry = cache.get(url);
-    if (entry === undefined)
-        return { status: "idle", dataUrl: null };
-    if (entry.status === "ready")
-        return { status: "ready", dataUrl: entry.dataUrl };
-    if (entry.status === "error")
-        return { status: "error", dataUrl: null };
-    return { status: "loading", dataUrl: null };
+    if (entry === undefined) {
+        snapshots.delete(url);
+        return IDLE_STATE;
+    }
+    const prev = snapshots.get(url);
+    // Reuse the prior snapshot object whenever the observable state is unchanged so
+    // useSyncExternalStore sees a stable reference (no infinite re-render loop).
+    if (entry.status === "ready") {
+        if (prev !== undefined && prev.status === "ready" && prev.dataUrl === entry.dataUrl)
+            return prev;
+        const next = { status: "ready", dataUrl: entry.dataUrl };
+        snapshots.set(url, next);
+        return next;
+    }
+    if (entry.status === "error") {
+        if (prev !== undefined && prev.status === "error")
+            return prev;
+        const next = { status: "error", dataUrl: null };
+        snapshots.set(url, next);
+        return next;
+    }
+    if (prev !== undefined && prev.status === "loading")
+        return prev;
+    const next = { status: "loading", dataUrl: null };
+    snapshots.set(url, next);
+    return next;
 }
 /**
  * Ensures a thumbnail render is in flight (or already cached) for `url`.

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,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { scatterFootprintArea } from "@jgengine/core/world/scatterCoverage";
+import { useDebouncedCommit } from "@jgengine/react/useDebouncedCommit";
+import { MICRO_LABEL } from "./theme.js";
+const fmt = (n) => Math.round(n).toLocaleString();
+/**
+ * The hoisted density slider: live-mirrored thumb + readout, debounced commit flushed on release
+ * (#1372). Scatter/grass/city regen is heavy, so one write per pause instead of ~50 per drag.
+ */
+function CoverageDensitySlider({ field, density, densityKey, onMeta, }) {
+    const { value: local, onInput, flush } = useDebouncedCommit(density, (next) => onMeta({ [densityKey]: next }, `kind:${densityKey}`));
+    return (_jsxs("label", { className: "block space-y-1", children: [_jsxs("span", { className: "flex items-center justify-between", children: [_jsx("span", { className: MICRO_LABEL, children: field.label ?? field.key }), _jsxs("span", { className: "text-cyan-200", children: [local.toFixed(field.step !== undefined && field.step >= 1 ? 0 : 2), field.unit ?? ""] })] }), _jsx("input", { type: "range", min: field.min, max: field.max, step: field.step ?? (field.max - field.min) / 100, value: local, className: "w-full accent-emerald-400", "aria-label": `${field.label ?? field.key} density`, onChange: (event) => onInput(Number(event.target.value)), onPointerUp: flush, onKeyUp: flush, onBlur: flush })] }));
+}
+/** 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" ? (_jsx(CoverageDensitySlider, { field: densityField, density: density, densityKey: coverage.densityKey, onMeta: onMeta })) : 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/dist/useStoreSelector.d.ts

@@ -10,6 +10,18 @@ export interface SubscribableStore<S> {
  * slice. The selected value is memoized so an equal slice keeps its reference (no render churn).
  */
 export declare function useStoreSelector<S, T>(store: SubscribableStore<S>, selector: (state: S) => T, isEqual?: (a: T, b: T) => boolean): T;
+/** A notification-only source — `subscribe` is all a coarse invalidation needs. */
+export interface SubscribableSource {
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Subscribe a component to **every** notification from one or more sources, returning a monotonic
+ * version number via `useSyncExternalStore`. For components that read `store.getState()` directly
+ * in render (whole-store chrome) or fan several sources into one coarse invalidation — the version
+ * is a `useMemo` cache key, not data.
+ * @internal
+ */
+export declare function useStoreVersion(...sources: readonly SubscribableSource[]): number;
 /** Shallow array equality — for selectors that return id lists (`selection`) or small tuples. */
 export declare function shallowArrayEqual<T>(a: readonly T[], b: readonly T[]): boolean;
 /** The visible slice of a fixed-row-height list: which rows to mount and the spacer geometry. */