@cat-factory/app 0.280.0 → 0.280.2

package/app/composables/useBoardActivity.ts

@@ -1,4 +1,5 @@
 import { inject, onBeforeUnmount, onMounted, provide, type InjectionKey, type Ref } from 'vue'
+import { createWakeGate } from '~/utils/boardWakeGate'
 
 /**
  * The board's shared "something may have moved" pulse.
@@ -16,9 +17,13 @@ import { inject, onBeforeUnmount, onMounted, provide, type InjectionKey, type Re
  *  - a `MutationObserver` over the canvas subtree, watching structure plus `style` / `class`.
  *    That is every Vue-driven render change on the board, Vue Flow's own pan/zoom transform
  *    included. Attribute changes the drivers themselves write (`x1`/`y1` on the edge overlay)
- *    are outside the filter, so a driver cannot pulse itself awake forever.
+ *    are outside the filter, so a driver cannot pulse itself awake forever. These wakes are
+ *    RATE-LIMITED (see `boardWakeGate`): a live board re-renders its cards on every execution
+ *    event, and admitting each one kept the measuring loops from ever parking on exactly the
+ *    board where measuring costs the most. The gesture and camera signals below are admitted
+ *    unthrottled, so nothing the user is actually moving waits on an interval.
  *  - a `ResizeObserver` on the canvas, plus window `resize`: layout changes with no mutation.
- *  - pointer, wheel and scroll gestures on the canvas: the user moving something.
+ *  - pointer, wheel and scroll gestures, listened for on the WINDOW: the user moving something.
  *
  * What it does NOT catch is a reflow with no mutation and no gesture, such as a late-loading
  * image or font resizing a card. Those settle on the next pulse of any kind.
@@ -28,6 +33,14 @@ export type BoardActivity = {
   subscribe: (onPulse: () => void) => () => void
   /** Fire the pulse from a signal the observers above cannot see. */
   pulse: () => void
+  /**
+   * Where the pointer last was over the canvas (viewport coordinates), or null once it left.
+   *
+   * Owned here because the pulse already listens for the same gestures: a driver that wants the
+   * position registered a SECOND `pointermove` listener on the same element to learn what this
+   * one had just seen. Read inside a measurement pass, never subscribed to.
+   */
+  pointer: () => { x: number; y: number } | null
 }
 
 const boardActivityKey: InjectionKey<BoardActivity> = Symbol('boardActivity')
@@ -42,19 +55,62 @@ export function provideBoardActivity(container: Ref<HTMLElement | null>): BoardA
     for (const onPulse of subscribers) onPulse()
   }
 
+  // Renders reach the pulse through the gate; everything the user is moving goes straight to it.
+  const renderWakes = createWakeGate({
+    wake: pulse,
+    // `window.setTimeout` rather than the bare global: the DOM overload returns the numeric
+    // handle the gate's scheduler is typed on, where Node's returns a `Timeout` object.
+    scheduler: {
+      schedule: (run, delayMs) => window.setTimeout(run, delayMs),
+      cancel: (handle) => window.clearTimeout(handle),
+    },
+  })
+
+  let pointer: { x: number; y: number } | null = null
+
+  /**
+   * Track the pointer and pulse, in that order, off the SAME listener.
+   *
+   * `pointerleave` does not bubble, but a CAPTURE-phase listener sees one fired at any element
+   * below it, and the pointer moving from a card onto the canvas around it is exactly that
+   * event. So only the canvas's OWN leave clears the position; treating a descendant's as "the
+   * pointer is gone" would collapse the hovered card the moment the pointer crossed one of its
+   * inner elements. That check is on the TARGET, so it reads the same from the window as it did
+   * from the canvas.
+   */
+  const onGesture = (event: Event) => {
+    if (event.type === 'pointerleave') {
+      if (event.target === container.value) pointer = null
+    } else if (event.type === 'pointermove' || event.type === 'pointerdown') {
+      const { clientX, clientY } = event as PointerEvent
+      pointer = { x: clientX, y: clientY }
+    }
+    pulse()
+  }
+
   const activity: BoardActivity = {
     subscribe(onPulse) {
       subscribers.add(onPulse)
       return () => subscribers.delete(onPulse)
     },
     pulse,
+    pointer: () => pointer,
   }
   provide(boardActivityKey, activity)
 
