@volter/editor-blender 0.1.0

package/contributions/model.layout.ts

@@ -0,0 +1,53 @@
+/**
+ * The MODEL workspace — Blender-shaped modeling: a dominant document, outliner
+ * above properties (`@volter/editor-sdk/looks`, a `workspace.layout`
+ * contribution). Its arrangement carries Blender 5.2's own MODELING-workspace
+ * proportions; `../src/layouts.tsx` states the measurement and the host's
+ * fixed-pane clamp that bounds it.
+ */
+
+import type { WorkspaceLayoutContribution } from '@volter/editor-sdk/looks';
+
+export const point = 'workspace.layout';
+export const layout: WorkspaceLayoutContribution = {
+  id: 'model',
+  title: 'Model',
+  description: 'Blender-shaped modeling: a dominant document, outliner above properties.',
+  // No `tabs` here ON PURPOSE. The host's default is already `shown`, so
+  // stating it changed nothing for a bare host — but the WORKSPACE layer wins
+  // over the style bundle (`workspace-regions.ts`), so restating the default
+  // silently shadowed `blender.style.ts`'s `tabs: 'hidden'` and the Model
+  // document still painted a 25px tab row (measured against Blender 5.2, which
+  // has none). Leave a region unstated unless this workspace genuinely needs
+  // it different from the host default.
+  regions: {
+    header: 'shown',
+    shelf: 'shown',
+    inspector: 'properties',
+    drawer: 'hidden',
+  },
+  // THE TIMELINE IS THE BOTTOM AREA (owner, 2026-09-20: "doesn't blender have
+  // a timeline at the bottom?"). It does — and the workspace this Model
+  // document stands in is Blender's LAYOUT screen for us, not its Modeling
+  // one: Layout is the four-area screen with the Timeline, and Modeling is the
+  // same screen WITHOUT it (measured below).
+  //
+  // THE PROPORTION IS BLENDER'S OWN, measured through bpy on the installed
+  // Blender 5.2.1 at factory settings in a 1920-wide window
+  // (`bpy.data.workspaces['Layout'].screens[0].areas`):
+  //
+  //   PROPERTIES        x1579 y23  w339  h839
+  //   OUTLINER          x1579 y865 w339  h189
+  //   DOPESHEET_EDITOR  x2    y23  w1574 h74    ui_type TIMELINE  ← this area
+  //   VIEW_3D           x2    y100 w1574 h954
+  //
+  // and the same screen at a 1600×929 window gives the Timeline 63 of an
+  // 880-px centre column. Both are the same ratio to three places: 74/1029 =
+  // 0.0719 and 63/880 = 0.0716. The Modeling screen's own reading, for the
+  // contrast: VIEW_3D `x2 y23 w1574 h1031` and no DOPESHEET area at all.
+  //
+  // It is stated to four places because it is a measurement, not a preference;
+  // the dock uses it once, to size the group the first time this workspace
+  // stands up, and a capture of the settled grid wins afterwards.
+  areas: [{ id: 'timeline', document: 'blender-timeline.document', place: 'below', ratio: 0.0719 }],
+};

package/contributions/models.finder.ts

