@jgengine/editor 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -10,7 +10,53 @@ let consumers pick up the better stuff, not just to list what moved.
 Agents building on the published SDK can also read this programmatically:
 `import { VERSION, CHANGELOG } from "@jgengine/core/meta/changelog"` gives the
 same data as typed values, so an updater can diff its installed version against
-the latest and surface the migration steps.
+the latest and surface the migration steps. Easier still: `npx jgengine upgrade`
+run inside a game project diffs the installed `@jgengine/*` versions against the
+latest release and prints every Migrate step and Adopt-worthy addition in
+between (`--json` for structured output).
+
+## [Unreleased]
+
+<!--
+Every PR that changes `packages/*/src` records its consumer-facing change here, so
+the next release's notes are complete by construction. Add a bullet under the right
+subhead below. `bun run check-changelog` fails a source PR whose `[Unreleased]` block
+is untouched; pure refactors/tests bypass with `[skip changelog]` in a commit message.
+At publish, rename this heading to the new version and mirror the entries into
+`packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
+-->
+
+### Migrate
+
+- _Nothing yet._
+
+### Added
+
+### Changed
+
+### Removed
+
+## 0.14.0
+
+### Migrate
+
+- **Nothing required** — this release is additive drop-in primitives, editor authoring, CLI discovery, and fixes. Bump `@jgengine/*` pins to `^0.14.0` (CLI `jgengine` is 0.11.0; `@jgengine/github` unchanged at 0.1.0) and rebuild.
+- One behavior fix to know about: in a `rig: "chase"` game, on-foot movement and aim are now camera-relative (the chase rig reports its yaw to the shell like every other rig). If a game somehow relied on world-yaw-0 movement under a chase camera, that was the bug this fixes.
+
+### Added
+
+- One authoring gesture for scatterable coverage: `@jgengine/core/world/scatterCoverage` owns shared density/budget semantics (per-kind unit, requested→count→capped, one clamp-and-warn phrasing) for `grass_field`/`scatter`/`city`; the editor inspector leads each kind with the same Area → Assets → Density coverage section, scatter truncates to the shared 250k instance budget, and city single-sources its 2,600-lot cap.
+- **Created games ship a drive/playtest script** (#1248) — `npx jgengine create` scaffolds now include `scripts/drive.mjs` (`bun run drive`): dependency-free headless play/testing of the running game — ordered `--click`/`--key`/`--wait`/`--shot`/`--rpc` steps against the agent bridge, plus `--playtest --strict` progress/softlock verdicts off `capture.probe`. Shared Chrome/CDP machinery lives in `scripts/browser.mjs`; `scripts/shoot.mjs` is unchanged in behavior, now a thin CLI over it.
+- Editor: viewport clip preview for rigged assets (Animation dock "Clips" mode — pick a rig or placed instance, play/scrub/loop/speed any catalog clip) and an Inspector "Animation" section that authors a placement's `ModelConfig.animation` (role→clip dropdowns, auto/none, walk/run/fade, one-shot event bindings) as undoable `marker.meta.animation` edits. New subpaths: `@jgengine/editor/shell/clipPreview`, `@jgengine/editor/modelAnimationAuthoring`, `@jgengine/editor/ClipPreviewLayer`.
+- **`npx jgengine find <intent>`** — active capability discovery: searches every shipped domain's `capabilities.md` (staged inside the CLI tarball, so it works regardless of which `@jgengine/*` packages a project installed) and prints the drop-in primitive + its import for an intent like `"toggleable window"`, `inventory`, or `minimap`. Scaffolded games are now briefed (in `AGENTS.md` and the `jgengine` intake skill) to reach for it before hand-rolling a HUD/inventory/window/rig.
+- **`EntityPreview`** (`@jgengine/shell/render/EntityPreview`) — drop-in live 3D entity portrait for character screens, unit inspectors, and loadout viewers. Owns the nested `<Canvas>`, the `GameContextBridge`, and a `StudioStage` lighting rig with optional turntable / face-camera; the game passes its own `renderEntity` as children (or a native `model` + `instanceId`) and, bound to a live entity, the portrait walks/flinches/topples in sync with the world.
+- **`GameContextBridge`** (`@jgengine/react`) — re-provide the running `GameContext` across a nested React reconciler boundary (the R3F `<Canvas>`), so a game building its own preview canvas no longer re-derives the bridge by hand.
+
+### Changed
+
+- **Chase rig reports its yaw to the shell** — `ChaseRig` now writes the camera yaw back to the shared yaw ref like every other player-facing rig, so on-foot movement and aim in a `rig: "chase"` game are camera-relative instead of frozen to world yaw 0 (WASD no longer fights the camera the moment it swings behind the player). Interior views (cockpit/hood/rear) report the vehicle heading.
+- **Combat VFX no longer render as black squares under AO/DOF post-processing** (#1247) — GTAO/Bokeh scene prepasses skip overlay effects. Games with custom additive overlay effects opt out the same way: spread `POSTFX_OVERLAY_USERDATA` (`@jgengine/shell/postfx/postfxOverlay`) onto the overlay group's `userData`.
+- **`PanelHost` windows stack above the HUD by default** (`@jgengine/react`) — the host establishes its own stacking context at `zIndexBase` (default 40), so open windows always paint over stat bars / nameplates / frames instead of bleeding through. Overridable per instance.
 
 ## 0.13.0
 

package/dist/ClipPreviewLayer.d.ts

@@ -0,0 +1,15 @@
+import type { EditorHostApi } from "./session.js";
+import type { EditorUiStore } from "./uiStore.js";
+/**
+ * Viewport layer that renders the active clip-preview asset playing the selected clip, mounted by
+ * `EditorApp` inside the editor's R3F scene + GameContext. Reuses the shell's shared GLTF loader,
+ * scene clone, and `useModelAnimation` mixer — the same driver `EntityModel` runs at play time — so
+ * the preview IS the runtime playback. Reads the live session from the editor UI store and publishes
+ * the selected clip's measured duration back so the dock scrubber can normalize.
+ *
+ * @internal — not a game-author entry point.
+ */
+export declare function ClipPreviewLayer({ api, ui }: {
+    api: EditorHostApi;
+    ui: EditorUiStore;
+}): import("react").JSX.Element | null;

