@volter/editor-blender 0.1.150 → 0.1.151

package/contributions/blender-properties-tab.tsx

@@ -1,39 +1,4 @@
-/**
- * ONE PROPERTIES TAB IS ONE `selection.inspector` CONTRIBUTION — the factory
- * every `properties-*.inspector.tsx` in this package is built from (WORK.md
- * §Blender in the tab is Blender, "Inspection parity", I1, item 3).
- *
- * WHY A TAB IS A SECTION, and not a rail of our own: under the `properties`
- * presentation the inspector's sections ARE the vertical icon rail, 1:1
- * (`packages/sdk/src/kit/components/InspectionProjection.tsx`,
- * `PropertiesColumn`). So the way to make Blender's tab rail appear is to
- * contribute Blender's tabs as sections — which is also exactly the shape I2
- * needs, because each of these modules then grows a CURATED body over the same
- * door while the generic view stays beneath it.
- *
- * WHICH TABS STAND is `buttons_context.cc`'s answer, computed in the engine
- * (`session.py::rna_context`) and read here. Two kinds of tab:
- *
- *  - `standing: 'any' | 'object'` — a tab `buttons_context.cc` builds a path
- *    to UNCONDITIONALLY given a scene (`buttons_context_path_scene`,
- *    `_view_layer`, `_world`) or given an object at all
- *    (`buttons_context_path_object`, of which only the OBJECT tab is standing
- *    here — Physics and Constraints share that path but are context-gated,
- *    because Blender's Properties editor follows the ACTIVE OBJECT rather
- *    than the row that was clicked, and only the door knows there is one).
- *    These match from the SELECTION alone, synchronously.
- *  - everything else — Modifiers (an object type set), Particles (a mesh),
- *    Object Data (the object has data), Bone (an active bone), Material,
- *    Collection, Texture — which only the engine can answer, so they match
- *    against the context the door last returned.
- *
- * THE STANDING TABS EXIST SO THE RAIL IS NEVER EMPTY: `match()` is
- * synchronous and the first composition has read nothing, so if every tab
- * waited on the door there would be no rail at all. The READ itself is driven
- * from `match` (see the note there), and when its answer lands it calls
- * `documents.contextChanged`, which re-derives the whole inspection and brings
- * the rest of the rail in.
- */
+/** Build one selection.inspector contribution per Blender Properties tab. Standing scene/object tabs match synchronously; context-dependent tabs use the engine’s answer. Matchers drive the shared read, whose publication recomposes the rail; only the active tab mounts its body. */
 
 import type {
   ToolContributionNode,
@@ -52,11 +17,7 @@ export interface BlenderPropertiesTab {
   /** Whether this tab needs the engine's answer to exist, or stands on the
    *  selection alone — see the header. */
   readonly standing?: 'any' | 'object';
-  /** BLENDER'S OWN PANELS for this tab, in Blender's order, transcribed from
-   *  the matching `scripts/startup/bl_ui/properties_*.py`
-   *  ({@link BlenderCuratedPanel}). The generic RNA view stays beneath them
-   *  under "All properties"; a tab that declares none is the generic view
-   *  alone, which is what I1 shipped. */
+  /** Curated panels follow Blender’s panel order. The generic RNA view remains beneath them under All properties. */
   readonly curated?: readonly BlenderCuratedPanel[];
 }
 
@@ -64,15 +25,7 @@ export function blenderPropertiesTabMatch(tab: BlenderPropertiesTab) {
   return (node: ToolContributionNode | null, adapter: unknown): boolean => {
     const subject = resolveBlenderSubject(node, adapter);
     if (subject === null) return false;
-    // THE READ IS DRIVEN FROM `match`, NOT FROM A BODY, and that is a
-    // correction the live walk forced: under the `properties` presentation
-    // the host mounts ONLY THE ACTIVE TAB's body, so a read driven from a
-    // body never happened at all unless the person had already clicked a
-    // Blender tab — the rail showed the standing tabs and nothing else, for
-    // good (measured 2026-09-19). A matcher runs on every composition,
-    // active tab or not, so this is the one place that always sees the
-    // subject. It is idempotent by construction: `showBlenderSubject`
-    // returns immediately unless the subject moved.
+    // Drive the idempotent subject read from match, which runs for every composition even when this tab’s body is unmounted.
     showBlenderSubject(subject);
     if (tab.standing === 'any') return true;
     if (tab.standing === 'object') return subject.kind === 'object';

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,
@@ -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);
 
@@ -235,12 +171,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 +377,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 +454,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 +496,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 +707,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 +818,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];
@@ -1010,12 +892,12 @@ 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();
@@ -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} />
       ))}
@@ -1240,27 +1117,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]);

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(' ')}` : '';
+}