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

* feat(editor): preset-system primitives — presettable, sceneApi subtree round-trip, isolate + setCaptureMode enum, headless exports Per pascalorg/editor#340 (redesigned: single live canvas, no Viewer scene prop). Core - `capabilities.presettable` on `NodeDefinition` + `isPresettable` / `isPresettableKind` helpers. Explicit `false` on level / building / site / zone / spawn / guide / scan / item; implicit `true` for any kind with `def.parametrics`. - `sceneApi.getSubtreeSnapshot(rootId)` + `materializeSubtree(subtree, position, parentId?)` for round-tripping a node subtree through catalog storage. Strips id / parentId / absolute root position / host refs (`wallId`, `wallT`); fresh IDs minted at materialize time; child ordering preserved (FIFO walk). Viewer - `<Viewer isolate>` prop + `ViewerHandle.setIsolated(ids | null)`. Walks `sceneRegistry`, hides every registered group not in the isolated set's ancestor + descendant closure. Building block for preset capture + future focus-mode UX. Editor - `useEditor.captureMode: CaptureMode` discriminated union (`idle` | `standard` | `preset`). `isCaptureMode` stays as a derived boolean for the existing read sites; `setCaptureMode` accepts both the boolean shape (back-compat) and the enum. - `preset` capture mode in `SnapshotCaptureOverlay`: drag locked to a square, mode-picker hidden, transparent flag forwarded through the `camera-controls:generate-thumbnail` emitter event. - Headless exports: `Inspector` (alias of `ParametricInspector`), `FloatingMenu` (alias of `FloatingActionMenu`), `ToolbarLeft` / `ToolbarRight` (aliases of `ViewerToolbarLeft` / `ViewerToolbarRight`), `useSelection` hook returning `{selectedIds, selectedNode, building/ level/zone}`, plus re-exports of `useScene` / `useViewer` from core / viewer so consumer shells (community, embedders) need only one import. Out of scope by design (see issue #340 "Out of scope"): a separate offscreen Viewer rendering an arbitrary subtree. The unified preset modal captures inside the live canvas via isolation + the existing snapshot pipeline — no `useScene` factory / React context refactor. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(editor): split snapshot/materialize into pure getSubtree + cloneNodesInto; add def.hostRefFields; auto-stage preset capture square Per pascalorg/editor#340 redesign discussion: the editor's scene API should expose *pure* primitives and let the host (community modal, embedders) own storage shape, position stripping, and host-ref re-derivation policy. Editor API delta - `sceneApi.getSubtreeSnapshot(rootId)` → `sceneApi.getSubtree(rootId)` Returns the live subtree verbatim (BFS via `children[]`, no clones, no stripping). Callers deep-clone if they need persistence. - `sceneApi.materializeSubtree(subtree, pos, parent?)` → `sceneApi.cloneNodesInto(nodes, { rootId, parentId?, position? })` Generic clone-and-insert. Deep-clones via JSON, mints fresh ids preserving the prefix, rewires parent/children, stamps position + parent if supplied. Host-ref-agnostic — `wallId`/`wallT` etc are preserved verbatim. - New `capabilities.hostRefFields?: string[]` on `NodeDefinition`. Declares per kind which schema fields are placement-derived so the host strips them at preset-save time. Declared on door (`['wallId']`), window (`['wallId']`), item (`['wallId', 'wallT']`). - New `getHostRefFields(def)` exported from `@pascal-app/core`. Removed the intermediate token-based payload format (`NodeSubtree`, `buildSubtreeSnapshot`, `materializeSubtree`, `SubtreeNode`). UX polish - `<SnapshotCaptureOverlay>` in `preset` mode now auto-stages a centered square crop sized to ~75% of the shorter viewport dimension. The user can pan / move / resize within square-aspect, but doesn't have to drag from scratch — clicking the capture button works immediately on entry. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(editor): lock preset capture frame; allow item presets - SnapshotCaptureOverlay: in `preset` mode, the auto-staged centered square is now fully locked — corner handles hidden, the dim layer is click-through (no drag-to-move, no drag-to-resize). The user just adjusts the camera (orbit / pan / zoom) and clicks capture. The letterbox + dashed border stay visible as a cosmetic frame. - `item.capabilities.presettable` removed (implicit `true` via `def.parametrics`). Enables compositions like "table-with-plants", "shelf-with-books" where the preset root may be an item and other items ride along as descendants. The GLB-kind item catalog is unchanged; presets become siblings of GLB rows under the same `items` table. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(editor): auto-frame camera on preset capture entry; restore on exit `<CustomCameraControls>` now watches `useEditor.captureMode` and, when preset capture mode begins, flies the camera to a pose that fits the union bounds of the isolated subtree inside the locked square crop — no more hunting for the subject after opening the modal. The pre-capture pose is stashed and restored on exit so the user lands exactly where they were. The user can still pan / orbit / zoom from the auto-staged pose if they want a different angle before snapping. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-28 09:49:50 -04:00
parent 350cad9c89
commit 1fd59dd9cd
31 changed files with 1087 additions and 113 deletions
@@ -0,0 +1,101 @@
+'use client'
+
+import type { AnyNodeId } from '@pascal-app/core'
+import { sceneRegistry } from '@pascal-app/core'
+import type { Object3D } from 'three'
+import { SCENE_LAYER } from './layers'
+
+// Marker on each Object3D we modify during isolation so we can restore
+// the original `layers.mask` bitfield. Stored under a `Symbol` so it
+// can't collide with any kind's own userData fields.
+const ORIGINAL_LAYERS = Symbol('isolation:original-layers')
+
+type IsolationCarrier = Object3D & { [ORIGINAL_LAYERS]?: number }
+
+/**
+ * Compute the union of every isolated subtree's `Object3D` descendants.
+ *
+ * Pure traversal — exported so future "focus mode" / debug tooling can
+ * reuse the same definition of "what's in the isolated set". Each root
+ * is walked via `Object3D.traverse` (the live Three.js graph, not the
+ * data-model `children` array — those can disagree when systems mount
+ * synthesized sub-meshes that the data model doesn't track).
+ */
+export function collectIsolationSubtree(ids: ReadonlyArray<string>): Set<Object3D> {
+  const keep = new Set<Object3D>()
+  for (const id of ids) {
+    const root = sceneRegistry.nodes.get(id)
+    if (!root) continue
+    root.traverse((child) => {
+      keep.add(child)
+    })
+  }
+  return keep
+}
+
+/**
+ * Imperative visibility filter on the live `sceneRegistry`. Hides every
+ * registered group (and its synthesized child meshes) outside the
+ * isolated subtree by disabling the {@link SCENE_LAYER} bit on the
+ * relevant `Object3D.layers` masks.
+ *
+ * Why layers instead of `obj.visible = false`? Three.js's visibility
+ * flag *cascades* — hiding a parent hides every descendant — so we
+ * can't hide a host wall while keeping a door rendered inside it.
+ * Layer masks are per-object and don't cascade: `WebGLRenderer
+ * .projectObject` skips objects whose layer mask doesn't intersect the
+ * camera's, but always recurses into their children. So we can disable
+ * `SCENE_LAYER` on the wall and the door (hosted under it in the
+ * scene graph) still renders, with its local position relative to the
+ * wall preserved automatically by the matrix walk.
+ *
+ * The original `layers.mask` is stashed under a private Symbol so
+ * {@link clearIsolation} can restore the exact prior state.
+ *
+ * Pass `null` to clear isolation (equivalent to calling
+ * {@link clearIsolation}).
+ */
+export function applyIsolation(ids: ReadonlyArray<AnyNodeId> | null): void {
+  if (ids == null || ids.length === 0) {
+    clearIsolation()
+    return
+  }
+
+  const keep = collectIsolationSubtree(ids as ReadonlyArray<string>)
+
+  // Iterate registered roots. For each one outside the keep set,
+  // disable `SCENE_LAYER` on it and on every descendant — *except*
+  // descendants that are themselves in `keep` (a kept node nested under
+  // a non-kept host: the isolated door under the hidden wall).
+  for (const [, obj] of sceneRegistry.nodes) {
+    if (keep.has(obj)) continue
+    hideRecursive(obj, keep)
+  }
+}
+
+function hideRecursive(obj: Object3D, keep: Set<Object3D>): void {
+  if (keep.has(obj)) return
+  const carrier = obj as IsolationCarrier
+  if (carrier[ORIGINAL_LAYERS] === undefined) {
+    carrier[ORIGINAL_LAYERS] = obj.layers.mask
+  }
+  obj.layers.disable(SCENE_LAYER)
+  for (const child of obj.children) {
+    hideRecursive(child, keep)
+  }
+}
+
+export function clearIsolation(): void {
+  // We don't know which objects were touched without re-walking, so
+  // walk every registered root + its descendants and restore any
+  // stashed original-mask. `traverse` is cheap and idempotent here.
+  for (const [, obj] of sceneRegistry.nodes) {
+    obj.traverse((child) => {
+      const carrier = child as IsolationCarrier
+      if (carrier[ORIGINAL_LAYERS] !== undefined) {
+        child.layers.mask = carrier[ORIGINAL_LAYERS]
+        delete carrier[ORIGINAL_LAYERS]
+      }
+    })
+  }
+}