package/dist/ClipPreviewLayer.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense, useEffect, useMemo } from "react";
+import { useLoader } from "@react-three/fiber";
+import * as THREE from "three";
+import { sharedGltfLoader } from "@jgengine/shell/render/modelLoad";
+import { cloneModelScene, disposeClonedMaterials } from "@jgengine/shell/render/modelRender";
+import { useModelAnimation } from "@jgengine/shell/render/useModelAnimation";
+import { previewAnimationConfig } from "./shell/clipPreview.js";
+import { useStoreSelector } from "./useStoreSelector.js";
+/** World-unit height the previewed model is normalized to, so tiny/huge rigs are both framed. */
+const PREVIEW_TARGET_HEIGHT = 2;
+/**
+ * Viewport layer that renders the active clip-preview asset playing the selected clip, mounted by
+ * `EditorApp` inside the editor's R3F scene + GameContext. Reuses the shell's shared GLTF loader,
+ * scene clone, and `useModelAnimation` mixer — the same driver `EntityModel` runs at play time — so
+ * the preview IS the runtime playback. Reads the live session from the editor UI store and publishes
+ * the selected clip's measured duration back so the dock scrubber can normalize.
+ *
+ * @internal — not a game-author entry point.
+ */
+export function ClipPreviewLayer({ api, ui }) {
+    const session = useStoreSelector(ui, (state) => state.clipPreview);
+    if (session === null)
+        return null;
+    return (_jsx(Suspense, { fallback: null, children: _jsx(ClipPreviewModel, { session: session, api: api, ui: ui }, session.source.assetId) }));
+}
+function ClipPreviewModel({ session, api, ui, }) {
+    const { source, driver } = session;
+    const gltf = useLoader(sharedGltfLoader, source.url);
+    const scene = useMemo(() => cloneModelScene(gltf.scene), [gltf]);
+    useEffect(() => () => disposeClonedMaterials(scene), [scene]);
+    // Normalize height and center/ground so any rig frames nicely at the camera focus point.
+    const placement = useMemo(() => {
+        const box = new THREE.Box3().setFromObject(scene);
+        const height = box.max.y - box.min.y;
+        if (!Number.isFinite(height) || height <= 0)
+            return { scale: 1, minY: 0, centerX: 0, centerZ: 0 };
+        return {
+            scale: PREVIEW_TARGET_HEIGHT / height,
+            minY: box.min.y,
+            centerX: (box.min.x + box.max.x) / 2,
+            centerZ: (box.min.z + box.max.z) / 2,
+        };
+    }, [scene]);
+    const config = useMemo(() => previewAnimationConfig(driver), [driver]);
+    useModelAnimation(scene, gltf.animations, config, undefined);
+    // Publish the selected clip's duration once loaded so the dock scrubber can span it (0 = unknown).
+    const clipName = driver.clipName;
+    useEffect(() => {
+        const clip = clipName === null ? undefined : gltf.animations.find((entry) => entry.name === clipName);
+        const duration = clip?.duration ?? 0;
+        const current = ui.getState().clipPreview;
+        if (current !== null && current.source.assetId === source.assetId && current.duration !== duration) {
+            ui.patch({ clipPreview: { ...current, duration } });
+        }
+    }, [gltf, clipName, ui, source.assetId]);
+    const focus = api.getFocusTarget() ?? { x: 0, y: 0, z: 0 };
+    const s = placement.scale;
+    return (_jsx("group", { position: [focus.x, focus.y, focus.z], children: _jsx("primitive", { object: scene, scale: s, position: [-s * placement.centerX, -s * placement.minY, -s * placement.centerZ] }) }));
+}

package/dist/EditorApp.js

@@ -15,6 +15,7 @@ import { MaterialDropZone } from "./MaterialDropZone.js";
 import { PerfProbe } from "./PerfProbe.js";
 import { ScatterPreview } from "./ScatterPreview.js";
 import { CityPreview } from "./CityPreview.js";
+import { ClipPreviewLayer } from "./ClipPreviewLayer.js";
 import { SelectionGizmo, ViewportSelect } from "./SelectionGizmo.js";
 import { TerrainReadout } from "./TerrainReadout.js";
 import { TerrainReadoutHud } from "./TerrainReadoutHud.js";
@@ -153,7 +154,7 @@ function EditorWorldOverlay({ api, ui, world, readout, }) {
             unsubscribe();
         };
     }, [session, readoutActive]);
