@pascal-app/editor 0.9.1 → 1.0.0-beta.1

package/src/index.tsx

@@ -2,7 +2,21 @@
 // own shells on top of `@pascal-app/editor` (community-app, embedders)
 // don't have to learn three separate package imports. The canonical
 // definitions still live in `@pascal-app/core` / `@pascal-app/viewer`.
-export { useScene } from '@pascal-app/core'
+export {
+  type ApplySceneSnapshotOptions,
+  acquireSceneReadOnlyLease,
+  applyScenePatch,
+  applySceneSnapshot,
+  type SceneCommit,
+  type SceneCommitListener,
+  type SceneCommitOrigin,
+  type SceneMaterialPatch,
+  type SceneNodePatch,
+  type ScenePatch,
+  type SceneSnapshot,
+  subscribeSceneCommits,
+  useScene,
+} from '@pascal-app/core'
 export { useViewer } from '@pascal-app/viewer'
 export type { EditorProps } from './components/editor'
 export { default as Editor } from './components/editor'
@@ -11,12 +25,70 @@ export { default as Editor } from './components/editor'
 // they're referenced throughout the editor's own internals; the public
 // surface uses the shorter, shell-friendly names from the unified
 // preset-system spec.
+export { BakeExporter } from './components/editor/bake-exporter'
+export { BakeThumbnail } from './components/editor/bake-thumbnail'
+export { FirstPersonControls } from './components/editor/first-person-controls'
 export { FloatingActionMenu as FloatingMenu } from './components/editor/floating-action-menu'
-export { formatMeasurement, MeasurementPill } from './components/editor/measurement-pill'
+// Embed surface — the editor's real in-canvas affordances, so a host can mount
+// authentic selection handles, interactive build tools, and the mover on top
+// of a bare `<Viewer>` without the full `<Editor>` shell.
+//  - `NodeArrowHandles` renders the selected node's registry resize/rotate/move
+//    handles.
+//  - `MoveTool` runs the kind-owned mover once a translate handle arms
+//    `useEditor.movingNode`.
+//  - `ToolManager` mounts the active registry build tool (wall / door / window /
+//    …) for interactive placement when `useEditor` is in build mode with a
+//    tool, plus the snap/alignment guide layers. Mount it only while a tool is
+//    active to avoid its select-mode boundary editors.
+//  - `Grid` is the interactive drafting plane: it raycasts the pointer and
+//    emits the `grid:move` / `grid:click` events the build tools consume (the
+//    wall tool is driven entirely by them; door/window use them for free-follow
+//    alongside the viewer's `wall:*` mesh events). Without it the tools mount
+//    but their cursor never tracks the pointer. Mount it while a tool is active.
+// All read `useViewer` selection + `useEditor` state, and cooperate with host
+// camera controls via the `useViewer.inputDragging` / `useEditor.movingNode`
+// flags. Tools place onto `useViewer.selection.levelId`, so the host must set a
+// building + level selection first.
+export { Grid } from './components/editor/grid'
+export {
+  DimensionPill,
+  type DimensionPillPart,
+  formatMeasurement,
+  MeasurementPill,
+} from './components/editor/measurement-pill'
+// In-world arrow handle primitives (chevron geometry, invisible hit area,
+// shared material, palette + scale constants). Re-exported so kind-owned
+// 3D selection affordances in `@pascal-app/nodes` (duct side-move / height /
+// extend arrows) reuse the same UI family as the wall / fence side handles.
+export {
+  ARROW_COLOR,
+  ARROW_HOVER_COLOR,
+  ARROW_SCALE,
+  createArrowHandleGeometry,
+  createArrowHitAreaGeometry,
+  HandleArrow,
+  type HandleArrowInputShape,
+  type HandleArrowPlacement,
+  type HandleArrowProps,
+  InvisibleHandleHitArea,
+  NO_RAYCAST,
+  NodeArrowHandles,
+  swallowNextClick,
+  useArrowMaterial,
+  useInvisibleHitAreaMaterial,
+} from './components/editor/node-arrow-handles'
+export { QuickMeasurementCard } from './components/editor/quick-measurement-card'
 export {
   type SnapshotCameraData,
   ThumbnailGenerator,
 } from './components/editor/thumbnail-generator'
