@volter/editor-blender 0.1.150 → 0.1.152

package/contributions/blender-properties-view.tsx

@@ -1,50 +1,4 @@
-/**
- * THE GENERIC PROPERTIES VIEW — every `bl_rna` property of the active
- * datablock, drawn in OUR panels (WORK.md §Blender in the tab is Blender,
- * "Inspection parity", I1; ARCHITECTURE-CORE §Blender north star, "Inspection
- * parity, not editing parity"). Blender's UI layer is never run, ported or
- * recorded: what arrives is `session.py`'s RNA rows, and what is drawn here is
- * this file's own widgets.
- *
- * ## The geometry is Blender's SOURCE, not an eyedropper
- *
- * Every number below cites the file and constant it came from, read at the
- * engine's own pin (Blender 5.2.0, `fbe6228777e7`, `~/volter/blender-src`).
- * That is the rule as of 2026-09-19: a theme value or a metric traces to
- * `userdef_default_theme.c` / `interface_*.cc`, and a frame is what confirms
- * the result rather than what supplies the number.
- *
- *   UI_UNIT_Y            20  `UI_interface_c.hh:2346` (`U.widget_unit`, 1x)
- *   row gap               2  `interface_style.cc:110`  (`buttonspacey`)
- *   label column        40%  `interface_layout.cc:79`  (UI_ITEM_PROP_SEP_DIVIDE)
- *   label alignment   right  `interface_layout.cc:3394` (LayoutAlign::Right)
- *   panel header         25  `interface_intern.hh:152` (PNL_HEADER = 1.25 UI_UNIT_Y)
- *   panel label x        20  `interface_panel.cc:1054` (UI_UNIT_X * 1.0)
- *   sub-panel indent     14  `interface_panel.cc:1058` (+0.7 UI_UNIT_X)
- *   panel padding         8  `interface_style.cc:111`  (`panelspace`)
- *   panel radius          4  `interface_panel.cc:1103` (panel_roundness 0.4 x unit x 0.5)
- *   widget radius   0.2 x h  `interface_widgets.cc` widget_radius_from_rcti,
- *                            `userdef_default_theme.c:100` wcol_num.roundness
- *   text margin           8  `interface_intern.hh:1503` (UI_TEXT_MARGIN_X 0.4 x unit)
- *   font                 11  `UI_interface_c.hh:425` (UI_DEFAULT_TEXT_POINTS)
- *   read-only alpha     0.5  `interface_widgets.cc` widget_alpha_factor /
- *                            widget_color_disabled — EVERY widget colour at
- *                            half alpha, which is why a read-only row here is
- *                            DIMMED rather than a disabled control.
- *
- * Colours, from `release/datafiles/userdef/userdef_default_theme.c`:
- *   panel header/back  #3d3d3d  :281,:282   sub-panel back  #0000001f  :283
- *   panel outline    #ffffff11  :284        panel title     #e6e6e6    :285
- *   widget inner       #545454  :95         widget outline  #3d3d3d    :93
- *   widget text        #e6e6e6  :98         number slider   #4772b3    :97
- *   checkbox mark      #ffffff  :77 (wcol_option.item)
- *
- * The values are literal rather than `var(--volter-…)` because the palette is
- * the FRAME's grading (U8/U9) and eyedropped: `blender.palette.json` carries
- * `surface.panel` #2f2f2f where the source says `.space_properties.back` is
- * #303030, and `content.primary` #e5e5e5 against `.text` #e6e6e6. Where a
- * token and the source agree, the token is used.
- */
+
 
 import type {
   BlenderRnaCollectionValue,
@@ -54,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,
@@ -84,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
@@ -98,25 +52,7 @@ const TRIANGLE_GAP = 6;
  *  is 0.2 for every widget this view draws. */
 const widgetRadius = (height: number) => Math.round(height * 0.2);
 
-/**
- * WHAT BLENDER DRAWS NOWHERE, WE DRAW NOWHERE — RNA's own `PROP_HIDDEN`
- * (`BlenderRnaRow.hidden`, `rna_rna.cc:795-799`). The door reports the whole
- * surface and this is the one place it is narrowed, so "hidden" stays
- * Blender's answer rather than a list of ours.
- *
- * AND THE SECOND RULE, ruled on after I2 measured it: UNDRAWN STATE
- * (`BlenderRnaRow.undrawn`). The `PROP_HIDDEN` flag above does NOT cover a
- * modifier's panel-open booleans (`open_advanced_panel` and its siblings) —
- * there is not one `PROP_HIDDEN` in the whole of `rna_modifier.cc`, because
- * `rna_def_modifier_panel_open_prop` (`rna_modifier.cc:2694-2705`) sets
- * `PROP_NO_DEG_UPDATE` and an sdna bit and no flag. What RNA does say is that
- * they carry no `RNA_def_property_ui_text` at all, so
- * `rna_define.cc:1311-1312`'s definition-time defaults still stand: `name`
- * equal to the identifier, `description` empty. A property Blender never gave
- * UI text to is a property Blender never meant to draw, and the generic view
- * omits it here for exactly the same reason it omits a hidden one. The
- * curated lists need no change: `bl_ui` names none of them.
- */
+/** Omit RNA rows marked hidden or undrawn. Undrawn properties have no UI text; curated lists do not name them either. */
 const shown = (rows: readonly BlenderRnaRow[]): readonly BlenderRnaRow[] =>
   rows.filter((row) => row.hidden !== true && row.undrawn !== true);
 
@@ -130,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,
@@ -235,12 +179,7 @@ function Row({
 }) {
   return (
     <div
-      // WHAT THIS ROW IS, published so it can be READ. The rail is a VS Code
-      // view (`editor-document-probe.ts` scope `'rail'`), and before these
-      // three attributes a reading of it could recover a label only as the
-      // row's text and could not say which RNA property that label belonged
-      // to or whether the field was writable. They change nothing about what
-      // is drawn.
+      // Publish the RNA property identity and writability for the rail’s document probe.
       data-rna-field={identifier ?? ''}
       data-field-label={label}
       data-field-readonly={readonly ? 'true' : undefined}
@@ -446,7 +385,7 @@ function colourBytes(values: readonly number[], gamma: boolean): [number, number
   return [byte(0), byte(1), byte(2)];
 }
 
-function colourOf(values: readonly number[], gamma = false): string {
+function colourOf(values: readonly number[], gamma: boolean): string {
   const [r, g, b] = colourBytes(values, gamma);
   return `rgb(${r}, ${g}, ${b})`;
 }
@@ -523,11 +462,10 @@ function StringWidget({ row, write }: WidgetProps) {
   );
 }
 
-/** A COLOR subtype is a swatch, not three numbers — `PropertyRNA.subtype` is
- *  exactly what says so, and it is why the door carries `subtype` at all. */
 /** BLENDER'S COLOUR FIELD: the whole-width swatch, and a click opens a picker under it
  *  (`ui_block_colorpicker`); the colour is written when the pick ends, one step, as Blender's
- *  popup pushes one undo when it closes. */
+ *  popup pushes one undo when it closes. `PropertyRNA.subtype` selects this swatch
+ *  presentation for COLOR values instead of separate numeric fields. */
 function ColourWidget({ row, write }: WidgetProps) {
   const values = (row.value as readonly number[] | null) ?? [];
   const gamma = row.subtype === 'COLOR_GAMMA';
@@ -566,23 +504,7 @@ function ColourWidget({ row, write }: WidgetProps) {
   );
 }
 
-/** Blender stacks an array's components as their own rows, labelled by
- *  `RNA_property_array_item_char` (X/Y/Z/W) and numbered past four.
- *
- *  A BOOLEAN ARRAY IS AN ARRAY, and that is why this function dispatches on
- *  the element type rather than being numeric-only. `Object.lock_location` is
- *  three booleans, and Blender draws all three: `properties_object.py:49`
- *  (`OBJECT_PT_transform`) is `row.prop(ob, "lock_location", text="",
- *  emboss=False, icon='DECORATE_UNLOCKED')` — a whole-array `prop()` beside
- *  the location vector, which Blender's layout engine expands into one lock
- *  toggle per component, stacked alongside the three number fields (the same
- *  shape at `:59`/`:74` for `lock_rotation` and `:83` for `lock_scale`).
- *  Measured 2026-09-21 in the rail before this: `lock_location` fell to the
- *  single-checkbox arm of {@link widgetFor}, so ONE unchecked box stood for
- *  three values — and its write was `setattr(ob, "lock_location", true)`, a
- *  scalar into a three-element array, which is a refusal rather than the lock
- *  the person asked for. Each toggle here writes its own index (the door's
- *  `index` argument, `session.py::rna_set`'s `getattr(target, id)[index]`). */
+/** Draw array elements as separate rows using RNA component labels. Boolean arrays write an individual index through rna_set, just as numeric arrays do. */
 function ArrayRows({ row, path, label, title, write, locks }: WidgetProps & {
   label: string; title: string;
   locks?: readonly { row: BlenderRnaRow; index?: number }[] | undefined;
@@ -793,27 +715,7 @@ function CollectionRow({
 
 // ---- the curated body ------------------------------------------------------
 
-/**
- * ONE OF BLENDER'S OWN PANELS, as data.
- *
- * A tab module declares a list of these and the view draws them ABOVE the
- * generic RNA view, which stays beneath under "All properties". The list is a
- * transcription of the matching `scripts/startup/bl_ui/properties_*.py`:
- * `bl_label` is the title, each `layout.prop(ob, "x")` is an entry of
- * {@link properties} IN BLENDER'S ORDER, and a `bl_parent_id` panel is a
- * {@link sub}. Blender's UI layer is never run, ported or recorded
- * (ARCHITECTURE-CORE §Blender north star) — the Python file is read as the
- * SPECIFICATION of which properties this tab shows and in what order, and
- * what draws them is this file's own widgets over the RNA door's rows.
- *
- * WHAT IS DELIBERATELY NOT TRANSCRIBED: the `poll`/`if` conditions Blender's
- * draw functions carry. A `properties_object.py` panel hides
- * `show_all_edges` for a non-mesh by branching in Python; here the property is
- * simply NOT ON the datablock RNA answered with, so it does not render and
- * the panel header says how many of Blender's it found. That is the same
- * outcome by a mechanism that cannot go stale — a transcribed condition is a
- * copy of Blender's logic, which is the one thing the ruling forbids.
- */
+
 /**
  * ONE ENTRY OF A PANEL'S PROPERTY LIST.
  *
@@ -924,19 +826,7 @@ export interface BlenderCuratedPanel {
   readonly active?: keyof BlenderRnaContext;
 }
 
-/**
- * WHICH MEMBER OF THIS COLLECTION THE CONTEXT CALLS ACTIVE — by address when
- * RNA gives the member one, and by INDEX when it does not.
- *
- * The index half is not a convenience, it is the only answer for two of the
- * three lists that need one, and the live walk is what said so (2026-09-19):
- * a `VertexGroup` has no `path_from_id()` at all — I1 recorded that — so
- * `activeVertexGroup` carries only its index, and `activeMaterial` carries the
- * MATERIAL's address while the list being drawn is of material SLOTS, so its
- * path never matches a row. Both marked nothing. `rna_context` reports
- * `index` for exactly those two (`session.py::rna_context`), which is what
- * Blender's own `template_list` highlights by.
- */
+/** Resolve active collection members by RNA address or index. Vertex groups have no path_from_id and material context names a material rather than its slot, so both use the context’s index. */
 function activeMember(panel: BlenderCuratedPanel): { path: string | null; index: number | null } {
   if (panel.active === undefined) return { path: null, index: null };
   const handle = blenderPropertiesState().context?.[panel.active];
@@ -963,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
@@ -988,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}
@@ -1010,20 +896,18 @@ function CuratedCollectionPanel({
 function CuratedRows({
   path,
   properties,
-  andDeclared = false,
+  andDeclared,
   onOpen,
 }: {
   readonly path: string;
   readonly properties: readonly BlenderCuratedProperty[];
-  readonly andDeclared?: boolean;
+  readonly andDeclared: boolean;
   readonly onOpen: (path: string) => void;
 }) {
   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
@@ -1142,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;
@@ -1170,12 +1052,7 @@ function CuratedPanel({
         <PropertyRow key={item.identifier} row={item.row} path={item.path} onOpen={onOpen}
           label={item.label} locks={item.locks} />
       ))}
-      {/* KEYED BY POSITION, NOT BY TITLE: Blender ships two panels with the
-          same `bl_label` under different engines and expects the poll to pick
-          one — Render's "Sampling" (EEVEE `:675`, Workbench `:1004`) and
-          "Film" (`:757`, `:1025`), View Layer's "Data" (`:111`, `:137`). A
-          title key made those React duplicates, which the live walk found by
-          name ("Encountered two children with the same key"). */}
+      {/* Key by position: engine-specific panels can share a title. */}
       {sub.map((child, index) => (
         <CuratedPanel key={`${index}:${child.title}`} panel={child} paths={paths} onOpen={onOpen} />
       ))}
@@ -1195,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} />
             )}
@@ -1240,27 +1109,18 @@ function DatablockView({
 
 // ---- the section body ------------------------------------------------------
 
-/**
- * ONE PROPERTIES TAB'S BODY. `tabId` names the tab this section IS; the
- * context door says which datablocks that tab shows and in what order
- * (`session.py::rna_context`, mirrored from `buttons_context.cc`).
- *
- * A pointer row DRILLS: clicking it replaces the shown datablock with the
- * target, and the breadcrumb walks back. That is the "pointer → the target's
- * name as a link that changes the active datablock" half of I1, and it is what
- * makes `object.data.materials[0].node_tree` reachable with no per-tab code.
- */
+/** One Properties tab body over the datablocks and ordering returned by rna_context. Pointer rows drill into a target datablock and breadcrumbs return to the parent. */
 export function BlenderPropertiesSection({
   tabId,
   subject,
-  curated = [],
+  curated,
 }: {
   readonly tabId: string;
   readonly subject: BlenderSubject;
   /** Blender's own panels for this tab, in Blender's order
    *  ({@link BlenderCuratedPanel}). Empty — the tab has not been curated yet —
    *  and the generic view is the whole body, uncollapsed. */
-  readonly curated?: readonly BlenderCuratedPanel[];
+  readonly curated: readonly BlenderCuratedPanel[];
 }) {
   useBlenderProperties();
   useEffect(() => showBlenderSubject(subject), [subject]);
@@ -1276,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]);

package/contributions/blender-remedy.ts

@@ -0,0 +1,14 @@
+/**
+ * WHAT TO DO ABOUT WHAT PLAYS ONLY IN BLENDER, said after a warning that names it, by the Timeline
+ * (`blender-runtime-skin.ts`). Pure: it reads no Blender host.
+ */
+export function remedy(unsupported: readonly string[]): string {
+  const out: string[] = [];
+  if (unsupported.some((thing) => thing.includes(' constraint ') || thing.includes('drivers')))
+    out.push('Bake a constraint or driver into the action (Pose ▸ Animation ▸ Bake Action, Visual Keying), or aim with a Damped Track.');
+  if (unsupported.some((thing) => thing.includes('curves on ')))
+    out.push("Key the motion on a bone (the root bone) instead of the armature object, or move the object from the game.");
+  if (unsupported.some((thing) => thing.includes('interpolation') || thing.includes(' modifier')))
+    out.push('Use Bezier, Linear or Constant keys and the Cycles modifier only, or bake the curves (Key ▸ Bake Keyframes).');
+  return out.length ? ` ${out.join(' ')}` : '';
+}