-    return (_jsxs(_Fragment, { children: [_jsx(PerfProbe, { api: api }), _jsx(EditorCameraDriver, { api: api }), _jsx(ViewportSelect, { api: api, ui: ui }), _jsx(MaterialDropZone, { api: api }), _jsx(AssetDropZone, { api: api }), _jsx(TerrainSculpt, { api: api, ui: ui, world: world }), _jsx(ScatterPreview, { api: api }), _jsx(CityPreview, { api: api }), showGrid ? _jsx("gridHelper", { args: [400, 80, "#3b4252", "#20242e"], position: [0, 0.05, 0] }) : null, readoutActive ? (_jsx(TerrainReadout, { groundHeightAt: groundHeightAt, region: readoutRegion, showContours: showContours, showSurfaceGrid: showSurfaceGrid, version: terrainVersion, readout: readout })) : null, _jsx(EditorLayerOverlays, { document: document, visibility: visibility, selection: selection, hoverId: hoverId, onSelect: (id) => session.dispatch({ type: "select", ids: [id] }), activePathPoint: pathPoint, groundHeightAt: groundHeightAt }), pathDraft.length > 0 ? _jsx(PathDraftPreview, { points: pathDraft }) : null, _jsx(SelectionGizmo, { session: session, ui: ui, groundSnap: groundHeightAt })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(PerfProbe, { api: api }), _jsx(EditorCameraDriver, { api: api }), _jsx(ViewportSelect, { api: api, ui: ui }), _jsx(MaterialDropZone, { api: api }), _jsx(AssetDropZone, { api: api }), _jsx(TerrainSculpt, { api: api, ui: ui, world: world }), _jsx(ScatterPreview, { api: api }), _jsx(CityPreview, { api: api }), _jsx(ClipPreviewLayer, { api: api, ui: ui }), showGrid ? _jsx("gridHelper", { args: [400, 80, "#3b4252", "#20242e"], position: [0, 0.05, 0] }) : null, readoutActive ? (_jsx(TerrainReadout, { groundHeightAt: groundHeightAt, region: readoutRegion, showContours: showContours, showSurfaceGrid: showSurfaceGrid, version: terrainVersion, readout: readout })) : null, _jsx(EditorLayerOverlays, { document: document, visibility: visibility, selection: selection, hoverId: hoverId, onSelect: (id) => session.dispatch({ type: "select", ids: [id] }), activePathPoint: pathPoint, groundHeightAt: groundHeightAt }), pathDraft.length > 0 ? _jsx(PathDraftPreview, { points: pathDraft }) : null, _jsx(SelectionGizmo, { session: session, ui: ui, groundSnap: groundHeightAt })] }));
 }
 /** Default skin for the play/walk escape chip; swap via `EditorAppProps.modeChip`, or pass `null` to hide it (F2+E still exits). */
 function EditorModeChip({ mode, onExit }) {

package/dist/EditorChrome.js

@@ -745,11 +745,11 @@ export function EditorChrome({ gameId, session, api, assets, ui, baselineDocumen
                                                     ? `Parented to ${parentId}`
                                                     : `Parented ${ids.length} objects to ${parentId}`);
                                             }
-                                        }, onClose: () => setParentPicker(null) })) : null] }), layoutState.bottomOpen ? (_jsxs(_Fragment, { children: [_jsx(PanelResizer, { orientation: "horizontal", label: "Resize bottom dock", sign: -1, onResize: (delta) => layout.resize("bottomHeight", delta) }), _jsx("div", { className: "flex shrink-0 flex-col", style: { height: layoutState.bottomHeight }, children: _jsx(BottomDock, { tab: layoutState.bottomTab, onSelectTab: (tab) => layout.patch({ bottomTab: tab }), onClose: () => layout.patch({ bottomOpen: false }), assets: liveAssets, session: session, api: api, consoleStore: consoleStore, perfHistory: perfHistory, browserView: layoutState.browserView, onSetBrowserView: (view) => layout.patch({ browserView: view }), onPlaceAsset: placeAsset, onImportModels: importModels, importBusy: importBusy }) })] })) : (_jsxs("div", { className: `pointer-events-auto flex h-7 shrink-0 items-center gap-1 border-t ${BORDER} bg-[#0e1014] px-1.5`, children: [[
+                                        }, onClose: () => setParentPicker(null) })) : null] }), layoutState.bottomOpen ? (_jsxs(_Fragment, { children: [_jsx(PanelResizer, { orientation: "horizontal", label: "Resize bottom dock", sign: -1, onResize: (delta) => layout.resize("bottomHeight", delta) }), _jsx("div", { className: "flex shrink-0 flex-col", style: { height: layoutState.bottomHeight }, children: _jsx(BottomDock, { tab: layoutState.bottomTab, onSelectTab: (tab) => layout.patch({ bottomTab: tab }), onClose: () => layout.patch({ bottomOpen: false }), assets: liveAssets, session: session, api: api, ui: ui, consoleStore: consoleStore, perfHistory: perfHistory, browserView: layoutState.browserView, onSetBrowserView: (view) => layout.patch({ browserView: view }), onPlaceAsset: placeAsset, onImportModels: importModels, importBusy: importBusy }) })] })) : (_jsxs("div", { className: `pointer-events-auto flex h-7 shrink-0 items-center gap-1 border-t ${BORDER} bg-[#0e1014] px-1.5`, children: [[
                                         ["content", "Content Browser"],
                                         ["console", "Console"],
                                         ["profiler", "Profiler"],
                                         ["animation", "Animation"],
                                         ["assistant", "AI Assistant"],
-                                    ].map(([id, label]) => (_jsx("button", { type: "button", onClick: () => openBottomTab(id), className: `rounded-[4px] px-2 py-0.5 text-[10px] text-neutral-500 transition-colors hover:bg-white/[0.05] hover:text-neutral-300 ${FOCUS_RING}`, children: label }, id))), _jsx("span", { className: "ml-auto text-[9px] text-neutral-600", children: "Ctrl+B opens the content browser" })] }))] }), layoutState.rightOpen ? (_jsxs(_Fragment, { children: [_jsx(PanelResizer, { orientation: "vertical", label: "Resize inspector panel", sign: -1, onResize: (delta) => layout.resize("rightWidth", delta) }), _jsx("aside", { className: `pointer-events-auto hidden min-h-0 flex-col overflow-hidden border-l ${BORDER} bg-[#111318] md:flex`, style: { width: layoutState.rightWidth }, "aria-label": "Inspector dock", children: _jsx(InspectorPanel, { session: session, ui: ui, api: api, tab: layoutState.inspectorTab, onSelectTab: (tab) => layout.patch({ inspectorTab: tab }), collapsed: layoutState.collapsed, onToggleSection: (id) => layout.toggleSection(id), onClose: () => layout.patch({ rightOpen: false }) }) })] })) : null] }), _jsx(StatusBar, { api: api, history: perfHistory, objects: sceneStats.objects, foliage: sceneStats.foliage, selectionCount: state.selection.length, autosave: true }), paletteQuery !== null ? (_jsx(CommandPalette, { commands: paletteCommands, initialQuery: paletteQuery, onClose: () => setPaletteQuery(null) })) : null, helpOpen ? (_jsx("div", { className: "pointer-events-auto absolute inset-0 z-[70] flex items-center justify-center bg-black/50 backdrop-blur-[2px]", onClick: () => setHelpOpen(false), children: _jsxs("div", { className: "w-[28rem] max-w-[90vw] rounded-[10px] border border-white/10 bg-[#14171d] p-5 shadow-2xl shadow-black/60", onClick: (event) => event.stopPropagation(), role: "dialog", "aria-label": "Keyboard shortcuts", children: [_jsxs("div", { className: "mb-3 flex items-center", children: [_jsxs("div", { className: "flex items-center gap-2 text-sm font-semibold tracking-wide text-neutral-100", children: [_jsx(Icon, { name: "command", size: 15, className: "text-cyan-300" }), "Keyboard shortcuts"] }), _jsx(IconButton, { icon: "close", label: "Close shortcuts", tone: "ghost", className: "ml-auto", onClick: () => setHelpOpen(false) })] }), _jsx("div", { className: "grid max-h-[60vh] grid-cols-[auto_1fr] items-center gap-x-4 gap-y-1.5 overflow-auto", children: shortcuts.map((entry) => (_jsxs("div", { className: "contents", children: [_jsx("span", { className: "justify-self-start", children: _jsx(Kbd, { children: entry.keys }) }), _jsx("span", { className: "text-neutral-300", children: entry.action })] }, entry.keys))) })] }) })) : null] }));
+                                    ].map(([id, label]) => (_jsx("button", { type: "button", onClick: () => openBottomTab(id), className: `rounded-[4px] px-2 py-0.5 text-[10px] text-neutral-500 transition-colors hover:bg-white/[0.05] hover:text-neutral-300 ${FOCUS_RING}`, children: label }, id))), _jsx("span", { className: "ml-auto text-[9px] text-neutral-600", children: "Ctrl+B opens the content browser" })] }))] }), layoutState.rightOpen ? (_jsxs(_Fragment, { children: [_jsx(PanelResizer, { orientation: "vertical", label: "Resize inspector panel", sign: -1, onResize: (delta) => layout.resize("rightWidth", delta) }), _jsx("aside", { className: `pointer-events-auto hidden min-h-0 flex-col overflow-hidden border-l ${BORDER} bg-[#111318] md:flex`, style: { width: layoutState.rightWidth }, "aria-label": "Inspector dock", children: _jsx(InspectorPanel, { session: session, ui: ui, api: api, assets: liveAssets, tab: layoutState.inspectorTab, onSelectTab: (tab) => layout.patch({ inspectorTab: tab }), collapsed: layoutState.collapsed, onToggleSection: (id) => layout.toggleSection(id), onClose: () => layout.patch({ rightOpen: false }) }) })] })) : null] }), _jsx(StatusBar, { api: api, history: perfHistory, objects: sceneStats.objects, foliage: sceneStats.foliage, selectionCount: state.selection.length, autosave: true }), paletteQuery !== null ? (_jsx(CommandPalette, { commands: paletteCommands, initialQuery: paletteQuery, onClose: () => setPaletteQuery(null) })) : null, helpOpen ? (_jsx("div", { className: "pointer-events-auto absolute inset-0 z-[70] flex items-center justify-center bg-black/50 backdrop-blur-[2px]", onClick: () => setHelpOpen(false), children: _jsxs("div", { className: "w-[28rem] max-w-[90vw] rounded-[10px] border border-white/10 bg-[#14171d] p-5 shadow-2xl shadow-black/60", onClick: (event) => event.stopPropagation(), role: "dialog", "aria-label": "Keyboard shortcuts", children: [_jsxs("div", { className: "mb-3 flex items-center", children: [_jsxs("div", { className: "flex items-center gap-2 text-sm font-semibold tracking-wide text-neutral-100", children: [_jsx(Icon, { name: "command", size: 15, className: "text-cyan-300" }), "Keyboard shortcuts"] }), _jsx(IconButton, { icon: "close", label: "Close shortcuts", tone: "ghost", className: "ml-auto", onClick: () => setHelpOpen(false) })] }), _jsx("div", { className: "grid max-h-[60vh] grid-cols-[auto_1fr] items-center gap-x-4 gap-y-1.5 overflow-auto", children: shortcuts.map((entry) => (_jsxs("div", { className: "contents", children: [_jsx("span", { className: "justify-self-start", children: _jsx(Kbd, { children: entry.keys }) }), _jsx("span", { className: "text-neutral-300", children: entry.action })] }, entry.keys))) })] }) })) : null] }));
 }

