@volter/editor-blender 0.1.150 → 0.1.152

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

@@ -1,49 +1,11 @@
-/**
- * THE NODE EDITOR — Blender's Shader Editor, READ-ONLY, over the active
- * material's RNA node tree (WORK.md §Blender in the tab is Blender,
- * "Inspection parity", I5; ARCHITECTURE-CORE §Blender north star).
- *
- * OUR PANEL, BLENDER'S DRAWING. Blender's own UI layer — `bl_ui`, the node
- * editor's C++ drawing code — is never run, ported as a UI system, or
- * recorded here. It is READ as the specification of what to draw, and every
- * number it specifies lives in `./blender-node-geometry.ts` with its file and
- * line beside it. This module is an ordinary React component over that data.
- *
- * INSPECTION PARITY, NOT EDITING PARITY. Nothing here writes. A gesture that
- * WOULD edit — dragging a node, dragging a link, typing into a socket's value
- * — is refused BY NAME in the frame's status line rather than quietly doing
- * nothing, which is the ruling's own "never a silent degrade". The only state
- * this view owns is INSPECTION state: which node is looked at, and where the
- * view is panned. Selecting a node here does not write `Node.select` in the
- * engine (that would be a mutation the document saves); the ENGINE's own
- * selection is still drawn, in Blender's own selected outline.
- *
- * WHY SVG AND NOT CANVAS 2D. The tree is a few dozen rounded rects, circles
- * and cubics, and SVG gives three things a 2D context would have to
- * reimplement: the browser's own `C` path segment for `node_link_bezier`'s
- * cubic, real text layout and measurement for the header labels, and hit
- * testing for free on every node and socket. The measured tree this unit was
- * built against is 2 nodes and 37 sockets; a pathological 200-node tree is
- * ~1,200 elements, which is inside what a browser lays out in one frame. The
- * moment a tree is measured slow, the answer is a canvas with the same
- * geometry module behind it — which is why the geometry lives in its own
- * module and this file holds no constants.
- *
- * WHY IT IS THE DRAWER AND NOT A SECOND DOCUMENT. Blender's Shading workspace
- * puts the Shader Editor in the AREA BELOW the 3D viewport, and this host's
- * bottom group (`volter:bottom-center`) is that area: the Model workspace hides
- * it for exactly this reason, recorded in `workspace-regions.ts` — "Blender's
- * modeling workspace has no timeline strip". The Shading workspace shows it
- * and puts this in it.
- */
+
 
 import type { BlenderNode, BlenderNodeTree } from '@volter/blender-engine/browser/rna';
-import { registerViewVerbs } from '@volter/sdk/views';
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { StateSurface } from '@volter/sdk/widgets';
 import {
   blenderNodeTree,
   blenderRnaVersion,
-  NODE_VIEW_VERBS,
   subscribeBlenderRna,
 } from '../host/blender-runtime-host';
 import type { NodeViewTransform } from '../src/node-view-state';
@@ -107,26 +69,7 @@ export const point = 'workspace.document';
  *  the editor-type menu): "Shader Editor" for a `ShaderNodeTree`. */
 export const title = 'Shader Editor';
 
