@volter/editor-blender 0.1.150 → 0.1.151

package/contributions/blender-node-panels.source.mjs

@@ -1,85 +1,4 @@
-/**
- * TRACING A NODE'S SOCKET PANELS FROM BLENDER'S OWN DECLARATIONS — the table
- * that closes I5's one named gap (WORK.md §Blender in the tab is Blender,
- * "Inspection parity", I5; RULED 2026-09-19: "socket panels are traced from
- * Blender's source, like the icons and the palette").
- *
- * ## Why a trace and not a read
- *
- * `Node.panel_states` is RNA's whole answer about a node's socket panels: a
- * `persistent_uid` and `is_collapsed`, and nothing else
- * (`rna_nodetree.cc:9289-9299`, `:9430-9434`). Which SOCKETS belong to a
- * panel, what a panel is CALLED, and where a panel sits among the node's
- * items all live in the node's C++ declaration — the `root_items` list that
- * `node_update_basis_from_declaration` (`node_draw.cc:1086-1218`) walks — and
- * bpy exposes no part of it. Measured on the engine: a
- * `ShaderNodeBsdfPrincipled` answers 8 panel states and not one of its
- * `NodeSocket`s carries a panel field.
- *
- * So the membership is READ FROM THE SOURCE, exactly as the icons are traced
- * out of `release/datafiles/icons_svg/*.svg` (`blender-icon-trace.mjs`) and
- * the palette out of `userdef_default_theme.c` (`blender-palette.source.mjs`).
- * The reference is Blender's SOURCE as well as its frames
- * (ARCHITECTURE-CORE §Blender north star), and a declaration is source.
- *
- * ## What is traced, and what deliberately is not
- *
- * ONLY node types that DECLARE A PANEL. A node with no panel is already laid
- * out correctly by the flat path — its flattened item list is its socket list
- * — so a table row for it would carry no information and would have to be
- * kept in step with 558 files instead of 36. Measured at Blender 5.2.0
- * (`fbe6228777e7`): 558 `node_*.cc` files, **36** of which call `add_panel`
- * in a declaration (17 composite, 11 geometry, 5 shader, 3 function).
- *
- * TWO `add_panel` CALL SITES ARE EXCLUDED AND THE REASON IS STATED.
- * `intern/node_declaration.cc:474` is the builder method itself, not a
- * declaration. `intern/node_common.cc:485` is the NODE GROUP's declare, which
- * builds its panels in a LOOP over `ntree->tree_interface` — a group's panels
- * are runtime data, not a static declaration, and RNA *can* answer them
- * (`NodeTree.interface`), so tracing them would be tracing the wrong thing.
- * A group node therefore has no row here and keeps the flat fallback.
- *
- * ## The grammar this reads
- *
- * A declaration body is a straight-line sequence of builder calls. Measured
- * across the 36 files, a panel is introduced in exactly two spellings —
- * `PanelDeclarationBuilder &<var> = <recv>.add_panel("Name")` (49 sites) and
- * `auto &<var> = <recv>.add_panel("Name")` (17 sites) — and everything else
- * is `<recv>.add_input<…>("Name"[, "Identifier"])`,
- * `<recv>.add_output<…>(…)`, `<recv>.add_layout(…)`,
- * `<recv>.add_default_layout()` and `<recv>.add_separator()`, where `<recv>`
- * is either the root builder's own parameter or a bound panel variable. That
- * is the whole grammar, and this file parses that and nothing more.
- *
- * A body with CONTROL FLOW is parsed straight through — both arms of an
- * `if`/`else` contribute items, in source order — and the entry is marked
- * `conditional`. That is deliberately a LOUD approximation rather than a
- * clever one: the consumer checks the traced item list against the engine's
- * LIVE socket list before it uses it, and a node whose real declaration took
- * the other arm simply disagrees and falls back to flat with its frame
- * warning. A static parser cannot evaluate `b.tree_or_null()`, and pretending
- * otherwise is how a drawing quietly stops being a measurement.
- *
- * ## Running it
- *
- * ```
- * node packages/editor-blender/contributions/blender-node-panels.source.mjs \
- *   [--checkout <path>] [--check]
- * ```
- * writes (or, with `--check`, verifies) `blender.node-panels.json` beside
- * this file. The checkout defaults to `~/volter/blender-src`, the sparse
- * checkout pinned at the engine's own commit; `source/blender/nodes` is one
- * of the paths it must carry (see the checkout recipe's file map).
- *
- * ## Licence
- *
- * What lands in the JSON is a table of PANEL NAMES and SOCKET NAMES read out
- * of GPL-2.0-or-later sources. `@volter/editor-blender` is AGPL-3.0-only, which that
- * is compatible with (relicense to GPL-3.0, then §13), and the package
- * already carries Blender itself — the same standing this file's sibling
- * `blender-icon-trace.mjs` records for the icon paths. Nothing traced here
- * may be copied into an Apache-2.0 or MIT part of this repo.
- */
+
 
 import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -90,9 +9,7 @@ const DEFAULT_CHECKOUT = join(homedir(), 'volter', 'blender-src');
 const NODES_ROOT = join('source', 'blender', 'nodes');
 const OUT = fileURLToPath(new URL('./blender.node-panels.json', import.meta.url));
 
