@volter/editor-blender 0.1.151 → 0.1.153

package/contributions/blender-model-opening.tsx

@@ -1,16 +1,16 @@
 import type { ModelDocumentPreview } from '../src/model-document-preview';
 import { modelOpeningErrorMessage } from '../src/model-opening-error';
-import { Button, StateSurface, fontMono, fontSizeVar, spaceVar, themeVars } from '@volter/sdk/widgets';
+import { Button, EditorBanner, StateSurface, themeVars } from '@volter/sdk/widgets';
 import type { AuthoringAdapter, EditorNode } from '@volter/project/adapter';
 import { AssetEditorSubject } from '@volter/sdk/components/AssetEditorShell';
-import { useEffect, useMemo, useState } from 'react';
+import { useMemo } from 'react';
 
-/** How long an open may run before the surface says it may have stalled and offers a retry. A
- *  limited view's first open downloads the engine and the project, so this is generous. */
-const STALL_AFTER_MS = 180_000;
-
-/** A loading/error surface has no authoring stage and publishes no model. */
-export function BlenderModelOpening({ documentId, path, error, preview, retry, returnToPreview, preparingView = false, note = null }: {
+/**
+ * A model that is not open yet: its empty frame while it opens (the previous model's last view,
+ * when there is one), and what failed once it has failed. Its wait is the document's
+ * (`blender-runtime.document.tsx`). It has no authoring stage and publishes no model.
+ */
+export function BlenderModelOpening({ documentId, path, error, preview, retry, returnToPreview, preparingView = false }: {
   readonly documentId: string;
   readonly path: string;
   readonly error: string | null;
@@ -18,63 +18,37 @@ export function BlenderModelOpening({ documentId, path, error, preview, retry, r
   readonly retry: () => void;
   readonly returnToPreview: () => void;
   readonly preparingView?: boolean;
-  /** What a slow open is waiting on — progress beside the spinner, not an error. */
-  readonly note?: string | null;
 }) {
-  const title = error ? 'Could not open model' : preparingView ? 'Preparing model view' : 'Opening model';
-  // A stalled open offers the same retry as an error.
-  const [startedAt] = useState(() => Date.now());
-  const [now, setNow] = useState(() => Date.now());
-  useEffect(() => {
-    if (error) return;
-    const timer = setInterval(() => setNow(Date.now()), 5_000);
-    return () => clearInterval(timer);
-  }, [error]);
-  const waited = now - startedAt;
-  const stalled = !error && waited >= STALL_AFTER_MS;
   // This document has not published an authoring stage yet. Its panels still
   // belong to it, rather than the empty project's "Declare a root" fallback.
   // A boundary row is informational; no old model objects remain editable.
+  const label = error ? 'Could not open model' : path;
   const adapter = useMemo<AuthoringAdapter>(() => {
-    const node: EditorNode = { id: `opening:${documentId}`, label: title, secondaryLabel: path,
+    const node: EditorNode = { id: `opening:${documentId}`, label, ...(error ? { secondaryLabel: path } : {}),
       role: 'boundary', kind: 'object', parentId: null, childIds: [] };
     return { capabilities: { transform: false, inspectorFields: false, persist: false },
       hierarchy: { roots: () => [node], node: id => id === node.id ? node : null },
       subscribe: () => () => {} };
-  }, [documentId, path, title]);
+  }, [documentId, error, label, path]);
   return (
     <div data-testid="blender-model-opening" aria-busy={!error}
-      style={{ position: 'absolute', inset: 0, overflow: 'auto', background: themeVars.surface.panel, color: themeVars.content.primary }}>
-      {!preparingView && <AssetEditorSubject key={title} documentId={documentId} type="Model" title={path}
-        status={error ? modelOpeningErrorMessage(error) : title}
+      style={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', background: themeVars.surface.panel }}>
+      {!preparingView && <AssetEditorSubject documentId={documentId} type="Model" title={path}
+        status={error ? modelOpeningErrorMessage(error) : undefined}
         selection={() => ({ adapter, nodeId: null })} />}
-      {preview && <img src={preview.image} alt={`Last view of ${preview.path}`} draggable={false}
-        style={{ position: 'absolute', inset: 0, width: '100%', height: '100%', objectFit: 'contain', pointerEvents: 'none' }} />}
-      <div style={{ position: 'relative', minHeight: '100%', display: 'flex', flexDirection: 'column', justifyContent: preview ? 'flex-end' : 'center', alignItems: preview ? 'flex-start' : 'center', boxSizing: 'border-box', padding: spaceVar[8], gap: spaceVar[4] }}>
-        {preview && <div style={{ padding: `${spaceVar[2]} ${spaceVar[4]}`, background: themeVars.surface.chrome, border: `1px solid ${themeVars.boundary.default}`, borderRadius: themeVars.shape.small, maxWidth: '100%', overflowWrap: 'anywhere' }}>
-          Previous model: {preview.path} · Preview only
-        </div>}
-        <StateSurface tone={error ? 'error' : 'loading'}
-          style={{ width: 'min(100%, 32rem)', background: themeVars.surface.chrome, border: `1px solid ${themeVars.boundary.default}`, borderRadius: themeVars.shape.small, overflowWrap: 'anywhere' }}
-          title={<span style={{ fontSize: fontSizeVar.lg }}>{title}</span>}
-          description={<>
-            <div style={{ color: themeVars.content.primary, marginBottom: spaceVar[3] }}>{path}</div>
-            {error ? modelOpeningErrorMessage(error) : preparingView ? 'The file is open. Preparing its viewport.' : preview ? 'The previous model stays visible while this file opens.' : 'Preparing Blender and opening this file. The model will appear here when it is ready.'}
-            {/* Show the exact cause as selectable text where the person is looking. */}
-            {stalled && <div data-testid="blender-model-opening-stalled" style={{ marginTop: spaceVar[3], color: themeVars.content.primary }}>
-              Still opening after {Math.floor(waited / 60_000)} minutes. It may have stalled: retry opening, or reload the page.
-            </div>}
-            {!error && note && <div data-testid="blender-model-opening-note" style={{ marginTop: spaceVar[3], color: themeVars.content.muted, userSelect: 'text' }}>{note}</div>}
-            {error && <div data-testid="blender-model-opening-detail"
-              style={{ marginTop: spaceVar[3], fontFamily: fontMono, fontSize: fontSizeVar.sm, color: themeVars.content.muted, whiteSpace: 'pre-wrap', userSelect: 'text', textAlign: 'left' }}>
-              {error}
-            </div>}
-          </>}
-          action={error || stalled ? <div style={{ display: 'flex', flexWrap: 'wrap', justifyContent: 'center', gap: spaceVar[3] }}>
+      {preview && <EditorBanner tone="info">Previous model: {preview.path} · Preview only</EditorBanner>}
+      <div style={{ position: 'relative', flex: 1, minHeight: 0 }}>
+        {preview && <img src={preview.image} alt={`Last view of ${preview.path}`} draggable={false}
+          style={{ position: 'absolute', inset: 0, width: '100%', height: '100%', objectFit: 'contain', pointerEvents: 'none' }} />}
+        {error && <StateSurface tone="error" fill data-testid="blender-model-opening-error"
+          title="Could not open model"
+          description={<>{path}<br />{modelOpeningErrorMessage(error)}</>}
+          detail={error}
+          action={<>
             {preview && <Button onClick={returnToPreview}>Return to previous model</Button>}
             <Button variant="secondary" onClick={retry}>Retry opening</Button>
-          </div> : <progress aria-label={`Opening ${path}`} style={{ width: 'min(100%, 18rem)', accentColor: themeVars.accent.default }} />}
-        />
+          </>}
+        />}
       </div>
     </div>
   );

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

@@ -2,6 +2,7 @@
 
 import type { BlenderNode, BlenderNodeTree } from '@volter/blender-engine/browser/rna';
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { StateSurface } from '@volter/sdk/widgets';
 import {
   blenderNodeTree,
   blenderRnaVersion,
@@ -1181,7 +1182,7 @@ function NodePanel({
     >
       <div style={{ opacity: 0.6, marginBottom: 'var(--volter-space-2)' }}>Node</div>
       {!node ? (
-        <div style={{ opacity: 0.5 }}>No node looked at.</div>
+        <StateSurface inline title="No node looked at." />
       ) : (
         <>
           <Row label="Name" value={node.name} onRefuse={onRefuse} />

package/contributions/blender-play-area.tsx

@@ -1,6 +1,6 @@
-/** The bottom area shows animation editors or the model Play tool’s Panel. PlayModeSwitch stays in the header of either view, and exists only with a Play tool and model. Each switch applies the mode’s area ratio; the person’s sash resize holds between switches. */
+/** The bottom area shows the Play tool’s Panel, or below a model its animation editors. PlayModeSwitch stays in the header of either view, and exists only with a Play tool and a model in front. Each switch applies the mode’s area ratio; the person’s sash resize holds between switches. */
 import { type MouseEvent, type ReactNode, useSyncExternalStore } from 'react';
-import { modelPlayExtension, subscribeModelPlayExtension } from '../src/model-play-extension';
+import { playTool, subscribePlayTool } from '../src/play-tool';
 import { blenderSkin } from './blender-runtime-skin';
 import { type ModelPlayMode, modelPlayMode, playModeVersion, servedModelDocument, setChosenPlayMode, subscribePlayMode } from '../src/play-mode';
 import { TIMELINE_CHROME, TIMELINE_THEME } from './blender-timeline-geometry';
@@ -8,7 +8,6 @@ import { TIMELINE_CHROME, TIMELINE_THEME } from './blender-timeline-geometry';
 /** Reserve 20% of the column for the Game panel; the person can resize its sash. */
 export const PLAY_PANEL_RATIO = 0.2;
 
-const extension = () => modelPlayExtension();
 
 /**
  * FLIP A DOCUMENT BETWEEN GAME AND ANIMATION. A running game keeps running when Animation is
@@ -76,7 +75,7 @@ export function PlayAreaButton({ label, testId, disabled, pressed, wide, onClick
  */
 export function PlayModeSwitch({ title }: { readonly title: string }) {
   useSyncExternalStore(subscribePlayMode, playModeVersion, playModeVersion);
-  const found = useSyncExternalStore(subscribeModelPlayExtension, extension, () => null);
+  const found = useSyncExternalStore(subscribePlayTool, playTool, () => null);
   const documentId = servedModelDocument();
   if (found === null || documentId === null) return <span style={{ color: TIMELINE_CHROME.text }}>{title}</span>;
   const mode = modelPlayMode(documentId);

package/contributions/blender-properties-model.ts

@@ -8,9 +8,12 @@ import {
   blenderRna,
   blenderRnaContext,
   blenderRnaSet,
+  blenderModelChanging,
+  blenderModelConflict,
   blenderSessionStarted,
   noteBlenderRnaChanged,
   subscribeBlenderRna,
+  subscribeBlenderStarting,
 } from '../host/blender-runtime-host';
 import { blenderOutlinerState } from './blender-outliner-model';
 
@@ -143,6 +146,8 @@ let contextRequest = 0;
 /** Views read at the current generation. A held view outside this set is
  *  STALE: still shown, re-read on the next ask. */
 const fresh = new Set<string>();
+/** Paths Blender answered with nothing at the current generation: it holds no model. */
+const answeredNothing = new Set<string>();
 
 function publish(next: Partial<BlenderPropertiesState>, tabsMayHaveChanged = false): void {
   state = { ...state, ...next };
@@ -179,6 +184,7 @@ function onEngineMoved(): void {
   readGeneration += 1;
   inFlight.clear();
   fresh.clear();
+  answeredNothing.clear();
   if (subject !== null) scheduleContextRead(subject, true);
   else publish({});
 }
@@ -229,6 +235,7 @@ async function readContext(key: string, refresh = false): Promise<void> {
     readGeneration += 1;
     inFlight.clear();
     fresh.clear();
+    answeredNothing.clear();
   }
   const generation = readGeneration;
   const request = ++contextRequest;
@@ -247,6 +254,18 @@ async function readContext(key: string, refresh = false): Promise<void> {
     publish({ context, loading: false, error: null }, true);
   } catch (error) {
     if (generation !== readGeneration || request !== contextRequest) return;
+    if (blenderModelChanging()) {
+      // Refused while Blender changes its model (a switch): still reading, and read again once the
+      // change is over, when the tabs ask for their subject again.
+      readFor = null;
+      publish({ loading: true, error: null });
+      const stop = subscribeBlenderStarting(() => {
+        if (blenderModelChanging()) return;
+        stop();
+        publish({}, true);
+      });
+      return;
+    }
     publish({ context: null, loading: false, error: describe(error) }, true);
   }
 }
@@ -279,7 +298,11 @@ export function blenderRnaViewFor(path: string): BlenderRnaView | undefined {
       if (generation !== readGeneration) return;
       inFlight.delete(path);
       fresh.add(path);
-      if (view === null) return;
+      if (view === null) {
+        answeredNothing.add(path);
+        publish({});
+        return;
+      }
       const views = new Map(state.views);
       views.set(path, view);
       publish({ views, error: null });
@@ -287,11 +310,30 @@ export function blenderRnaViewFor(path: string): BlenderRnaView | undefined {
     .catch((error: unknown) => {
       if (generation !== readGeneration) return;
       inFlight.delete(path);
+      // Refused while Blender changes its model (a switch): the read waits for it and is asked again
+      // once the change is over (`subscribeBlenderRnaAvailability`), rather than failing.
+      if (blenderModelChanging()) return;
       publish({ error: describe(error) });
     });
   return held;
 }
 
+/** Why `path` cannot be read, in a person's words, or null while its read may still come: Blender is on another
+ *  document than the editor shows, or holds no model, or answered nothing for it. While Blender starts or changes its
+ *  model (a switch) the read waits. Its section says the reason rather than waiting on a read that will not come. */
+export function blenderRnaUnavailable(path: string): string | null {
+  if (state.views.get(path) !== undefined || blenderModelChanging()) return null;
+  const conflict = blenderModelConflict();
+  if (conflict !== null) return conflict;
+  if (!blenderSessionStarted() || answeredNothing.has(path)) return `Blender holds no model, so ${path} cannot be read.`;
+  return null;
+}
+
+/** Hear when what {@link blenderRnaUnavailable} answers may have changed. */
+export function subscribeBlenderRnaAvailability(listener: () => void): () => void {
+  return subscribeBlenderStarting(listener);
+}
+
 /**
  * WRITE ONE PROPERTY. The engine refuses a read-only one by name and this
  * surfaces that refusal verbatim; a successful write presents, and the frame
@@ -309,6 +351,7 @@ export async function writeBlenderRnaProperty(
     // The write presented; a re-read of this one datablock closes the loop
     // even if the frame listener has not been taken yet.
     fresh.delete(path);
+    answeredNothing.delete(path);
     publish({ error: null });
     return true;
   } catch (error) {

package/contributions/blender-properties-view.tsx

@@ -8,12 +8,15 @@ import type {
   BlenderRnaView,
 } from '@volter/blender-engine/browser/rna';
 import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { Progress } from '@volter/sdk/progress';
 import { faLock, faLockOpen } from '@fortawesome/free-solid-svg-icons';
-import { ColorPicker, EditorIcon, hexToRgb, parseAlpha, toHex } from '@volter/sdk/widgets';
+import { ColorPicker, EditorIcon, hexToRgb, parseAlpha, StateSurface, toHex } from '@volter/sdk/widgets';
 import {
   type BlenderSubject,
   blenderPropertiesState,
   blenderPropertiesVersion,
+  blenderRnaUnavailable,
+  subscribeBlenderRnaAvailability,
   blenderRnaViewFor,
   showBlenderSubject,
   subscribeBlenderProperties,
@@ -38,9 +41,6 @@ const SUB_PANEL_BACK = 'rgba(0,0,0,0.12)';
 const WIDGET_INNER = '#545454';
 const WIDGET_OUTLINE = '#3d3d3d';
 const WIDGET_ITEM = '#4772b3';
-/** `wcol_state.error` (`userdef_default_theme.c:234`) — the ink Blender puts
- *  on a widget whose state is an error. The door's refusals are drawn in it. */
-const ERROR_INK = '#991616';
 /** The collapse triangle's optical size and the gap after it. Blender draws
  *  the triangle as an icon inside `panel_label_offset`'s UI_UNIT_X lead-in
  *  (`interface_panel.cc:1049-1060`) rather than as text; 8 is that mark's
@@ -66,6 +66,14 @@ export function useBlenderProperties() {
 
 // ---- Blender's panel -------------------------------------------------------
 
+/** A datablock still being read: the Properties view's wait, or, when Blender holds no model to
+ *  read it from, that failure said in its place. */
+function Reading({ path }: { readonly path: string }) {
+  const unavailable = useSyncExternalStore(subscribeBlenderRnaAvailability, () => blenderRnaUnavailable(path), () => null);
+  if (unavailable !== null) return <StateSurface inline tone="error" title={unavailable} />;
+  return <Progress view="properties" title={"Reading " + path} />;
+}
+
 function Panel({
   title,
   sub = false,
@@ -845,21 +853,19 @@ function CuratedCollectionPanel({
   if (view === undefined)
     return (
       <Panel title={panel.title} closed={panel.closed === true}>
-        <div style={{ color: INK, opacity: READONLY_ALPHA, fontSize: FONT }}>Reading {path}…</div>
+        <Reading path={path} />
       </Panel>
     );
   if (view.kind !== 'collection')
     return (
       <Panel title={panel.title} closed={panel.closed === true} note={path}>
-        <div style={{ color: ERROR_INK, fontSize: FONT }}>
-          {path} is not a collection — this panel is declared `collection: true`.
-        </div>
+        <StateSurface inline tone="error" title={<>{path} is not a collection — this panel is declared <code>collection: true</code>.</>} />
       </Panel>
     );
   return (
     <Panel title={panel.title} closed={panel.closed === true} note={path} count={view.count}>
       {view.items.length === 0 ? (
-        <div style={{ color: INK, opacity: READONLY_ALPHA, fontSize: FONT }}>None</div>
+        <StateSurface inline title="None" />
       ) : null}
       {view.items.map((item, index) => (
         <Panel
@@ -870,9 +876,7 @@ function CuratedCollectionPanel({
           sub
         >
           {item.path === null ? (
-            <div style={{ color: INK, opacity: READONLY_ALPHA, fontSize: FONT }}>
-              {item.type} — RNA gives this member no address.
-            </div>
+            <StateSurface inline title={<>{item.type} — RNA gives this member no address.</>} />
           ) : (
             <CuratedRows
               path={item.path}
@@ -903,9 +907,7 @@ function CuratedRows({
   useBlenderProperties();
   const view = blenderRnaViewFor(path);
   if (view === undefined)
-    return (
-      <div style={{ color: INK, opacity: READONLY_ALPHA, fontSize: FONT }}>Reading {path}…</div>
-    );
+    return <Reading path={path} />;
   const rows = view.kind === 'struct' ? view.groups.flatMap((group) => group.rows) : [];
   const byIdentifier = new Map(rows.map((row) => [row.identifier, row]));
   // A collection member is addressed by its own path, so a qualified entry is
@@ -1024,9 +1026,7 @@ function CuratedPanel({
   if (view === undefined)
     return (
       <Panel title={panel.title} closed={panel.closed === true}>
-        <div style={{ color: INK, opacity: READONLY_ALPHA, fontSize: FONT }}>
-          Reading {entry.path}…
-        </div>
+        <Reading path={entry.path} />
       </Panel>
     );
   if (found.length === 0 && sub.length === 0) return null;
@@ -1072,25 +1072,17 @@ function DatablockView({
   useBlenderProperties();
   const view: BlenderRnaView | undefined = blenderRnaViewFor(path);
   if (view === undefined)
-    return (
-      <div style={{ color: INK, opacity: READONLY_ALPHA, fontSize: FONT, padding: PANEL_PAD }}>
-        Reading {path}…
-      </div>
-    );
+    return <Reading path={path} />;
   if (view.kind === 'collection')
     return (
       <>
         {view.items.length === 0 ? (
-          <div style={{ color: INK, opacity: READONLY_ALPHA, fontSize: FONT }}>
-            {view.count === 0 ? 'None' : `${view.count} items`}
-          </div>
+          <StateSurface inline title={view.count === 0 ? 'None' : <>{view.count} items</>} />
         ) : null}
         {view.items.map((item) => (
           <Panel key={item.path ?? item.name ?? item.type} title={item.name ?? item.type} sub>
             {item.path === null ? (
-              <div style={{ color: INK, opacity: READONLY_ALPHA, fontSize: FONT }}>
-                {item.type} — RNA gives this member no address.
-              </div>
+              <StateSurface inline title={<>{item.type} — RNA gives this member no address.</>} />
             ) : (
               <DatablockView path={item.path} onOpen={onOpen} />
             )}
@@ -1144,13 +1136,11 @@ export function BlenderPropertiesSection({
 
   if (state.error !== null)
     return (
-      <div style={{ color: ERROR_INK, fontSize: FONT, padding: PANEL_PAD }}>{state.error}</div>
+      <StateSurface inline tone="error" title="Blender did not answer for these properties" detail={state.error} />
     );
   if (tab === null)
-    return (
-      <div style={{ color: INK, opacity: READONLY_ALPHA, fontSize: FONT, padding: PANEL_PAD }}>
-        {state.loading ? 'Reading the engine…' : 'Blender shows no properties here.'}
-      </div>
+    return state.loading ? <Progress view="properties" title="Reading the engine" /> : (
+      <StateSurface inline title="Blender shows no properties here." />
     );
 
   const open = (path: string) => setDrill((held) => [...held, path]);