@cat-factory/app 0.116.6 → 0.116.7

package/app/components/auth/AuthGate.vue

@@ -14,7 +14,9 @@ const { t } = useI18n()
 // out, so it must render even when auth is required and there's no user.
 const isPublicRoute = computed(() => route.path === '/reset-password')
 
-onMounted(() => auth.bootstrap())
+// Stamp the first cold-open milestone once the auth handshake settles (app-startup initiative,
+// item 1) — bootstrap resolves even on failure (it catches internally), so `finally` always fires.
+onMounted(() => void auth.bootstrap().finally(() => markBoot('auth-ready')))
 </script>
 
 <template>

package/app/components/layout/SideBar.vue

@@ -100,11 +100,14 @@ watch(
   () => workspace.workspaceId,
   (id) => {
     if (!id) return
-    void documents.probe()
-    void tasks.probe()
-    void github.probe()
-    void slack.probe()
-    void library.probe()
+    // `ensureProbed` single-flights per board (app-startup initiative, item 12): on a cold open
+    // these coalesce with the board page's own github probe and don't refire on a re-mount, while a
+    // workspace switch (new id) still re-probes. `probe()` stays the explicit post-connect refresh.
+    void documents.ensureProbed()
+    void tasks.ensureProbed()
+    void github.ensureProbed()
+    void slack.ensureProbed()
+    void library.ensureProbed()
     void providerConnections.ensureLoaded().catch(() => {})
   },
   { immediate: true },

package/app/composables/useSingleFlightProbe.spec.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it, vi } from 'vitest'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
+
+// Single-flight probe guard (app-startup initiative, item 12). Pure logic, no Pinia/Nuxt: a fake
+// `run` (counting calls, with a manually-resolved promise) and a mutable `id` getter.
+
+/** A `run` whose promise the test resolves by hand, plus a call counter. */
+function deferredRun() {
+  let resolve!: () => void
+  const calls = { count: 0 }
+  const run = vi.fn(() => {
+    calls.count++
+    return new Promise<void>((r) => (resolve = r))
+  })
+  return { run, calls, resolve: () => resolve() }
+}
+
+describe('useSingleFlightProbe', () => {
+  it('coalesces concurrent probe() calls for the same board into one run', async () => {
+    const { run, calls, resolve } = deferredRun()
+    const { probe } = useSingleFlightProbe(run, () => 'ws1')
+
+    const a = probe()
+    const b = probe()
+    expect(calls.count).toBe(1) // one in-flight run shared by both callers
+    resolve()
+    await Promise.all([a, b])
+  })
+
+  it('ensureProbed() is a no-op once the board is already probed', async () => {
+    const { run, calls, resolve } = deferredRun()
+    const { ensureProbed } = useSingleFlightProbe(run, () => 'ws1')
+
+    const first = ensureProbed()
+    resolve()
+    await first
+    expect(calls.count).toBe(1)
+
+    await ensureProbed() // already settled for ws1 → does not run again
+    expect(calls.count).toBe(1)
+  })
+
+  it('ensureProbed() re-runs when the workspace id changes', async () => {
+    const { run, calls, resolve } = deferredRun()
+    let id = 'ws1'
+    const { ensureProbed } = useSingleFlightProbe(run, () => id)
+
+    const first = ensureProbed()
+    resolve()
+    await first
+    expect(calls.count).toBe(1)
+
+    id = 'ws2' // a switch — connections are per board, so it must re-probe
+    const second = ensureProbed()
+    resolve()
+    await second
+    expect(calls.count).toBe(2)
+  })
+
+  it('probe() always re-runs (a deliberate refresh) even after a completed probe', async () => {
+    const { run, calls, resolve } = deferredRun()
+    const guard = useSingleFlightProbe(run, () => 'ws1')
+
+    const first = guard.probe()
+    resolve()
+    await first
+    expect(calls.count).toBe(1)
+
+    const refresh = guard.probe() // e.g. after a connect — re-reads
+    resolve()
+    await refresh
+    expect(calls.count).toBe(2)
+  })
+
+  it('a probe() refresh in flight is shared by a concurrent ensureProbed()', async () => {
+    const { run, calls, resolve } = deferredRun()
+    const guard = useSingleFlightProbe(run, () => 'ws1')
+
+    const refresh = guard.probe()
+    const ensured = guard.ensureProbed() // rides the in-flight probe rather than firing a duplicate
+    expect(calls.count).toBe(1)
+    resolve()
+    await Promise.all([refresh, ensured])
+  })
+
+  it('a superseded out-of-order completion does not stamp a stale probedId', async () => {
+    // ws1 probe starts, then a switch to ws2 starts a second — and ws2 (the newer, current board)
+    // resolves BEFORE the older ws1 probe. The late ws1 completion must NOT record ws1 as the
+    // settled board, else the next ensureProbed() for ws2 would redundantly re-run.
+    let id = 'ws1'
+    let n = 0
+    let resolve1!: () => void
+    let resolve2!: () => void
+    const run = vi.fn(() => {
+      n++
+      return new Promise<void>((r) => (n === 1 ? (resolve1 = r) : (resolve2 = r)))
+    })
+    const { ensureProbed } = useSingleFlightProbe(run, () => id)
+
+    const p1 = ensureProbed() // starts ws1
+    id = 'ws2'
+    const p2 = ensureProbed() // starts ws2 (a switch — different id)
+    expect(run).toHaveBeenCalledTimes(2)
+
+    resolve2() // the current board settles first
+    await p2
+    resolve1() // the superseded older probe settles late
+    await p1
+
+    // ws2 is the current, settled board → ensureProbed() is a no-op, not a third (redundant) run.
+    await ensureProbed()
+    expect(run).toHaveBeenCalledTimes(2)
+  })
+})