@@ -0,0 +1,59 @@
+/**
+ * The `modelsFromBlendFiles` FINDER (ARCHITECTURE-CORE §The project model,
+ * "A model is Blender data, and a prefab is not a model"): every `.blend`
+ * under the selection's `include` globs is a `model` document — a Blender
+ * file the engine in the tab opens, edits and saves. The bpy scripts that
+ * authored it are ordinary project files beside it (`src/models/<name>.py`);
+ * this document does not run them, a person or an agent does, through the
+ * session's Blender (`vgai blender-mcp`).
+ *
+ * It replaced `modelsFromMeshModules`, which listed every module exporting
+ * `build(): THREE.BufferGeometry` (owner ruling 2026-09-19, "do the delete":
+ * the TypeScript mesh kit was the modeling engine while Blender could not run
+ * in the tab; it now does, and a model is Blender data).
+ *
+ * Select it in `vgai.adapter.ts`:
+ *
+ *   documents: { find: [{ finder: 'modelsFromBlendFiles', include: ['src/models/**\/*.blend'] }] }
+ *
+ * This module is a plain object the HOST registers; it mounts no UI. It reads
+ * the project only through `input.files` — the PATHS matching those globs.
+ * Deliberately not `input.sources`: a `.blend` is binary, there is nothing in
+ * it a text walk could honestly read, and the entry is the file itself.
+ */
+
+import { z } from 'zod';
+
+export const finder = {
+  name: 'modelsFromBlendFiles',
+  schema: z
+    .object({
+      finder: z.literal('modelsFromBlendFiles'),
+      include: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe('Project-relative globs of the Blender files to list (`src/models/**/*.blend`)'),
+    })
+    .strict(),
+  run(
+    _selection: { finder: 'modelsFromBlendFiles'; include: readonly string[] },
+    input: { files?: readonly string[] },
+  ) {
+    const entries = [];
+    const notes: string[] = [];
+    for (const path of input.files ?? []) {
+      if (!path.endsWith('.blend')) continue;
+      const name = (path.split('/').pop() ?? path).replace(/\.blend$/, '');
+      entries.push({
+        id: `model:${path}`,
+        label: name,
+        kind: 'model',
+        region: null,
+        authorable: true,
+        reach: { kind: 'root-mount' as const },
+        source: { path },
+      });
+    }
+    return { entries, notes };
+  },
+} as const;

package/contributions/properties-bone-constraints.inspector.tsx

@@ -0,0 +1,50 @@
+/**
+ * BLENDER'S BONE CONSTRAINTS TAB, as a Properties section (WORK.md §Blender in
+ * the tab is Blender, "Inspection parity", I2): the active POSE BONE's
+ * constraint stack, with the generic view beneath under "All properties".
+ *
+ * It is the Object Constraints tab over a different datablock, and Blender
+ * says so itself: `properties_constraint.py` registers
+ * `BONE_PT_constraints` beside `OBJECT_PT_constraints` with the same
+ * `template_constraints()` body, differing only in reading
+ * `context.pose_bone.constraints`. So it shares the header list that module
+ * exports rather than restating it — a second copy is a second thing to keep
+ * in step.
+ *
+ * It stands when: `buttons_context_path_pose_bone` — a pose channel for the
+ * active bone, and never in Edit mode.
+ */
+import { blenderPropertiesTabMatch, blenderPropertiesTabSection } from './blender-properties-tab';
+import type { BlenderCuratedPanel } from './blender-properties-view';
+import { CONSTRAINT_HEADER } from './properties-constraints.inspector';
+
+const CURATED: readonly BlenderCuratedPanel[] = [
+  {
+    title: 'Bone Constraints',
+    from: 'Constraints',
+    collection: true,
+    properties: CONSTRAINT_HEADER,
+    andDeclared: true,
+  },
+];
+
+const TAB = { id: 'bone_constraint', curated: CURATED } as const;
+
+export const point = 'selection.inspector';
+export const title = 'Bone Constraints';
+/** `blender.icons.json` — Blender's own mark, TRACED from
+ *  `release/datafiles/icons_svg/` at the engine's pin (the icon this tab draws
+ *  is named in `buttons_context_items`, `makesrna/intern/rna_space.cc:579`),
+ *  and tinted by the group `UI_icons.hh` declares it in. */
+export const icon = 'properties-bone-constraints';
+/** `ED_buttons_tabs_list` (`space_buttons.cc:218-252`) is the rail's order;
+ *  these are that order, spaced so a tab can be inserted between two. */
+export const order = 140;
+/** THE RAIL'S GROUPS, from `ED_buttons_tabs_list`'s own `add_spacer()` calls
+ *  (`space_buttons/space_buttons.cc:201-255`): the tool tab, then the scene
+ *  group (Render, Output, View Layer, Scene, World), then Collection, then the
+ *  object group (Object … Material), then Texture. The presentation draws a
+ *  separator wherever this changes. */
+export const railGroup = 'object';
+export const match = blenderPropertiesTabMatch(TAB);
+export default blenderPropertiesTabSection(TAB);

