@pascal-app/core 1.0.0-beta.5 → 1.0.0

package/dist/registry/registry.js

@@ -108,6 +108,31 @@ class NodeRegistryImpl {
         inspectorExtensionsByKind.clear();
         notifyRegistryChanged();
     }
+    // Test-only — captures the registry (definitions + plugin bookkeeping) and
+    // returns a restore function. The registry is a module singleton and bun
+    // runs a package's test files sequentially in ONE process, so a test that
+    // registers a throwaway kind (or `_reset()`s) without restoring leaks that
+    // state into every later test FILE — and file order varies by platform
+    // (macOS vs CI Linux), which turns the leak into an order-dependent flake.
+    // Wrap registry mutations in `const restore = nodeRegistry._snapshot()`
+    // + `restore()` in `afterEach`/`finally`.
+    _snapshot() {
+        const defs = new Map(this.defs);
+        const pluginIds = new Map(pluginIdsByKind);
+        const extensions = new Map(Array.from(inspectorExtensionsByKind, ([kind, list]) => [kind, [...list]]));
+        return () => {
+            this.defs.clear();
+            for (const [kind, def] of defs)
+                this.defs.set(kind, def);
+            pluginIdsByKind.clear();
+            for (const [kind, id] of pluginIds)
+                pluginIdsByKind.set(kind, id);
+            inspectorExtensionsByKind.clear();
+            for (const [kind, list] of extensions)
+                inspectorExtensionsByKind.set(kind, [...list]);
+            notifyRegistryChanged();
+        };
+    }
 }
 export const nodeRegistry = new NodeRegistryImpl();
 export function registerNode(def) {
@@ -165,12 +190,20 @@ export function getSelectableKinds() {
 export function isRegistrySelectable(kind) {
     return nodeRegistry.get(kind)?.capabilities.selectable !== undefined;
 }
+/**
+ * Whether the editor should apply its material-based selection highlight to a
+ * kind. Selection highlighting is enabled by default, including for legacy or
+ * unregistered kinds; definitions may explicitly opt out.
+ */
+export function isSelectionHighlightEnabled(kind) {
+    return nodeRegistry.get(kind)?.capabilities.selectionHighlight !== false;
+}
 /**
  * Kinds whose `def.floorplanScope` matches the requested scope. Used by
- * `FloorplanRegistryLayer` to discover building-scoped kinds (e.g.
- * elevator) without hardcoding kind names in the editor layer. `'level'`
- * is the default, so `kindsWithFloorplanScope('level')` includes kinds
- * that didn't set the field at all.
+ * `FloorplanRegistryLayer` to discover building- and site-scoped kinds
+ * without hardcoding kind names in the editor layer. `'level'` is the
+ * default, so `kindsWithFloorplanScope('level')` includes kinds that
+ * didn't set the field at all.
  */
 export function kindsWithFloorplanScope(scope) {
     const result = [];

package/dist/registry/scene-api.d.ts

@@ -16,10 +16,26 @@ export type SceneStoreLike = {
             node: AnyNode;
             parentId?: AnyNodeId;
         }[]) => void;
+        applyNodeChanges?: (changes: {
+            create?: {
+                node: AnyNode;
+                parentId?: AnyNodeId;
+            }[];
+            update?: {
+                id: AnyNodeId;
+                data: Partial<AnyNode>;
+            }[];
+            delete?: AnyNodeId[];
+        }) => void;
         updateNode: (id: AnyNodeId, data: Partial<AnyNode>) => void;
         deleteNode: (id: AnyNodeId) => void;
         markDirty: (id: AnyNodeId) => void;
     };
+    subscribe?: (listener: (state: {
+        nodes: Record<AnyNodeId, AnyNode>;
+    }, previous: {
+        nodes: Record<AnyNodeId, AnyNode>;
+    }) => void) => () => void;
     temporal: {
         getState: () => {
             pause: () => void;

package/dist/registry/scene-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-api.d.ts","sourceRoot":"","sources":["../../src/registry/scene-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAOzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,MAAM;QACd,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QACjC,WAAW,EAAE,SAAS,EAAE,CAAA;QACxB,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,CAAA;QAC1B,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,KAAK,IAAI,CAAA;QACzD,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;SAAE,EAAE,KAAK,IAAI,CAAA;QACtE,UAAU,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;QAC3D,UAAU,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAA;QACnC,SAAS,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAA;KACnC,CAAA;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM;YAAE,KAAK,EAAE,MAAM,IAAI,CAAC;YAAC,MAAM,EAAE,MAAM,IAAI,CAAA;SAAE,CAAA;KAC1D,CAAA;CACF,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,QAAQ,CAgG9D"}
+{"version":3,"file":"scene-api.d.ts","sourceRoot":"","sources":["../../src/registry/scene-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAWzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,MAAM;QACd,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QACjC,WAAW,EAAE,SAAS,EAAE,CAAA;QACxB,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,CAAA;QAC1B,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,KAAK,IAAI,CAAA;QACzD,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;SAAE,EAAE,KAAK,IAAI,CAAA;QACtE,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE;YAC3B,MAAM,CAAC,EAAE;gBAAE,IAAI,EAAE,OAAO,CAAC;gBAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;aAAE,EAAE,CAAA;YAClD,MAAM,CAAC,EAAE;gBAAE,EAAE,EAAE,SAAS,CAAC;gBAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;aAAE,EAAE,CAAA;YACpD,MAAM,CAAC,EAAE,SAAS,EAAE,CAAA;SACrB,KAAK,IAAI,CAAA;QACV,UAAU,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;QAC3D,UAAU,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAA;QACnC,SAAS,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAA;KACnC,CAAA;IACD,SAAS,CAAC,EAAE,CACV,QAAQ,EAAE,CACR,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;KAAE,EAC5C,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;KAAE,KAC5C,IAAI,KACN,MAAM,IAAI,CAAA;IACf,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM;YAAE,KAAK,EAAE,MAAM,IAAI,CAAC;YAAC,MAAM,EAAE,MAAM,IAAI,CAAA;SAAE,CAAA;KAC1D,CAAA;CACF,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,QAAQ,CAwI9D"}

package/dist/registry/scene-api.js

@@ -1,4 +1,4 @@
-import { pauseSceneHistory, resumeSceneHistory } from '../store/history-control';
+import { activeSceneCommitNodeIds, pauseSceneHistory, resumeSceneHistory, } from '../store/history-control';
 import { collectSubtree, cloneNodesInto as runCloneNodesInto, } from './subtree';
 /**
  * Creates a {@link SceneApi} backed by a store.
@@ -37,6 +37,54 @@ export function createSceneApi(store) {
             store.getState().createNode(node, parentId);
             return node.id;
         },
+        createMany(ops) {
+            for (const op of ops)
+                captureIfNeeded(op.node.id);
+            const batch = store.getState().createNodes;
+            if (batch)
+                batch(ops);
+            else
+                for (const op of ops)
+                    this.upsert(op.node, op.parentId);
+        },
+        applyChanges(changes) {
+            for (const op of changes.create ?? [])
+                captureIfNeeded(op.node.id);
+            for (const op of changes.update ?? [])
+                captureIfNeeded(op.id);
+            for (const id of changes.delete ?? [])
+                captureIfNeeded(id);
+            const batch = store.getState().applyNodeChanges;
+            if (batch) {
+                batch(changes);
+                return;
+            }
+            for (const op of changes.create ?? [])
+                this.upsert(op.node, op.parentId);
+            for (const op of changes.update ?? [])
+                this.update(op.id, op.data);
+            for (const id of changes.delete ?? [])
+                this.delete(id);
+        },
+        subscribeNodes(listener) {
+            return (store.subscribe?.((state, previous) => {
+                if (state.nodes === previous.nodes)
+                    return;
+                const scopedIds = activeSceneCommitNodeIds();
+                const changedIds = new Set(scopedIds);
+                if (!scopedIds) {
+                    for (const id of Object.keys(state.nodes)) {
+                        if (state.nodes[id] !== previous.nodes[id])
+                            changedIds.add(id);
+                    }
+                    for (const id of Object.keys(previous.nodes)) {
+                        if (!(id in state.nodes))
+                            changedIds.add(id);
+                    }
+                }
+                listener(state.nodes, previous.nodes, changedIds);
+            }) ?? (() => { }));
+        },
         delete(id) {
             captureIfNeeded(id);
             store.getState().deleteNode(id);

package/dist/registry/types.d.ts

@@ -2,6 +2,7 @@ import type { ComponentType } from 'react';
 import type { AnimationClip, BufferGeometry, Object3D, Ray } from 'three';
 import type { ZodObject, z } from 'zod';
 import type { MaterialSchema, MaterialTarget } from '../schema/material';
+import type { AssetInput, ItemNode } from '../schema/nodes/item';
 import type { MeasurementFeatureReference, MeasurementPoint } from '../schema/nodes/measurement';
 import type { SceneMaterial, SceneMaterialId } from '../schema/scene-material';
 import type { AnyNode, AnyNodeId } from '../schema/types';
@@ -60,6 +61,9 @@ export type GeometryContext = {
     materials?: Record<SceneMaterialId, SceneMaterial>;
     /** Opaque host/plugin context. Core never interprets extension values. */
     extensions?: Readonly<Record<string, unknown>>;
+    /** Read-only scene snapshot for pure floor-plan builders that need to
+     *  inspect cross-kind spatial relationships such as connected ports. */
+    sceneNodes?: Readonly<Record<AnyNodeId, AnyNode>>;
     /**
      * Optional view state — only populated for `def.floorplan` builders. The
      * 2D floor-plan layer surfaces selection / hover here so kinds can vary
@@ -191,6 +195,8 @@ export type DimensionTextPosition = 'above' | 'centered';
 export type FloorplanStyle = {
     stroke?: string;
     fill?: string;
+    /** Winding rule for compound paths. `evenodd` keeps nested contour rings hollow. */
+    fillRule?: 'nonzero' | 'evenodd';
     strokeWidth?: number;
     strokeDasharray?: string;
     opacity?: number;
@@ -264,6 +270,8 @@ export type ToolHint = {
      * so the HUD reflects reality. Omit for always-shown hints.
      */
     minDraftVertices?: number;
+    /** Optional live predicate for hints that only apply in one tool sub-mode. */
+    visible?: ToolHintVisibility;
     /**
      * Render this hint as a live mode chip — like the snapping / continuation
      * chips — instead of a static key row: the HUD shows the current value's
@@ -273,6 +281,12 @@ export type ToolHint = {
      */
     chip?: ToolHintChip;
 };
+export type ToolHintVisibility = {
+    /** Subscribe to changes that may alter `value`. */
+    subscribe: (onChange: () => void) => () => void;
+    /** Whether the helper should render this hint now. */
+    value: () => boolean;
+};
 export type ToolHintChip = {
     /** Subscribe to live value changes (Zustand-store-like); returns unsubscribe. */
     subscribe: (onChange: () => void) => () => void;
@@ -288,6 +302,30 @@ export type ToolHintChip = {
     /** Hover tooltip, e.g. 'Placement type — click or press I to cycle'. */
     tooltip?: string;
 };
+export type FloorplanScope = 'level' | 'building' | 'site';
+export type ToolOptionChoice = {
+    /** Value token, e.g. 'draw'. */
+    value: string;
+    /** Button label. Sentence case. */
+    label: string;
+    /** Helper line shown under the row while this choice is active. */
+    description?: string;
+};
+export type ToolOption = {
+    /** Stable row id within the kind, e.g. 'footprintSource'. */
+    id: string;
+    /** Row label. Sentence case, e.g. 'Create from'. */
+    label: string;
+    choices: readonly ToolOptionChoice[];
+    /** Subscribe to live value changes (Zustand-store-like); returns unsubscribe. */
+    subscribe: (onChange: () => void) => () => void;
+    /** Current value token. */
+    value: () => string;
+    /** Select a choice. Pure state write — arming the tool is the host's job. */
+    set: (value: string) => void;
+    /** Optional live predicate — e.g. the roof's 'Create from' hides for conical. */
+    visible?: ToolHintVisibility;
+};
 export type FloorplanGeometry = ({
     kind: 'path';
     d: string;
@@ -460,6 +498,7 @@ export type FloorplanGeometry = ({
  | {
     kind: 'midpoint-handle';
     point: FloorplanPoint;
+    activation?: 'drag' | 'action';
     affordance: string;
     payload: unknown;
 }
@@ -707,6 +746,8 @@ export type FloorplanAffordance<N> = {
         initialPlanPoint: FloorplanAffordancePoint;
         /** Active editor grid step in meters. */
         gridSnapStep: number;
+        /** Injected mutation/read seam for kind-owned affordances. */
+        sceneApi?: SceneApi;
     }): FloorplanAffordanceSession;
 };
 export type FloorplanMoveTargetSession = {
@@ -757,6 +798,7 @@ export type FloorplanMoveTargetSession = {
 export type FloorplanMoveTarget<N> = (args: {
     node: N;
     nodes: Record<AnyNodeId, AnyNode>;
+    sceneApi?: SceneApi;
 }) => FloorplanMoveTargetSession;
 /**
  * A plugin-contributed section for the floating node inspector card.
@@ -855,6 +897,13 @@ export type NodeDefinition<S extends ZodObject<any>> = {
      * Kinds outside any distribution system leave this unset.
      */
     distributionRole?: DistributionRole;
+    /** Optional behavior while the kind's click-to-click construction tool is active. */
+    drafting?: {
+        /** Raycast architectural hosts and emit their semantic surface data with grid events. */
+        surfaceQuery?: boolean;
+        /** Cancel the in-flight draft before applying an undo or redo history jump. */
+        cancelOnHistoryJump?: boolean;
+    };
     /**
      * When `distributionRole` is `'fitting'`, controls whether this fitting
      * is dragged as a rigid follower when a connected run endpoint moves.
@@ -886,6 +935,27 @@ export type NodeDefinition<S extends ZodObject<any>> = {
     dirtyTracking?: boolean;
     /** GLB bake treatment for this kind (default `'static'`). See {@link BakePolicy}. */
     bake?: BakePolicy;
+    /**
+     * Optional export-only geometry builder. The GLB exporter calls this against
+     * persisted scene data and replaces the registered node's cloned subtree
+     * with the returned local-space Object3D. The live editor object is never
+     * passed to the hook or mutated.
+     *
+     * Use this when the live geometry is unsuitable for a portable GLB (for
+     * example, a procedural NodeMaterial that masks a maximum candidate
+     * population on the GPU). The returned tree must be a complete static
+     * snapshot for this node and use exporter-supported Three.js materials.
+     */
+    bakeGeometry?: BakeGeometryBuilder<z.infer<S>>;
+    /**
+     * Optional asynchronous export-only geometry builder for textured static artifacts.
+     * Export preparation awaits this exactly once in place of {@link bakeGeometry}.
+     * Synchronous geometry-only callers continue to use `bakeGeometry`.
+     *
+     * The returned tree follows the same ownership contract: it is detached,
+     * local-space, complete for the node, and owned by the export artifact.
+     */
+    bakeGeometryAsync?: BakeGeometryAsyncBuilder<z.infer<S>>;
     /**
      * Renderer for this kind. Optional under the three-checkbox composition
      * model (see `wiki/architecture/node-definitions.md`): when omitted, the
@@ -979,8 +1049,9 @@ export type NodeDefinition<S extends ZodObject<any>> = {
     /**
      * Pure 2D builder for floor-plan rendering. Mirrors `geometry` but emits
      * plain `FloorplanGeometry` data (SVG-renderable) rather than three.js
-     * Object3D. Coordinates are level-local meters — the floor-plan panel
-     * applies the world→SVG transform.
+     * Object3D. Level- and building-scoped builders emit building-local metres.
+     * Site-scoped builders emit site-local metres; the floor-plan layer projects
+     * their output into the active building's plan coordinates.
      *
      * Returns `null` when the kind shouldn't appear in floor plan (e.g. an
      * invisible utility node, or a kind that's 3D-only). Kinds that need
@@ -1005,8 +1076,11 @@ export type NodeDefinition<S extends ZodObject<any>> = {
      * building). For `'building'`-scoped kinds the layer iterates every
      * instance whose parent matches the active level's building, and
      * synthesises a `GeometryContext` whose `parent` is the active level.
+     * `'site'` discovers direct children of the active building's Site,
+     * supplies the real Site as `ctx.parent`, and projects site-local output
+     * into the active building's plan coordinates below level architecture.
      */
-    floorplanScope?: 'level' | 'building';
+    floorplanScope?: FloorplanScope;
     /**
      * 2D drag affordances keyed by the string identifier emitted on
      * `endpoint-handle` (and similar interactive floor-plan primitives) via
@@ -1170,6 +1244,12 @@ export type NodeDefinition<S extends ZodObject<any>> = {
      * its bespoke helper component instead.
      */
     toolHints?: ToolHint[];
+    /**
+     * Pick-one option rows for this kind's build tool, rendered by the shared
+     * `<ToolOptionsPanel>` in whichever sidebar the host mounts it (see
+     * `ToolOption`). E.g. the roof's 'Create from: Draw / Room'.
+     */
+    toolOptions?: readonly ToolOption[];
     /**
      * Which snapping profile this kind uses, so the editor's contextual snapping
      * HUD + snap math + force-place affordance are node-declared rather than
@@ -1285,6 +1365,8 @@ export type Presentation = {
     icon: IconRef;
     /** Tool palette section. Defaults to `category` when omitted. */
     paletteSection?: 'site' | 'structure' | 'furnish';
+    /** Optional presentation-only subgroup used by palette surfaces. */
+    paletteGroup?: string;
     /** Sort key within a palette section; lower numbers come first. */
     paletteOrder?: number;
     /** Set true for kinds that exist but should NOT appear in the palette
@@ -1293,6 +1375,9 @@ export type Presentation = {
     /** Set false when selection is edited directly through in-scene affordances
      * and the generic floating action menu would duplicate or conflict with them. */
     actionMenu?: boolean;
+    /** Set false to drop the "Find in catalog" action for this kind — for nodes
+     * that are placed through a plugin panel rather than a browsable catalog. */
+    findInCatalog?: boolean;
 };
 export type IconRef = 
 /** Iconify identifier, e.g. `lucide:square`. Matches the @iconify-react
@@ -1352,6 +1437,8 @@ export type BakeReplaceRenderer<N> = {
         }>;
     }>;
 };
+export type BakeGeometryBuilder<N> = (node: N, ctx: GeometryContext) => Object3D;
+export type BakeGeometryAsyncBuilder<N> = (node: N, ctx: GeometryContext) => Promise<Object3D>;
 export type AssetRef = {
     id: string;
     src: string;
@@ -1392,10 +1479,18 @@ export type Capabilities = {
     cuttable?: CuttableConfig;
     snappable?: SnappableConfig;
     surfaces?: SurfacesConfig;
+    faceHost?: FaceHostCapability<any>;
     duplicable?: boolean | DuplicableConfig;
     deletable?: boolean;
     groupable?: boolean;
     selectable?: SelectableConfig;
+    /**
+     * Whether selecting this kind should replace its rendered mesh materials
+     * with the editor's selection tint. Defaults to `true`. Set to `false` for
+     * hidden interaction nodes whose rendered geometry must retain its authored
+     * materials while the node remains selected (for example, paint layers).
+     */
+    selectionHighlight?: boolean;
     interactive?: boolean;
     floorPlaced?: FloorPlacedConfig;
     /**
@@ -1771,6 +1866,8 @@ export type CapabilityCtx = {
 export type MovableConfig = {
     axes: ReadonlyArray<'x' | 'y' | 'z'>;
     gridSnap?: boolean;
+    /** Allow an ordinary primary-button body drag to enter the move tool. */
+    directDrag?: boolean;
     /**
      * Pin the dragged node to the cursor (absolute placement) instead of the
      * default offset-preserving drag, where the node moves by the cursor's
@@ -1806,11 +1903,34 @@ export type MovableConfig = {
     parentFrame?: MovableParentFrame;
     /**
      * Optional group-move snap for the generic multi-selection translate gizmo.
-     * Returns an adjusted candidate position for this node when the moving group
-     * should magnetically settle onto a nearby feature (for example, a cabinet
-     * run snapping flush to a wall while the whole selected kitchen moves as one).
+     * Returns an adjusted candidate position for this node when the moving
+     * group should magnetically settle onto a nearby feature.
      */
     groupMoveSnap?: (args: GroupMoveSnapArgs) => [number, number, number] | null;
+    /**
+     * Optional rotation-aware group-move snap. This is additive to the original
+     * `groupMoveSnap` contract so existing v1 plugins remain valid.
+     */
+    groupMoveSnapPose?: (args: GroupMoveSnapArgs) => GroupMoveSnapResult | null;
+    /**
+     * Optional kind-owned validity check for the final planar drag pose. This
+     * complements `floorPlaced` collision checks for constraints that depend
+     * on other scene geometry, such as a cabinet crossing a wall opening.
+     */
+    isValidPosition?: (args: {
+        node: AnyNode;
+        position: readonly [number, number, number];
+        rotation: number;
+        levelId: AnyNodeId | null;
+        nodes: Readonly<Record<string, AnyNode>>;
+    }) => boolean;
+    /**
+     * Kind-owned grid resolver for a planar move. Unlike scalar grid snapping,
+     * this receives the complete candidate pose so a kind can snap a visible
+     * footprint edge (including a local bounds offset and rotation) rather than
+     * blindly rounding its stored origin.
+     */
+    gridSnapPosition?: (args: GridSnapPositionArgs) => [number, number, number];
     override?: (ctx: CapabilityCtx) => MovableConfig | null;
 };
 export type MovableParentFrame = {
@@ -1837,6 +1957,24 @@ export type MovableParentFrame = {
     magneticSnap?: (node: AnyNode, parent: AnyNode, local: readonly [number, number, number], nodes: Readonly<Record<string, AnyNode>>) => [number, number, number];
     /** Optional snap-line matches for the parent-frame magnetic snap result. */
     magneticSnapMatches?: (node: AnyNode, parent: AnyNode, local: readonly [number, number, number], snappedLocal: readonly [number, number, number], nodes: Readonly<Record<string, AnyNode>>) => ParentFrameSnapMatch[];
+    /** Optional kind-owned live patches for derived nodes that follow the move. */
+    previewOverrides?: (args: {
+        node: AnyNode;
+        parent: AnyNode;
+        position: readonly [number, number, number];
+        sceneApi: SceneApi;
+    }) => ReadonlyArray<readonly [AnyNodeId, Partial<AnyNode>]>;
+    /**
+     * Optional live collision check for a child moving in the parent frame.
+     * The generic move tool uses this to colour the drag bounds and reject an
+     * invalid drop; the kind owns the actual domain rule.
+     */
+    isValidPosition?: (args: {
+        node: AnyNode;
+        parent: AnyNode;
+        position: readonly [number, number, number];
+        nodes: Readonly<Record<string, AnyNode>>;
+    }) => boolean;
     /**
      * Called after a move of the child commits, with the LIVE (post-commit)
      * child and parent. Lets the kind run derived-state maintenance the
@@ -1860,10 +1998,19 @@ export type ParentFrameSnapMatch = {
 export type GroupMoveSnapArgs = {
     node: AnyNode;
     candidatePosition: [number, number, number];
+    candidateRotation?: number;
     movingIds: readonly AnyNodeId[];
     nodes: Readonly<Record<string, AnyNode>>;
     levelId: AnyNodeId | null;
 };
+export type GroupMoveSnapResult = {
+    position: [number, number, number];
+    rotation?: number;
+};
+export type GridSnapPositionArgs = Omit<GroupMoveSnapArgs, 'candidateRotation'> & {
+    candidateRotation: number;
+    gridStep: number;
+};
 export type LiveTransformLike = {
     position: [number, number, number];
     rotation: number;
@@ -1897,7 +2044,9 @@ export type SnappableConfig = {
 export type SnapPointKind = 'start' | 'end' | 'midpoint' | 'center' | 'corners';
 export type SurfacesConfig = {
     top?: {
-        height: number | ((n: AnyNode) => number);
+        height: number | ((n: AnyNode, context: {
+            nodes: Record<string, AnyNode>;
+        }) => number);
     };
     sides?: {
         faces: 'all' | ReadonlyArray<readonly [number, number, number]>;
@@ -1909,6 +2058,43 @@ export type SurfacePoint = {
     position: readonly [number, number, number];
     normal: readonly [number, number, number];
 };
+export type FaceHostPlacementArgs<N extends AnyNode = AnyNode> = {
+    host: N;
+    asset: AssetInput;
+    draftItem: ItemNode | null;
+    localPosition: readonly [number, number, number];
+    faceIndex?: number;
+    object: Object3D;
+    currentFaceId?: string | null;
+    rawDimensions: readonly [number, number, number];
+    dimensions: readonly [number, number, number];
+    snapScalar: (value: number) => number;
+};
+export type FaceHostStoredPlacementArgs<N extends AnyNode = AnyNode> = {
+    host: N;
+    item: ItemNode;
+    position: readonly [number, number, number];
+};
+export type FaceHostStoredValidityArgs<N extends AnyNode = AnyNode> = {
+    host: N;
+    item: ItemNode;
+    asset: AssetInput;
+};
+export type FaceHostPlacementResult = {
+    faceId: string;
+    nodeUpdate: Partial<ItemNode>;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    cursorPosition: [number, number, number];
+    cursorRotation: [number, number, number];
+};
+export type FaceHostCapability<N extends AnyNode = AnyNode> = {
+    currentFaceId: (item: ItemNode | null) => string | null;
+    clearItemFields: readonly (keyof ItemNode)[];
+    resolvePlacement: (args: FaceHostPlacementArgs<N>) => FaceHostPlacementResult | null;
+    storedPlacementPatch: (args: FaceHostStoredPlacementArgs<N>) => Partial<ItemNode> | null;
+    isStoredPlacementValid: (args: FaceHostStoredValidityArgs<N>) => boolean;
+};
 export type SelectableConfig = {
     hitVolume?: 'bbox' | 'mesh' | 'none';
     override?: (ctx: CapabilityCtx) => SelectableConfig | null;
@@ -1998,7 +2184,7 @@ export type ParametricDescriptor<N> = {
      * Direct store/MCP writes bypass it — keep real invariants in
      * `invariants`.
      */
-    derive?: (next: N, patch: Partial<N>) => Partial<N>;
+    derive?: (next: N, patch: Partial<N>, previous?: N) => Partial<N>;
     /**
      * Cross-node companion to `derive`: after an inspector edit lands on
      * this node, return patches for OTHER nodes that must follow to keep
@@ -2018,13 +2204,15 @@ export type ParametricDescriptor<N> = {
      * auto-inserted elbow re-extends the duct runs it trimmed back onto the
      * corner it replaced. Called with the node and the live scene `nodes`
      * map BEFORE the deletion lands; patches targeting nodes also being
-     * deleted are ignored. Applied in the same `set` as the delete so it's
-     * one undo step. Fires only on `deleteNodes` (user-intent deletes) —
+     * deleted are ignored. `pendingDeleteIds` includes cascaded companion
+     * deletes, while `requestedDeleteIds` is the user's original selection.
+     * Applied in the same `set` as the delete so it's one undo step. Fires
+     * only on `deleteNodes` (user-intent deletes) —
      * NOT on `applyNodeChanges`, whose deletes are internal re-routes that
      * rewrite neighbours explicitly in the same batch and would fight a
      * restore.
      */
-    onDelete?: (node: N, nodes: Record<AnyNodeId, AnyNode>) => Array<{
+    onDelete?: (node: N, nodes: Record<AnyNodeId, AnyNode>, pendingDeleteIds: ReadonlySet<AnyNodeId>, requestedDeleteIds: ReadonlySet<AnyNodeId>) => Array<{
         id: AnyNodeId;
         data: Partial<AnyNode>;
     }>;
@@ -2035,9 +2223,10 @@ export type ParametricDescriptor<N> = {
      * deletion; returned ids are recursively expanded through the normal
      * descendant cascade. `pendingDeleteIds` holds every id already part of
      * the gesture so "would my parent become empty?" checks see sibling
-     * deletes from the same multi-select.
+     * deletes from the same multi-select. `requestedDeleteIds` remains the
+     * original selection while the pending set expands.
      */
-    onDeleteCascade?: (node: N, nodes: Record<AnyNodeId, AnyNode>, pendingDeleteIds: ReadonlySet<AnyNodeId>) => AnyNodeId[];
+    onDeleteCascade?: (node: N, nodes: Record<AnyNodeId, AnyNode>, pendingDeleteIds: ReadonlySet<AnyNodeId>, requestedDeleteIds: ReadonlySet<AnyNodeId>) => AnyNodeId[];
     customPanel?: () => Promise<{
         default: ComponentType<{
             node: N;
@@ -2078,6 +2267,7 @@ export type ParamGroup<N> = {
 };
 export type ParamField<N> = {
     key: keyof N;
+    label?: string;
     kind: 'number';
     unit?: string;
     min?: number;
@@ -2087,10 +2277,12 @@ export type ParamField<N> = {
     customEditor?: ComponentType;
 } | {
     key: keyof N;
+    label?: string;
     kind: 'boolean';
     visibleIf?: (n: N) => boolean;
 } | {
     key: keyof N;
+    label?: string;
     kind: 'enum';
     options: readonly string[];
     /** Defaults to 'select' (dropdown). 'segmented' renders the inline
@@ -2099,18 +2291,22 @@ export type ParamField<N> = {
     visibleIf?: (n: N) => boolean;
 } | {
     key: keyof N;
+    label?: string;
     kind: 'vec3';
     visibleIf?: (n: N) => boolean;
 } | {
     key: keyof N;
+    label?: string;
     kind: 'color';
     visibleIf?: (n: N) => boolean;
 } | {
     key: keyof N;
+    label?: string;
     kind: 'material';
     visibleIf?: (n: N) => boolean;
 } | {
     key: keyof N;
+    label?: string;
     kind: 'ref';
     refKind: string;
     visibleIf?: (n: N) => boolean;
@@ -2122,6 +2318,7 @@ export type ParamField<N> = {
  *  update logic. `key` here is just a stable React key/label. */
  | {
     key: string;
+    label?: string;
     kind: 'custom';
     component: ComponentType<{
         node: N;
@@ -2180,6 +2377,22 @@ export type SceneApi = {
     nodes: () => Readonly<Record<AnyNodeId, AnyNode>>;
     update: (id: AnyNodeId, patch: Partial<AnyNode>) => void;
     upsert: (node: AnyNode, parentId?: AnyNodeId) => AnyNodeId;
+    createMany?: (ops: {
+        node: AnyNode;
+        parentId?: AnyNodeId;
+    }[]) => void;
+    applyChanges?: (changes: {
+        create?: {
+            node: AnyNode;
+            parentId?: AnyNodeId;
+        }[];
+        update?: {
+            id: AnyNodeId;
+            data: Partial<AnyNode>;
+        }[];
+        delete?: AnyNodeId[];
+    }) => void;
+    subscribeNodes?: (listener: (nodes: Readonly<Record<AnyNodeId, AnyNode>>, previous: Readonly<Record<AnyNodeId, AnyNode>>, changedIds: ReadonlySet<AnyNodeId>) => void) => () => void;
     delete: (id: AnyNodeId) => void;
     restore: (id: AnyNodeId) => void;
     restoreAll: () => void;