@cat-factory/app 0.280.0 → 0.280.1

package/app/utils/blockRects.spec.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { measureBlocks } from './blockRects'
+
+function card(id: string): HTMLElement {
+  const el = document.createElement('div')
+  el.setAttribute('data-block-id', id)
+  return el
+}
+
+beforeEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('measureBlocks', () => {
+  it('resolves each rendered card by its block id', () => {
+    const a = card('a')
+    const b = card('b')
+    document.body.append(a, b)
+
+    const blocks = measureBlocks(document)
+    expect(blocks.elementFor('a')).toBe(a)
+    expect(blocks.elementFor('b')).toBe(b)
+    expect(blocks.elementFor('missing')).toBeNull()
+  })
+
+  it('resolves the first card in document order, as a bare querySelector did', () => {
+    const onBoard = card('a')
+    const inOverlay = card('a')
+    document.body.append(onBoard, inOverlay)
+
+    expect(measureBlocks(document).elementFor('a')).toBe(onBoard)
+  })
+
+  it('measures an element once per pass however many links read it', () => {
+    const a = card('a')
+    document.body.append(a)
+    const measure = vi.spyOn(a, 'getBoundingClientRect')
+
+    const blocks = measureBlocks(document)
+    const first = blocks.rectFor(a)
+    expect(blocks.rectFor(a)).toBe(first)
+    expect(measure).toHaveBeenCalledTimes(1)
+  })
+
+  it('is a snapshot: a later pass measures again', () => {
+    const a = card('a')
+    document.body.append(a)
+    const measure = vi.spyOn(a, 'getBoundingClientRect')
+
+    measureBlocks(document).rectFor(a)
+    measureBlocks(document).rectFor(a)
+    expect(measure).toHaveBeenCalledTimes(2)
+  })
+
+  it('queries nothing until something is actually looked up', () => {
+    // The edge overlay builds a pass every awake frame of a pan and, on a board with no links
+    // of any kind, asks it for no card at all. Deferring is what keeps that pass free.
+    const root = document.createElement('div')
+    root.append(card('a'))
+    document.body.append(root)
+    const query = vi.spyOn(root, 'querySelectorAll')
+
+    const blocks = measureBlocks(root)
+    expect(query).not.toHaveBeenCalled()
+
+    blocks.elementFor('a')
+    blocks.elementFor('a')
+    expect(query).toHaveBeenCalledTimes(1)
+  })
+
+  it('scopes the pass to the root it was given', () => {
+    const outside = card('a')
+    const root = document.createElement('div')
+    const inside = card('b')
+    root.append(inside)
+    document.body.append(outside, root)
+
+    const blocks = measureBlocks(root)
+    expect(blocks.elementFor('b')).toBe(inside)
+    expect(blocks.elementFor('a')).toBeNull()
+  })
+})

package/app/utils/blockRects.ts

