@cat-factory/app 0.43.0 → 0.45.0

package/app/composables/useArtifactBlobs.ts

@@ -0,0 +1,120 @@
+import { reactive } from 'vue'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Per-component cache for resolving stored binary artifacts (screenshots / reference
+ * designs) into `<img>`-ready object URLs.
+ *
+ * The artifact bytes are served behind an authed endpoint (`GET /workspaces/:ws/
+ * artifacts/:id/blob`), so the browser can't point an `<img src>` straight at them — they
+ * have to be fetched as a `Blob` and turned into an `URL.createObjectURL`. That object URL
+ * pins the blob in memory until it's explicitly revoked, so this composable is a FACTORY
+ * (one cache per calling component), and the caller MUST `revokeAll()` on unmount. Making
+ * it a global singleton would mean one window's unmount frees another window's images.
+ *
+ * Both the visual-confirmation gate and the test-report window use this, so neither has to
+ * own blob plumbing or depend on the other's Pinia store.
+ */
+export type ArtifactBlobStatus = 'idle' | 'loading' | 'ready' | 'error'
+
+export function useArtifactBlobs() {
+  const ws = useWorkspaceStore()
+  const api = useApi()
+
+  /** artifactId → object URL (reactive so templates re-render when a blob resolves). */
+  const urls = reactive<Record<string, string>>({})
+  /** artifactId → fetch status, drives loading / error / retry affordances. */
+  const status = reactive<Record<string, ArtifactBlobStatus>>({})
+  /** In-flight promises, so concurrent `resolve(id)` calls share one fetch + one blob. */
+  const inFlight = new Map<string, Promise<string | null>>()
+  /**
+   * Set once `revokeAll()` has run (the owning component unmounted). A fetch already in
+   * flight at that point still creates its object URL when it settles; without this guard
+   * that URL would be written into the now-cleared cache and never revoked (a leak), and
+   * we'd be mutating reactive state for a dead component.
+   */
+  let disposed = false
+
+  function urlFor(id: string | null | undefined): string | undefined {
+    return id ? urls[id] : undefined
+  }
+
+  function statusFor(id: string | null | undefined): ArtifactBlobStatus {
+    return id ? (status[id] ?? 'idle') : 'idle'
+  }
+
+  /** Resolve an artifact to an object URL (cached + deduped). Returns null on failure. */
+  function resolve(id: string | null | undefined): Promise<string | null> {
+    if (!id || disposed) return Promise.resolve(null)
+    const cached = urls[id]
+    if (cached) return Promise.resolve(cached)
+    const pending = inFlight.get(id)
+    if (pending) return pending
+
+    status[id] = 'loading'
+    const p = api
+      .fetchArtifactBlobUrl(ws.requireId(), id)
+      .then((url) => {
+        // The owner unmounted while this was in flight: revoke the freshly-minted URL
+        // instead of stranding it in the cleared cache.
+        if (disposed) {
+          try {
+            URL.revokeObjectURL(url)
+          } catch {
+            // Already revoked / unsupported environment — nothing to do.
+          }
+          return null
+        }
+        urls[id] = url
+        status[id] = 'ready'
+        return url
+      })
+      .catch(() => {
+        status[id] = 'error'
+        return null
+      })
+      .finally(() => {
+        inFlight.delete(id)
+      })
+    inFlight.set(id, p)
+    return p
+  }
+
+  /** Force a re-fetch of a previously-failed artifact (clears its cached error state). */
+  function retry(id: string): Promise<string | null> {
+    const stale = urls[id]
+    if (stale) {
+      try {
+        URL.revokeObjectURL(stale)
+      } catch {
+        // Already revoked / unsupported environment — nothing to do.
+      }
+    }
+    delete urls[id]
+    status[id] = 'idle'
+    inFlight.delete(id)
+    return resolve(id)
+  }
+
+  /**
+   * Revoke every cached object URL and clear the cache. Call on `onUnmounted` — otherwise
+   * the (potentially large) screenshot bytes linger in memory for the session's lifetime.
+   */
+  function revokeAll(): void {
+    disposed = true
+    for (const url of Object.values(urls)) {
+      try {
+        URL.revokeObjectURL(url)
+      } catch {
+        // Already revoked / unsupported environment — nothing to do.
+      }
+    }
+    for (const k of Object.keys(urls)) delete urls[k]
+    for (const k of Object.keys(status)) delete status[k]
+    inFlight.clear()
+  }
+
+  return { urls, status, urlFor, statusFor, resolve, retry, revokeAll }
+}
+
+export type ArtifactBlobs = ReturnType<typeof useArtifactBlobs>

