@cat-factory/app 0.196.1 → 0.197.0

package/app/stores/requirements/recommendations.ts

@@ -0,0 +1,77 @@
+import type { Ref } from 'vue'
+import type { RequestRecommendationItem, RequirementReview } from '~/types/requirements'
+
+/**
+ * Shared state + injected dependencies the recommendation slice closes over. Created once in the
+ * `requirements` store setup and threaded into {@link createRecommendationCommands} so the split
+ * operations stay behaviourally identical to the original single-closure store — a size-only
+ * extraction, not a new seam.
+ */
+export interface RecommendationCommandContext {
+  api: ReturnType<typeof useApi>
+  workspace: ReturnType<typeof useWorkspaceStore>
+  /** Block ids whose Requirement Writer is currently producing recommendations. */
+  recommending: Ref<Set<string>>
+  /** Toggle a block/review id in one of the store's flag sets. */
+  withFlag: (set: Ref<Set<string>>, key: string, on: boolean) => void
+  /** Commit a server-returned review into the cache. */
+  store: (review: RequirementReview) => void
+  /** Whether a `pending` recommendation placeholder still exists for the block (server-derived). */
+  hasPendingRecommendations: (blockId: string) => boolean
+}
+
+/** Ask for, accept, reject and re-request the Requirement Writer's suggested answers. */
+export function createRecommendationCommands(ctx: RecommendationCommandContext) {
+  const { api, workspace, recommending, withFlag, store, hasPendingRecommendations } = ctx
+
+  function isRecommending(blockId: string): boolean {
+    return recommending.value.has(blockId) || hasPendingRecommendations(blockId)
+  }
+
+  /**
+   * Ask the Requirement Writer to recommend answers for a batch of findings. Each item carries
+   * its finding id plus optional per-finding guidance (the note the human typed before choosing
+   * "recommend something"). ASYNCHRONOUS: returns at once with `pending` placeholder
+   * recommendations (the Writer runs per finding in the durable driver), which fill in (`ready`)
+   * via live `requirements` stream events; a notification calls the user back when the batch is
+   * ready. The board shows the `recommending` background stage while any placeholder is pending.
+   */
+  async function requestRecommendations(blockId: string, items: RequestRecommendationItem[]) {
+    withFlag(recommending, blockId, true)
+    try {
+      const updated = await api.requestRecommendations(workspace.requireId(), blockId, items)
+      if (updated) store(updated)
+      return updated
+    } finally {
+      withFlag(recommending, blockId, false)
+    }
+  }
+
+  /** Accept a recommendation (becomes the finding's answer, folded into the next incorporation). */
+  async function acceptRecommendation(review: RequirementReview, recId: string) {
+    store(await api.acceptRecommendation(workspace.requireId(), review.id, recId))
+  }
+
+  /** Reject a recommendation (the human then dismisses / answers manually / re-requests). */
+  async function rejectRecommendation(review: RequirementReview, recId: string) {
+    store(await api.rejectRecommendation(workspace.requireId(), review.id, recId))
+  }
+
+  /** Re-request a recommendation with a "do it differently" note. */
+  async function reRequestRecommendation(review: RequirementReview, recId: string, note: string) {
+    withFlag(recommending, review.blockId, true)
+    try {
+      store(await api.reRequestRecommendation(workspace.requireId(), review.id, recId, note))
+    } finally {
+      withFlag(recommending, review.blockId, false)
+    }
+  }
+
+  return {
+    isRecommending,
+    requestRecommendations,
+    acceptRecommendation,
+    rejectRecommendation,
+    reRequestRecommendation,
+  }
+}

package/app/stores/requirements.ts

@@ -1,12 +1,12 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 import type {
-  RequestRecommendationItem,
   RequirementReview,
   ResolveRequirementsExceededChoice,
   ReviewItemStatus,
 } from '~/types/requirements'
 import { useWorkspaceStore } from '~/stores/workspace'
