@volter/editor-blender 0.1.0

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@volter/editor-blender",
+  "author": "Volter AI, Inc.",
+  "license": "AGPL-3.0-only AND GPL-3.0-or-later",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Blender modeling documents, inspectors, commands and presentation for Volter Editor.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/editor.git",
+    "directory": "packages/editor-blender"
+  },
+  "files": [
+    "src",
+    "contributions",
+    "host",
+    "LICENSE"
+  ],
+  "exports": {
+    "./contributions/*": "./contributions/*",
+    "./looks": "./src/looks.ts",
+    "./layouts": "./src/layouts.tsx",
+    "./package.json": "./package.json"
+  },
+  "vgai": {
+    "contributions": [
+      "./contributions/blender-node-editor.document.tsx",
+      "./contributions/blender-timeline.document.tsx",
+      "./contributions/blender-uv-editor.document.tsx",
+      "./contributions/blender-runtime.document.tsx",
+      "./contributions/blender-version.status.tsx",
+      "./contributions/blender.command.ts",
+      "./contributions/blender.keymap.ts",
+      "./contributions/blender.status.tsx",
+      "./contributions/blender.style.ts",
+      "./contributions/model.layout.ts",
+      "./contributions/models.finder.ts",
+      "./contributions/properties-bone-constraints.inspector.tsx",
+      "./contributions/properties-bone.inspector.tsx",
+      "./contributions/properties-collection.inspector.tsx",
+      "./contributions/properties-constraints.inspector.tsx",
+      "./contributions/properties-data.inspector.tsx",
+      "./contributions/properties-material.inspector.tsx",
+      "./contributions/properties-modifiers.inspector.tsx",
+      "./contributions/properties-object.inspector.tsx",
+      "./contributions/properties-output.inspector.tsx",
+      "./contributions/properties-particles.inspector.tsx",
+      "./contributions/properties-physics.inspector.tsx",
+      "./contributions/properties-render.inspector.tsx",
+      "./contributions/properties-scene.inspector.tsx",
+      "./contributions/properties-texture.inspector.tsx",
+      "./contributions/properties-view-layer.inspector.tsx",
+      "./contributions/properties-world.inspector.tsx",
+      "./contributions/sculpt.layout.ts",
+      "./contributions/shading.layout.ts",
+      "./contributions/uv-editing.layout.ts",
+      "./contributions/texture.layout.ts"
+    ]
+  },
+  "dependencies": {
+    "@volter/blender-engine": "0.1.0",
+    "@volter/editor-threejs": "0.5.57",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@volter/editor-sdk": "*",
+    "@volter/editor-project": "*",
+    "react": "^19.0.0",
+    "three": "^0.180.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}

package/src/layouts.tsx

@@ -0,0 +1,48 @@
+/**
+ * The BLENDER layout — the composition a models project's adapter declares
+ * (`vgai.adapter.ts`: `editor: { Layout: ModelLayout }`, the door
+ * `@volter/editor-sdk/layouts` documents). `ModelArrangement` names the Model
+ * workspace and the chrome regions it shows; Sculpt and Texture open on it too
+ * — their reserved panels (the brush rail, the layer stack) ship WITH their
+ * programs, never as empty chrome, and until then nothing about a sculpt
+ * arrangement differs from a modeling one.
+ *
+ * WHERE THE PANELS SIT IS THE WORKBENCH'S. A workspace declares what it SHOWS
+ * (`regions`) and which documents stand beside the centre one (`areas`); the
+ * sizes, the splits and the tab order are the frame's editor-group state,
+ * which VS Code persists itself. A captured grid used to ship here beside the
+ * contribution, measured off Blender 5.2's own MODELING workspace; the
+ * measurement that outlived it is `contributions/model.layout.ts`'s Timeline
+ * RATIO, which is a proportion rather than a geometry and is stated there.
+ */
+import {
+  EditorFooter,
+  EditorFrame,
+  EditorHeader,
+  Workspace,
+  type WorkspaceArrangement,
+} from '@volter/editor-sdk/layouts';
+
+export const ModelArrangement: WorkspaceArrangement = {
+  id: 'model',
+  title: 'Model',
+  // `tabs` unstated — see `../contributions/model.layout.ts`: the workspace
+  // layer wins over the style bundle, so restating the host default shadows it.
+  regions: {
+    header: 'shown',
+    shelf: 'shown',
+    inspector: 'properties',
+    drawer: 'hidden',
+  },
+};
+
+/** Blender-shaped modeling; the game never takes the workspace over. */
+export function ModelLayout() {
+  return (
+    <EditorFrame>
+      <EditorHeader />
+      <Workspace arrangement={ModelArrangement} immersivePlay={false} />
+      <EditorFooter />
+    </EditorFrame>
+  );
+}

package/src/looks.ts

@@ -0,0 +1,14 @@
+/**
+ * The Blender skew's LOOK and BINDINGS as importable values — `@volter/editor-blender/looks`,
+ * the public surface a project's `vgai.adapter.ts` declares them from
+ * (ARCHITECTURE-CORE §Adapters and contributions are code, not configs):
+ *
+ *     editor: { Layout: ModelLayout, style: blenderStyle, keymap: blenderKeymap }
+ *
+ * The same two objects the package's `workspace.style` / `workspace.keymap`
+ * contributions register (`package.json#vgai.contributions`). Registration
+ * publishes them to every project that declares this package; the adapter's
+ * declaration is what CHOOSES them for one.
+ */
+export { keymap as blenderKeymap } from '../contributions/blender.keymap';
+export { style as blenderStyle } from '../contributions/blender.style';

package/src/node-view-state.ts

@@ -0,0 +1,125 @@
+/**
+ * THE NODE VIEW'S OWN STATE, and the reason it is a module rather than a
+ * `useState` inside the component.
+ *
+ * `editor.document.*` is scoped to the ACTIVE CENTER DOCUMENT by design — its
+ * own header says so: "a selector resolving outside that document's container
+ * is refused by a message naming the scope". The node editor is a DRAWER
+ * utility, so nothing in the product could read or drive it: the sighted door
+ * (`editor.captureEditorChrome`, `vgai screenshot editor`) photographs it, and
+ * a photograph cannot click.
+ *
+ * So the view's actions are SESSION VERBS, which is the pattern the keyboard
+ * ruling already asks for — a `vgai.*` command per action rather than a raw
+ * listener — and this module is the one place their state lives. The component
+ * subscribes to it; `blender-node-view` (the command) reads and writes it. One
+ * store, two readers, no second copy.
+ *
+ * It imports NOTHING: the host handler and the contribution both reach it, and
+ * a store either of them could not import would not be one store.
+ */
+
+export interface NodeViewTransform {
+  /** The tree-space point at the view's centre. */
+  readonly cx: number;
+  readonly cy: number;
+  /** Tree units per CSS pixel. Blender's node editor draws without DPI
+   *  (`node_intern.hh:332`), so zoom 1 is one tree unit per pixel. */
+  readonly zoom: number;
+}
+
+export interface NodeViewState {
+  readonly transform: NodeViewTransform;
+  /** The node being LOOKED AT — inspection state, never `Node.select` in the
+   *  engine, which writing would be a mutation the document saves. */
+  readonly looked: string | null;
+  /** The last gesture refused by name, and why. */
+  readonly refusal: string | null;
+  /** The canvas box the view measured itself at, in CSS px. */
+  readonly size: { readonly w: number; readonly h: number };
+  /** Set by the view when a `view-all` was asked for and it has framed. */
+  readonly framedAt: number;
+  /**
+   * WHAT THE VIEW ACTUALLY DREW, in tree space — published so the parity
+   * table is a MEASUREMENT of the shipped drawing rather than a second run of
+   * the same arithmetic. `height` is `yTop - yBottom`, which at zoom 1 is CSS
+   * pixels, because the node editor draws without DPI (`node_intern.hh:332`).
+   */
+  readonly drawn: readonly DrawnNode[];
+}
+
+export interface DrawnNode {
+  readonly name: string;
+  readonly x: number;
+  readonly yTop: number;
+  readonly yBottom: number;
+  readonly width: number;
+  readonly height: number;
+  /** How many socket marks the node drew, and where the first one sits
+   *  relative to the node's top — the number `node_update_basis_socket`'s
+   *  `locy - NODE_DYS` decides. */
+  readonly sockets: number;
+  readonly firstSocketBelowTop: number | null;
+  /** The header's colour, as drawn. */
+  readonly header: string;
+  /** SOCKET PANELS, as drawn: how many the node stood and how many of those
+   *  are collapsed. A node that declares panels and drew them FLAT instead
+   *  carries the reason in `panelFallback` — the ruling's own condition,
+   *  readable rather than merely displayed. */
+  readonly panels: number;
+  readonly collapsedPanels: number;
+  readonly panelFallback: string | null;
+}
+
+const INITIAL: NodeViewState = {
+  transform: { cx: 0, cy: 0, zoom: 1 },
+  looked: null,
+  refusal: null,
+  size: { w: 0, h: 0 },
+  framedAt: 0,
+  drawn: [],
+};
+
+let state: NodeViewState = INITIAL;
+let version = 0;
+const listeners = new Set<() => void>();
+/** A `view-all` ASK, raised by the command and consumed by the view — the one
+ *  action the store cannot compute, because framing needs the laid-out tree. */
+let viewAllRequest = 0;
+
+export function nodeViewState(): NodeViewState {
+  return state;
+}
+
+export function nodeViewVersion(): number {
+  return version;
+}
+
+export function subscribeNodeView(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function setNodeViewState(next: Partial<NodeViewState>): void {
+  state = { ...state, ...next };
+  version += 1;
+  for (const listener of [...listeners]) listener();
+}
+
+export function requestNodeViewAll(): void {
+  viewAllRequest += 1;
+  version += 1;
+  for (const listener of [...listeners]) listener();
+}
+
+export function nodeViewAllRequest(): number {
+  return viewAllRequest;
+}
+
+/** A gesture the view refuses because it would EDIT. One place, so the command
+ *  door and the pointer handlers cannot drift into two vocabularies. */
+export function refuseNodeViewGesture(text: string): void {
+  setNodeViewState({ refusal: text });
+}

package/src/timeline-view-state.ts

@@ -0,0 +1,154 @@
+/**
+ * THE TIMELINE'S OWN VIEW STATE — the pan/zoom of its ruler, the last refusal,
+ * the measured box, and what it drew.
+ *
+ * THE PLAYBACK STATE IS NOT HERE. The frame, the play/pause and the keyframe
+ * columns live in the presenter's `BlenderSkinDirector`
+ * (`../contributions/blender-runtime-skin.ts`), because that object OWNS the
+ * `AnimationMixer` and a second copy of "what frame is it" is exactly the
+ * disagreement the whole design exists to avoid. This module holds only what
+ * is about the DRAWING.
+ *
+ * WHAT DRIVES IT IS NOT A SESSION VERB. U8's ruling 1 (2026-09-19): every view
+ * publishes `vgai.<view>.<verb>` commands through `@volter/editor-sdk/views`, one
+ * table behind the frame's command service and standalone `vgai edit`'s
+ * session verb — so this view adds no `blender-*` verb of its own.
+ *
+ * It imports NOTHING, for the reason the node and UV stores do: the view and
+ * the verb table both reach it, and a store either of them could not import
+ * would not be one store.
+ */
+
+export interface TimelineTransform {
+  /** The FRAME at the view's left edge, and the CSS pixels per frame. Blender's
+   *  own `View2D.cur` for a time editor is exactly this pair. */
+  readonly startFrame: number;
+  readonly pixelsPerFrame: number;
+}
+
+export interface TimelineDrawn {
+  /** The action being played, and whose keys the summary row draws. */
+  readonly action: string | null;
+  readonly object: string | null;
+  readonly armature: string | null;
+  /** The playhead's frame, as the MIXER holds it. */
+  readonly frame: number;
+  readonly start: number;
+  readonly end: number;
+  readonly fps: number;
+  readonly playing: boolean;
+  /** The frames the summary row drew a diamond at — AFTER the selection
+   *  filter, which is what "what the row drew" means. */
+  readonly keyframes: readonly number[];
+  /** The filter's position, and the objects whose keys survived it. */
+  readonly onlySelected: boolean;
+  readonly summaryObjects: readonly string[];
+  /** The ruler's major step, in frames, as `calculate_grid_step` answered it
+   *  for the drawn width — the number a parity read checks. */
+  readonly majorStep: number;
+  readonly minorStep: number | null;
+  /** How many marks of each kind went into the DOM. */
+  readonly majorLines: number;
+  readonly minorLines: number;
+  readonly labels: number;
+  readonly diamonds: number;
+  /** The diamond's drawn geometry, so the table is a measurement of the
+   *  shipped drawing rather than a second run of the same arithmetic. */
+  readonly diamondRadius: number;
+  readonly diamondSprite: number;
+  /** Bones the presenter bound, and tracks the mixer holds. */
+  readonly bones: number;
+  readonly tracks: number;
+  /** Engine calls the whole Timeline has made since the session began — a
+   *  scrub adds NONE, and that is the claim this number is here to prove. */
+  readonly engineCalls: number;
+  /** Everything this view shows LESS than Blender would, by name. */
+  readonly warnings: readonly string[];
+}
+
+export interface TimelineViewState {
+  readonly transform: TimelineTransform;
+  readonly refusal: string | null;
+  readonly size: { readonly w: number; readonly h: number };
+  readonly framedAt: number;
+  readonly drawn: TimelineDrawn | null;
+  /**
+   * BLENDER'S `show_keys_from_selected_only`, and it is VIEW state here for a
+   * reason a headless Blender forces: the flag Blender's Timeline reads is
+   * `Scene.flag & SCE_KEYS_NO_SELONLY` (`anim_filter.cc:254-270`), and this
+   * surface is an INSPECTION surface that does not write the file — so the
+   * filter's position is ours to hold and the data it filters on
+   * (`Object.select_get()`) stays Blender's.
+   *
+   * DEFAULTS ON, as Blender's does: `SCE_KEYS_NO_SELONLY` is a NEGATIVE flag
+   * and a new scene does not carry it, so a factory Blender's Timeline shows
+   * the selected objects' keys only. The reference read recorded exactly that
+   * — the probe's own Timeline drew an EMPTY summary row with the rig
+   * unselected while its Dope Sheet drew all five keys.
+   *
+   * IT DECIDES WHAT THE ROW DRAWS, NEVER WHAT PLAYS. Playback moves every
+   * object regardless, in Blender and here.
+   */
+  readonly onlySelected: boolean;
+}
+
+const INITIAL: TimelineViewState = {
+  transform: { startFrame: -5, pixelsPerFrame: 8 },
+  refusal: null,
+  size: { w: 0, h: 0 },
+  framedAt: 0,
+  drawn: null,
+  onlySelected: true,
+};
+
+let state: TimelineViewState = INITIAL;
+let version = 0;
+const listeners = new Set<() => void>();
+let viewAllRequest = 0;
+
+export function timelineViewState(): TimelineViewState {
+  return state;
+}
+
+export function timelineViewVersion(): number {
+  return version;
+}
+
+export function subscribeTimelineView(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function setTimelineViewState(next: Partial<TimelineViewState>): void {
+  state = { ...state, ...next };
+  version += 1;
+  for (const listener of [...listeners]) listener();
+}
+
+/** Flip the summary row's selection filter (Blender's `View ▸ Only Show
+ *  Selected`). The row re-filters from data the door already reported; nothing
+ *  is read from the engine and nothing the mixer plays changes. */
+export function setTimelineOnlySelected(onlySelected: boolean): void {
+  if (state.onlySelected === onlySelected) return;
+  setTimelineViewState({ onlySelected });
+}
+
+/** A `view-all` ASK, raised by the verb and consumed by the view — the one
+ *  action the store cannot compute, because framing needs the measured box. */
+export function requestTimelineViewAll(): void {
+  viewAllRequest += 1;
+  version += 1;
+  for (const listener of [...listeners]) listener();
+}
+
+export function timelineViewAllRequest(): number {
+  return viewAllRequest;
+}
+
+/** A gesture the view refuses because it would EDIT. One place, so the verb
+ *  table and the pointer handlers cannot drift into two vocabularies. */
+export function refuseTimelineGesture(text: string): void {
+  setTimelineViewState({ refusal: text });
+}

package/src/uv-view-state.ts

@@ -0,0 +1,125 @@
+/**
+ * THE UV VIEW'S OWN STATE, and the reason it is a module rather than a
+ * `useState` inside the component — the same reason `node-view-state.ts`
+ * records: `editor.document.*` reaches only the ACTIVE CENTRE DOCUMENT by its
+ * own contract, and this view is not one, so a `useState` here would be a
+ * surface nothing in the product could read or drive.
+ *
+ * WHAT DRIVES IT IS NOT A SESSION VERB. U8's ruling 1 (2026-09-19): every view
+ * publishes `vgai.<view>.<verb>` commands through `@volter/editor-sdk/views`,
+ * one table behind the frame's command service and standalone `vgai edit`'s
+ * session verb — so this view adds NO `blender-*` verb of its own, which is
+ * exactly what the ruling asked the remaining I5 views to stop paying for.
+ *
+ * It imports NOTHING, for the reason the node view's store does: the view and
+ * the verb table both reach it, and a store either of them could not import
+ * would not be one store.
+ */
+
+export interface UvViewTransform {
+  /** The UV-space point at the view's centre. UV space is Y-UP (v increases
+   *  upward, as Blender's image space does); the view flips it once, at the
+   *  SVG transform, so nothing downstream carries a sign. */
+  readonly cx: number;
+  readonly cy: number;
+  /** CSS pixels per UV unit. At zoom 1 the 0–1 tile is one pixel across, so
+   *  the view's own `view-all` is what a person actually starts from — the
+   *  same shape as Blender's `image_view_all` (`image_ops.cc`). */
+  readonly zoom: number;
+}
+
+export interface UvViewState {
+  readonly transform: UvViewTransform;
+  /** The last gesture refused by name, and why. */
+  readonly refusal: string | null;
+  /** The canvas box the view measured itself at, in CSS px. */
+  readonly size: { readonly w: number; readonly h: number };
+  /** Set by the view when a `view-all` was asked for and it has framed. */
+  readonly framedAt: number;
+  /**
+   * WHAT THE VIEW ACTUALLY DREW — published so a parity table is a
+   * MEASUREMENT of the shipped drawing rather than a second run of the same
+   * arithmetic, which is the reading `node-view-state.ts`'s `drawn` already
+   * earns its keep with.
+   */
+  readonly drawn: UvViewDrawn | null;
+}
+
+export interface UvViewDrawn {
+  readonly object: string | null;
+  readonly mesh: string | null;
+  readonly layer: string | null;
+  readonly layers: readonly string[];
+  /** Blender's mode at the read — named, never required (ruling 1). */
+  readonly mode: string;
+  readonly loops: number;
+  readonly polygons: number;
+  readonly triangles: number;
+  /** How many marks of each kind the view put in the DOM. */
+  readonly faces: number;
+  readonly edges: number;
+  readonly verts: number;
+  readonly faceDots: number;
+  readonly pinned: number;
+  /** The UV bounds the layout actually occupies. */
+  readonly bounds: readonly [number, number, number, number] | null;
+  /** The tile grid, as drawn: the tile count and its subdivision. */
+  readonly tiles: readonly [number, number];
+  readonly subdiv: readonly [number, number];
+  /** The image behind the tile, or the reason there is none. */
+  readonly image: string | null;
+  /** Everything the view is showing LESS than Blender would, by name. */
+  readonly warnings: readonly string[];
+}
+
+const INITIAL: UvViewState = {
+  transform: { cx: 0.5, cy: 0.5, zoom: 512 },
+  refusal: null,
+  size: { w: 0, h: 0 },
+  framedAt: 0,
+  drawn: null,
+};
+
+let state: UvViewState = INITIAL;
+let version = 0;
+const listeners = new Set<() => void>();
+/** A `view-all` ASK, raised by the verb and consumed by the view — the one
+ *  action the store cannot compute, because framing needs the read layout. */
+let viewAllRequest = 0;
+
+export function uvViewState(): UvViewState {
+  return state;
+}
+
+export function uvViewVersion(): number {
+  return version;
+}
+
+export function subscribeUvView(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function setUvViewState(next: Partial<UvViewState>): void {
+  state = { ...state, ...next };
+  version += 1;
+  for (const listener of [...listeners]) listener();
+}
+
+export function requestUvViewAll(): void {
+  viewAllRequest += 1;
+  version += 1;
+  for (const listener of [...listeners]) listener();
+}
+
+export function uvViewAllRequest(): number {
+  return viewAllRequest;
+}
+
+/** A gesture the view refuses because it would EDIT. One place, so the verb
+ *  table and the pointer handlers cannot drift into two vocabularies. */
+export function refuseUvViewGesture(text: string): void {
+  setUvViewState({ refusal: text });
+}