@designcrowd/library.brand-page 5.18.1-undo-32 → 5.18.1-undo-34

package/lib/src/brand-page-maker/stores/history/history-store.js

@@ -6,57 +6,27 @@ import { useAiWebsiteBuilderThreadStore } from '../ai-thread/ai-website-builder-
 import { useEventTracker } from '../../composables/useEventTracker';
 import { usePageNavigationStore } from '@shared/page-navigation/store/page-navigation-store';
 import { useUiEditableLogoStore } from '@shared/logo-settings/store/editable-logo-store';
-/**
- * Single-stack history model with a pointer instead of two stacks.
- *
- *   entries:  [e0, e1, e2, e3, e4]
- *                          ^
- *                          currentIndex
- *
- *   canUndo  = currentIndex > 0
- *   canRedo  = currentIndex < entries.length - 1
- *
- *   capture  → entries = entries.slice(0, currentIndex + 1); push; currentIndex = end
- *   undo     → currentIndex--; applySnapshot(entries[currentIndex])
- *   redo     → currentIndex++; applySnapshot(entries[currentIndex])
- *
- * This model:
- *   - eliminates the two-stack-desync risk class (mutating two refs in sequence)
- *   - makes FR-11 "clear redo on new change" a single array truncation
- *   - makes it trivial to build a V2 timeline UI (iterate entries, highlight
- *     currentIndex)
- */
-// Collapses multi-step mutations into a single capture. Monotonic: first
-// mutation starts the timer, further mutations inside the window do not
-// reset it. A max-wait ceiling forces a commit during continuous activity
-// so a user holding down a key for 15 s still gets periodic snapshots.
+// Monotonic burst — first mutation starts the timer, subsequent mutations
+// don't reset it; max-wait ceiling forces a commit during continuous typing.
 const CAPTURE_DEBOUNCE_MS = 1700;
 const CAPTURE_MAX_WAIT_MS = 10000;
-// FR-12: 40-entry cap. FR-13: 100 MB memory budget. FR-13c: per-entry
-// oversize threshold — entries above this are skipped + emit telemetry.
-// 25 MB accommodates a high-res BYO logo upload, which renders ~2.5 MB
-// of base64 PNG into each of four viewport sections (~10 MB) plus per-page
-// logo content blocks. The variations grid (~10 MB) does NOT live in the
-// snapshot — it sits on the editable-logo store keyed by draft token, and
-// is restored on undo from there. The 100 MB total budget still evicts
-// oldest non-baseline entries to keep memory bounded.
+// FR-12 / FR-13 / FR-13c. 25 MB per-entry accommodates a high-res BYO logo
+// rendered into 4 viewport sections + per-page logo blocks. Oversize
+// entries are skipped with telemetry; 100 MB total evicts oldest
+// non-baseline entries.
 const MAX_ENTRIES = 40;
 const MAX_MEMORY_BYTES = 100 * 1024 * 1024;
 const MAX_ENTRY_BYTES = 25 * 1024 * 1024;
