@pascal-app/editor 1.0.0-beta.4 → 1.0.0

package/src/hooks/use-registered-tool-enabled.ts

@@ -0,0 +1,20 @@
+'use client'
+
+import { isNodeKindEnabled, useScene } from '@pascal-app/core'
+import { useEffect } from 'react'
+import useEditor, { type Tool } from '../store/use-editor'
+
+export function useRegisteredToolEnabled(tool: Tool | null): boolean {
+  const installedPlugins = useScene((state) => state.installedPlugins)
+  const enabled = tool === null || isNodeKindEnabled(tool, installedPlugins)
+
+  useEffect(() => {
+    if (enabled || tool === null) return
+
+    // The render gate has already unmounted the tool, so its own cleanup cancels
+    // any draft before clearing the stale selection prevents reinstall remounts.
+    if (useEditor.getState().tool === tool) useEditor.getState().setTool(null)
+  }, [enabled, tool])
+
+  return enabled
+}

package/src/hooks/use-save-shortcut.ts

@@ -0,0 +1,33 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+
+/**
+ * Claims Cmd/Ctrl+S for the app's save.
+ *
+ * Capture phase and ungated on purpose: the browser's "Save page" dialog must
+ * never appear anywhere in the editor — including first-person, studio mode and
+ * while focus sits in an input, where people still expect the chord to save.
+ * `e.code` keeps it on the physical S key across keyboard layouts.
+ */
+export function useSaveShortcut(onSave: () => void) {
+  const onSaveRef = useRef(onSave)
+
+  useEffect(() => {
+    onSaveRef.current = onSave
+  }, [onSave])
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (!(e.metaKey || e.ctrlKey) || e.altKey || e.shiftKey) return
+      if (e.code !== 'KeyS') return
+
+      e.preventDefault()
+      e.stopPropagation()
+      onSaveRef.current()
+    }
+
+    window.addEventListener('keydown', handleKeyDown, true)
+    return () => window.removeEventListener('keydown', handleKeyDown, true)
+  }, [])
+}

package/src/index.tsx

@@ -56,6 +56,7 @@ export {
   formatMeasurement,
   MeasurementPill,
 } from './components/editor/measurement-pill'
+export { NodeActionMenu } from './components/editor/node-action-menu'
 // 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 /
@@ -98,6 +99,11 @@ export {
   buildSvgArrowHeadPoints,
   getArcPlanPoint,
 } from './components/editor-2d/svg-paths'
+export type {
+  SelectionAffordanceHistoryApi,
+  SelectionAffordanceInteractionApi,
+  SelectionAffordanceProps,
+} from './components/systems/selection-affordance-services'
 // Phase 5 Stage D transitional exports — pure drafting / angle helpers
 // consumed by kind-owned drag actions in @pascal-app/nodes. Stage F
 // cleanup moves these into @pascal-app/nodes (fence/drafting.ts +