-// THE VIEW'S PRODUCT DOOR (WORK.md §The core is Code-OSS U8, ruling 1). This
-// view's verbs are published ONCE, here, where the view itself is contributed:
-// under the Code-OSS frame each becomes a `volter.blender-node-view.<verb>`
-// command the bridge dispatches into the view, and standalone `cyclotron edit` —
-// which has no command service — reaches the SAME table through the session's
-// `blender-node-view` verb. One table, two doors, which is why the remaining
-// read-only editors (UV Editing, Animation, Texture Paint) add no session verb
-// of their own: they register here instead.
-// THIS LINE RUNS ONCE PER EVALUATION, and a contribution is evaluated more
-// than once per session by design — the tool loader imports it as
-// `?t=<version>`, so a save re-evaluates it against a registry that already
-// holds the view. `registerViewVerbs` recognises the re-evaluation and the
-// newer table wins; measured live 2026-09-19, before it did, the first reload
-// threw and the loader reported "editor app failed to start", taking the whole
-// editor down with the view.
-registerViewVerbs(NODE_VIEW_VERBS);
-
-/** The N-panel's width. `bl_ui` sizes a sidebar in `UI_UNIT_X`; the node
- *  editor's sidebar opens at the region default, measured in Blender 5.2 at
- *  ~16 units. */
+/** The node sidebar opens at about 16 UI_UNIT_X units in Blender 5.2. */
 const SIDEBAR_WIDTH = 16 * 20;
 
 /** One unit of tree space per CSS px is Blender's zoom 1 — the node editor
@@ -137,23 +80,13 @@ const ZOOM_MAX = 4;
 type View = NodeViewTransform;
 
 export default function BlenderNodeEditor() {
-  // THE TREE'S FRESHNESS IS THE TREE'S, NOT THE PRESENTED FRAME'S (ruling 3,
-  // 2026-09-19). This used to read the properties model's version, which moves
-  // on a presented frame — and collapsing a socket panel writes
-  // `Node.panel_states[n].is_collapsed`, which presents NOTHING, so the view
-  // kept drawing the old tree until the document was reopened (measured by the
-  // socket-panel step that shipped the panels). `blenderRnaVersion` is the RNA
-  // door's own, bumped by the write, and a frame bumps it too.
+  // Use the RNA door’s version: every write and presented frame bumps it, including panel-state writes that change no rendered geometry.
   const version = useSyncExternalStore(subscribeBlenderRna, blenderRnaVersion, blenderRnaVersion);
   const [tree, setTree] = useState<BlenderNodeTree | null>(null);
   const [error, setError] = useState<string | null>(null);
   const canvas = useRef<HTMLDivElement | null>(null);
   const framed = useRef(false);
-  // THE VIEW'S STATE IS THE STORE'S (`../src/node-view-state.ts`), not this
-  // component's, because the session verb `blender-node-view` has to reach it:
-  // `editor.document.*` is scoped to the active CENTER document and a drawer
-  // utility is not one, so a `useState` here would be a surface nothing in the
-  // product could read or drive.
+  // Share view state with the blender-node-view command through node-view-state.ts.
   useSyncExternalStore(subscribeNodeView, nodeViewVersion, nodeViewVersion);
   const { transform: view, looked, refusal, size } = nodeViewState();
   const setView = useCallback((next: View | ((current: View) => View)): void => {
@@ -272,7 +205,7 @@ export default function BlenderNodeEditor() {
     // `VIEW2D_OT_pan`, bound to `MIDDLEMOUSE` in the default keymap).
     if (event.button !== 1) return;
     event.preventDefault();
-    (event.target as Element).setPointerCapture?.(event.pointerId);
+    (event.target as Element).setPointerCapture(event.pointerId);
     panning.current = { x: event.clientX, y: event.clientY, cx: view.cx, cy: view.cy };
   };
   const onPointerMove = (event: React.PointerEvent<SVGSVGElement>) => {
@@ -310,11 +243,7 @@ export default function BlenderNodeEditor() {
     >
       <div style={{ display: 'flex', flexDirection: 'column', flex: 1, minWidth: 0, minHeight: 0 }}>
         <NodeEditorHeader tree={tree} zoom={view.zoom} onViewAll={viewAll} onRefuse={refuse} />
-        {/* THE CANVAS BOX. Its height comes from FLEX, never from its own
-            content: a `height: 100%` SVG inside an auto-height parent makes
-            the parent's height a function of the SVG's, which is a function
-            of the parent's — measured live 2026-09-19, that loop settled at
-            ~30 px and drew the whole tree in a sliver at 31 % zoom. */}
+        {/* Flex supplies the canvas height; a percentage-height SVG inside an auto-height parent would size the parent from its own content. */}
         <div ref={canvas} style={{ position: 'relative', flex: 1, minHeight: 0 }}>
           <svg
             role="presentation"
@@ -383,8 +312,6 @@ interface LaidLink {
   readonly key: string;
   readonly from: readonly [number, number];
   readonly to: readonly [number, number];
-  readonly fromColor: string;
-  readonly toColor: string;
   readonly muted: boolean;
   readonly valid: boolean;
 }