+export { useFloorplanRender } from './components/editor-2d/floorplan-render-context'
+export { FloorplanDimensionRenderer } from './components/editor-2d/renderers/floorplan-dimension-renderer'
+export { FloorplanGeometryRenderer } from './components/editor-2d/renderers/floorplan-geometry-renderer'
+export {
+  FloorplanNodePreview,
+  type FloorplanNodePreviewProps,
+} from './components/editor-2d/renderers/floorplan-placement-preview-layer'
 // SVG path builders for arc / annular-sector / arrow-head shapes —
 // inlined into `kind: 'path'` / `kind: 'polygon'` primitives by curved
 // stair rendering in `nodes/src/stair/floorplan.ts`.
@@ -32,9 +104,11 @@ export {
 // shared/segment-angle.ts) once every Stage D port is in.
 export {
   createFenceOnCurrentLevel,
+  createSplineFenceOnCurrentLevel,
   type FencePlanPoint,
   snapFenceDraftPoint,
 } from './components/tools/fence/fence-drafting'
+export { MoveTool } from './components/tools/item/move-tool'
 // Placement-math helpers — shared by kind-owned placement tools in
 // `@pascal-app/nodes` (wall curve sagitta snap, door / window placement,
 // item drop) so kinds don't reach into editor internals.
@@ -62,9 +136,25 @@ export { CursorSphere } from './components/tools/shared/cursor-sphere'
 export { DragBoundingBox } from './components/tools/shared/drag-bounding-box'
 export { getFloorStackPreviewPosition } from './components/tools/shared/floor-stack-preview'
 export { useFreshPlacementVisibility } from './components/tools/shared/fresh-placement-visibility'
+export {
+  type HorizontalConstructionPlane,
+  publishHorizontalConstructionPlane,
+  resampleTerrainConstructionPlane,
+  resolveEventConstructionPlane,
+  resolveLevelConstructionPlane,
+} from './components/tools/shared/horizontal-construction-plane'
+export { PlacementBox } from './components/tools/shared/placement-box'
+// Pointer-decided support surface (deck top vs floor underneath) — the
+// draw tools (wall / fence) ride their grid plane and commit cap on it.
+export {
+  type PointerSupportSurface,
+  resolvePointerSupportElevation,
+  resolvePointerSupportSurface,
+} from './components/tools/shared/pointer-support-cap'
 // Phase 5 Stage D — PolygonEditor for slab/ceiling boundary + hole editors.
 export {
   PolygonEditor,
+  type PolygonEditorPlanPointSnapContext,
   type PolygonEditorProps,
 } from './components/tools/shared/polygon-editor'
 export {
@@ -95,19 +185,24 @@ export {
   DEFAULT_STAIR_TYPE,
   DEFAULT_STAIR_WIDTH,
 } from './components/tools/stair/stair-defaults'
+export { preloadRegistryToolModules, ToolManager } from './components/tools/tool-manager'
 export {
+  chainEndJoinsExistingWall,
   createWallOnCurrentLevel,
   getSegmentGridStep,
   isSegmentLongEnough,
+  resolveEndpointWallSplit,
   snapPointToGrid,
   snapScalarToGrid,
   snapWallDraftPoint,
   snapWallDraftPointDetailed,
-  WALL_FINE_GRID_STEP,
+  WALL_CONNECT_SNAP_RADIUS,
   WALL_GRID_STEP,
+  WALL_JOIN_SNAP_RADIUS,
   type WallDraftSnapKind,
   type WallDraftSnapResult,
   type WallPlanPoint,
+  type WallSnapRadii,
 } from './components/tools/wall/wall-drafting'
 // `ToolbarLeft` / `ToolbarRight` are the headless-spec aliases for the
 // existing `ViewerToolbarLeft` / `ViewerToolbarRight` exports — the
@@ -124,12 +219,20 @@ export {
 } from './components/ui/action-menu/view-toggles'
 export { useCommandPalette } from './components/ui/command-palette'
 export { ActionButton, ActionGroup } from './components/ui/controls/action-button'
-export { MaterialPaintPanel } from './components/ui/controls/material-paint-panel'
-export { MaterialPicker } from './components/ui/controls/material-picker'
+export {
+  MaterialPaintPanel,
+  type MaterialPaintPanelProps,
+} from './components/ui/controls/material-paint-panel'
+export {
+  MaterialPicker,
+  type MaterialPickerProps,
+  type MaterialSourceFilter,
+} from './components/ui/controls/material-picker'
 export { MetricControl } from './components/ui/controls/metric-control'
 export { PanelSection } from './components/ui/controls/panel-section'
 export { SegmentedControl } from './components/ui/controls/segmented-control'
 export { SliderControl } from './components/ui/controls/slider-control'
+export { TerrainSculptPanel } from './components/ui/controls/terrain-sculpt-panel'
 export { ToggleControl } from './components/ui/controls/toggle-control'
 export { FloatingLevelSelector } from './components/ui/floating-level-selector'
 export { CATALOG_ITEMS } from './components/ui/item-catalog/catalog-items'
@@ -164,6 +267,26 @@ export {
 } from './components/ui/sidebar/panels/settings-panel'
 export type { SitePanelProps } from './components/ui/sidebar/panels/site-panel'
 export type { SidebarTab } from './components/ui/sidebar/tab-bar'
+export {
+  resolveAssetSnapTarget,
+  resolveNodeSnapTarget,
+  type SnapTarget,
+  SnapTargetBadge,
+  SnapTargetIcon,
+} from './components/ui/snap-target-badge'
+export {
+  ViewerControlsBar,
+  type ViewerControlsBarProps,
+} from './components/viewer/viewer-controls-bar'
+export {
+  ViewerSceneHeader,
+  type ViewerSceneHeaderProps,
+} from './components/viewer/viewer-scene-header'
+export {
+  WalkthroughHud,
+  type WalkthroughHudProps,
+  type WalkthroughInteract,
+} from './components/walkthrough-hud'
 export type { SaveStatus } from './hooks/use-auto-save'
 // useDragAction is the React-side glue for the registry's DragAction
 // primitive. Public so registry-driven kinds (Phase 5+ Stage D ports)
@@ -171,9 +294,41 @@ export type { SaveStatus } from './hooks/use-auto-save'
 export { type UseDragActionArgs, useDragAction } from './hooks/use-drag-action'
 // Phase 5 Stage D — extras for kind-owned placement tools (FenceTool etc.).
 export { markToolCancelConsumed } from './hooks/use-keyboard'
+export { useReducedMotion } from './hooks/use-reduced-motion'
 export { type Selection, useSelection } from './hooks/use-selection'
+export {
+  clearPlacementSurface,
+  getPlacementSurface,
+  type PlacementSurface,
+  publishPlacementSurface,
+} from './lib/active-placement-surface'
+export {
+  CEILING_ALIGNMENT_THRESHOLD_M,
+  type CeilingPlanSnapInput,
+  type CeilingPlanSnapResult,
+  clearCeilingSnapFeedback,
+  resolveCeilingPlanPointSnap,
+} from './lib/ceiling-plan-snap'
 export { EDITOR_LAYER } from './lib/constants'
 // Helper libs used by the kind-owned roof / stair / elevator panels.
+export {
+  CONTINUATION_PROFILES,
+  type ContinuationContext,
+  type ContinuationMode,
+  continuationContextOf,
+  nextContinuation,
+} from './lib/continuation'
+export {
+  clearStructuralElevationGuide,
+  collectElevationSnapTargets,
+  ELEVATION_ALIGNMENT_THRESHOLD_M,
+  type ElevationGuideSource,
+  type ElevationSnapMatch,
+  type ElevationSnapTarget,
+  publishStructuralElevationGuide,
+  resolveElevationSnapMatch,
+  resolveStructuralElevationSnap,
+} from './lib/elevation-guides'
 export {
   resolveCurrentBuildingId,
   resolveElevatorNodeSupportY,
@@ -200,16 +355,92 @@ export {
   type FloorplanStairSegmentEntry,
   getFloorplanWallThickness,
 } from './lib/floorplan'
+export type {
+  FloorplanAnnotationCategory,
+  FloorplanAnnotationVisibility,
+} from './lib/floorplan/annotation-visibility'
+export {
+  createFloorplanContextExtensions,
+  FLOORPLAN_CONTEXT_EXTENSION_KEY,
+  FLOORPLAN_GEOMETRY_METADATA_KEY,
+  FLOORPLAN_NODE_EXTENSION_KEY,
+  type FloorplanAnnotationRole,
+  type FloorplanMetricNotation,
+  type FloorplanNodeExtension,
+  type FloorplanRenderPurpose,
+  type FloorplanSchedule,
+  type FloorplanToolContext,
+  type FloorplanToolMode,
+  floorplanGeometryMetadata,
+  getFloorplanNodeExtension,
+  readFloorplanContext,
+  readFloorplanGeometryMetadata,
+  readFloorplanMetricNotationOverride,
+  withFloorplanGeometryMetadata,
+} from './lib/floorplan/floorplan-extension'
+export {
+  DEFAULT_FLOORPLAN_MODE,
+  FLOORPLAN_MODES,
+  type FloorplanMode,
+  isFloorplanToolAvailableInMode,
+} from './lib/floorplan/floorplan-mode'
 export { commitFreshPlacementSubtree } from './lib/fresh-planar-placement'
+export { exportSceneToGlb } from './lib/glb-export'
+export {
+  type HistoryCommandDelegate,
+  installHistoryCommandDelegate,
+  runRedo,
+  runUndo,
+} from './lib/history'
+export {
+  boundaryReshapeScope,
+  curveReshapeScope,
+  endpointReshapeScope,
+  holeEditScope,
+  movingNodeOf,
+  scopeNodeId,
+} from './lib/interaction/scope'
 export {
   buildResetSurfaceMaterialUpdates,
   buildRoofSurfaceMaterialPatch,
   buildSingleSurfaceMaterialPatch,
   buildStairSurfaceMaterialPatch,
-  buildWallSurfaceMaterialPatch,
   getActivePaintMaterialLabel,
   hasActivePaintMaterial,
 } from './lib/material-paint'
+export {
+  CREATABLE_MEASUREMENT_KINDS,
+  type CreatableMeasurementKind,
+  DEFAULT_CREATABLE_MEASUREMENT_KIND,
+  isCreatableMeasurementKind,
+  normalizeCreatableMeasurementKind,
+} from './lib/measurement-kind'
+export {
+  measurementPolygonLabelAnchor,
+  triangulateMeasurementPolygon,
+} from './lib/measurement-label'
+export {
+  buildMeasurementAngleArcPoints,
+  cubicMetersToVolumeUnit,
+  formatAreaLabel,
+  formatLinearMeasurement,
+  formatVolumeLabel,
+  getAreaUnitLabel,
+  getLinearUnitLabel,
+  getVolumeUnitLabel,
+  type LinearUnit,
+  linearControlValueToMeters,
+  linearUnitToMeters,
+  MEASUREMENT_ACTIVE_COLOR,
+  MEASUREMENT_DANGLING_COLOR,
+  MEASUREMENT_FLOORPLAN_COLOR,
+  MEASUREMENT_PERSISTENT_COLOR,
+  measurementFloorplanPresentationColor,
+  measurementPresentationColor,
+  metersToLinearUnit,
+  squareMetersToAreaUnit,
+} from './lib/measurements'
+export { consumePlacementDragRelease } from './lib/placement-drag-release'
 export {
   addFreshPlacementMetadata,
   getPlacementMetadataRecord,
@@ -221,10 +452,37 @@ export {
   type PlanarPoint,
   resolvePlanarCursorPosition,
 } from './lib/planar-cursor-placement'
+export {
+  type EditorHostPanel,
+  type EditorHostPanelWorkspace,
+  editorHostPanelRegistry,
+  registerEditorHostPanel,
+} from './lib/plugin-panels'
+export {
+  createQuickMeasurementPointerScheduler,
+  quickMeasurementContext,
+  resolveQuickMeasurementReport,
+} from './lib/quick-measurement'
 export { clearRoofDuplicateMetadata, duplicateRoofSubtree } from './lib/roof-duplication'
+// Roof wall-face hit resolution + overlap guard — shared by the
+// kind-owned door / window tools in `@pascal-app/nodes` and the item
+// placement coordinator's roof-wall strategy.
+export { hasRoofFaceChildOverlap, type RoofWallHit, resolveRoofWallHit } from './lib/roof-wall-hit'
 export type { SceneGraph } from './lib/scene'
 export { applySceneGraphToEditor } from './lib/scene'
+export { movementSfxStepKey } from './lib/sfx/movement-tick'
 export { triggerSFX } from './lib/sfx-bus'
+export { playSFX, type SFXName, type SFXPlaybackOptions } from './lib/sfx-player'
+export {
+  clearSlabSnapFeedback,
+  resolveSlabEdgeBandSnap,
+  resolveSlabPlanPointSnap,
+  SLAB_ALIGNMENT_THRESHOLD_M,
+  type SlabEdgeBandSnapInput,
+  type SlabEdgeBandSnapResult,
+  type SlabPlanSnapInput,
+  type SlabPlanSnapResult,
+} from './lib/slab-plan-snap'
 export { duplicateStairSubtree } from './lib/stair-duplication'
 export {
   getBuildingLevelsForLevel,
@@ -234,36 +492,124 @@ export {
   resolveStairPlacementLevelId,
   resolveStairToLevelId,
 } from './lib/stair-levels'
+export {
+  clearSurfacePlanSnapFeedback,
+  resolveSurfacePlanPointSnap,
+  SURFACE_ALIGNMENT_THRESHOLD_M,
+  type SurfacePlanSnapInput,
+  type SurfacePlanSnapResult,
+} from './lib/surface-plan-snap'
+export {
+  fieldExtentForSite,
+  flattenSite,
+  resetSiteTerrain,
+  resolveFlattenTarget,
+  sculptFieldForSite,
+} from './lib/terrain-sculpt'
 // `cn` (twMerge + clsx) — used by kind-owned panels in `@pascal-app/
 // nodes` so they don't need their own copy / their own tailwind-merge
 // dependency.
 export { cn } from './lib/utils'
 export {
   getActiveBuildingPose,
+  projectAlignmentGuidesWorldToActiveBuildingLocal,
   resolveAlignmentForActiveBuilding,
+  resolveAlignmentForFloorplanView,
   snapBuildingLocalToWorldGrid,
   snapWorldXZForActiveBuilding,
 } from './lib/world-grid-snap'
 export { default as useAlignmentGuides } from './store/use-alignment-guides'
 export { default as useAudio } from './store/use-audio'
 export { type CommandAction, useCommandRegistry } from './store/use-command-registry'
+export {
+  DRAWING_TYPE_OPTIONS,
+  default as useDrawingView,
+} from './store/use-drawing-view'
 export type {
+  CaptureMode,
   FloorplanSelectionTool,
-  MovingFenceEndpoint,
-  MovingWallEndpoint,
+  SnapshotCropMode,
+  SnapshotStandardAspect,
   SplitOrientation,
   Tool,
   ToolDefaults,
   ViewMode,
   WorkspaceMode,
 } from './store/use-editor'
-export { default as useEditor } from './store/use-editor'
+export {
+  default as useEditor,
+  getActiveContinuationContext,
+  getContinuation,
+  isAlignmentGuideActive,
+  isAngleSnapActive,
+  isGridSnapActive,
+  isMagneticSnapActive,
+} from './store/use-editor'
+export { default as useFacingPose, type FacingPose } from './store/use-facing-pose'
+export { default as useFenceCurveDraft } from './store/use-fence-curve-draft'
+export { type FirstPersonHudState, useFirstPersonHud } from './store/use-first-person-hud'
+export { default as useFloorplanAnnotationVisibility } from './store/use-floorplan-annotation-visibility'
+export { useFloorplanDraftPreview } from './store/use-floorplan-draft-preview'
+export { default as useFloorplanMode } from './store/use-floorplan-mode'
+export {
+  default as useInteractionScope,
+  getEditingHole,
+  getIsCurveReshape,
+  getMovingNode,
+  useActiveHandleDrag,
+  useEditingHole,
+  useEndpointReshape,
+  useIsCurveReshape,
+  useMovingNode,
+  useReshapingNode,
+} from './store/use-interaction-scope'
+export {
+  commitMeasurementDraft,
+  finishMeasurementDraft,
+  handleMeasurementDraftEscape,
+  type MeasurementAxis,
+  type MeasurementAxisGuide,
+  type MeasurementDraftOwner,
+  type MeasurementDraftPayload,
+  type MeasurementDraftStage,
+  type MeasurementKind,
+  type MeasurementPoint,
+  type MeasurementSurfacePoint,
+  measurementPolygonMidpoints,
+  useMeasurementDraft,
+} from './store/use-measurement-draft'
+export {
+  default as useOpeningGuides,
+  type OpeningGuide3D,
+  type OpeningGuideVec3,
+} from './store/use-opening-guides'
 export {
   type PaletteView,
   type PaletteViewProps,
   usePaletteViewRegistry,
 } from './store/use-palette-view-registry'
+export {
+  type PathDraftKind,
+  type PathDraftParameter,
+  type PathDraftParameters,
+  type PathDraftPoint,
+  usePathDraftPreview,
+} from './store/use-path-draft-preview'
 export { default as usePlacementPreview } from './store/use-placement-preview'
+export {
+  activateQuickMeasurementHudSource,
+  clearQuickMeasurementHudSource,
+  publishQuickMeasurementHudSource,
+  type QuickMeasurementHudEntry,
+  type QuickMeasurementHudSource,
+  selectQuickMeasurementHudEntry,
+  useQuickMeasurementHud,
+} from './store/use-quick-measurement-hud'
+export { default as useSegmentDraftChain } from './store/use-segment-draft-chain'
+export {
+  type StairPreviewPoint,
+  useStairBuildPreview,
+} from './store/use-stair-build-preview'
 export { useUploadStore } from './store/use-upload'
 export { useWallMoveGhosts, type WallMoveGhostBridge } from './store/use-wall-move-ghosts'
 export {

package/src/lib/active-placement-surface.test.ts

@@ -0,0 +1,24 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { Vector3 } from 'three'
+import {
+  clearPlacementSurface,
+  getPlacementSurface,
+  publishPlacementSurface,
+} from './active-placement-surface'
+
+describe('active placement surface', () => {
+  afterEach(() => clearPlacementSurface())
+
+  test('marks a frozen construction plane so terrain raycasting can bypass it', () => {
+    publishPlacementSurface(new Vector3(1, 0, 2), new Vector3(0, 1, 0), 'fixed-plane')
+
+    expect(getPlacementSurface()?.projection).toBe('fixed-plane')
+  })
+
+  test('ordinary surface publishes reset the projection mode', () => {
+    publishPlacementSurface(new Vector3(), new Vector3(0, 1, 0), 'fixed-plane')
+    publishPlacementSurface(new Vector3(), new Vector3(0, 1, 0))
+
+    expect(getPlacementSurface()?.projection).toBe('surface')
+  })
+})

package/src/lib/active-placement-surface.ts

@@ -0,0 +1,42 @@
+import { Vector3 } from 'three'
+
+// The surface the active placement/move ghost is currently snapped to: a contact
+// point (world space) and the surface's outward unit normal. Published each frame
+// by the placement tools (the item coordinator + the drawn-kind tools) and read
+// by the grid so its snap patch sits at the ghost's height AND orients to the
+// surface — horizontal on a floor / shelf top, vertical in a wall plane.
+//
+// A plain module singleton (not a store): both writer and reader run inside
+// `useFrame`, so reactivity would only add overhead. The vectors are reused, so
+// readers must consume them within the same frame.
+export type PlacementSurface = {
+  point: Vector3
+  normal: Vector3
+  projection: 'surface' | 'fixed-plane'
+}
+
+const surface: PlacementSurface = {
+  point: new Vector3(),
+  normal: new Vector3(0, 1, 0),
+  projection: 'surface',
+}
+let active = false
+
+export function publishPlacementSurface(
+  point: Vector3,
+  normal: Vector3,
+  projection: PlacementSurface['projection'] = 'surface',
+): void {
+  surface.point.copy(point)
+  surface.normal.copy(normal)
+  surface.projection = projection
+  active = true
+}
+
+export function clearPlacementSurface(): void {
+  active = false
+}
+
+export function getPlacementSurface(): PlacementSurface | null {
+  return active ? surface : null
+}