@nelsonlongxiang/dsh-open-a2a-net 0.6.40 → 0.6.42

package/nexus-stage/src/planning-roster.ts

@@ -1,15 +1,15 @@
-/** Roster frames use an independent layout namespace beside canvas frames. */
-import type { PlanningTeam } from './planning-types'
-
-export const ROSTER_PREFIX = 'roster:'
-export const rosterNameOf = (frame: string): string | undefined => frame.startsWith(ROSTER_PREFIX) ? frame.slice(ROSTER_PREFIX.length) : undefined
-export const rosterFrameName = (name: string): string => ROSTER_PREFIX + name
-export const rosterFrameTitle = (frame: string): string => { const name = rosterNameOf(frame); return name === undefined ? frame : `网络队 · roster · ${name}` }
-export function rosterFrames(rows: readonly { team: string; members: readonly string[] }[], zone: string): PlanningTeam[] {
-  return rows.flatMap(row => {
-    if (zone === '' || !row.team.startsWith(zone + '/') || !Array.isArray(row.members)) return []
-    const name = row.team.slice(zone.length + 1)
-    if (name === '' || name.length > 40 || name.includes('/') || name.startsWith(ROSTER_PREFIX) || name.includes('*')) return []
-    return [{ name: rosterFrameName(name), team: row.team, kind: 'roster' as const, members: row.members.filter(id => typeof id === 'string' && id !== '').map(id => ({ id })) }]
-  })
-}
+/** Roster frames use an independent layout namespace beside canvas frames. */
+import type { PlanningTeam } from './planning-types'
+
+export const ROSTER_PREFIX = 'roster:'
+export const rosterNameOf = (frame: string): string | undefined => frame.startsWith(ROSTER_PREFIX) ? frame.slice(ROSTER_PREFIX.length) : undefined
+export const rosterFrameName = (name: string): string => ROSTER_PREFIX + name
+export const rosterFrameTitle = (frame: string): string => { const name = rosterNameOf(frame); return name === undefined ? frame : `网络队 · roster · ${name}` }
+export function rosterFrames(rows: readonly { team: string; members: readonly string[] }[], zone: string): PlanningTeam[] {
+  return rows.flatMap(row => {
+    if (zone === '' || !row.team.startsWith(zone + '/') || !Array.isArray(row.members)) return []
+    const name = row.team.slice(zone.length + 1)
+    if (name === '' || name.length > 40 || name.includes('/') || name.startsWith(ROSTER_PREFIX) || name.includes('*')) return []
+    return [{ name: rosterFrameName(name), team: row.team, kind: 'roster' as const, members: row.members.filter(id => typeof id === 'string' && id !== '').map(id => ({ id })) }]
+  })
+}

package/nexus-stage/src/planning-search.ts

