@volter/editor-blender 0.1.128 → 0.1.130

package/contributions/blender-runtime.document.tsx

@@ -25,11 +25,14 @@
  */
 
 // How the `model` stage this document builds behaves (its starting presentation).
+import './blender-properties-context';
 import { blenderViewFieldOfView } from '../src/presentation';
 import {
   type BlenderRuntimeView,
   blenderModelView,
 } from '@volter/blender-engine/browser/three/blender-runtime-view';
+import { ownedSurfaceMaterial } from '@volter/blender-engine/browser/three/blender-physical-material';
+import { createBlenderDisplayTransform, type BlenderDisplayTransform } from '@volter/blender-engine/browser/three/blender-display-transform';
 import type { ToolContributionProps, ToolDocumentToolbar } from '@volter/editor-sdk/contributions';
 import { editorHost } from '@volter/editor-sdk/host';
 import {
@@ -72,6 +75,7 @@ import { BlenderObjectModeHeader } from './blender-header-menus';
 import { blenderOutlinerAuthoringFor, createBlenderOutlinerAuthoring } from './blender-outliner-authoring';
 import { blenderSkin } from './blender-runtime-skin';
 import { areaSplit, subscribeAreaSplit } from '../src/area-split';
+import { noteModelDocument } from '../src/play-mode';
 import { documentPlayExtension, subscribeDocumentPlayExtensions } from '@volter/editor-sdk/kit/document-play-extension';
 import { notifyWorkspaceDocumentSelectionChanged } from '@volter/editor-sdk/kit/workspace-document-registry';
 import {
@@ -90,6 +94,14 @@ import { stageStore, subscribeStageStores } from '@volter/editor-sdk/kit/stage-s
 import { surfaceAcceptsKey } from '@volter/editor-sdk/kit/surface-keyboard';
 import { BlenderModelOpening } from './blender-model-opening';
 import { modelOpeningErrorMessage } from '../src/model-opening-error';
+import { commandLine } from '@volter/editor-sdk/kit/product-command';
+import { fontSizeVar, spaceVar, themeVars } from '@volter/editor-sdk/widgets';
+import { clearStartupFailure, reportStartupFailure } from '@volter/editor-sdk/kit/startup-failure';
+
+/** This document's model open, as a source in the page's startup-failure registry. */
+const MODEL_OPEN_STARTUP_SOURCE = 'blender-model-open';
+/** How long "Opening model…" stands before the pane also says what it is waiting on. */
+const MODEL_OPEN_NOTE_AFTER_MS = 30_000;
 import {
   clearModelDocumentPreview,
   modelDocumentPreview,
@@ -98,6 +110,15 @@ import {
   type ModelDocumentPreview,
 } from '../src/model-document-preview';
 
+/** A detached copy's identity as a React key (the play area is keyed on the copy it draws). */
+const playCopyKeys = new WeakMap<object, number>();
+let nextPlayCopyKey = 0;
+function playCopyKey(copy: object): number {
+  let key = playCopyKeys.get(copy);
+  if (key === undefined) { key = ++nextPlayCopyKey; playCopyKeys.set(copy, key); }
+  return key;
+}
+
 /** The second areas' stage stores whose overlays have been opened off (`BlenderViewportArea`). */
 const overlaysOpened = new WeakSet<object>();
 
@@ -222,6 +243,8 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
   const entryId = document?.id;
   const key = JSON.stringify([documentId, entryId, blend]);
   const [opened, setOpened] = useState<{ key: string; error: string | null } | null>(null);
+  /** What a slow open is waiting on, once it has been slow (`MODEL_OPEN_NOTE_AFTER_MS`). */
+  const [stillOpening, setStillOpening] = useState<string | null>(null);
   const [attempt, setAttempt] = useState(0);
   const project = editorHost().projectLocalState.projectRootPath();
   const preview = useSyncExternalStore(subscribeModelDocumentPreview, () => modelDocumentPreview(project), () => null);
@@ -287,6 +310,7 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
     const unbind = bindModelDocument(binding);
     const publish = () => { unpublish = callbacks.current.publishContext?.(view); };
     setOpened(null);
+    setStillOpening(null);
     // Native focus can arrive after the contributed pane mounts. A declined
     // open is not an in-flight load: retry when the host activates this model,
     // rather than leaving "Opening model…" latched forever. Utility focus
@@ -294,18 +318,23 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
     const documents = editorHost().documents;
     let starting = false;
     let finished = false;
+    let declined = false;
+    const path = blend ?? 'the model';
     const open = async () => {
-      if (cancelled || starting || finished || (binding && !modelDocumentMayOpen(binding))) return;
+      if (cancelled || starting || finished) return;
+      if (binding && !modelDocumentMayOpen(binding)) { declined = true; return; }
       starting = true;
+      declined = false;
       try {
         if (binding) {
-          if (!await openModelDocumentBlend(binding, publish)) return;
+          if (!await openModelDocumentBlend(binding, publish)) { declined = true; return; }
         } else {
           // The standing Model document is the explicit blender-start target.
           publish();
         }
         if (!cancelled) {
           finished = true;
+          clearStartupFailure(MODEL_OPEN_STARTUP_SOURCE);
           setOpened({ key, error: null });
         }
       } catch (error) {
@@ -316,11 +345,29 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
         const detail = error instanceof Error ? error.message : String(error);
         setOpened({ key, error: detail });
         editorHost().console.error(detail, 'blender-open');
-        callbacks.current.notify?.({ tone: 'error', title: `Blender could not open ${blend ?? 'the model'}`, detail: modelOpeningErrorMessage(detail) });
+        callbacks.current.notify?.({ tone: 'error', title: `Blender could not open ${path}`, detail: modelOpeningErrorMessage(detail) });
+        // AND TO THE PRODUCT'S COVER, which is still up while the first model opens and
+        // would otherwise go on saying "Opening the first model…" over this pane's error
+        // until its own budget ran out. After the cover has lifted, this changes nothing.
+        reportStartupFailure(MODEL_OPEN_STARTUP_SOURCE, {
+          message: `Blender could not open ${path}: ${detail}`,
+          guidance: `${modelOpeningErrorMessage(detail)} Dismiss this to reach the model's Retry.`,
+          command: null,
+        });
       } finally {
         starting = false;
       }
     };
+    // A SLOW OPEN SAYS WHAT IT IS WAITING ON (2026-10-06 audit: "Opening model…" had no word
+    // past its spinner, and a declined open sat there indefinitely). It is progress, never an
+    // error, and it offers no Retry (#147 review): the open is still running, and a second one
+    // would queue behind it. A real failure arrives through the catch above.
+    const slow = setInterval(() => {
+      if (cancelled || finished) return;
+      setStillOpening(declined
+        ? `Still waiting: Blender is holding another model, and opens ${path} when it is free.`
+        : `Still opening ${path}: Blender is working (a large file, or a cold start). ${commandLine('status')} shows what it is busy with.`);
+    }, MODEL_OPEN_NOTE_AFTER_MS);
     // Opening publishes context to other React roots. Start outside this
     // effect (or a host activation listener's synchronous notification stack)
     // so those roots cannot synchronously commit through a pending commit here.
@@ -334,6 +381,7 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
     requestOpen();
     return () => {
       cancelled = true;
+      clearInterval(slow);
       unsubscribe();
       unpublish?.();
       unbind();
@@ -343,6 +391,7 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
   if (active === false || !documentId) return null;
   if (opened?.key !== key || opened.error) return <BlenderModelOpening
     documentId={documentId} path={blend ?? 'Model'} error={opened?.key === key ? opened.error : null} preview={preview}
+    note={stillOpening}
     retry={() => { setOpened(null); setAttempt(value => value + 1); }}
     returnToPreview={() => {
       if (!preview) return;
@@ -373,6 +422,10 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
  */
 function BlenderModelViewport(props: ToolContributionProps) {
   const { documentId } = props;
+  const blend = props.document?.source?.path;
+  // THE BOTTOM AREA SERVES THIS DOCUMENT while it is the model on screen (`../src/play-mode.ts`):
+  // the Game panel drives this id's run, and Game or Movie is chosen by this file's play script.
+  useEffect(() => (documentId ? noteModelDocument(documentId, blend) : undefined), [documentId, blend]);
   // Rendered areas and Play use the scene's display transform, just as a
   // photograph does. Solid keeps its studio transform. RNA also announces
   // colour settings that change without changing the presented geometry.
@@ -380,31 +433,62 @@ function BlenderModelViewport(props: ToolContributionProps) {
     if (!documentId) return;
     let cancelled = false;
     let revision = 0;
-    let applied: { mapper: string; exposure: number } | null = null;
+    let applied: { key: string; transform: BlenderDisplayTransform } | null = null;
+    const ids = [documentId, `${documentId}#area-2`, `${documentId}#play`];
+    const attach = () => {
+      for (const id of ids) object3DDocumentSession(id)?.setDisplayTransform(applied?.transform ?? null);
+    };
     const read = async () => {
       const mine = ++revision;
       const context = await blenderRnaContext();
       if (!context) return;
-      const settings = await blenderRna(`${context.scene}.view_settings`);
+      const [settings, displaySettings] = await Promise.all([
+        blenderRna(`${context.scene}.view_settings`),
+        blenderRna(`${context.scene}.display_settings`),
+      ]);
       if (cancelled || mine !== revision || settings?.kind !== 'struct' || settings.type !== 'ColorManagedViewSettings') return;
+      if (displaySettings?.kind === 'struct') {
+        const device = displaySettings.groups.flatMap(group => group.rows).find(row => row.identifier === 'display_device')?.value;
+        if (typeof device === 'string' && device !== 'sRGB')
+          throw new Error(`Blender display device ${device} has no browser display processor yet`);
+      }
       const rows = settings.groups.flatMap(group => group.rows);
       const transform = rows.find(row => row.identifier === 'view_transform')?.value;
       const stops = rows.find(row => row.identifier === 'exposure')?.value;
-      const mapper = transform === 'Standard' ? 'none' : transform === 'Filmic' ? 'filmic' : 'agx';
+      const look = rows.find(row => row.identifier === 'look')?.value;
+      const gamma = rows.find(row => row.identifier === 'gamma')?.value;
       const exposure = typeof stops === 'number' ? 2 ** stops : 1;
-      if (applied?.mapper === mapper && applied.exposure === exposure) return;
-      applied = { mapper, exposure };
-      for (const id of [documentId, `${documentId}#area-2`, `${documentId}#play`]) {
+      const display = {
+        transform: typeof transform === 'string' ? transform : 'AgX',
+        look: typeof look === 'string' ? look : 'None',
+        exposure, gamma: typeof gamma === 'number' ? gamma : 1,
+      };
+      const key = JSON.stringify(display);
+      if (applied?.key === key) return;
+      const resolved = await createBlenderDisplayTransform(display);
+      if (cancelled || mine !== revision) { resolved.dispose(); return; }
+      const previous = applied;
+      applied = { key, transform: resolved };
+      attach();
+      previous?.transform.dispose();
+      for (const id of ids) {
         setViewPresentation(id, { modes: {
-          rendered: { lighting: { tone: { mapper, exposure } } },
-          preview: { lighting: { tone: { mapper, exposure } } },
+          rendered: { lighting: { tone: { mapper: 'none', exposure: 1 } } },
+          preview: { lighting: { tone: { mapper: 'none', exposure: 1 } } },
         } });
       }
     };
     const update = () => { void read().catch(error => editorHost().console.error(String(error), 'blender-colour')); };
     const stopRna = subscribeBlenderRna(update);
+    const stopSessions = subscribeObject3DDocumentSessions(attach);
     update();
-    return () => { cancelled = true; stopRna(); };
+    return () => {
+      cancelled = true; stopRna(); stopSessions();
+      const previous = applied;
+      applied = null;
+      attach();
+      previous?.transform.dispose();
+    };
   }, [documentId]);
   const split = useSyncExternalStore(
     subscribeAreaSplit,
@@ -438,30 +522,121 @@ function BlenderModelViewport(props: ToolContributionProps) {
     () => null,
   );
   const [playedReady, setPlayedReady] = useState(false);
+  /**
+   * RESTART IS A NEW GENERATION OF THE SAME PLAY (`DocumentPlayTransport.generation`): the copy
+   * below is detached per generation, so a restart disposes the played copy and detaches a fresh
+   * one from the model, which never moved, while playing stays true throughout.
+   *
+   * THE OLD GAME STAYS ON SCREEN UNTIL THE NEW ONE HAS DRAWN. Between the two the new copy's
+   * stage is still preparing its rendered draw, and the model area is what lies under the play
+   * area — so a restart would flash the editing model between two games. The generation is
+   * therefore taken in two steps: a layout effect photographs the old play stage while it still
+   * stands (`capture`, the frame it draws) and only then moves `shownGeneration`, which is what
+   * detaches the new copy. The photograph covers the play area until the new runner's first
+   * frame (`onPlayReady`), the model area stays hidden throughout, and the old runner, no longer
+   * the current generation, stands still meanwhile (`play-script.ts`).
+   */
+  const generation = useSyncExternalStore(
+    subscribeDocumentPlayExtensions,
+    () => (documentId ? documentPlayExtension('model')?.transport?.generation(documentId) ?? 0 : 0),
+    () => 0,
+  );
+  const [shownGeneration, setShownGeneration] = useState(generation);
+  const [restartStill, setRestartStill] = useState<string | null>(null);
+  const restarting = useRef(false);
+  // A restarted game that has not drawn yet: its stage holds no game to photograph, so a second
+  // Restart in that window keeps the cover it has (or none) rather than photographing a blank.
+  const awaitingDraw = useRef(false);
+  useLayoutEffect(() => {
+    if (generation === shownGeneration) return;
+    if (playing && documentId) {
+      restarting.current = true;
+      if (!awaitingDraw.current) {
+        let still: string | null = null;
+        try { still = documentViewport(`${documentId}#play`)?.capture?.() ?? null; }
+        catch { /* No photograph: the new stage shows as it prepares, still never the model. */ }
+        setRestartStill(still);
+      }
+      awaitingDraw.current = true;
+    }
+    setShownGeneration(generation);
+  }, [generation, shownGeneration, playing, documentId]);
+  /**
+   * A RESTARTED GAME THAT FAILS never draws (its script did not start, or threw on its first
+   * update), so the cover would stand over it while the panel said Playing. The runner says so
+   * on the clock (`DocumentPlayClock.failure`); the cover drops and the stage shows what it has.
+   */
+  const transport = documentPlayExtension('model')?.transport;
+  const subscribeFailure = useCallback(
+    (listener: () => void) => transport?.subscribeClock(listener) ?? (() => {}),
+    [transport],
+  );
+  const failure = useSyncExternalStore(
+    subscribeFailure,
+    () => (documentId && transport ? transport.clock(documentId).failure ?? null : null),
+    () => null,
+  );
   useEffect(() => {
-    if (!playing || !documentId) return;
+    if (failure === null) return;
+    awaitingDraw.current = false;
+    setRestartStill(null);
+  }, [failure]);
+  /**
+   * COPIES A RESTART RETIRED, disposed only once the play area that drew them has unmounted:
+   * the commit that renders the new copy removes the old area first, and this runs after it.
+   * Disposed earlier, the old stage could draw a disposed copy for a frame.
+   */
+  const retired = useRef<ReturnType<AreaView['detach']>[]>([]);
+  useEffect(() => {
+    if (!playing || !documentId) { restarting.current = false; return; }
     const playId = `${documentId}#play`;
     // A game is seen as the render is: Rendered shading, chosen before the stage binds.
     setViewPresentation(playId, { drawMode: 'rendered' });
     const copy = view.detach();
-    setPlayedReady(false);
+    const restart = restarting.current;
+    restarting.current = false;
+    // A restart keeps the model area hidden: the old game's photograph stands in until ready.
+    if (!restart) setPlayedReady(false);
     setPlayed(copy);
-    // The stage's mode is PLAY for as long as the copy stands, so the keys are the player's.
-    view.setPlaying(true);
-    notifyWorkspaceDocumentSelectionChanged(documentId);
+    if (!restart) {
+      // The stage's mode is PLAY for as long as a copy stands, so the keys are the player's.
+      view.setPlaying(true);
+      notifyWorkspaceDocumentSelectionChanged(documentId);
+    }
     return () => {
-      setPlayed(null);
+      // Read at cleanup: the layout effect above has already marked a restart, whose new copy
+      // takes over in this same commit with the play mode unchanged.
+      if (restarting.current && documentPlayExtension('model')?.playing(documentId)) {
+        retired.current.push(copy);
+        return;
+      }
       copy.dispose();
+      for (const old of retired.current.splice(0)) old.dispose();
+      awaitingDraw.current = false;
+      setPlayed(null);
+      setRestartStill(null);
       view.setPlaying(false);
       notifyWorkspaceDocumentSelectionChanged(documentId);
     };
-  }, [playing, documentId]);
+  }, [playing, documentId, shownGeneration]);
+  useEffect(() => {
+    for (const old of retired.current.filter(one => one !== played)) old.dispose();
+    retired.current = retired.current.filter(one => one === played);
+  }, [played]);
+  // And whatever is still retired when the document itself goes (declared after the copy's own
+  // effect, so its cleanup has already handed over anything mid-restart).
+  useEffect(() => () => { for (const old of retired.current.splice(0)) old.dispose(); }, []);
   // The document closing or going inactive ends its game; a game never outlives its stage.
   useEffect(() => {
     if (!documentId) return;
     return () => documentPlayExtension('model')?.setPlaying(documentId, false);
   }, [documentId]);
   const game = playing ? played : null;
+  const playFrame = playAspect === null ? { position: 'absolute', inset: 0 } as const : {
+    position: 'absolute', left: '50%', top: '50%', transform: 'translate(-50%, -50%)',
+    width: `min(100cqw, calc(100cqh * ${playAspect}))`,
+    height: `min(100cqh, calc(100cqw / ${playAspect}))`,
+  } as const;
   useEffect(() => {
     if (!game || !documentId) return;
     const modelViewport = documentViewport(documentId);
@@ -481,22 +656,46 @@ function BlenderModelViewport(props: ToolContributionProps) {
   // Keep both authoring areas mounted across Play/Stop. Remounting a stage discards
   // its pose/session and repeats the second area's initial scene-camera setup.
   const area = { position: 'relative', flex: '1 1 0', minWidth: 0, margin: 12 } as const;
+  // THE HIDDEN MODEL AREA IS INERT, not merely `pointer-events: none`. It lies OVER the play
+  // area (z-index 2, faded out once the game has drawn), and the stage inside it sets its own
+  // `pointer-events: auto` (`StageHost`'s viewport box), which a parent's `none` does not reach:
+  // a real click on the game hit the invisible editing canvas, never the play surface, so the
+  // runner's takeover (`play-script.ts`, which asks whether the press landed in the game) never
+  // saw it and the game never got it — while keys, read off the window, took over fine. `inert`
+  // takes the whole subtree out of hit testing and focus.
+  const hidden = game !== null && playedReady;
   return (
     <div style={game || second ? { position: 'absolute', inset: -12, display: 'flex', gap: 2 } : { display: 'contents' }}>
-      <div key="model" style={game ? { position: 'absolute', inset: 12, zIndex: 2, opacity: playedReady ? 0 : 1, pointerEvents: playedReady ? 'none' : 'auto', transition: 'opacity 160ms ease-out' } : second ? area : { display: 'contents' }}>
+      <div key="model" inert={hidden || undefined} style={game ? { position: 'absolute', inset: 12, zIndex: 2, opacity: playedReady ? 0 : 1, pointerEvents: playedReady ? 'none' : 'auto', transition: 'opacity 160ms ease-out' } : second ? area : { display: 'contents' }}>
         <BlenderViewportArea {...props} view={view} main />
       </div>
       {game && (
-        <div key="play" style={{ position: 'absolute', inset: 12, containerType: 'size' }} data-testid="blender-play-area">
-          <div data-volter-play-frame style={playAspect === null ? { position: 'absolute', inset: 0 } : {
-            position: 'absolute', left: '50%', top: '50%', transform: 'translate(-50%, -50%)',
-            width: `min(100cqw, calc(100cqh * ${playAspect}))`,
-            height: `min(100cqh, calc(100cqw / ${playAspect}))`,
-          }}>
-          <BlenderViewportArea {...props} documentId={`${documentId}#play`} view={game.view} main={false} playing onPlayReady={() => setPlayedReady(true)} onPlayReturn={() => setPlayedReady(false)} />
+        // Keyed on the COPY, so a restart mounts a new stage and runner exactly when the new copy
+        // is the one rendered — never over the old, disposed one.
+        <div key={`play-${playCopyKey(game)}`} style={{ position: 'absolute', inset: 12, containerType: 'size' }} data-testid="blender-play-area">
+          <div data-volter-play-frame style={playFrame}>
+          <BlenderViewportArea {...props} documentId={`${documentId}#play`} view={game.view} main={false} playing
+            onPlayReady={() => { awaitingDraw.current = false; setPlayedReady(true); setRestartStill(null); }} onPlayReturn={() => setPlayedReady(false)} />
           </div>
         </div>
       )}
+      {game && failure !== null && (
+        // A PLAY WITH NO GAME, said over the area itself. When the script did not start (or the
+        // stage could not be prepared) the game never draws and the model area stays in front,
+        // so the area looked like plain editing while Play was on and the reason was a toast
+        // that had already gone (2026-10-06 audit). The Game panel says the same in its line.
+        <div key="play-failure" role="alert" data-testid="blender-play-failure"
+          style={{ position: 'absolute', left: 24, right: 24, top: 24, zIndex: 4, padding: `${spaceVar[2]} ${spaceVar[3]}`,
+            background: themeVars.surface.chrome, border: `1px solid ${themeVars.semantic.danger}`, borderRadius: themeVars.shape.small,
+            color: themeVars.content.primary, fontSize: fontSizeVar.sm, whiteSpace: 'pre-wrap', overflowWrap: 'anywhere', userSelect: 'text' }}>
+          <strong style={{ color: themeVars.semantic.danger }}>Play is not running.</strong> {failure} Restart (or save the script) to try again, or Stop.
+        </div>
+      )}
+      {game && restartStill !== null && (
+        <div key="restart-still" style={{ position: 'absolute', inset: 12, containerType: 'size', zIndex: 3, pointerEvents: 'none' }} data-testid="blender-play-restart-still">
+          <img alt="" src={restartStill} style={{ ...playFrame, display: 'block', objectFit: 'fill' }} />
+        </div>
+      )}
       {second && (
         <div key="second" style={{ ...area, visibility: game ? 'hidden' : undefined }} aria-hidden={game ? true : undefined} data-testid="blender-second-area">
           <BlenderViewportArea {...props} documentId={`${documentId}#area-2`} view={second.view} main={false} />
@@ -717,6 +916,7 @@ function BlenderViewportArea({
           camera: () => stage.rig().drawCamera(),
           editingCamera: () => viewportStages().find(one => one.documentId === modelId)?.rig().drawCamera() ?? stage.rig().drawCamera(),
           onFrame: (fn) => stage.onFrame(fn),
+          ownMaterial: (material) => ownedSurfaceMaterial(material as THREE.Material),
           report: (title, detail) => {
             editorHost().console.error(`${title}: ${detail}`, 'blender-play');
             notifyRef.current?.({ tone: 'error', title, detail });
@@ -724,8 +924,17 @@ function BlenderViewportArea({
         }) ?? null;
       }, error => {
         if (stopped) return;
-        editorHost().console.error(`Rendered stage preparation failed: ${String(error)}`, 'model-play');
-        documentPlayExtension('model')?.setPlaying(modelId, false);
+        const failure = `The game's stage could not be prepared for a rendered draw: ${error instanceof Error ? error.message : String(error)}`;
+        editorHost().console.error(failure, 'model-play');
+        // SAID WHERE THE PERSON IS LOOKING: on the run's clock, which the Game panel and the
+        // play area draw, and in the play log. Turning Play off (what this did until
+        // 2026-10-06) erased the only trace a person could have seen.
+        const extension = documentPlayExtension('model');
+        if (extension?.transport?.fail) extension.transport.fail(modelId, blend, failure);
+        else {
+          notifyRef.current?.({ tone: 'error', title: 'Play could not start', detail: failure });
+          extension?.setPlaying(modelId, false);
+        }
       });
     };
     start();

package/contributions/blender-timeline.document.tsx

@@ -67,6 +67,9 @@ import {
   timelineViewVersion,
 } from '../src/timeline-view-state';
 import { blenderSkin, blenderSkinVersion, subscribeBlenderSkin } from './blender-runtime-skin';
+import { BlenderGamePanel, GAME_PANEL_RATIO, PlayModeSwitch } from './blender-game-panel';
+import { setWorkspaceAreaRatio } from '@volter/editor-sdk/kit/workspace-areas';
+import { modelPlayMode, playModeVersion, servedModelDocument, subscribePlayMode } from '../src/play-mode';
 import {
   CHANNEL_HEIGHT,
   DIAMOND_RADIUS,
@@ -228,7 +231,7 @@ function report(): unknown {
  *  no mixer (`blender-runtime-skin.ts`), so the seek was a no-op and
  *  `report()` then answered `frame: 1` — the playhead's honest position and a
  *  complete lie about the gesture. Measured on walk 5 over a fresh
- *  `model-editor create` scaffold: `volter.timeline.frame {frame:120}` and
+ *  `cyclotron create` scaffold: `volter.timeline.frame {frame:120}` and
  *  `volter.timeline.jump-end` (frame 250) both answered `frame: 1`,
  *  `refusal: null`. This is the half of walk 4's W5 (#7740) that the header
  *  got and the VERBS did not — there the buttons were disabled wearing this
@@ -360,7 +363,32 @@ registerViewVerbs({
   ],
 });
 
-export default function BlenderTimeline() {
+/** This area's id in `model.layout.ts`, the one workspace that places this document. */
+const BOTTOM_AREA = 'timeline';
+
+/**
+ * THE BOTTOM AREA IS THE TIMELINE IN MOVIE MODE AND THE GAME PANEL IN GAME MODE
+ * (`../src/play-mode.ts`, for the model document on screen). Same area: the
+ * layout's `areas` entry names this document either way. NOT THE SAME SIZE:
+ * Blender's measured Timeline strip (`model.layout.ts`) left the Game panel's
+ * play log one clipped line, so Game mode asks the area for the panel's own
+ * share (`GAME_PANEL_RATIO`) and Movie mode hands Blender's back. Each switch
+ * stands the area up at its mode's size; a person's resize holds until the
+ * next switch. The Timeline unmounts in Game mode; a document that opens as a
+ * game therefore never pays for the rig bind (the cost note in
+ * `BlenderTimeline`), and one bound earlier keeps its bind, which the Timeline
+ * never undoes.
+ */
+export default function BlenderBottomArea() {
+  useSyncExternalStore(subscribePlayMode, playModeVersion, playModeVersion);
+  const documentId = servedModelDocument();
+  const game = documentId !== null && modelPlayMode(documentId) === 'game';
+  useEffect(() => setWorkspaceAreaRatio(BOTTOM_AREA, game ? GAME_PANEL_RATIO : null), [game]);
+  useEffect(() => () => setWorkspaceAreaRatio(BOTTOM_AREA, null), []);
+  return game ? <BlenderGamePanel /> : <BlenderTimeline />;
+}
+
+function BlenderTimeline() {
   // THE FRESHNESS IS THE RNA DOOR'S (ruling 3, 2026-09-19): every write and
   // every presented frame bumps it, which is exactly when a rig or an action
   // can have moved.
@@ -919,7 +947,9 @@ function TimelineHeader() {
         borderBottom: `1px solid ${TIMELINE_CHROME.rule}`,
       }}
     >
-      <span style={{ color: TIMELINE_CHROME.text }}>Timeline</span>
+      {/* GAME | MOVIE in place of the title, as in the Game panel, so the person switches back
+          from either (`blender-game-panel.tsx`); without a Play tool or a model, the title. */}
+      <PlayModeSwitch title="Timeline" />
       <TimelineViewMenu />
       {/* TWO SPACERS, which is what CENTRES the transport. Blender's Timeline
           header is three clusters: the menus at the leading edge, the

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

@@ -94,7 +94,7 @@ const REFUSALS = {
 
 /** THE VIEW'S VERBS, published once, here — U8's ruling 1 (2026-09-19). Under
  *  the Code-OSS frame each becomes a `volter.blender-uv-view.<verb>` command the
- *  bridge dispatches into the view, and standalone `volter-model-editor edit` reaches the
+ *  bridge dispatches into the view, and standalone `cyclotron edit` reaches the
  *  SAME table through the session. **This view adds no `blender-*` session
  *  verb at all**, which is exactly what the ruling asked the remaining I5
  *  views to stop paying for. */

package/contributions/model.layout.ts

@@ -49,5 +49,9 @@ export const layout: WorkspaceLayoutContribution = {
   // It is stated to four places because it is a measurement, not a preference;
   // the dock uses it once, to size the group the first time this workspace
   // stands up, and a capture of the settled grid wins afterwards.
+  //
+  // IN GAME MODE THE SAME AREA HOLDS THE GAME PANEL (`../src/play-mode.ts`):
+  // the document below draws the Timeline or the panel by the model's mode,
+  // so the area, its proportion and a person's resize all carry over.
   areas: [{ id: 'timeline', document: 'blender-timeline.document', place: 'below', ratio: 0.0719 }],
 };

package/contributions/models.finder.ts

@@ -25,13 +25,17 @@
  * This module is a plain object the HOST registers; it mounts no UI. It reads
  * the project only through `input.files` — the PATHS matching those globs.
  * Deliberately not `input.sources`: a `.blend` is binary, there is nothing in
- * it a text walk could honestly read, and the entry is the file itself.
+ * it a text walk could honestly read, and the entry is the file itself. It says
+ * so (`reads: 'files'`), and the host then lists the files without fetching them.
  */
 
 import { z } from 'zod';
 
 export const finder = {
   name: 'modelsFromBlendFiles',
+  // PATHS ONLY, so the host never fetches a `.blend` through its text-source route (a
+  // multi-megabyte binary there is a `413`, and nothing here would read the text).
+  reads: 'files',
   schema: z
     .object({
       finder: z.literal('modelsFromBlendFiles'),

package/contributions/properties-object.inspector.tsx

@@ -13,9 +13,10 @@
  * this tab shows, and our widgets draw them from the door's rows.
  *
  * WHAT THE TRANSCRIPTION DELIBERATELY DROPS:
- *  - the `poll`/`if` branches. `show_all_edges` is mesh-only in Python; here
+ *  - type-only `poll`/`if` branches. `show_all_edges` is mesh-only in Python; here
  *    it is simply not on a Camera's RNA, so it does not draw. Same outcome,
  *    from the datablock rather than from a copy of Blender's conditions.
+ *    Rotation mode is a value on every object, so its draw branch is retained.
  *  - `OBJECT_PT_context_object` (`bl_label = ""`) — the breadcrumb row, which
  *    is the host's identity row here.
  *  - the four panels whose datablock is NOT the object: Motion Paths reads
@@ -35,35 +36,33 @@ import type { BlenderCuratedPanel } from './blender-properties-view';
 /** `properties_object.py`, panel by panel. Line numbers are that file's. */
 const CURATED: readonly BlenderCuratedPanel[] = [
   {
-    // OBJECT_PT_transform, :36. Blender draws the rotation channel that
-    // `rotation_mode` selects; all three are listed, and the two the object is
-    // not in are still real RNA, so all three draw. That is MORE than Blender
-    // shows and it is the honest reading: the door reports what the object
-    // holds, and a quaternion object's euler is not a fiction.
+    // OBJECT_PT_transform, :36-83: only the current rotation channel, with
+    // lock toggles aligned beside its components and the Mode label.
     title: 'Transform',
     properties: [
-      'location',
-      'lock_location',
-      'rotation_quaternion',
-      'rotation_axis_angle',
-      'rotation_euler',
-      'lock_rotation_w',
-      'lock_rotation',
-      'rotation_mode',
-      'scale',
-      'lock_scale',
-    ],
-  },
-  {
-    // OBJECT_PT_delta_transform, :86.
-    title: 'Delta Transform',
-    closed: true,
-    properties: [
-      'delta_location',
-      'delta_rotation_quaternion',
-      'delta_rotation_euler',
-      'delta_scale',
+      { property: 'location', lock: 'lock_location' },
+      { property: 'rotation_quaternion', label: 'Rotation', lock: 'lock_rotation', firstLock: 'lock_rotation_w',
+        when: { property: 'rotation_mode', is: ['QUATERNION'] } },
+      { property: 'rotation_axis_angle', label: 'Rotation', lock: 'lock_rotation', firstLock: 'lock_rotation_w',
+        when: { property: 'rotation_mode', is: ['AXIS_ANGLE'] } },
+      { property: 'rotation_euler', label: 'Rotation', lock: 'lock_rotation',
+        when: { property: 'rotation_mode', isNot: ['QUATERNION', 'AXIS_ANGLE'] } },
+      { property: 'rotation_mode', label: 'Mode' },
+      { property: 'scale', lock: 'lock_scale' },
     ],
+    sub: [{
+      // OBJECT_PT_delta_transform, :86-107: a child of Transform, with no
+      // rotation field for AXIS_ANGLE, exactly as its draw branch specifies.
+      title: 'Delta Transform', closed: true,
+      properties: [
+        { property: 'delta_location', label: 'Location' },
+        { property: 'delta_rotation_quaternion', label: 'Rotation',
+          when: { property: 'rotation_mode', is: ['QUATERNION'] } },
+        { property: 'delta_rotation_euler', label: 'Rotation',
+          when: { property: 'rotation_mode', isNot: ['QUATERNION', 'AXIS_ANGLE'] } },
+        { property: 'delta_scale', label: 'Scale' },
+      ],
+    }],
   },
   {
     // OBJECT_PT_relations, :132.

package/contributions/properties-scene.inspector.tsx

@@ -35,13 +35,15 @@
  */
 import { blenderPropertiesTabMatch, blenderPropertiesTabSection } from './blender-properties-tab';
 import type { BlenderCuratedPanel } from './blender-properties-view';
+import { resolveBlenderSubject } from './blender-properties-model';
+import type { ToolContributionNode } from '@volter/editor-sdk/contributions';
 
 /** `properties_scene.py`, panel by panel. Line numbers are that file's. */
 const CURATED: readonly BlenderCuratedPanel[] = [
   {
     // SCENE_PT_scene, :49.
     title: 'Scene',
-    properties: ['camera', 'background_set', 'active_clip'],
+    properties: ['camera', 'background_set', { property: 'active_clip', label: 'Active Clip' }],
   },
   {
     // SCENE_PT_unit, :64 — `unit = scene.unit_settings` (:74).
@@ -64,7 +66,8 @@ const CURATED: readonly BlenderCuratedPanel[] = [
     // (`draw_header`, :307) and `gravity` its one row.
     title: 'Gravity',
     closed: true,
-    properties: ['use_gravity', 'gravity'],
+    headerProperty: 'use_gravity',
+    properties: ['gravity'],
   },
   {
     // SCENE_PT_simulation, :320.
@@ -170,5 +173,9 @@ export const order = 40;
  *  object group (Object … Material), then Texture. The presentation draws a
  *  separator wherever this changes. */
 export const railGroup = 'scene';
+/** buttons_context_compute falls back to SCENE when no object context exists.
+ * Keep the remembered tab when valid; otherwise use Blender's scene fallback. */
+export const railDefault = (node: ToolContributionNode | null, adapter: unknown): boolean =>
+  resolveBlenderSubject(node, adapter)?.kind === 'scene';
 export const match = blenderPropertiesTabMatch(TAB);
 export default blenderPropertiesTabSection(TAB);