-  const mutations = new MutationObserver(pulse)
+  const mutations = new MutationObserver(renderWakes.request)
   const resizes = new ResizeObserver(pulse)
   // `scroll` does not bubble, so it is caught in the capture phase; the gestures are
   // passive listeners because the pulse never wants to cancel one.
+  //
+  // They are bound to the WINDOW rather than to the canvas, because a drag does not end at the
+  // canvas's edge: `useBlockDrag` tracks the pointer on the window precisely so a card keeps
+  // following it, and the toolbar region and the inspector are SIBLINGS painted over the canvas,
+  // not descendants of it. Bound to the canvas, a drag whose cursor crossed one of them stopped
+  // delivering the gesture that keeps the measuring loops awake, and the arrows fell back to the
+  // rate-limited mutation wake for as long as the cursor was over it: a visible lag in the one
+  // interaction this pulse exists to keep smooth. Capture on the window sees every one of those
+  // events wherever it is dispatched, so nothing else about the handler changes.
   const gestures = [
     'pointerdown',
     'pointermove',
@@ -77,15 +133,15 @@ export function provideBoardActivity(container: Ref<HTMLElement | null>): BoardA
       attributeFilter: ['style', 'class'],
     })
     resizes.observe(el)
-    for (const type of gestures) el.addEventListener(type, pulse, gestureOptions)
+    for (const type of gestures) window.addEventListener(type, onGesture, gestureOptions)
     window.addEventListener('resize', pulse)
   })
 
   onBeforeUnmount(() => {
     mutations.disconnect()
     resizes.disconnect()
-    const el = container.value
-    for (const type of gestures) el?.removeEventListener(type, pulse, gestureOptions)
+    renderWakes.cancel()
+    for (const type of gestures) window.removeEventListener(type, onGesture, gestureOptions)
     window.removeEventListener('resize', pulse)
     subscribers.clear()
   })

package/app/composables/useConfirm.spec.ts

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { useConfirm } from '~/composables/useConfirm'
+
+// The confirm singleton's state lives at module scope so every caller and the one mounted
+// `<ConfirmDialog />` share ONE request queue. That is also why each test starts by cancelling
+// whatever the previous one left pending.
+describe('useConfirm', () => {
+  beforeEach(() => {
+    useConfirm().cancel()
+  })
+
+  it('opens on request and resolves the choice the user made', async () => {
+    const { open, current, confirm, accept } = useConfirm()
+
+    const pending = confirm({ title: 'Delete it?' })
+    expect(open.value).toBe(true)
+    expect(current.value?.title).toBe('Delete it?')
+
+    accept()
+    await expect(pending).resolves.toBe(true)
+    expect(open.value).toBe(false)
+  })
+
+  // The dismissal path (backdrop, Escape, unmount): the dialog is CONTROLLED, so settling the
+  // promise without writing `open` left it on screen with no resolver behind it — a dialog whose
+  // buttons resolve nothing, on what is now the primary dismissal path of eleven result windows.
+  it('closes the dialog as well as settling the promise when it is dismissed', async () => {
+    const { open, confirm, dismissed } = useConfirm()
+
+    const pending = confirm({ title: 'Discard your changes?' })
+    dismissed()
+
+    await expect(pending).resolves.toBe(false)
+    expect(open.value).toBe(false)
+  })
+
+  // A second dismissal with nothing pending must stay a no-op rather than closing a request that
+  // arrived in between.
+  it('leaves a fresh request alone when a stale dismissal arrives', async () => {
+    const { open, confirm, dismissed, accept } = useConfirm()
+
+    dismissed()
+    const pending = confirm({ title: 'Remove the pipeline?' })
+    expect(open.value).toBe(true)
+
+    accept()
+    await expect(pending).resolves.toBe(true)
+  })
+
+  // Load-bearing for every surface that can raise two confirms: the superseded awaiter resolves
+  // `false`, so its caller treats the choice as declined rather than hanging forever.
+  it('settles a superseded request false instead of leaving it pending', async () => {
+    const { confirm, accept } = useConfirm()
+
+    const first = confirm({ title: 'Delete A?' })
+    const second = confirm({ title: 'Delete B?' })
+
+    await expect(first).resolves.toBe(false)
+    accept()
+    await expect(second).resolves.toBe(true)
+  })
+})