package/dist/InspectorPanel.d.ts

@@ -1,4 +1,5 @@
 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 { InspectorTab } from "./shell/layoutStore.js";
@@ -9,12 +10,14 @@ import type { InspectorTab } from "./shell/layoutStore.js";
  * `pathPoint` slice, so UI-only churn never rerenders it on `EditorChrome`'s render tick.
  * @internal — mounted by `EditorChrome` inside the right dock.
  */
-export declare function InspectorPanel({ session, ui, onClose, api, tab, onSelectTab, collapsed, onToggleSection, }: {
+export declare function InspectorPanel({ session, ui, onClose, api, assets, tab, onSelectTab, collapsed, onToggleSection, }: {
     session: EditorSession;
     ui: EditorUiStore;
     onClose?: () => void;
     /** Host API for RPC-backed actions (material assignment, camera). */
     api?: EditorHostApi;
+    /** Live browser asset list, used to resolve a placed marker's rig clips for animation authoring. */
+    assets?: readonly EditorAssetEntry[];
     /** Controlled active tab; omit for local state. */
     tab?: InspectorTab;
     onSelectTab?: (tab: InspectorTab) => void;

package/dist/InspectorPanel.js

@@ -4,10 +4,13 @@ import { editorParentOf, findEditorNote, findEditorPath, isEditorObjectLocked, }
 import { readVegetationSettings, vegetationFootprint } from "@jgengine/core/world/vegetation";
 import { getSceneKind, isSceneKind, parseParams, } from "@jgengine/core/scene/sceneKinds";
 import { getAssetGenerator } from "@jgengine/core/scene/assetGenerator";
+import { markerCatalogId } from "@jgengine/core/world/authoredObjects";
 import { useGameContext } from "@jgengine/react/provider";
 import { canAuthorTrigger, clearMaterialAssignmentPatch, clearTriggerInstallPatch, defaultTriggerInstallPatch, hasAuthoredTrigger, hasMaterialAssignment, } from "./authoredComponentMeta.js";
 import { SchemaInspector } from "./SchemaInspector.js";
 import { TriggerInspector } from "./TriggerInspector.js";
+import { describeClipRoles } from "./AssetBrowser.js";
+import { animationMode, animationMetaPatch, LOCOMOTION_ROLES, ONE_SHOT_EVENTS, readAnimationSetting, setAnimationMode, setLocomotionClip, setLocomotionNumber, setOneShotClip, } from "./modelAnimationAuthoring.js";
 import { listParentCandidates } from "./parentCandidates.js";
 import { TERRAIN_MATERIALS } from "./uiStore.js";
 import { shallowArrayEqual, useStoreSelector } from "./useStoreSelector.js";
@@ -15,6 +18,7 @@ import { INPUT } from "./chromeStyles.js";
 import { NumberField } from "./chromeFields.js";
 import { AxisNumberField, FieldRow, SectionAction } from "./shell/fields.js";
 import { Icon, kindIcon } from "./shell/icons.js";
+import { CoverageSection } from "./shell/scatterCoverage.js";
 import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./shell/theme.js";
 import { CollapsibleSection, EmptyState, IconButton, PanelTabs } from "./shell/ui.js";
 function VegetationFields({ volume, onMeta, }) {
@@ -49,8 +53,11 @@ function KindInspector({ object, meta, onMeta }) {
     const definition = getSceneKind(object.kind);
     if (definition === undefined)
         return null;
-    const note = definition.note?.(object, parseParams(definition.schema, object.meta));
-    return (_jsx(SchemaInspector, { schema: definition.schema, label: definition.label, meta: meta, onMeta: onMeta, ...(definition.accent === undefined ? {} : { accent: definition.accent }), ...(note === undefined ? {} : { note }) }));
+    const params = parseParams(definition.schema, object.meta);
+    const note = definition.note?.(object, params);
+    const coverage = definition.coverage;
+    const accent = definition.accent ?? "#34d399";
+    return (_jsxs("div", { className: "space-y-2", children: [coverage !== undefined ? (_jsx(CoverageSection, { schema: definition.schema, coverage: coverage, object: object, params: params, accent: accent, onMeta: onMeta, ...(note === undefined ? {} : { note }) })) : null, _jsx(SchemaInspector, { schema: definition.schema, label: definition.label, meta: meta, onMeta: onMeta, ...(definition.accent === undefined ? {} : { accent: definition.accent }), ...(coverage === undefined && note !== undefined ? { note } : {}), ...(coverage === undefined ? {} : { hideKeys: [coverage.densityKey] }) })] }));
 }
 /** Auto-generated inspector for a placed generator asset's params (building/bookcase/…). */
 function GeneratorInspector({ meta, onMeta }) {
@@ -107,6 +114,26 @@ function ComponentAddBar({ target, meta, onMeta, api, selectionIds, }) {
                                     event.currentTarget.value = "";
                                 }, children: [_jsx("option", { value: "", children: "+ Material\u2026" }), TERRAIN_MATERIALS.map((material) => (_jsx("option", { value: material.id, children: material.label }, material.id)))] })] })) : null] })] }));
 }