package/app/composables/useFocusTrap.ts

@@ -0,0 +1,72 @@
+import { nextTick, onScopeDispose, watch, type Ref } from 'vue'
+
+/**
+ * Lightweight focus management for a modal surface (the screenshot review windows + the
+ * shared lightbox). While `active`, it:
+ *   · moves focus into the container on open (so keyboard / screen-reader users land inside
+ *     the dialog instead of staying on the background),
+ *   · traps Tab / Shift+Tab within the container's focusable elements, and
+ *   · restores focus to whatever was focused before, on close.
+ *
+ * Nested surfaces (a lightbox opened over a review window) hand off cleanly because each
+ * caller scopes its own `active` — the window passes `open && !lightboxOpen`, so exactly one
+ * trap is live at a time and they never fight over Tab.
+ */
+export function useFocusTrap(container: Ref<HTMLElement | null>, active: Ref<boolean>): void {
+  let previouslyFocused: HTMLElement | null = null
+
+  function focusables(): HTMLElement[] {
+    const root = container.value
+    if (!root) return []
+    const nodes = root.querySelectorAll<HTMLElement>(
+      'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+    )
+    // Skip elements that aren't actually rendered (e.g. inside a `v-if`/`hidden` branch).
+    return Array.from(nodes).filter(
+      (el) => el.offsetParent !== null || el === document.activeElement,
+    )
+  }
+
+  function onKeydown(e: KeyboardEvent): void {
+    if (!active.value || e.key !== 'Tab') return
+    const els = focusables()
+    if (!els.length) {
+      e.preventDefault()
+      container.value?.focus()
+      return
+    }
+    const first = els[0]!
+    const last = els[els.length - 1]!
+    const current = document.activeElement as HTMLElement | null
+    const inside = !!container.value?.contains(current)
+    if (e.shiftKey) {
+      if (!inside || current === first) {
+        e.preventDefault()
+        last.focus()
+      }
+    } else if (!inside || current === last) {
+      e.preventDefault()
+      first.focus()
+    }
+  }
+
+  watch(
+    active,
+    (on) => {
+      if (on) {
+        previouslyFocused = document.activeElement as HTMLElement | null
+        window.addEventListener('keydown', onKeydown, true)
+        void nextTick(() => {
+          ;(focusables()[0] ?? container.value)?.focus()
+        })
+      } else {
+        window.removeEventListener('keydown', onKeydown, true)
+        previouslyFocused?.focus?.()
+        previouslyFocused = null
+      }
+    },
+    { immediate: true },
+  )
+
+  onScopeDispose(() => window.removeEventListener('keydown', onKeydown, true))
+}

package/app/stores/visualConfirm.ts

@@ -6,9 +6,11 @@ import { useWorkspaceStore } from '~/stores/workspace'
 /**
  * Visual-confirmation gate actions. The gate's live state rides on its execution step
  * (`step.visualConfirm`) and arrives via the execution stream, so this store holds NO gate
- * state — it only drives the actions (approve / request a fix / recapture), uploads reference
- * design images, and resolves stored artifacts into object URLs for the gallery. A per-block
- * `busy` flag lets the window disable its controls while an action is in flight.
+ * state — it only drives the actions (approve / request a fix / recapture) and uploads
+ * reference design images. A per-block `busy` flag lets the window disable its controls
+ * while an action is in flight. (Resolving stored artifacts into object URLs for the gallery
+ * lives in the per-component `useArtifactBlobs` composable, so each window owns + revokes its
+ * own blob cache on unmount.)
  */
 export const useVisualConfirmStore = defineStore('visualConfirm', () => {
   const api = useApi()
@@ -16,8 +18,6 @@ export const useVisualConfirmStore = defineStore('visualConfirm', () => {
   const execution = useExecutionStore()
 
   const busy = ref<Set<string>>(new Set())
-  /** Cache of artifactId → object URL, so the gallery doesn't re-fetch the same blob. */
-  const blobUrls = ref<Map<string, string>>(new Map())
 
   function isBusy(blockId: string): boolean {
     return busy.value.has(blockId)
@@ -59,34 +59,5 @@ export const useVisualConfirmStore = defineStore('visualConfirm', () => {
     return run(blockId, () => api.uploadReferenceArtifact(ws.requireId(), blockId, file, view))
   }
 
-  /** Resolve a stored artifact to an object URL (cached). Returns null on failure. */
-  async function blobUrl(artifactId: string): Promise<string | null> {
-    const cached = blobUrls.value.get(artifactId)
-    if (cached) return cached
-    try {
-      const url = await api.fetchArtifactBlobUrl(ws.requireId(), artifactId)
-      blobUrls.value.set(artifactId, url)
-      return url
-    } catch {
-      return null
-    }
-  }
-
-  /**
-   * Release every cached object URL and clear the cache. `URL.createObjectURL` holds the
-   * blob in memory until explicitly revoked, so the gate window calls this on unmount to
-   * avoid leaking the (potentially large) screenshot bytes for the session's lifetime.
-   */
-  function revokeBlobs(): void {
-    for (const url of blobUrls.value.values()) {
-      try {
-        URL.revokeObjectURL(url)
-      } catch {
-        // Ignore — a URL already revoked / unsupported environment.
-      }
-    }
-    blobUrls.value = new Map()
-  }
-
-  return { isBusy, approve, requestFix, recapture, uploadReference, blobUrl, revokeBlobs }
+  return { isBusy, approve, requestFix, recapture, uploadReference }
 })

package/app/types/domain.ts

@@ -22,6 +22,7 @@ export type {
   TaskType,
   CreateTaskType,
   TaskTypeFields,
+  DocKind,
   Block,
   PullRequestRef,
   CloudProvider,
@@ -32,6 +33,7 @@ export type {
   TestConcern,
   TestOutcome,
   TestReport,
+  TestScreenshot,
   AgentKind,
   AgentCategory,
   CustomAgentKind,
@@ -52,6 +54,10 @@ export type {
 
 import type { AgentCategory, AgentKind } from '@cat-factory/contracts'
 
+// The document-kind list is a runtime value (used to render the picker), so it is re-exported
+// as a value — the single source of truth lives in the contracts package.
+export { DOC_KINDS } from '@cat-factory/contracts'
+
 /** A draggable agent definition shown in the agent palette. Frontend-only. */
 export interface AgentArchetype {
   kind: AgentKind

package/app/utils/catalog.spec.ts

@@ -28,6 +28,7 @@ const AGENT_KINDS: AgentKind[] = [
   'integrator',
   'architect-companion',
   'spec-companion',
+  'doc-reviewer',
   'playwright',
   'mocker',
   'business-documenter',

package/app/utils/catalog.ts

@@ -251,6 +251,14 @@ export const COMPANION_ARCHETYPES: AgentArchetype[] = [
     description:
       'Reviews the spec — especially acceptance-scenario coverage — rating it and looping the Spec Writer back for automatic rework below the threshold, instead of requiring a human review.',
   },
+  {
+    kind: 'doc-reviewer',
+    label: 'Doc Reviewer',
+    icon: 'i-lucide-file-search',
+    color: '#818cf8',
+    description:
+      'Reviews the drafted document for completeness, clarity, accuracy and structure, looping the Doc Writer back for automatic rework below the threshold.',
+  },
 ]
 
 /**
@@ -262,6 +270,7 @@ export const COMPANION_FOR_PRODUCER: Record<string, AgentKind> = {
   coder: 'reviewer',
   architect: 'architect-companion',
   'spec-writer': 'spec-companion',
+  'doc-writer': 'doc-reviewer',
 }
 
 const COMPANION_KINDS: ReadonlySet<string> = new Set(COMPANION_ARCHETYPES.map((a) => a.kind))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "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",
@@ -34,7 +34,7 @@
     "pinia-plugin-persistedstate": "^4.7.1",
     "vue": "^3.5.38",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.41.0"
+    "@cat-factory/contracts": "0.42.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.1",