package/app/composables/useSingleFlightProbe.ts

@@ -0,0 +1,70 @@
+/**
+ * Single-flight guard for a per-workspace integration probe (app-startup initiative, item 12).
+ *
+ * On a board open the same probe is fired from several places at once — e.g. `github.probe()` runs
+ * from both the board page (to resolve the onboarding gate) and the SideBar, and the SideBar fans
+ * out five more (`documents` / `tasks` / `slack` / `library` / provider connections). Each was an
+ * independent network call, and a re-mount re-ran them. This wraps a store's probe with two
+ * behaviours keyed on the active workspace id:
+ *
+ *   - {@link probe} — always re-runs the probe (deliberate refresh, e.g. after a connect), but a
+ *     burst of concurrent callers on ONE board open shares the single in-flight request.
+ *   - {@link ensureProbed} — runs the probe AT MOST ONCE per workspace: a no-op when this board is
+ *     already probed, or the shared in-flight promise otherwise. This is what the on-board-open
+ *     fan-out uses, so the duplicate/refire collapses to one call — while a workspace SWITCH (a new
+ *     id) still re-probes, since connections are per board.
+ *
+ * The id-keying means no explicit reset on workspace change: a call for a different id than the last
+ * completed probe re-runs. `run` reads whatever workspace-scoped state it needs itself; `currentId`
+ * only supplies the key (and the "which board did this settle for" record).
+ */
+interface SingleFlightProbe {
+  probe: () => Promise<void>
+  ensureProbed: () => Promise<void>
+}
+
+export function useSingleFlightProbe(
+  run: () => Promise<void>,
+  currentId: () => string | null,
+): SingleFlightProbe {
+  let inFlight: Promise<void> | null = null
+  let inFlightId: string | null = null
+  let probedId: string | null = null
+
+  function start(id: string | null): Promise<void> {
+    const p = Promise.resolve(run()).finally(() => {
+      // Only record "settled for this board" / clear the in-flight slot when a NEWER probe hasn't
+      // superseded us. Otherwise an out-of-order completion — an older probe for board A resolving
+      // after a newer probe for board B — would stamp probedId back to A and force a redundant
+      // re-probe of B on the next ensureProbed. The newer probe owns `inFlight`, so it records the
+      // board that's actually current.
+      if (inFlight === p) {
+        probedId = id
+        inFlight = null
+        inFlightId = null
+      }
+    })
+    inFlight = p
+    inFlightId = id
+    return p
+  }
+
+  function probe(): Promise<void> {
+    const id = currentId()
+    // Share an already-running probe for the same board (the concurrent-burst case); otherwise
+    // start a fresh one — a deliberate refresh must always re-read.
+    if (inFlight && inFlightId === id) return inFlight
+    return start(id)
+  }
+
+  function ensureProbed(): Promise<void> {
+    const id = currentId()
+    // Already settled for this board and nothing running → nothing to do.
+    if (probedId === id && !inFlight) return Promise.resolve()
+    // A probe for this board is in flight → ride it rather than firing a duplicate.
+    if (inFlight && inFlightId === id) return inFlight
+    return start(id)
+  }
+
+  return { probe, ensureProbed }
+}