+/** A labeled clip dropdown (never free-text) for a role/event; "— none —" clears the binding. */
+function ClipSelectRow({ label, clips, value, onChange, }) {
+    return (_jsx(FieldRow, { label: label, children: _jsxs("select", { className: `h-6.5 w-full min-w-0 px-1.5 ${INPUT_CLS}`, value: value ?? "", "aria-label": `${label} clip`, onChange: (event) => onChange(event.target.value === "" ? null : event.target.value), children: [_jsx("option", { value: "", children: "\u2014 none \u2014" }), clips.map((clip) => (_jsx("option", { value: clip, children: clip }, clip)))] }) }));
+}
+const ANIMATION_MODE_HINT = {
+    default: "Inherits the catalog default: a rigged asset auto-animates from its clip roles.",
+    auto: "Forces derivation of idle/walk/run + hit/death/attack from this rig's clip names.",
+    none: "Renders the bind pose — no clip playback.",
+    custom: "Author explicit role→clip bindings below; unset roles fall back to the rig's defaults.",
+};
+/**
+ * Inspector section authoring a placement's `ModelConfig.animation` for a rigged catalog asset.
+ * Persists to `marker.meta.animation` through the passed `onChange` (an undoable `setMarker` dispatch).
+ * All clip picks are dropdowns over the asset's real clip list — never free-text.
+ */
+function ModelAnimationSection({ clips, setting, onChange, }) {
+    const mode = animationMode(setting);
+    const config = mode === "custom" && typeof setting === "object" ? setting : null;
+    return (_jsxs("div", { className: "space-y-2.5", children: [_jsxs("div", { className: "text-[10px] text-neutral-500", children: [clips.length, " clips \u00B7 ", describeClipRoles(clips)] }), _jsx(FieldRow, { label: "Mode", children: _jsxs("select", { className: `h-6.5 w-full min-w-0 px-1.5 ${INPUT_CLS}`, value: mode, "aria-label": "Animation mode", onChange: (event) => onChange(setAnimationMode(setting, event.target.value, clips)), children: [_jsx("option", { value: "default", children: "Default (catalog)" }), _jsx("option", { value: "auto", children: "Auto (derive)" }), _jsx("option", { value: "none", children: "None (bind pose)" }), _jsx("option", { value: "custom", children: "Custom" })] }) }), config === null ? (_jsx("div", { className: "text-[10px] leading-relaxed text-neutral-600", children: ANIMATION_MODE_HINT[mode] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "space-y-1.5 rounded-[6px] border border-white/[0.06] bg-white/[0.02] p-2", children: [_jsx("div", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "Locomotion states" }), LOCOMOTION_ROLES.map((role) => (_jsx(ClipSelectRow, { label: role, clips: clips, value: config.states?.[role] ?? null, onChange: (clip) => onChange(setLocomotionClip(setting, role, clip)) }, role))), _jsx(FieldRow, { label: "walkSpeed", title: "Speed (u/s) above which the entity counts as moving (walk).", children: _jsx(AxisNumberField, { label: "u/s", step: 0.1, value: config.states?.walkSpeed ?? 0.5, onCommit: (value) => onChange(setLocomotionNumber(setting, "walkSpeed", Math.max(0, value))) }) }), _jsx(FieldRow, { label: "runSpeed", title: "Speed above which the run clip plays (when a run clip is set).", children: _jsx(AxisNumberField, { label: "u/s", step: 0.5, value: config.states?.runSpeed ?? 6, onCommit: (value) => onChange(setLocomotionNumber(setting, "runSpeed", Math.max(0, value))) }) }), _jsx(FieldRow, { label: "fadeSec", title: "Crossfade duration (s) when the locomotion state changes.", children: _jsx(AxisNumberField, { label: "s", step: 0.05, value: config.states?.fadeSec ?? 0.2, onCommit: (value) => onChange(setLocomotionNumber(setting, "fadeSec", Math.max(0, value))) }) })] }), _jsxs("div", { className: "space-y-1.5 rounded-[6px] border border-white/[0.06] bg-white/[0.02] p-2", children: [_jsx("div", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "One-shot events" }), _jsx("div", { className: "text-[10px] text-neutral-600", children: "hit / death auto-fire on damage/death; others via playEntityAnimation." }), ONE_SHOT_EVENTS.map((event) => (_jsx(ClipSelectRow, { label: event, clips: clips, value: config.oneShots?.[event] ?? null, onChange: (clip) => onChange(setOneShotClip(setting, event, clip)) }, event)))] })] }))] }));
+}
 function Section({ id, title, icon, sections, children, trailing, }) {
     return (_jsx(CollapsibleSection, { title: title, ...(icon === undefined ? {} : { icon }), open: sections.collapsed[id] !== true, onToggle: () => sections.toggle(id), ...(trailing === undefined ? {} : { trailing }), children: children }));
 }