package/app/composables/useConfirm.ts

@@ -55,8 +55,13 @@ export function useConfirm() {
 
   // Called by the dialog when `open` flips to false without an explicit accept/cancel
   // (backdrop, Escape, unmount). Any still-pending promise resolves `false`.
+  //
+  // It also has to write `open` itself, exactly as `cancel` does: the dialog is CONTROLLED (its
+  // `v-model:open` reads this ref), so a dismissal that only settled the promise left a visible
+  // modal behind with no pending resolver, whose buttons then resolve nothing.
   function dismissed(): void {
-    if (resolver) settle(false)
+    open.value = false
+    settle(false)
   }
 
   return { open, current: readonly(current), confirm, accept, cancel, dismissed }

package/app/composables/useInterviewDrafts.spec.ts

@@ -0,0 +1,198 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { nextTick, ref } from 'vue'
+import { useInterviewDrafts } from '~/composables/useInterviewDrafts'
+
+interface Q {
+  id?: string
+  key: string
+  answer?: string
+  status?: 'open' | 'dismissed'
+}
+
+const TITLES = { one: 'interview.saveFailed', many: 'interview.saveFailedCount' }
+
+let present: ReturnType<typeof vi.fn>
+
+beforeEach(() => {
+  present = vi.fn()
+  vi.stubGlobal('usePipelineErrorToast', () => ({ present }))
+})
+
+function harness(questions: Q[], write: (id: string, answer: string) => Promise<unknown>) {
+  const list = ref<Q[]>(questions)
+  const blockId = ref<string | null>('blk_1')
+  const seam = useInterviewDrafts<Q>({
+    blockId: () => blockId.value,
+    questions: () => list.value,
+    pending: () => list.value.filter((q) => !(q.answer ?? '').trim()),
+    write: (_block, questionId, answer) => write(questionId, answer),
+    writable: (q) => q.status !== 'dismissed',
+    failureTitleKeys: TITLES,
+  })
+  return { ...seam, list, blockId }
+}
+
+describe('useInterviewDrafts', () => {
+  it('seeds each draft from the entity and leaves an edit alone across rounds', async () => {
+    const { drafts, list } = harness([{ id: 'q1', key: 'q1', answer: 'recorded' }], async () => {})
+    expect(drafts.q1).toBe('recorded')
+
+    drafts.q1 = 'the human is mid-edit'
+    list.value = [
+      { id: 'q1', key: 'q1', answer: 'recorded' },
+      { id: 'q2', key: 'q2' },
+    ]
+    await nextTick()
+
+    expect(drafts.q1).toBe('the human is mid-edit')
+    expect(drafts.q2).toBe('')
+  })
+
+  it('writes only the drafts that changed, and never a question set aside', async () => {
+    const written: string[] = []
+    const { drafts, flushDrafts } = harness(
+      [
+        { id: 'q1', key: 'q1', answer: 'already this' },
+        { id: 'q2', key: 'q2' },
+        { id: 'q3', key: 'q3', status: 'dismissed' },
+      ],
+      async (id) => {
+        written.push(id)
+      },
+    )
+
+    drafts.q1 = 'already this'
+    drafts.q2 = 'a new answer'
+    drafts.q3 = 'a stale draft on a not-relevant question'
+    flushDrafts()
+    await vi.waitFor(() => expect(written).toEqual(['q2']))
+    expect(present).not.toHaveBeenCalled()
+  })
+
+  // The defect: a sequential loop that awaited straight through abandoned every answer after the
+  // first rejection, with the window already torn down and nothing left on screen to say so.
+  it('keeps flushing after a failed write, then reports how many were lost', async () => {
+    const attempted: string[] = []
+    const { drafts, flushDrafts } = harness(
+      [
+        { id: 'q1', key: 'q1' },
+        { id: 'q2', key: 'q2' },
+        { id: 'q3', key: 'q3' },
+      ],
+      async (id) => {
+        attempted.push(id)
+        if (id !== 'q2') throw new Error(`boom ${id}`)
+      },
+    )
+
+    drafts.q1 = 'one'
+    drafts.q2 = 'two'
+    drafts.q3 = 'three'
+    flushDrafts()
+
+    await vi.waitFor(() => expect(present).toHaveBeenCalled())
+    expect(attempted).toEqual(['q1', 'q2', 'q3'])
+    // The plural title, carrying the count, plus the FIRST cause so the toast's detail names a real
+    // failure rather than a synthesised summary.
+    expect(present).toHaveBeenCalledWith(expect.any(Error), TITLES.many, { count: 2 })
+    expect((present.mock.calls[0]![0] as Error).message).toBe('boom q1')
+  })
+
+  it('reports a single lost answer with the singular title', async () => {
+    const { drafts, flushDrafts } = harness([{ id: 'q1', key: 'q1' }], async () => {
+      throw new Error('nope')
+    })
+    drafts.q1 = 'one'
+    flushDrafts()
+
+    await vi.waitFor(() => expect(present).toHaveBeenCalled())
+    expect(present).toHaveBeenCalledWith(expect.any(Error), TITLES.one, { count: 1 })
+  })
+
+  it('reports a failed single save from the blur path', async () => {
+    const { drafts, saveAnswer } = harness([{ id: 'q1', key: 'q1' }], async () => {
+      throw new Error('nope')
+    })
+    drafts.q1 = 'one'
+    saveAnswer({ id: 'q1', key: 'q1' })
+
+    await vi.waitFor(() =>
+      expect(present).toHaveBeenCalledWith(expect.any(Error), TITLES.one, {
+        count: 1,
+      }),
+    )
+  })
+
+  // A missing answer may not be submitted as if it were there, and the window has to stay put so the
+  // same button is still on screen with the text still in its box.
+  it('withholds the action when a draft could not be written', async () => {
+    const action = vi.fn().mockResolvedValue(undefined)
+    const { drafts, flushThen } = harness([{ id: 'q1', key: 'q1' }], async () => {
+      throw new Error('nope')
+    })
+    drafts.q1 = 'one'
+
+    await flushThen(action, 'interview.continueFailed')
+
+    expect(action).not.toHaveBeenCalled()
+    expect(present).toHaveBeenCalledWith(expect.any(Error), TITLES.one, { count: 1 })
+  })
+
+  it('runs the action once every draft is written, and reports the action itself failing', async () => {
+    const written: string[] = []
+    const { drafts, flushThen } = harness([{ id: 'q1', key: 'q1' }], async (id) => {
+      written.push(id)
+    })
+    drafts.q1 = 'one'
+
+    const ok = vi.fn().mockResolvedValue(undefined)
+    await flushThen(ok, 'interview.continueFailed')
+    expect(written).toEqual(['q1'])
+    expect(ok).toHaveBeenCalledWith('blk_1')
+    expect(present).not.toHaveBeenCalled()
+
+    // The backing stores rethrow and Vue discards a click handler's promise, so the action's own
+    // failure is reported here or nowhere.
+    await flushThen(
+      vi.fn().mockRejectedValue(new Error('resume failed')),
+      'interview.continueFailed',
+    )
+    expect(present).toHaveBeenCalledWith(expect.any(Error), 'interview.continueFailed')
+  })
+
+  it('writes nothing once the view has torn down and the block id is gone', async () => {
+    const written: string[] = []
+    const { drafts, flushDrafts, flushThen, blockId } = harness(
+      [{ id: 'q1', key: 'q1' }],
+      async (id) => {
+        written.push(id)
+      },
+    )
+    drafts.q1 = 'one'
+    blockId.value = null
+
+    flushDrafts()
+    const action = vi.fn()
+    await flushThen(action, 'interview.continueFailed')
+    await nextTick()
+
+    expect(written).toEqual([])
+    expect(action).not.toHaveBeenCalled()
+  })
+
+  // An exchange with no id cannot be addressed by the answer write at all. It must not hold the
+  // submit button hostage, since nothing the human types would ever clear it.
+  it('excludes an unaddressable question from the unanswered count', () => {
+    const { drafts, addressable, unanswered } = harness(
+      [{ id: 'q1', key: 'q1' }, { key: 'q-1' }],
+      async () => {},
+    )
+
+    expect(addressable({ id: 'q1', key: 'q1' })).toBe(true)
+    expect(addressable({ key: 'q-1' })).toBe(false)
+    expect(unanswered.value).toBe(1)
+
+    drafts.q1 = 'answered'
+    expect(unanswered.value).toBe(0)
+  })
+})

package/app/composables/useInterviewDrafts.ts

@@ -0,0 +1,184 @@
+import { computed, reactive, watch } from 'vue'
+
+/**
+ * Per-question answer drafts for an INTERVIEW gate window (the initiative planner's interviewer and
+ * the doc-authoring interviewer), plus the two ways they leave the browser: one answer on blur, and
+ * every dirty answer on the way out.
+ *
+ * Both windows hold the same shape of draft for the same reason, and recording one is a PLAIN SAVE:
+ * it writes the reply without resolving the interview, which is what the window's own two commands
+ * do. That is what makes the FLUSH disposition correct here rather than a discard prompt (see
+ * `ResultWindowDrafts.logic.spec.ts` for the rule and the per-window table).
+ *
+ * It is ONE seam because the two windows held byte-identical copies of this logic and only ever got
+ * fixed one at a time: the doc interview grew a close-time flush while the planner kept dropping
+ * answers on close, and neither reported a failed write. Three properties are easy to lose when this
+ * is hand-rolled per window, and each one was:
+ *
+ *  - The flush CAPTURES what it needs synchronously. `blockId` and everything derived from it go
+ *    null the instant the view tears down, so an awaited loop that re-reads them writes nowhere.
+ *  - Each answer settles INDEPENDENTLY. A loop that awaited straight through dropped every answer
+ *    after the first rejection, with the window already gone.
+ *  - Every path REPORTS its own failure. Both backing stores rethrow and Vue discards a handler's
+ *    returned promise, so an unreported write is an unhandled rejection and, to the user, a no-op.
+ */
+
+/** The minimum an exchange has to carry for a draft answer to be held against it. */
+export interface InterviewDraftQuestion {
+  /**
+   * The id the answer write addresses. Optional because the wire shape leaves it optional (a
+   * hand-authored or fixture exchange parses without one); see {@link useInterviewDrafts}'s
+   * `addressable`.
+   */
+  id?: string
+  /** Stable key for the list and the draft map: the question id, or its index as a fallback. */
+  key: string
+  /** What is already recorded. Seeds the draft, and decides whether the draft is dirty. */
+  answer?: string
+}
+
+export function useInterviewDrafts<Q extends InterviewDraftQuestion>(opts: {
+  /** The block the answers are written against, or null while no view is open. */
+  blockId: () => string | null
+  /** Every exchange the session holds, settled rounds included. */
+  questions: () => Q[]
+  /** The subset still owing an answer, which is what the submit button waits on. */
+  pending: () => Q[]
+  /** Record ONE answer against the block. */
+  write: (blockId: string, questionId: string, answer: string) => Promise<unknown>
+  /**
+   * Whether this question's draft may be written at all. A question set aside as not-relevant had
+   * its recorded answer cleared, so writing a stale local draft back would silently re-answer it.
+   */
+  writable?: (question: Q) => boolean
+  /** Toast titles for a failed write: one answer lost, and several (which takes a `{ count }`). */
+  failureTitleKeys: { one: string; many: string }
+}) {
+  const { present } = usePipelineErrorToast()
+
+  const drafts = reactive<Record<string, string>>({})
+  // Seeded from the entity and refreshed as new rounds arrive, without clobbering an answer the
+  // human is mid-edit on.
+  watch(
+    opts.questions,
+    (list) => {
+      for (const question of list) {
+        if (!(question.key in drafts)) drafts[question.key] = question.answer ?? ''
+      }
+    },
+    { immediate: true },
+  )
+
+  /**
+   * Whether an answer to this exchange can be RECORDED at all: the write addresses a question BY
+   * ID, so one without an id has nowhere for an answer to go.
+   *
+   * Callers disable that question's input and say why. Accepting text into it instead would take an
+   * answer the flush could only drop, which is the silent loss this seam exists to end.
+   */
+  function addressable(question: Q): boolean {
+    return typeof question.id === 'string' && question.id.length > 0
+  }
+
+  /**
+   * Questions still missing a drafted answer, which is what a submit button gates on (and renders,
+   * because a disabled button with no stated reason is itself a "nothing happened").
+   *
+   * Unaddressable questions are excluded: nothing the human can type clears one, so counting it
+   * would disable the submit for good.
+   */
+  const unanswered = computed(
+    () => opts.pending().filter((q) => addressable(q) && !drafts[q.key]?.trim()).length,
+  )
+
+  /**
+   * Persist one answer when its draft differs from what is recorded. The block id is threaded in
+   * rather than read off `opts.blockId()`, so a flush that started as the window closed still writes
+   * to the right board.
+   */
+  async function persist(blockId: string, question: Q): Promise<void> {
+    const id = question.id
+    if (!id || opts.writable?.(question) === false) return
+    const next = (drafts[question.key] ?? '').trim()
+    if (!next || next === (question.answer ?? '').trim()) return
+    await opts.write(blockId, id, next)
+  }
+
+  /** Report a failed write, naming how many answers did not make it. */
+  function report(failed: number, cause: unknown): void {
+    present(cause, failed === 1 ? opts.failureTitleKeys.one : opts.failureTitleKeys.many, {
+      count: failed,
+    })
+  }
+
+  /**
+   * Persist every dirty draft, each on its OWN: one rejection may not cost the answers after it.
+   * Returns how many could not be written plus the first cause, which is what the caller reports.
+   *
+   * Sequential rather than concurrent because each write is a read-modify-write of the session's one
+   * question-and-answer array, so two in flight would race to overwrite each other's answer.
+   */
+  async function flushAll(blockId: string, list: Q[]): Promise<{ failed: number; cause: unknown }> {
+    let failed = 0
+    let cause: unknown
+    for (const question of list) {
+      try {
+        await persist(blockId, question)
+      } catch (error) {
+        failed += 1
+        if (failed === 1) cause = error
+      }
+    }
+    return { failed, cause }
+  }
+
+  /**
+   * Save this ONE answer against the block that is open right now: the blur handler, and the same
+   * call an adopted recommendation makes. Detached, because Vue discards a handler's returned
+   * promise, so the failure is reported here or nowhere.
+   */
+  function saveAnswer(question: Q): void {
+    const blockId = opts.blockId()
+    if (!blockId) return
+    void persist(blockId, question).catch((error) => report(1, error))
+  }
+
+  /**
+   * Persist every dirty draft on the way out, detached so it can be called from the synchronous
+   * close hook. A close-time flush is the one path with no button left on screen to have reported a
+   * failure, so it reports the loss itself.
+   */
+  function flushDrafts(): void {
+    const blockId = opts.blockId()
+    if (!blockId) return
+    const list = [...opts.questions()]
+    void (async () => {
+      const { failed, cause } = await flushAll(blockId, list)
+      if (failed > 0) report(failed, cause)
+    })()
+  }
+
+  /**
+   * Flush every dirty draft, then run a window action, but ONLY if every draft was written: an
+   * answer that failed to save may not be submitted as if it were there. On a failure the report is
+   * the whole outcome, and the window is left as it is, with the same button on screen and the text
+   * still in its box.
+   */
+  async function flushThen(
+    action: (blockId: string) => Promise<unknown>,
+    failureTitleKey: string,
+  ): Promise<void> {
+    const blockId = opts.blockId()
+    if (!blockId) return
+    const { failed, cause } = await flushAll(blockId, [...opts.questions()])
+    if (failed > 0) {
+      report(failed, cause)
+      return
+    }
+    // The action rejects too (both backing stores rethrow) and it is reached from a click handler
+    // whose promise Vue discards, so its failure is reported here or nowhere.
+    await action(blockId).catch((error) => present(error, failureTitleKey))
+  }
+
+  return { drafts, addressable, unanswered, saveAnswer, flushDrafts, flushThen }
+}

package/app/composables/useTaskExpansion.ts

@@ -3,6 +3,7 @@ import { onMounted, onBeforeUnmount } from 'vue'
 import { lodAtLeast } from '~/composables/useSemanticZoom'
 import { onBoardActivity, type BoardActivity } from '~/composables/useBoardActivity'
 import { useSettlingRaf } from '~/composables/useSettlingRaf'
+import { measureBlocks, type BlockMeasurements } from '~/utils/blockRects'
 import { headerDistanceSq, type Rect } from '~/utils/taskExpansionRanking'
 
 function intersects(a: Rect, b: Rect) {
@@ -54,21 +55,6 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
   // card is still tested at its expanded extent and stays denied. Stable.
   const expandedHeight = new Map<string, number>()
 
-  // Last pointer position over the board (viewport coords), or null when the pointer has
-  // left it. The card under the pointer is expanded on hover (see `hoveredTaskId`).
-  let pointer: { x: number; y: number } | null = null
-  function onPointerMove(e: PointerEvent) {
-    pointer = { x: e.clientX, y: e.clientY }
-  }
-  function onPointerLeave() {
-    pointer = null
-  }
-
-  function rectOf(id: string): DOMRect | null {
-    const el = document.querySelector(`[data-block-id="${id}"]`) as HTMLElement | null
-    return el ? el.getBoundingClientRect() : null
-  }
-
   // The task whose card is topmost at the pointer, or null. Using elementFromPoint (not a
   // rect test) means an open pipeline stacked above a neighbour wins the hit, so hovering
   // a region obscured by another pipeline doesn't switch to the card hidden beneath it.
@@ -77,6 +63,9 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
   // a frame, a module, or a task with no run expands to nothing, and granting it would
   // still lift an empty card over its neighbours (see LaneTask's z-index).
   function hoveredTaskId(): string | null {
+    // Where the pointer is comes from the pulse, which already listens for the same gestures on
+    // the same element (see `BoardActivity.pointer`).
+    const pointer = activity.pointer()
     if (!pointer) return null
     const hit = document.elementFromPoint(pointer.x, pointer.y)
     const id = hit?.closest('[data-block-id]')?.getAttribute('data-block-id') ?? null
@@ -107,6 +96,8 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
     }
     const view = container.value?.getBoundingClientRect()
     if (!view) return changed
+    // One DOM query for the whole sweep instead of one per candidate task (see `measureBlocks`).
+    const blocks: BlockMeasurements = measureBlocks()
     const cx = view.left + view.width / 2
     const cy = view.top + view.height / 2
 
@@ -115,8 +106,9 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
     for (const t of board.allTasks) {
       // Only tasks whose run actually has steps would expand a pipeline list.
       if (!execution.getByBlock(t.id)?.steps.length) continue
-      const rect = rectOf(t.id)
-      if (!rect) continue
+      const el = blocks.elementFor(t.id)
+      if (!el) continue
+      const rect = blocks.rectFor(el)
       liveIds.add(t.id)
       // While a card is granted it's rendered expanded, so its live height is its
       // expanded footprint — cache it. A denied card keeps its last cached value.
@@ -166,19 +158,12 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
   }
 
   const { poke } = useSettlingRaf(recompute)
-  // The pointer listeners below only record where the pointer IS; the pulse (which watches the
-  // same gestures) is what schedules the frame that acts on it.
+  // The pulse both records where the pointer is and schedules the frame that acts on it.
   onBoardActivity(activity, poke)
   onMounted(() => {
     store.setDriverActive(true)
-    const el = container.value
-    el?.addEventListener('pointermove', onPointerMove)
-    el?.addEventListener('pointerleave', onPointerLeave)
   })
   onBeforeUnmount(() => {
-    const el = container.value
-    el?.removeEventListener('pointermove', onPointerMove)
-    el?.removeEventListener('pointerleave', onPointerLeave)
     store.setDriverActive(false)
   })
 }

package/app/docs/consumer-extensions.md

@@ -102,6 +102,15 @@ An unpaired id degrades to the generic prose panel (a dev-console warning names
 id); a structured kind with no bespoke window gets the built-in `generic-structured` viewer
 for free.
 
+**Contribute the component asynchronously.** Every first-party window is registered as
+`defineAsyncView(() => import('...'))`, so its code is fetched on the click that opens it rather
+than on every board load; an async component is an ordinary `Component`, so the slot entry and the
+host's mount are identical either way. A window is a modal opened deliberately, so copy that shape
+unless yours is small enough not to matter. Prefer the seam over a bare `defineAsyncComponent`: it
+attaches the shared failure notice, so a chunk that 404s (which is what a deploy landing under an
+open tab makes of every chunk the session had not yet fetched) states itself instead of opening
+your window onto a blank screen.
+
 ### Navigation
 
 A consumer nav item carries its own `run` closure (first-party items use a typed `action`