@volter/project 0.5.210 → 0.5.212

package/src/adapter/editor-looks.ts

@@ -1,25 +1,23 @@
 /**
  * THE LOOK POINTS — a workspace layout, a keymap and a style bundle as DATA a
- * package contributes (WORKBENCH.md §Contribution points: "Layouts, keymaps
+ * package contributes (keymaps
  * and styles are DATA points: they need no code to load, which is what makes
- * a 'styled build' a manifest choice rather than a code change").
+ * a styled build a manifest choice).
  *
  * A contribution module declares its point and exports ONE object:
  *
- *   `model.layout.ts`    export const point = 'workspace.layout';  export const layout: WorkspaceLayoutContribution
- *   `blender.keymap.ts`  export const point = 'workspace.keymap';  export const keymap: KeymapContribution
- *   `blender.style.ts`   export const point = 'workspace.style';   export const style: StyleContribution
+ *   `<name>.layout.ts`   export const point = 'workspace.layout';  export const layout: WorkspaceLayoutContribution
+ *   `<name>.keymap.ts`   export const point = 'workspace.keymap';  export const keymap: KeymapContribution
+ *   `<name>.style.ts`    export const point = 'workspace.style';   export const style: StyleContribution
  *
- * The editor registers what a project's declared packages contribute beside
- * its own built-ins — Look, Animate and Design as workspaces, the volter keymap,
- * the Classic/Glass/Maya/Substance bundles — and never asks which package is
- * open: a build without the Blender look has no Model workspace.
+ * The editor registers the layouts, keymaps and styles declared by product and project
+ * packages. A composition offers only what its installed packages contribute.
  */
 import type { WorkspaceArrangement } from './workspace-arrangement';
 
 /**
  * Every keyboard action the editor's chrome binds. A keymap binds these and
- * nothing else; a game never reads this table (play-mode input isolation is a
+ * nothing else; a project never reads this table (play-mode input isolation is a
  * different mechanism).
  */
 export type EditorKeyActionId =
@@ -52,10 +50,8 @@ export type EditorKeyActionId =
   | 'view.focusMode'
   | 'workspace.cycleNext'
   | 'workspace.cyclePrevious'
-  /** Arm the tool that draws NO transform gizmo — Blender's Select Box, whose
-   *  3D View keymap puts it on `W` (`blender_default.py:1950-1955`,
-   *  `op_tool_cycle("builtin.select_box", …)`). This editor's own keymap binds
-   *  it to nothing: W/E/R/T are its four transform tools. */
+  /** Arm the tool that draws NO transform gizmo, a box-select tool. This editor's
+   *  own keymap binds it to nothing: W/E/R/T are its four transform tools. */
   | 'transform.select'
   | 'transform.combined'
   | 'transform.translate'
@@ -76,7 +72,7 @@ export type EditorKeyActionId =
   | 'view.back'
   | 'view.left'
   /** Step the view: orbit 15° about the world's up or the view's horizon, turn to the opposite
-   *  side, or roll 15° (Blender's `view3d.view_orbit` and `view3d.view_roll` on the numpad). */
+   *  side, or roll 15°. */
   | 'view.orbitLeft'
   | 'view.orbitRight'
   | 'view.orbitUp'
@@ -84,14 +80,13 @@ export type EditorKeyActionId =
   | 'view.opposite'
   | 'view.rollLeft'
   | 'view.rollRight'
-  /** Frame everything in the view, selected or not (Blender's `view3d.view_all`, Home). */
+  /** Frame everything in the view, selected or not. */
   | 'view.all'
-  /** Step the view nearer or farther by the keymap's zoom step (`view3d.zoom`, numpad +/-). */
+  /** Step the view nearer or farther by the keymap's zoom step. */
   | 'view.zoomIn'
   | 'view.zoomOut'
   | 'view.perspective'
-  /** Switch the view between perspective and orthographic, keeping where it looks from
-   *  (Blender's `view3d.view_persportho`, numpad 5). */
+  /** Switch the view between perspective and orthographic, keeping where it looks from. */
   | 'view.projection'
   | 'view.camera';
 
@@ -105,51 +100,51 @@ export interface KeyChord {
   readonly key: string;
   readonly code?: string;
   readonly mod?: boolean;
-  /** The Control key itself on every platform, macOS included (Blender's Ctrl), where `mod`
-   *  would be ⌘. */
+  /** The Control key itself on every platform, macOS included, where `mod` would be ⌘. */
   readonly ctrl?: boolean;
   readonly shift?: boolean;
   readonly alt?: boolean;
 }
 
