@cat-factory/app 0.213.1 → 0.215.0

package/app/stores/tutorial.record.ts

@@ -0,0 +1,191 @@
+import { ref } from 'vue'
+
+/** The launch-prompt answer. `null` = never answered, so the app asks again next launch. */
+export type TutorialDecision = 'accepted' | 'declined'
+
+/** The server's copy of a user's record, as the snapshot delivers it. */
+export interface RemoteTutorialRecord {
+  decision: TutorialDecision | null
+  completedTourIds: readonly string[]
+  nudgedTourIds: readonly string[]
+}
+
+/**
+ * The PERSISTED tier of the tutorial's state: the standing record of what this PERSON has done.
+ *
+ * Extracted from `stores/tutorial.ts` along the boundary that store's own docblock already draws.
+ * Everything here outlives a visit and is mirrored to the signed-in user's server row; everything
+ * left behind (the prompt, the catalogue, the step cursor, the resume point, which offer is on
+ * screen) is session state that a reload is right to discard. Splitting on that line also put every
+ * piece of the sync story in one module: the union rule, what counts as "this browser knows more",
+ * and the flag the mirror acts on.
+ *
+ * A factory rather than a second Pinia store, because the two tiers are one store's worth of state
+ * to every consumer: the returned refs go straight into the setup store's state, so
+ * `persist: { pick: [...] }` and every existing `tutorial.completedTourIds` read are unchanged.
+ */
+export function createTutorialRecord() {
+  /** The saved launch-prompt answer. Written only by an explicit accept/decline/reset. */
+  const decision = ref<TutorialDecision | null>(null)
+  /** Ids of tours the user finished (reached the last step's Done). */
+  const completedTourIds = ref<string[]>([])
+  /**
+   * Ids the CONTEXTUAL offer has already been spent on (see `newlyAvailableTour`). Persisted beside
+   * the completions, because "we have mentioned this once" is a fact about the person, not about
+   * this visit: re-offering the parked-run walkthrough on every reload is a nag, and the gates it
+   * watches flip several times per run.
+   */
+  const nudgedTourIds = ref<string[]>([])
+  /**
+   * This browser holds progress the server row does not, so the mirror owes it a write.
+   *
+   * Session-lived and a FLAG rather than a direct call, because the merge below runs inside the
+   * snapshot fan-out, which is synchronous and store-only. `useTutorialSync` watches it.
+   */
+  const serverPushNeeded = ref(false)
+  /**
+   * Counts LOCAL changes to this record, and nothing else. Session-lived.
+   *
+   * The mirror watches this rather than the state itself, and the distinction is the whole reason
+   * it exists: adopting the server's ids in {@link mergeServerProgress} also changes the state, so
+   * a watcher over the state pushes the server's own row straight back at it on every fresh-browser
+   * board load. Counting only what the USER did means a write happens exactly when this browser has
+   * something to say.
+   */
+  const localRev = ref(0)
+  /**
+   * The local `decision` has changed and has not been mirrored yet, so it must survive a snapshot.
+   *
+   * Without this, a failed mirror write silently UNDOES the user's answer: they click "No thanks",
+   * the push fails, and the next snapshot re-adopts the older `accepted` from the server row,
+   * re-arming every contextual offer they just declined. The server row wins on `decision` because
+   * it is the shared record of the latest answer, but only where this browser is not itself holding
+   * a newer one that the server has not seen.
+   */
+  const decisionDirty = ref(false)
+
+  const isCompleted = (tourId: string) => completedTourIds.value.includes(tourId)
+  const wasNudged = (tourId: string) => nudgedTourIds.value.includes(tourId)
+
+  /** Record a finished walkthrough. Idempotent: the same tour taken twice is still one entry. */
+  function markCompleted(tourId: string) {
+    if (isCompleted(tourId)) return
+    completedTourIds.value = [...completedTourIds.value, tourId]
+    localRev.value += 1
+  }
+
+  /** Spend the contextual offer for a tour. Idempotent, so an offer can never be made twice. */
+  function markNudged(tourId: string) {
+    if (wasNudged(tourId)) return
+    nudgedTourIds.value = [...nudgedTourIds.value, tourId]
+    localRev.value += 1
+  }
+
+  /** Record an answer to the launch prompt, and ask the mirror to carry it. */
+  function answer(next: TutorialDecision) {
+    if (decision.value === next) return
+    decision.value = next
+    decisionDirty.value = true
+    localRev.value += 1
+  }
+
+  /** Starting a tour IS accepting the tutorial, however the user got there. */
+  function acceptOffer() {
+    answer('accepted')
+  }
+
+  /** The explicit "no thanks": saved, so the launch prompt never auto-opens again. */
+  function declineOffer() {
+    answer('declined')
+  }
+
+  /**
+   * Fold the signed-in user's SERVER copy into this browser's, and report whether the local copy
+   * held anything the server did not.
+   *
+   * A union rather than a replace, in the same direction and for the same reason the server merges:
+   * both lists are grow-only sets of things that HAPPENED, so neither side is ever right to un-say
+   * one. A replace here would lose a tour finished while the mirror write was failing; a replace on
+   * the server would lose a tour finished on another machine. `decision` is taken from the server
+   * when it HAS one and this browser is not holding an un-mirrored answer of its own
+   * ({@link decisionDirty}), because it is a preference someone re-answers rather than an
+   * accumulating fact — while a server row with no answer is not evidence that the local answer
+   * never happened.
+   *
+   * The return value closes the loop: `true` means this browser knows something the server does not,
+   * so the merged state is worth pushing back. Recomputing that comparison at the call site would be
+   * a second copy of the union rule. It is also what makes the server's un-guarded merge safe: the
+   * PUT's response goes through here too, so a merge that lost a concurrent writer's ids comes back
+   * missing something local, and the re-push is automatic rather than hoped for.
+   */
+  function mergeServerProgress(remote: RemoteTutorialRecord | null): boolean {
+    // No server copy at all (no accounts, no store wired, or the read degraded) is NOT a reason to
+    // push: there is nothing to reconcile against, and treating an absent row as an empty one would
+    // make every such board load write a mirror nothing reads.
+    if (!remote) return false
+    const union = (mine: string[], theirs: readonly string[]) => [...new Set([...theirs, ...mine])]
+    const completed = union(completedTourIds.value, remote.completedTourIds)
+    const nudged = union(nudgedTourIds.value, remote.nudgedTourIds)
+    const keepLocalDecision = decisionDirty.value || remote.decision === null
+    const localOnly =
+      completed.length > remote.completedTourIds.length ||
+      nudged.length > remote.nudgedTourIds.length ||
+      (keepLocalDecision && decision.value !== remote.decision)
+    completedTourIds.value = completed
+    nudgedTourIds.value = nudged
+    if (!keepLocalDecision) decision.value = remote.decision
+    if (localOnly) serverPushNeeded.value = true
+    return localOnly
+  }
+
+  /**
+   * The mirror has caught up: this browser's state is on the server, including its answer.
+   *
+   * Called BEFORE the response is reconciled, so that a response missing something local can flip
+   * {@link serverPushNeeded} back on and re-trigger the watcher. Clearing it after would look
+   * identical and would swallow exactly the retry that matters.
+   */
+  function markServerPushed() {
+    serverPushNeeded.value = false
+    decisionDirty.value = false
+  }
+
+  /**
+   * Forget the whole record, including the answered offer.
+   *
+   * The decision goes with it deliberately: "Reset" is asked for by someone handing the app to a
+   * colleague, demoing it, or re-walking the product after it changed, and every one of those wants
+   * the first-launch experience back, which a cleared completion list alone does not restore. The
+   * spent contextual offers go too, or a board that has already run something would never make
+   * those offers again to the colleague the app was just handed to.
+   *
+   * Deliberately does NOT bump {@link localRev}, and cancels any pending mirror write. The server
+   * side of a reset is a DELETE, and a PUT of the freshly-emptied state racing it would re-create
+   * the row the DELETE just removed — leaving "reset it" distinguishable from "never touched the
+   * tutorial", which is the one thing the reset has to get right.
+   */
+  function reset() {
+    completedTourIds.value = []
+    nudgedTourIds.value = []
+    decision.value = null
+    serverPushNeeded.value = false
+    decisionDirty.value = false
+  }
+
+  return {
+    decision,
+    completedTourIds,
+    nudgedTourIds,
+    serverPushNeeded,
+    localRev,
+    isCompleted,
+    wasNudged,
+    markCompleted,
+    markNudged,
+    acceptOffer,
+    declineOffer,
+    mergeServerProgress,
+    markServerPushed,
+    reset,
+  }
+}