-// Window after baseline-capture during which any auto-captured snapshot
-// REPLACES the baseline rather than pushing a new entry. Covers post-init
-// reactive cascades (template loadPageNo, router afterEach, layout settle)
-// that would otherwise make undo light up before the user has done anything.
+// Window after baseline during which captured mutations REPLACE the
+// baseline instead of pushing — covers async post-init cascades
+// (template load, router afterEach, layout settle).
 const BASELINE_SETTLE_MS = 2000;
 export const useHistoryStore = defineStore('history', () => {
     const eventTracker = useEventTracker();
     // --- State ---
-    /**
-     * `shallowRef` keeps the array ref reactive (so dependent computeds recompute
-     * when we swap the array) but prevents Pinia / Vue from proxying every entry
-     * object inside. Combined with string snapshots, entries are fully opaque to
-     * reactivity traversal — which is what we want for a history log.
-     */
+    // shallowRef keeps the array reactive but prevents Pinia from proxying
+    // every entry — combined with stringified snapshots, entries are
+    // fully opaque to reactivity traversal.
     const entries = shallowRef([]);
     const currentIndex = ref(-1); // -1 means "no baseline yet"
     const isApplyingSnapshot = ref(false);
@@ -67,24 +37,10 @@ export const useHistoryStore = defineStore('history', () => {
     const canUndo = computed(() => currentIndex.value > 0);
     const canRedo = computed(() => currentIndex.value >= 0 && currentIndex.value < entries.value.length - 1);
     // --- Internals ---
-    /**
-     * Cached reference to the maker store. Set once when the watcher installs so
-     * the capture hot path is synchronous.
-     */
-    let cachedMakerStore = null;
-    /**
-     * Walk `brandPageData` and null `logoImageBase64Url` on every logo
-     * placement (header/footer × desktop/mobile + per-page logo content).
-     * Pre-purchase only — the same gate the save path uses
-     * (see `brand-page-container-store.ts:805`).
-     *
-     * Each rendered base64 is ~2-4 MB and the brand-site templates put the
-     * same logo in 6-8 places, so unstripped pre-purchase snapshots run
-     * 18-24 MB and bump the 25 MB per-entry cap, which silently drops the
-     * entry. The base64 is repopulated on undo by `_syncLogoSettingsFromSnapshot`
-     * (designed: re-issue fabric-render; BYO: stamp from per-token cache),
-     * so the snapshot doesn't need to carry it.
-     */
+    // Pre-purchase only (matches the save-path strip in
+    // `brand-page-container-store.ts:805`). Each rendered base64 is ~2-4 MB
+    // across 6-8 placements, so unstripped snapshots bump the 25 MB cap.
+    // `_syncLogoSettingsFromSnapshot` repopulates on undo.
     function stripLogoBase64IfPrePurchase(data) {
         try {
             if (!useBrandPageContainerStore().isPrePurchase)
@@ -119,16 +75,9 @@ export const useHistoryStore = defineStore('history', () => {
             }
         }
     }
-    /**
-     * Serialize the current `brandPageData` into a detached JSON string.
-     * Synchronous — safe to call inside a microtask without racing a follow-up
-     * mutation.
-     */
     function serializeCurrentSnapshot() {
-        if (!cachedMakerStore)
-            return null;
         try {
-            const cloned = JSON.parse(JSON.stringify(toRaw(cachedMakerStore.brandPageData)));
+            const cloned = JSON.parse(JSON.stringify(toRaw(useBrandPageMakerStore().brandPageData)));
             stripLogoBase64IfPrePurchase(cloned);
             return JSON.stringify(cloned);
         }
@@ -137,19 +86,9 @@ export const useHistoryStore = defineStore('history', () => {
             return null;
         }
     }
-    /**
-     * Read the currently active pageId from `pageNavigationStore`. Sidecar to
-     * the snapshot string — see `HistoryEntry.activePageId`. Empty string when
-     * no page is active yet.
-     */
     function getCurrentActivePageId() {
         return usePageNavigationStore().activePageId ?? '';
     }
-    /**
-     * Serialize the current `editableLogoStore.logoEdits` as a sidecar to the
-     * snapshot — see `HistoryEntry.logoEdits`. Returns undefined when the
-     * editable-logo store hasn't initialized yet (no logo tab interaction).
-     */
     function serializeCurrentLogoEdits() {
         try {
             const editableLogoStore = useUiEditableLogoStore();
@@ -160,65 +99,28 @@ export const useHistoryStore = defineStore('history', () => {
             return undefined;
         }
     }
-    /**
-     * One-shot "fold next mutation back into the baseline (or current entry)
-     * rather than pushing a new entry" flag.
-     *
-     * Hydration write sites (TipTap mount, lazy paymentConfig fill,
-     * stale-page-ref clear) all run from a lifecycle hook on first sidebar
-     * open / section click. Each site mutates `brandPageData` exactly once
-     * with a value the user can't see as a change — but the deep watcher
-     * fires anyway, and without this gate the next idle flush would land a
-     * phantom undo entry.
-     *
-     * Each call site sets the flag immediately before the imperative write
-     * it knows is a hydration. The watcher's flush consumes the flag (clears
-     * it) and merges the resulting snapshot into `entries[currentIndex]`
-     * instead of pushing. No TTL — the flag stays armed until either:
-     *   - the watcher fires and consumes it, or
-     *   - a snapshot apply (undo/redo) clears it (we don't want a hydration
-     *     flag set immediately before an apply to swallow the post-apply
-     *     watcher tick), or
-     *   - `reset()` clears it on save.
-     *
-     * Multiple call sites in the same burst all set the same flag — they
-     * collapse together into a single merge into the current head, which is
-     * the semantics we want.
-     */
-    const mergeNextFlush = ref(false);
-    /**
-     * Commit a new entry into the stack at the current pointer position.
-     *
-     * Returns 'committed' when the entry lands in the stack, 'oversized' when
-     * the entry exceeds `MAX_ENTRY_BYTES` and is skipped (FR-13c), or 'noop'
-     * when the snapshot is byte-identical to the entry at the current pointer.
-     * Callers can use the return to emit telemetry — analytics wiring lives
-     * in U5.
-     *
-     * Enforces these invariants in order:
-     *   1. Drop no-op duplicates — if the new snapshot is identical to the
-     *      entry at the current pointer, skip it. Color/text settle paths,
-     *      template-switch confirms with no real diff, and AI applies that
-     *      land identical state would otherwise create undo/redo steps that
-     *      do nothing visible.
-     *   2. FR-13c — if the new entry exceeds 5 MB, skip it entirely.
-     *   3. FR-11 — truncate any redo tail.
-     *   4. FR-12 — cap at 40 entries; drop oldest non-baseline on overflow.
-     *   5. FR-13 — keep total memory under 100 MB; drop oldest non-baseline
-     *      repeatedly until we're under budget.
-     *
-     * Baseline (entry 0) is never evicted so "undo everything" always returns
-     * to session start.
-     */
+    // Two-phase merge flag. Hydration write sites call `mergeNextMutation()`
+    // immediately before their imperative write, which sets `mergeArmed`.
+    // When the watcher's `scheduleAutoCapture` arms a new idle timer, it
+    // transfers `mergeArmed` into `pendingTimerIsMerge`. The flush then
+    // consumes `pendingTimerIsMerge` and merges into the current head
+    // instead of pushing.
+    //
+    // The microtask cleanup on `mergeArmed` prevents stale flags surviving
+    // when the user navigates away (e.g. sidebar tab switch) before the
+    // flagged write actually happens — a previously-set arm is dropped
+    // synchronously after the current tick if no watcher fired.
+    const mergeArmed = ref(false);
+    let pendingTimerIsMerge = false;
+    // Returns 'noop' when no-change vs current head, 'oversized' when over
+    // MAX_ENTRY_BYTES, else 'committed'. Truncates the redo tail, caps at
+    // MAX_ENTRIES, evicts oldest non-baseline to stay under MAX_MEMORY_BYTES.
+    // Baseline (index 0) is never evicted.
     function commitEntry(args) {
         const current = entries.value[currentIndex.value];
-        // Compare both the snapshot bytes AND the logoEdits sidecar.
-        // Pre-purchase logo-tab edits (text/color/font) live in the
-        // `editableLogoStore.logoEdits` sidecar, NOT in `brandPageData`.
-        // The accompanying base64 writeback is also stripped from the
-        // snapshot (size cap), so a pure logo edit would produce a
-        // byte-identical snapshot to the previous entry — without the
-        // sidecar comparison every logo edit would dedup as a no-op.
+        // Compare both snapshot AND logoEdits sidecar — pre-purchase logo
+        // edits don't change brandPageData (base64 is stripped) so the
+        // sidecar is the only signal that distinguishes them.
         if (current &&
             current.snapshot === args.snapshot &&
             current.logoEdits === args.logoEdits) {
@@ -271,26 +173,8 @@ export const useHistoryStore = defineStore('history', () => {
         }
         return 'committed';
     }
-    /**
-     * Install a deep watcher on `brandPageData` that auto-captures mutations.
-     *
-     * Debounce strategy (FR-16 / ADR-005):
-     *   - Monotonic — the first mutation starts the idle timer; subsequent
-     *     mutations inside the window DO NOT reset it. This is what collapses
-     *     e.g. an RTE italic click's sync style write + ~100 ms-later HTML
-     *     update into a single capture.
-     *   - Idle flush — the idle timer fires CAPTURE_DEBOUNCE_MS after the
-     *     first mutation in a burst (2 s by default).
-     *   - Max-wait ceiling — if mutations keep arriving and the idle timer
-     *     keeps being "one more edit away", a second timer forces a commit at
-     *     CAPTURE_MAX_WAIT_MS after the burst started (10 s by default). This
-     *     is what keeps a user holding down a key from losing undo resolution.
-     *
-     * Both timers clear after a commit fires, so the next mutation starts a
-     * fresh burst.
-     */
-    // Hoisted so force-commit paths (template switch, AI apply) can cancel any
-    // pending auto-capture that would otherwise duplicate their entry.
+    // Hoisted so force-commit paths (template switch, AI apply) can cancel
+    // any pending auto-capture that would otherwise duplicate their entry.
     let idleTimerId = null;
     let maxWaitTimerId = null;
     function cancelPendingAutoCapture() {
@@ -306,7 +190,6 @@ export const useHistoryStore = defineStore('history', () => {
     function installWatcher() {
         if (watcherInstalled.value)
             return;
-        cachedMakerStore = useBrandPageMakerStore();
         const flush = () => {
             cancelPendingAutoCapture();
             if (isApplyingSnapshot.value)
@@ -318,28 +201,16 @@ export const useHistoryStore = defineStore('history', () => {
                 return;
             const activePageId = getCurrentActivePageId();
             const logoEdits = serializeCurrentLogoEdits();
-            // During the post-init settle window, fold any captured mutation back
-            // into the baseline (entry 0). Async cascades like template
-            // `loadPageNo`, the router's `afterEach`, and layout settling all
-            // mutate `brandPageData` after baseline is taken — without this they
-            // would each look like an undoable user edit on first paint. The
-            // baseline's `activePageId` is also overwritten so it tracks where
-            // the user actually settled (the router's `afterEach` runs inside
-            // this window, so the post-init `activePageId` is more accurate
-            // than the pre-router value captured in `captureBaseline`).
+            // Settle window: fold post-init reactive cascades back into the
+            // baseline so undo doesn't light up before the user has done
+            // anything.
             const inSettleWindow = currentIndex.value === 0 &&
                 Date.now() - baselineCapturedAt < BASELINE_SETTLE_MS;
-            // Merge branch — a hydration write site (TipTap mount, lazy
-            // paymentConfig fill, stale-page-ref clear) flagged this flush as
-            // "fold into the head, don't push". Replace `entries[currentIndex]`
-            // in place so the user-visible undo stack stays exactly as it was
-            // before the hydration burst arrived. Consume the flag whether or
-            // not we're in the settle window — `inSettleWindow` already merges
-            // into the baseline, but past that window the same merge has to
-            // happen against the current head for hydrations that fire when the
-            // user clicks into a section after the settle elapsed.
-            const shouldMerge = mergeNextFlush.value;
-            mergeNextFlush.value = false;
+            // Merge: the timer that fired this flush was armed during a
+            // hydration burst — replace the current head in place instead of
+            // pushing. Consumed once.
+            const shouldMerge = pendingTimerIsMerge;
+            pendingTimerIsMerge = false;
             if (inSettleWindow) {
                 entries.value = [
                     {
@@ -374,31 +245,32 @@ export const useHistoryStore = defineStore('history', () => {
                 logoEdits,
             });
         };
-        // Monotonic burst arming. `isApplyingSnapshot` is gated here so an
-        // undo/redo doesn't leave a stale timer ticking that later flushes
-        // mid-keystroke when the user starts editing inside the debounce
-        // window. `baselineCaptured` is not gated here — `installWatcher` is
-        // only called from `captureBaseline`, so by the time this fires it is
-        // always true, and `flush` re-checks it.
+        // Monotonic — first mutation arms; subsequent ones inside the window
+        // don't reset. Gated on isApplyingSnapshot so undo/redo don't leave
+        // a stale timer ticking. If a hydration site armed `mergeArmed`
+        // immediately before the mutation that triggered this run, transfer
+        // the intent into `pendingTimerIsMerge` so the resulting flush
+        // merges instead of commits.
         const scheduleAutoCapture = () => {
             if (isApplyingSnapshot.value)
                 return;
             if (idleTimerId !== null)
                 return;
+            if (mergeArmed.value) {
+                pendingTimerIsMerge = true;
+                mergeArmed.value = false;
+            }
             idleTimerId = setTimeout(flush, CAPTURE_DEBOUNCE_MS);
             maxWaitTimerId = setTimeout(flush, CAPTURE_MAX_WAIT_MS);
         };
-        watch(() => cachedMakerStore.brandPageData, scheduleAutoCapture, {
+        watch(() => useBrandPageMakerStore().brandPageData, scheduleAutoCapture, {
             deep: true,
         });
         watcherInstalled.value = true;
     }
     // --- Actions ---
-    /**
-     * Captures the baseline entry. Called once per session, typically by
-     * `BrandPageMaker.mixin.ts` immediately after `setIsBrandPageLoaded(true)`.
-     * Installs the reactive watcher so subsequent mutations auto-capture.
-     */
+    // Called once per session by BrandPageMaker.mixin.ts after
+    // setIsBrandPageLoaded(true). Installs the watcher.
     function captureBaseline() {
         if (baselineCaptured.value)
             return;
@@ -406,7 +278,6 @@ export const useHistoryStore = defineStore('history', () => {
         const snapshot = serializeCurrentSnapshot();
         if (!snapshot)
             return;
-        // Baseline starts a fresh stack of exactly 1 entry with pointer at 0.
         entries.value = [
             {
                 snapshot,
@@ -423,13 +294,7 @@ export const useHistoryStore = defineStore('history', () => {
         baselineCaptured.value = true;
         baselineCapturedAt = Date.now();
     }
-    /**
-     * Force-commit capture used by non-watcher call sites (template switch,
-     * AI apply). The watcher path commits atomically on its own.
-     *
-     * Returns the `commitEntry` result so force-commit callers can log
-     * oversized telemetry — analytics wiring lives in U5.
-     */
+    // Force-commit for non-watcher call sites (template switch, AI apply).
     function capture(args) {
         if (isApplyingSnapshot.value)
             return 'skipped';
@@ -445,47 +310,22 @@ export const useHistoryStore = defineStore('history', () => {
             ...args,
         });
     }
-    /**
-     * Force-commit a `template_switch` entry. Cancels any pending auto-capture
-     * so the template-switch change lands as exactly one entry (not a duplicate
-     * with the watcher's eventual flush).
-     */
+    // Cancel pending auto-capture so the forced entry doesn't duplicate
+    // with the watcher's eventual flush.
     function captureTemplateSwitch(label) {
         cancelPendingAutoCapture();
         return capture({ source: 'template_switch', actor: 'user', label });
     }
-    /**
-     * Force-commit an `ai_changeset` entry. Cancels any pending auto-capture
-     * so the AI apply lands as exactly one entry per prompt (US-E1).
-     */
     function captureAiChangeset(label) {
         cancelPendingAutoCapture();
         return capture({ source: 'ai_changeset', actor: 'ai_builder', label });
     }
-    /**
-     * Parse a stringified snapshot and push it through the maker store's
-     * dedicated `applyHistorySnapshot` action, which rehydrates every Pinia
-     * source store + own-store scalar fields that `brandPageData` reads from.
-     *
-     * Holds `isApplyingSnapshot` for the duration of the apply so the
-     * watcher guard suppresses the cascade of mutations from being
-     * re-captured as a spurious duplicate entry.
-     *
-     * Active-page resolution priority:
-     *   1. Diff against `cameFromIndex` — any page present in the target
-     *      snapshot but absent from the source snapshot is being "restored"
-     *      by this transition. Navigate there. Covers undo-of-delete (lands
-     *      on the deleted page) and redo-of-add (lands on the newly-added
-     *      page) — both of which the user expects to "follow" the change.
-     *      Without this, undo of a page-delete would resolve via walk-back
-     *      to whatever page the user was on at the previous baseline, not
-     *      the page they just un-deleted.
-     *   2. Walk back from `targetIndex` to find the closest entry whose
-     *      captured `activePageId` still exists in the restored snapshot.
-     *      Covers undo-of-add (falls back to the page the user was on
-     *      before they added the new one) and any non-page-structural
-     *      edits.
-     */
+    // Active-page resolution priority:
+    //   1. Diff `cameFromIndex` against target — pages present in target
+    //      but absent from source are being restored/added; navigate there
+    //      (undo-of-delete, redo-of-add).
+    //   2. Walk back from targetIndex for the closest entry whose
+    //      activePageId still exists (undo-of-add and non-page edits).
     async function applySnapshotString(snapshotStr, targetIndex, cameFromIndex) {
         const brandPageMakerStore = useBrandPageMakerStore();
         let snapshot;
@@ -502,9 +342,7 @@ export const useHistoryStore = defineStore('history', () => {
                 restoredPageIds.add(p.id);
         });
         let resolvedActivePageId;
-        // Step 1: diff against the source-of-transition. The first page in
-        // the target snapshot whose id is absent from the source is the page
-        // being restored/added by this apply.
+        // Step 1: diff cameFromIndex → first page absent from source wins.
         const sourceEntry = entries.value[cameFromIndex];
         if (sourceEntry) {
             const sourcePageIds = new Set();
@@ -525,9 +363,7 @@ export const useHistoryStore = defineStore('history', () => {
                 // Source snapshot unparseable — fall through to walk-back.
             }
         }
-        // Step 2: walk-back fallback. Used when no page-structural diff
-        // applies (style/content edits) or when the diff produced nothing
-        // viable.
+        // Step 2: walk-back fallback for non-page-structural edits.
         if (!resolvedActivePageId) {
             for (let i = targetIndex; i >= 0; i--) {
                 const candidate = entries.value[i]?.activePageId;
@@ -539,11 +375,10 @@ export const useHistoryStore = defineStore('history', () => {
         }
         const targetEntry = entries.value[targetIndex];
         isApplyingSnapshot.value = true;
-        // Drop any merge flag a hydration site might have armed but the
-        // watcher hasn't yet consumed — otherwise the post-apply watcher
-        // tick would silently fold the freshly-restored snapshot into the
-        // entry at the new pointer position and erase the user's redo.
-        mergeNextFlush.value = false;
+        // Clear any unconsumed merge intent — a stale flag would fold the
+        // post-apply tick into the restored entry and erase the redo.
+        mergeArmed.value = false;
+        pendingTimerIsMerge = false;
         cancelPendingAutoCapture();
         try {
             await brandPageMakerStore.applyHistorySnapshot(snapshot, resolvedActivePageId, targetEntry?.logoEdits);
@@ -552,14 +387,13 @@ export const useHistoryStore = defineStore('history', () => {
             isApplyingSnapshot.value = false;
         }
     }
-    /** Move the pointer back one step and apply the entry at the new position. */
     async function undo() {
         if (!canUndo.value)
             return;
         const aiThreadStore = useAiWebsiteBuilderThreadStore();
         if (aiThreadStore.isProcessing)
             return;
-        // Capture the actor of the entry we're leaving — that's the change being undone.
+        // Actor of the entry being undone (the one we're leaving).
         const undoneActor = entries.value[currentIndex.value]?.actor;
         const cameFromIndex = currentIndex.value;
         currentIndex.value -= 1;
@@ -572,7 +406,6 @@ export const useHistoryStore = defineStore('history', () => {
             actor: undoneActor,
         });
     }
-    /** Move the pointer forward one step and apply the entry at the new position. */
     async function redo() {
         if (!canRedo.value)
             return;
@@ -585,67 +418,49 @@ export const useHistoryStore = defineStore('history', () => {
         if (target) {
             await applySnapshotString(target.snapshot, currentIndex.value, cameFromIndex);
         }
-        // Actor of the entry we're moving onto — that's the change being re-applied.
         eventTracker.sendRedoEvent({
             entries_count: entries.value.length,
             actor: target?.actor,
         });
     }
-    /**
-     * Clear the stack and re-baseline against the just-saved state.
-     *
-     * PRD §3 Non-Goals: undo history resets on save/publish — the saved state
-     * becomes the new clean baseline so a user can't accidentally undo back
-     * past a save. Called by `brand-page-container-store.saveBrandPage` on a
-     * successful save (covers both Save Progress and Publish, since publish
-     * routes through `saveBrandPage`).
-     *
-     * No-ops when no baseline has ever been captured — the undo/redo feature
-     * is gated by `userStore.features.canUseUndoRedo` (see
-     * BrandPageMaker.mixin.ts), and only flagged sessions install the watcher
-     * + capture a baseline. Without this guard, calling reset() in an
-     * unflagged session would install the watcher and start eating memory
-     * for snapshots the user can never see.
-     *
-     * Re-runs `captureBaseline` synchronously so the next mutation lands as
-     * an actual undoable edit rather than disappearing into a fresh settle
-     * window. The watcher stays installed; `installWatcher` early-returns
-     * if `watcherInstalled` is already true.
-     */
+    // PRD §3: undo history resets on save/publish. Called by
+    // brand-page-container-store.saveBrandPage. No-ops when no baseline
+    // exists — unflagged sessions never installed the watcher.
     function reset() {
         if (!baselineCaptured.value)
             return;
         cancelPendingAutoCapture();
-        mergeNextFlush.value = false;
+        mergeArmed.value = false;
+        pendingTimerIsMerge = false;
         entries.value = [];
         currentIndex.value = -1;
         baselineCaptured.value = false;
         baselineCapturedAt = 0;
         captureBaseline();
     }
-    /**
-     * Arm the next watcher flush to fold its snapshot into the current head
-     * entry instead of pushing a new one. Hydration write sites (TipTap mount,
-     * lazy paymentConfig fill, stale-page-ref clear) call this immediately
-     * before the imperative `update:modelValue` / `$emit` they know is a
-     * hydration mutation. The next flush consumes (clears) the flag.
-     *
-     * Idempotent — multiple call sites in the same burst all set the same
-     * flag and collapse together into a single merge into the current head.
-     *
-     * No-op when the watcher hasn't yet baselined: hydration writes inside
-     * the settle window already merge into the baseline; outside a flagged
-     * session the flag has no observable effect.
-     */
+    // Hydration write sites call this immediately before their imperative
+    // mutation. The arm is auto-cleared on the next Vue tick — `nextTick`
+    // runs AFTER all queued reactive effects (including the watcher), so
+    // if the hydration write triggered `scheduleAutoCapture`, the arm has
+    // already been transferred into `pendingTimerIsMerge` before this
+    // cleanup fires. If no mutation followed (e.g. the user navigated
+    // away before the flagged write), the cleanup drops the stale arm so
+    // it can't be consumed by an unrelated future mutation.
     function mergeNextMutation() {
-        mergeNextFlush.value = true;
+        mergeArmed.value = true;
+        // setTimeout(0) is a macrotask — runs AFTER the synchronous write
+        // and AFTER Vue's microtask flush of the watcher's reactive effect.
+        // If `scheduleAutoCapture` fired in between (the imperative write
+        // triggered the watcher), the arm has already been transferred into
+        // `pendingTimerIsMerge` before this cleanup runs.
+        setTimeout(() => {
+            mergeArmed.value = false;
+        }, 0);
     }
     // --- Instrumentation (NFR-04a) ---
-    /** Sum of all entries' serialized sizes in bytes. */
     function getCurrentSizeBytes() {
         return entries.value.reduce((sum, e) => sum + e.sizeBytes, 0);
     }
-    /** Total number of entries currently in the stack. */
     function getCurrentEntryCount() {
         return entries.value.length;
     }

package/lib/src/index.mjs

@@ -1,4 +1,4 @@
-import { A as E, a as T, b as s, c as I, d as S, e as N, f as e, B as A, g as O, h as C, i as G, j as D, k as P, l as t, m as R, n as L, o as M, p as o, q as r, r as b, s as n, t as F, u as i, v as l, w as g, x as B, y as c, z as Y, C as U, D as d, E as u, F as H, G as p, H as y, I as K, J as k, K as m, L as V, M as X, N as h, O as v, P as W, Q as f, R as x, S as z, T as w, U as Z, V as j, W as Q, X as q, Y as J, Z as $, $ as aa, a0 as _a, a1 as Ea, a2 as Ta, a3 as sa, a4 as Ia, a5 as Sa, a6 as Na, a7 as ea, a8 as Aa, a9 as Oa, aa as Ca, ab as Ga, ac as Da, ad as Pa, ae as ta, af as Ra, ag as La, ah as Ma, ai as oa, aj as ra, ak as ba, al as na, am as Fa, an as ia, ao as la, ap as ga, aq as Ba, ar as ca, as as Ya, at as Ua, au as da, av as ua, aw as Ha, ax as pa, ay as ya, az as Ka, aA as ka, aB as ma, aC as Va, aD as Xa, aE as ha, aF as va, aG as Wa, aH as fa, aI as xa, aJ as za, aK as wa, aL as Za, aM as ja, aN as Qa, aO as qa, aP as Ja, aQ as $a, aR as a_, aS as __, aT as E_, aU as T_, aV as s_, aW as I_, aX as S_, aY as N_, aZ as e_, a_ as A_, a$ as O_, b0 as C_, b1 as G_, b2 as D_, b3 as P_, b4 as t_, b5 as R_, b6 as L_, b7 as M_, b8 as o_, b9 as r_, ba as b_, bb as n_, bc as F_, bd as i_, be as l_, bf as g_, bg as B_, bh as c_, bi as Y_, bj as U_, bk as d_, bl as u_, bm as H_, bn as p_, bo as y_, bp as K_, bq as k_, br as m_, bs as V_, bt as X_, bu as h_, bv as v_, bw as W_, bx as f_, by as x_, bz as z_, bA as w_, bB as Z_, bC as j_, bD as Q_, bE as q_, bF as J_, bG as $_, bH as aE, bI as _E, bJ as EE, bK as TE, bL as sE, bM as IE, bN as SE, bO as NE, bP as eE, bQ as AE, bR as OE, bS as CE, bT as GE, bU as DE, bV as PE, bW as tE, bX as RE, bY as LE, bZ as ME, b_ as oE, b$ as rE, c0 as bE, c1 as nE, c2 as FE, c3 as iE, c4 as lE, c5 as gE, c6 as BE, c7 as cE, c8 as YE, c9 as UE, ca as dE, cb as uE, cc as HE, cd as pE, ce as yE, cf as KE, cg as kE, ch as mE, ci as VE, cj as XE, ck as hE, cl as vE, cm as WE, cn as fE, co as xE } from "./lib-DVs3jUit.js";
+import { A as E, a as T, b as s, c as I, d as S, e as N, f as e, B as A, g as O, h as C, i as G, j as D, k as P, l as t, m as R, n as L, o as M, p as o, q as r, r as b, s as n, t as F, u as i, v as l, w as g, x as B, y as c, z as Y, C as U, D as d, E as u, F as H, G as p, H as y, I as K, J as k, K as m, L as V, M as X, N as h, O as v, P as W, Q as f, R as x, S as z, T as w, U as Z, V as j, W as Q, X as q, Y as J, Z as $, $ as aa, a0 as _a, a1 as Ea, a2 as Ta, a3 as sa, a4 as Ia, a5 as Sa, a6 as Na, a7 as ea, a8 as Aa, a9 as Oa, aa as Ca, ab as Ga, ac as Da, ad as Pa, ae as ta, af as Ra, ag as La, ah as Ma, ai as oa, aj as ra, ak as ba, al as na, am as Fa, an as ia, ao as la, ap as ga, aq as Ba, ar as ca, as as Ya, at as Ua, au as da, av as ua, aw as Ha, ax as pa, ay as ya, az as Ka, aA as ka, aB as ma, aC as Va, aD as Xa, aE as ha, aF as va, aG as Wa, aH as fa, aI as xa, aJ as za, aK as wa, aL as Za, aM as ja, aN as Qa, aO as qa, aP as Ja, aQ as $a, aR as a_, aS as __, aT as E_, aU as T_, aV as s_, aW as I_, aX as S_, aY as N_, aZ as e_, a_ as A_, a$ as O_, b0 as C_, b1 as G_, b2 as D_, b3 as P_, b4 as t_, b5 as R_, b6 as L_, b7 as M_, b8 as o_, b9 as r_, ba as b_, bb as n_, bc as F_, bd as i_, be as l_, bf as g_, bg as B_, bh as c_, bi as Y_, bj as U_, bk as d_, bl as u_, bm as H_, bn as p_, bo as y_, bp as K_, bq as k_, br as m_, bs as V_, bt as X_, bu as h_, bv as v_, bw as W_, bx as f_, by as x_, bz as z_, bA as w_, bB as Z_, bC as j_, bD as Q_, bE as q_, bF as J_, bG as $_, bH as aE, bI as _E, bJ as EE, bK as TE, bL as sE, bM as IE, bN as SE, bO as NE, bP as eE, bQ as AE, bR as OE, bS as CE, bT as GE, bU as DE, bV as PE, bW as tE, bX as RE, bY as LE, bZ as ME, b_ as oE, b$ as rE, c0 as bE, c1 as nE, c2 as FE, c3 as iE, c4 as lE, c5 as gE, c6 as BE, c7 as cE, c8 as YE, c9 as UE, ca as dE, cb as uE, cc as HE, cd as pE, ce as yE, cf as KE, cg as kE, ch as mE, ci as VE, cj as XE, ck as hE, cl as vE, cm as WE, cn as fE, co as xE } from "./lib-B5jbN-ro.js";
 import { createPinia as wE, setActivePinia as ZE } from "pinia";
 export {
   E as ABOUT_SECTION_SETTINGS_CONFIG,