@@ -1,168 +1,168 @@
-/**
- * 画板全局搜索（属主令 W1）: a toolbar search box (Ctrl+K focuses) over the
- * board's node FACTS — display name, zone/id8 handle, and host spelling, in
- * one substring match (case-insensitive). Picking a hit rides the existing
- * fitView flight chain (the caller frames ~100% and pulses the card);
- * Escape clears. Pure front end: no backend, no routing, no persistence.
- * @module nexus-stage/planning-search
- */
-import { fitView, type LayoutViewport } from './viewport'
-import { NODE_W, NODE_H } from './world'
-/** One searchable node fact row (already display-resolved by the caller). */
-export interface SearchHit {
-  readonly id: string
-  /** Display name (member cards' person name, peer hosts' spelling). */
-  readonly name: string
-  /** The zone/id8 handle (n.team) and any extra host tokens. */
-  readonly team: string
-  /** Optional host/owner token (peer cards carry the host spelling). */
-  readonly host?: string
-}
-
-/** Case-insensitive substring match across name / team / host. */
-export function matchHits(rows: ReadonlyArray<SearchHit>, query: string): SearchHit[] {
-  const q = query.trim().toLowerCase()
-  if (q === '') return []
-  return rows.filter(r =>
-    r.name.toLowerCase().includes(q) || r.team.toLowerCase().includes(q) || (r.host ?? '').toLowerCase().includes(q))
-    .slice(0, 8)
-}
-
-/**
- * Build the searchable rows from the board model — the SAME display facts
- * the cards render (member display name / peer host spelling / its handle),
- * so every hit is a card the user can see.
- */
-export function hitsFromModel(model: { allNodes(): ReadonlyArray<{ id: string; name?: string; team: string; remote?: boolean }> }, displayName: (n: never) => string): SearchHit[] {
-  return model.allNodes().map(n => {
-    const host = n.id.slice('peer-'.length)
-    const name = n.id.startsWith('member-')
-      ? (n.name !== undefined && n.name !== '' ? n.name : n.team)
-      : n.remote === true ? host : displayName(n as never)
-    return { id: n.id, name, team: n.team, ...(n.remote === true ? { host } : {}) }
-  })
-}
-
-/** W1 pulse: briefly ring the picked card (class removed on the timer). */
-export function pulseCard(el: HTMLElement | undefined, ms = 1200): void {
-  if (el === undefined) return
-  el.classList.add('pulse')
-  setTimeout(() => el.classList.remove('pulse'), ms)
-}
-
-/** The view seams the node flyer needs (the view keeps owning its model). */
-export interface NodeFlyerSpec {
-  readonly model: { getNode(id: string): { x: number; y: number } | undefined }
-  readonly viewSize: () => { w: number; h: number }
-  readonly setVp: (vp: LayoutViewport) => void
-  readonly applyViewport: () => void
-  readonly markDirty: () => void
-  readonly cardEl: (id: string) => HTMLElement | undefined
-}
-
-/**
- * W1 pick flight: frame ONE node's rect at ~100% (the same fitView chain the
- * statusbar fly rides) and pulse its card for 1.2s.
- */
-export function createNodeFlyer(spec: NodeFlyerSpec): (id: string) => void {
-  return id => {
-    const n = spec.model.getNode(id)
-    if (n === undefined) return
-    const size = spec.viewSize()
-    // fitView takes WorldBounds ({minX,minY,maxX,maxY}), not the card rect —
-    // passing {x,y,w,h} silently yielded NaN → IDENTITY (flight never landed).
-    spec.setVp(fitView({ minX: n.x, minY: n.y, maxX: n.x + NODE_W, maxY: n.y + NODE_H }, size.w, size.h, 1))
-    spec.applyViewport()
-    spec.markDirty()
-    pulseCard(spec.cardEl(id))
-  }
-}
-
-export interface SearchMount extends PlanningSearch {
-  /** Rebuild the index from the model (call from the node reconcile). */
-  refresh(): void
-}
-
-/**
- * Mount the whole search surface into the toolbar — the wiring lines the
- * view used to carry live here (create + append + index builder), keeping
- * the view under the M1 ratchet; the view keeps ONE call.
- */
-export function mountBoardSearch(
-  toolbar: HTMLElement,
-  model: Parameters<typeof hitsFromModel>[0],
-  displayName: Parameters<typeof hitsFromModel>[1],
-  onPick: (id: string) => void,
-): SearchMount {
-  const search = createPlanningSearch({ onPick })
-  toolbar.appendChild(search.root)
-  return { ...search, refresh: () => search.setIndex(hitsFromModel(model, displayName)) }
-}
-
-export interface PlanningSearch {
-  readonly root: HTMLElement
-  /** Refresh the searchable index (called from the node reconcile). */
-  setIndex(rows: ReadonlyArray<SearchHit>): void
-  /** Focus the box (Ctrl+K) and select the current text. */
-  focus(): void
-  /** Clear the query and the dropdown (Escape elsewhere). */
-  clear(): void
-}
-
-/** Build the search box widget (input + hit list + keyboard handling). */
-export function createPlanningSearch(opts: { onPick: (id: string) => void }): PlanningSearch {
-  const root = document.createElement('div')
-  root.className = 'p-search'
-  const input = document.createElement('input')
-  input.type = 'search'
-  input.className = 'p-search-input'
-  // Short enough to read whole in the 170px box (review 2026-10-27); the
-  // full scope rides the tooltip and the accessible name.
-  input.placeholder = '🔍 搜索（Ctrl+K）'
-  input.title = '搜索名字 / 句柄 / 宿主（Ctrl+K 聚焦，Esc 清空）'
-  input.setAttribute('aria-label', '搜索画板节点：名字、句柄或宿主')
-  const list = document.createElement('div')
-  list.className = 'p-search-list'
-  let rows: ReadonlyArray<SearchHit> = []
-  let hits: SearchHit[] = []
-  let active = 0
-  const close = (): void => { list.style.display = 'none'; list.textContent = '' }
-  const paint = (): void => {
-    list.textContent = ''
-    if (hits.length === 0) { close(); return }
-    hits.forEach((h, i) => {
-      const row = document.createElement('div')
-      row.className = 'p-search-hit' + (i === active ? ' active' : '')
-      row.dataset.id = h.id
-      row.textContent = h.name === h.team ? h.name : `${h.name} · ${h.team}`
-      row.addEventListener('mousedown', ev => { ev.preventDefault(); opts.onPick(h.id); clearBox() })
-      list.appendChild(row)
-    })
-    list.style.display = 'block'
-  }
-  const clearBox = (): void => { input.value = ''; hits = []; close() }
-  const refresh = (): void => { hits = matchHits(rows, input.value); active = 0; paint() }
-  input.addEventListener('input', refresh)
-  input.addEventListener('keydown', ev => {
-    if (ev.key === 'Escape') { clearBox(); input.blur(); ev.stopPropagation(); return }
-    if (ev.key === 'ArrowDown' || ev.key === 'ArrowUp') {
-      if (hits.length === 0) return
-      ev.preventDefault()
-      active = (active + (ev.key === 'ArrowDown' ? 1 : hits.length - 1)) % hits.length
-      paint()
-      return
-    }
-    if (ev.key === 'Enter' && hits.length > 0) {
-      ev.preventDefault()
-      opts.onPick(hits[active]!.id)
-      clearBox()
-    }
-  })
-  root.append(input, list)
-  return {
-    root,
-    setIndex(next) { rows = next; if (input.value !== '') refresh() },
-    focus() { input.focus(); input.select() },
-    clear() { clearBox() },
-  }
-}
+/**
+ * 画板全局搜索（属主令 W1）: a toolbar search box (Ctrl+K focuses) over the
+ * board's node FACTS — display name, zone/id8 handle, and host spelling, in
+ * one substring match (case-insensitive). Picking a hit rides the existing
+ * fitView flight chain (the caller frames ~100% and pulses the card);
+ * Escape clears. Pure front end: no backend, no routing, no persistence.
+ * @module nexus-stage/planning-search
+ */
+import { fitView, type LayoutViewport } from './viewport'
+import { NODE_W, NODE_H } from './world'
+/** One searchable node fact row (already display-resolved by the caller). */
+export interface SearchHit {
+  readonly id: string
+  /** Display name (member cards' person name, peer hosts' spelling). */
+  readonly name: string
+  /** The zone/id8 handle (n.team) and any extra host tokens. */
+  readonly team: string
+  /** Optional host/owner token (peer cards carry the host spelling). */
+  readonly host?: string
+}
+
+/** Case-insensitive substring match across name / team / host. */
+export function matchHits(rows: ReadonlyArray<SearchHit>, query: string): SearchHit[] {
+  const q = query.trim().toLowerCase()
+  if (q === '') return []
+  return rows.filter(r =>
+    r.name.toLowerCase().includes(q) || r.team.toLowerCase().includes(q) || (r.host ?? '').toLowerCase().includes(q))
+    .slice(0, 8)
+}
+
+/**
+ * Build the searchable rows from the board model — the SAME display facts
+ * the cards render (member display name / peer host spelling / its handle),
+ * so every hit is a card the user can see.
+ */
+export function hitsFromModel(model: { allNodes(): ReadonlyArray<{ id: string; name?: string; team: string; remote?: boolean }> }, displayName: (n: never) => string): SearchHit[] {
+  return model.allNodes().map(n => {
+    const host = n.id.slice('peer-'.length)
+    const name = n.id.startsWith('member-')
+      ? (n.name !== undefined && n.name !== '' ? n.name : n.team)
+      : n.remote === true ? host : displayName(n as never)
+    return { id: n.id, name, team: n.team, ...(n.remote === true ? { host } : {}) }
+  })
+}
+
+/** W1 pulse: briefly ring the picked card (class removed on the timer). */
+export function pulseCard(el: HTMLElement | undefined, ms = 1200): void {
+  if (el === undefined) return
+  el.classList.add('pulse')
+  setTimeout(() => el.classList.remove('pulse'), ms)
+}
+
+/** The view seams the node flyer needs (the view keeps owning its model). */
+export interface NodeFlyerSpec {
+  readonly model: { getNode(id: string): { x: number; y: number } | undefined }
+  readonly viewSize: () => { w: number; h: number }
+  readonly setVp: (vp: LayoutViewport) => void
+  readonly applyViewport: () => void
+  readonly markDirty: () => void
+  readonly cardEl: (id: string) => HTMLElement | undefined
+}
+
+/**
+ * W1 pick flight: frame ONE node's rect at ~100% (the same fitView chain the
+ * statusbar fly rides) and pulse its card for 1.2s.
+ */
+export function createNodeFlyer(spec: NodeFlyerSpec): (id: string) => void {
+  return id => {
+    const n = spec.model.getNode(id)
+    if (n === undefined) return
+    const size = spec.viewSize()
+    // fitView takes WorldBounds ({minX,minY,maxX,maxY}), not the card rect —
+    // passing {x,y,w,h} silently yielded NaN → IDENTITY (flight never landed).
+    spec.setVp(fitView({ minX: n.x, minY: n.y, maxX: n.x + NODE_W, maxY: n.y + NODE_H }, size.w, size.h, 1))
+    spec.applyViewport()
+    spec.markDirty()
+    pulseCard(spec.cardEl(id))
+  }
+}
+
+export interface SearchMount extends PlanningSearch {
+  /** Rebuild the index from the model (call from the node reconcile). */
+  refresh(): void
+}
+
+/**
+ * Mount the whole search surface into the toolbar — the wiring lines the
+ * view used to carry live here (create + append + index builder), keeping
+ * the view under the M1 ratchet; the view keeps ONE call.
+ */
+export function mountBoardSearch(
+  toolbar: HTMLElement,
+  model: Parameters<typeof hitsFromModel>[0],
+  displayName: Parameters<typeof hitsFromModel>[1],
+  onPick: (id: string) => void,
+): SearchMount {
+  const search = createPlanningSearch({ onPick })
+  toolbar.appendChild(search.root)
+  return { ...search, refresh: () => search.setIndex(hitsFromModel(model, displayName)) }
+}
+
+export interface PlanningSearch {
+  readonly root: HTMLElement
+  /** Refresh the searchable index (called from the node reconcile). */
+  setIndex(rows: ReadonlyArray<SearchHit>): void
+  /** Focus the box (Ctrl+K) and select the current text. */
+  focus(): void
+  /** Clear the query and the dropdown (Escape elsewhere). */
+  clear(): void
+}
+
+/** Build the search box widget (input + hit list + keyboard handling). */
+export function createPlanningSearch(opts: { onPick: (id: string) => void }): PlanningSearch {
+  const root = document.createElement('div')
+  root.className = 'p-search'
+  const input = document.createElement('input')
+  input.type = 'search'
+  input.className = 'p-search-input'
+  // Short enough to read whole in the 170px box (review 2026-10-27); the
+  // full scope rides the tooltip and the accessible name.
+  input.placeholder = '🔍 搜索（Ctrl+K）'
+  input.title = '搜索名字 / 句柄 / 宿主（Ctrl+K 聚焦，Esc 清空）'
+  input.setAttribute('aria-label', '搜索画板节点：名字、句柄或宿主')
+  const list = document.createElement('div')
+  list.className = 'p-search-list'
+  let rows: ReadonlyArray<SearchHit> = []
+  let hits: SearchHit[] = []
+  let active = 0
+  const close = (): void => { list.style.display = 'none'; list.textContent = '' }
+  const paint = (): void => {
+    list.textContent = ''
+    if (hits.length === 0) { close(); return }
+    hits.forEach((h, i) => {
+      const row = document.createElement('div')
+      row.className = 'p-search-hit' + (i === active ? ' active' : '')
+      row.dataset.id = h.id
+      row.textContent = h.name === h.team ? h.name : `${h.name} · ${h.team}`
+      row.addEventListener('mousedown', ev => { ev.preventDefault(); opts.onPick(h.id); clearBox() })
+      list.appendChild(row)
+    })
+    list.style.display = 'block'
+  }
+  const clearBox = (): void => { input.value = ''; hits = []; close() }
+  const refresh = (): void => { hits = matchHits(rows, input.value); active = 0; paint() }
+  input.addEventListener('input', refresh)
+  input.addEventListener('keydown', ev => {
+    if (ev.key === 'Escape') { clearBox(); input.blur(); ev.stopPropagation(); return }
+    if (ev.key === 'ArrowDown' || ev.key === 'ArrowUp') {
+      if (hits.length === 0) return
+      ev.preventDefault()
+      active = (active + (ev.key === 'ArrowDown' ? 1 : hits.length - 1)) % hits.length
+      paint()
+      return
+    }
+    if (ev.key === 'Enter' && hits.length > 0) {
+      ev.preventDefault()
+      opts.onPick(hits[active]!.id)
+      clearBox()
+    }
+  })
+  root.append(input, list)
+  return {
+    root,
+    setIndex(next) { rows = next; if (input.value !== '') refresh() },
+    focus() { input.focus(); input.select() },
+    clear() { clearBox() },
+  }
+}