package/app/stores/tutorial.spec.ts

@@ -121,10 +121,16 @@ describe('useTutorialStore catalogue', () => {
     tutorial.setStepIndex(2)
     tutorial.stopTour()
 
+    tutorial.offerNudge('answer-park')
     tutorial.resetProgress()
     expect(tutorial.completedTourIds).toEqual([])
     expect(tutorial.interruptedAt('run-task')).toBeNull()
     expect(tutorial.decision).toBeNull()
+    // The spent contextual offers go too, or a board that has already run something would
+    // never make them again to the colleague the app was just handed to.
+    expect(tutorial.nudgedTourIds).toEqual([])
+    expect(tutorial.pendingNudgeId).toBeNull()
+    expect(tutorial.wasNudged('answer-park')).toBe(false)
   })
 
   it('leaves a running tour alone when progress is reset', () => {
@@ -300,3 +306,204 @@ describe('useTutorialStore resuming a broken-off tour', () => {
     expect(tutorial.interruptedAt('gone-away')).toBeNull()
   })
 })
+
+describe('useTutorialStore contextual offer', () => {
+  it('raises the offer and spends the id in one act', () => {
+    // The guard against re-offering is the PERSISTED list, not the visible state, so an offer
+    // cannot be made twice however many times the live gates flip.
+    const tutorial = useTutorialStore()
+    tutorial.offerNudge('answer-park')
+    expect(tutorial.pendingNudgeId).toBe('answer-park')
+    expect(tutorial.wasNudged('answer-park')).toBe(true)
+  })
+
+  it('never re-raises an offer already spent, even once dismissed', () => {
+    const tutorial = useTutorialStore()
+    tutorial.offerNudge('answer-park')
+    tutorial.dismissNudge()
+    expect(tutorial.pendingNudgeId).toBeNull()
+    tutorial.offerNudge('answer-park')
+    expect(tutorial.pendingNudgeId).toBeNull()
+    expect(tutorial.nudgedTourIds).toEqual(['answer-park'])
+  })
+
+  it('holds one offer at a time, keeping the newer arrival', () => {
+    const tutorial = useTutorialStore()
+    tutorial.offerNudge('answer-park')
+    tutorial.offerNudge('diagnose-failure')
+    expect(tutorial.pendingNudgeId).toBe('diagnose-failure')
+    expect(tutorial.nudgedTourIds).toEqual(['answer-park', 'diagnose-failure'])
+  })
+})
+
+describe('useTutorialStore server reconciliation', () => {
+  it('unions the server copy into the local one, keeping what only this browser knew', () => {
+    // Both lists are grow-only sets of things that HAPPENED, so neither side may un-say one. A
+    // replace here loses a tour finished while the mirror write was failing.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    const pushNeeded = tutorial.mergeServerProgress({
+      decision: 'accepted',
+      completedTourIds: ['first-task'],
+      nudgedTourIds: [],
+    })
+    expect(tutorial.completedTourIds).toEqual(['first-task', 'board-basics'])
+    // This browser held something the server did not, so the mirror owes it a write.
+    expect(pushNeeded).toBe(true)
+    expect(tutorial.serverPushNeeded).toBe(true)
+  })
+
+  it('asks for no push when the server copy is already a superset', () => {
+    // The ordinary reload. Writing anyway would mean every board load posted a mirror nobody reads.
+    const tutorial = useTutorialStore()
+    expect(
+      tutorial.mergeServerProgress({
+        decision: 'accepted',
+        completedTourIds: ['board-basics'],
+        nudgedTourIds: ['answer-park'],
+      }),
+    ).toBe(false)
+    expect(tutorial.completedTourIds).toEqual(['board-basics'])
+    expect(tutorial.serverPushNeeded).toBe(false)
+  })
+
+  it('never duplicates an id both sides already hold', () => {
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    tutorial.mergeServerProgress({
+      decision: null,
+      completedTourIds: ['board-basics'],
+      nudgedTourIds: [],
+    })
+    expect(tutorial.completedTourIds).toEqual(['board-basics'])
+  })
+
+  it('takes the server decision, but never clears a local one with an absent row', () => {
+    // The decision is a preference someone re-answers, so the shared record wins when it has an
+    // answer. A server row with no answer is not evidence that the local answer never happened.
+    const tutorial = useTutorialStore()
+    tutorial.decline()
+    tutorial.markServerPushed()
+    tutorial.mergeServerProgress({
+      decision: null,
+      completedTourIds: [],
+      nudgedTourIds: [],
+    })
+    expect(tutorial.decision).toBe('declined')
+    expect(tutorial.serverPushNeeded).toBe(true)
+
+    tutorial.markServerPushed()
+    tutorial.mergeServerProgress({
+      decision: 'accepted',
+      completedTourIds: [],
+      nudgedTourIds: [],
+    })
+    expect(tutorial.decision).toBe('accepted')
+  })
+
+  it('holds an UN-MIRRORED local answer against the server, so a failed push cannot undo it', () => {
+    // The mirror is best-effort, so a decline can be sitting in this browser and nowhere else. If
+    // the snapshot re-adopted the older server answer, "No thanks" would silently come back as
+    // "accepted" and every contextual offer the user just declined would re-arm.
+    const tutorial = useTutorialStore()
+    tutorial.decline()
+    expect(
+      tutorial.mergeServerProgress({
+        decision: 'accepted',
+        completedTourIds: [],
+        nudgedTourIds: [],
+      }),
+    ).toBe(true)
+    expect(tutorial.decision).toBe('declined')
+
+    // Once the answer HAS been mirrored, the shared record is authoritative again: another machine
+    // re-answering is a real change, and this browser has nothing newer to defend.
+    tutorial.markServerPushed()
+    tutorial.mergeServerProgress({ decision: 'accepted', completedTourIds: [], nudgedTourIds: [] })
+    expect(tutorial.decision).toBe('accepted')
+  })
+
+  it('treats an absent server copy as nothing to reconcile, not as an empty one', () => {
+    // No accounts, no store wired, or a degraded read. Pushing here would write a mirror on a
+    // deployment that has nowhere to put it; clearing would be worse.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    expect(tutorial.mergeServerProgress(null)).toBe(false)
+    expect(tutorial.completedTourIds).toEqual(['board-basics'])
+    expect(tutorial.serverPushNeeded).toBe(false)
+  })
+
+  it('clears the push request once the mirror has caught up', () => {
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    tutorial.mergeServerProgress({ decision: null, completedTourIds: [], nudgedTourIds: [] })
+    expect(tutorial.serverPushNeeded).toBe(true)
+    tutorial.markServerPushed()
+    expect(tutorial.serverPushNeeded).toBe(false)
+  })
+
+  it('re-arms the push when a merge RESPONSE comes back missing something local', () => {
+    // What makes the server's un-guarded merge safe. Two concurrent merges can lose one writer's
+    // ids, and the loser finds out because the response it gets back is a row without them. The
+    // ordering is the load-bearing part: the push is marked done FIRST, so re-arming flips the flag
+    // and re-triggers the mirror rather than being swallowed by a later clear.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    tutorial.markServerPushed()
+    expect(tutorial.serverPushNeeded).toBe(false)
+    tutorial.mergeServerProgress({
+      decision: 'accepted',
+      completedTourIds: ['first-task'],
+      nudgedTourIds: [],
+    })
+    expect(tutorial.serverPushNeeded).toBe(true)
+  })
+})
+
+describe('useTutorialStore local revision (what the mirror watches)', () => {
+  it('counts only what the USER did, never what the server told us', () => {
+    // The mirror watches this instead of the state, because adopting the server's own ids is a
+    // state change too: watching the state posts the server's row straight back at it on every
+    // fresh-browser board load.
+    const tutorial = useTutorialStore()
+    const before = tutorial.localRev
+    tutorial.mergeServerProgress({
+      decision: 'accepted',
+      completedTourIds: ['board-basics', 'first-task'],
+      nudgedTourIds: ['answer-park'],
+    })
+    expect(tutorial.completedTourIds).toEqual(['board-basics', 'first-task'])
+    expect(tutorial.localRev).toBe(before)
+
+    tutorial.startTour('run-task')
+    tutorial.completeTour()
+    expect(tutorial.localRev).toBeGreaterThan(before)
+  })
+
+  it('does not bump on a re-recorded completion, an unchanged answer, or a reset', () => {
+    const tutorial = useTutorialStore()
+    // Two real changes: the accept `startTour` writes, and the completion.
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    const settled = tutorial.localRev
+    expect(settled).toBe(2)
+
+    // Repeating the same tour changes nothing that is persisted: the answer is already 'accepted'
+    // and the completion is already recorded, so there is nothing for the mirror to carry.
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    expect(tutorial.localRev).toBe(settled)
+
+    // A reset's server side is a DELETE. A push of the freshly-emptied state racing it would
+    // re-create the row the DELETE removed, leaving "reset it" distinguishable from "never touched
+    // the tutorial" — the one thing the reset has to get right.
+    tutorial.resetProgress()
+    expect(tutorial.localRev).toBe(settled)
+    expect(tutorial.serverPushNeeded).toBe(false)
+  })
+})

