@jgengine/editor 0.12.0 → 0.14.0

package/dist/handlers/streets.js

@@ -0,0 +1,159 @@
+import { generateStreets } from "@jgengine/core/world/streetGenerator";
+/** Fully-defaulted slider preset for an open street net (resolves to `net` in `streetNetworkMode`). */
+const NET_DEFAULTS = {
+    gridness: 0.9,
+    loopiness: 0.2,
+    connectivity: 0.35,
+    branching: 0.3,
+    deadEnds: 0.5,
+    segmentLength: 48,
+    aspect: 1,
+    winding: 0.2,
+    minCurveRadius: 30,
+    minTurnAngle: 0,
+    maxTurnAngle: 120,
+    width: 7,
+    boulevards: 0.3,
+};
+/** Fully-defaulted slider preset for a closed race circuit (resolves to `circuit` in `streetNetworkMode`). */
+const CIRCUIT_DEFAULTS = {
+    gridness: 0.1,
+    loopiness: 1,
+    connectivity: 0,
+    branching: 0,
+    deadEnds: 0,
+    segmentLength: 60,
+    aspect: 1,
+    winding: 0.5,
+    minCurveRadius: 24,
+    minTurnAngle: 0,
+    maxTurnAngle: 70,
+    width: 12,
+    boulevards: 0,
+};
+/** The numeric slider keys a caller may overlay onto the mode preset via `params`. */
+const RULE_KEYS = [
+    "gridness",
+    "loopiness",
+    "connectivity",
+    "branching",
+    "deadEnds",
+    "segmentLength",
+    "aspect",
+    "winding",
+    "minCurveRadius",
+    "minTurnAngle",
+    "maxTurnAngle",
+    "width",
+    "boulevards",
+];
+/** The tag every baked path carries in `meta.generator`, so a re-run can find and replace its own output. */
+const GENERATOR_TAG = "streetGenerator";
+/** Stable id prefix for a seed's baked paths — the idempotency key for replace-on-re-run. */
+function genPrefix(seed) {
+    return `gen-${seed}-`;
+}
+/** True when a path was baked by this generator for `seed` (matches id prefix OR the meta tag). */
+function isGeneratedForSeed(path, seed) {
+    if (path.id.startsWith(genPrefix(seed)))
+        return true;
+    const meta = path.meta;
+    return meta !== undefined && meta.generator === GENERATOR_TAG && meta.seed === seed;
+}
+/** Half-extents (hx, hz) and world origin a volume fills, so the generator grows inside its footprint. */
+function volumeFootprint(volume) {
+    if (volume.shape === "box" && volume.halfExtents !== undefined) {
+        return { hx: Math.max(1, volume.halfExtents.x), hz: Math.max(1, volume.halfExtents.z), origin: volume.center };
+    }
+    // sphere / cylinder (or a box missing halfExtents): a radius is symmetric in x/z.
+    const r = Math.max(1, volume.radius ?? 0);
+    return { hx: r, hz: r, origin: volume.center };
+}
+/** Document, selection, camera, mode, asset placement, and status verbs. */
+export const streetsHandlers = {
+    generate_streets: (ctx, request) => {
+        const doc = ctx.session.getState().document;
+        const seed = request.seed ?? "path";
+        const requestedMode = request.mode === "circuit" ? "circuit" : "net";
+        // Resolve the footprint + world origin from a named volume or from explicit bounds.
+        let hx;
+        let hz;
+        let origin;
+        if (request.volumeId !== undefined) {
+            const volume = doc.volumes.find((v) => v.id === request.volumeId);
+            if (volume === undefined)
+                return { ok: false, error: `volume not found: ${request.volumeId}` };
+            ({ hx, hz, origin } = volumeFootprint(volume));
+        }
+        else {
+            const center = request.center ?? { x: 0, y: 0, z: 0 };
+            if (request.halfX === undefined || request.halfZ === undefined) {
+                return { ok: false, error: "generate_streets requires volumeId, or center + halfX + halfZ" };
+            }
+            hx = Math.max(1, request.halfX);
+            hz = Math.max(1, request.halfZ);
+            origin = center;
+        }
+        // Build rules: mode preset, overlaid with any numeric slider overrides from `params`.
+        const preset = requestedMode === "circuit" ? CIRCUIT_DEFAULTS : NET_DEFAULTS;
+        const rules = { seed, ...preset };
+        const params = request.params;
+        if (params !== undefined) {
+            for (const key of RULE_KEYS) {
+                const value = params[key];
+                if (typeof value === "number" && Number.isFinite(value)) {
+                    rules[key] = value;
+                }
+            }
+        }
+        const network = generateStreets(rules, hx, hz);
+        // The generator resolves the ACTUAL topology from the rules; use it for the default path kind so a
+        // circuit bakes `route`s and a net bakes `road`s even when the caller's sliders cross the boundary.
+        const kind = request.kind ?? (network.mode === "circuit" ? "route" : "road");
+        const baseY = origin.y;
+        const toWorld = (street) => street.points.map(([lx, lz]) => ({ x: origin.x + lx, y: baseY, z: origin.z + lz }));
+        // Through-streets → one path each (a circuit's ring is a single closed loop street: first ≈ last).
+        const newPaths = [];
+        network.streets.forEach((street, index) => {
+            const points = toWorld(street);
+            if (points.length < 2)
+                return;
+            newPaths.push({
+                id: `${genPrefix(seed)}${index}`,
+                kind,
+                points,
+                width: street.width,
+                label: `${kind} ${index}`,
+                meta: {
+                    generator: GENERATOR_TAG,
+                    seed,
+                    mode: network.mode,
+                    level: street.level,
+                    loop: street.loop,
+                },
+            });
+        });
+        // Idempotent replace: drop this seed's prior baked paths, keep everything else, append the fresh set —
+        // all as ONE undoable structural edit via replaceDocument.
+        const kept = doc.paths.filter((p) => !isGeneratedForSeed(p, seed));
+        const nextDoc = { ...doc, paths: [...kept, ...newPaths] };
+        const { applied } = ctx.dispatchGuarded({ type: "replaceDocument", document: nextDoc });
+        if (!applied)
+            return { ok: false, error: "generate_streets: document replace had no effect" };
+        // replaceDocument clears selection; re-select the freshly baked paths for the caller.
+        ctx.session.dispatch({ type: "select", ids: newPaths.map((p) => p.id) });
+        return {
+            ok: true,
+            result: {
+                seed,
+                requestedMode,
+                mode: network.mode,
+                kind,
+                pathCount: newPaths.length,
+                removed: doc.paths.length - kept.length,
+                ids: newPaths.map((p) => p.id),
+                footprint: { hx, hz, origin },
+            },
+        };
+    },
+};