@@ -0,0 +1,61 @@
+/**
+ * One measurement pass's view of the board's rendered block cards.
+ *
+ * The two DOM-measuring drivers on the canvas (dependency edges, task expansion) resolve cards
+ * by `[data-block-id]`, which is what lets an arrow follow pan / zoom / drag for free. Done a
+ * card at a time it is also the drivers' whole cost: the edge overlay ran two
+ * `document.querySelector` scans plus two `getBoundingClientRect` reads PER LINK, so a task with
+ * five dependencies was found and measured five times in the same frame, and the expansion sweep
+ * ran one scan per candidate task.
+ *
+ * A pass builds this once instead: one `querySelectorAll` over the board, then map lookups, with
+ * each element measured at most once. First-in-document-order wins per id, matching what
+ * `document.querySelector` returned before, so a card also rendered outside the canvas (the focus
+ * view, the inspector) resolves to the same element it always did.
+ *
+ * The query itself is DEFERRED to the first lookup, so a pass that turns out to have nothing to
+ * resolve costs nothing. That is the common case rather than a corner: a board with no
+ * dependency, epic, frontend or connection link runs the edge overlay's pass on every awake
+ * frame of a pan and asks it for not one card, and the sweep it replaced did no DOM work there
+ * at all. Deferring keeps that property in the helper, where both drivers inherit it, rather
+ * than as a `links.length` guard at each call site that a fifth overlay would silently miss.
+ *
+ * It is still a SNAPSHOT: geometry read inside one frame must not change halfway through a pass,
+ * the query runs at most once whenever it runs, and the next pass builds a fresh one.
+ */
+export type BlockMeasurements = {
+  /** The rendered card for a block id, or null when nothing on the page renders it. */
+  elementFor: (id: string) => HTMLElement | null
+  /** The element's viewport rect, measured once per pass. */
+  rectFor: (el: Element) => DOMRect
+}
+
+export const BLOCK_ID_ATTRIBUTE = 'data-block-id'
+
+export function measureBlocks(root: ParentNode = document): BlockMeasurements {
+  let elements: Map<string, HTMLElement> | null = null
+
+  function index(): Map<string, HTMLElement> {
+    if (elements) return elements
+    const found = new Map<string, HTMLElement>()
+    for (const el of root.querySelectorAll<HTMLElement>(`[${BLOCK_ID_ATTRIBUTE}]`)) {
+      const id = el.getAttribute(BLOCK_ID_ATTRIBUTE)
+      if (id && !found.has(id)) found.set(id, el)
+    }
+    elements = found
+    return found
+  }
+
+  const rects = new WeakMap<Element, DOMRect>()
+
+  return {
+    elementFor: (id) => index().get(id) ?? null,
+    rectFor(el) {
+      const cached = rects.get(el)
+      if (cached) return cached
+      const rect = el.getBoundingClientRect()
+      rects.set(el, rect)
+      return rect
+    },
+  }
+}

package/app/utils/boardWakeGate.spec.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest'
+import { createWakeGate, type WakeGateScheduler } from './boardWakeGate'
+
+/** A hand-driven timer: `run()` fires the one scheduled callback, whatever its delay. */
+function fakeScheduler() {
+  let nextHandle = 1
+  const pending = new Map<number, { run: () => void; delayMs: number }>()
+  const scheduler: WakeGateScheduler = {
+    schedule(run, delayMs) {
+      const handle = nextHandle++
+      pending.set(handle, { run, delayMs })
+      return handle
+    },
+    cancel(handle) {
+      pending.delete(handle)
+    },
+  }
+  return {
+    scheduler,
+    pending: () => pending.size,
+    delays: () => [...pending.values()].map((p) => p.delayMs),
+    /** Fire every scheduled callback; anything they schedule waits for the next elapse. */
+    elapse() {
+      const due = [...pending.entries()]
+      pending.clear()
+      for (const [, { run }] of due) run()
+    },
+  }
+}
+
+function gateWith(intervalMs?: number) {
+  const clock = fakeScheduler()
+  let wakes = 0
+  const gate = createWakeGate({
+    wake: () => {
+      wakes++
+    },
+    scheduler: clock.scheduler,
+    intervalMs,
+  })
+  return { clock, gate, wakes: () => wakes }
+}
+
+describe('createWakeGate', () => {
+  it('wakes immediately on the first request', () => {
+    const { gate, wakes, clock } = gateWith()
+    gate.request()
+    expect(wakes()).toBe(1)
+    expect(clock.pending()).toBe(1)
+  })
+
+  it('admits at most one wake per interval while requests keep arriving', () => {
+    const { gate, wakes, clock } = gateWith()
+    gate.request()
+    gate.request()
+    gate.request()
+    expect(wakes()).toBe(1)
+
+    // The suppressed requests are owed one wake, which lands when the interval ends.
+    clock.elapse()
+    expect(wakes()).toBe(2)
+    // ... and the wake it just admitted opens the next interval, so a continuing stream
+    // stays bounded rather than firing per request.
+    gate.request()
+    expect(wakes()).toBe(2)
+    clock.elapse()
+    expect(wakes()).toBe(3)
+  })
+
+  it('goes idle after a quiet interval, so an isolated request is never delayed', () => {
+    const { gate, wakes, clock } = gateWith()
+    gate.request()
+    expect(wakes()).toBe(1)
+
+    clock.elapse()
+    // Nothing was owed, so the interval simply closed: no wake, nothing scheduled.
+    expect(wakes()).toBe(1)
+    expect(clock.pending()).toBe(0)
+
+    gate.request()
+    expect(wakes()).toBe(2)
+  })
+
+  it('drops an owed wake when cancelled, and admits the next request immediately', () => {
+    const { gate, wakes, clock } = gateWith()
+    gate.request()
+    gate.request()
+    gate.cancel()
+    clock.elapse()
+    expect(wakes()).toBe(1)
+
+    gate.request()
+    expect(wakes()).toBe(2)
+  })
+
+  it('schedules the interval the caller configured', () => {
+    const { gate, clock } = gateWith(40)
+    gate.request()
+    expect(clock.delays()).toEqual([40])
+  })
+})

