@pascal-app/editor 1.0.3 → 1.0.5

package/README.md

@@ -0,0 +1,106 @@
+# @pascal-app/editor
+
+The Pascal building editor as a React component: tools, panels, the floor plan, views and the agent chat surfaces, composed over `@pascal-app/viewer`.
+
+## Installation
+
+```bash
+npm install @pascal-app/core @pascal-app/viewer @pascal-app/editor @pascal-app/nodes
+```
+
+Load the built-in plugin once before mounting, as for the viewer (see the [viewer quick start](../viewer/README.md#usage)).
+
+## Usage
+
+```tsx
+import { Editor } from '@pascal-app/editor'
+
+export function ProjectPage({ projectId }: { projectId: string }) {
+  return (
+    <div className="dark" style={{ width: '100vw', height: '100vh' }}>
+      <Editor
+        layoutVersion="v2"
+        projectId={projectId}
+        onLoad={() => loadScene(projectId)}
+        onSave={(scene) => saveScene(projectId, scene)}
+        actionMenuPlacement="top"
+        loadingSlot={<MyProjectSpinner />}
+        onLoaderChange={(visible) => track('editor-loading', visible)}
+      />
+    </div>
+  )
+}
+```
+
+`apps/editor/components/scene-loader.tsx` is a complete host: navbar, sidebar tabs, toolbars and persistence.
+
+## Host props
+
+| Prop                  | What it does                                                                                                                                                                                                                                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `loadingSlot`         | Your loading surface, shown in the canvas panes of both layouts and in 2D and 3D while the scene loads. The editor still decides when loading is over and fires `onLoaderChange`; a failed load always shows the editor's error and retry screen. Omit it or pass `null` for the default loader. |
+| `actionMenuPlacement` | `'bottom'` (default) or `'top'`. With `'top'`, the v2 layout gives the tool menu its own row under the toolbar, centred on the scene panes and following them in split, so the bottom strip is free; v1 floats it at the top edge. Mobile keeps the bottom rail.                                 |
+| `viewBar`             | Each pane's view bar (v2, default `true`). Turn it off for a host that shows one fixed view.                                                                                                                                                                                                     |
+| `sceneOverlay`        | Chrome over the 3D and 2D panes with the level selector and tool dock, hidden while no scene view is on screen.                                                                                                                                                                                  |
+| `stageOverlay`        | A full-bleed surface over the whole stage; the scene stays mounted underneath. To show something beside the scene, register a view instead.                                                                                                                                                      |
+
+## Theme
+
+The editor sets no theme of its own: its chrome follows the nearest `.dark` ancestor, so leave the class off for a light editor. Menus and tooltips portal to `<body>`, so put `dark` there too (or on `<html>`) for a dark one. Hand the person a theme switch with `InterfaceThemeRow` in the settings panel's `preferences` slot:
+
+```tsx
+import { InterfaceThemeRow, SettingsPanel, type InterfaceTheme } from '@pascal-app/editor'
+
+<SettingsPanel
+  preferences={<InterfaceThemeRow value={theme} onChange={(next: InterfaceTheme) => setTheme(next)} />}
+/>
+```
+
+`theme` is `'system' | 'light' | 'dark'`; applying it (toggling `.dark`) is the host's. A host that passes no row gets none. The Preview stage, the walkthrough HUD and the controls bar stay dark in either theme. The viewer's own "Scene theme" is separate (see [materials and themes](../../wiki/architecture/materials-and-themes.md)).
+
+## Views
+
+The stage is one or two panes, each showing a view: 3D, 2D, or one a plugin registers.
+
+```tsx
+import { openEditorView, PLUGINS_VIEW_ID, registerEditorHostView } from '@pascal-app/editor'
+
+registerEditorHostView({
+  id: 'acme:signage:schedule',
+  label: 'Sign schedule',
+  icon: { kind: 'url', src: '/icons/signs.webp' },
+  component: () => import('./schedule-view'),
+  pluginId: 'acme:signage',
+})
+
+openEditorView('acme:signage:schedule', { beside: true }) // split, next to the scene
+openEditorView(PLUGINS_VIEW_ID) // the plugin directory
+```
+
+Each workspace keeps its own layout, and swapping panes never remounts the 3D canvas or the plan. `\` toggles split. The full contract is in [plugin authoring](../../wiki/architecture/plugin-authoring.md).
+
+## Selecting and showing a node
+
+The helpers the editor's own lists use:
+
+```ts
+import { enterUnitFocus, frameViewerNode, selectZoneOrRoom } from '@pascal-app/editor'
+
+selectZoneOrRoom(zoneId) // 'room' for an enclosed room, else 'zone'
+frameViewerNode(nodeId, source) // the node's saved view, else its box; the plan frames it when no 3D view is on screen
+enterUnitFocus(unitId) // focus a unit, as the site panel does
+```
+
+What a host's chat points at (`useViewer.pointedIds`) lights in the plan and as a room outline, as well as in 3D. See [selection managers](../../wiki/architecture/selection-managers.md) and [point and ask](../../wiki/architecture/point-and-ask.md).
+
+## Plugin chat surfaces
+
+A plugin's `PluginChatExtension` can give a host's chat a start screen (`start`), shown while the thread is empty and acting through `ChatStartProps` (`send`, `attach`, `requirePro`). `IconRefGlyph` and `IconRefImage` render registry icons the way the editor does:
+
+```tsx
+import { IconRefGlyph } from '@pascal-app/editor'
+
+<IconRefGlyph icon={view.icon} />
+```
+
+See [plugin authoring, agent tools and chat extensions](../../wiki/architecture/plugin-authoring.md#agent-tools-and-chat-extensions).

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "@pascal-app/editor",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Pascal building editor component",
   "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./src/index.tsx",
     "./catalog": "./src/components/ui/item-catalog/catalog-items.tsx",
-    "./procedural-items": "./src/components/procedural-items/inspector.tsx"
+    "./procedural-items": "./src/components/procedural-items/inspector.tsx",
+    "./distribution": "./src/components/tools/distribution/distribution-public.ts"
   },
   "scripts": {
+    "bench:room-labels": "bun run src/components/editor/__bench__/room-label-placement.bench.ts",
     "check-types": "tsgo --noEmit",
     "test": "bun test src"
   },
   "peerDependencies": {
-    "@pascal-app/core": "^1.0.3",
-    "@pascal-app/viewer": "^1.0.3",
+    "@pascal-app/core": "^1.0.5",
+    "@pascal-app/viewer": "^1.0.5",
     "@react-three/drei": "^10",
     "@react-three/fiber": "^9",
     "next": ">=15",
@@ -27,21 +29,23 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@iconify/react": "^6.0.2",
-    "@number-flow/react": "^0.6.0",
-    "@pascal-app/lingo": "^0.2.0",
-    "@radix-ui/react-alert-dialog": "^1.1.15",
-    "@radix-ui/react-context-menu": "^2.2.16",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-select": "^2.2.6",
-    "@radix-ui/react-separator": "^1.1.8",
-    "@radix-ui/react-slider": "^1.3.6",
-    "@radix-ui/react-slot": "^1.2.4",
-    "@radix-ui/react-switch": "^1.2.6",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-tooltip": "^1.2.8",
+    "@iconify/react": "^6.0.3",
+    "@number-flow/react": "^0.6.2",
+    "@pascal-app/geometry-script": "^1.0.5",
+    "@pascal-app/ifc-converter": "^1.0.5",
+    "@pascal-app/lingo": "^0.5.0",
+    "@radix-ui/react-alert-dialog": "^1.2.1",
+    "@radix-ui/react-context-menu": "^2.4.1",
+    "@radix-ui/react-dialog": "^1.3.1",
+    "@radix-ui/react-dropdown-menu": "^2.2.1",
+    "@radix-ui/react-popover": "^1.3.1",
+    "@radix-ui/react-select": "^2.4.1",
+    "@radix-ui/react-separator": "^1.2.0",
+    "@radix-ui/react-slider": "^1.6.1",
+    "@radix-ui/react-slot": "^1.5.0",
+    "@radix-ui/react-switch": "^1.4.1",
+    "@radix-ui/react-tabs": "^1.2.1",
+    "@radix-ui/react-tooltip": "^1.4.1",
     "@visual-json/react": "^0.4.0",
     "blob-stream": "^0.1.3",
     "class-variance-authority": "^0.7.1",
@@ -49,32 +53,32 @@
     "cmdk": "^1.1.1",
     "fflate": "^0.8.3",
     "howler": "^2.2.4",
-    "lucide-react": "^1.7.0",
-    "manifold-3d": "3.5.1",
+    "lucide-react": "^1.61.0",
+    "manifold-3d": "3.5.4",
     "mitt": "^3.0.1",
-    "motion": "^12.34.3",
-    "nanoid": "^5.1.6",
-    "pdfkit": "^0.19.1",
-    "tailwind-merge": "^3.5.0",
+    "motion": "^14.5.0",
+    "nanoid": "^6.0.2",
+    "pdfkit": "^0.20.2",
+    "tailwind-merge": "^3.7.0",
     "three-bvh-csg": "^0.0.18",
-    "three-mesh-bvh": "~0.9.8",
-    "zod": ">=4.5.4 <4.6",
-    "zustand": "^5.0.11"
+    "three-mesh-bvh": "~0.9.16",
+    "zod": ">=4.6.7 <4.7",
+    "zustand": "^5.0.15"
   },
   "devDependencies": {
-    "@pascal-app/core": "^1.0.3",
-    "@pascal-app/viewer": "^1.0.3",
+    "@pascal-app/core": "^1.0.5",
+    "@pascal-app/viewer": "^1.0.5",
     "@pascal/typescript-config": "*",
-    "@react-three/test-renderer": "^9.1.0",
+    "@react-three/test-renderer": "^9.1.1",
     "@types/blob-stream": "^0.1.33",
-    "@types/bun": "^1.3.0",
-    "@types/howler": "^2.2.12",
+    "@types/bun": "^1.4.3",
+    "@types/howler": "^2.2.13",
     "@types/pdfkit": "^0.17.6",
-    "@types/react": "19.2.2",
-    "@types/react-dom": "19.2.2",
-    "@types/three": "^0.184.0",
-    "fast-xml-parser": "^5.4.2",
-    "typescript": "6.0.3"
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@types/three": "^0.186.0",
+    "fast-xml-parser": "^5.11.2",
+    "typescript": "7.0.2"
   },
   "repository": {
     "type": "git",

package/src/components/editor/__bench__/room-label-placement.bench.ts

@@ -0,0 +1,108 @@
+import type { Polygon } from '@pascal-app/core'
+import {
+  type PillCandidate,
+  placePills,
+  type RoomHit,
+  type RoomLabelEntry,
+  roomAt,
+} from '../room-labels'
+
+// One room-label placement pass and one pointer pick, for a 900 × 600 px house of 31, 60 and 120
+// rooms (every third an L), printed as JSON medians in ms. Run with `bun run <this file>`.
+let seed = 11
+const random = () => {
+  seed = (seed * 1_103_515_245 + 12_345) % 2 ** 31
+  return seed / 2 ** 31
+}
+
+function house(count: number) {
+  const columns = Math.ceil(Math.sqrt(count * 1.5))
+  const rows = Math.ceil(count / columns)
+  const width = 900 / columns
+  const depth = 600 / rows
+  return Array.from({ length: count }, (_, i) => {
+    const left = 270 + (i % columns) * width
+    const top = 150 + Math.floor(i / columns) * depth
+    const right = left + width
+    const bottom = top + depth
+    const outer: [number, number][] =
+      i % 3 === 0
+        ? [
+            [left, top],
+            [right, top],
+            [right, top + depth / 2],
+            [left + width / 2, top + depth / 2],
+            [left + width / 2, bottom],
+            [left, bottom],
+          ]
+        : [
+            [left, top],
+            [right, top],
+            [right, bottom],
+            [left, bottom],
+          ]
+    const outline: Polygon = { outer, holes: [] }
+    const pill = 60 + random() * 110
+    const candidate: PillCandidate = {
+      id: `room_${i}`,
+      x: left + width / 4,
+      y: top + depth / 4,
+      size: [pill, 24, pill * 0.6],
+      area: width * depth * (i % 3 === 0 ? 0.75 : 1),
+      outline,
+    }
+    const entry: RoomLabelEntry = {
+      zoneId: candidate.id,
+      polygon: outer,
+      holes: [],
+      area: candidate.area,
+    }
+    return { candidate, entry }
+  })
+}
+
+const median = (samples: number[]) => samples.sort((a, b) => a - b)[samples.length >> 1]!
+
+const pane = { width: 1440, height: 900 }
+const results: Record<string, unknown> = {}
+for (const count of [31, 60, 120]) {
+  const rooms = house(count)
+  const candidates = rooms.map((room) => room.candidate)
+  const entries = rooms.map((room) => room.entry)
+  for (let i = 0; i < 20; i++) placePills(candidates, pane)
+  const cold: number[] = []
+  const warm: number[] = []
+  let previous = placePills(candidates, pane)
+  for (let i = 0; i < 100; i++) {
+    let started = performance.now()
+    placePills(candidates, pane)
+    cold.push(performance.now() - started)
+    started = performance.now()
+    previous = placePills(candidates, pane, previous)
+    warm.push(performance.now() - started)
+  }
+  const points = Array.from(
+    { length: 1000 },
+    (): RoomHit => [270 + random() * 900, 150 + random() * 600, 0],
+  )
+  for (const point of points) roomAt(entries, () => point)
+  const picks: number[] = []
+  for (let i = 0; i < 20; i++) {
+    const started = performance.now()
+    for (const point of points) roomAt(entries, () => point)
+    picks.push((performance.now() - started) / points.length)
+  }
+  const tiers = Object.fromEntries(
+    ['full', 'name', 'dot', 'hidden'].map((tier) => [
+      tier,
+      [...previous.values()].filter((placement) => placement.tier === tier).length,
+    ]),
+  )
+  results[count] = {
+    placeMs: median(cold),
+    placeWithPreviousMs: median(warm),
+    pickMs: median(picks),
+    tiers,
+  }
+}
+console.log(JSON.stringify(results, null, 2))

package/src/components/editor/action-menu-button.tsx

@@ -0,0 +1,83 @@
+'use client'
+
+import type { MouseEventHandler, ReactNode } from 'react'
+import { cn } from '../../lib/utils'
+import { shortcutDisplayValue } from '../ui/primitives/shortcut-token'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/primitives/tooltip'
+
+const BUTTON =
+  'rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground'
+const DESTRUCTIVE = 'hover:bg-destructive/10 hover:text-destructive'
+const DISABLED = 'cursor-not-allowed opacity-40 hover:bg-transparent hover:text-muted-foreground'
+
+/**
+ * One button of an action pill, with the editor's tooltip: its name, and the
+ * keys that do the same where there are any. A disabled button still shows
+ * its tooltip (it stays hoverable) so it can say why it is off.
+ */
+export function ActionMenuButton({
+  label,
+  keys,
+  onClick,
+  destructive = false,
+  disabled = false,
+  disabledReason,
+  pressed,
+  children,
+}: {
+  label: string
+  /** Keys pressed together, as `ShortcutToken` names them (`Cmd/Ctrl`, `G`). */
+  keys?: string[]
+  onClick?: MouseEventHandler<HTMLButtonElement>
+  destructive?: boolean
+  disabled?: boolean
+  /** The tooltip while disabled; the label otherwise. */
+  disabledReason?: string
+  /** A toggle's state: sets `aria-pressed` and the active look. */
+  pressed?: boolean
+  children: ReactNode
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          aria-disabled={disabled || undefined}
+          aria-label={label}
+          aria-pressed={pressed}
+          className={cn(
+            BUTTON,
+            destructive && DESTRUCTIVE,
+            disabled && DISABLED,
+            pressed && 'bg-accent text-foreground',
+          )}
+          data-action-disabled={disabled || undefined}
+          onClick={(event) => {
+            if (disabled) {
+              event.stopPropagation()
+              return
+            }
+            onClick?.(event)
+          }}
+          type="button"
+        >
+          {children}
+        </button>
+      </TooltipTrigger>
+      <TooltipContent className="flex items-center gap-2" side="top" sideOffset={6}>
+        <span>{disabled && disabledReason ? disabledReason : label}</span>
+        {!disabled && keys?.length ? (
+          <span className="flex items-center gap-0.5">
+            {keys.map((key) => (
+              <kbd
+                className="rounded border border-background/30 px-1 font-mono text-[10px] leading-4 opacity-80"
+                key={key}
+              >
+                {shortcutDisplayValue(key)}
+              </kbd>
+            ))}
+          </span>
+        ) : null}
+      </TooltipContent>
+    </Tooltip>
+  )
+}