package/dist/mcp/fieldSpec.js

@@ -71,6 +71,7 @@ export const RPC_FIELD_SCHEMAS = {
     set_terrain_layers: [req(oa("layers", [req(s("id")), req(s("surface")), n("roughness"), n("tiling"), b("triplanar"), s("tint"), n("opacity")]))],
     blend_terrain: [req(s("surface")), req(n("x")), req(n("z")), n("radius"), n("strength"), s("shape", SHAPE)],
     convert_scatter: [req(s("pathId"))],
+    generate_streets: [s("volumeId"), v3("center"), n("halfX"), n("halfZ"), s("seed"), s("mode", ["net", "circuit"]), s("kind"), o("params")],
     bake_minimap: [n("padding"), n("resolution"), n("waterLevel")],
     add_foliage: [req(oa("points", [req(n("x")), req(n("z"))])), n("density"), s("item"), s("seed"), n("minSpacing")],
     scatter_summary: [],

package/dist/mcp/tools.js

@@ -64,6 +64,7 @@ const TOOL_DESCRIPTIONS = [
     { name: "set_terrain_layers", description: "Replace the reorderable terrain material layer stack; a params-only edit keeps painted blends." },
     { name: "blend_terrain", description: "Blend-paint a material layer's weight at x/z (weighted multi-layer blend); auto-adds the layer." },
     { name: "convert_scatter", description: "Detach a foliage/scatter region into individually-editable placed prop markers, removing the region." },
+    { name: "generate_streets", description: "Bake the seed-driven street generator into the scene as authorable road/route paths inside a volume (or explicit center+halfX/halfZ). mode net→roads, circuit→closed route; params overlays sliders (gridness/loopiness/connectivity/winding/...). Idempotent: re-running the same seed replaces its own prior output. One undoable edit; round-trips --save." },
     { name: "bake_minimap", description: "Rasterize the authored terrain into a stored minimap PNG on the document (runtime reads it as the Minimap background). Live-editor only — needs the mounted viewport's terrain sampler, not a headless CLI." },
     { name: "add_foliage", description: "Add a foliage/scatter region from a closed polygon (≥3 x/z points) with density and item." },
     { name: "scatter_summary", description: "Count foliage/scatter regions and their total deterministic instance placements." },

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 };
+}

package/dist/session.d.ts

@@ -195,6 +195,20 @@ export type EditorBridgeRequest = {
 } | {
     method: "convert_scatter";
     pathId: string;
+} | {
+    method: "generate_streets";
+    volumeId?: string;
+    center?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    halfX?: number;
+    halfZ?: number;
+    seed?: string;
+    mode?: "net" | "circuit";
+    kind?: string;
+    params?: Record<string, unknown>;
 } | {
     method: "bake_minimap";
     padding?: number;

package/dist/shell/AnimationPanel.d.ts

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

package/dist/shell/AnimationPanel.js

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