package/app/utils/boardWakeGate.ts

@@ -0,0 +1,78 @@
+/**
+ * Rate limiter for the wakes the board's activity pulse raises from RENDERS.
+ *
+ * The canvas MutationObserver is deliberately broad (see `useBoardActivity`): it watches the
+ * whole subtree for structure plus `style`/`class`, which is what lets it catch a geometry
+ * change without enumerating the causes. The cost is that every Vue-driven card re-render
+ * wakes the two DOM-measuring loops, and each wake carries a settle tail of several frames,
+ * so under a steady execution-event stream a busy board never parks them: exactly the board
+ * where the measurement is most expensive pays for it continuously.
+ *
+ * A render is not a gesture, though. A card whose badge changed may or may not have moved its
+ * neighbours, and either way nobody is watching that pixel land within one frame, so these
+ * wakes may be COALESCED where a pointer/wheel/camera wake may not. This gate fires the first
+ * one straight through (an isolated change still follows within a frame) and then admits at
+ * most one per interval for as long as the stream lasts.
+ *
+ * The scheduler is injected so the behaviour is testable without a timer clock.
+ */
+export type WakeGateScheduler = {
+  schedule: (run: () => void, delayMs: number) => number
+  cancel: (handle: number) => void
+}
+
+export type WakeGate = {
+  /** Ask for a wake: immediate when the interval is clear, coalesced onto its end otherwise. */
+  request: () => void
+  /** Drop a coalesced wake that has not fired yet. Idempotent. */
+  cancel: () => void
+}
+
+/**
+ * How long one admitted render wake covers. The settle tail of a woken loop is ~4 frames
+ * (~66ms at 60Hz), so this leaves a busy board measuring for a fraction of each interval
+ * instead of every frame, while a change that really did move a card is on screen well inside
+ * the window a reader would notice.
+ */
+export const RENDER_WAKE_INTERVAL_MS = 250
+
+export function createWakeGate(options: {
+  /** Raise the pulse. */
+  wake: () => void
+  scheduler: WakeGateScheduler
+  intervalMs?: number
+}): WakeGate {
+  const { wake, scheduler } = options
+  const intervalMs = options.intervalMs ?? RENDER_WAKE_INTERVAL_MS
+  /** The open interval's handle, or null when no wake has been admitted recently. */
+  let window: number | null = null
+  /** Whether a request arrived while the interval was open and still owes a wake. */
+  let owed = false
+
+  function closeWindow() {
+    window = null
+    // A quiet interval simply ends: the next request is admitted immediately, so an isolated
+    // render never waits. Only a stream that kept asking re-opens the interval, which is what
+    // bounds it to one wake per interval for as long as it lasts.
+    if (!owed) return
+    owed = false
+    wake()
+    window = scheduler.schedule(closeWindow, intervalMs)
+  }
+
+  return {
+    request() {
+      if (window !== null) {
+        owed = true
+        return
+      }
+      wake()
+      window = scheduler.schedule(closeWindow, intervalMs)
+    },
+    cancel() {
+      if (window !== null) scheduler.cancel(window)
+      window = null
+      owed = false
+    },
+  }
+}

