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

package/dist/registry/types.d.ts

@@ -1,12 +1,14 @@
 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 { MeasurementFeatureReference, MeasurementPoint } from '../schema/nodes/measurement';
-import type { SceneMaterial, SceneMaterialId } from '../schema/scene-material';
-import type { AnyNode, AnyNodeId } from '../schema/types';
-import type { HandleList } from './handles';
-import type { CloneNodesIntoOptions, Subtree } from './subtree';
+import type { MaterialSchema, MaterialTarget } from '../schema/material.js';
+import type { AssetInput, ItemNode } from '../schema/nodes/item.js';
+import type { MeasurementFeatureReference, MeasurementPoint } from '../schema/nodes/measurement.js';
+import type { SceneMaterial, SceneMaterialId } from '../schema/scene-material.js';
+import type { AnyNode, AnyNodeId } from '../schema/types.js';
+import type { SurfaceProvider } from '../services/surface-hosting.js';
+import type { HandleList } from './handles.js';
+import type { CloneNodesIntoOptions, Subtree } from './subtree.js';
 export type GeometryContext = {
     /** Look up any node by ID. Returns undefined if the node doesn't exist. */
     resolve: <N = AnyNode>(id: AnyNodeId) => N | undefined;
@@ -60,6 +62,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
@@ -83,6 +88,10 @@ export type GeometryContext = {
          * wall ends only during the move.
          */
         moving: boolean;
+        /** The unit under focus in the editor and its member zone ids, so zone
+         * builders can dim non-members. Absent when no unit is focused. */
+        focusedUnitId?: string;
+        focusedUnitMemberIds?: readonly string[];
         /**
          * The kind's theme palette. Theme-aware colors (selection stroke,
          * endpoint handle fill, hatch color) live here so kinds don't need
@@ -191,6 +200,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 +275,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 +286,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 +307,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 +503,7 @@ export type FloorplanGeometry = ({
  | {
     kind: 'midpoint-handle';
     point: FloorplanPoint;
+    activation?: 'drag' | 'action';
     affordance: string;
     payload: unknown;
 }
@@ -707,6 +751,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 +803,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 +902,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 +940,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
@@ -944,6 +1019,8 @@ export type NodeDefinition<S extends ZodObject<any>> = {
      * inputs aren't captured by the node alone.
      */
     geometryKey?: (node: z.infer<S>) => string;
+    /** Child kinds whose live overrides affect this node’s generated geometry. */
+    geometryChildTypes?: readonly string[];
     /**
      * Level-batch precompute hook. Called by `<GeometrySystem>` once per
      * level per frame, **before** the per-node `def.geometry` calls in
@@ -979,8 +1056,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
@@ -991,8 +1069,10 @@ export type NodeDefinition<S extends ZodObject<any>> = {
      * the legacy `floorplan-panel.tsx` monolith.
      */
     floorplan?: (node: z.infer<S>, ctx: GeometryContext) => FloorplanGeometry | null;
-    /** Extra node IDs whose committed changes invalidate this node's floor-plan cache. */
-    floorplanDependencies?: (node: z.infer<S>) => readonly AnyNodeId[];
+    /** Extra node IDs whose committed changes invalidate this node's floor-plan cache.
+     *  `nodes` is the committed scene, for dependencies the node doesn't name itself
+     *  (a zone's owning unit lists the zone, not the other way round). */
+    floorplanDependencies?: (node: z.infer<S>, nodes: Readonly<Record<AnyNodeId, AnyNode>>) => readonly AnyNodeId[];
     /** Stable semantic geometry that associative measurement anchors may reference. */
     measurement?: MeasurementContribution<z.infer<S>>;
     /**
@@ -1005,8 +1085,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 +1253,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 +1374,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 +1384,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 +1446,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 +1488,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 +1875,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 +1912,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 +1966,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 +2007,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;
@@ -1896,8 +2052,11 @@ export type SnappableConfig = {
 };
 export type SnapPointKind = 'start' | 'end' | 'midpoint' | 'center' | 'corners';
 export type SurfacesConfig = {
+    hosting?: SurfaceProvider;
     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 +2068,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 +2194,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 +2214,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 +2233,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;
@@ -2075,9 +2274,12 @@ export type ParamAction<N> = {
 export type ParamGroup<N> = {
     label: string;
     fields: ParamField<N>[];
+    /** Whether this inspector group is open when it is first rendered. */
+    defaultExpanded?: boolean;
 };
 export type ParamField<N> = {
     key: keyof N;
+    label?: string;
     kind: 'number';
     unit?: string;
     min?: number;
@@ -2087,10 +2289,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 +2303,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 +2330,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 +2389,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;