@@ -419,7 +346,6 @@ function layoutTree(tree: BlenderNodeTree | null): {
   const placed = new Map<string, LaidOutNode>();
   const entries = tree.nodes.map((node): LaidEntry => {
     const flat = {
-      name: node.name,
       location: node.location,
       width: node.width,
       collapsed: node.collapsed,
@@ -469,9 +395,8 @@ function layoutTree(tree: BlenderNodeTree | null): {
     return { node, laid, panels: [], fallback: null, approximate: false };
   });
   const links: LaidLink[] = tree.links.flatMap((link, index) => {
-    const from = placed.get(link.fromNode);
-    const to = placed.get(link.toNode);
-    if (!from || !to) return [];
+    const from = placed.get(link.fromNode)!;
+    const to = placed.get(link.toNode)!;
     const fromSocket = from.sockets.find((s) => s.output && s.identifier === link.fromSocket);
     const toSocket = to.sockets.find((s) => !s.output && s.identifier === link.toSocket);
     if (!fromSocket || !toSocket) return [];
@@ -480,8 +405,6 @@ function layoutTree(tree: BlenderNodeTree | null): {
         key: `${link.fromNode}.${link.fromSocket}→${link.toNode}.${link.toSocket}#${index}`,
         from: [fromSocket.x, fromSocket.y] as const,
         to: [toSocket.x, toSocket.y] as const,
-        fromColor: socketColor(fromSocket.type),
-        toColor: socketColor(toSocket.type),
         muted: link.muted,
         valid: link.valid,
       },
@@ -837,11 +760,7 @@ function PanelHeader({
   );
 }
 
-/** Blender's socket mark: a 10×10 box (radius `NODE_SOCKSIZE`) in the socket
- *  TYPE's colour with a 1 px `TH_WIRE` outline, shaped by `display_shape`
- *  (`node_draw.cc:1824-1857`; the shapes themselves are SDFs in
- *  `gpu_shader_2D_node_socket*.glsl`, which is outside the sparse checkout —
- *  the silhouettes below are drawn from the enum's own names). */
+/** Socket marks use Blender's type colours, TH_WIRE outlines and display_shape silhouettes. */
 function Socket({
   socket,
   node,
@@ -925,12 +844,8 @@ function Socket({
  * `:529`), which is why an output's name is right-aligned against the node's
  * edge and an input's widget fills the row.
  *
- * WHY THE WIDGET IS DRAWN HERE AND NOT BORROWED FROM THE PROPERTIES RAIL.
- * This surface is a ZOOMING tree-space canvas: a DOM control would need a
- * `foreignObject` per socket and would not scale with the view transform, so
- * it would stop being the same drawing at any zoom but 1. The Properties
- * rail's widgets are reused where they belong — the N-panel, which is
- * ordinary unzoomed DOM.
+ * SVG widgets use the node canvas's tree-space transform. The N-panel uses
+ * ordinary unzoomed DOM controls.
  */
 function SocketRow({
   socket,
@@ -965,6 +880,7 @@ function SocketRow({
   }
 
   const isColour = Array.isArray(socket.value) && socket.value.length >= 3;
+  const fraction = sliderFraction(socket);
   return (
     <g
       onPointerDown={(event) => {
@@ -989,15 +905,8 @@ function SocketRow({
         fill="#545454"
         transform="scale(1 -1)"
       />
-      {/* THE SLIDER'S FILL. A scalar socket with a bounded SOFT range is drawn
-          by Blender as `UI_BTYPE_NUM_SLIDER`, whose back is filled to the
-          value's proportion of that range (`widget_numslider`,
-          `interface_widgets.cc`) — which is why Roughness at 0.5 reads as
-          half-filled at a glance and ours read as a text box (sighted read,
-          2026-09-20). No range means no fill, which is also what Blender does
-          for an unbounded number. The fill is clipped to the field's own
-          rounded rect so a full-value slider does not square off its corners. */}
-      {sliderFraction(socket) !== null && (
+      {/* A bounded scalar socket fills its rounded field to its fraction of the soft range (widget_numslider). Unbounded values have no fill. */}
+      {fraction !== null && (
         <>
           <clipPath id={`sl-${socket.identifier}`}>
             <rect
@@ -1011,7 +920,7 @@ function SocketRow({
           <rect
             x={left}
             y={centre - NODE_DY / 2 + 1}
-            width={(right - left) * (sliderFraction(socket) ?? 0)}
+            width={(right - left) * fraction}
             height={NODE_DY - 2}
             fill={NODE_THEME.sliderFill}
             clipPath={`url(#sl-${socket.identifier})`}
@@ -1037,7 +946,7 @@ function SocketRow({
           width={30}
           height={NODE_DY - 6}
           rx={2}
-          fill={rgbFloatsToHex(socket.value as readonly number[])}
+          fill={rgbFloatsToHex(socket.value as unknown as readonly [number, number, number, ...number[]])}
           transform="scale(1 -1)"
         />
       ) : (
@@ -1059,15 +968,14 @@ function SocketRow({
 }
 
 /**
- * How far along its soft range a scalar socket sits, or `null` when it is not
- * a slider at all. Blender's own test is the property's soft range being
- * bounded (`ui_but_is_slider` → `UI_BTYPE_NUM_SLIDER`); the engine reports the
- * pair only for a bounded scalar, so the presence of the pair IS the test.
+ * A scalar factor socket's fraction of its soft range, or null without a
+ * numeric value and range. The engine reports only finite, increasing soft
+ * ranges for factor scalars.
  */
 function sliderFraction(socket: LaidOutSocket): number | null {
   const { softMin, softMax, value } = socket;
   if (softMin === undefined || softMax === undefined) return null;
-  if (typeof value !== 'number' || softMax <= softMin) return null;
+  if (typeof value !== 'number') return null;
   return Math.min(1, Math.max(0, (value - softMin) / (softMax - softMin)));
 }
 
@@ -1104,10 +1012,8 @@ function Noodle({ link }: { readonly link: LaidLink }) {
   );
 }
 
-/** A frame: its own colour at `TH_NODE_FRAME`'s alpha, radius `BASIS_RAD` with
- *  no 0.5 padding (`frame_node_draw_background`, `node_draw.cc:3749-3772`),
- *  and a centred label `0.5 * margin_top + 0.35 * label_size` below the top
- *  (`node_draw.cc:3474-3484, 3699-3703`). */
+/** A frame with its own colour at TH_NODE_FRAME's alpha, BASIS_RAD corners and
+ *  a centred 20-pixel label 25 tree units below the top. */
 function FrameNode({ node, laid }: { readonly node: BlenderNode; readonly laid: LaidOutNode }) {
   const height = Math.max(laid.yTop - laid.yBottom, FRAME_MARGIN * 2);
   return (
@@ -1140,21 +1046,7 @@ function FrameNode({ node, laid }: { readonly node: BlenderNode; readonly laid:
 
 /* -------------------------------------------------------------------------- */
 
-/**
- * THE HEADER, per `bl_ui/space_node.py:41-260` — read as a specification and
- * drawn READ-ONLY, which is where it diverges from Blender by design: a
- * control that would WRITE is drawn as what it reads and refuses the click by
- * name. What the shader path's header carries, in order: the tree-type well
- * (`template_header`, `:55`), the shader-type selector (`snode.shader_type`,
- * `:62`), the material slot popover and the material ID (`:79-93`), the pin
- * (`:222-224`), the breadcrumb parent (`:228-230`), snapping
- * (`tool_settings.use_snap_node`, `:249-252`) and the overlays popover
- * (`:254-260`).
- *
- * There is deliberately NO "Use Nodes" checkbox: measured in the source, 5.2
- * draws it only for Line Style (`:119`) and Texture (`:133`) trees, never for
- * a material's.
- */
+/** Read-only tree/material labels, zoom and View All; Use Nodes reports its write refusal. */
 function NodeEditorHeader({
   tree,
   zoom,
@@ -1213,20 +1105,7 @@ function NodeEditorHeader({
   );
 }
 
-/**
- * THE STATUS LINE — where a refusal lands, and where anything this view
- * cannot draw is named rather than silently skipped.
- *
- * THE PANEL GAP IS CLOSED, and what is left of it is stated here rather than
- * hidden. A node's socket-panel MEMBERSHIP is traced from Blender's own
- * `declare()` bodies (`blender.node-panels.json`) and its COLLAPSED STATE is
- * read live from `Node.panel_states`, so a Principled BSDF draws the eight
- * collapsed panel rows Blender draws. Two things still fall back, and both
- * say so by name: a node whose LIVE socket list disagrees with the traced
- * declaration (the ruling's own condition), and a node the trace does not
- * cover at all — a node GROUP, whose panels are its tree interface's runtime
- * data rather than a declaration.
- */
+/** The status line names refusals and node-layout limitations. Socket panels use traced declarations and live panel_states; mismatched socket lists and runtime node groups draw flat with a named warning. */
 function StatusLine({
   entries,
   error,
@@ -1272,20 +1151,7 @@ function StatusLine({
   );
 }
 
-/**
- * THE N-PANEL'S NODE TAB — `NODE_PT_active_node_generic`
- * (`bl_ui/space_node.py:800-841`), in its own order: `name` (`:819`), `label`
- * (`:820`), the Color heading with `use_custom_color` and `color`
- * (`:822-834`), then `show_options` (`:837`) and `mute` (`:838`). Blender
- * 5.2 has no separate `NODE_PT_active_node_color`; the colour controls are
- * that panel's own sub-column.
- *
- * `NODE_PT_active_node_properties` (`:844-857`) is ONE call —
- * `layout.template_node_inputs(node)` — and that template is C: it draws the
- * same per-socket widgets the node body draws. The node's own inputs are
- * listed here with their values for exactly that reason, which is the same
- * fact through the same door.
- */
+/** Read-only looked-at node name, label, colour, mute and visible socket values. */
 function NodePanel({
   node,
   onRefuse,
@@ -1301,15 +1167,9 @@ function NodePanel({
         flex: '0 0 auto',
         overflow: 'auto',
         // THE SIDEBAR IS PART OF THE NODE EDITOR'S AREA, so it wears the
-        // space's own `TH_BACK` like the header and the canvas do. It used to
-        // paint `--volter-color-surface-panel`, which is the DOCK's grey
-        // (#303030 under the Blender look): Blender fills every region of a
-        // node editor area with `TH_BACK` and draws panels ON it
-        // (`ED_region_panels`), so the grey was this view wearing its
-        // container's colour. MEASURED 2026-09-19 (the frame walk, beat 5):
-        // at (600,500) — inside the Shader Editor's pane, which a 320px
-        // sidebar had squeezed the canvas out of — the read was #303030 where
-        // the beat named #1a1a1a. The frame's `volter.nodeEditor.background`
+        // space's own `TH_BACK` like the header and the canvas do, not the
+        // DOCK's grey: Blender fills every region of a node editor area with
+        // `TH_BACK` and draws panels ON it (`ED_region_panels`). The frame's `volter.nodeEditor.background`
         // theme colour carries the same traced value for the workbench's own
         // painting; this is the same number, from the same trace, for the
         // pixels we paint ourselves.
@@ -1322,9 +1182,7 @@ function NodePanel({
     >
       <div style={{ opacity: 0.6, marginBottom: 'var(--volter-space-2)' }}>Node</div>
       {!node ? (
-        // Blender's panel `poll` is `context.active_node is not None`
-        // (`space_node.py:806-808`): with no active node the tab draws nothing.
-        <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} />
@@ -1391,12 +1249,3 @@ function Row({
     </div>
   );
 }
-
-// THERE IS DELIBERATELY NO `available` GATE. A `workspace.utility` may gate
-// its tab on session state, and the Network utility does because a game may or
-// may not expose a networking adapter. This tab's condition is that the
-// BLENDER BUILD is loaded, and a contribution of this package cannot be
-// registered unless it is — the same reason `model.layout.ts` gates on the
-// project declaring a `model` document and nothing else. With no material the
-// view draws what Blender draws with no tree: the bare background, and the
-// header saying so.