package/contributions/properties-bone.inspector.tsx

@@ -0,0 +1,184 @@
+/**
+ * BLENDER'S BONE TAB, as a Properties section (WORK.md §Blender in the tab is
+ * Blender, "Inspection parity", I2). Blender's own panels over the RNA door,
+ * with the generic view beneath under "All properties".
+ *
+ * THE SPECIFICATION IS `scripts/startup/bl_ui/properties_data_bone.py` at the
+ * engine's pin: its `classes` tuple is the panel order, `bl_label` the title,
+ * each `layout.prop(bone, "x")` an entry. Blender's UI layer is never run,
+ * ported or recorded.
+ *
+ * TWO DATABLOCKS, AND THAT IS THE WHOLE STRUCTURE OF THIS TAB. Blender's panels
+ * read `bone` (the armature's `Bone`, or the `EditBone` in Edit mode) for the
+ * rest pose — head, tail, roll, envelope, collections, display — and `pchan`
+ * (the `PoseBone`) for the POSE: its location/rotation/scale and its inverse
+ * kinematics. `buttons_context_path_bone` and `_pose_bone` build both, and the
+ * door hands this tab both as "Bone" and "Pose Bone", so each panel names the
+ * one Blender's draw function reads. That is why Transform below is split in
+ * two the way `BONE_PT_transform` (:39) is: its first half is `pchan`, its
+ * second `bone`.
+ *
+ * It stands when: `buttons_context_path_bone` — an armature with an ACTIVE bone
+ * (the edit bone in Edit mode).
+ */
+import { blenderPropertiesTabMatch, blenderPropertiesTabSection } from './blender-properties-tab';
+import type { BlenderCuratedPanel } from './blender-properties-view';
+
+/** `properties_data_bone.py`, panel by panel. Line numbers are that file's. */
+const CURATED: readonly BlenderCuratedPanel[] = [
+  {
+    // BONE_PT_transform, :39, pose half (:63-99) — drawn in Pose mode.
+    title: 'Transform (Pose)',
+    from: 'Pose Bone',
+    properties: [
+      'location',
+      'lock_location',
+      'rotation_quaternion',
+      'rotation_axis_angle',
+      'rotation_euler',
+      'lock_rotation_w',
+      'lock_rotation',
+      'rotation_mode',
+      'scale',
+      'lock_scale',
+    ],
+  },
+  {
+    // BONE_PT_transform, :39, rest half (:104-110) — the bone's own geometry.
+    // NO MATRICES. The first cut named `matrix` and `matrix_local` beside them
+    // and the live read showed why Blender does not: a 3x3 and a 4x4 draw as
+    // twenty-five numbered rows, which buries the five values the panel is
+    // about. They are still in "All properties" beneath, where a matrix is
+    // something you go looking for. (`roll` is an EditBone property, so it
+    // draws in Edit mode and not in Object mode — the datablock's answer, not
+    // a condition of ours.)
+    title: 'Transform',
+    from: 'Bone',
+    properties: ['head', 'tail', 'roll', 'length', 'lock'],
+  },
+  {
+    // BONE_PT_curved, :114 — "Bendy Bones".
+    title: 'Bendy Bones',
+    closed: true,
+    from: 'Bone',
+    properties: [
+      'bbone_segments',
+      'bbone_x',
+      'bbone_z',
+      'bbone_mapping_mode',
+      'use_endroll_as_inroll',
+      'use_scale_easing',
+      'bbone_handle_type_start',
+      'bbone_handle_use_scale_start',
+      'bbone_handle_use_ease_start',
+      'bbone_handle_type_end',
+      'bbone_handle_use_scale_end',
+      'bbone_handle_use_ease_end',
+    ],
+  },
+  {
+    // BONE_PT_relations, :213.
+    title: 'Relations',
+    from: 'Bone',
+    properties: [
+      'parent',
+      'children',
+      'use_relative_parent',
+      'use_connect',
+      'use_local_location',
+      'use_inherit_rotation',
+      'inherit_scale',
+    ],
+  },
+  {
+    // BONE_PT_collections, :252 — the collections this bone is in.
+    title: 'Bone Collections',
+    closed: true,
+    from: 'Bone',
+    properties: ['collections'],
+  },
+  {
+    // BONE_PT_inverse_kinematics, :430 — every one of these is on the POSE
+    // channel, not the bone.
+    title: 'Inverse Kinematics',
+    closed: true,
+    from: 'Pose Bone',
+    properties: [
+      'ik_stretch',
+      'lock_ik_x',
+      'lock_ik_y',
+      'lock_ik_z',
+      'ik_stiffness_x',
+      'ik_stiffness_y',
+      'ik_stiffness_z',
+      'use_ik_limit_x',
+      'ik_min_x',
+      'ik_max_x',
+      'use_ik_limit_y',
+      'ik_min_y',
+      'ik_max_y',
+      'use_ik_limit_z',
+      'ik_min_z',
+      'ik_max_z',
+      'use_ik_rotation_control',
+    ],
+  },
+  {
+    // BONE_PT_deform, :535 — `use_deform` is the panel's own header checkbox.
+    title: 'Deform',
+    closed: true,
+    from: 'Bone',
+    properties: [
+      'use_deform',
+      'envelope_distance',
+      'envelope_weight',
+      'use_envelope_multiply',
+      'head_radius',
+      'tail_radius',
+    ],
+  },
+  {
+    // BONE_PT_display, :304, and BONE_PT_display_custom_shape (:388), whose
+    // properties are all on the pose channel.
+    title: 'Viewport Display',
+    closed: true,
+    from: 'Bone',
+    properties: ['hide', 'hide_select', 'display_type', 'color', 'show_wire'],
+    sub: [
+      {
+        title: 'Custom Shape',
+        closed: true,
+        from: 'Pose Bone',
+        properties: [
+          'custom_shape',
+          'custom_shape_translation',
+          'custom_shape_rotation_euler',
+          'custom_shape_scale_xyz',
+          'use_custom_shape_bone_size',
+          'custom_shape_transform',
+        ],
+      },
+    ],
+  },
+];
+
+const TAB = { id: 'bone', curated: CURATED } as const;
+
+export const point = 'selection.inspector';
+export const title = 'Bone';
+/** `blender.icons.json` — Blender's own mark, TRACED from
+ *  `release/datafiles/icons_svg/` at the engine's pin (the icon this tab draws
+ *  is named in `buttons_context_items`, `makesrna/intern/rna_space.cc:579`),
+ *  and tinted by the group `UI_icons.hh` declares it in. */
+export const icon = 'properties-bone';
+/** `ED_buttons_tabs_list` (`space_buttons.cc:218-252`) is the rail's order;
+ *  these are that order, spaced so a tab can be inserted between two. */
+export const order = 130;
+/** THE RAIL'S GROUPS, from `ED_buttons_tabs_list`'s own `add_spacer()` calls
+ *  (`space_buttons/space_buttons.cc:201-255`): the tool tab, then the scene
+ *  group (Render, Output, View Layer, Scene, World), then Collection, then the
+ *  object group (Object … Material), then Texture. The presentation draws a
+ *  separator wherever this changes. */
+export const railGroup = 'object';
+export const match = blenderPropertiesTabMatch(TAB);
+export default blenderPropertiesTabSection(TAB);

