@volter/editor-blender 0.1.140 → 0.1.142

package/LICENSE

@@ -34,6 +34,17 @@ ARTWORK is not.
   be copied into an Apache-2.0 or MIT part of this repository —
   `packages/editor`'s own icon set included.
 
+  ONE SOURCE FILE FOLLOWS BLENDER'S OWN CODE.
+
+  `contributions/blender-pose.ts` evaluates a pose as Blender does, and is
+  written from Blender's source: its damped-track constraint follows
+  `damptrack_do_transform` statement by statement, and its NLA stack, channel
+  blending, bone matrices and F-Curve evaluation follow the Blender functions
+  its header names. It is a derivative work of GPL-2.0-or-later code and,
+  exercising Blender's "or later", is conveyed under the GNU General Public
+  License, version 3 or later, not the AGPL. The file says so in its header.
+  It may not be copied into an Apache-2.0 or MIT part of this repository.
+
 THE COMBINATION, AND WHY THIS PACKAGE CARRIES TWO LICENCES. Our own code in
 this package is licensed under the GNU Affero General Public License,
 version 3 only.

package/README.md

@@ -2,7 +2,7 @@
 
 Blender modeling documents, inspectors, commands, layouts and presentation for
 Volter Editor. The integration talks to the independent Blender engine over its
-worker wire and contributes its editing surfaces through the editor SDK.
+worker wire and contributes its editing surfaces through the SDK.
 
 The package uses the project contracts and shared Three rendering/capture
 utilities. It imports no editor-core internals and no game runtime. Its

package/contributions/blender-animation-editors.tsx

