@jgengine/editor 0.18.1 → 0.19.0

package/dist/shell/AnimationGraphPanel.js

@@ -0,0 +1,172 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { markerCatalogId } from "@jgengine/core/world/authoredObjects";
+import { animationMetaPatch, clearAnimGraph, effectiveAnimGraph, readAnimationSetting, setTransitionDuration, storeAnimGraph, } from "../modelAnimationAuthoring.js";
+import { shallowArrayEqual, useStoreSelector } from "../useStoreSelector.js";
+import { graphParamControls, graphTriggers, MAX_PREVIEW_SECONDS, recordTrigger, simulateGraphPreview, } from "./animGraphPreview.js";
+import { initialClipPreviewState } from "./clipPreview.js";
+import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./theme.js";
+import { EmptyState, IconButton } from "./ui.js";
+const SOURCE_LABEL = {
+    authored: "Stored on this placement",
+    locomotion: "Built from the placement's states and one-shots",
+    auto: "Derived from the rig's clip names",
+};
+function conditionText(condition) {
+    return `${condition.param} ${condition.op} ${String(condition.value)}`;
+}
+function stateClips(state) {
+    if (state.kind === "clip")
+        return state.clip;
+    if (state.kind === "blend1D")
+        return state.points.map((point) => `${point.clip}@${point.at}`).join(" · ");
+    return state.points.map((point) => `${point.clip}@${point.at[0]},${point.at[1]}`).join(" · ");
+}
+/**
+ * Graph mode of the Animation dock: the selected placement's animation graph (layers, states,
+ * transitions), a scrubbed preview driven by the headless graph runtime and shown on the rig in the
+ * viewport, trigger buttons that record presses on the timeline, and crossfade editing that stores
+ * the graph on the placement as an undoable edit.
+ *
+ * @internal
+ */
+export function AnimationGraphPanel({ session, ui, rigged, }) {
+    const selection = useStoreSelector(session, (state) => state.selection, shallowArrayEqual);
+    const markers = useStoreSelector(session, (state) => state.document.markers);
+    const target = useMemo(() => {
+        for (const id of selection) {
+            const marker = markers.find((entry) => entry.id === id);
+            if (marker === undefined)
+                continue;
+            const catalogId = markerCatalogId(marker);
+            const asset = catalogId === null ? undefined : rigged.find((entry) => entry.id === catalogId);
+            if (asset?.url !== undefined && asset.clips !== undefined)
+                return { marker, asset };
+        }
+        return null;
+    }, [selection, markers, rigged]);
+    if (target === null) {
+        return (_jsx(EmptyState, { icon: "film", title: "Animation graph", badge: "Placed rig", description: "Select a placed instance of a rigged asset to see the graph it plays: layers, states and transitions, with a scrubbed preview on the rig in the viewport." }));
+    }
+    return _jsx(GraphInspector, { session: session, ui: ui, marker: target.marker, asset: target.asset }, target.marker.id);
+}
+function GraphInspector({ session, ui, marker, asset, }) {
+    const clips = asset.clips ?? [];
+    const setting = readAnimationSetting(marker.meta);
+    const effective = useMemo(() => effectiveAnimGraph(setting, clips), [JSON.stringify(setting), clips]);
+    const graph = effective?.graph ?? null;
+    const controls = useMemo(() => (graph === null ? [] : graphParamControls(graph)), [graph]);
+    const triggerNames = useMemo(() => (graph === null ? [] : graphTriggers(graph)), [graph]);
+    const [time, setTime] = useState(0);
+    const [playing, setPlaying] = useState(false);
+    const [params, setParams] = useState({});
+    const [triggers, setTriggers] = useState([]);
+    const durations = useStoreSelector(ui, (state) => state.clipPreview?.clipDurations);
+    const frame = useMemo(() => {
+        if (graph === null)
+            return null;
+        const merged = {};
+        for (const control of controls)
+            merged[control.name] = params[control.name] ?? (control.kind === "boolean" ? false : 0);
+        return simulateGraphPreview({ graph, durations: durations ?? {}, time, params: merged, triggers });
+    }, [graph, controls, params, triggers, time, durations]);
+    useEffect(() => {
+        if (asset.url === undefined)
+            return;
+        const current = ui.getState().clipPreview;
+        const sameAsset = current?.source.assetId === asset.id;
+        ui.patch({
+            clipPreview: {
+                source: { assetId: asset.id, label: asset.label, url: asset.url, clips },
+                driver: initialClipPreviewState(null),
+                duration: 0,
+                ...(sameAsset && current?.clipDurations !== undefined ? { clipDurations: current.clipDurations } : {}),
+            },
+        });
+        return () => {
+            if (ui.getState().clipPreview?.source.assetId === asset.id)
+                ui.patch({ clipPreview: null });
+        };
+    }, [asset.id, asset.url, asset.label, clips, ui]);
+    useEffect(() => {
+        const current = ui.getState().clipPreview;
+        if (current === null || current.source.assetId !== asset.id)
+            return;
+        if (graph === null || frame === null) {
+            if (current.graphPose !== undefined)
+                ui.patch({ clipPreview: { ...current, graphPose: undefined } });
+            return;
+        }
+        ui.patch({ clipPreview: { ...current, graphPose: { graph, clips: frame.clips } } });
+    }, [graph, frame, asset.id, ui, durations]);
+    const timeRef = useRef(time);
+    timeRef.current = time;
+    useEffect(() => {
+        if (!playing)
+            return;
+        let handle = 0;
+        let last = performance.now();
+        const tick = (now) => {
+            const next = timeRef.current + Math.min(0.05, Math.max(0, (now - last) / 1000));
+            last = now;
+            if (next >= MAX_PREVIEW_SECONDS) {
+                setTime(MAX_PREVIEW_SECONDS);
+                setPlaying(false);
+                return;
+            }
+            setTime(next);
+            handle = requestAnimationFrame(tick);
+        };
+        handle = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(handle);
+    }, [playing]);
+    const commit = (next) => session.dispatch({ type: "setMarker", id: marker.id, patch: { meta: { ...marker.meta, ...animationMetaPatch(next) } } }, { coalesce: `animation:${marker.id}` });
+    if (graph === null || effective === null || frame === null) {
+        return (_jsx(EmptyState, { icon: "film", title: "No graph", badge: marker.label ?? marker.id, description: "This placement plays no graph: its animation is off, a single clip, or the rig has no idle clip. Pick Custom or Auto in the inspector's Animation section." }));
+    }
+    const weights = new Map(frame.clips.map((clip) => [`${clip.layer}:${clip.clip}`, clip.weight]));
+    const trigger = (name) => setTriggers((current) => recordTrigger(current, name, timeRef.current));
+    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: marker.label ?? marker.id }), _jsxs("span", { className: "text-[10px] text-neutral-600", children: [asset.label, " \u00B7 ", SOURCE_LABEL[effective.source]] }), _jsx("div", { className: "ml-auto flex items-center gap-1", children: effective.source === "authored" ? (_jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => commit(clearAnimGraph(setting)), title: "Drop the stored graph", children: "Use derived graph" })) : (_jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => commit(storeAnimGraph(setting, graph)), title: "Store this graph on the placement", children: "Store graph" })) })] }), _jsxs("div", { className: "flex min-h-0 flex-1 gap-3 overflow-auto p-3", children: [_jsxs("div", { className: "flex w-64 shrink-0 flex-col gap-2", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(IconButton, { icon: playing ? "pause" : "play", label: playing ? "Pause preview" : "Play preview", size: 14, active: playing, onClick: () => setPlaying((value) => !value) }), _jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => {
+                                            setPlaying(false);
+                                            setTime(0);
+                                            setTriggers([]);
+                                        }, children: "Reset" }), _jsxs("span", { className: `ml-auto text-[10px] text-neutral-400 ${NUMERIC}`, children: [time.toFixed(2), " s"] })] }), _jsxs("label", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Scrub" }), _jsx("input", { type: "range", min: 0, max: MAX_PREVIEW_SECONDS, step: 0.01, value: time, "aria-label": "Graph preview time", className: `h-2 w-full accent-cyan-400 ${FOCUS_RING}`, onChange: (event) => {
+                                            setPlaying(false);
+                                            setTime(Number(event.target.value));
+                                        } }), _jsx(TriggerTicks, { triggers: triggers })] }), controls.map((control) => control.kind === "boolean" ? (_jsxs("label", { className: "flex items-center gap-2 text-[11px] text-neutral-300", children: [_jsx("input", { type: "checkbox", checked: params[control.name] === true, "aria-label": `Parameter ${control.name}`, onChange: (event) => setParams((current) => ({ ...current, [control.name]: event.target.checked })) }), control.name] }, control.name)) : (_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: control.name }), _jsx("span", { className: NUMERIC, children: Number(params[control.name] ?? 0).toFixed(2) })] }), _jsx("input", { type: "range", min: control.min, max: control.max, step: (control.max - control.min) / 200, value: Number(params[control.name] ?? 0), "aria-label": `Parameter ${control.name}`, className: `h-2 w-full accent-cyan-400 ${FOCUS_RING}`, onChange: (event) => setParams((current) => ({ ...current, [control.name]: Number(event.target.value) })) })] }, control.name))), triggerNames.length > 0 ? (_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Triggers at the playhead" }), _jsx("div", { className: "flex flex-wrap gap-1", children: triggerNames.map((name) => (_jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => trigger(name), children: name }, name))) })] })) : null, frame.events.length > 0 ? (_jsxs("div", { className: "flex flex-col gap-0.5", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Clip events" }), frame.events.slice(-6).map((event, index) => (_jsxs("span", { className: `text-[10px] text-amber-200/80 ${NUMERIC}`, children: [event.at.toFixed(2), " s \u00B7 ", event.name, " (", event.clip, ")"] }, index)))] })) : null] }), _jsx("div", { className: "flex min-w-0 flex-1 flex-col gap-3", children: graph.layers.map((layer) => (_jsxs("section", { className: "rounded-[6px] border border-white/[0.07] bg-white/[0.02]", "aria-label": `Layer ${layer.id}`, children: [_jsxs("header", { className: "flex items-center gap-2 border-b border-white/[0.06] px-2.5 py-1.5", children: [_jsx("span", { className: "text-[11px] font-medium text-neutral-100", children: layer.id }), _jsxs("span", { className: "text-[10px] text-neutral-500", children: ["entry ", layer.entry] }), layer.mask !== undefined ? _jsxs(Chip, { children: ["mask ", layer.mask.join(", ")] }) : null, layer.additive === true ? _jsx(Chip, { children: "additive" }) : null, layer.weight !== undefined ? _jsxs(Chip, { children: ["weight ", layer.weight] }) : null, _jsxs("span", { className: "ml-auto text-[10px] text-cyan-200", children: ["\u25B6 ", frame.states[layer.id]] })] }), _jsxs("div", { className: "grid grid-cols-2 gap-3 p-2.5", children: [_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "States" }), Object.entries(layer.states).map(([name, state]) => {
+                                                    const active = frame.states[layer.id] === name;
+                                                    const clipsOfState = state.kind === "clip" ? [state.clip] : state.points.map((point) => point.clip);
+                                                    const weight = clipsOfState.reduce((sum, clip) => sum + (weights.get(`${layer.id}:${clip}`) ?? 0), 0);
+                                                    return (_jsxs("div", { className: `rounded-[5px] border px-2 py-1 ${active ? "border-cyan-400/40 bg-cyan-500/10" : "border-white/[0.05]"}`, children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "text-[11px] text-neutral-100", children: name }), _jsx("span", { className: "text-[10px] text-neutral-500", children: state.kind }), _jsx("span", { className: `ml-auto text-[10px] text-neutral-400 ${NUMERIC}`, children: weight > 0 ? weight.toFixed(2) : "" })] }), _jsx("div", { className: "truncate text-[10px] text-neutral-500", title: stateClips(state), children: stateClips(state) }), _jsx("div", { className: "mt-1 h-1 rounded bg-white/[0.05]", children: _jsx("div", { className: "h-1 rounded bg-cyan-400/70", style: { width: `${Math.round(Math.min(1, weight) * 100)}%` } }) })] }, name));
+                                                })] }), _jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Transitions" }), layer.transitions.length === 0 ? _jsx("span", { className: "text-[10px] text-neutral-600", children: "None" }) : null, layer.transitions.map((transition, index) => (_jsx(TransitionRow, { transition: transition, onTrigger: transition.trigger === undefined ? undefined : () => trigger(transition.trigger), onDuration: (duration) => commit(setTransitionDuration(setting, graph, layer.id, index, duration)) }, index)))] })] })] }, layer.id))) })] })] }));
+}
+const SMALL_BUTTON = `rounded-[5px] border border-white/[0.08] bg-white/[0.03] px-2 py-0.5 text-[10px] text-neutral-300 transition-colors hover:bg-white/[0.07] ${FOCUS_RING}`;
+function Chip({ children }) {
+    return _jsx("span", { className: "rounded-[4px] bg-white/[0.05] px-1.5 py-0.5 text-[9px] text-neutral-400", children: children });
+}
+function TriggerTicks({ triggers }) {
+    if (triggers.length === 0)
+        return null;
+    return (_jsx("div", { className: "relative h-3", "aria-label": "Recorded triggers", children: triggers.map((entry, index) => (_jsx("span", { title: `${entry.name} at ${entry.at.toFixed(2)} s`, className: "absolute top-0 h-3 w-0.5 bg-amber-300/80", style: { left: `${(entry.at / MAX_PREVIEW_SECONDS) * 100}%` } }, index))) }));
+}
+function TransitionRow({ transition, onTrigger, onDuration, }) {
+    const [draft, setDraft] = useState(String(transition.duration ?? 0.2));
+    useEffect(() => setDraft(String(transition.duration ?? 0.2)), [transition.duration]);
+    const label = `${transition.from} → ${transition.to}`;
+    return (_jsxs("div", { className: "flex items-center gap-1.5 rounded-[5px] border border-white/[0.05] px-2 py-1", children: [_jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "truncate text-[11px] text-neutral-100", children: label }), _jsx("div", { className: "truncate text-[10px] text-neutral-500", children: [
+                            transition.trigger === undefined ? null : `trigger ${transition.trigger}`,
+                            ...(transition.when ?? []).map(conditionText),
+                            transition.exitTime === undefined ? null : `exit ${transition.exitTime}`,
+                        ]
+                            .filter((part) => part !== null)
+                            .join(" · ") || "always" })] }), _jsx("input", { className: `${INPUT_CLS} h-6 w-14 px-1 text-right text-[11px] ${NUMERIC}`, value: draft, "aria-label": `Crossfade seconds for ${label}`, inputMode: "decimal", onChange: (event) => setDraft(event.target.value), onBlur: () => {
+                    const value = Number(draft);
+                    if (Number.isFinite(value) && value !== (transition.duration ?? 0.2))
+                        onDuration(value);
+                    else
+                        setDraft(String(transition.duration ?? 0.2));
+                }, onKeyDown: (event) => {
+                    if (event.key === "Enter")
+                        event.target.blur();
+                } }), _jsx("span", { className: "text-[9px] text-neutral-600", children: "s" }), onTrigger !== undefined ? _jsx(IconButton, { icon: "play", label: `Trigger ${transition.trigger}`, size: 11, onClick: onTrigger }) : null] }));
+}