package/app/composables/useSourceIntegration.ts

@@ -1,5 +1,6 @@
 import { type ComputedRef, type Ref, computed, ref } from 'vue'
 import { apiErrorEnvelope, apiErrorStatus } from '~/composables/api/errors'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import { useUpsertList } from '~/composables/useUpsertList'
 
 /**
@@ -25,6 +26,12 @@ export function useSourceIntegration<
   fetch: () => Promise<{ sources: Desc[]; connections: Conn[] }>
   /** Gate the probe (e.g. skip until a workspace is selected). */
   enabled?: () => boolean
+  /**
+   * The active workspace id, keying the single-flight probe (app-startup initiative, item 12): a
+   * board-open fan-out via `ensureProbed` hits the source once per board, and a workspace switch
+   * (new id) re-probes. Omitted ⇒ a single bucket (probe-once for the composable's lifetime).
+   */
+  workspaceId?: () => string | null
 }): {
   available: Ref<boolean | null>
   probeError: Ref<{ status: number | null; message: string } | null>
@@ -38,6 +45,7 @@ export function useSourceIntegration<
   upsertConnection: (conn: Conn) => void
   removeConnection: (source: Source) => void
   probe: () => Promise<void>
+  ensureProbed: () => Promise<void>
 } {
   /** null = unknown (not probed yet), true/false = integration on/off. */
   const available = ref<boolean | null>(null)
@@ -67,7 +75,7 @@ export function useSourceIntegration<
   }
 
   /** Probe the integration: resolves `available`, the sources and connections. */
-  async function probe() {
+  async function runProbe() {
     if (opts.enabled && !opts.enabled()) return
     try {
       const { sources: srcs, connections: conns } = await opts.fetch()
@@ -89,6 +97,13 @@ export function useSourceIntegration<
       connections.value = []
     }
   }
+  // Single-flight the probe (app-startup initiative, item 12): `probe()` still re-reads on demand
+  // (a connect/disconnect refresh), but the board-open fan-out uses `ensureProbed` so it fetches
+  // once per board rather than on every SideBar/page (re)mount.
+  const { probe, ensureProbed } = useSingleFlightProbe(
+    runProbe,
+    opts.workspaceId ?? (() => 'source-integration'),
+  )
 
   return {
     available,
@@ -103,5 +118,6 @@ export function useSourceIntegration<
     upsertConnection,
     removeConnection,
     probe,
+    ensureProbed,
   }
 }

package/app/pages/index.vue