package/app/stores/tutorial.ts

@@ -1,41 +1,46 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
+import { createTutorialPrompt } from '~/stores/tutorial.prompt'
+import { createTutorialRecord } from '~/stores/tutorial.record'
 
-/** The launch-prompt answer. `null` = never answered, so the app asks again next launch. */
-export type TutorialDecision = 'accepted' | 'declined'
+// `TutorialDecision` is deliberately NOT re-exported from here even though it used to live here:
+// both store modules are auto-import sources, so two exports of one name make Nuxt drop one of them
+// with a build warning. It is reachable unqualified anywhere in the layer, from `tutorial.record.ts`
+// where it is declared beside the state it describes.
 
 /**
  * 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:
+ * Two tiers of state, split on purpose — and the split is now a real seam rather than a comment:
  *
- *  - 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`, `catalogueOpen`, `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.
+ *  - PERSISTED (`decision`, `completedTourIds`, `nudgedTourIds`) — the standing record of what this
+ *    PERSON has done, owned by `createTutorialRecord` (`stores/tutorial.record.ts`) along with the
+ *    server-reconciliation rules that go with it. `null` (never asked) is a real state distinct from
+ *    `declined`: only an explicit answer stops the launch prompt returning, while closing it without
+ *    answering merely defers it to the next launch.
+ *  - SESSION-ONLY (`promptOpen`, `catalogueOpen`, `activeTourId`, `stepIndex`, `pendingNudgeId`) —
+ *    owned here. 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.
+ *
+ * The persisted half is a per-person fact rather than a per-browser one, so it is MIRRORED to the
+ * signed-in user's server row when the deployment has accounts (`useTutorialSync`), with this store
+ * staying the local cache the SPA reads. Persisting it here as well is not redundancy: it is what a
+ * deployment with auth disabled, and every load before the snapshot lands, runs on.
  *
  * 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.
+ * `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 record = createTutorialRecord()
+    // The launch offer's own four-exit state machine (`stores/tutorial.prompt.ts`), which needs to
+    // know only WHETHER an answer exists.
+    const prompt = createTutorialPrompt({ hasDecision: () => record.decision.value !== null })
+    const { promptOpen } = prompt
     /**
      * The tutorial catalogue (every tour this deployment ships, startable at any time) is
      * open. Always user-driven — nothing auto-opens it — which is why it carries none of the
@@ -58,6 +63,21 @@ export const useTutorialStore = defineStore(
      */
     const interrupted = ref<{ tourId: string; stepIndex: number } | null>(null)
 