@@ -0,0 +1,387 @@
+/**
+ * BLENDER'S ANIMATION EDITORS beside the Timeline, in the bottom area's Animation view: the editor-
+ * type menu Blender's area header has, the Dope Sheet's ACTION EDITOR and the NLA editor.
+ *
+ * - **Action Editor** (`SpaceAction.mode == 'ACTION'`): one armature's active action. Its
+ *   selector is Blender's: picking an action writes `animation_data.action` (and its slot), so the
+ *   character plays it; the channel list is one row per bone with the frames it keys.
+ * - **NLA** (`SPACE_NLA`): each armature's tracks, bottom track last as Blender lists them, their
+ *   strips over scene frames, and the active action's own line on top.
+ *
+ * WHILE A GAME RUNS both show what the game is animating, read-only, the way a game engine's
+ * animator view highlights the live state: each character's clips as its last update posed them
+ * (`blender-play-skin.ts`'s `live`), with the frame and influence of each. Nothing is written
+ * then: the game owns its copy.
+ */
+import { type ReactNode, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { blenderRnaSet, blenderRnaVersion, subscribeBlenderRna } from '../host/blender-runtime-host';
+import { liveAnimation, subscribeLiveAnimation } from '../src/play-live';
+import {
+  type AnimationEditor,
+  setTimelineViewState,
+  subscribeTimelineView,
+  timelineViewState,
+  timelineViewVersion,
+} from '../src/timeline-view-state';
+import { PlayModeSwitch } from './blender-game-panel';
+import { blenderSkin, blenderSkinVersion, subscribeBlenderSkin } from './blender-runtime-skin';
+import {
+  CHANNEL_HEIGHT,
+  DIAMOND_RADIUS,
+  DIAMOND_STROKE,
+  HEADER_HEIGHT,
+  KEY_COLORS,
+  PLAYHEAD,
+  SCRUB_HEIGHT,
+  TIMELINE_CHROME,
+  TIMELINE_THEME,
+} from './blender-timeline-geometry';
+
+const EDITORS: readonly { readonly id: AnimationEditor; readonly label: string }[] = [
+  { id: 'timeline', label: 'Timeline' },
+  { id: 'action', label: 'Action Editor' },
+  { id: 'nla', label: 'Nonlinear Animation' },
+];
+/** The channel region's width: Blender's default `ACHANNEL_NAMEWIDTH` area for a Dope Sheet. */
+const CHANNELS_WIDTH = 200;
+
+/** BLENDER'S EDITOR-TYPE MENU, limited to its animation editors: which one this area shows. */
+export function AnimationEditorMenu() {
+  useSyncExternalStore(subscribeTimelineView, timelineViewVersion, timelineViewVersion);
+  const { editor } = timelineViewState();
+  return (
+    <select
+      aria-label="Animation editor"
+      data-testid="animation-editor-type"
+      value={editor}
+      onChange={(event) => setTimelineViewState({ editor: event.target.value as AnimationEditor })}
+      style={{
+        height: TIMELINE_CHROME.unit,
+        border: `1px solid ${TIMELINE_CHROME.widgetOutline}`,
+        borderRadius: TIMELINE_CHROME.widgetRadius,
+        background: TIMELINE_CHROME.widget,
+        color: TIMELINE_CHROME.widgetText,
+        font: 'inherit',
+      }}
+    >
+      {EDITORS.map((one) => <option key={one.id} value={one.id}>{one.label}</option>)}
+    </select>
+  );
+}
+
+/** Re-render on every frame while a game runs (its animation changes each update), else never. */
+function useLive() {
+  const live = useSyncExternalStore(subscribeLiveAnimation, liveAnimation, () => null);
+  const [, setTick] = useState(0);
+  useEffect(() => {
+    if (!live) return;
+    let frame = requestAnimationFrame(function tick() {
+      setTick((n) => (n + 1) % 1_000_000);
+      frame = requestAnimationFrame(tick);
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [live]);
+  return live;
+}
+
+function useMeasured() {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [size, setSize] = useState({ w: 0, h: 0 });
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+    const observer = new ResizeObserver(() => setSize({ w: element.clientWidth, h: element.clientHeight }));
+    observer.observe(element);
+    setSize({ w: element.clientWidth, h: element.clientHeight });
+    return () => observer.disconnect();
+  }, []);
+  return { ref, size };
+}
+
+function Header({ children }: { readonly children?: ReactNode }) {
+  return (
+    <div
+      style={{
+        height: HEADER_HEIGHT,
+        flex: `0 0 ${HEADER_HEIGHT}px`,
+        display: 'flex',
+        alignItems: 'center',
+        gap: TIMELINE_CHROME.headerGap,
+        padding: TIMELINE_CHROME.headerPadding,
+        background: TIMELINE_THEME.header,
+        borderBottom: `1px solid ${TIMELINE_CHROME.rule}`,
+      }}
+    >
+      <PlayModeSwitch title="Animation" />
+      <AnimationEditorMenu />
+      {children}
+    </div>
+  );
+}
+
+function Frame({ children, header }: { readonly children: ReactNode; readonly header: ReactNode }) {
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        inset: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        overflow: 'hidden',
+        background: TIMELINE_THEME.back,
+        color: TIMELINE_CHROME.text,
+        font: '11px Inter, system-ui, sans-serif',
+      }}
+    >
+      {header}
+      {children}
+    </div>
+  );
+}
+
+/** A frame ruler over [start, end] in `width` pixels: majors every step that keeps labels apart. */
+function ruler(start: number, end: number, width: number) {
+  const span = Math.max(1, end - start);
+  const pixelsPerFrame = Math.max(1e-6, width / (span * 1.1));
+  const first = start - span * 0.05;
+  const toX = (frame: number) => (frame - first) * pixelsPerFrame;
+  const steps = [1, 2, 5, 10, 20, 25, 50, 100, 250, 500, 1000];
+  const step = steps.find((one) => one * pixelsPerFrame >= 40) ?? 1000;
+  const majors: number[] = [];
+  // Unmeasured (zero width) draws no ruler; a measured one has at most width / 40 labels.
+  if (width > 0)
+    for (let frame = Math.ceil(first / step) * step; toX(frame) <= width && majors.length < 500; frame += step) majors.push(frame);
+  return { toX, majors, toFrame: (x: number) => first + x / pixelsPerFrame };
+}
+
+function Playhead({ x, frame, height }: { readonly x: number; readonly frame: number; readonly height: number }) {
+  const text = `${Math.round(frame)}`;
+  const width = Math.max(PLAYHEAD.minPillWidth, text.length * 6 + 2 * PLAYHEAD.textPadding);
+  return (
+    <g>
+      <rect x={x - PLAYHEAD.stalkWidth / 2} y={SCRUB_HEIGHT} width={PLAYHEAD.stalkWidth} height={Math.max(0, height - SCRUB_HEIGHT)} fill={TIMELINE_THEME.playhead} />
+      <rect x={x - width / 2} y={PLAYHEAD.margin} width={width} height={SCRUB_HEIGHT - 2 * PLAYHEAD.margin} rx={PLAYHEAD.radius} fill={TIMELINE_THEME.playhead} />
+      <text x={x} y={15.5} textAnchor="middle" fill={TIMELINE_THEME.playheadText} fontSize={11}>{text}</text>
+    </g>
+  );
+}
+
+function Grid({ majors, toX, width, height }: { readonly majors: number[]; readonly toX: (f: number) => number; readonly width: number; readonly height: number }) {
+  return (
+    <g>
+      {majors.map((frame) => <line key={`g${frame}`} x1={toX(frame)} y1={SCRUB_HEIGHT} x2={toX(frame)} y2={height} stroke={TIMELINE_THEME.grid} />)}
+      <rect x={0} y={0} width={width} height={SCRUB_HEIGHT} fill={TIMELINE_THEME.scrubBack} />
+      {majors.map((frame) => <text key={`t${frame}`} x={toX(frame)} y={15.5} textAnchor="middle" fill={TIMELINE_THEME.scrubText} fontSize={11}>{frame}</text>)}
+    </g>
+  );
+}
+
+function diamond(x: number, y: number, key: string) {
+  const r = DIAMOND_RADIUS;
+  return <polygon key={key} points={`${x},${y - r} ${x + r},${y} ${x},${y + r} ${x - r},${y}`} fill={KEY_COLORS['KEYFRAME']!.fill} stroke={TIMELINE_THEME.keyBorder} strokeWidth={DIAMOND_STROKE} />;
+}
+
+const address = (armature: string) => `bpy.data.objects[${JSON.stringify(armature)}].animation_data`;
+
+/**
+ * THE DOPE SHEET'S ACTION EDITOR for the armature the Timeline describes. Its selector is
+ * Blender's: an action picked here becomes the armature's `animation_data.action`.
+ */
+export function BlenderActionEditor() {
+  useSyncExternalStore(subscribeBlenderRna, blenderRnaVersion, blenderRnaVersion);
+  useSyncExternalStore(subscribeBlenderSkin, blenderSkinVersion, blenderSkinVersion);
+  const live = useLive();
+  const { ref, size } = useMeasured();
+  const [refusal, setRefusal] = useState<string | null>(null);
+  const play = blenderSkin.state();
+  const armature = blenderSkin.subject ?? play.armature;
+  const running = live?.live().find((one) => one.armature === armature) ?? null;
+  // READ-ONLY WHILE ANY GAME RUNS: the game owns its copy, and the document is not edited under it.
+  const gameRunning = live !== null;
+  const top = running?.layers.at(-1) ?? null;
+  const action = running ? top?.action ?? null : play.action;
+  const channels = useMemo(
+    () => (running && action ? live!.channels(running.armature, action) : blenderSkin.channels()),
+    // The live clip's keys do not change while it plays; the edited clip's change with its revision.
+    [running ? action : play.action, play.engineCalls, live],
+  );
+  const frames = channels.flatMap((channel) => channel.keys);
+  const start = frames.length ? Math.min(...frames) : play.start;
+  const end = frames.length ? Math.max(...frames) : play.end;
+  const width = Math.max(0, size.w - CHANNELS_WIDTH);
+  const { toX, majors, toFrame } = ruler(start, end, width);
+  const frame = running ? top?.frame ?? start : play.frame;
+  const rowTop = (i: number) => SCRUB_HEIGHT + CHANNEL_HEIGHT * (i + 1);
+  const height = SCRUB_HEIGHT + CHANNEL_HEIGHT * (channels.length + 2);
+  const summary = [...new Set(frames)].sort((a, b) => a - b);
+
+  const pick = async (name: string) => {
+    if (!armature || gameRunning) return;
+    setRefusal(null);
+    // ONE WRITE, as Blender's own selector makes it: assigning the action lets Blender choose the
+    // slot that fits this armature (measured: `OBArmature` for a UAL1 clip on a renamed rig).
+    try {
+      await blenderRnaSet(address(armature), 'action', `bpy.data.actions[${JSON.stringify(name)}]`);
+    } catch (error) {
+      setRefusal(`${name} could not be assigned to ${armature}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+
+  const header = (
+    <Header>
+      <span style={{ color: TIMELINE_CHROME.textHi }}>{armature ?? 'No armature'}</span>
+      <select
+        aria-label="Action"
+        data-testid="action-editor-action"
+        value={action ?? ''}
+        disabled={!armature || gameRunning}
+        title={gameRunning ? 'A game is running; it chooses the clips while it runs' : 'The action this armature plays (animation_data.action)'}
+        onChange={(event) => void pick(event.target.value)}
+        style={{
+          height: TIMELINE_CHROME.unit,
+          minWidth: 180,
+          border: `1px solid ${TIMELINE_CHROME.widgetOutline}`,
+          borderRadius: TIMELINE_CHROME.widgetRadius,
+          background: TIMELINE_CHROME.widget,
+          color: TIMELINE_CHROME.widgetText,
+          font: 'inherit',
+        }}
+      >
+        {action === null ? <option value="">No action</option> : null}
+        {(running && action ? [action] : blenderSkin.actionNames()).map((name) => <option key={name} value={name}>{name}</option>)}
+      </select>
+      {running ? (
+        <span data-testid="action-editor-live" style={{ color: TIMELINE_THEME.playhead }}>
+          ● game running: {running.layers.map((layer) => `${layer.action} @${layer.frame.toFixed(1)} ×${layer.influence.toFixed(2)}`).join(' + ')}
+        </span>
+      ) : null}
+      <div style={{ flex: 1 }} />
+      {refusal ? <span style={{ color: TIMELINE_CHROME.refusal }}>{refusal}</span> : null}
+    </Header>
+  );
+
+  return (
+    <Frame header={header}>
+      <div ref={ref} style={{ flex: 1, minHeight: 0, overflowY: 'auto', overflowX: 'hidden' }}>
+        <div style={{ display: 'flex', minHeight: height }}>
+          <div style={{ width: CHANNELS_WIDTH, flex: `0 0 ${CHANNELS_WIDTH}px`, borderRight: `1px solid ${TIMELINE_CHROME.rule}` }}>
+            <div style={{ height: SCRUB_HEIGHT, background: TIMELINE_THEME.scrubBack }} />
+            <div style={{ height: CHANNEL_HEIGHT, paddingLeft: 6, color: TIMELINE_CHROME.textHi }}>Summary</div>
+            {channels.map((channel) => (
+              <div key={channel.bone} style={{ height: CHANNEL_HEIGHT, paddingLeft: 18, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>{channel.bone}</div>
+            ))}
+          </div>
+          <svg
+            width={width}
+            height={height}
+            style={{ display: 'block', cursor: gameRunning ? 'default' : 'ew-resize' }}
+            aria-label="Action Editor"
+            onPointerDown={(event) => {
+              if (gameRunning) return;
+              const box = event.currentTarget.getBoundingClientRect();
+              blenderSkin.transport?.seekFrame(Math.round(toFrame(event.clientX - box.left)));
+            }}
+          >
+            <rect x={0} y={0} width={width} height={height} fill={TIMELINE_THEME.back} />
+            <Grid majors={majors} toX={toX} width={width} height={height} />
+            {summary.map((key) => diamond(toX(key), rowTop(0) - CHANNEL_HEIGHT / 2, `s${key}`))}
+            {channels.map((channel, i) => channel.keys.map((key) => diamond(toX(key), rowTop(i + 1) - CHANNEL_HEIGHT / 2, `${channel.bone}${key}`)))}
+            <Playhead x={toX(frame)} frame={frame} height={height} />
+          </svg>
+        </div>
+      </div>
+    </Frame>
+  );
+}
+
+/** THE NLA EDITOR: every armature's tracks and strips over scene frames, and its active action. */
+export function BlenderNlaEditor() {
+  useSyncExternalStore(subscribeBlenderRna, blenderRnaVersion, blenderRnaVersion);
+  useSyncExternalStore(subscribeBlenderSkin, blenderSkinVersion, blenderSkinVersion);
+  const live = useLive();
+  const { ref, size } = useMeasured();
+  const play = blenderSkin.state();
+  const stacks = blenderSkin.stacks();
+  const running = live?.live() ?? null;
+  const width = Math.max(0, size.w - CHANNELS_WIDTH);
+  const { toX, majors } = ruler(play.start, play.end, width);
+  type Row = { label: string; kind: 'armature' | 'action' | 'track'; strips: { name: string; start: number; end: number; mute: boolean }[]; live?: string; mute?: boolean };
+  const rows: Row[] = [];
+  for (const stack of stacks) {
+    const layers = running?.find((one) => one.armature === stack.armature)?.layers ?? null;
+    const influence = (track: string | null) => {
+      const layer = layers?.find((one) => one.track === track);
+      return layer ? `@${layer.frame.toFixed(1)} ×${layer.influence.toFixed(2)}` : undefined;
+    };
+    rows.push({ label: stack.armature, kind: 'armature', strips: [] });
+    const activeAction = layers ? layers.find((one) => one.track === null)?.action ?? null : stack.action;
+    const activeLive = influence(null);
+    rows.push({ label: activeAction ? `[Action] ${activeAction}` : '[Action] (none)', kind: 'action', strips: [], ...(activeLive ? { live: activeLive } : {}) });
+    for (const track of [...(stack.animation?.tracks ?? [])].reverse()) {
+      const playingHere = influence(track.name);
+      rows.push({
+        label: track.name,
+        kind: 'track',
+        mute: track.mute,
+        strips: track.strips.map((strip) => ({ name: strip.name, start: strip.start, end: strip.end, mute: strip.mute })),
+        ...(playingHere ? { live: playingHere } : {}),
+      });
+    }
+  }
+  const height = SCRUB_HEIGHT + CHANNEL_HEIGHT * (rows.length + 1);
+  const header = (
+    <Header>
+      {running ? <span data-testid="nla-live" style={{ color: TIMELINE_THEME.playhead }}>● game running: each playing track shows the game's frame and influence; the strips are the file's layout</span> : null}
+    </Header>
+  );
+  return (
+    <Frame header={header}>
+      <div ref={ref} style={{ flex: 1, minHeight: 0, overflowY: 'auto', overflowX: 'hidden' }}>
+        <div style={{ display: 'flex', minHeight: height }}>
+          <div style={{ width: CHANNELS_WIDTH, flex: `0 0 ${CHANNELS_WIDTH}px`, borderRight: `1px solid ${TIMELINE_CHROME.rule}` }}>
+            <div style={{ height: SCRUB_HEIGHT, background: TIMELINE_THEME.scrubBack }} />
+            {rows.map((row, i) => (
+              <div
+                key={`${row.label}${i}`}
+                data-testid={`nla-row-${row.kind}`}
+                style={{
+                  height: CHANNEL_HEIGHT,
+                  paddingLeft: row.kind === 'armature' ? 6 : 18,
+                  whiteSpace: 'nowrap',
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                  color: row.kind === 'armature' ? TIMELINE_CHROME.textHi : row.mute ? '#6a6a6a' : TIMELINE_CHROME.text,
+                }}
+              >
+                {row.label}{row.live ? <span style={{ color: TIMELINE_THEME.playhead }}> {row.live}</span> : null}
+              </div>
+            ))}
+          </div>
+          <svg width={width} height={height} style={{ display: 'block' }} aria-label="NLA">
+            <rect x={0} y={0} width={width} height={height} fill={TIMELINE_THEME.back} />
+            <Grid majors={majors} toX={toX} width={width} height={height} />
+            {rows.map((row, i) => {
+              const y = SCRUB_HEIGHT + CHANNEL_HEIGHT * i + 2;
+              return row.strips.map((strip) => (
+                <g key={`${i}${strip.name}${strip.start}`}>
+                  <rect
+                    x={toX(strip.start)}
+                    y={y}
+                    width={Math.max(2, toX(strip.end) - toX(strip.start))}
+                    height={CHANNEL_HEIGHT - 4}
+                    rx={2}
+                    fill={strip.mute || row.mute ? '#4a4a4a' : running ? (row.live ? '#5a7fb8' : '#555555') : '#7b7b7b'}
+                    opacity={running ? 0.6 : 1}
+                    stroke="#1a1a1a"
+                  />
+                  <text x={toX(strip.start) + 4} y={y + CHANNEL_HEIGHT - 7} fill="#ffffff" fontSize={10}>{strip.name}</text>
+                </g>
+              ));
+            })}
+            {running ? null : <Playhead x={toX(play.frame)} frame={play.frame} height={height} />}
+          </svg>
+        </div>
+      </div>
+    </Frame>
+  );
+}

package/contributions/blender-game-panel.tsx

@@ -7,12 +7,12 @@
  * ## One Play, here
  *
  * The confusion it ends was two Plays on one screen: the header's (the play script) and the
- * Timeline's (the file's animation). A mode now chooses which one exists. In Movie mode the
- * Timeline's transport is the only one; in Game mode this panel's Play is the only one, and the
- * Timeline is not mounted. The 3D viewport's header carries neither (`blender-header-menus.tsx`
+ * Timeline's (the file's animation). A mode now chooses which one is shown. In Animation mode the
+ * Timeline's transport is the one shown; in Game mode this panel's Play is, and the Timeline is
+ * not mounted. A game started in Game mode keeps running in Animation mode. The 3D viewport's header carries neither (`blender-header-menus.tsx`
  * is its menus alone). Escape still stops a game, from the stage, as before.
  *
- * ## The Game | Movie switch is the bottom area's own
+ * ## The Game | Animation switch is the bottom area's own
  *
  * Switching modes swaps this area and nothing else, so the switch stands at the leading edge of
  * the area's header row, in place of its title — in this panel and in the Timeline alike
@@ -24,15 +24,15 @@
  *
  * Blender's Timeline strip (`model.layout.ts`'s measured 0.0719 — 63 px of an 880-px column)
  * showed this panel's play log as one clipped line. So Game mode asks the area for
- * {@link GAME_PANEL_RATIO} (`setWorkspaceAreaRatio`, by the bottom area's document) and Movie
+ * {@link GAME_PANEL_RATIO} (`setWorkspaceAreaRatio`, by the bottom area's document) and Animation
  * mode gives Blender's back: each switch stands the area up at its mode's size, as a workspace
  * switch does, and the sash stays the person's in between.
  *
  * ## What it drives is the Play tool's own run
  *
  * Every control here is a call on the Play tool's door (`DocumentPlayExtension` and its
- * `transport`, `@volter/editor-sdk/kit/document-play-extension`), the same calls the runner
- * reads every frame (`@volter/editor-model-play`'s `model-play.ts`), so Pause freezes the
+ * `transport`, `@volter/sdk/kit/document-play-extension`), the same calls the runner
+ * reads every frame (`@volter/play`'s `model-play.ts`), so Pause freezes the
  * simulation itself — the `dt` the script is handed — and the clock drawn here is that
  * simulation's: the seconds the script was given and the updates it ran. The verbs below are
  * the same calls behind command ids (`volter.model-play.<verb>`), which is how an agent drives
@@ -64,7 +64,7 @@
  * playhead's blue, which is Blender's own selected-widget colour in the same theme.
  */
 import { blenderSkin } from './blender-runtime-skin';
-import { registerViewVerbs } from '@volter/editor-sdk/views';
+import { registerViewVerbs } from '@volter/sdk/views';
 import {
   type DocumentPlayAutoplay,
   type DocumentPlayClock,
@@ -73,7 +73,7 @@ import {
   type DocumentPlayTransport,
   documentPlayExtension,
   subscribeDocumentPlayExtensions,
-} from '@volter/editor-sdk/kit/document-play-extension';
+} from '@volter/sdk/kit/document-play-extension';
 import {
   type MouseEvent,
   type ReactNode,
@@ -89,6 +89,7 @@ import {
   type ModelPlayMode,
   modelDocumentSource,
   modelPlayMode,
+  playModeOf,
   playModeVersion,
   servedModelDocument,
   setChosenPlayMode,
@@ -112,12 +113,11 @@ function extension(): DocumentPlayExtension | null {
 }
 
 /**
- * FLIP A DOCUMENT BETWEEN GAME AND MOVIE, and leave nothing running that the new mode has no
- * control for: a game playing when Movie is chosen is stopped (Movie has no Stop), and the
- * file's animation playing when Game is chosen is paused (Game has no Timeline).
+ * FLIP A DOCUMENT BETWEEN GAME AND ANIMATION. A running game keeps running when Animation is
+ * chosen: the animation editors then show what it animates. The file's animation playing in the
+ * Timeline when Game is chosen is paused (Game has no Timeline transport).
  */
 export function switchPlayMode(documentId: string, mode: ModelPlayMode): void {
-  if (mode === 'movie' && extension()?.playing(documentId)) extension()?.setPlaying(documentId, false);
   if (mode === 'game' && blenderSkin.transport?.snapshot().playbackState === 'playing') blenderSkin.transport.pause();
   setChosenPlayMode(documentId, mode);
 }
@@ -138,9 +138,9 @@ function verbDocument(args: Record<string, unknown> | undefined): string {
 function verbExtension(): DocumentPlayExtension & { transport: NonNullable<DocumentPlayExtension['transport']> } {
   const found = extension();
   if (found === null)
-    throw new Error('This project has no Play tool: `cyclotron add-play` adds @volter/editor-model-play.');
+    throw new Error('This project has no Play tool: `cyclotron add-play` adds @volter/play.');
   if (found.transport === undefined)
-    throw new Error('The installed Play tool has no pause, step, speed or restart; update @volter/editor-model-play.');
+    throw new Error('The installed Play tool has no pause, step, speed or restart; update @volter/play.');
   return found as DocumentPlayExtension & { transport: NonNullable<DocumentPlayExtension['transport']> };
 }
 
@@ -220,8 +220,9 @@ registerViewVerbs({
         const documentId = verbDocument(args);
         const mode = args?.['mode'] ?? args?.['to'];
         if (mode !== undefined) {
-          if (mode !== 'game' && mode !== 'movie') throw new Error(`mode is \`game\` or \`movie\`; got ${String(mode)}.`);
-          switchPlayMode(documentId, mode);
+          const asked = playModeOf(mode);
+          if (asked === null) throw new Error(`mode is \`game\` or \`animation\`; got ${String(mode)}.`);
+          switchPlayMode(documentId, asked);
         }
         return gameState(documentId);
       },
@@ -232,9 +233,9 @@ registerViewVerbs({
       run: (args) => { const documentId = verbDocument(args); switchPlayMode(documentId, 'game'); return gameState(documentId); },
     },
     {
-      id: 'movie-mode',
-      title: 'Game: Switch to Movie Mode',
-      run: (args) => { const documentId = verbDocument(args); switchPlayMode(documentId, 'movie'); return gameState(documentId); },
+      id: 'animation-mode',
+      title: 'Game: Switch to Animation Mode',
+      run: (args) => { const documentId = verbDocument(args); switchPlayMode(documentId, 'animation'); return gameState(documentId); },
     },
     {
       // PLAY IS GAME MODE'S CONTROL, so asking for it puts the document in Game mode: the person
@@ -326,7 +327,7 @@ registerViewVerbs({
         const found = verbExtension();
         const { transport } = found;
         if (transport.setAutoplay === undefined)
-          throw new Error('The installed Play tool has no autoplay; update @volter/editor-model-play.');
+          throw new Error('The installed Play tool has no autoplay; update @volter/play.');
         // Refused with the reason, stopped or no bot, as `play state`'s `autoplay.why` gives it.
         const why = on ? autoplayWhy(found.playing(documentId), transport.clock(documentId), transport.autoplay?.(documentId) ?? NO_BOT) : null;
         if (why !== null) throw new Error(why);
@@ -439,9 +440,9 @@ export function PlayModeSwitch({ title }: { readonly title: string }) {
     </GameButton>
   );
   return (
-    <div role="group" aria-label="Game or Movie mode" data-testid="model-play-mode" style={{ display: 'flex' }}>
-      {cell('game', 'Game', 'Game mode: this area is the Game panel, with Play, pause, step, speed, restart and autoplay')}
-      {cell('movie', 'Movie', 'Movie mode: this area is the Timeline, playing the file’s animation')}
+    <div role="group" aria-label="Game or Animation" data-testid="model-play-mode" style={{ display: 'flex' }}>
+      {cell('game', 'Game', 'Game: this area is the Game panel, with Play, pause, step, speed, restart and autoplay')}
+      {cell('animation', 'Animation', 'Animation: this area is Blender’s animation editors (Timeline, Action Editor, NLA); a running game keeps running and they show what it animates')}
     </div>
   );
 }

package/contributions/blender-header-menus.tsx

@@ -46,7 +46,7 @@
  * because switching modes swaps that area and nothing here.
  */
 
-import type { ToolNotice } from '@volter/editor-sdk/contributions';
+import type { ToolNotice } from '@volter/sdk/contributions';
 import {
   AnchoredMenu,
   EditorToolbar,
@@ -54,7 +54,7 @@ import {
   MenuSeparator,
   MenuSubmenu,
   MenuTrigger,
-} from '@volter/editor-sdk/widgets';
+} from '@volter/sdk/widgets';
 import { type ReactNode, type RefObject, useRef, useState, useSyncExternalStore } from 'react';
 import {
   type BlenderCreatableKind,

package/contributions/blender-icons.source.mjs

@@ -2507,7 +2507,7 @@ g(
  *    glyph — and an explicit site tone wins by contract. A tone there would
  *    never paint.
  */
-/** The union `IconCategoryTone` declares (`@volter/editor-sdk/looks`), and the
+/** The union `IconCategoryTone` declares (`@volter/sdk/looks`), and the
  *  reason `blender.style.ts` may narrow this JSON with an assertion: a tone
  *  outside it never reaches the artifact. */
 const TONES = ['object', 'modifier', 'material', 'tool', 'operator', 'data', 'scene', 'collection', 'select'];

package/contributions/blender-model-opening.tsx

@@ -1,8 +1,8 @@
 import type { ModelDocumentPreview } from '../src/model-document-preview';
 import { modelOpeningErrorMessage } from '../src/model-opening-error';
-import { Button, StateSurface, fontMono, fontSizeVar, spaceVar, themeVars } from '@volter/editor-sdk/widgets';
-import type { AuthoringAdapter, EditorNode } from '@volter/editor-project/adapter';
-import { AssetEditorSubject } from '@volter/editor-sdk/kit/components/AssetEditorShell';
+import { Button, StateSurface, fontMono, fontSizeVar, spaceVar, themeVars } from '@volter/sdk/widgets';
+import type { AuthoringAdapter, EditorNode } from '@volter/project/adapter';
+import { AssetEditorSubject } from '@volter/sdk/kit/components/AssetEditorShell';
 import { useMemo } from 'react';
 
 /** A loading/error surface has no authoring stage and publishes no model. */

package/contributions/blender-node-editor.document.tsx

@@ -38,7 +38,7 @@
  */
 
 import type { BlenderNode, BlenderNodeTree } from '@volter/blender-engine/browser/rna';
-import { registerViewVerbs } from '@volter/editor-sdk/views';
+import { registerViewVerbs } from '@volter/sdk/views';
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import {
   blenderNodeTree,

package/contributions/blender-outliner-authoring.ts

@@ -58,7 +58,7 @@
 
 import type { BlenderOutlinerRow } from '@volter/blender-engine/browser/rna';
 import type { ToolObject3DDocumentAuthoringFactory } from '@volter/editor-threejs/object3d-contributions';
-import { editorHost } from '@volter/editor-sdk/host';
+import { editorHost } from '@volter/sdk/host';
 import type {
   AuthoringAdapter,
   AuthoringCapabilities,
@@ -73,7 +73,7 @@ import type {
   Transform,
   TransformProvider,
   WriteAck,
-} from '@volter/editor-project/adapter';
+} from '@volter/project/adapter';
 import type * as THREE from 'three';
 import { threeObject } from '@volter/editor-threejs/adapter/three-contract';
 import { viewportStages } from '@volter/editor-threejs/viewport-door';
@@ -340,7 +340,7 @@ function blenderWorldMatrixRows(object: THREE.Object3D, root: THREE.Object3D): n
  * gesture that cannot complete (the shape B6 set for Set Origin ▸ Origin to 3D
  * Cursor). Blender's Image ▸ Reference/Background/Mesh Plane and Volume ▸
  * Import OpenVDB open a FILE BROWSER; this editor has no door to open one
- * through — `EditorHost.files` (`@volter/editor-sdk/host`) reads and writes
+ * through — `EditorHost.files` (`@volter/sdk/host`) reads and writes
  * project-relative paths and has no "pick a file" member at all — so those
  * rows carry {@link BlenderCreatableKind.refusal} instead. Measured at the
  * engine on 2026-09-21: `object.empty_image_add` answers "poll() failed,
@@ -383,7 +383,7 @@ export interface BlenderCreatableKind {
 function needsAFilePicker(what: string, blenderSaid: string): string {
   return (
     `${what} needs a file, and this editor has no door to ask for one: the host's file ` +
-    `door (\`EditorHost.files\`, \`@volter/editor-sdk/host\`) reads and writes ` +
+    `door (\`EditorHost.files\`, \`@volter/sdk/host\`) reads and writes ` +
     `project-relative paths and has no file-picker member, so there is nothing to open ` +
     `the workbench's own dialog through. Blender's row opens a file browser; run without ` +
     `one, the engine answers "${blenderSaid}".`

package/contributions/blender-outliner-model.ts

@@ -15,7 +15,7 @@
  */
 
 import type { BlenderOutlinerRow, BlenderOutlinerTree } from '@volter/blender-engine/browser/rna';
-import { editorHost } from '@volter/editor-sdk/host';
+import { editorHost } from '@volter/sdk/host';
 import type * as THREE from 'three';
 import {
   blenderOutliner,