@@ -113,7 +119,6 @@ export { MoveTool } from './components/tools/item/move-tool'
 // `@pascal-app/nodes` (wall curve sagitta snap, door / window placement,
 // item drop) so kinds don't reach into editor internals.
 export {
-  calculateCursorRotation,
   calculateItemRotation,
   getSideFromNormal,
   isValidWallSideFace,
@@ -132,6 +137,7 @@ export {
   type PlacementCoordinatorConfig,
   usePlacementCoordinator,
 } from './components/tools/item/use-placement-coordinator'
+export { useRegistryToolContext } from './components/tools/registry-tool-context'
 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'
@@ -144,6 +150,7 @@ export {
   resolveLevelConstructionPlane,
 } from './components/tools/shared/horizontal-construction-plane'
 export { PlacementBox } from './components/tools/shared/placement-box'
+export { PlacementDimensionGuides } from './components/tools/shared/placement-dimension-guides'
 // Pointer-decided support surface (deck top vs floor underneath) — the
 // draw tools (wall / fence) ride their grid plane and commit cap on it.
 export {
@@ -234,6 +241,7 @@ 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 { ToolOptionsPanel } from './components/ui/controls/tool-options-panel'
 export { FloatingLevelSelector } from './components/ui/floating-level-selector'
 export { CATALOG_ITEMS } from './components/ui/item-catalog/catalog-items'
 // Item collections UI — used by the kind-owned ItemPanel in nodes/.
@@ -254,6 +262,10 @@ export {
   DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from './components/ui/primitives/dropdown-menu'
+export {
+  ShortcutToken,
+  shortcutDisplayValue,
+} from './components/ui/primitives/shortcut-token'
 export { useSidebarStore } from './components/ui/primitives/sidebar'
 export { Slider } from './components/ui/primitives/slider'
 export { SceneLoader } from './components/ui/scene-loader'
@@ -274,6 +286,16 @@ export {
   SnapTargetBadge,
   SnapTargetIcon,
 } from './components/ui/snap-target-badge'
+export {
+  FloorplanCompassButton,
+  type FloorplanCompassButtonProps,
+} from './components/viewer/floorplan-compass-button'
+export {
+  FloorplanPreview,
+  type FloorplanPreviewProps,
+  type FloorplanPreviewScene,
+} from './components/viewer/floorplan-preview'
+export { useViewerCameraNavigationSync } from './components/viewer/use-viewer-camera-navigation-sync'
 export {
   ViewerControlsBar,
   type ViewerControlsBarProps,
@@ -282,6 +304,19 @@ export {
   ViewerSceneHeader,
   type ViewerSceneHeaderProps,
 } from './components/viewer/viewer-scene-header'
+export { ViewerStage, type ViewerStageProps } from './components/viewer/viewer-stage'
+export {
+  normalizeViewerStageModes,
+  resolveMobileViewerStageMode,
+  resolveViewerStageMode,
+  VIEWER_STAGE_MODES,
+  viewerStageIncludes3D,
+} from './components/viewer/viewer-stage-modes'
+export {
+  type ViewerStageMode,
+  ViewerStageSwitcher,
+  type ViewerStageSwitcherProps,
+} from './components/viewer/viewer-stage-switcher'
 export {
   WalkthroughHud,
   type WalkthroughHudProps,
@@ -310,6 +345,12 @@ export {
   resolveCeilingPlanPointSnap,
 } from './lib/ceiling-plan-snap'
 export { EDITOR_LAYER } from './lib/constants'
+export type { ContextualShortcutHint } from './lib/contextual-help'
+export {
+  CONTEXTUAL_HELP_NODE_EXTENSION_KEY,
+  type ContextualHelpNodeExtension,
+  getContextualHelpNodeExtension,
+} from './lib/contextual-help-extension'
 // Helper libs used by the kind-owned roof / stair / elevator panels.
 export {
   CONTINUATION_PROFILES,
@@ -318,6 +359,7 @@ export {
   continuationContextOf,
   nextContinuation,
 } from './lib/continuation'
+export { createEditorApi } from './lib/editor-api'
 export {
   clearStructuralElevationGuide,
   collectElevationSnapTargets,
@@ -325,6 +367,7 @@ export {
   type ElevationGuideSource,
   type ElevationSnapMatch,
   type ElevationSnapTarget,
+  publishResolvedElevationGuide,
   publishStructuralElevationGuide,
   resolveElevationSnapMatch,
   resolveStructuralElevationSnap,
@@ -335,6 +378,7 @@ export {
   resolveElevatorSupportLevelId,
   resolveElevatorSupportY,
 } from './lib/elevator-support'
+export { getFloatingMenuScale } from './lib/floating-menu-scale'
 // Floor-plan stair helpers — the cumulative-transform walk
 // (`computeFloorplanStairSegmentTransforms`) and the rich segment-entry
 // builder (`buildFloorplanStairEntry`) used by the kind-owned stair
@@ -359,6 +403,10 @@ export type {
   FloorplanAnnotationCategory,
   FloorplanAnnotationVisibility,
 } from './lib/floorplan/annotation-visibility'
+export {
+  exportFloorplanPdf,
+  type FloorplanExportScope,
+} from './lib/floorplan/floorplan-export'
 export {
   createFloorplanContextExtensions,
   FLOORPLAN_CONTEXT_EXTENSION_KEY,
@@ -384,23 +432,47 @@ export {
   type FloorplanMode,
   isFloorplanToolAvailableInMode,
 } from './lib/floorplan/floorplan-mode'
-export { commitFreshPlacementSubtree } from './lib/fresh-planar-placement'
-export { exportSceneToGlb } from './lib/glb-export'
 export {
+  commitFreshPlacementSubtree,
+  createFreshPlacementSubtree,
+} from './lib/fresh-planar-placement'
+export { exportSceneToGlb, type GlbExportOptions } from './lib/glb-export'
+export {
+  type EditorGridEvent,
+  type GridEventScreenProjection,
+  getGridEventScreenProjection,
+} from './lib/grid-event-presentation'
+export {
+  getHistoryCommandState,
   type HistoryCommandDelegate,
+  type HistoryCommandResult,
+  type HistoryCommandState,
   installHistoryCommandDelegate,
   runRedo,
   runUndo,
+  subscribeHistoryCommandState,
 } from './lib/history'
+export {
+  type EditorHostTreeChildren,
+  type EditorHostTreeChildrenProps,
+  editorHostTreeChildrenRegistry,
+  registerEditorHostTreeChildren,
+} from './lib/host-tree-children'
+export {
+  DRAFTING_SURFACE_EXTENSION_KEY,
+  type DraftingSurfaceExtension,
+} from './lib/interaction/registered-drafting'
 export {
   boundaryReshapeScope,
   curveReshapeScope,
   endpointReshapeScope,
   holeEditScope,
+  meshEditScope,
   movingNodeOf,
   scopeNodeId,
 } from './lib/interaction/scope'
 export {
+  type ActivePaintMaterial,
   buildResetSurfaceMaterialUpdates,
   buildRoofSurfaceMaterialPatch,
   buildSingleSurfaceMaterialPatch,
@@ -419,6 +491,14 @@ export {
   measurementPolygonLabelAnchor,
   triangulateMeasurementPolygon,
 } from './lib/measurement-label'
+export {
+  type LingoUnitSpec,
+  lingoUnitSpec,
+  type MeasurementHintOptions,
+  measurementHint,
+  type ParseMeasurementOptions,
+  parseMeasurement,
+} from './lib/measurement-parser'
 export {
   buildMeasurementAngleArcPoints,
   cubicMetersToVolumeUnit,
@@ -440,6 +520,12 @@ export {
   metersToLinearUnit,
   squareMetersToAreaUnit,
 } from './lib/measurements'
+export type {
+  ModelExport,
+  ModelExportArtifact,
+  ModelExportFormat,
+  ModelExportOptions,
+} from './lib/model-export'
 export { consumePlacementDragRelease } from './lib/placement-drag-release'
 export {
   addFreshPlacementMetadata,
@@ -483,6 +569,13 @@ export {
   type SlabPlanSnapInput,
   type SlabPlanSnapResult,
 } from './lib/slab-plan-snap'
+export {
+  getSnappingModeLabel,
+  resolveSnapFlags,
+  type SnapContext,
+  type SnapFlags,
+  type SnappingMode,
+} from './lib/snapping-mode'
 export { duplicateStairSubtree } from './lib/stair-duplication'
 export {
   getBuildingLevelsForLevel,
@@ -506,6 +599,7 @@ export {
   resolveFlattenTarget,
   sculptFieldForSite,
 } from './lib/terrain-sculpt'
+export { exportSceneToUsdz, type UsdzExportOptions } from './lib/usdz-export'
 // `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.
@@ -521,6 +615,7 @@ export {
 export { subscribeCameraPose } from './store/camera-pose-store'
 export { default as useAlignmentGuides } from './store/use-alignment-guides'
 export { default as useAudio } from './store/use-audio'
+export { type CameraHintAction, useCameraHintFocus } from './store/use-camera-hint-focus'
 export { type CommandAction, useCommandRegistry } from './store/use-command-registry'
 export {
   DRAWING_TYPE_OPTIONS,
@@ -529,17 +624,24 @@ export {
 export type {
   CaptureMode,
   FloorplanSelectionTool,
+  Mode,
   SnapshotCropMode,
   SnapshotStandardAspect,
   SplitOrientation,
+  StructureTool,
   Tool,
   ToolDefaults,
+  ToolMode,
   ViewMode,
   WorkspaceMode,
 } from './store/use-editor'
 export {
+  armMaterialPaint,
+  armToolMode,
   default as useEditor,
   getActiveContinuationContext,
+  getActiveSnapContext,
+  getActiveSnappingMode,
   getContinuation,
   isAlignmentGuideActive,
   isAngleSnapActive,
@@ -596,7 +698,10 @@ export {
   type PathDraftPoint,
   usePathDraftPreview,
 } from './store/use-path-draft-preview'
-export { default as usePlacementPreview } from './store/use-placement-preview'
+export {
+  default as usePlacementPreview,
+  type PlacementPreviewDimension,
+} from './store/use-placement-preview'
 export {
   activateQuickMeasurementHudSource,
   clearQuickMeasurementHudSource,

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

@@ -4,6 +4,7 @@ import {
   clearPlacementSurface,
   getPlacementSurface,
   publishPlacementSurface,
+  usesOrientedPlacementPlane,
 } from './active-placement-surface'
 
 describe('active placement surface', () => {
@@ -21,4 +22,19 @@ describe('active placement surface', () => {
 
     expect(getPlacementSurface()?.projection).toBe('surface')
   })
+
+  test('copies a stable lattice anchor when one is provided', () => {
+    publishPlacementSurface(
+      new Vector3(4, 2, 3),
+      new Vector3(0, 0, 1),
+      'surface',
+      new Vector3(1, 2, 3),
+    )
+
+    expect(getPlacementSurface()?.anchor?.toArray()).toEqual([1, 2, 3])
+  })
+
+  test('orients the grid to a sloped placement surface', () => {
+    expect(usesOrientedPlacementPlane(new Vector3(0, 0.6, 0.8))).toBe(true)
+  })
 })

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

@@ -11,12 +11,15 @@ import { Vector3 } from 'three'
 // readers must consume them within the same frame.
 export type PlacementSurface = {
   point: Vector3
+  /** Optional stable origin for the construction lattice. */
+  anchor?: Vector3
   normal: Vector3
   projection: 'surface' | 'fixed-plane'
 }
 
 const surface: PlacementSurface = {
   point: new Vector3(),
+  anchor: new Vector3(),
   normal: new Vector3(0, 1, 0),
   projection: 'surface',
 }
@@ -26,8 +29,15 @@ export function publishPlacementSurface(
   point: Vector3,
   normal: Vector3,
   projection: PlacementSurface['projection'] = 'surface',
+  anchor?: Vector3,
 ): void {
   surface.point.copy(point)
+  if (anchor) {
+    surface.anchor ??= new Vector3()
+    surface.anchor.copy(anchor)
+  } else {
+    surface.anchor = undefined
+  }
   surface.normal.copy(normal)
   surface.projection = projection
   active = true
@@ -40,3 +50,7 @@ export function clearPlacementSurface(): void {
 export function getPlacementSurface(): PlacementSurface | null {
   return active ? surface : null
 }
+
+export function usesOrientedPlacementPlane(normal: Vector3): boolean {
+  return Math.abs(normal.y) < 0.95
+}

package/src/lib/ceiling-surface-raycast.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  BackSide,
+  Mesh,
+  MeshBasicMaterial,
+  Path,
+  Raycaster,
+  Shape,
+  ShapeGeometry,
+  Vector3,
+} from 'three'
+import { raycastCeilingUnderside } from './ceiling-surface-raycast'
+
+function ceilingMesh() {
+  const shape = new Shape()
+  shape.moveTo(-2, -2)
+  shape.lineTo(2, -2)
+  shape.lineTo(2, 2)
+  shape.lineTo(-2, 2)
+  shape.closePath()
+  const hole = new Path()
+  hole.moveTo(-0.5, -0.5)
+  hole.lineTo(-0.5, 0.5)
+  hole.lineTo(0.5, 0.5)
+  hole.lineTo(0.5, -0.5)
+  hole.closePath()
+  shape.holes.push(hole)
+  const geometry = new ShapeGeometry(shape).rotateX(-Math.PI / 2)
+  const mesh = new Mesh(geometry, new MeshBasicMaterial({ side: BackSide }))
+  mesh.position.y = 3
+  mesh.updateMatrixWorld(true)
+  return mesh
+}
+
+describe('ceiling drawing surfaces', () => {
+  test('lets drawing pass through the transparent top while picking the underside', () => {
+    const ceiling = ceilingMesh()
+    for (const side of [-1, 1]) {
+      const ray = new Raycaster(new Vector3(1, 3 + side * 2, 0), new Vector3(0, -side, 0))
+      const hit = raycastCeilingUnderside(ray, ceiling)[0]
+      if (side > 0) {
+        expect(hit).toBeUndefined()
+      } else {
+        expect(hit?.point.y).toBeCloseTo(3)
+        expect(hit?.object).toBe(ceiling)
+      }
+      expect(ceiling.material.side).toBe(BackSide)
+    }
+    ceiling.geometry.dispose()
+    ceiling.material.dispose()
+  })
+
+  test('respects ceiling holes and the polygon boundary from either side', () => {
+    const ceiling = ceilingMesh()
+    for (const side of [-1, 1]) {
+      for (const x of [0, 3]) {
+        const ray = new Raycaster(new Vector3(x, 3 + side * 2, 0), new Vector3(0, -side, 0))
+        expect(raycastCeilingUnderside(ray, ceiling)).toHaveLength(0)
+      }
+    }
+    ceiling.geometry.dispose()
+    ceiling.material.dispose()
+  })
+})

package/src/lib/ceiling-surface-raycast.ts

@@ -0,0 +1,12 @@
+import { BackSide, Mesh, MeshBasicMaterial, type Object3D, type Raycaster } from 'three'
+
+const pickingMaterial = new MeshBasicMaterial({ side: BackSide })
+
+export function raycastCeilingUnderside(raycaster: Raycaster, ceiling: Object3D) {
+  if (!(ceiling instanceof Mesh)) return []
+  // Ignore the transparent top and its grid overlay so drawing can reach surfaces below.
+  const proxy = new Mesh(ceiling.geometry, pickingMaterial)
+  proxy.matrixWorld.copy(ceiling.matrixWorld)
+  proxy.layers.mask = ceiling.layers.mask
+  return raycaster.intersectObject(proxy, false).map((hit) => ({ ...hit, object: ceiling }))
+}

package/src/lib/contextual-help-extension.ts

@@ -0,0 +1,17 @@
+import type { NodeDefinition } from '@pascal-app/core'
+import type { ContextualShortcutHint } from './contextual-help'
+
+export const CONTEXTUAL_HELP_NODE_EXTENSION_KEY = 'pascal:editor/contextual-help'
+
+export type ContextualHelpNodeExtension = {
+  subscribe: (onChange: () => void) => () => void
+  getHints: (nodeId: string) => ContextualShortcutHint[]
+}
+
+export function getContextualHelpNodeExtension(
+  definition: NodeDefinition<any> | undefined,
+): ContextualHelpNodeExtension | undefined {
+  return definition?.extensions?.[CONTEXTUAL_HELP_NODE_EXTENSION_KEY] as
+    | ContextualHelpNodeExtension
+    | undefined
+}

package/src/lib/contextual-help.test.ts

@@ -73,6 +73,14 @@ describe('resolveSelectModeHelpHints', () => {
         label: 'Click or drag the selection to move it as one',
       },
       { keys: ['R / T'], label: 'Rotate the selection ±45°' },
+      {
+        keys: ['Cmd/Ctrl', 'G'],
+        label: 'Group selection (session only)',
+      },
+      {
+        keys: ['Cmd/Ctrl', 'Shift', 'G'],
+        label: 'Ungroup session selection',
+      },
       {
         keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
         label: 'Add or remove objects from the selection',

package/src/lib/contextual-help.ts

@@ -93,6 +93,14 @@ export function resolveSelectModeHelpHints({
       label: 'Click or drag the selection to move it as one',
     })
     hints.push({ keys: [ROTATE_KEYS], label: 'Rotate the selection ±45°' })
+    hints.push({
+      keys: [COMMAND_KEY, 'G'],
+      label: 'Group selection (session only)',
+    })
+    hints.push({
+      keys: [COMMAND_KEY, SHIFT_KEY, 'G'],
+      label: 'Ungroup session selection',
+    })
     hints.push({
       keys: [[COMMAND_KEY, SHIFT_KEY], LEFT_CLICK],
       label: 'Add or remove objects from the selection',

package/src/lib/continuation.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, test } from 'bun:test'
+import { CONTINUATION_PROFILES, continuationContextOf, nextContinuation } from './continuation'
+
+describe('canopy continuation', () => {
+  test('maps the canopy tool to its own single and continuous profile', () => {
+    expect(continuationContextOf('lean-to-extension')).toBe('canopy')
+    expect(CONTINUATION_PROFILES.canopy.default).toBe('single')
+    expect(nextContinuation('canopy', 'single')).toBe('continuous')
+    expect(nextContinuation('canopy', 'continuous')).toBe('single')
+  })
+})

package/src/lib/continuation.ts

@@ -1,4 +1,4 @@
-export type ContinuationContext = 'wall' | 'fence' | 'point' | 'cabinet'
+export type ContinuationContext = 'wall' | 'fence' | 'point' | 'cabinet' | 'canopy'
 export type ContinuationMode = string
 
 export const CONTINUATION_PROFILES: Record<
@@ -42,6 +42,12 @@ export const CONTINUATION_PROFILES: Record<
     labels: { single: 'Single cabinet', continuous: 'Continuous run' },
     icons: { single: 'lucide:minus', continuous: 'lucide:waypoints' },
   },
+  canopy: {
+    options: ['single', 'continuous'],
+    default: 'single',
+    labels: { single: 'Single canopy', continuous: 'Continuous canopy' },
+    icons: { single: 'lucide:minus', continuous: 'lucide:waypoints' },
+  },
 }
 
 const POINT_KINDS = new Set(['item', 'door', 'window', 'shelf', 'column'])
@@ -60,5 +66,6 @@ export function continuationContextOf(kind: string): ContinuationContext | null
   if (kind === 'wall') return 'wall'
   if (kind === 'fence') return 'fence'
   if (kind === 'cabinet') return 'cabinet'
+  if (kind === 'lean-to-extension') return 'canopy'
   return POINT_KINDS.has(kind) ? 'point' : null
 }