feat(editor): preset-system primitives (#340)

packages/core/src/events/bus.ts

@@ -130,6 +130,13 @@ export interface ThumbnailGenerateEvent {
    * that should fire immediately from the current camera pose.
    */
   snapLevels?: boolean
+  /**
+   * When true, keep the rendered alpha channel — emits a transparent PNG
+   * without baking the scene background into the output. Used by the
+   * preset capture flow so saved preset thumbnails composite cleanly on
+   * any palette background.
+   */
+  transparent?: boolean
 }
 
 export interface CameraControlFitSceneEvent {

packages/core/src/registry/__bench__/relations-resolver.bench.ts

@@ -110,6 +110,8 @@ function makeScene(nodes: Record<string, AnyNode>): SceneApi {
     markDirty: () => {},
     pauseHistory: () => {},
     resumeHistory: () => {},
+    getSubtree: () => null,
+    cloneNodesInto: () => null,
   }
 }
 

packages/core/src/registry/index.ts

@@ -1,6 +1,24 @@
+export type {
+  ArcResizeHandle,
+  Cursor,
+  EditorApi,
+  EndpointMoveHandle,
+  HandleAnchor,
+  HandleAxis,
+  HandleDescriptor,
+  HandleList,
+  HandlePlacement,
+  HandlePortal,
+  LinearResizeHandle,
+  RadialResizeHandle,
+  TapActionHandle,
+} from './handles'
 export {
   discoverPlugins,
+  getHostRefFields,
   getSelectableKinds,
+  isPresettable,
+  isPresettableKind,
   isRegistryMovable,
   isRegistrySelectable,
   kindsWithFloorplanScope,
@@ -17,22 +35,14 @@ export {
   collectDescendants,
   type SpatialQuery,
 } from './relations-resolver'
-export type {
-  ArcResizeHandle,
-  Cursor,
-  EditorApi,
-  EndpointMoveHandle,
-  HandleAnchor,
-  HandleAxis,
-  HandleDescriptor,
-  HandleList,
-  HandlePlacement,
-  HandlePortal,
-  LinearResizeHandle,
-  RadialResizeHandle,
-  TapActionHandle,
-} from './handles'
 export { createSceneApi, type SceneStoreLike } from './scene-api'
+export {
+  type CloneNodesIntoOptions,
+  type CloneNodesIntoResult,
+  cloneNodesInto,
+  collectSubtree,
+  type Subtree,
+} from './subtree'
 export type {
   Affordance,
   AnyNodeDefinition,

packages/core/src/registry/registry.test.ts

@@ -1,6 +1,13 @@
 import { beforeEach, describe, expect, test } from 'bun:test'
 import { z } from 'zod'
-import { loadPlugin, nodeRegistry, registerNode } from './registry'
+import {
+  getHostRefFields,
+  isPresettable,
+  isPresettableKind,
+  loadPlugin,
+  nodeRegistry,
+  registerNode,
+} from './registry'
 import type { AnyNodeDefinition, Plugin } from './types'
 
 function makeDefinition(
@@ -70,6 +77,53 @@ describe('nodeRegistry', () => {
   })
 })
 
+describe('isPresettable', () => {
+  beforeEach(() => {
+    nodeRegistry._reset()
+  })
+
+  test('explicit true wins', () => {
+    const def = makeDefinition('explicit-true', { capabilities: { presettable: true } })
+    expect(isPresettable(def)).toBe(true)
+  })
+
+  test('explicit false wins even with parametrics', () => {
+    const def = makeDefinition('explicit-false', {
+      capabilities: { presettable: false },
+      parametrics: { groups: [] } as any,
+    })
+    expect(isPresettable(def)).toBe(false)
+  })
+
+  test('defaults to true when parametrics exists', () => {
+    const def = makeDefinition('param', { parametrics: { groups: [] } as any })
+    expect(isPresettable(def)).toBe(true)
+  })
+
+  test('defaults to false without parametrics', () => {
+    const def = makeDefinition('no-param')
+    expect(isPresettable(def)).toBe(false)
+  })
+
+  test('isPresettableKind looks up the registry', () => {
+    registerNode(makeDefinition('shelfy', { parametrics: { groups: [] } as any }))
+    expect(isPresettableKind('shelfy')).toBe(true)
+    expect(isPresettableKind('unknown')).toBe(false)
+  })
+})
+
+describe('getHostRefFields', () => {
+  test('returns the declared hostRefFields verbatim', () => {
+    const def = makeDefinition('door', { capabilities: { hostRefFields: ['wallId'] } })
+    expect(getHostRefFields(def)).toEqual(['wallId'])
+  })
+
+  test('defaults to an empty array when none declared', () => {
+    const def = makeDefinition('shelf')
+    expect(getHostRefFields(def)).toEqual([])
+  })
+})
+
 describe('loadPlugin', () => {
   beforeEach(() => {
     nodeRegistry._reset()

packages/core/src/registry/registry.ts

@@ -146,6 +146,34 @@ export function isRegistryMovable(kind: string): boolean {
   return false
 }
 
+/**
+ * Whether the kind can be saved as a reusable preset. Default: an
+ * explicit `capabilities.presettable` boolean wins; otherwise the kind
+ * is presettable iff it declares `def.parametrics`. Read by host apps
+ * (community shell) to gate "save as preset" UI on a selection.
+ */
+export function isPresettable(def: AnyNodeDefinition): boolean {
+  if (typeof def.capabilities.presettable === 'boolean') {
+    return def.capabilities.presettable
+  }
+  return def.parametrics !== undefined
+}
+
+export function isPresettableKind(kind: string): boolean {
+  const def = nodeRegistry.get(kind)
+  return def ? isPresettable(def) : false
+}
+
+/**
+ * Names of schema fields on `def` that are host references (`wallId`,
+ * `wallT`, etc.). Read by host apps at preset-save time to strip these
+ * from the stored payload — see `def.capabilities.hostRefFields` docs.
+ * Returns an empty array for kinds that don't declare any.
+ */
+export function getHostRefFields(def: AnyNodeDefinition): ReadonlyArray<string> {
+  return def.capabilities.hostRefFields ?? []
+}
+
 export async function loadPlugin(plugin: Plugin): Promise<void> {
   if (plugin.apiVersion !== HOST_API_VERSION) {
     throw new Error(

packages/core/src/registry/relations-resolver.test.ts

@@ -47,6 +47,8 @@ function makeFakeScene(nodes: Record<string, AnyNode>): SceneApi {
     markDirty: () => {},
     pauseHistory: () => {},
     resumeHistory: () => {},
+    getSubtree: () => null,
+    cloneNodesInto: () => null,
   }
 }
 

packages/core/src/registry/scene-api.ts

@@ -1,5 +1,10 @@
 import type { AnyNode, AnyNodeId } from '../schema/types'
 import { pauseSceneHistory, resumeSceneHistory } from '../store/history-control'
+import {
+  type CloneNodesIntoOptions,
+  collectSubtree,
+  cloneNodesInto as runCloneNodesInto,
+} from './subtree'
 import type { SceneApi } from './types'
 
 /**
@@ -14,6 +19,7 @@ export type SceneStoreLike = {
     rootNodeIds: AnyNodeId[]
     dirtyNodes: Set<AnyNodeId>
     createNode: (node: AnyNode, parentId?: AnyNodeId) => void
+    createNodes?: (ops: { node: AnyNode; parentId?: AnyNodeId }[]) => void
     updateNode: (id: AnyNodeId, data: Partial<AnyNode>) => void
     deleteNode: (id: AnyNodeId) => void
     markDirty: (id: AnyNodeId) => void
@@ -104,5 +110,32 @@ export function createSceneApi(store: SceneStoreLike): SceneApi {
       resumeSceneHistory(store)
       snapshot = null
     },
+
+    getSubtree(rootId) {
+      return collectSubtree(store.getState().nodes, rootId)
+    },
+
+    cloneNodesInto(nodes, opts: CloneNodesIntoOptions) {
+      const { rootId, nodes: cloned } = runCloneNodesInto(nodes, opts)
+      const root = cloned[0]
+      if (!root) return null
+      const state = store.getState()
+      const ops: { node: AnyNode; parentId?: AnyNodeId }[] = []
+      for (let i = 0; i < cloned.length; i += 1) {
+        const node = cloned[i]!
+        if (i === 0) {
+          ops.push(opts.parentId ? { node, parentId: opts.parentId } : { node })
+        } else {
+          ops.push({ node })
+        }
+      }
+      const batch = state.createNodes
+      if (batch) {
+        batch(ops)
+      } else {
+        for (const op of ops) state.createNode(op.node, op.parentId)
+      }
+      return rootId
+    },
   }
 }

packages/core/src/registry/subtree.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from 'bun:test'
+import type { AnyNode, AnyNodeId } from '../schema/types'
+import { cloneNodesInto, collectSubtree } from './subtree'
+
+function makeNode(id: string, type: string, extra: Record<string, unknown> = {}): AnyNode {
+  return {
+    object: 'node',
+    id,
+    type,
+    parentId: null,
+    visible: true,
+    metadata: {},
+    ...extra,
+  } as unknown as AnyNode
+}
+
+describe('collectSubtree', () => {
+  test('returns null for missing root', () => {
+    expect(collectSubtree({}, 'missing' as AnyNodeId)).toBeNull()
+  })
+
+  test('returns just the root for a leaf node', () => {
+    const root = makeNode('shelf_1', 'shelf', { width: 1 })
+    const sub = collectSubtree({ ['shelf_1' as AnyNodeId]: root }, 'shelf_1' as AnyNodeId)
+    expect(sub?.root).toBe(root)
+    expect(sub?.descendants).toEqual([])
+  })
+
+  test('walks descendants in BFS / declaration order', () => {
+    const nodes: Record<AnyNodeId, AnyNode> = {
+      ['shelf_1' as AnyNodeId]: makeNode('shelf_1', 'shelf', {
+        position: [0, 0, 0],
+        children: ['item_a', 'item_b'],
+        width: 1,
+      }),
+      ['item_a' as AnyNodeId]: makeNode('item_a', 'item', {
+        parentId: 'shelf_1',
+        position: [0, 0, 0],
+      }),
+      ['item_b' as AnyNodeId]: makeNode('item_b', 'item', {
+        parentId: 'shelf_1',
+        position: [0.3, 0, 0],
+      }),
+    }
+    const sub = collectSubtree(nodes, 'shelf_1' as AnyNodeId)
+    expect(sub?.descendants.map((n) => n.id)).toEqual(['item_a', 'item_b'])
+  })
+
+  test('returned nodes are live references — no cloning', () => {
+    const item = makeNode('item_a', 'item', { parentId: 'shelf_1', position: [0, 0, 0] })
+    const nodes: Record<AnyNodeId, AnyNode> = {
+      ['shelf_1' as AnyNodeId]: makeNode('shelf_1', 'shelf', { children: ['item_a'] }),
+      ['item_a' as AnyNodeId]: item,
+    }
+    const sub = collectSubtree(nodes, 'shelf_1' as AnyNodeId)
+    expect(sub?.descendants[0]).toBe(item)
+  })
+})
+
+describe('cloneNodesInto', () => {
+  test('clones a single root with fresh id and supplied position', () => {
+    const original = makeNode('door_orig', 'door', {
+      position: [1, 2, 3],
+      wallId: 'wall_x',
+      width: 0.9,
+    })
+    const { rootId, nodes } = cloneNodesInto([original], {
+      rootId: 'door_orig' as AnyNodeId,
+      position: [10, 0, -4],
+    })
+    expect(nodes).toHaveLength(1)
+    const cloned = nodes[0] as any
+    expect(cloned.id).toBe(rootId)
+    expect(cloned.id).not.toBe('door_orig')
+    expect(cloned.id.startsWith('door_')).toBe(true)
+    expect(cloned.position).toEqual([10, 0, -4])
+    expect(cloned.width).toBe(0.9)
+    // cloneNodesInto is host-ref-agnostic — wallId is preserved
+    // verbatim. Stripping is the caller's job (see getHostRefFields).
+    expect(cloned.wallId).toBe('wall_x')
+  })
+
+  test('preserves root position when none is supplied', () => {
+    const original = makeNode('shelf_orig', 'shelf', { position: [5, 0, 5] })
+    const { nodes } = cloneNodesInto([original], { rootId: 'shelf_orig' as AnyNodeId })
+    expect((nodes[0] as any).position).toEqual([5, 0, 5])
+  })
+
+  test('preserves parent/child subtree with remapped ids and relative positions', () => {
+    const shelf = makeNode('shelf_1', 'shelf', {
+      position: [5, 0, 5],
+      children: ['item_a', 'item_b'],
+    })
+    const itemA = makeNode('item_a', 'item', { parentId: 'shelf_1', position: [0, 0, 0] })
+    const itemB = makeNode('item_b', 'item', { parentId: 'shelf_1', position: [0.3, 0, 0] })
+
+    const { rootId, nodes: out } = cloneNodesInto([shelf, itemA, itemB], {
+      rootId: 'shelf_1' as AnyNodeId,
+      position: [99, 0, -99],
+    })
+    expect(out).toHaveLength(3)
+    const root = out[0] as any
+    expect(root.id).toBe(rootId)
+    expect(root.id).not.toBe('shelf_1')
+    expect(root.position).toEqual([99, 0, -99])
+    // Root's children rewritten to fresh ids; descendants' parentIds
+    // point at the new root id.
+    const ids = new Set(out.map((n) => (n as any).id))
+    expect(root.children).toHaveLength(2)
+    for (const cid of root.children) expect(ids.has(cid)).toBe(true)
+    for (let i = 1; i < out.length; i += 1) {
+      const desc = out[i] as any
+      expect(desc.parentId).toBe(rootId)
+      expect(Array.isArray(desc.position)).toBe(true)
+    }
+  })
+
+  test('parents the cloned root under opts.parentId when supplied', () => {
+    const orig = makeNode('shelf_1', 'shelf', { parentId: 'level_old' })
+    const { nodes } = cloneNodesInto([orig], {
+      rootId: 'shelf_1' as AnyNodeId,
+      parentId: 'level_new' as AnyNodeId,
+    })
+    expect((nodes[0] as any).parentId).toBe('level_new')
+  })
+
+  test('two clones produce disjoint id sets', () => {
+    const orig = makeNode('shelf_1', 'shelf', {
+      position: [0, 0, 0],
+      children: ['item_a'],
+    })
+    const child = makeNode('item_a', 'item', { parentId: 'shelf_1', position: [0, 0, 0] })
+    const first = cloneNodesInto([orig, child], { rootId: 'shelf_1' as AnyNodeId })
+    const second = cloneNodesInto([orig, child], { rootId: 'shelf_1' as AnyNodeId })
+    const idsA = new Set(first.nodes.map((n) => (n as any).id))
+    const idsB = new Set(second.nodes.map((n) => (n as any).id))
+    for (const id of idsA) expect(idsB.has(id)).toBe(false)
+  })
+
+  test('throws if rootId is missing from the input array', () => {
+    const orig = makeNode('shelf_1', 'shelf', {})
+    expect(() => cloneNodesInto([orig], { rootId: 'shelf_other' as AnyNodeId })).toThrow(/rootId/)
+  })
+})