Add e2e test suite (puppeteer + vitest) for edit-mode UX

16 tests covering: selection overlay, click-to-deselect, select-other-node,
dbl-click add, single-click no-op, Backspace/Delete deletion, rotation
handle drag, undo/redo via window API and via cmd+z/cmd+shift+z keyboard
shortcuts, node-drag undo, and a history-length regression guard
(rotation drag = 1 past entry, not N-per-mousemove).

- `pnpm test` runs headless; `pnpm test:headful` shows the browser.
- Tests read state via `window.__geoSankey` (graph, past/future lengths,
  undo/redo callbacks), and derive node screen positions via
  `map.project` + canvas `getBoundingClientRect` offset.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ryan-williams

package.json

@@ -15,7 +15,10 @@
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly",
     "clean": "rm -rf node_modules/.vite dist",
-    "dev": "cd site && vite"
+    "dev": "cd site && vite",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:headful": "HEADFUL=1 vitest run"
   },
   "devDependencies": {
     "@types/geojson": "^7946.0.16",

test/e2e/edit-mode.spec.ts

@@ -0,0 +1,219 @@
+import { describe, it, beforeAll, afterAll, beforeEach, afterEach, expect } from 'vitest'
+import type { Browser, Page } from 'puppeteer-core'
+import {
+  launch,
+  openEditMode,
+  getNodeCount,
+  getNode,
+  getHistoryLengths,
+  projectNode,
+  getSelectedBearing,
+  getRotHandlePos,
+  getSelectedLabel,
+  isSelected,
+  mapClick,
+  mapDblClick,
+  undoViaApi,
+  redoViaApi,
+} from './helpers'
+
+let browser: Browser
+let page: Page
+
+beforeAll(async () => { browser = await launch() }, 30_000)
+afterAll(async () => { await browser?.close() })
+
+beforeEach(async () => {
+  page = await openEditMode(browser, { nodeId: 'origin' })
+}, 30_000)
+afterEach(async () => { await page?.close() })
+
+describe('selection', () => {
+  it('shows overlay label for selected node', async () => {
+    const label = await getSelectedLabel(page)
+    expect(label).toBe('Origin')
+  })
+
+  it('shows rotation handle with bearing label', async () => {
+    const pos = await getRotHandlePos(page)
+    expect(pos).not.toBeNull()
+    const bearing = await getSelectedBearing(page)
+    expect(bearing).toBe('90°')
+  })
+
+  it('deselects on empty-map click', async () => {
+    expect(await isSelected(page, 'origin')).toBe(true)
+    // Click an area on the map with no node
+    await mapClick(page, 600, 400)
+    expect(await isSelected(page, 'origin')).toBe(false)
+    // Overlay should be gone
+    expect(await getSelectedLabel(page)).toBeNull()
+  })
+
+  it('selects a different node on click', async () => {
+    const destPos = await projectNode(page, 'dest')
+    expect(destPos).not.toBeNull()
+    await mapClick(page, destPos!.x, destPos!.y)
+    expect(await isSelected(page, 'dest')).toBe(true)
+  })
+})
+
+describe('add node', () => {
+  it('double-click adds a node', async () => {
+    const before = await getNodeCount(page)
+    await mapDblClick(page, 500, 500)
+    const after = await getNodeCount(page)
+    expect(after).toBe(before + 1)
+  })
+
+  it('single-click on empty map does NOT add a node', async () => {
+    const before = await getNodeCount(page)
+    await mapClick(page, 500, 500)
+    const after = await getNodeCount(page)
+    expect(after).toBe(before)
+  })
+})
+
+describe('delete node', () => {
+  it('Backspace deletes the selected node', async () => {
+    const before = await getNodeCount(page)
+    await page.keyboard.press('Backspace')
+    await new Promise(r => setTimeout(r, 300))
+    const after = await getNodeCount(page)
+    expect(after).toBe(before - 1)
+    expect(await isSelected(page, 'origin')).toBe(false)
+  })
+
+  it('Delete key also deletes the selected node', async () => {
+    const before = await getNodeCount(page)
+    await page.keyboard.press('Delete')
+    await new Promise(r => setTimeout(r, 300))
+    const after = await getNodeCount(page)
+    expect(after).toBe(before - 1)
+  })
+})
+
+describe('rotation handle', () => {
+  it('drag updates bearing', async () => {
+    const before = await getSelectedBearing(page)
+    expect(before).toBe('90°')
+    const handle = await getRotHandlePos(page)
+    expect(handle).not.toBeNull()
+    // Drag handle to below the node (south) — origin's screen position is roughly (X_handle - 40, Y_handle)
+    // Drag direction: move from handle toward a south-of-node position
+    // origin node is at the handle position minus the bearing-radius offset (40px east at 90°)
+    const nodeCx = handle!.x - 40
+    const nodeCy = handle!.y
+    await page.mouse.move(handle!.x, handle!.y)
+    await page.mouse.down()
+    await page.mouse.move(nodeCx, nodeCy + 50, { steps: 10 })
+    await page.mouse.up()
+    await new Promise(r => setTimeout(r, 300))
+    const after = await getSelectedBearing(page)
+    expect(after).not.toBe('90°')
+    // A drag to the south should yield a bearing in [120°, 210°] range
+    const deg = parseInt(after!.replace('°', ''))
+    expect(deg).toBeGreaterThan(120)
+    expect(deg).toBeLessThan(210)
+  })
+})
+
+describe('undo / redo', () => {
+  it('undo reverts a double-click add', async () => {
+    const before = await getNodeCount(page)
+    await mapDblClick(page, 500, 500)
+    expect(await getNodeCount(page)).toBe(before + 1)
+    await undoViaApi(page)
+    expect(await getNodeCount(page)).toBe(before)
+  })
+
+  it('redo re-adds after undo', async () => {
+    const before = await getNodeCount(page)
+    await mapDblClick(page, 500, 500)
+    expect(await getNodeCount(page)).toBe(before + 1)
+    await undoViaApi(page)
+    expect(await getNodeCount(page)).toBe(before)
+    await redoViaApi(page)
+    expect(await getNodeCount(page)).toBe(before + 1)
+  })
+
+  it('undo reverts a rotation drag (single history entry, not per-mousemove)', async () => {
+    expect(await getSelectedBearing(page)).toBe('90°')
+    const handle = (await getRotHandlePos(page))!
+    const nodeCx = handle.x - 40
+    const nodeCy = handle.y
+    await page.mouse.move(handle.x, handle.y)
+    await page.mouse.down()
+    for (let i = 1; i <= 20; i++) {
+      await page.mouse.move(nodeCx + 10, nodeCy + 3 * i, { steps: 1 })
+    }
+    await page.mouse.up()
+    await new Promise(r => setTimeout(r, 300))
+    expect(await getSelectedBearing(page)).not.toBe('90°')
+    await undoViaApi(page)
+    expect(await getSelectedBearing(page)).toBe('90°')
+  })
+
+  it('undo reverts a node drag to pre-drag position', async () => {
+    const originBefore = await getNode(page, 'origin')
+    const originScreen = (await projectNode(page, 'origin'))!
+    // Drag origin 100px to the right via the map canvas (edit-mode node drag)
+    await page.mouse.move(originScreen.x, originScreen.y)
+    await page.mouse.down()
+    for (let i = 1; i <= 10; i++) {
+      await page.mouse.move(originScreen.x + 10 * i, originScreen.y, { steps: 1 })
+    }
+    await page.mouse.up()
+    await new Promise(r => setTimeout(r, 300))
+    const moved = await getNode(page, 'origin')
+    expect(moved.pos[1]).not.toBeCloseTo(originBefore.pos[1], 4)
+    await undoViaApi(page)
+    const restored = await getNode(page, 'origin')
+    expect(restored.pos[0]).toBeCloseTo(originBefore.pos[0], 4)
+    expect(restored.pos[1]).toBeCloseTo(originBefore.pos[1], 4)
+  })
+
+  async function pressMod(keys: string) {
+    // On macOS, Cmd (Meta) is the mod key. Try Meta first; some headless
+    // environments need Control.
+    const mods = process.platform === 'darwin' ? ['Meta'] : ['Control']
+    for (const k of keys.split('+').slice(0, -1)) mods.push(k === 'Shift' ? 'Shift' : k)
+    const target = keys.split('+').slice(-1)[0]
+    for (const m of mods) await page.keyboard.down(m)
+    await page.keyboard.press(target)
+    for (const m of mods.slice().reverse()) await page.keyboard.up(m)
+  }
+
+  it('Cmd+Z undo works via keyboard shortcut', async () => {
+    const before = await getNodeCount(page)
+    await mapDblClick(page, 500, 500)
+    expect(await getNodeCount(page)).toBe(before + 1)
+    await pressMod('z')
+    await new Promise(r => setTimeout(r, 300))
+    expect(await getNodeCount(page)).toBe(before)
+  })
+
+  it('Cmd+Shift+Z redo works via keyboard shortcut', async () => {
+    const before = await getNodeCount(page)
+    await mapDblClick(page, 500, 500)
+    await undoViaApi(page)
+    expect(await getNodeCount(page)).toBe(before)
+    await pressMod('Shift+z')
+    await new Promise(r => setTimeout(r, 300))
+    expect(await getNodeCount(page)).toBe(before + 1)
+  })
+
+  it('rotation drag produces exactly ONE history entry (not per-mousemove)', async () => {
+    const histBefore = await getHistoryLengths(page)
+    const handle = (await getRotHandlePos(page))!
+    await page.mouse.move(handle.x, handle.y)
+    await page.mouse.down()
+    for (let i = 1; i <= 20; i++) {
+      await page.mouse.move(handle.x + 2 * i, handle.y + 5 * i, { steps: 1 })
+    }
+    await page.mouse.up()
+    await new Promise(r => setTimeout(r, 300))
+    const histAfter = await getHistoryLengths(page)
+    expect(histAfter.past).toBe(histBefore.past + 1)
+  })
+})

test/e2e/helpers.ts

@@ -0,0 +1,138 @@
+import puppeteer, { Browser, Page } from 'puppeteer-core'
+
+const CHROME_PATH = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+export const BASE_URL = process.env.GS_BASE_URL ?? 'http://localhost:7251'
+
+export async function launch(): Promise<Browser> {
+  return puppeteer.launch({
+    headless: process.env.HEADFUL ? false : true,
+    executablePath: CHROME_PATH,
+    args: ['--no-sandbox', '--disable-dev-shm-usage'],
+  })
+}
+
+/** Load the Simple Flow example in edit mode with the Origin node selected. */
+export async function openEditMode(browser: Browser, opts: { nodeId?: string } = {}): Promise<Page> {
+  const page = await browser.newPage()
+  await page.setViewport({ width: 1200, height: 800 })
+  await page.evaluateOnNewDocument((sel) => {
+    sessionStorage.setItem('geo-sankey-edit', '1')
+    if (sel) sessionStorage.setItem('geo-sankey-sel', JSON.stringify({ type: 'node', id: sel }))
+  }, opts.nodeId ?? '')
+  await page.goto(`${BASE_URL}/?ex=ferry&nodes=2&llz=40.7350_-74.0300_13.50`)
+  await waitForMap(page)
+  return page
+}
+
+export async function waitForMap(page: Page, timeout = 10_000): Promise<void> {
+  await page.waitForFunction(() => {
+    const gs = (window as any).__geoSankey
+    return gs && gs.mapRef?.current?.getMap?.()
+  }, { timeout })
+  await new Promise(r => setTimeout(r, 500))
+}
+
+export async function getNodeCount(page: Page): Promise<number> {
+  return page.evaluate(() => (window as any).__geoSankey?.graph?.nodes?.length ?? -1)
+}
+
+export async function getNode(page: Page, id: string): Promise<any> {
+  return page.evaluate((nodeId) => {
+    const g = (window as any).__geoSankey?.graph
+    return g?.nodes?.find((n: any) => n.id === nodeId) ?? null
+  }, id)
+}
+
+export async function getHistoryLengths(page: Page): Promise<{ past: number; future: number }> {
+  return page.evaluate(() => {
+    const gs = (window as any).__geoSankey
+    return { past: gs?.pastLen ?? 0, future: gs?.futureLen ?? 0 }
+  })
+}
+
+export async function undoViaApi(page: Page): Promise<void> {
+  await page.evaluate(() => (window as any).__geoSankey?.undo?.())
+  await new Promise(r => setTimeout(r, 150))
+}
+
+export async function redoViaApi(page: Page): Promise<void> {
+  await page.evaluate(() => (window as any).__geoSankey?.redo?.())
+  await new Promise(r => setTimeout(r, 150))
+}
+
+/** Project a node's LL to VIEWPORT pixel coords (accounting for canvas offset). */
+export async function projectNode(page: Page, id: string): Promise<{ x: number; y: number } | null> {
+  return page.evaluate((nodeId) => {
+    const gs = (window as any).__geoSankey
+    const map = gs?.mapRef?.current?.getMap?.()
+    const node = gs?.graph?.nodes?.find((n: any) => n.id === nodeId)
+    if (!map || !node) return null
+    const pt = map.project([node.pos[1], node.pos[0]]) // [lng, lat] → canvas px
+    const canvas = map.getCanvas() as HTMLCanvasElement
+    const rect = canvas.getBoundingClientRect()
+    return { x: pt.x + rect.left, y: pt.y + rect.top }
+  }, id)
+}
+
+export async function getSelectedBearing(page: Page): Promise<string | null> {
+  return page.evaluate(() => {
+    const els = document.querySelectorAll('.map-container div[style]')
+    for (const el of els) {
+      const txt = (el as HTMLElement).textContent ?? ''
+      // The "NN°" label next to the rotation handle
+      if (/^\d+°$/.test(txt)) return txt
+    }
+    return null
+  })
+}
+
+export async function getRotHandlePos(page: Page): Promise<{ x: number; y: number } | null> {
+  return page.evaluate(() => {
+    const divs = document.querySelectorAll('.map-container div[style]')
+    for (const d of divs) {
+      const style = (d as HTMLElement).style
+      if (style.cursor === 'grab' && style.borderRadius === '50%') {
+        const r = (d as HTMLElement).getBoundingClientRect()
+        return { x: r.x + r.width / 2, y: r.y + r.height / 2 }
+      }
+    }
+    return null
+  })
+}
+
+export async function getSelectedLabel(page: Page): Promise<string | null> {
+  return page.evaluate(() => {
+    // Find the node-label overlay div (non-expanded form shows label text)
+    const divs = document.querySelectorAll('.map-container div[style]')
+    for (const d of divs) {
+      const s = (d as HTMLElement).style
+      if (s.position === 'absolute' && s.cursor === 'default') {
+        const span = d.querySelector('span')
+        return span?.textContent ?? null
+      }
+    }
+    return null
+  })
+}
+
+export async function isSelected(page: Page, nodeId: string): Promise<boolean> {
+  return page.evaluate((id) => {
+    const stored = sessionStorage.getItem('geo-sankey-sel')
+    if (!stored) return false
+    try {
+      const s = JSON.parse(stored)
+      return s?.type === 'node' && s?.id === id
+    } catch { return false }
+  }, nodeId)
+}
+
+/** Map-canvas click (single-click = select/deselect in edit mode). */
+export async function mapClick(page: Page, x: number, y: number): Promise<void> {
+  await page.mouse.click(x, y)
+  await new Promise(r => setTimeout(r, 200))
+}
+
+export async function mapDblClick(page: Page, x: number, y: number): Promise<void> {
+  await page.mouse.click(x, y, { clickCount: 2 })
+  await new Promise(r => setTimeout(r, 200))
+}

vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['test/e2e/**/*.spec.ts'],
+    testTimeout: 30_000,
+    hookTimeout: 30_000,
+    // Run serially so a single browser instance is shared per worker
+    fileParallelism: false,
+  },
+})