+    /**
+     * The tour the contextual offer is currently holding out, or null.
+     *
+     * Session state, and separate from `nudgedTourIds` on purpose: the id is marked as SPENT the
+     * moment the offer is made, while what is on SCREEN survives being suppressed. The two most
+     * valuable moments to offer a tour (a run parked, a run failed) routinely arrive while a
+     * tutorial window or another tour is up, and dropping the offer there would lose the one chance
+     * this mechanism gets. Holding it means it appears as soon as the way is clear.
+     *
+     * The trade is deliberate: a reload before it is ever shown burns the offer. That beats the
+     * alternative of re-arming it, which turns one missed moment into a prompt that keeps coming
+     * back on a board whose gates flip constantly.
+     */
+    const pendingNudgeId = ref<string | null>(null)
+
     /** A tour is currently running (the overlay mounts off this). */
     const touring = computed(() => activeTourId.value !== null)
 
@@ -77,43 +97,6 @@ export const useTutorialStore = defineStore(
      */
     const ownWindowOpen = computed(() => promptOpen.value || catalogueOpen.value)
 
-    /**
-     * 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
-    }
-
     /**
      * Open the catalogue. Closes the launch prompt WITHOUT answering it: browsing the full
      * list is not "no thanks" (it is the opposite), and the two are modals that would
@@ -131,7 +114,7 @@ export const useTutorialStore = defineStore(
 
     /** The explicit "no thanks": saved, so the launch prompt never auto-opens again. */
     function decline() {
-      decision.value = 'declined'
+      record.declineOffer()
       promptOpen.value = false
     }
 
@@ -141,7 +124,7 @@ export const useTutorialStore = defineStore(
      * leaving `declined` in place would misdescribe what happened).
      */
     function startTour(tourId: string) {
-      decision.value = 'accepted'
+      record.acceptOffer()
       promptOpen.value = false
       catalogueOpen.value = false
       activeTourId.value = tourId
@@ -171,7 +154,7 @@ export const useTutorialStore = defineStore(
         startTour(tourId)
         return
       }
-      decision.value = 'accepted'
+      record.acceptOffer()
       promptOpen.value = false
       catalogueOpen.value = false
       activeTourId.value = tourId
@@ -211,9 +194,7 @@ export const useTutorialStore = defineStore(
     /** 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]
-      }
+      if (id) record.markCompleted(id)
       // A finished tour has no position left to resume, and an offer to resume the walkthrough
       // the user just completed would sit beside its own Completed badge.
       if (id !== null && interrupted.value?.tourId === id) interrupted.value = null
@@ -225,45 +206,50 @@ export const useTutorialStore = defineStore(
       return interrupted.value?.tourId === tourId ? interrupted.value.stepIndex : null
     }
 
-    function isCompleted(tourId: string): boolean {
-      return completedTourIds.value.includes(tourId)
+    /**
+     * Hold out the contextual offer for a tour that just became takeable.
+     *
+     * Spending the id and raising the offer are ONE action, so an offer can never be made twice
+     * however many times the gates flip: the guard is the persisted list, not the visible state.
+     * Idempotent, so a caller re-evaluating the catalogue needs no check of its own.
+     */
+    function offerNudge(tourId: string) {
+      if (record.wasNudged(tourId)) return
+      record.markNudged(tourId)
+      pendingNudgeId.value = tourId
+    }
+
+    /** Take the offer off screen. It is already spent, so it does not come back. */
+    function dismissNudge() {
+      pendingNudgeId.value = null
     }
 
     /**
-     * Forget everything this browser remembers about the tutorial: which tours were finished,
-     * where one was broken off, and the answer to the launch offer.
-     *
-     * The decision goes with it deliberately. "Reset" is asked for by someone handing the app
-     * to a colleague, demoing it, or re-walking the product after it changed — and every one
-     * of those wants the first-launch experience back, which a cleared completion list alone
-     * does not restore. It does NOT re-open the prompt in this session: `promptAutoOpened` is
-     * session state and stays spent, so the offer returns at the next launch rather than
-     * appearing on top of the catalogue the user is still reading.
+     * Forget everything this browser remembers about the tutorial (see `record.reset`), plus the
+     * offer currently on screen.
      *
-     * A running tour is left alone: this clears a record, it does not interrupt a walkthrough
-     * the user is in the middle of (which would end it, unrecorded, on a click about history).
+     * It does NOT re-open the prompt in this session: `promptAutoOpened` is session state and stays
+     * spent, so the offer returns at the next launch rather than appearing on top of the catalogue
+     * the user is still reading. A running tour is left alone: this clears a record, it does not
+     * interrupt a walkthrough the user is in the middle of (which would end it, unrecorded, on a
+     * click about history).
      */
     function resetProgress() {
-      completedTourIds.value = []
+      record.reset()
       interrupted.value = null
-      decision.value = null
+      pendingNudgeId.value = null
     }
 
     return {
-      decision,
-      completedTourIds,
-      promptOpen,
-      promptAutoOpened,
+      ...record,
+      ...prompt,
       catalogueOpen,
       activeTourId,
       stepIndex,
       interrupted,
+      pendingNudgeId,
       touring,
       ownWindowOpen,
-      maybeOfferOnLaunch,
-      openPrompt,
-      closePrompt,
-      deferPrompt,
       openCatalogue,
       closeCatalogue,
       resetProgress,
@@ -273,9 +259,10 @@ export const useTutorialStore = defineStore(
       setStepIndex,
       stopTour,
       completeTour,
-      isCompleted,
       interruptedAt,
+      offerNudge,
+      dismissNudge,
     }
   },
-  { persist: { pick: ['decision', 'completedTourIds'] } },
+  { persist: { pick: ['decision', 'completedTourIds', 'nudgedTourIds'] } },
 )