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

package/src/lib/paint-preview-owner.ts

@@ -0,0 +1,71 @@
+export type PaintPreviewCleanup = (() => void) & { commit?: () => void }
+
+type Interaction = {
+  key: string
+  apply: (() => void) | null
+  preview: (() => PaintPreviewCleanup | null) | null
+}
+
+export function combinePaintPreviews(previews: PaintPreviewCleanup[]): PaintPreviewCleanup {
+  const finish = (committed: boolean) => {
+    const pending = previews.splice(0).reverse()
+    let failure: unknown
+    for (const cleanup of pending) {
+      try {
+        if (committed) cleanup.commit?.()
+        else cleanup()
+      } catch (error) {
+        failure ??= error
+      }
+    }
+    if (failure) throw failure
+  }
+  return Object.assign(() => finish(false), { commit: () => finish(true) })
+}
+
+export function createPaintPreviewOwner() {
+  let active: { key: string; cleanup: PaintPreviewCleanup } | null = null
+  const end = (committed = false) => {
+    const previous = active
+    active = null
+    if (committed) previous?.cleanup.commit?.()
+    else previous?.cleanup()
+  }
+  return {
+    wrap<T extends Interaction>(interaction: T | null): T | null {
+      if (!interaction) return null
+      return {
+        ...interaction,
+        preview: interaction.preview
+          ? () => {
+              end()
+              const cleanup = interaction.preview!()
+              if (!cleanup) return null
+              const owned = { key: interaction.key, cleanup }
+              active = owned
+              return () => {
+                if (active === owned) end()
+              }
+            }
+          : null,
+        apply: interaction.apply
+          ? () => {
+              if (active && active.key !== interaction.key) end()
+              try {
+                interaction.apply!()
+              } catch (error) {
+                // A subscriber can throw after the scene write has already been published.
+                try {
+                  end(true)
+                } catch {
+                  // Preserve the apply error even if a hold listener also throws.
+                }
+                throw error
+              }
+              end(true)
+            }
+          : null,
+      }
+    },
+  }
+}

package/src/lib/paint-scope.test.ts

@@ -81,8 +81,8 @@ describe('paintScopeLabel', () => {
 function item(id: string, assetId: string): ItemNode {
   return { id, type: 'item', asset: { id: assetId } } as unknown as ItemNode
 }
-function slab(id: string, polygon: Array<[number, number]>): SlabNode {
-  return { id, type: 'slab', polygon } as unknown as SlabNode
+function slab(id: string, polygon: Array<[number, number]>, levelId = 'l1'): SlabNode {
+  return { id, type: 'slab', polygon, parentId: levelId } as unknown as SlabNode
 }
 function wall(
   id: string,
@@ -451,4 +451,60 @@ describe('resolvePaintScopeTargets', () => {
     })
     expect(keys(result).sort()).toEqual(['inA:surface', 'inB:surface'])
   })
+
+  it('slab room stops at the level boundary', () => {
+    // Stacked storeys share a footprint, so the upper slab's centroid sits inside
+    // the ground floor's space polygon. Painting downstairs must not reach it.
+    const ground = slab(
+      'ground',
+      [
+        [1, 1],
+        [3, 1],
+        [3, 3],
+        [1, 3],
+      ],
+      'l1',
+    )
+    const upstairs = slab(
+      'upstairs',
+      [
+        [1, 1],
+        [3, 1],
+        [3, 3],
+        [1, 3],
+      ],
+      'l2',
+    )
+    const footprint: Array<[number, number]> = [
+      [0, 0],
+      [10, 0],
+      [10, 10],
+      [0, 10],
+    ]
+    const result = resolve({
+      node: ground,
+      role: 'surface',
+      scope: 'room',
+      nodes: [ground, upstairs],
+      spaces: [
+        {
+          id: 's1',
+          levelId: 'l1',
+          polygon: footprint,
+          wallIds: [],
+          boundaryFaces: [],
+          isExterior: false,
+        },
+        {
+          id: 's2',
+          levelId: 'l2',
+          polygon: footprint,
+          wallIds: [],
+          boundaryFaces: [],
+          isExterior: false,
+        },
+      ],
+    })
+    expect(keys(result)).toEqual(['ground:surface'])
+  })
 })