@@ -127,7 +154,7 @@ function MaterialsTab({ api, selection, meta, }) {
  * `pathPoint` slice, so UI-only churn never rerenders it on `EditorChrome`'s render tick.
  * @internal — mounted by `EditorChrome` inside the right dock.
  */
-export function InspectorPanel({ session, ui, onClose, api, tab, onSelectTab, collapsed, onToggleSection, }) {
+export function InspectorPanel({ session, ui, onClose, api, assets, tab, onSelectTab, collapsed, onToggleSection, }) {
     const document = useStoreSelector(session, (state) => state.document);
     const selection = useStoreSelector(session, (state) => state.selection, shallowArrayEqual);
     const pathPoint = useStoreSelector(ui, (state) => state.pathPoint);
@@ -198,12 +225,16 @@ export function InspectorPanel({ session, ui, onClose, api, tab, onSelectTab, co
     else if (selectedMarker !== undefined) {
         const marker = selectedMarker;
         const onMeta = (patch, coalesce) => session.dispatch({ type: "setMarker", id: marker.id, patch: { meta: { ...marker.meta, ...patch } } }, { coalesce: `${coalesce}:${marker.id}` });
+        // Rig clips for animation authoring: this placement's catalog asset must carry animation clips.
+        const markerCatalog = markerCatalogId(marker);
+        const markerRigAsset = markerCatalog === null ? undefined : assets?.find((entry) => entry.id === markerCatalog);
+        const markerRigClips = markerRigAsset?.clips !== undefined && markerRigAsset.clips.length > 0 ? markerRigAsset.clips : null;
         const hasTrigger = hasAuthoredTrigger(marker.meta);
         const hasMaterial = hasMaterialAssignment(marker.meta);
         const hasGenerator = typeof marker.meta?.["assetId"] === "string" && getAssetGenerator(marker.meta["assetId"]) !== undefined;
         const hasKindParams = isSceneKind(marker.kind);
         const componentCards = (_jsxs(_Fragment, { children: [_jsx(ComponentAddBar, { target: "marker", meta: marker.meta, onMeta: onMeta, api: api, selectionIds: [marker.id] }), hasKindParams ? (_jsx(Section, { id: "kindParams", title: "Kind parameters", icon: "settings", sections: sections, children: _jsx(KindInspector, { object: markerObject(marker), meta: marker.meta, onMeta: onMeta }) })) : null, hasTrigger ? (_jsx(Section, { id: "trigger", title: "Trigger", icon: "target", sections: sections, trailing: _jsx(SectionAction, { label: "Remove trigger component", onClick: () => onMeta(clearTriggerInstallPatch(), "component:remove-trigger"), children: "remove" }), children: _jsx(TriggerInspector, { target: "marker", meta: marker.meta, onMeta: onMeta }) })) : null, hasMaterial ? (_jsx(Section, { id: "material", title: "Material", icon: "sphere", sections: sections, trailing: _jsx(SectionAction, { label: "Remove material assignment", onClick: () => onMeta(clearMaterialAssignmentPatch(), "component:remove-material"), children: "remove" }), children: _jsxs("div", { className: "text-[11px] text-neutral-300", children: ["materialId: ", _jsx("span", { className: NUMERIC, children: String(marker.meta?.["materialId"]) })] }) })) : null, hasGenerator ? (_jsx(Section, { id: "generator", title: "Generator", icon: "cube", sections: sections, children: _jsx(GeneratorInspector, { meta: marker.meta, onMeta: onMeta }) })) : null, !hasKindParams && !hasTrigger && !hasMaterial && !hasGenerator && !canAuthorTrigger("marker") ? (_jsx(EmptyState, { icon: "settings", title: "No components", description: "This marker has no optional components. Games that register trigger actions enable Add trigger here." })) : null] }));
-        body = (_jsxs("div", { className: "space-y-2 p-2.5", children: [_jsx(ObjectHeader, { kind: marker.kind, id: marker.id, label: marker.label ?? "", placeholder: marker.id, locked: isEditorObjectLocked(document, marker.id), onLabel: (value) => session.dispatch({ type: "setMarker", id: marker.id, patch: { label: value } }, { coalesce: `label:${marker.id}` }) }), activeTab === "inspector" ? (_jsxs(_Fragment, { children: [_jsx(Section, { id: "transform", title: "Transform", icon: "move", sections: sections, trailing: _jsx(SectionAction, { label: "Reset position to origin", onClick: () => session.dispatch({ type: "setTransform", id: marker.id, position: { x: 0, y: 0, z: 0 } }), children: "reset" }), children: _jsxs("div", { className: "space-y-1.5", children: [_jsx(FieldRow, { label: "Position", children: ["x", "y", "z"].map((axis) => (_jsx(AxisNumberField, { axis: axis, label: axis, step: 0.5, value: marker.position[axis], onCommit: (value) => session.dispatch({ type: "setTransform", id: marker.id, position: { ...marker.position, [axis]: value } }, { coalesce: `pos:${axis}:${marker.id}` }) }, axis))) }), _jsx(FieldRow, { label: "Rotation", children: _jsx(AxisNumberField, { axis: "y", label: "y\u00B0", step: 5, precision: 1, value: Math.round((((marker.rotationY ?? 0) * 180) / Math.PI) * 10) / 10, onCommit: (value) => session.dispatch({ type: "setTransform", id: marker.id, rotationY: (value * Math.PI) / 180 }, { coalesce: `rot:${marker.id}` }) }) })] }) }), _jsx(Section, { id: "appearance", title: "Appearance", icon: "sphere", sections: sections, children: _jsx(KindColorFields, { kind: marker.kind, color: marker.color, onKind: (kind) => session.dispatch({ type: "setMarker", id: marker.id, patch: { kind } }, { coalesce: `kind:${marker.id}` }), onColor: (color) => session.dispatch({ type: "setMarker", id: marker.id, patch: { color } }, { coalesce: `color:${marker.id}` }) }) }), _jsx(Section, { id: "placement", title: "Placement", icon: "pin", sections: sections, children: _jsxs("div", { className: "space-y-2", children: [_jsx(ClearanceField, { meta: marker.meta, onMeta: onMeta }), _jsx(ParentField, { session: session, id: marker.id })] }) }), marker.meta !== undefined ? (_jsx(Section, { id: "meta", title: "Raw metadata", icon: "script", sections: sections, children: _jsx("pre", { className: "max-h-48 overflow-auto rounded-[5px] border border-white/[0.06] bg-black/40 p-2 text-[10px] text-neutral-400", children: JSON.stringify(marker.meta, null, 2) }) })) : null] })) : (componentCards)] }));
+        body = (_jsxs("div", { className: "space-y-2 p-2.5", children: [_jsx(ObjectHeader, { kind: marker.kind, id: marker.id, label: marker.label ?? "", placeholder: marker.id, locked: isEditorObjectLocked(document, marker.id), onLabel: (value) => session.dispatch({ type: "setMarker", id: marker.id, patch: { label: value } }, { coalesce: `label:${marker.id}` }) }), activeTab === "inspector" ? (_jsxs(_Fragment, { children: [_jsx(Section, { id: "transform", title: "Transform", icon: "move", sections: sections, trailing: _jsx(SectionAction, { label: "Reset position to origin", onClick: () => session.dispatch({ type: "setTransform", id: marker.id, position: { x: 0, y: 0, z: 0 } }), children: "reset" }), children: _jsxs("div", { className: "space-y-1.5", children: [_jsx(FieldRow, { label: "Position", children: ["x", "y", "z"].map((axis) => (_jsx(AxisNumberField, { axis: axis, label: axis, step: 0.5, value: marker.position[axis], onCommit: (value) => session.dispatch({ type: "setTransform", id: marker.id, position: { ...marker.position, [axis]: value } }, { coalesce: `pos:${axis}:${marker.id}` }) }, axis))) }), _jsx(FieldRow, { label: "Rotation", children: _jsx(AxisNumberField, { axis: "y", label: "y\u00B0", step: 5, precision: 1, value: Math.round((((marker.rotationY ?? 0) * 180) / Math.PI) * 10) / 10, onCommit: (value) => session.dispatch({ type: "setTransform", id: marker.id, rotationY: (value * Math.PI) / 180 }, { coalesce: `rot:${marker.id}` }) }) })] }) }), _jsx(Section, { id: "appearance", title: "Appearance", icon: "sphere", sections: sections, children: _jsx(KindColorFields, { kind: marker.kind, color: marker.color, onKind: (kind) => session.dispatch({ type: "setMarker", id: marker.id, patch: { kind } }, { coalesce: `kind:${marker.id}` }), onColor: (color) => session.dispatch({ type: "setMarker", id: marker.id, patch: { color } }, { coalesce: `color:${marker.id}` }) }) }), _jsx(Section, { id: "placement", title: "Placement", icon: "pin", sections: sections, children: _jsxs("div", { className: "space-y-2", children: [_jsx(ClearanceField, { meta: marker.meta, onMeta: onMeta }), _jsx(ParentField, { session: session, id: marker.id })] }) }), markerRigClips !== null ? (_jsx(Section, { id: "modelAnimation", title: "Animation", icon: "film", sections: sections, children: _jsx(ModelAnimationSection, { clips: markerRigClips, setting: readAnimationSetting(marker.meta), onChange: (next) => onMeta(animationMetaPatch(next), "animation") }) })) : null, marker.meta !== undefined ? (_jsx(Section, { id: "meta", title: "Raw metadata", icon: "script", sections: sections, children: _jsx("pre", { className: "max-h-48 overflow-auto rounded-[5px] border border-white/[0.06] bg-black/40 p-2 text-[10px] text-neutral-400", children: JSON.stringify(marker.meta, null, 2) }) })) : null] })) : (componentCards)] }));
     }
     else if (selectedVolume !== undefined) {
         const volume = selectedVolume;

package/dist/SchemaInspector.d.ts

@@ -9,11 +9,13 @@ export type MetaPatch = (patch: Record<string, unknown>, coalesce: string) => vo
  * seam owns the inspector. Replaces the hand-written per-kind field blocks (`ScatterFields`).
  * @internal — mounted by `EditorChrome`'s inspector; not a game-author entry point.
  */
-export declare function SchemaInspector({ schema, label, accent, note, meta, onMeta, }: {
+export declare function SchemaInspector({ schema, label, accent, note, meta, onMeta, hideKeys, }: {
     schema: ParamSchema;
     label: string;
     accent?: string;
     note?: string;
     meta: Record<string, unknown> | undefined;
     onMeta: MetaPatch;
+    /** Field keys to omit from this body — hoisted elsewhere (e.g. the density slider in `CoverageSection`). */
+    hideKeys?: readonly string[];
 }): import("react").JSX.Element;

package/dist/SchemaInspector.js

@@ -82,10 +82,15 @@ function GroupSection({ title, accent, fields, schema, meta, onMeta, defaultColl
  * seam owns the inspector. Replaces the hand-written per-kind field blocks (`ScatterFields`).
  * @internal — mounted by `EditorChrome`'s inspector; not a game-author entry point.
  */
-export function SchemaInspector({ schema, label, accent = "#34d399", note, meta, onMeta, }) {
+export function SchemaInspector({ schema, label, accent = "#34d399", note, meta, onMeta, hideKeys, }) {
     const groups = schema.groups ?? [];
     const grouped = new Set(groups.map((group) => group.id));
+    const hidden = hideKeys === undefined || hideKeys.length === 0 ? null : new Set(hideKeys);
+    const visible = hidden === null ? schema.fields : schema.fields.filter((field) => !hidden.has(field.key));
     // Fields with no group (or a group not declared in schema.groups) render first, headerless.
-    const ungrouped = schema.fields.filter((field) => field.group === undefined || !grouped.has(field.group));
-    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: label }), _jsx(PresetRow, { schema: schema, onMeta: onMeta }), ungrouped.map((field) => field.type === "action" ? (_jsx(ActionButton, { field: field, schema: schema, onMeta: onMeta }, field.key)) : (_jsx(FieldRow, { field: field, meta: meta, onMeta: onMeta }, field.key))), groups.map((group) => (_jsx(GroupSection, { title: group.label, accent: accent, fields: schema.fields.filter((field) => field.group === group.id), schema: schema, meta: meta, onMeta: onMeta, defaultCollapsed: group.collapsed ?? false }, group.id))), note !== undefined && note.length > 0 ? _jsx("div", { className: "text-[10px] text-neutral-500", children: note }) : null] }));
+    const ungrouped = visible.filter((field) => field.group === undefined || !grouped.has(field.group));
+    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: label }), _jsx(PresetRow, { schema: schema, onMeta: onMeta }), ungrouped.map((field) => field.type === "action" ? (_jsx(ActionButton, { field: field, schema: schema, onMeta: onMeta }, field.key)) : (_jsx(FieldRow, { field: field, meta: meta, onMeta: onMeta }, field.key))), groups
+                .map((group) => ({ group, fields: visible.filter((field) => field.group === group.id) }))
+                .filter((entry) => entry.fields.length > 0)
+                .map(({ group, fields }) => (_jsx(GroupSection, { title: group.label, accent: accent, fields: fields, schema: schema, meta: meta, onMeta: onMeta, defaultCollapsed: group.collapsed ?? false }, group.id))), note !== undefined && note.length > 0 ? _jsx("div", { className: "text-[10px] text-neutral-500", children: note }) : null] }));
 }