@@ -245,12 +245,13 @@ watch(
 
 // Probe the GitHub integration as soon as a board is active (re-probe per board —
 // connections are per workspace). The result drives the onboarding gate below
-// before the board mounts, so an unconnected user can't slip past it. SideBar
-// re-probes once it mounts; that duplicate is harmless (probe is idempotent).
+// before the board mounts, so an unconnected user can't slip past it. `ensureProbed`
+// single-flights per board (app-startup initiative, item 12), so this and the SideBar's
+// probe collapse to one request on a cold open instead of two.
 watch(
   () => workspace.workspaceId,
   (id) => {
-    if (id) void github.probe()
+    if (id) void github.ensureProbed()
   },
   { immediate: true },
 )
@@ -268,6 +269,9 @@ const stream = useWorkspaceStream()
 // in the template would not unwrap, since `stream` is a plain object). Drives the headless
 // `workspace-stream` readiness marker the e2e suite waits on.
 const streamConnected = computed(() => stream.connected.value)
+// Final cold-open milestone (app-startup initiative, item 1): a live, reconciled board. `markBoot`
+// fires once, so only the first connect of the session times the waterfall's tail.
+watch(streamConnected, (c) => c && markBoot('stream-connected'), { immediate: true })
 const streamEverConnected = computed(() => stream.everConnected.value)
 const streamConnectionFailed = computed(() => stream.connectionFailed.value)
 watch(

package/app/stores/documents.ts

@@ -35,6 +35,7 @@ export const useDocumentsStore = defineStore('documents', () => {
     DocumentSourceDescriptor
   >({
     enabled: () => !!workspace.workspaceId,
+    workspaceId: () => workspace.workspaceId,
     fetch: async () => {
       const [{ sources }, { connections }] = await Promise.all([
         api.listDocumentSources(workspace.requireId()),
@@ -44,7 +45,7 @@ export const useDocumentsStore = defineStore('documents', () => {
     },
   })
   const { available, sources, connections, connectedSources, anyConnected } = integration
-  const { descriptorFor, connectionFor, isConnected, probe } = integration
+  const { descriptorFor, connectionFor, isConnected, probe, ensureProbed } = integration
 
   const { items: documents, upsert: upsertDoc } = useUpsertList<SourceDocument>({
     key: (d) => `${d.source}:${d.externalId}`,
@@ -187,6 +188,7 @@ export const useDocumentsStore = defineStore('documents', () => {
     isConnected,
     docsForBlock,
     probe,
+    ensureProbed,
     connect,
     disconnect,
     loadDocuments,

package/app/stores/fragmentLibrary.ts

@@ -10,6 +10,7 @@ import type {
   ResolvedFragment,
   UpdatePromptFragmentInput,
 } from '~/types/domain'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { useFragmentsStore } from '~/stores/fragments'
 
@@ -62,7 +63,7 @@ function fragmentLibrarySetup(kind: FragmentOwnerKind, resolveOwnerId: () => str
   }
 
   /** Probe the feature + load this owner's tier, sources and (ws) resolved catalog. */
-  async function probe() {
+  async function runProbe() {
     const id = resolveOwnerId()
     if (!id) return
     try {
@@ -82,6 +83,10 @@ function fragmentLibrarySetup(kind: FragmentOwnerKind, resolveOwnerId: () => str
       resolved.value = []
     }
   }
+  // Single-flight the probe keyed on the owner id (app-startup initiative, item 12): the SideBar's
+  // board-open fan-out uses `ensureProbed`, so it loads once per owner; `probe()` stays the
+  // on-demand refresh (a library mutation still re-reads via the explicit calls).
+  const { probe, ensureProbed } = useSingleFlightProbe(runProbe, () => resolveOwnerId())
 
   async function refreshResolved() {
     // Every library mutation lands here: drop the picker catalog's cache so the
@@ -192,6 +197,7 @@ function fragmentLibrarySetup(kind: FragmentOwnerKind, resolveOwnerId: () => str
     viaWorkspaceId,
     builtinCount,
     probe,
+    ensureProbed,
     refreshResolved,
     create,
     createDocumentFragment,

package/app/stores/github.ts

@@ -13,6 +13,7 @@ import type {
   OpenPullRequestInput,
   ResyncRequest,
 } from '~/types/domain'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { useServicesStore } from '~/stores/services'
 
@@ -96,7 +97,7 @@ export const useGitHubStore = defineStore('github', () => {
   }
 
   /** Probe the integration: resolves `available` and the current connection. */
-  async function probe() {
+  async function runProbe() {
     if (!workspace.workspaceId) return
     try {
       const { connection: conn } = await api.getGitHubConnection(workspace.requireId())
@@ -108,6 +109,11 @@ export const useGitHubStore = defineStore('github', () => {
       connection.value = null
     }
   }
+  // Single-flight the probe (app-startup initiative, item 12): `probe()` still re-reads on demand,
+  // but the on-board-open callers (the board page's onboarding gate + the SideBar) use
+  // `ensureProbed()` so their duplicate fire collapses to one request per board. A workspace switch
+  // (new id) re-probes.
+  const { probe, ensureProbed } = useSingleFlightProbe(runProbe, () => workspace.workspaceId)
 
   /** Load the cached repos, pull requests and issues for the workspace. */
   async function load() {
@@ -327,6 +333,7 @@ export const useGitHubStore = defineStore('github', () => {
     pullUrl,
     issueUrl,
     probe,
+    ensureProbed,
     load,
     ensureLoaded,
     loadAvailableRepos,

package/app/stores/slack.ts

@@ -6,6 +6,7 @@ import type {
   SlackMemberMappingEntry,
   SlackNotificationSettings,
 } from '~/types/domain'
+import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import { useWorkspaceStore } from '~/stores/workspace'
 
 /**
@@ -43,7 +44,8 @@ export const useSlackStore = defineStore('slack', () => {
    * is off — hide the UI. On success, capture the connection + whether OAuth is
    * available. Called on workspace change, like the GitHub probe.
    */
-  async function probe() {
+  async function runProbe() {
+    if (!workspace.workspaceId) return
     try {
       const { connection: conn, oauthEnabled: oauth } = await api.getSlackConnection(
         workspace.requireId(),
@@ -56,6 +58,9 @@ export const useSlackStore = defineStore('slack', () => {
       connection.value = null
     }
   }
+  // Single-flight the probe (app-startup initiative, item 12) so the SideBar's board-open fan-out
+  // (via `ensureProbed`) hits Slack once per board; `probe()` stays the on-demand refresh.
+  const { probe, ensureProbed } = useSingleFlightProbe(runProbe, () => workspace.workspaceId)
 
   /** Resolve the "Add to Slack" OAuth URL (only when oauthEnabled). */
   function installUrl(): Promise<string> {
@@ -130,6 +135,7 @@ export const useSlackStore = defineStore('slack', () => {
     saving,
     connected,
     probe,
+    ensureProbed,
     installUrl,
     connectWithToken,
     disconnect,

package/app/stores/tasks.ts

@@ -34,6 +34,7 @@ export const useTasksStore = defineStore('tasks', () => {
   // (integration disabled vs a server/backend error) instead of "install it first".
   const integration = useSourceIntegration<TaskSourceKind, TaskConnection, TaskSourceState>({
     enabled: () => !!workspace.workspaceId,
+    workspaceId: () => workspace.workspaceId,
     fetch: async () => {
       const [{ sources }, { connections }] = await Promise.all([
         api.listTaskSources(workspace.requireId()),
@@ -44,7 +45,7 @@ export const useTasksStore = defineStore('tasks', () => {
   })
   const { available, probeError, sources, connections, connectedSources, anyConnected } =
     integration
-  const { descriptorFor, connectionFor, isConnected, probe } = integration
+  const { descriptorFor, connectionFor, isConnected, probe, ensureProbed } = integration
 
   const { items: tasks, upsert: upsertTask } = useUpsertList<SourceTask>({
     key: (t) => `${t.source}:${t.externalId}`,
@@ -224,6 +225,7 @@ export const useTasksStore = defineStore('tasks', () => {
     isConnected,
     tasksForBlock,
     probe,
+    ensureProbed,
     checkSetup,
     connect,
     startLinearOAuth,

package/app/stores/workspace.spec.ts

@@ -112,3 +112,70 @@ describe('workspace store refresh ordering', () => {
     expect(board.getBlock('spawned')).toBeDefined()
   })
 })
+
+// Cold-open waterfall flattening (app-startup initiative, item 8): `init()` fetches the persisted
+// board's snapshot SPECULATIVELY, in parallel with the workspace list, instead of waiting for the
+// list to resolve before the (heaviest) snapshot fetch. These pin that (a) a still-valid persisted
+// board is opened with EXACTLY ONE snapshot fetch — the reused speculative one — and (b) a stale
+// persisted id falls back cleanly, discarding the speculative result.
+describe('workspace store cold-open speculative snapshot', () => {
+  beforeEach(() => {
+    // A working accounts store (the inert stub returns non-promises, which init's `.catch` chain +
+    // `accountWorkspaces` can't use). Auth off ⇒ all boards are in scope.
+    vi.stubGlobal('useAccountsStore', () => ({
+      load: async () => {},
+      enabled: false,
+      activeAccountId: null,
+    }))
+  })
+
+  it('reuses the speculative persisted snapshot — one getWorkspace on a cold open', async () => {
+    const getWorkspace = vi.fn().mockResolvedValue(snapshot('ws1', [block('f1')]))
+    const listWorkspaces = vi.fn().mockResolvedValue([{ id: 'ws1', name: 'ws1', accountId: null }])
+    vi.stubGlobal('useApi', () => ({ getWorkspace, listWorkspaces }))
+
+    const ws = useWorkspaceStore()
+    ws.workspaceId = 'ws1' // the persisted board (read from localStorage on a real cold open)
+    await ws.init()
+
+    // The persisted board's snapshot was fetched exactly once (speculatively) and REUSED —
+    // resolveActiveBoard did not fetch it a second time.
+    expect(listWorkspaces).toHaveBeenCalledTimes(1)
+    expect(getWorkspace).toHaveBeenCalledTimes(1)
+    expect(getWorkspace).toHaveBeenCalledWith('ws1')
+    expect(useBoardStore().getBlock('f1')).toBeDefined()
+  })
+
+  it('falls back to the first board when the persisted id is gone', async () => {
+    const getWorkspace = vi.fn(async (id: string) => {
+      if (id === 'gone') throw new Error('404') // the speculative fetch for a removed board rejects
+      return snapshot(id, [block('f2')])
+    })
+    const listWorkspaces = vi.fn().mockResolvedValue([{ id: 'ws2', name: 'ws2', accountId: null }])
+    vi.stubGlobal('useApi', () => ({ getWorkspace, listWorkspaces }))
+
+    const ws = useWorkspaceStore()
+    ws.workspaceId = 'gone'
+    await ws.init()
+
+    // The rejected speculative fetch didn't wedge init; it fell back to the one board in scope.
+    expect(getWorkspace).toHaveBeenNthCalledWith(1, 'gone')
+    expect(getWorkspace).toHaveBeenCalledWith('ws2')
+    expect(ws.workspaceId).toBe('ws2')
+    expect(useBoardStore().getBlock('f2')).toBeDefined()
+  })
+
+  it('no persisted board: no speculative fetch, opens the first board', async () => {
+    const getWorkspace = vi.fn().mockResolvedValue(snapshot('ws3', [block('f3')]))
+    const listWorkspaces = vi.fn().mockResolvedValue([{ id: 'ws3', name: 'ws3', accountId: null }])
+    vi.stubGlobal('useApi', () => ({ getWorkspace, listWorkspaces }))
+
+    const ws = useWorkspaceStore()
+    ws.workspaceId = null
+    await ws.init()
+
+    expect(getWorkspace).toHaveBeenCalledTimes(1)
+    expect(getWorkspace).toHaveBeenCalledWith('ws3')
+    expect(useBoardStore().getBlock('f3')).toBeDefined()
+  })
+})

package/app/stores/workspace.ts

@@ -32,6 +32,7 @@ import { useConsensusStore } from '~/stores/consensus'
 import { useGitHubStore } from '~/stores/github'
 import { useFragmentsStore } from '~/stores/fragments'
 import { useProviderConnectionsStore } from '~/stores/providerConnections'
+import { markBoot } from '~/utils/bootMarks'
 
 /**
  * Owns the active workspace and bootstraps the app against the backend. On load
@@ -159,6 +160,17 @@ export const useWorkspaceStore = defineStore(
       ready.value = false
       error.value = null
       try {
+        // Cold-open waterfall flattening (app-startup initiative, item 8): the persisted board is
+        // usually known from localStorage BEFORE any request fires, and its snapshot is the app's
+        // heaviest payload (the ~18-read aggregate). Fetch it SPECULATIVELY in parallel with the
+        // workspace list + accounts instead of waiting for the list to resolve first — one fewer
+        // sequential round trip on the critical path. Validated for membership in
+        // resolveActiveBoard; a stale/removed persisted id just discards the speculative result and
+        // falls back to today's path. `.catch` keeps a gone-board 404 from rejecting the whole init.
+        const persistedId = workspaceId.value
+        const speculativeSnapshot = persistedId
+          ? api.getWorkspace(persistedId).catch(() => null)
+          : null
         // Accounts (an auth concept — empty in dev, which leaves boards unscoped) and the
         // workspace list are independent, so fetch them concurrently. resolveActiveBoard
         // needs both, so it still runs after.
@@ -168,25 +180,38 @@ export const useWorkspaceStore = defineStore(
             .catch(() => {}),
           api.listWorkspaces(),
         ])
+        markBoot('workspaces-listed')
         workspaces.value = workspaceList
-        await resolveActiveBoard()
+        await resolveActiveBoard(await speculativeSnapshot)
+        markBoot('snapshot-hydrated')
         ready.value = true
       } catch (e) {
         error.value = e instanceof Error ? e.message : 'Failed to reach the backend.'
       }
     }
 
-    /** Open the persisted board (aligning the active account to it), else pick/create one. */
-    async function resolveActiveBoard() {
+    /**
+     * Open the persisted board (aligning the active account to it), else pick/create one.
+     *
+     * `prefetched` is the speculatively-fetched snapshot for the persisted board (see {@link init}):
+     * when it's for the SAME still-valid board we reuse it instead of re-fetching, so the cold open
+     * pays exactly one snapshot fetch — overlapped with the workspace list rather than after it.
+     */
+    async function resolveActiveBoard(prefetched?: WorkspaceSnapshot | null) {
       const accounts = useAccountsStore()
       if (workspaceId.value) {
         const existing = workspaces.value.find((w) => w.id === workspaceId.value)
         if (existing) {
           if (accounts.enabled && existing.accountId) accounts.activeAccountId = existing.accountId
-          hydrate(await api.getWorkspace(existing.id))
+          hydrate(
+            prefetched && prefetched.workspace.id === existing.id
+              ? prefetched
+              : await api.getWorkspace(existing.id),
+          )
           return
         }
-        // Persisted board is gone (deleted, or now another tenant's) — fall through.
+        // Persisted board is gone (deleted, or now another tenant's) — fall through (and discard the
+        // now-irrelevant speculative snapshot).
         workspaceId.value = null
       }
       const first = accountWorkspaces.value[0]

package/app/utils/bootMarks.ts

@@ -0,0 +1,49 @@
+/**
+ * Cold-open instrumentation (app-startup initiative, item 1). The SPA is `ssr: false`, so the whole
+ * "launch → usable board" path runs client-side after the bundle loads, and nothing timed the
+ * milestones along it. `markBoot` drops a `performance.mark` at each one plus `performance.measure`s
+ * so the cold-open waterfall is visible in a Playwright/browser trace:
+ *   - one `cat-factory:open→<milestone>` measure = absolute ms from navigation start to the milestone,
+ *   - one `cat-factory:<prev>→<milestone>` measure = the segment since the previous milestone.
+ *
+ * Milestones (fired once per cold open): `auth-ready` → `workspaces-listed` → `snapshot-hydrated`
+ * → `stream-connected`. It is pure instrumentation — no behaviour depends on it — and it is a no-op
+ * where the User Timing API is unavailable (SSR/prerender, ancient engines), so callers never guard.
+ */
+
+const PREFIX = 'cat-factory'
+
+/** Milestones already stamped this session — cold-open marks fire ONCE (later switches don't re-time). */
+const seen = new Set<string>()
+/** The previous milestone's mark name, so each call can measure the segment since it. */
+let previousMark: string | null = null
+
+export function markBoot(milestone: string): void {
+  if (seen.has(milestone)) return
+  if (typeof performance === 'undefined' || typeof performance.mark !== 'function') return
+  seen.add(milestone)
+  const mark = `${PREFIX}:${milestone}`
+  const prev = previousMark
+  try {
+    performance.mark(mark)
+  } catch {
+    return
+  }
+  // Advance the chain as soon as the mark itself lands, INDEPENDENT of the derived measures below.
+  // Some engines reject the numeric-`start` measure form; if that throws we still want the NEXT
+  // milestone to measure its segment from THIS mark rather than a stale earlier one.
+  previousMark = mark
+  try {
+    // Absolute time from navigation start (DOMHighResTimeStamp 0 = timeOrigin) to this milestone.
+    performance.measure(`${PREFIX}:open→${milestone}`, { start: 0, end: mark })
+    // The segment since the previous milestone — the waterfall bar.
+    if (prev) {
+      performance.measure(`${PREFIX}:${prev.slice(PREFIX.length + 1)}→${milestone}`, {
+        start: prev,
+        end: mark,
+      })
+    }
+  } catch {
+    // Derived measures unsupported on this engine; the marks still land, so the trace is usable.
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.116.6",
+  "version": "0.116.7",
   "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",