-/** The two `add_panel` call sites that are not a node's declaration — see the
- *  header. Both are named rather than filtered by a shape rule, so a third one
- *  appearing upstream shows up as a new row instead of vanishing. */
+/** Exclude the two add_panel call sites outside node declarations. Other upstream call sites remain visible. */
 const NOT_A_DECLARATION = new Set([
   join(NODES_ROOT, 'intern', 'node_common.cc'),
   join(NODES_ROOT, 'intern', 'node_declaration.cc'),
@@ -162,7 +79,7 @@ function blockAt(source, open) {
  * `;` at nesting depth 0 ends a statement; a `{ … }` that closes back to
  * depth 0 is spliced in as its own statements, which is what makes an
  * `if`/`else` body contribute its items in source order (and what makes the
- * entry `conditional` — see the header).
+ * diagnostic report list conditional declarations).
  */
 function statementsOf(block) {
   const out = [];
@@ -207,15 +124,7 @@ function statementsOf(block) {
 
 /* ----------------------------------------------------------------- the walk */
 
-/**
- * The string literals in the FIRST call of a chain, and only that call.
- *
- * `open` is the index of its `(`. Taking the balanced argument list rather
- * than "every quoted run in the statement" is not a nicety: the very first
- * node measured, `Base Color`, chains
- * `.description("Color of the material used for …")`, and a whole-statement
- * scan reads that sentence as the socket's identifier.
- */
+/** Read string literals only from the first balanced call in a chain. Later description calls are metadata, not socket identifiers. */
 function firstStrings(call, open) {
   let depth = 0;
   let end = call.length;
@@ -302,10 +211,7 @@ function parseDeclaration(body, rootParam) {
     if (method === 'add_input' || method === 'add_output') {
       const names = firstStrings(call, open);
       if (names.length === 0) continue;
-      // EVERY OPTIONAL FLAG IS OMITTED WHEN IT IS FALSE, and `identifier` when
-      // it equals the name. The table is 36 node types and is meant to be
-      // READ in review; spelling four `false`s per socket triples it for no
-      // information (105 KB against 47 KB, measured).
+      // Omit false flags and identifiers equal to the socket name to keep the generated declaration table compact.
       const socket = {
         kind: method === 'add_input' ? 'input' : 'output',
         name: names[0],
@@ -319,10 +225,6 @@ function parseDeclaration(body, rootParam) {
       // (`node_declaration.cc:528-542`) takes the panel's FIRST item when it
       // is a panel-toggle boolean input.
       if (/\.panel_toggle\s*\(/.test(call)) socket.panelToggle = true;
-      // `.available(<expr>)` — a socket whose availability is COMPUTED. It is
-      // recorded rather than resolved: the consumer matches against the LIVE
-      // socket list, where the expression has already been evaluated.
-      if (/\.available\s*\(/.test(call)) socket.conditional = true;
       // `SocketDeclaration::align_with_previous_socket` (`:196`): this socket
       // shares the previous socket's ROW instead of taking one
       // (`add_flat_items_for_socket`, `node_draw.cc:704-717`).
@@ -347,17 +249,7 @@ function parseDeclaration(body, rootParam) {
 
 /* ------------------------------------------------------------ the registry */
 
-/**
- * The node types a file registers, each with the declaration function it
- * points `ntype.declare` at.
- *
- * `<x>_node_type_base(&ntype, "IDNAME"_ustr, …)` names the type and
- * `ntype.declare = <ns>::<fn>` names the body. Where one file registers two
- * types from two nested namespaces with the SAME function name
- * (`node_geo_foreach_geometry_element.cc` is the measured case), the body is
- * the definition of that name nearest ABOVE the register function — which is
- * what C++ name lookup resolves to from inside the namespace.
- */
+/** Resolve each registered node type’s declare function to the nearest preceding definition in its namespace. */
 function registrationsOf(source) {
   const declares = [];
   const declareEach =
@@ -371,12 +263,7 @@ function registrationsOf(source) {
     });
   }
   const out = [];
-  // THREE SPELLINGS, measured across the tree: `static void node_register()`
-  // with `NOD_REGISTER_NODE(node_register)` (411 sites, the modern one),
-  // `static void register_node()` (5) and the legacy
-  // `void register_node_type_sh_*()` (the shader tree's). A function is a
-  // registration when its body calls `<x>_node_type_base(&ntype, "IDNAME")`,
-  // which is the test below; these names are only how the body is FOUND.
+  // Find node_register, register_node and register_node_type_sh_* bodies; only calls to a node-type base constructor identify registrations.
   const registerEach =
     /(?:static\s+)?void\s+(register_node_type_\w+|node_register|register_node)\s*\(\s*\)\s*\{/g;
   for (let hit = registerEach.exec(source); hit !== null; hit = registerEach.exec(source)) {
@@ -429,7 +316,6 @@ function build(checkout) {
         // DECLARATION layout path at all. A panel-declaring node that does not
         // set it is a contradiction worth carrying rather than hiding.
         customSocketOrder: parsed.customSocketOrder,
-        ...(parsed.conditional ? { conditional: true } : {}),
         items: parsed.items,
       };
     }