package/dist/modelAnimationAuthoring.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Authoring model for a placement's `ModelConfig.animation`, persisted on a marker's `meta.animation`
+ * and consumed by the shell exactly like a game-authored config. Pure data + reducers, no JSX — the
+ * inspector section wires these to `session.dispatch({ type: "setMarker", ... })` so every edit is
+ * undoable like any other inspector change. Splitting this out mirrors how `pathFlythrough.ts` /
+ * `renameObject.ts` keep inspector logic testable apart from the panel.
+ *
+ * The stored value is either the string modes `"auto"` / `"none"` (see `resolveAnimationConfig`) or a
+ * concrete config object. `undefined` means "no override" — a catalog-resolved rigged asset still
+ * auto-animates from its clip roles. Authored types here are permissive supersets of core's
+ * `ModelAnimationConfig` so an in-progress edit (idle picked, walk not yet) is still storable.
+ *
+ * @internal
+ */
+/** Locomotion state roles the speed-driven idle/walk/run crossfade reads. */
+export declare const LOCOMOTION_ROLES: readonly ["idle", "walk", "run"];
+/** Locomotion clip role a placement can override (idle/walk/run). */
+export type LocomotionRole = (typeof LOCOMOTION_ROLES)[number];
+/** Numeric locomotion tunings (`ModelAnimationStates`). */
+export declare const LOCOMOTION_NUMBERS: readonly ["walkSpeed", "runSpeed", "fadeSec"];
+/** Numeric locomotion tuning field on an authored animation config (walkSpeed/runSpeed/fadeSec). */
+export type LocomotionNumber = (typeof LOCOMOTION_NUMBERS)[number];
+/**
+ * One-shot event slots offered in the inspector. `hit` / `death` auto-fire on this entity's
+ * `combat.hitReaction` / `entity.died`; the rest fire when the game calls `playEntityAnimation`.
+ */
+export declare const ONE_SHOT_EVENTS: readonly ["attack", "hit", "death", "jump", "interact", "cheer"];
+/** One-shot animation event a placement can bind a clip to (attack/hit/death/...). */
+export type OneShotEvent = (typeof ONE_SHOT_EVENTS)[number];
+/** Role->clip override map persisted inside an authored animation config. */
+export interface AuthoredAnimationStates {
+    idle?: string;
+    walk?: string;
+    run?: string;
+    walkSpeed?: number;
+    runSpeed?: number;
+    fadeSec?: number;
+}
+/** Structurally compatible with `ModelAnimationConfig`, but every field optional for authoring. */
+export interface AuthoredAnimationConfig {
+    clip?: string;
+    loop?: boolean;
+    timeScale?: number;
+    states?: AuthoredAnimationStates;
+    oneShots?: Record<string, string>;
+}
+/** The value stored at `meta.animation`. */
+export type AnimationSetting = AuthoredAnimationConfig | "auto" | "none";
+/** Which authoring mode a stored setting represents. `default` = no override key. */
+export type AnimationMode = "default" | "auto" | "none" | "custom";
+/** Reads and shape-validates the animation override from a marker's meta; undefined when absent/invalid. */
+export declare function readAnimationSetting(meta: Record<string, unknown> | undefined): AnimationSetting | undefined;
+/** The authoring mode a stored setting maps to. */
+export declare function animationMode(setting: AnimationSetting | undefined): AnimationMode;
+/**
+ * Switches authoring mode. `custom` seeds from the asset's clip-role defaults (so the user starts from
+ * a working config, then overrides) when there is no existing object config; the other modes are the
+ * bare string/undefined values.
+ */
+export declare function setAnimationMode(setting: AnimationSetting | undefined, mode: AnimationMode, clips?: readonly string[]): AnimationSetting | undefined;
+/** A concrete custom config derived from a rigged asset's clip roles — the `custom` mode seed. */
+export declare function defaultCustomConfig(clips: readonly string[]): AuthoredAnimationConfig;
+/** Sets or clears (null) a locomotion state clip; forces the setting into `custom`. */
+export declare function setLocomotionClip(setting: AnimationSetting | undefined, role: LocomotionRole, clipName: string | null): AuthoredAnimationConfig;
+/** Sets or clears (null) a numeric locomotion tuning. */
+export declare function setLocomotionNumber(setting: AnimationSetting | undefined, key: LocomotionNumber, value: number | null): AuthoredAnimationConfig;
+/** Binds or clears (null) a one-shot event to a clip. */
+export declare function setOneShotClip(setting: AnimationSetting | undefined, event: string, clipName: string | null): AuthoredAnimationConfig;
+/**
+ * The meta patch that persists a setting (or clears the override when undefined). Shallow-merges onto
+ * `marker.meta` via `setMarker`; an undefined value drops out of the saved JSON document.
+ */
+export declare function animationMetaPatch(setting: AnimationSetting | undefined): {
+    animation: AnimationSetting | undefined;
+};