package/contributions/properties-collection.inspector.tsx

@@ -0,0 +1,96 @@
+/**
+ * BLENDER'S COLLECTION TAB, as a Properties section (WORK.md §Blender in the
+ * tab is Blender, "Inspection parity", I2). Blender's own panels over the RNA
+ * door, with the generic view beneath under "All properties".
+ *
+ * THE SPECIFICATION IS `scripts/startup/bl_ui/properties_collection.py` at the
+ * engine's pin — `classes` (`:146-155`) is the panel order and `bl_label` the
+ * title. Blender's UI layer is never run, ported or recorded.
+ *
+ * THE FIRST PANEL IS CALLED "VISIBILITY" AT THIS PIN, not "Restrictions":
+ * `COLLECTION_PT_collection_flags.bl_label` is `"Visibility"` (`:32`). Its
+ * child View Layer (`:47`) does not read the collection at all — it reads
+ * `view_layer.active_layer_collection` (`:56`), a different datablock, which
+ * the context door now names beside the collection as this tab's second path.
+ *
+ * TWO CHECKBOXES BLENDER DRAWS INVERTED. `hide_select` is labelled
+ * "Selectable" with `invert_checkbox=True` (`:41`) and `exclude` is labelled
+ * "Include" the same way (`:60`). What stands here is the RNA's own value
+ * under the RNA's own name, because inverting a value in the presentation is
+ * exactly the fabrication the anti-shim rule forbids — the same reading the
+ * Object tab's Visibility panel already made.
+ *
+ * WHAT THE TRANSCRIPTION DELIBERATELY DROPS: `COLLECTION_PT_importer`
+ * (`:65`), whose poll is a PREFERENCE (`prefs.experimental.use_collection_
+ * importer`) and whose body is `template_collection_importer()` — an operator
+ * template. Exporters (`:80`) is the same widget over `collection.exporters`,
+ * and the collection itself is real RNA (`rna_collection.cc:954`), so its row
+ * stands. `COLLECTION_PT_collection_custom_props` (`:143`) is IDProperties
+ * rather than RNA.
+ *
+ * It stands when: `buttons_context_path_collection` — the view layer's ACTIVE
+ * collection, and never the scene's master collection, which only the engine
+ * knows.
+ */
+import { blenderPropertiesTabMatch, blenderPropertiesTabSection } from './blender-properties-tab';
+import type { BlenderCuratedPanel } from './blender-properties-view';
+
+/** `properties_collection.py`, panel by panel. Line numbers are that file's. */
+const CURATED: readonly BlenderCuratedPanel[] = [
+  {
+    // COLLECTION_PT_collection_flags, :31.
+    title: 'Visibility',
+    properties: ['hide_select', 'hide_render'],
+    sub: [
+      {
+        // COLLECTION_PT_viewlayer_flags, :47 — the LayerCollection's.
+        title: 'View Layer',
+        from: 'View Layer Collection',
+        properties: ['exclude', 'holdout', 'indirect_only'],
+      },
+    ],
+  },
+  {
+    // COLLECTION_PT_instancing, :99.
+    title: 'Instancing',
+    properties: ['instance_offset'],
+  },
+  {
+    // COLLECTION_PT_lineart_collection, :113 — the mask is drawn as eight
+    // indexed toggles (:130); the array row carries all eight.
+    title: 'Line Art',
+    properties: [
+      'lineart_usage',
+      'lineart_use_intersection_mask',
+      'lineart_intersection_mask',
+      'use_lineart_intersection_priority',
+      'lineart_intersection_priority',
+    ],
+  },
+  {
+    // COLLECTION_PT_exporters, :80.
+    title: 'Exporters',
+    properties: ['exporters'],
+  },
+];
+
+const TAB = { id: 'collection', curated: CURATED } as const;
+
+export const point = 'selection.inspector';
+export const title = 'Collection';
+/** `blender.icons.json` — Blender's own mark, TRACED from
+ *  `release/datafiles/icons_svg/` at the engine's pin (the icon this tab draws
+ *  is named in `buttons_context_items`, `makesrna/intern/rna_space.cc:579`),
+ *  and tinted by the group `UI_icons.hh` declares it in. */
+export const icon = 'properties-collection';
+/** `ED_buttons_tabs_list` (`space_buttons.cc:218-252`) is the rail's order;
+ *  these are that order, spaced so a tab can be inserted between two. */
+export const order = 60;
+/** THE RAIL'S GROUPS, from `ED_buttons_tabs_list`'s own `add_spacer()` calls
+ *  (`space_buttons/space_buttons.cc:201-255`): the tool tab, then the scene
+ *  group (Render, Output, View Layer, Scene, World), then Collection, then the
+ *  object group (Object … Material), then Texture. The presentation draws a
+ *  separator wherever this changes. */
+export const railGroup = 'collection';
+export const match = blenderPropertiesTabMatch(TAB);
+export default blenderPropertiesTabSection(TAB);