package/i18n/locales/de.json

@@ -6041,6 +6041,11 @@
         "body": "Die Bereitstellungsintegration dieses Dienstes hat den Verbindungstest nicht bestanden: {detail}. Überprüfe ihren Endpunkt und ihre Anmeldedaten und teste die Verbindung erneut, um sie auszuführen.",
         "action": "Infrastruktur konfigurieren"
       }
+    },
+    "asyncView": {
+      "title": "Diese Ansicht konnte nicht geladen werden",
+      "body": "Ihr Code konnte nicht geladen werden. Meist wurde die Anwendung aktualisiert, während dieser Tab geöffnet war, sodass die angeforderten Dateien nicht mehr auf dem Server liegen. Laden Sie neu, um die aktuelle Version zu erhalten.",
+      "reload": "Neu laden"
     }
   },
   "slack": {

package/i18n/locales/en.json

@@ -847,6 +847,11 @@
         },
         "action": "Configure infrastructure"
       }
+    },
+    "asyncView": {
+      "title": "This view could not be loaded",
+      "body": "Its code failed to load. That usually means the app was updated while this tab was open, so the files this page is asking for are no longer on the server. Reload to pick up the current version.",
+      "reload": "Reload"
     }
   },
   "personalSubscriptions": {

package/i18n/locales/es.json

@@ -757,6 +757,11 @@
         "body": "La integración de despliegue de este servicio falló la prueba de conexión: {detail}. Revisa su endpoint y credenciales y vuelve a probar la conexión para ejecutarla.",
         "action": "Configurar infraestructura"
       }
+    },
+    "asyncView": {
+      "title": "No se pudo cargar esta vista",
+      "body": "No se pudo cargar su código. Normalmente significa que la aplicación se actualizó mientras esta pestaña estaba abierta, así que los archivos que pide esta página ya no están en el servidor. Vuelve a cargar para obtener la versión actual.",
+      "reload": "Volver a cargar"
     }
   },
   "personalSubscriptions": {

package/i18n/locales/fr.json

@@ -757,6 +757,11 @@
         "body": "L’intégration de déploiement de ce service a échoué au test de connexion : {detail}. Vérifiez son point de terminaison et ses identifiants, puis retestez la connexion pour l’exécuter.",
         "action": "Configurer l’infrastructure"
       }
+    },
+    "asyncView": {
+      "title": "Cette vue n'a pas pu être chargée",
+      "body": "Son code n'a pas pu être chargé. Cela signifie généralement que l'application a été mise à jour pendant que cet onglet était ouvert : les fichiers demandés par cette page ne sont plus sur le serveur. Rechargez pour obtenir la version actuelle.",
+      "reload": "Recharger"
     }
   },
   "personalSubscriptions": {

package/i18n/locales/he.json

@@ -757,6 +757,11 @@
         "body": "אינטגרציית הפריסה של שירות זה נכשלה בבדיקת החיבור: {detail}. בדוק את נקודת הקצה והאישורים שלה, ואז בדוק שוב את החיבור כדי להריץ אותו.",
         "action": "הגדר תשתית"
       }
+    },
+    "asyncView": {
+      "title": "לא ניתן היה לטעון את התצוגה הזו",
+      "body": "טעינת הקוד שלה נכשלה. בדרך כלל המשמעות היא שהאפליקציה עודכנה בזמן שהלשונית הזו הייתה פתוחה, ולכן הקבצים שהדף מבקש כבר אינם בשרת. רעננו כדי לקבל את הגרסה הנוכחית.",
+      "reload": "רענון"
     }
   },
   "personalSubscriptions": {

package/i18n/locales/it.json

@@ -6041,6 +6041,11 @@
         "body": "L’integrazione di deployment di questo servizio non ha superato il test di connessione: {detail}. Controlla il suo endpoint e le credenziali, poi riprova la connessione per eseguirla.",
         "action": "Configura infrastruttura"
       }