package/dist/shell/AnimationPanel.d.ts

@@ -3,7 +3,9 @@ import type { EditorAssetEntry } from "../AssetBrowser.js";
 import type { EditorHostApi } from "../session.js";
 import type { EditorUiStore } from "../uiStore.js";
 /**
- * Animation dock with two modes:
+ * Animation dock with three modes:
+ * - **Graph** — the selected placement's animation graph with a scrubbed, triggerable preview posed
+ *   on the rig in the viewport (see {@link AnimationGraphPanel}).
  * - **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

package/dist/shell/AnimationPanel.js

@@ -3,6 +3,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 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 { AnimationGraphPanel } from "./AnimationGraphPanel.js";
 import { listScrubbablePaths, samplePathAt } from "./pathFlythrough.js";
 import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./theme.js";
 import { EmptyState, IconButton } from "./ui.js";
@@ -13,7 +14,9 @@ function riggedAssets(assets) {
     return assets.filter((entry) => entry.url !== undefined && entry.clips !== undefined && entry.clips.length > 0);
 }
 /**
- * Animation dock with two modes:
+ * Animation dock with three modes:
+ * - **Graph** — the selected placement's animation graph with a scrubbed, triggerable preview posed
+ *   on the rig in the viewport (see {@link AnimationGraphPanel}).
  * - **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
@@ -23,9 +26,7 @@ function riggedAssets(assets) {
  */
 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");