package/dist/modelAnimationAuthoring.js

@@ -0,0 +1,164 @@
+import { rolesFromClips } from "@jgengine/core/game/clipRoles";
+/**
+ * Authoring model for a placement's `ModelConfig.animation`, persisted on a marker's `meta.animation`
+ * and consumed by the shell exactly like a game-authored config. Pure data + reducers, no JSX — the
+ * inspector section wires these to `session.dispatch({ type: "setMarker", ... })` so every edit is
+ * undoable like any other inspector change. Splitting this out mirrors how `pathFlythrough.ts` /
+ * `renameObject.ts` keep inspector logic testable apart from the panel.
+ *
+ * The stored value is either the string modes `"auto"` / `"none"` (see `resolveAnimationConfig`) or a
+ * concrete config object. `undefined` means "no override" — a catalog-resolved rigged asset still
+ * auto-animates from its clip roles. Authored types here are permissive supersets of core's
+ * `ModelAnimationConfig` so an in-progress edit (idle picked, walk not yet) is still storable.
+ *
+ * @internal
+ */
+/** Locomotion state roles the speed-driven idle/walk/run crossfade reads. */
+export const LOCOMOTION_ROLES = ["idle", "walk", "run"];
+/** Numeric locomotion tunings (`ModelAnimationStates`). */
+export const LOCOMOTION_NUMBERS = ["walkSpeed", "runSpeed", "fadeSec"];
+/**
+ * One-shot event slots offered in the inspector. `hit` / `death` auto-fire on this entity's
+ * `combat.hitReaction` / `entity.died`; the rest fire when the game calls `playEntityAnimation`.
+ */
+export const ONE_SHOT_EVENTS = ["attack", "hit", "death", "jump", "interact", "cheer"];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Reads and shape-validates the animation override from a marker's meta; undefined when absent/invalid. */
+export function readAnimationSetting(meta) {
+    const value = meta?.["animation"];
+    if (value === "auto" || value === "none")
+        return value;
+    if (!isRecord(value))
+        return undefined;
+    const config = {};
+    if (typeof value["clip"] === "string")
+        config.clip = value["clip"];
+    if (typeof value["loop"] === "boolean")
+        config.loop = value["loop"];
+    if (typeof value["timeScale"] === "number")
+        config.timeScale = value["timeScale"];
+    if (isRecord(value["states"])) {
+        const raw = value["states"];
+        const states = {};
+        for (const role of LOCOMOTION_ROLES)
+            if (typeof raw[role] === "string")
+                states[role] = raw[role];
+        for (const key of LOCOMOTION_NUMBERS)
+            if (typeof raw[key] === "number")
+                states[key] = raw[key];
+        if (Object.keys(states).length > 0)
+            config.states = states;
+    }
+    if (isRecord(value["oneShots"])) {
+        const raw = value["oneShots"];
+        const oneShots = {};
+        for (const [event, clip] of Object.entries(raw)) {
+            if (typeof clip === "string")
+                oneShots[event] = clip;
+            else if (Array.isArray(clip) && typeof clip[0] === "string")
+                oneShots[event] = clip[0];
+        }
+        if (Object.keys(oneShots).length > 0)
+            config.oneShots = oneShots;
+    }
+    return config;
+}
+/** The authoring mode a stored setting maps to. */
+export function animationMode(setting) {
+    if (setting === undefined)
+        return "default";
+    if (setting === "auto")
+        return "auto";
+    if (setting === "none")
+        return "none";
+    return "custom";
+}
+function asConfig(setting) {
+    return setting !== undefined && setting !== "auto" && setting !== "none" ? setting : {};
+}
+function normalizeConfig(config) {
+    const next = { ...config };
+    if (next.states !== undefined && Object.keys(next.states).length === 0)
+        delete next.states;
+    if (next.oneShots !== undefined && Object.keys(next.oneShots).length === 0)
+        delete next.oneShots;
+    return next;
+}
+/**
+ * Switches authoring mode. `custom` seeds from the asset's clip-role defaults (so the user starts from
+ * a working config, then overrides) when there is no existing object config; the other modes are the
+ * bare string/undefined values.
+ */
+export function setAnimationMode(setting, mode, clips = []) {
+    if (mode === "default")
+        return undefined;
+    if (mode === "auto")
+        return "auto";
+    if (mode === "none")
+        return "none";
+    if (setting !== undefined && setting !== "auto" && setting !== "none")
+        return setting;
+    return normalizeConfig(defaultCustomConfig(clips));
+}
+/** A concrete custom config derived from a rigged asset's clip roles — the `custom` mode seed. */
+export function defaultCustomConfig(clips) {
+    const roles = rolesFromClips(clips);
+    const states = {};
+    if (roles.idle?.[0] !== undefined)
+        states.idle = roles.idle[0];
+    if (roles.walk?.[0] !== undefined)
+        states.walk = roles.walk[0];
+    if (roles.run?.[0] !== undefined)
+        states.run = roles.run[0];
+    const oneShots = {};
+    for (const event of ONE_SHOT_EVENTS) {
+        const variant = roles[event]?.[0];
+        if (variant !== undefined)
+            oneShots[event] = variant;
+    }
+    const config = {};
+    if (Object.keys(states).length > 0)
+        config.states = states;
+    if (Object.keys(oneShots).length > 0)
+        config.oneShots = oneShots;
+    return config;
+}
+/** Sets or clears (null) a locomotion state clip; forces the setting into `custom`. */
+export function setLocomotionClip(setting, role, clipName) {
+    const config = asConfig(setting);
+    const states = { ...config.states };
+    if (clipName === null)
+        delete states[role];
+    else
+        states[role] = clipName;
+    return normalizeConfig({ ...config, states });
+}
+/** Sets or clears (null) a numeric locomotion tuning. */
+export function setLocomotionNumber(setting, key, value) {
+    const config = asConfig(setting);
+    const states = { ...config.states };
+    if (value === null || !Number.isFinite(value))
+        delete states[key];
+    else
+        states[key] = value;
+    return normalizeConfig({ ...config, states });
+}
+/** Binds or clears (null) a one-shot event to a clip. */
+export function setOneShotClip(setting, event, clipName) {
+    const config = asConfig(setting);
+    const oneShots = { ...config.oneShots };
+    if (clipName === null)
+        delete oneShots[event];
+    else
+        oneShots[event] = clipName;
+    return normalizeConfig({ ...config, oneShots });
+}
+/**
+ * The meta patch that persists a setting (or clears the override when undefined). Shallow-merges onto
+ * `marker.meta` via `setMarker`; an undefined value drops out of the saved JSON document.
+ */
+export function animationMetaPatch(setting) {
+    return { animation: setting };
+}