+import { createRecommendationCommands } from '~/stores/requirements/recommendations'
 
 /**
  * Requirements-review state. On the pipeline path the reviewer runs as the first gate
@@ -204,48 +204,22 @@ export const useRequirementsStore = defineStore('requirements', () => {
     return updated
   }
 
-  function isRecommending(blockId: string): boolean {
-    return recommending.value.has(blockId) || hasPendingRecommendations(blockId)
-  }
-
-  /**
-   * Ask the Requirement Writer to recommend answers for a batch of findings. Each item carries
-   * its finding id plus optional per-finding guidance (the note the human typed before choosing
-   * "recommend something"). ASYNCHRONOUS: returns at once with `pending` placeholder
-   * recommendations (the Writer runs per finding in the durable driver), which fill in (`ready`)
-   * via live `requirements` stream events; a notification calls the user back when the batch is
-   * ready. The board shows the `recommending` background stage while any placeholder is pending.
-   */
-  async function requestRecommendations(blockId: string, items: RequestRecommendationItem[]) {
-    withFlag(recommending, blockId, true)
-    try {
-      const updated = await api.requestRecommendations(workspace.requireId(), blockId, items)
-      if (updated) store(updated)
-      return updated
-    } finally {
-      withFlag(recommending, blockId, false)
-    }
-  }
-
-  /** Accept a recommendation (becomes the finding's answer, folded into the next incorporation). */
-  async function acceptRecommendation(review: RequirementReview, recId: string) {
-    store(await api.acceptRecommendation(workspace.requireId(), review.id, recId))
-  }
-
-  /** Reject a recommendation (the human then dismisses / answers manually / re-requests). */
-  async function rejectRecommendation(review: RequirementReview, recId: string) {
-    store(await api.rejectRecommendation(workspace.requireId(), review.id, recId))
-  }
-
-  /** Re-request a recommendation with a "do it differently" note. */
-  async function reRequestRecommendation(review: RequirementReview, recId: string, note: string) {
-    withFlag(recommending, review.blockId, true)
-    try {
-      store(await api.reRequestRecommendation(workspace.requireId(), review.id, recId, note))
-    } finally {
-      withFlag(recommending, review.blockId, false)
-    }
-  }
+  // The Requirement Writer recommendation slice (request / accept / reject / re-request),
+  // extracted into a cohesive factory over the state above — a size-only split.
+  const {
+    isRecommending,
+    requestRecommendations,
+    acceptRecommendation,
+    rejectRecommendation,
+    reRequestRecommendation,
+  } = createRecommendationCommands({
+    api,
+    workspace,
+    recommending,
+    withFlag,
+    store,
+    hasPendingRecommendations,
+  })
 
   /** Resolve a capped review: extra-round / proceed / stop-reset. */
   async function resolveExceeded(

package/app/stores/tutorial.spec.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest'
+import { useTutorialStore } from '~/stores/tutorial'
+
+describe('useTutorialStore launch prompt', () => {
+  it('offers the tutorial on launch while no decision was ever saved', () => {
+    const tutorial = useTutorialStore()
+    expect(tutorial.decision).toBeNull()
+    tutorial.maybeOfferOnLaunch()
+    expect(tutorial.promptOpen).toBe(true)
+  })
+
+  it('auto-opens at most once per session', () => {
+    const tutorial = useTutorialStore()
+    tutorial.maybeOfferOnLaunch()
+    tutorial.closePrompt()
+    // The advisory watcher re-fires whenever another modal closes; the guard must hold.
+    tutorial.maybeOfferOnLaunch()
+    expect(tutorial.promptOpen).toBe(false)
+  })
+
+  it('closing without answering saves nothing, so the next launch asks again', () => {
+    const tutorial = useTutorialStore()
+    tutorial.maybeOfferOnLaunch()
+    tutorial.closePrompt()
+    expect(tutorial.decision).toBeNull()
+  })
+
+  it('declining is saved and stops the launch offer for good', () => {
+    const tutorial = useTutorialStore()
+    tutorial.maybeOfferOnLaunch()
+    tutorial.decline()
+    expect(tutorial.decision).toBe('declined')
+    expect(tutorial.promptOpen).toBe(false)
+    // A fresh session (new auto-open guard) still must not offer: decision wins.
+    tutorial.promptAutoOpened = false
+    tutorial.maybeOfferOnLaunch()
+    expect(tutorial.promptOpen).toBe(false)
+  })
+
+  it('defers an offer an advisory landed on top of, and re-offers when it clears', () => {
+    const tutorial = useTutorialStore()
+    tutorial.maybeOfferOnLaunch()
+    // A startup advisory opened after the prompt: withdraw rather than stack.
+    tutorial.deferPrompt()
+    expect(tutorial.promptOpen).toBe(false)
+    expect(tutorial.decision).toBeNull()
+    // A deferral is not the user's answer, so it must not consume the session's offer.
+    tutorial.maybeOfferOnLaunch()
+    expect(tutorial.promptOpen).toBe(true)
+  })
+
+  it('never withdraws a prompt the user opened themselves', () => {
+    const tutorial = useTutorialStore()
+    tutorial.openPrompt()
+    tutorial.deferPrompt()
+    expect(tutorial.promptOpen).toBe(true)
+  })
+
+  it('a user-driven open works regardless of a saved decision', () => {
+    const tutorial = useTutorialStore()
+    tutorial.decline()
+    tutorial.openPrompt()
+    expect(tutorial.promptOpen).toBe(true)
+  })
+})
+
+describe('useTutorialStore tours', () => {
+  it('starting a tour records acceptance, closes the prompt, and resets the cursor', () => {
+    const tutorial = useTutorialStore()
+    tutorial.openPrompt()
+    tutorial.startTour('board-basics')
+    expect(tutorial.decision).toBe('accepted')
+    expect(tutorial.promptOpen).toBe(false)
+    expect(tutorial.activeTourId).toBe('board-basics')
+    expect(tutorial.stepIndex).toBe(0)
+    expect(tutorial.touring).toBe(true)
+  })
+
+  it('starting a tour after a decline flips the decision to accepted', () => {
+    // The user changed their mind via the palette; leaving `declined` in place would
+    // misdescribe what happened.
+    const tutorial = useTutorialStore()
+    tutorial.decline()
+    tutorial.startTour('board-basics')
+    expect(tutorial.decision).toBe('accepted')
+  })
+
+  it('the step cursor never goes below zero', () => {
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.setStepIndex(-3)
+    expect(tutorial.stepIndex).toBe(0)
+    tutorial.setStepIndex(4)
+    expect(tutorial.stepIndex).toBe(4)
+  })
+
+  it('skipping (stopTour) abandons the tour without marking it complete', () => {
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.setStepIndex(2)
+    tutorial.stopTour()
+    expect(tutorial.touring).toBe(false)
+    expect(tutorial.stepIndex).toBe(0)
+    expect(tutorial.isCompleted('board-basics')).toBe(false)
+  })
+
+  it('completing records the tour id once, idempotently', () => {
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    expect(tutorial.isCompleted('board-basics')).toBe(true)
+    expect(tutorial.touring).toBe(false)
+
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    expect(tutorial.completedTourIds).toEqual(['board-basics'])
+  })
+
+  it('completing with no active tour records nothing', () => {
+    const tutorial = useTutorialStore()
+    tutorial.completeTour()
+    expect(tutorial.completedTourIds).toEqual([])
+  })
+
+  it('tracks completion per tour id', () => {
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    tutorial.startTour('first-task')
+    tutorial.completeTour()
+    expect(tutorial.completedTourIds).toEqual(['board-basics', 'first-task'])
+    expect(tutorial.isCompleted('first-task')).toBe(true)
+    expect(tutorial.isCompleted('made-up')).toBe(false)
+  })
+})

package/app/stores/tutorial.ts

@@ -0,0 +1,145 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+
+/** The launch-prompt answer. `null` = never answered, so the app asks again next launch. */
+export type TutorialDecision = 'accepted' | 'declined'
+
+/**
+ * The in-app tutorial state: the launch-prompt decision, per-tour completion, and the
+ * live progress of whichever tour is running.
+ *
+ * Two tiers of state, split on purpose:
+ *
+ *  - PERSISTED (`decision`, `completedTourIds`) — the user's explicit answer to "would you
+ *    like a tour?" and which tours they have finished. Browser-persisted like the interface
+ *    tier (`uiMode`): it is a per-person, per-browser preference, and `null` (never asked)
+ *    is a real state distinct from `declined` — only an explicit answer stops the launch
+ *    prompt from returning, while closing it without answering merely defers it to the
+ *    next launch.
+ *  - SESSION-ONLY (`promptOpen`, `activeTourId`, `stepIndex`) — a tour is anchored to live
+ *    DOM, so replaying progress across a reload would point step N at a board that hasn't
+ *    reached that state; a reloaded tour restarts from its beginning instead.
+ *
+ * The store deliberately knows nothing about WHICH tours exist: the catalog lives in the
+ * `tutorialTours` slot (see `modular/tutorial-tours.ts`), so tours ship and evolve — first-
+ * party and consumer-contributed alike — without this store changing. It tracks ids and a
+ * step cursor; the overlay resolves definitions and drives the cursor.
+ */
+export const useTutorialStore = defineStore(
+  'tutorial',
+  () => {
+    /** The saved launch-prompt answer. Written only by an explicit accept/decline/start. */
+    const decision = ref<TutorialDecision | null>(null)
+    /** Ids of tours the user finished (reached the last step's Done), persisted. */
+    const completedTourIds = ref<string[]>([])
+
+    const promptOpen = ref(false)
+    /** Once-per-session guard for the launch auto-open; later opens are user-driven. */
+    const promptAutoOpened = ref(false)
+    const activeTourId = ref<string | null>(null)
+    const stepIndex = ref(0)
+
+    /** A tour is currently running (the overlay mounts off this). */
+    const touring = computed(() => activeTourId.value !== null)
+
+    /**
+     * Auto-open the launch prompt, at most once per session and only while the user has
+     * never answered it. Callers gate on the rest of the launch context (board ready, no
+     * other startup advisory open) — see `pages/index.vue`.
+     */
+    function maybeOfferOnLaunch() {
+      if (decision.value !== null || promptAutoOpened.value) return
+      promptAutoOpened.value = true
+      promptOpen.value = true
+    }
+
+    /** User-driven open (command palette), regardless of any saved decision. */
+    function openPrompt() {
+      promptOpen.value = true
+    }
+
+    /**
+     * Withdraw an offer this store made, because something the user actually has to answer
+     * (a startup advisory, the GitHub onboarding gate) opened on top of it — and re-arm, so
+     * the offer returns once that surface is gone. Distinct from {@link closePrompt}: no
+     * decision is written EITHER way, but a deferral was not the user's doing, so it must
+     * not consume this session's one offer.
+     *
+     * Only ever withdraws the auto-opened prompt; a prompt the user opened themselves from
+     * the palette is theirs to close.
+     */
+    function deferPrompt() {
+      if (!promptAutoOpened.value) return
+      promptOpen.value = false
+      promptAutoOpened.value = false
+    }
+
+    /** Close without answering: no decision is written, so the next launch asks again. */
+    function closePrompt() {
+      promptOpen.value = false
+    }
+
+    /** The explicit "no thanks": saved, so the launch prompt never auto-opens again. */
+    function decline() {
+      decision.value = 'declined'
+      promptOpen.value = false
+    }
+
+    /**
+     * Begin a tour from its first step. Starting one IS accepting the tutorial (also when
+     * launched later from the palette after a decline — the user changed their mind, and
+     * leaving `declined` in place would misdescribe what happened).
+     */
+    function startTour(tourId: string) {
+      decision.value = 'accepted'
+      promptOpen.value = false
+      activeTourId.value = tourId
+      stepIndex.value = 0
+    }
+
+    /** Move the step cursor; the overlay owns bounds/skip logic and never goes below 0. */
+    function setStepIndex(index: number) {
+      stepIndex.value = Math.max(0, index)
+    }
+
+    /** Abandon the running tour without marking it complete (the Skip action). */
+    function stopTour() {
+      activeTourId.value = null
+      stepIndex.value = 0
+    }
+
+    /** Finish the running tour: record completion (idempotent) and clear the cursor. */
+    function completeTour() {
+      const id = activeTourId.value
+      if (id && !completedTourIds.value.includes(id)) {
+        completedTourIds.value = [...completedTourIds.value, id]
+      }
+      stopTour()
+    }
+
+    function isCompleted(tourId: string): boolean {
+      return completedTourIds.value.includes(tourId)
+    }
+
+    return {
+      decision,
+      completedTourIds,
+      promptOpen,
+      promptAutoOpened,
+      activeTourId,
+      stepIndex,
+      touring,
+      maybeOfferOnLaunch,
+      openPrompt,
+      closePrompt,
+      deferPrompt,
+      decline,
+      startTour,
+      setStepIndex,
+      stopTour,
+      completeTour,
+      isCompleted,
+    }
+  },
+  { persist: { pick: ['decision', 'completedTourIds'] } },
+)

package/app/stores/workspace/commands.ts

@@ -0,0 +1,77 @@
+import type { Ref } from 'vue'
+import type { WorkspaceListItem, WorkspaceSnapshot } from '~/types/domain'
+import { useAccountsStore } from '~/stores/accounts'
+
+/**
+ * Shared reactive state + injected dependencies the workspace-store board-CRUD factory closes
+ * over. Created once in the `workspace` store setup and threaded into
+ * {@link createWorkspaceCommands} so the split operations stay behaviourally identical to the
+ * original single-closure store — a size-only extraction mirroring `stores/workspace/hydrate.ts`
+ * and `stores/workspace/infraSetup.ts`, not a new seam.
+ */
+export interface WorkspaceCommandContext {
+  api: ReturnType<typeof useApi>
+  workspaceId: Ref<string | null>
+  workspaces: Ref<WorkspaceListItem[]>
+  hydrate: (snapshot: WorkspaceSnapshot, boardSince?: number) => void
+  /** Open one of the active account's boards, creating one when it has none. */
+  resolveActiveBoard: () => Promise<void>
+}
+
+/** Open / create / rename / delete a board, plus switching the active account. */
+export function createWorkspaceCommands(ctx: WorkspaceCommandContext) {
+  const { api, workspaceId, workspaces, hydrate, resolveActiveBoard } = ctx
+
+  /** Switch to another board (within reach of the active account). */
+  async function switchTo(id: string) {
+    if (id === workspaceId.value) return
+    hydrate(await api.getWorkspace(id))
+  }
+
+  /** Switch the active account, then open one of its boards (creating one if needed). */
+  async function selectAccount(id: string) {
+    const accounts = useAccountsStore()
+    if (id === accounts.activeAccountId) return
+    accounts.switchTo(id)
+    workspaceId.value = null
+    await resolveActiveBoard()
+  }
+
+  /** Create a new board in the active account and open it. */
+  async function create(name?: string, description?: string) {
+    const accounts = useAccountsStore()
+    const snapshot = await api.createWorkspace({
+      seed: false,
+      name,
+      description,
+      accountId: accounts.activeAccountId ?? undefined,
+    })
+    hydrate(snapshot)
+    return snapshot.workspace
+  }
+
+  /** Rename a board and/or update its description. */
+  async function update(id: string, patch: { name?: string; description?: string | null }) {
+    const updated = await api.updateWorkspace(id, patch)
+    const i = workspaces.value.findIndex((w) => w.id === id)
+    if (i >= 0) workspaces.value[i] = updated
+    return updated
+  }
+
+  /** Rename a board (kept for the existing rename callers). */
+  async function rename(id: string, name: string) {
+    return update(id, { name })
+  }
+
+  /** Delete a board; if it was active, fall back to another in the account. */
+  async function remove(id: string) {
+    await api.deleteWorkspace(id)
+    workspaces.value = workspaces.value.filter((w) => w.id !== id)
+    if (workspaceId.value === id) {
+      workspaceId.value = null
+      await resolveActiveBoard()
+    }
+  }
+
+  return { switchTo, selectAccount, create, update, rename, remove }
+}

package/app/stores/workspace.ts

@@ -10,6 +10,7 @@ import type {
 import { useAccountsStore } from '~/stores/accounts'
 import { useBoardStore } from '~/stores/board'
 import { applySnapshotToStores, resetPerBoardCaches } from '~/stores/workspace/hydrate'
+import { createWorkspaceCommands } from '~/stores/workspace/commands'
 import { createInfraSetupState } from '~/stores/workspace/infraSetup'
 import { markBoot } from '~/utils/bootMarks'
 import { retryWhileBackendUnreachable } from '~/utils/backendReady'
@@ -184,56 +185,16 @@ export const useWorkspaceStore = defineStore(
       }
     }
 
-    /** Switch to another board (within reach of the active account). */
-    async function switchTo(id: string) {
-      if (id === workspaceId.value) return
-      hydrate(await api.getWorkspace(id))
-    }
-
-    /** Switch the active account, then open one of its boards (creating one if needed). */
-    async function selectAccount(id: string) {
-      const accounts = useAccountsStore()
-      if (id === accounts.activeAccountId) return
-      accounts.switchTo(id)
-      workspaceId.value = null
-      await resolveActiveBoard()
-    }
-
-    /** Create a new board in the active account and open it. */
-    async function create(name?: string, description?: string) {
-      const accounts = useAccountsStore()
-      const snapshot = await api.createWorkspace({
-        seed: false,
-        name,
-        description,
-        accountId: accounts.activeAccountId ?? undefined,
-      })
-      hydrate(snapshot)
-      return snapshot.workspace
-    }
-
-    /** Rename a board and/or update its description. */
-    async function update(id: string, patch: { name?: string; description?: string | null }) {
-      const updated = await api.updateWorkspace(id, patch)
-      const i = workspaces.value.findIndex((w) => w.id === id)
-      if (i >= 0) workspaces.value[i] = updated
-      return updated
-    }
-
-    /** Rename a board (kept for the existing rename callers). */
-    async function rename(id: string, name: string) {
-      return update(id, { name })
-    }
-
-    /** Delete a board; if it was active, fall back to another in the account. */
-    async function remove(id: string) {
-      await api.deleteWorkspace(id)
-      workspaces.value = workspaces.value.filter((w) => w.id !== id)
-      if (workspaceId.value === id) {
-        workspaceId.value = null
-        await resolveActiveBoard()
-      }
-    }
+    // Board CRUD (open / create / rename / delete) + the account switch, extracted into a
+    // cohesive factory over the state above — a size-only split mirroring `hydrate.ts` and
+    // `infraSetup.ts`.
+    const { switchTo, selectAccount, create, update, rename, remove } = createWorkspaceCommands({
+      api,
+      workspaceId,
+      workspaces,
+      hydrate,
+      resolveActiveBoard,
+    })
 
     // Monotonic guard for {@link refresh}: `board`-type stream events (and the on-connect resync)
     // each fire a full-snapshot refresh, and {@link hydrate} REPLACES the block list. Without

package/app/utils/tutorial.spec.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import { computeCoachMarkLayout, sortTours } from '~/utils/tutorial'
+import type { TutorialTour } from '~/utils/tutorial'
+
+const tour = (id: string, order: number): TutorialTour => ({
+  id,
+  order,
+  titleKey: `tutorial.tours.${id}.title`,
+  descriptionKey: `tutorial.tours.${id}.description`,
+  steps: [],
+})
+
+describe('sortTours', () => {
+  it('orders by `order`, breaking ties on id, without mutating the input', () => {
+    const input = [tour('c', 20), tour('b', 10), tour('a', 20)]
+    const sorted = sortTours(input)
+    expect(sorted.map((t) => t.id)).toEqual(['b', 'a', 'c'])
+    expect(input.map((t) => t.id)).toEqual(['c', 'b', 'a'])
+  })
+})
+
+const viewport = { width: 1000, height: 800 }
+const tooltip = { width: 300, height: 150 }
+
+describe('computeCoachMarkLayout', () => {
+  it('centers when there is no anchor (intro / wrap-up steps)', () => {
+    const layout = computeCoachMarkLayout(null, tooltip, viewport)
+    expect(layout.placement).toBe('center')
+    expect(layout.left).toBe((1000 - 300) / 2)
+    expect(layout.top).toBe((800 - 150) / 2)
+  })
+
+  it('honours a preferred side that fits', () => {
+    const target = { top: 400, left: 500, width: 100, height: 40 }
+    const layout = computeCoachMarkLayout(target, tooltip, viewport, 'top')
+    expect(layout.placement).toBe('top')
+    expect(layout.top).toBe(400 - 12 - 150)
+    // Cross-axis centered on the anchor.
+    expect(layout.left).toBe(500 + 50 - 150)
+  })
+
+  it('falls back when the preferred side has no room', () => {
+    // Anchor at the very top: 'top' can't fit a 150px card, so bottom wins.
+    const target = { top: 10, left: 500, width: 100, height: 40 }
+    const layout = computeCoachMarkLayout(target, tooltip, viewport, 'top')
+    expect(layout.placement).toBe('bottom')
+    expect(layout.top).toBe(10 + 40 + 12)
+  })
+
+  it('clamps the cross-axis to the viewport instead of overflowing', () => {
+    // Anchor hugging the left edge: centering would push the card off-screen.
+    const target = { top: 400, left: 0, width: 40, height: 40 }
+    const layout = computeCoachMarkLayout(target, tooltip, viewport, 'bottom')
+    expect(layout.placement).toBe('bottom')
+    expect(layout.left).toBe(8)
+  })
+
+  it('degrades to a clamped bottom position when no side fits at all', () => {
+    // A viewport smaller than the card in every direction around the anchor.
+    const tinyViewport = { width: 320, height: 200 }
+    const target = { top: 80, left: 100, width: 120, height: 40 }
+    const layout = computeCoachMarkLayout(target, tooltip, tinyViewport, 'right')
+    expect(layout.placement).toBe('bottom')
+    // Clamped inside the viewport: overlap beats disappearing off-screen.
+    expect(layout.top).toBe(200 - 150 - 8)
+    expect(layout.left).toBe(10)
+  })
+})