-/** The chords a keymap binds for the actions it names. An action a keymap
- *  omits keeps the editor's own binding; an EMPTY list unbinds it. */
-export type KeymapBindings = Partial<Record<EditorKeyActionId, readonly KeyChord[]>>;
-
+/**
+ * A KEYMAP, named. Its chords are not here: they are its package's
+ * `contributes.keybindings`, gated on `volter.keymap == '<id>'`, over the
+ * editor's own (the built-in `volter-editor` extension). This names the keymap
+ * for the `keymap` setting and states what a keybinding cannot: the viewport's
+ * mouse.
+ */
 export interface KeymapContribution {
   /** The `keymap` settings value that selects it. */
   readonly id: string;
   readonly title: string;
   readonly description: string;
-  readonly bindings: KeymapBindings;
   /** Which mouse button orbits the viewport. Absent: the editor's own. */
   readonly navigation?: KeymapNavigation;
 }
 
 /**
  * THE VIEWPORT'S MOUSE, as a keymap states it: the button that orbits. The editor's own orbits
- * with the right button and pans with the middle; a keymap that orbits with the middle (Blender's
- * `view3d.rotate` on MIDDLEMOUSE) pans with Shift and the same button, as that keymap does.
+ * with the right button and pans with the middle; a keymap that orbits with the middle pans with
+ * Shift and the same button.
  */
 export interface KeymapNavigation {
   readonly orbit: 'middle' | 'right';
   /**
-   * The orbit as a TURNTABLE that keeps the view's roll and may pass over the top (Blender's
-   * `view3d.rotate` in Turntable mode): a sideways drag spins the view about the world's up, a
+   * The orbit as a TURNTABLE that keeps the view's roll and may pass over the top: a sideways
+   * drag spins the view about the world's up, a
    * vertical one pitches it about the horizon, each at this angle per CSS pixel. Absent: the
    * editor's own orbit, which holds the view level and stops at the poles.
    */
   readonly turntable?: { readonly degreesPerPixel: number };
   /**
-   * An orthographic view still down an axis turns perspective when a rotate starts, as Blender's
-   * Auto Perspective does (`ED_view3d_persp_ensure`); the axis views themselves are orthographic.
+   * An orthographic view still down an axis turns perspective when a rotate starts; the axis
+   * views themselves are orthographic.
    */
   readonly autoPerspective?: boolean;
   /**
-   * ZOOM: `step` is the distance factor one zoom key moves by (Blender's `view_zoom_apply_step`,
-   * 1.2); `drag: 'dolly'` makes a zoom drag Blender's Dolly style (`viewzoom_scale_value`: the
-   * distance scales by `2 · (len / len₀ − 1) + 1`, `len` the pointer's height below the region's
-   * top plus 5). Absent: the editor's own.
+   * ZOOM: `step` is the distance factor one zoom key moves by; `drag: 'dolly'` makes a zoom drag
+   * a dolly (the distance scales by `2 · (len / len₀ − 1) + 1`, `len` the pointer's height below
+   * the region's top plus 5). Absent: the editor's own.
    */
   readonly zoom?: { readonly step: number; readonly drag?: 'dolly' };
 }
@@ -164,12 +159,11 @@ export interface WorkspaceLayoutContribution {
    *  `'mounts'` (at least one root that plays) or a document kind the
    *  project's table lists. Omitted: every project. */
   readonly requires?: 'mounts' | { readonly documentKind: string };
-  /** Which chrome regions the workspace shows; absent means every region. */
+  /** Chrome region overrides; omitted regions use their defaults, including hidden workspace tabs. */
   readonly regions?: WorkspaceLayoutRegions;
   /** The workspace's EDITOR AREAS beside the centre document — a second
-   *  editor group holding a `workspace.document` contribution, the shape
-   *  Blender's own screens have (`WorkspaceAreaContribution`). Absent: the
-   *  centre document alone. */
+   *  editor group holding a `workspace.document` contribution
+   *  (`WorkspaceAreaContribution`). Absent: the centre document alone. */
   readonly areas?: WorkspaceArrangement['areas'];
 }
 
@@ -220,8 +214,8 @@ export interface DensityContribution {
     readonly '2xl'?: number;
     readonly heading?: number;
   };