package/src/lib/paint-scope.ts

@@ -355,13 +355,19 @@ export function resolvePaintScopeTargets(args: {
   if (node.type === 'slab' && scope === 'room') {
     const centroid = polygonCentroid((node as SlabNode).polygon)
     if (!centroid) return single
-    const space = Object.values(spaces).find((candidate) =>
-      pointInPolygon2D(centroid, candidate.polygon),
+    // Space polygons are per-level footprints, and stacked storeys share a
+    // footprint — so the level has to gate both the space lookup and the fan-out
+    // or one click paints the floor above too.
+    const levelId = node.parentId ?? resolveLevelId(node, nodes)
+    if (!levelId) return single
+    const space = Object.values(spaces).find(
+      (candidate) => candidate.levelId === levelId && pointInPolygon2D(centroid, candidate.polygon),
     )
     if (!space) return single
     return Object.values(nodes)
       .filter((other) => {
         if (other.type !== 'slab') return false
+        if ((other.parentId ?? resolveLevelId(other, nodes)) !== levelId) return false
         const otherCentroid = polygonCentroid((other as SlabNode).polygon)
         return otherCentroid != null && pointInPolygon2D(otherCentroid, space.polygon)
       })

package/src/lib/planar-cursor-placement.test.ts

@@ -1,9 +1,90 @@
 import { describe, expect, test } from 'bun:test'
-import { resolvePlanarCursorPosition } from './planar-cursor-placement'
+import {
+  offsetPlanPositionByLocalCenter,
+  resolvePlanarCursorPosition,
+  resolvePrioritizedPlanarCursorPosition,
+} from './planar-cursor-placement'
 
 const snapHalf = (value: number) => Math.round(value / 0.5) * 0.5
 
 describe('resolvePlanarCursorPosition', () => {
+  test('absolute mode puts the unrotated footprint centre at the snapped cursor', () => {
+    const result = resolvePlanarCursorPosition({
+      cursor: [4.24, 2.26],
+      original: [0, 0],
+      anchor: null,
+      mode: 'absolute',
+      localCenter: [1.3, 0.5, 0.2],
+      snap: snapHalf,
+    })
+
+    expect(result.point).toEqual([2.7, 2.3])
+    expect(result.anchor).toBeNull()
+  })
+
+  test('absolute mode snaps the centre before deriving the rotated origin', () => {
+    const proposals: [number, number][] = []
+    const localCenter: [number, number, number] = [1.3, 0.5, 0.2]
+    const result = resolvePlanarCursorPosition({
+      cursor: [4.24, 2.26],
+      original: [0, 0],
+      anchor: null,
+      mode: 'absolute',
+      localCenter,
+      rotationY: Math.PI / 2,
+      snapPoint: (point) => {
+        proposals.push(point)
+        return [snapHalf(point[0]), snapHalf(point[1])]
+      },
+    })
+
+    expect(proposals).toEqual([[4.24, 2.26]])
+    expect(result.point[0]).toBeCloseTo(3.8)
+    expect(result.point[1]).toBeCloseTo(3.8)
+    const centre = offsetPlanPositionByLocalCenter(
+      [result.point[0], 0, result.point[1]],
+      localCenter,
+      Math.PI / 2,
+    )
+    expect(centre[0]).toBeCloseTo(4)
+    expect(centre[2]).toBeCloseTo(2.5)
+  })
+
+  test('absolute mode follows the unsnapped cursor at an oblique rotation', () => {
+    const localCenter: [number, number, number] = [1.5, 0.5, -0.3]
+    const result = resolvePlanarCursorPosition({
+      cursor: [-2.13, 6.27],
+      original: [0, 0],
+      anchor: null,
+      mode: 'absolute',
+      localCenter,
+      rotationY: -Math.PI / 4,
+    })
+    const centre = offsetPlanPositionByLocalCenter(
+      [result.point[0], 0, result.point[1]],
+      localCenter,
+      -Math.PI / 4,
+    )
+
+    expect(centre[0]).toBeCloseTo(-2.13)
+    expect(centre[2]).toBeCloseTo(6.27)
+  })
+
+  test('relative mode ignores the footprint centre and rotation', () => {
+    const result = resolvePlanarCursorPosition({
+      cursor: [4.9, 5.2],
+      original: [10, 20],
+      anchor: [4.1, 6.1],
+      mode: 'relative',
+      localCenter: [1.3, 0.5, 0.2],
+      rotationY: Math.PI / 2,
+      snap: snapHalf,
+    })
+
+    expect(result.point).toEqual([11, 19])
+    expect(result.anchor).toEqual([4.1, 6.1])
+  })
+
   test('absolute mode places the point directly at the snapped cursor', () => {
     const result = resolvePlanarCursorPosition({
       cursor: [1.24, -2.26],
@@ -98,3 +179,99 @@ describe('resolvePlanarCursorPosition', () => {
     expect(centerMoved.point[1]).toBeCloseTo(moved.point[1])
   })
 })
+
+describe('resolvePrioritizedPlanarCursorPosition', () => {
+  test('attachment receives the corrected raw origin and returns the final origin', () => {
+    const proposals: [number, number][] = []
+    const result = resolvePrioritizedPlanarCursorPosition({
+      cursor: [4.24, 2.26],
+      original: [0, 0],
+      anchor: null,
+      mode: 'absolute',
+      localCenter: [1.3, 0.5, 0.2],
+      rotationY: Math.PI / 2,
+      snapPoint: () => {
+        throw new Error('Grid snapping must not run after attachment')
+      },
+      resolveAttachment: (proposal) => {
+        proposals.push(proposal)
+        return [3, 5]
+      },
+    })
+
+    expect(proposals).toHaveLength(1)
+    expect(proposals[0]![0]).toBeCloseTo(4.04)
+    expect(proposals[0]![1]).toBeCloseTo(3.56)
+    expect(result.point).toEqual([3, 5])
+    expect(result.attachmentSnapped).toBe(true)
+  })
+
+  test('snaps the footprint centre when attachment declines the corrected origin', () => {
+    const result = resolvePrioritizedPlanarCursorPosition({
+      cursor: [4.24, 2.26],
+      original: [0, 0],
+      anchor: null,
+      mode: 'absolute',
+      localCenter: [1.3, 0.5, 0.2],
+      snapPoint: ([x, z]) => [snapHalf(x), snapHalf(z)],
+      resolveAttachment: () => null,
+    })
+
+    expect(result.point).toEqual([2.7, 2.3])
+    expect(result.attachmentSnapped).toBe(false)
+  })
+
+  test('wall attachment receives the raw proposal and wins over grid snapping', () => {
+    const attachmentProposals: [number, number][] = []
+    const result = resolvePrioritizedPlanarCursorPosition({
+      cursor: [0.73, 0.32],
+      original: [0, 0],
+      anchor: null,
+      mode: 'absolute',
+      snap: snapHalf,
+      resolveAttachment: (proposal) => {
+        attachmentProposals.push(proposal)
+        return [proposal[0], 0.39]
+      },
+    })
+
+    expect(attachmentProposals).toEqual([[0.73, 0.32]])
+    expect(result.point).toEqual([0.73, 0.39])
+    expect(result.attachmentSnapped).toBe(true)
+  })
+
+  test('falls back to the grid proposal when there is no attachment', () => {
+    const result = resolvePrioritizedPlanarCursorPosition({
+      cursor: [0.73, 0.32],
+      original: [0, 0],
+      anchor: null,
+      mode: 'absolute',
+      snap: snapHalf,
+      resolveAttachment: () => null,
+    })
+
+    expect(result.point).toEqual([0.5, 0.5])
+    expect(result.attachmentSnapped).toBe(false)
+  })
+
+  test('supports footprint-aware point snapping after attachment resolution', () => {
+    const pointProposals: [number, number][] = []
+    const result = resolvePrioritizedPlanarCursorPosition({
+      cursor: [1.03, 2.04],
+      original: [0.8, 1.8],
+      anchor: [0.9, 1.9],
+      mode: 'relative',
+      snapPoint: (proposal) => {
+        pointProposals.push(proposal)
+        return [0.8, 2.29]
+      },
+      resolveAttachment: () => null,
+    })
+
+    expect(pointProposals).toHaveLength(1)
+    expect(pointProposals[0]![0]).toBeCloseTo(0.93)
+    expect(pointProposals[0]![1]).toBeCloseTo(1.94)
+    expect(result.point).toEqual([0.8, 2.29])
+    expect(result.attachmentSnapped).toBe(false)
+  })
+})

package/src/lib/planar-cursor-placement.ts

@@ -7,7 +7,10 @@ type ResolvePlanarCursorPositionArgs = {
   original: PlanarPoint
   anchor: PlanarPoint | null
   mode: PlanarCursorPlacementMode
+  localCenter?: [number, number, number]
+  rotationY?: number
   snap?: (value: number) => number
+  snapPoint?: (point: PlanarPoint) => PlanarPoint
 }
 
 type ResolvePlanarCursorPositionResult = {
@@ -15,28 +18,81 @@ type ResolvePlanarCursorPositionResult = {
   anchor: PlanarPoint | null
 }
 
+type ResolvePrioritizedPlanarCursorPositionArgs = ResolvePlanarCursorPositionArgs & {
+  resolveAttachment?: (proposal: PlanarPoint) => PlanarPoint | null
+}
+
+type ResolvePrioritizedPlanarCursorPositionResult = ResolvePlanarCursorPositionResult & {
+  attachmentSnapped: boolean
+}
+
 const identity = (value: number) => value
 
+export function offsetPlanPositionByLocalCenter(
+  position: [number, number, number],
+  center: [number, number, number],
+  rotationY: number,
+): [number, number, number] {
+  const cos = Math.cos(rotationY)
+  const sin = Math.sin(rotationY)
+  return [
+    position[0] + center[0] * cos + center[2] * sin,
+    position[1] + center[1],
+    position[2] - center[0] * sin + center[2] * cos,
+  ]
+}
+
 export function resolvePlanarCursorPosition({
   cursor,
   original,
   anchor,
   mode,
+  localCenter,
+  rotationY = 0,
   snap = identity,
+  snapPoint,
 }: ResolvePlanarCursorPositionArgs): ResolvePlanarCursorPositionResult {
   if (mode === 'absolute') {
+    const proposal: PlanarPoint = [cursor[0], cursor[1]]
+    const snapped: PlanarPoint = snapPoint?.(proposal) ?? [snap(cursor[0]), snap(cursor[1])]
+    const origin: [number, number, number] = localCenter
+      ? offsetPlanPositionByLocalCenter(
+          [snapped[0], 0, snapped[1]],
+          [-localCenter[0], 0, -localCenter[2]],
+          rotationY,
+        )
+      : [snapped[0], 0, snapped[1]]
     return {
-      point: [snap(cursor[0]), snap(cursor[1])],
+      point: [origin[0], origin[2]],
       anchor,
     }
   }
 
   const resolvedAnchor = anchor ?? cursor
+  const delta: PlanarPoint = [cursor[0] - resolvedAnchor[0], cursor[1] - resolvedAnchor[1]]
+  const proposal: PlanarPoint = [original[0] + delta[0], original[1] + delta[1]]
   return {
-    point: [
-      original[0] + snap(cursor[0] - resolvedAnchor[0]),
-      original[1] + snap(cursor[1] - resolvedAnchor[1]),
-    ],
+    point: snapPoint?.(proposal) ?? [original[0] + snap(delta[0]), original[1] + snap(delta[1])],
     anchor: resolvedAnchor,
   }
 }
+
+export function resolvePrioritizedPlanarCursorPosition({
+  resolveAttachment,
+  ...args
+}: ResolvePrioritizedPlanarCursorPositionArgs): ResolvePrioritizedPlanarCursorPositionResult {
+  const raw = resolvePlanarCursorPosition({ ...args, snap: identity, snapPoint: undefined })
+  const attached = resolveAttachment?.(raw.point) ?? null
+  if (attached) {
+    return {
+      point: attached,
+      anchor: raw.anchor,
+      attachmentSnapped: true,
+    }
+  }
+
+  return {
+    ...resolvePlanarCursorPosition(args),
+    attachmentSnapped: false,
+  }
+}

package/src/lib/plugin-panels.test.ts

@@ -1,5 +1,11 @@
 import { afterEach, describe, expect, test } from 'bun:test'
-import { editorHostPanelRegistry, registerEditorHostPanel } from './plugin-panels'
+import {
+  type EditorHostPanel,
+  editorHostPanelRegistry,
+  managedPluginIds,
+  registerEditorHostPanel,
+  showsPluginManager,
+} from './plugin-panels'
 
 describe('editorHostPanelRegistry', () => {
   afterEach(() => editorHostPanelRegistry.reset())
@@ -17,3 +23,88 @@ describe('editorHostPanelRegistry', () => {
     expect(editorHostPanelRegistry.panelForKind('wall')).toBeUndefined()
   })
 })
+
+const panel = (id: string, pluginId?: string): EditorHostPanel => ({
+  component: async () => ({ default: () => null }),
+  icon: { kind: 'url', src: '/x.webp' },
+  id,
+  label: id,
+  ...(pluginId ? { pluginId } : {}),
+})
+
+describe('managedPluginIds', () => {
+  test('counts plugins, not panels — one plugin with two panels is one plugin', () => {
+    expect(
+      managedPluginIds([
+        panel('pascal:boots:game', 'pascal:boots'),
+        panel('pascal:boots:keep', 'pascal:boots'),
+        panel('pascal:trees:nature', 'pascal:trees'),
+      ]),
+    ).toEqual(['pascal:boots', 'pascal:trees'])
+  })
+
+  test("the editor's own panels are not plugins", () => {
+    // No `pluginId` means it came from the host app, not from a plugin, and
+    // there is nothing to install or uninstall.
+    expect(managedPluginIds([panel('site'), panel('settings')])).toEqual([])
+    expect(managedPluginIds([])).toEqual([])
+  })
+})
+
+/**
+ * THE EMPTY LOBBY PANEL (owner report 2026-08-31). `/play/<id>` mounts the
+ * editor read-only and registers no host panels, so the plugin *manager* was
+ * the only tab in the rail: it opened by default onto a bare "Plugins" heading
+ * eating ~40% of a visitor's window. Dropping the last tab makes the v2 layout
+ * drop the left column entirely, which is the lobby as designed.
+ *
+ * The line to hold is that this hides an EMPTY manager and never a populated
+ * one — a read-only viewer in the real editor can still see what a project uses.
+ */
+describe('showsPluginManager', () => {
+  test('the open lobby — read-only with nothing registered — gets no rail at all', () => {
+    expect(
+      showsPluginManager({ managedPluginCount: 0, readOnly: true, workspaceMode: 'edit' }),
+    ).toBe(false)
+  })
+
+  test('a read-only editor keeps the manager as soon as a plugin is registered', () => {
+    // Browsing what a project uses is a read, and the install button is
+    // already disabled on its own.
+    expect(
+      showsPluginManager({ managedPluginCount: 1, readOnly: true, workspaceMode: 'edit' }),
+    ).toBe(true)
+  })
+
+  test('a writable scene always keeps it, even with zero plugins', () => {
+    // The empty state is still useful to an owner: it is where "Create a
+    // Pascal plugin" lives.
+    expect(
+      showsPluginManager({ managedPluginCount: 0, readOnly: false, workspaceMode: 'edit' }),
+    ).toBe(true)
+    expect(
+      showsPluginManager({ managedPluginCount: 3, readOnly: false, workspaceMode: 'edit' }),
+    ).toBe(true)
+  })
+
+  test('never outside the edit workspace — studio has its own rail', () => {
+    for (const readOnly of [false, true]) {
+      for (const managedPluginCount of [0, 2]) {
+        expect(
+          showsPluginManager({ managedPluginCount, readOnly, workspaceMode: 'studio' }),
+          `readOnly=${readOnly} count=${managedPluginCount}`,
+        ).toBe(false)
+      }
+    }
+  })
+
+  test('the pre-existing behaviour is unchanged for the normal editor', () => {
+    // Regression fence: before this gate the rule was `workspaceMode === 'edit'`
+    // alone. Every writable edit-workspace case must still answer the same.
+    for (const managedPluginCount of [0, 1, 5]) {
+      expect(
+        showsPluginManager({ managedPluginCount, readOnly: false, workspaceMode: 'edit' }),
+      ).toBe(true)
+    }
+  })
+})

package/src/lib/plugin-panels.ts

@@ -89,3 +89,51 @@ export const editorHostPanelRegistry = new EditorHostPanelRegistryImpl()
 export function registerEditorHostPanel(panel: EditorHostPanel): void {
   editorHostPanelRegistry.registerPanel(panel)
 }
+
+/**
+ * The distinct plugins the manager can act on — every registered panel that
+ * declares a `pluginId`, deduplicated, because one plugin may contribute
+ * several panels and the manager lists plugins, not panels.
+ *
+ * Registration is what makes a plugin *manageable*, not installation: an
+ * uninstalled plugin still has to appear so it can be installed.
+ */
+export function managedPluginIds(panels: readonly EditorHostPanel[]): string[] {
+  return Array.from(
+    new Set(panels.filter((panel) => panel.pluginId).map((panel) => panel.pluginId as string)),
+  )
+}
+
+/**
+ * Does the plugin *manager* tab belong in the rail?
+ *
+ * It is a management surface — it installs and uninstalls plugins into the
+ * scene — so it earns a slot when there is something to manage, or when the
+ * scene is writable and the "create a plugin" path is still worth offering to
+ * whoever owns it.
+ *
+ * That leaves exactly one case out, and it is a real screen rather than a
+ * hypothetical: the open lobby (`/play/<id>`) mounts the editor under a
+ * read-only lease and registers NO host panels, so the manager was the only
+ * tab in the rail. The rail therefore opened by default onto a "Plugins"
+ * heading with nothing under it, covering roughly 40% of a visitor's window
+ * over the world they had come to play in (owner report 2026-08-31). With no
+ * tabs at all the v2 layout drops the whole left column, which is the lobby as
+ * intended: the canvas, and nothing else.
+ *
+ * A read-only *editor* keeps the tab as long as plugins are registered — a
+ * viewer can still read what a project uses; only the install button is
+ * disabled. So this hides an empty panel, never a populated one.
+ */
+export function showsPluginManager({
+  managedPluginCount,
+  readOnly,
+  workspaceMode,
+}: {
+  managedPluginCount: number
+  readOnly: boolean
+  workspaceMode: string
+}): boolean {
+  if (workspaceMode !== 'edit') return false
+  return managedPluginCount > 0 || !readOnly
+}