package/nexus-stage/src/planning-types.ts

@@ -1,115 +1,115 @@
-/**
- * Public shapes of the planning board: its input, dependencies, the
- * handler seam tests drive, and the view surface. planning-view re-exports
- * all of them, so importers keep using `./planning-view`.
- * @module nexus-stage/planning-types
- */
-import type { CanvasAction } from './canvas-ops'
-import type { InFlightRow, PeerRow, RemoteTeamRow } from './federation'
-import type { LampState } from './layout-wire'
-import type { LayoutViewport } from './viewport'
-import type { SessionLite, TeamLite } from './world'
-
-/** Minimal session/team shapes consumed here (topology rows satisfy them). */
-export interface PlanningSession extends SessionLite {}
-export interface PlanningTeam extends TeamLite { kind?: 'roster' }
-
-export interface PlanningInput {
-  sessions: ReadonlyArray<PlanningSession>
-  teams: ReadonlyArray<PlanningTeam>
-  peerCount: number
-  /** Federation peers (PR D): rows for the badge column right of the content. */
-  peers?: ReadonlyArray<PeerRow>
-  /** Pending outbound routes (PR D): the accent activity edges. */
-  inFlight?: ReadonlyArray<InFlightRow>
-  /** Remote team directory rows (PR D v1 ruling): grouped under peer cards. */
-  remoteTeams?: ReadonlyArray<RemoteTeamRow>
-  /** gh#41 fleet planning: each tracked peer's published canvas org —
-   *  rendered as REMOTE team frames (read + cross-host regulation). */
-  peerOrg?: ReadonlyArray<{ url: string; unreachable?: boolean; org: ReadonlyArray<{ name: string; team: string; members: readonly string[] }> }>
-}
-
-/** Screen-width class a viewport is remembered under (window width, not board width — collapsing the rail must not switch buckets). */
-export type ViewportBucket = 'narrow' | 'medium' | 'wide'
-
-export function viewportBucket(width: number): ViewportBucket {
-  return width < 680 ? 'narrow' : width < 1024 ? 'medium' : 'wide'
-}
-
-export interface PlanningDeps {
-  /** An edit that should persist happened (drag/nudge/pan/zoom/marquee end). */
-  onDirty(): void
-  /** The save lamp was clicked (error state -> retry). */
-  onLampClick(): void
-  /** Viewport size in CSS px (defaults to the root element's box; tests
-   *  inject fixed sizes so fit math is assertable without layout). */
-  viewSize?(): { w: number; h: number }
-  /**
-   * Per-device viewport memory. The saved layout's viewport is the LAST
-   * saver's screen, so a desktop pan landed on a phone (and any other
-   * device's save yanked this one's view). When present, the first adopted
-   * layout takes this screen bucket's own viewport — else, on a wide screen,
-   * the host's (where it was most likely saved), else a fit — later
-   * adoptions leave the viewport alone, and every persisted edit writes the
-   * bucket back. Optional: without it the host viewport wins as before.
-   */
-  viewportStore?: { get(bucket: ViewportBucket): unknown; set(bucket: ViewportBucket, vp: LayoutViewport): void }
-  /**
-   * A team write action (optimistic state already applied by the view).
-   * Resolves true when the host accepted it — or it was an idempotent
-   * no-op (ok:false without an error string). Resolves false when the
-   * write was refused/failed: the view then rolls the action's scoped
-   * undo back itself. Rejecting the promise is also handled (treated as
-   * false) — the channel must not leave the team's guard pinned.
-   */
-  onCanvasAction(a: CanvasAction): Promise<boolean>
-  /** A plain (non-shift, no-drag) left click selected exactly one node
-   * (0.6.13): the host may open the reading face (chat drawer) for it.
-   * Selection itself is already applied — this is a notification, not a
-   * command; the host decides what (if anything) to show. */
-  onNodePick?(id: string): void
-  /** Wall clock for the inFlight age labels (tests pin it; default Date.now). */
-  now?(): number
-}
-
-/** Pointer-like event surface the handlers consume (real events satisfy it). */
-export interface SeamPointer {
-  button: number
-  shiftKey: boolean
-  ctrlKey: boolean
-  clientX: number
-  clientY: number
-  pointerId?: number
-  target: Element | null
-  deltaX?: number
-  deltaY?: number
-  deltaMode?: number
-  preventDefault(): void
-}
-
-export interface SeamKey { key: string; shiftKey: boolean; altKey?: boolean; ctrlKey?: boolean; metaKey?: boolean; target: Element | null; preventDefault(): void }
-
-export interface PlanningView {
-  root: HTMLElement
-  reconcile(input: PlanningInput): void
-  activate(): void
-  deactivate(): void
-  /** Adopt a (possibly normalized) layout document when the save loop allows. */
-  adoptExternalLayout(layout: unknown): void
-  /** The current document for the save loop, read at send time. */
-  snapshotDoc(): unknown
-  setLamp(state: LampState, savedAt?: string): void
-  /** A transient notice (host error verbatim or an info hint). */
-  notice(kind: 'error' | 'info', text: string): void
-  seam: {
-    pointerDown(ev: SeamPointer): void
-    pointerMove(ev: SeamPointer): void
-    pointerUp(ev: SeamPointer): void
-    pointerCancel(ev: SeamPointer): void
-    wheel(ev: SeamPointer): void
-    key(ev: SeamKey): void
-    keyUp(ev: SeamKey): void
-    contextMenu(ev: SeamPointer): void
-  }
-  destroy(): void
-}
+/**
+ * Public shapes of the planning board: its input, dependencies, the
+ * handler seam tests drive, and the view surface. planning-view re-exports
+ * all of them, so importers keep using `./planning-view`.
+ * @module nexus-stage/planning-types
+ */
+import type { CanvasAction } from './canvas-ops'
+import type { InFlightRow, PeerRow, RemoteTeamRow } from './federation'
+import type { LampState } from './layout-wire'
+import type { LayoutViewport } from './viewport'
+import type { SessionLite, TeamLite } from './world'
+
+/** Minimal session/team shapes consumed here (topology rows satisfy them). */
+export interface PlanningSession extends SessionLite {}
+export interface PlanningTeam extends TeamLite { kind?: 'roster' }
+
+export interface PlanningInput {
+  sessions: ReadonlyArray<PlanningSession>
+  teams: ReadonlyArray<PlanningTeam>
+  peerCount: number
+  /** Federation peers (PR D): rows for the badge column right of the content. */
+  peers?: ReadonlyArray<PeerRow>
+  /** Pending outbound routes (PR D): the accent activity edges. */
+  inFlight?: ReadonlyArray<InFlightRow>
+  /** Remote team directory rows (PR D v1 ruling): grouped under peer cards. */
+  remoteTeams?: ReadonlyArray<RemoteTeamRow>
+  /** gh#41 fleet planning: each tracked peer's published canvas org —
+   *  rendered as REMOTE team frames (read + cross-host regulation). */
+  peerOrg?: ReadonlyArray<{ url: string; unreachable?: boolean; org: ReadonlyArray<{ name: string; team: string; members: readonly string[] }> }>
+}
+
+/** Screen-width class a viewport is remembered under (window width, not board width — collapsing the rail must not switch buckets). */
+export type ViewportBucket = 'narrow' | 'medium' | 'wide'
+
+export function viewportBucket(width: number): ViewportBucket {
+  return width < 680 ? 'narrow' : width < 1024 ? 'medium' : 'wide'
+}
+
+export interface PlanningDeps {
+  /** An edit that should persist happened (drag/nudge/pan/zoom/marquee end). */
+  onDirty(): void
+  /** The save lamp was clicked (error state -> retry). */
+  onLampClick(): void
+  /** Viewport size in CSS px (defaults to the root element's box; tests
+   *  inject fixed sizes so fit math is assertable without layout). */
+  viewSize?(): { w: number; h: number }
+  /**
+   * Per-device viewport memory. The saved layout's viewport is the LAST
+   * saver's screen, so a desktop pan landed on a phone (and any other
+   * device's save yanked this one's view). When present, the first adopted
+   * layout takes this screen bucket's own viewport — else, on a wide screen,
+   * the host's (where it was most likely saved), else a fit — later
+   * adoptions leave the viewport alone, and every persisted edit writes the
+   * bucket back. Optional: without it the host viewport wins as before.
+   */
+  viewportStore?: { get(bucket: ViewportBucket): unknown; set(bucket: ViewportBucket, vp: LayoutViewport): void }
+  /**
+   * A team write action (optimistic state already applied by the view).
+   * Resolves true when the host accepted it — or it was an idempotent
+   * no-op (ok:false without an error string). Resolves false when the
+   * write was refused/failed: the view then rolls the action's scoped
+   * undo back itself. Rejecting the promise is also handled (treated as
+   * false) — the channel must not leave the team's guard pinned.
+   */
+  onCanvasAction(a: CanvasAction): Promise<boolean>
+  /** A plain (non-shift, no-drag) left click selected exactly one node
+   * (0.6.13): the host may open the reading face (chat drawer) for it.
+   * Selection itself is already applied — this is a notification, not a
+   * command; the host decides what (if anything) to show. */
+  onNodePick?(id: string): void
+  /** Wall clock for the inFlight age labels (tests pin it; default Date.now). */
+  now?(): number
+}
+
+/** Pointer-like event surface the handlers consume (real events satisfy it). */
+export interface SeamPointer {
+  button: number
+  shiftKey: boolean
+  ctrlKey: boolean
+  clientX: number
+  clientY: number
+  pointerId?: number
+  target: Element | null
+  deltaX?: number
+  deltaY?: number
+  deltaMode?: number
+  preventDefault(): void
+}
+
+export interface SeamKey { key: string; shiftKey: boolean; altKey?: boolean; ctrlKey?: boolean; metaKey?: boolean; target: Element | null; preventDefault(): void }
+
+export interface PlanningView {
+  root: HTMLElement
+  reconcile(input: PlanningInput): void
+  activate(): void
+  deactivate(): void
+  /** Adopt a (possibly normalized) layout document when the save loop allows. */
+  adoptExternalLayout(layout: unknown): void
+  /** The current document for the save loop, read at send time. */
+  snapshotDoc(): unknown
+  setLamp(state: LampState, savedAt?: string): void
+  /** A transient notice (host error verbatim or an info hint). */
+  notice(kind: 'error' | 'info', text: string): void
+  seam: {
+    pointerDown(ev: SeamPointer): void
+    pointerMove(ev: SeamPointer): void
+    pointerUp(ev: SeamPointer): void
+    pointerCancel(ev: SeamPointer): void
+    wheel(ev: SeamPointer): void
+    key(ev: SeamKey): void
+    keyUp(ev: SeamKey): void
+    contextMenu(ev: SeamPointer): void
+  }
+  destroy(): void
+}