+    },
+    "asyncView": {
+      "title": "Impossibile caricare questa vista",
+      "body": "Il suo codice non è stato caricato. Di solito significa che l'applicazione è stata aggiornata mentre questa scheda era aperta, quindi i file richiesti da questa pagina non sono più sul server. Ricarica per ottenere la versione attuale.",
+      "reload": "Ricarica"
     }
   },
   "slack": {

package/i18n/locales/ja.json

@@ -757,6 +757,11 @@
         "body": "このサービスのデプロイ連携が接続テストに失敗しました: {detail}。エンドポイントと認証情報を確認し、接続を再テストしてから実行してください。",
         "action": "インフラを設定"
       }
+    },
+    "asyncView": {
+      "title": "このビューを読み込めませんでした",
+      "body": "コードの読み込みに失敗しました。多くの場合、このタブを開いたままアプリが更新され、このページが要求しているファイルがサーバー上に存在しなくなったことが原因です。再読み込みして最新版を取得してください。",
+      "reload": "再読み込み"
     }
   },
   "personalSubscriptions": {

package/i18n/locales/pl.json

@@ -757,6 +757,11 @@
         "body": "Integracja wdrożeniowa tej usługi nie przeszła testu połączenia: {detail}. Sprawdź jej punkt końcowy i poświadczenia, a następnie ponownie przetestuj połączenie, aby go uruchomić.",
         "action": "Skonfiguruj infrastrukturę"
       }
+    },
+    "asyncView": {
+      "title": "Nie udało się wczytać tego widoku",
+      "body": "Nie udało się wczytać jego kodu. Zwykle oznacza to, że aplikacja została zaktualizowana, gdy ta karta była otwarta, więc plików żądanych przez tę stronę nie ma już na serwerze. Odśwież, aby pobrać aktualną wersję.",
+      "reload": "Odśwież"
     }
   },
   "personalSubscriptions": {

package/i18n/locales/tr.json

@@ -757,6 +757,11 @@
         "body": "Bu hizmetin dağıtım entegrasyonu bağlantı testinde başarısız oldu: {detail}. Uç noktasını ve kimlik bilgilerini kontrol edin, ardından çalıştırmak için bağlantıyı yeniden test edin.",
         "action": "Altyapıyı yapılandır"
       }
+    },
+    "asyncView": {
+      "title": "Bu görünüm yüklenemedi",
+      "body": "Kodu yüklenemedi. Bu genellikle bu sekme açıkken uygulamanın güncellendiği anlamına gelir; sayfanın istediği dosyalar artık sunucuda değildir. Geçerli sürümü almak için yeniden yükleyin.",
+      "reload": "Yeniden yükle"
     }
   },
   "personalSubscriptions": {

package/i18n/locales/uk.json

@@ -757,6 +757,11 @@
         "body": "Інтеграція розгортання цього сервісу не пройшла перевірку з’єднання: {detail}. Перевірте її кінцеву точку та облікові дані, потім повторно перевірте з’єднання, щоб запустити його.",
         "action": "Налаштувати інфраструктуру"
       }
+    },
+    "asyncView": {
+      "title": "Не вдалося завантажити цей вигляд",
+      "body": "Не вдалося завантажити його код. Зазвичай це означає, що застосунок оновили, поки ця вкладка була відкрита, тож файлів, які запитує ця сторінка, уже немає на сервері. Перезавантажте, щоб отримати поточну версію.",
+      "reload": "Перезавантажити"
     }
   },
   "personalSubscriptions": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.280.0",
+  "version": "0.280.1",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",