+    const [mode, setMode] = useState(() => (rigged.length > 0 ? "graph" : "path"));
     // Tear down the viewport preview when the panel unmounts; leaving clip mode tears down in the
     // tab click below.
     useEffect(() => () => {
@@ -33,13 +34,14 @@ export function AnimationPanel({ session, api, ui, assets, }) {
             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"],
+                        ["graph", "Graph"],
                         ["clips", "Clip preview"],
+                        ["path", "Path flythrough"],
                     ].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: () => {
-                            if (id !== "clips" && ui.getState().clipPreview !== null)
+                            if (id !== mode && ui.getState().clipPreview !== null)
                                 ui.patch({ clipPreview: null });
                             setMode(id);
-                        }, children: label }, id))) }) }), mode === "path" ? (_jsx(PathFlythrough, { session: session, api: api })) : (_jsx(ClipPreview, { session: session, ui: ui, rigged: rigged }))] }));
+                        }, children: label }, id))) }) }), mode === "path" ? (_jsx(PathFlythrough, { session: session, api: api })) : mode === "graph" ? (_jsx(AnimationGraphPanel, { session: session, ui: ui, rigged: rigged })) : (_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, }) {

package/dist/shell/WorkspaceRail.js

@@ -8,7 +8,7 @@ export const WORKSPACES = [
     { id: "assets", label: "Assets", icon: "image", supported: true },
     { id: "materials", label: "Materials", icon: "sphere", supported: true },
     { id: "scripting", label: "Scripting", icon: "script", supported: true },
-    { id: "animation", label: "Animation", icon: "film", supported: false },
+    { id: "animation", label: "Animation", icon: "film", supported: true },
     { id: "audio", label: "Audio", icon: "audio", supported: false },
     { id: "lighting", label: "Lighting", icon: "bulb", supported: true },
     { id: "ai", label: "AI", icon: "sparkle", supported: true },

package/dist/shell/animGraphPreview.d.ts

@@ -0,0 +1,56 @@
+import { type AnimClipOutput, type AnimGraph, type AnimParams } from "@jgengine/core/anim/animGraph";
+/**
+ * Editor animation-graph preview: pure logic, no JSX. Replays a graph from its entry states to a
+ * scrub time with fixed steps, arming each recorded trigger at its time, so scrubbing back and forth
+ * always shows the same pose the runtime would reach.
+ *
+ * @internal
+ */
+/** A trigger pressed during preview, at a time on the scrub timeline. */
+export interface GraphPreviewTrigger {
+    at: number;
+    name: string;
+}
+/** Inputs for {@link simulateGraphPreview}. */
+export interface GraphPreviewInput {
+    graph: AnimGraph;
+    /** Clip durations in seconds from the loaded rig; unknown clips count as one second. */
+    durations: Readonly<Record<string, number>>;
+    time: number;
+    params: AnimParams;
+    triggers: readonly GraphPreviewTrigger[];
+    /** Fixed step in seconds. Default 1/30. */
+    step?: number;
+}
+/** What the rig shows at the scrub time. */
+export interface GraphPreviewFrame {
+    time: number;
+    /** Current state per layer id. */
+    states: Record<string, string>;
+    clips: AnimClipOutput[];
+    /** Clip events fired from zero to `time`, with when they fired. */
+    events: {
+        at: number;
+        name: string;
+        clip: string;
+    }[];
+}
+/** Longest preview timeline the scrubber offers, in seconds. */
+export declare const MAX_PREVIEW_SECONDS = 20;
+/** Replays `graph` from its entry states to `time` and reports the pose there. */
+export declare function simulateGraphPreview(input: GraphPreviewInput): GraphPreviewFrame;
+/** Every clip name a graph plays. */
+export declare function graphClipNames(graph: AnimGraph): string[];
+/** Every trigger name a graph's transitions listen for, in first-seen order. */
+export declare function graphTriggers(graph: AnimGraph): string[];
+/** A parameter the preview needs a control for: blend inputs and condition operands. */
+export interface GraphParamControl {
+    name: string;
+    kind: "number" | "boolean";
+    min: number;
+    max: number;
+}
+/** Parameters a graph reads, with a range covering its blend points and condition values. */
+export declare function graphParamControls(graph: AnimGraph): GraphParamControl[];
+/** Adds a trigger press at `at`, keeping the log in time order. */
+export declare function recordTrigger(triggers: readonly GraphPreviewTrigger[], name: string, at: number): GraphPreviewTrigger[];

package/dist/shell/animGraphPreview.js

@@ -0,0 +1,92 @@
+import { createAnimGraphRuntime, } from "@jgengine/core/anim/animGraph";
+/** Longest preview timeline the scrubber offers, in seconds. */
+export const MAX_PREVIEW_SECONDS = 20;
+/** Replays `graph` from its entry states to `time` and reports the pose there. */
+export function simulateGraphPreview(input) {
+    const step = input.step ?? 1 / 30;
+    const time = Math.max(0, Math.min(MAX_PREVIEW_SECONDS, input.time));
+    const runtime = createAnimGraphRuntime(input.graph);
+    const clips = {};
+    for (const name of graphClipNames(input.graph))
+        clips[name] = input.durations[name] ?? 1;
+    const pending = [...input.triggers].filter((trigger) => trigger.at <= time).sort((a, b) => a.at - b.at);
+    const events = [];
+    let elapsed = 0;
+    let next = 0;
+    let out = runtime.advance(0, input.params, clips);
+    while (elapsed < time - 1e-9) {
+        const dt = Math.min(step, time - elapsed);
+        while (next < pending.length && pending[next].at <= elapsed + 1e-9)
+            runtime.trigger(pending[next++].name);
+        out = runtime.advance(dt, input.params, clips);
+        elapsed += dt;
+        for (const event of out.events)
+            events.push({ at: elapsed, name: event.name, clip: event.clip });
+    }
+    if (next < pending.length) {
+        while (next < pending.length)
+            runtime.trigger(pending[next++].name);
+        out = runtime.advance(0, input.params, clips);
+    }
+    const states = {};
+    for (const layer of input.graph.layers)
+        states[layer.id] = runtime.stateOf(layer.id) ?? layer.entry;
+    return { time, states, clips: out.clips, events };
+}
+/** Every clip name a graph plays. */
+export function graphClipNames(graph) {
+    const names = new Set();
+    for (const layer of graph.layers) {
+        for (const state of Object.values(layer.states)) {
+            if (state.kind === "clip")
+                names.add(state.clip);
+            else
+                for (const point of state.points)
+                    names.add(point.clip);
+        }
+    }
+    return [...names];
+}
+/** Every trigger name a graph's transitions listen for, in first-seen order. */
+export function graphTriggers(graph) {
+    const names = new Set();
+    for (const layer of graph.layers)
+        for (const transition of layer.transitions)
+            if (transition.trigger !== undefined)
+                names.add(transition.trigger);
+    return [...names];
+}
+/** Parameters a graph reads, with a range covering its blend points and condition values. */
+export function graphParamControls(graph) {
+    const controls = new Map();
+    const widen = (name, value) => {
+        const kind = typeof value === "boolean" ? "boolean" : "number";
+        const current = controls.get(name) ?? { name, kind, min: 0, max: 1 };
+        if (kind === "number") {
+            current.min = Math.min(current.min, value);
+            current.max = Math.max(current.max, value * 1.25, value + 0.5);
+        }
+        controls.set(name, current);
+    };
+    for (const layer of graph.layers) {
+        for (const state of Object.values(layer.states)) {
+            if (state.kind === "blend1D")
+                for (const point of state.points)
+                    widen(state.param, point.at);
+            if (state.kind === "blend2D") {
+                for (const point of state.points) {
+                    widen(state.params[0], point.at[0]);
+                    widen(state.params[1], point.at[1]);
+                }
+            }
+        }
+        for (const transition of layer.transitions)
+            for (const condition of transition.when ?? [])
+                widen(condition.param, condition.value);
+    }
+    return [...controls.values()];
+}
+/** Adds a trigger press at `at`, keeping the log in time order. */
+export function recordTrigger(triggers, name, at) {
+    return [...triggers, { at, name }].sort((a, b) => a.at - b.at);
+}

package/dist/shell/clipPreview.d.ts

@@ -1,3 +1,4 @@
+import type { AnimClipOutput, AnimGraph } from "@jgengine/core/anim/animGraph";
 import { type ClipRole } from "@jgengine/core/game/clipRoles";
 import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
 /**
@@ -39,6 +40,13 @@ export interface ClipPreviewSession {
     readonly source: ClipPreviewSource;
     readonly driver: ClipPreviewState;
     readonly duration: number;
+    /** Every clip's duration, published by the viewport layer once the GLB loads. */
+    readonly clipDurations?: Readonly<Record<string, number>>;
+    /** When set, the viewport poses the rig from this graph output instead of playing `driver`'s clip. */
+    readonly graphPose?: {
+        readonly graph: AnimGraph;
+        readonly clips: readonly AnimClipOutput[];
+    };
 }
 /** Playback state of the clip preview driver. `time` is seconds into the clip. */
 export interface ClipPreviewState {

package/package.json

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

package/skills/ce-handoff/SKILL.md

@@ -143,7 +143,7 @@ When sufficient, return a concise orientation: objective, progress, decisions, c
 
 ## JGengine notes
 
-- Multi-session engine work often spans `docs/plans/`, GitHub issues, and stacked PRs — point at those; do not paste full plan bodies.
+- Multi-session engine work spans GitHub issues and PRs — point at those; do not paste full plan bodies.
 - Prefer `bun run agent:bootstrap --check` status, branch names, and PR links as state anchors.
 - Local parallelism uses `.claude/worktrees/`; never invent `C:\tmp\…` Codex-shared trees.
 - Durable process changes belong in skills, not only the handoff.

package/skills/jgengine/SKILL.md

@@ -5,7 +5,9 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 # JGengine intake and router
 
-Read the JGengine README for package truth, commands, layering, and license — the repo-root [`README.md`](../../../README.md) in the monorepo, or [jgengine.com](https://jgengine.com) from a scaffolded consumer project (where the relative link does not resolve). This skill decides what to load; it is not an engine manual.
+This skill decides what to load; it is not an engine manual. Package map, commands, layering, and license live in the JGengine README (repo-root [`README.md`](../../../README.md) in the monorepo, [jgengine.com](https://jgengine.com) from a created project); open it when you need one of those facts.
+
+A created project installs only `jgengine`, `jgengine-editor`, `jgengine-verify`, `game-design`, and `jgengine-ui`. Run `npx jgengine skills -p --all` before loading any other domain named below. Those projects do not ship `api.md`; read exact signatures from the `.d.ts` files under `node_modules/@jgengine/<pkg>/dist/`.
 
 ## 1. Establish the target
 
@@ -20,7 +22,7 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 - HUD/menu states and **custom** UI art direction (compose shipped building blocks + HudTheme; no unskinned stock face)
 - one observable completion scenario
 
-For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player model, editor scene); a grid, card, tile, or other board game with no 3D scene takes `create --2d` (a `board` world drawn by GameUI over `@jgengine/core/puzzle/cellGrid`). For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
 
 For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
 
@@ -46,9 +48,9 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
-0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search `capabilities.md` by intent; it maps needs to imports. Outside the monorepo (or before a domain skill is even loaded), `npx jgengine find <intent>` greps every shipped capability index at once and prints the primitive + import — reach for it the moment you're tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. If you're writing a `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob, a shipped drop-in almost certainly exists (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
-2. Open `api.md` only when exact signatures or export inventory are needed.
+0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) (`combat-loop`, `loot`, `world-drops`, `click-target`, `ability-bar`, `hitscan-weapon`, `rolled-gear`, `enter-vehicle` and more); `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
+1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); in the monorepo, `grep -i "<intent>" .claude/skills/*/capabilities.md` does the same. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
+2. Open `api.md` (monorepo) or the package `.d.ts` only when exact signatures are needed; grep it, never read it whole.
 3. Open the linked reference only for a deeper recipe or trap.
 4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.