package/contributions/properties-constraints.inspector.tsx

@@ -0,0 +1,69 @@
+/**
+ * BLENDER'S OBJECT CONSTRAINTS TAB, as a Properties section (WORK.md §Blender
+ * in the tab is Blender, "Inspection parity", I2): the STACK, each constraint
+ * its own panel with its own settings, the generic view beneath under "All
+ * properties".
+ *
+ * THE SPECIFICATION IS `scripts/startup/bl_ui/properties_constraint.py`, and
+ * it has the same shape `properties_data_modifier.py` does: `draw` is
+ * `layout.template_constraints()` and the per-type panels are built in C from
+ * each constraint's RNA. So the stack is derived the same way — the shared
+ * `Constraint` header properties named, then everything THIS constraint's own
+ * struct declares (`andDeclared`, which reads `BlenderRnaRow.group`). A Copy
+ * Location constraint gets `CopyLocationConstraint`'s target, subtarget, use_x
+ * / use_y / use_z, invert flags and offset, in RNA's order.
+ *
+ * The ACTIVE constraint (`buttons_context_path_constraint`, reported as
+ * `activeConstraint`) is marked.
+ *
+ * It stands when: `buttons_context_path_object` — Constraints shares Object's
+ * path, so the engine grants it whenever it grants Object.
+ */
+import { blenderPropertiesTabMatch, blenderPropertiesTabSection } from './blender-properties-tab';
+import type { BlenderCuratedPanel } from './blender-properties-view';
+
+/** The shared header every constraint panel carries — `Constraint`'s own
+ *  properties, in the order `template_constraints` heads a panel with them. */
+export const CONSTRAINT_HEADER: readonly string[] = [
+  'name',
+  'type',
+  'enabled',
+  'mute',
+  'influence',
+  'error_location',
+  'error_rotation',
+  'is_valid',
+  'is_override_data',
+];
+
+const CURATED: readonly BlenderCuratedPanel[] = [
+  {
+    title: 'Constraints',
+    from: 'Constraints',
+    collection: true,
+    active: 'activeConstraint',
+    properties: CONSTRAINT_HEADER,
+    andDeclared: true,
+  },
+];
+
+const TAB = { id: 'constraint', curated: CURATED } as const;
+
+export const point = 'selection.inspector';
+export const title = 'Object Constraints';
+/** `blender.icons.json` — Blender's own mark, TRACED from
+ *  `release/datafiles/icons_svg/` at the engine's pin (the icon this tab draws
+ *  is named in `buttons_context_items`, `makesrna/intern/rna_space.cc:579`),
+ *  and tinted by the group `UI_icons.hh` declares it in. */
+export const icon = 'properties-constraints';
+/** `ED_buttons_tabs_list` (`space_buttons.cc:218-252`) is the rail's order;
+ *  these are that order, spaced so a tab can be inserted between two. */
+export const order = 110;
+/** THE RAIL'S GROUPS, from `ED_buttons_tabs_list`'s own `add_spacer()` calls
+ *  (`space_buttons/space_buttons.cc:201-255`): the tool tab, then the scene
+ *  group (Render, Output, View Layer, Scene, World), then Collection, then the
+ *  object group (Object … Material), then Texture. The presentation draws a
+ *  separator wherever this changes. */
+export const railGroup = 'object';
+export const match = blenderPropertiesTabMatch(TAB);
+export default blenderPropertiesTabSection(TAB);