-  /** Glyph sizes, independent of the type scale: Blender's chrome glyphs are
-   *  14 px whatever the text around them measures. */
+  /** Glyph sizes, independent of the type scale, so a look's chrome glyphs keep
+   *  their size whatever the text around them measures. */
   readonly icon?: {
     readonly xs?: number;
     readonly sm?: number;
@@ -236,8 +230,8 @@ export interface DensityContribution {
     readonly localToolbar?: number;
     readonly treeRow?: number;
     /** How far one level of a tree steps right. Absent keeps the editor's own
-     *  14; Blender's Outliner steps by its ROW HEIGHT — a square grid, 20 —
-     *  with the chevron owning one cell and the type glyph the next. */
+     *  14; a look that sets it to `treeRow` steps by the row's height — a
+     *  square grid, with the chevron owning one cell and the type glyph the next. */
     readonly treeIndent?: number;
     readonly statusBar?: number;
     /** The tool rail: a tool's box, its width, the gap between groups. */
@@ -245,15 +239,26 @@ export interface DensityContribution {
     readonly toolWidth?: number;
     readonly toolGap?: number;
     /** How wide the seam between two docked AREAS is cut, in px. Absent
-     *  keeps the editor's own hairline; Blender's groove measures 3.5. The
-     *  colour is the palette's `color.boundary.area`. */
+     *  keeps the editor's own hairline. The colour is the palette's
+     *  `color.boundary.area`. */
     readonly areaSeam?: number;
     /** THE EMBOSS beside that groove, as a percentage of WHITE mixed into the
      *  area's OWN fill — so it is one number and every area computes its own
-     *  colour from it. Absent (or 0) paints nothing, which is what every skin
-     *  but Blender does; Blender's measures 8.2. See `theme.ts`'s
-     *  `areaEmbossValue` for the five fills it was solved against. */
+     *  colour from it. Absent (or 0) paints nothing, the editor's own. See
+     *  `theme.ts`'s `areaEmbossValue` for how each fill computes it. */
     readonly areaEmboss?: number;
+    /** The viewport navigation cluster's button column, in px: every control
+     *  height inside the cluster. Absent keeps the editor's own 28. */
+    readonly navigationControl?: number;
+    /** The height of a tree row's disclosure caret, in px. Absent keeps the
+     *  editor's own 18. */
+    readonly treeCaret?: number;
+    /** The corner of the plate a tree draws behind the active row's type glyph
+     *  and the edited datablock's glyph, in px. Absent keeps the editor's own 5. */
+    readonly treeGlyphPlateRadius?: number;
+    /** The opacity a tree composites its type and datablock glyphs at, as a
+     *  fraction from 0 to 1. Absent keeps the editor's own 0.8. */
+    readonly treeGlyphOpacity?: number;
   };
 }
 
@@ -261,55 +266,40 @@ export interface DensityContribution {
  * WHAT A LOOK STATES ABOUT THE 3D STAGE, as opposed to about the chrome around it: how the
  * stage's furniture is drawn (sizes, widths, the selection box's form). Absent members keep
  * the editor's own. What the stage DOES — its boot tool, its box-select rule, its world's up
- * axis — is its presentation's (`@volter/sdk/kit/viewport-presentation`), never the
+ * axis — is its presentation's (`@volter/sdk/viewport-presentation`), never the
  * look's (ARCHITECTURE.md rule 7).
  */
 export interface StageContribution {
   /**
-   * THE TRANSFORM GIZMO'S SCREEN SIZE, in px per gizmo unit — Blender's
-   * `U.gizmo_size` (`DNA_userdef_types.h:1095`, default 75; Preferences ▸
-   * Viewport ▸ Gizmos ▸ Size, `rna_userdef.cc:5415-5419`).
+   * THE TRANSFORM GIZMO'S SCREEN SIZE, in px per gizmo unit.
    *
-   * A gizmo is a CONSTANT SCREEN SIZE, never a fraction of the object or of
-   * the viewport: `wm_gizmo.cc:450-474` computes
-   * `scale_final = scale_basis · UI_SCALE_FAC · U.gizmo_size ·
-   * ED_view3d_pixel_size_no_ui_scale(rv3d, origin)`, and that last term is
-   * world units per device pixel while `UI_SCALE_FAC` is device pixels per
-   * UI pixel — so one gizmo unit is exactly `U.gizmo_size` CSS px at any
+   * Set, the gizmo is a CONSTANT SCREEN SIZE, never a fraction of the object
+   * or of the viewport: one gizmo unit is exactly this many CSS px at any
    * display scale.
    *
    * Absent keeps the editor's own gizmo, which is a fraction of the
-   * VIEWPORT (three's `TransformControls` at `size` 1). What the number
-   * means on our side — three's handles are authored on a unit half
-   * Blender's — is `editor-viewport.ts`'s to know, and it says so there.
+   * VIEWPORT (the stage gizmo at `size` 1). How the number maps
+   * onto the stage gizmo's handles is `editor-viewport.ts`'s to know, and it
+   * says so there.
    */
   readonly gizmoSize?: number;
   /**
-   * THE GIZMO'S HANDLES AT REST AND HIGHLIGHTED. `gizmoOpacity` is a resting handle's opacity
-   * (a highlighted one is opaque): Blender's 0.6 (`transform_gizmo_3d.cc`,
-   * `gizmo_get_axis_color`), Godot's 0.9 (`editors/3d/manipulator_gizmo_opacity`), Unity's
-   * 0.93 (`Handles.cs`, the axis colours' alpha). A handle with no fixed highlight colour
-   * (`color.gizmo.hover`) highlights in its own axis colour with its saturation multiplied by
-   * `gizmoHighlightSaturation` and its value set to `gizmoHighlightValue`, each kept when
-   * absent: Blender keeps both, Godot's are 0.25 and 1 (`node_3d_editor_plugin.cpp`,
-   * `col.from_hsv(col.get_h(), col.get_s() * 0.25, 1.0, 1)`).
+   * Resting handle opacity; highlighted handles are opaque. When no fixed hover
+   * color is supplied, highlight uses the axis hue with the optional saturation
+   * multiplier and value override. Omitted values retain the axis color.
    */
   readonly gizmoOpacity?: number;
   /**
-   * THE MOVE ARROWS' SHAPE: `gizmoArrowLength` is how far an arrow's tip stands from the
-   * centre, in rotation-ring radii (three's own 1.2; Godot's 1.6, measured on
-   * `tuto_3d5.png` as a 142 px tip against a 90 px ring), and `gizmoArrowHead` scales its
-   * head (three's own 1; Godot's about 1.5). Which handles the tool offers is the view's
-   * (`interaction.transformHandles`), never the look's.
+   * Move-arrow length in rotation-ring radii and arrow-head scale. The view’s
+   * interaction.transformHandles chooses which handles are available.
    */
   readonly gizmoArrowLength?: number;
   readonly gizmoArrowHead?: number;
-  /** THE ROTATION RINGS' THICKNESS, as a multiple of three's own (Godot's rings are about
-   *  twice as thick, `tuto_3d5.png`). */
+  /** THE ROTATION RINGS' THICKNESS, as a multiple of the stage gizmo's own (Godot's rings
+   *  are about twice as thick, `tuto_3d5.png`). */
   readonly gizmoRingWidth?: number;
   /**
-   * THE NAVIGATION GIZMO'S FORM AND CORNER: lettered `balls` (the editor's own, Blender's and
-   * Godot's), `cones` round a centre cube (Unity's scene gizmo) or a lettered axis `triad`
+   * THE NAVIGATION GIZMO'S FORM AND CORNER: lettered `balls` (the editor's own and Godot's), `cones` round a centre cube (Unity's scene gizmo) or a lettered axis `triad`
    * (Unreal's); `top-right` (the editor's own) or `bottom-left` (Unreal's). Whether a click on
    * it turns the view is the view's (`overlays.navigation`).
    */
@@ -324,17 +314,13 @@ export interface StageContribution {
    * THE FLOOR GRID'S LINES, in device pixels: the minor lines' width, the major lines' width,
    * and how far the major lines' colour is carried past the minor's from the backdrop (1 draws
    * both levels alike). A look that states none keeps the editor's own floor, one hairline
-   * level — the grid the kit drew before its floor was fitted to Blender. Blender's are 1.5,
-   * 2.25 and 39/21, measured across one scanline of `modeling-object-none.png`: the 1 m line
-   * 4 px at half rise plateauing at 83, the 10 m line 6 px plateauing at 101
-   * (`docs/VIEWPORT-STAGE.md`: widths are the look's, like colours).
+   * level (`docs/VIEWPORT-STAGE.md`: widths are the look's, like colours).
    */
   readonly gridLineWidth?: number;
   readonly gridMajorWidth?: number;
   readonly gridMajorContrast?: number;
-  /** THE AXIS LINES' WIDTH in device pixels (the editor's own and Blender's are 2, measured
-   *  on `modeling-object-none.png`). Which axis lines show is the view's
-   *  (`overlays.axes`), never the look's. */
+  /** THE AXIS LINES' WIDTH in device pixels (the editor's own is 2). Which axis lines show is
+   *  the view's (`overlays.axes`), never the look's. */
   readonly axisLineWidth?: number;
   /**
    * HOW THE SELECTION BOX MARK IS DRAWN (the view's `overlays.selection.box`): `corners`, the
@@ -347,9 +333,9 @@ export interface StageContribution {
   readonly selectionBoxFrame?: 'world' | 'object';
   /**
    * THE SELECTION OUTLINE'S FORM: `soft`, the editor's own blurred halo, or `crisp`, a hard
-   * line `outlineWidth` device pixels wide (Blender's, Unity's and Unreal's are crisp); and
-   * whether the parts of the selection other objects hide are drawn too (`outlineHidden`,
-   * the editor's own; Unity's and Blender's are not).
+   * line `outlineWidth` device pixels wide (Unity's and Unreal's are crisp); and whether the
+   * parts of the selection other objects hide are drawn too (`outlineHidden`, the editor's
+   * own; Unity's are not).
    */
   readonly outlineStyle?: 'soft' | 'crisp';
   readonly outlineWidth?: number;
@@ -361,10 +347,8 @@ export interface StageContribution {
   /**
    * THE BOX-SELECT OUTLINE'S DASH, in device pixels: each dash this long in the palette's
    * `color.viewport.marqueeLine`, each gap as long in its `marqueeGap`. Absent draws the
-   * editor's own solid line. Blender's is 4: `wm_gesture_draw_rect` (`wm_gesture.cc`) draws the
-   * box with a `dash_width` of 8 framebuffer pixels at a `udash_factor` of 0.5, the first half
-   * of each period in its `color` and the second in its `color2`. What a box drag selects is
-   * the view's (`interaction.boxSelect`), never the look's.
+   * editor's own solid line. What a box drag selects is the view's (`interaction.boxSelect`),
+   * never the look's.
    */
   readonly marqueeDash?: number;
   /** THE STAGE'S OWN CHROME: which overlay controls the viewport carries and where. See
@@ -377,22 +361,22 @@ export interface StageContribution {
 /**
  * THE VIEWPORT'S OWN CHROME, as each target's viewport arranges it (read from the reference
  * frames, `docs/VIEWPORT-STAGE.md`): a look places the stage's controls, it never adds one.
- * Each member is independently optional; absent keeps the editor's own arrangement (Blender's:
- * the view text top-left, the tool shelf, the display controls in the top-right corner).
+ * Each member is independently optional; absent keeps the editor's own arrangement (the view
+ * text top-left, the tool shelf, the display controls in the top-right corner).
  *
  * - `bar`: a row across the stage's top. `strip` is a flush panel band (Godot's 3D toolbar,
  *   Unity's Scene view toolbar); `pills` is a row of rounded pills floating over the view
  *   (Unreal's level viewport toolbar). Absent, there is no bar.
- * - `viewName`: where the view's name is. `text` is Blender's lines at the top-left; `menu`
+ * - `viewName`: where the view's name is. `text` is lines of text at the top-left; `menu`
  *   a pill at the top-left that opens the view menu (Godot's "⋮ Perspective"); `gizmo` a label
  *   under the navigation gizmo that toggles the projection (Unity's "Persp"); `bar` the first
  *   pill of the bar, opening the view menu (Unreal's "Perspective").
- * - `tools`: the transform tools on the `shelf` (Blender's, Unity's Tools overlay) or at the
+ * - `tools`: the transform tools on the `shelf` (the editor's own, Unity's Tools overlay) or at the
  *   bar's `bar-start` (Godot) or `bar-end` (Unreal).
  * - `display`: the display controls (shading, grid, helpers, lights) in the top-right
  *   `corner` or at the bar's `bar-start` (Unity, Unreal) or `bar-end` (Godot).
  * - `transformControls`: the stage's transform controls (orientation, pivot, snap and its
- *   values) in the document's `header` (the editor's own, Blender's) or on the `bar` after the
+ *   values) in the document's `header` (the editor's own) or on the `bar` after the
  *   tools (Unreal's row: world/local, the snap values; Godot's: local space, snap).
  *
  * Whether the zoom and pan cluster and the camera readout are drawn at all is the view's
@@ -416,7 +400,7 @@ export interface StageWordsContribution {
   readonly shading?: Readonly<Partial<Record<StageShadingModeId, string>>>;
   readonly helpers?: string;
 }
-/** The stage's shading modes, by id (`@volter/editor-threejs` `viewport-shading`). */
+/** The stage's shading modes, by id (the 3D integration's `viewport-shading`). */
 export type StageShadingModeId =
   | 'solid'
   | 'clay'
@@ -433,11 +417,9 @@ export type StageShadingModeId =
  * as `var(--volter-category-<tone>, currentColor)` so a palette that names no
  * `color.category` group paints the glyph exactly as a monochrome one.
  *
- * The vocabulary is Blender's Properties-tab rail read as data: that rail
- * groups by HUE, and at 14 px the hue is what tells one tab from another
- * (`properties-object.png` — the shapes are near-indistinguishable). Each
- * member is a MEASURED ink; see `EditorTheme.color.category` for the values
- * and their source coordinates.
+ * The vocabulary is a properties rail's grouping read as data: a rail that
+ * groups by HUE, where at 14 px the hue is what tells one tab from another.
+ * A style's palette states each member's ink (`EditorTheme.color.category`).
  */
 export type IconCategoryTone =
   | 'object'
@@ -446,21 +428,11 @@ export type IconCategoryTone =
   | 'tool'
   | 'operator'
   | 'data'
-  // Blender's SCENE group and its COLLECTION, added 2026-09-19 (WORK.md
-  // §Blender in the tab is Blender, "Inspection parity", I2 decision 3). They
-  // are not a reading of the rail: every Blender icon declares its group in
-  // `UI_icons.hh` through a `DEF_ICON_<GROUP>` macro, and
-  // `interface_icons.cc:126-132` maps those onto the theme members
-  // `interface/resources.cc:1059-1078` reads — `DEF_ICON_SCENE` →
-  // `TH_ICON_SCENE` → `.tui.icon_scene` #cccccc
-  // (`userdef_default_theme.c:272`), `DEF_ICON_COLLECTION` →
-  // `.tui.icon_collection` #ffffff (`:273`). The Render, Output, View Layer
-  // and Scene tabs are `DEF_ICON_SCENE`; the Collection tab is
-  // `DEF_ICON_COLLECTION(GROUP)` (`UI_icons.hh:248`).
+  // The scene-level tabs' group and the collection group.
   | 'scene'
   | 'collection'
-  // The SELECTION TOOLS' marquee, which Blender bakes into their tool icons' geometry
-  // (`ops.generic.select_box`) rather than reading from a theme member.
+  // The SELECTION TOOLS' marquee, drawn into their tool icons' geometry rather than read
+  // from a theme member.
   | 'select';
 
 /**
@@ -470,15 +442,13 @@ export type IconCategoryTone =
  * A set may be partial — a glyph it lacks paints the editor's own.
  *
  * `tone` and `tonedPath` are the COLOUR channel, and they are two shapes of
- * one idea because Blender draws two shapes of it:
+ * one idea because a set may draw two shapes of it:
  *
  *  - `tone` alone tints the WHOLE glyph — the Properties rail's category
  *    tabs and the outliner's type glyphs, where the mark IS the category.
  *  - `tone` with `tonedPath` splits the glyph in two: `path` stays neutral
  *    (`currentColor`) and `tonedPath` takes the category ink. That is
- *    exactly how an operator mark reads in `modeling-edit-none.png` — the
- *    cube stays white and only the OPERATED element is tinted — and a
- *    single per-glyph tone cannot express it.
+ *    how a mark can keep its base neutral while tinting the operated element.
  *
  * Either way an explicit `tone` prop at the SITE wins, so a de-emphasized
  * (`dim`/`muted`) glyph stays de-emphasized.
@@ -502,9 +472,9 @@ export interface IconSetContribution {
 export interface StyleContribution {
   readonly id: string;
   readonly title: string;
-  /** A palette id the editor knows — a built-in, or the `palette` document
-   *  this contribution carries. */
-  readonly paletteId: string;
+  /** The colour theme this style was drawn with (`contributes.themes`), which choosing the
+   *  style applies (docs/adr/looks-one-model.md). */
+  readonly colorTheme: string;
   /** A material id the editor knows — `classic`, `glass`, or the `material`
    *  this contribution carries. */
   readonly materialId: string;
@@ -513,7 +483,6 @@ export interface StyleContribution {
    *  editor knows. Absent: the editor's own glyphs. */
   readonly iconSetId?: string;
   readonly icons?: IconSetContribution;
-  /** A v3 palette DOCUMENT (the same shape a person imports), registered into
-   *  the editor's theme library with this bundle. */
-  readonly palette?: unknown;
+  /** The style's type families; absent, the editor's own. */
+  readonly typography?: { readonly sans: string; readonly mono: string };
 }

package/src/adapter/finders/registry.ts

@@ -1,13 +1,7 @@
 /**
- * THE FINDER REGISTRY — the open set of finders an adapter may SELECT by
- * name (ARCHITECTURE-CORE §The editor protocol, "Documents, not scenes").
- *
- * A finder is a pure function from the project's gathered source to document
- * entries, plus the Zod schema of its own parameters. The engine registers
- * its two here (`./index.ts`); a contribution registers more through the
- * same door. `adapter-module.ts` validates only the selection ENVELOPE; the
- * parameters are checked against the finder's schema when the loader runs
- * it — an unregistered name or a bad parameter refuses loudly, naming both.
+ * Finders selected by name, registered by integrations. Each registration supplies a pure
+ * function over gathered project files and a parameter schema. Adapter definitions validate
+ * the selection envelope; runRegisteredFinder validates its parameters against this registry.
  */
 
 import type { ZodType } from 'zod';
@@ -27,15 +21,7 @@ export interface FinderRegistration<
    *  same rule as every other adapter table. */
   readonly schema: ZodType<S>;
   readonly run: (selection: S, input: I) => FinderResult;
-  /**
-   * WHAT OF THE MATCHED PROJECT IT READS. `sources` (the default) is the text of every file
-   * under the selection's `include` globs (`input.sources`) and their paths; `files` is the
-   * paths alone (`input.files`). A finder over BINARY documents says `files`, so the host never
-   * fetches a file it could not hand over as text: `@volter/editor-blender`'s
-   * `modelsFromBlendFiles` lists `.blend` files, and reading each one through the text-source
-   * route asked a multi-megabyte binary of a route capped at 2 MiB of text — a
-   * `413 Payload Too Large` per model per resolve, for bytes nothing would have read.
-   */
+  /** sources reads matching file text and paths; files reads paths alone, including binary assets. */
   readonly reads?: 'sources' | 'files';
 }
 
@@ -54,9 +40,8 @@ export function registerFinder<S extends FinderSelectionEnvelope, I>(
 }
 
 /**
- * What a CONTRIBUTION exports to register a finder (ARCHITECTURE-CORE §The
- * project model): a plain object a project module `editor/contributions/<name>.finder.ts`
- * exports as `finder`, handed by the HOST to {@link registerContributedFinder}.
+ * What a CONTRIBUTION exports to register a finder: a plain object a package's finder module
+ * (`contributes.volter.finders`) exports as `finder`, handed by the HOST to {@link registerContributedFinder}.
  * A selection may carry `include` globs; the host then supplies the matching
  * project sources on `input.sources`, which is how a finder reads the
  * project without a file system.

package/src/adapter/host-context.ts

@@ -4,7 +4,7 @@
  */
 import type { AdapterSurface } from './adapter-surface';
 
-/** The canvas/container the game renders into, plus its size. */
+/** The canvas/container the project renders into, plus its size. */
 export interface HostSurface {
   readonly canvas: HTMLCanvasElement;
   readonly width: number;
@@ -12,36 +12,15 @@ export interface HostSurface {
 }
 
 /**
- * The surface-INDEPENDENT half of every host context — see this file's header
- * for ownership of product-specific extensions. Generic host code (a
- * harness, a tier report, anything that must not care what it is mounting) can
- * type against this; a real adapter always receives one of the per-surface
- * contexts below.
+ * What a `stage`-surface root is handed. This is the ONLY context carrying
+ * the stage's own objects — the split's entire point (see the header): a canvas
+ * or React root is never handed a GPU renderer it cannot use. The objects are
+ * opaque here; a runtime extends the context with its own types.
  */
-export interface HostContextBase {
-  /**
-   * No GPU/DOM/audio available (Node conformance tests). A first-party adapter
-   * skips postprocessing/render/audio/input-map loading but still builds the
-   * scene + Rapier + components, so its scene/authoring/physics can be exercised
-   * headlessly. Browser hosts leave this false/undefined → full behavior.
-   */
-  readonly headless?: boolean;
-}
-
-/**
- * What a `three`-surface root is handed. This is the ONLY context carrying
- * three's own objects — the split's entire point (see the header): a Pixi or
- * React root is never handed a `WebGLRenderer` it cannot use. The objects are
- * opaque here; `@volter/editor-threejs` names the Three-typed context, and a
- * runtime names its own.
- */
-export interface ThreeHostContext<Three = unknown, Renderer = unknown, Assets = unknown>
-  extends HostContextBase {
-  /** The ONE shared three instance — identity matters for capture (see ingest). */
-  readonly three: Three;
-  /** Canvas/container + size; a self-driven game may take the surface over. */
+export interface StageHostContext<Renderer = unknown, Assets = unknown> {
+  /** Canvas/container + size; a self-driven project may take the surface over. */
   readonly surface: HostSurface;
-  /** Host renderer — host-driven games render through it. */
+  /** Host renderer — host-driven projects render through it. */
   readonly renderer: Renderer;
   /** Shared GLTF/texture cache. */
   readonly assets: Assets;
@@ -49,51 +28,17 @@ export interface ThreeHostContext<Three = unknown, Renderer = unknown, Assets =
 
 /**
  * What a `canvas`-surface root is handed: a raw canvas + its
- * logical size, plus the
- * compositing hints the multi-root host computes once for every stacked
- * surface. No `three`, no `renderer`, no `assets` — a Pixi root builds its own
- * `PIXI.Application` and its own asset cache from this.
+ * logical size. No stage library, no `renderer`, no `assets` — a canvas root builds its own
+ * library's application and its own asset cache from this.
  */
-export interface CanvasHostContext extends HostContextBase {
+export interface CanvasHostContext {
   readonly canvas: HTMLCanvasElement;
   readonly width: number;
   readonly height: number;
-  /** DPR override (T6.1 slice 1, D5 §3 — "one DPR
-   *  everywhere"): the roots-path host computes ONE dpr for every stacked
-   *  surface and passes it here; omitted -> the canvas adapter's own
-   *  default (`window.devicePixelRatio`, uncapped). */
-  readonly dpr?: number;
-  /** This root is stacked ABOVE another root (D5 §1): clear with alpha 0
-   *  instead of an opaque background so the layer below shows through. */
-  readonly transparent?: boolean;
-  /** Capture tier cost (D5 §4) — the renderer's `preserveDrawingBuffer`. */
-  readonly preserveDrawingBuffer?: boolean;
 }
 
-/**
- * What a `dom`-surface root is handed (the shape `runtime/create-runtime.ts`
- * used to spell `ReactRootHost`).
- *
- * `container` is the absolutely-positioned, z-ordered DOM-root layer `<div>`
- * the host already created and stacked (same box/z-order rules as a canvas per
- * D5 §1) — the adapter's `mount` renders its react tree INTO
- * this exact element via `createRoot`; it must never create its own root
- * element (the DOM analog of three's "the root's runtime renders into the
- * surface it is handed" rule).
- *
- * `game` (inherited, and deliberately still optional): a
- * `default-react` sibling mounted BESIDE an ingest root (`packages/editor/src/
- * ingest-siblings.ts`) has no native `Game` to hand it — there is no
- * first-party loop for the sibling to join, only the ingested
- * root's own foreign runtime — so its host carries no `game` at all rather than
- * fabricating an empty one (anti-shim rule); the sibling mounts its entry
- * component bare, as every `dom` root renders. `mountOneReactRoot`
- * (`runtime/create-runtime.ts`, the NATIVE multi-root runtime path) still
- * ALWAYS supplies a real `game` — this optionality is reached only by the
- * composite sibling's own hand-built host, never by weakening the native path's
- * guarantee.
- */
-export interface DomHostContext extends HostContextBase {
+/** A DOM root mounts into the host-owned, absolutely positioned layer. */
+export interface DomHostContext {
   readonly container: HTMLElement;
 }
 
@@ -102,11 +47,11 @@ export interface DomHostContext extends HostContextBase {
  * handed — the mirror image of `MountedRootFor<K>` (`root-adapter.ts`), and
  * what makes `RootAdapter<K>.mount`'s PARAMETER K-typed. A hypothetical 4th
  * surface resolves to `never` here, so it cannot be mounted until it declares
- * its own context (the same fail-to-compile discipline `assertNever` gives the
- * dispatch sites).
+ * its own context (the same fail-to-compile discipline an exhaustive switch
+ * gives a dispatch site).
  */
-export type HostContextFor<K extends AdapterSurface> = K extends 'three'
-  ? ThreeHostContext
+export type HostContextFor<K extends AdapterSurface> = K extends 'stage'
+  ? StageHostContext
   : K extends 'canvas'
     ? CanvasHostContext
     : K extends 'dom'