@designcrowd/library.brand-page 5.17.25-undo-21 → 5.17.25

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

@@ -1,836 +0,0 @@
-import { defineStore } from 'pinia';
-import { computed, nextTick, ref, shallowRef, toRaw, watch } from 'vue';
-import { useBrandPageMakerStore } from '../brandpage-maker/brandpage-maker-store';
-import { useAiWebsiteBuilderThreadStore } from '../ai-thread/ai-website-builder-thread-store';
-import { useEventTracker } from '../../composables/useEventTracker';
-import { usePageNavigationStore } from '@shared/page-navigation/store/page-navigation-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.
-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.
-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.
-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.
-     */
-    const entries = shallowRef([]);
-    const currentIndex = ref(-1); // -1 means "no baseline yet"
-    const isApplyingSnapshot = ref(false);
-    const baselineCaptured = ref(false);
-    const watcherInstalled = ref(false);
-    let baselineCapturedAt = 0;
-    // --- Getters ---
-    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;
-    /**
-     * 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 {
-            return JSON.stringify(toRaw(cachedMakerStore.brandPageData));
-        }
-        catch (error) {
-            console.error('history-store: failed to serialize snapshot', error);
-            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 ?? '';
-    }
-    /**
-     * Normalize a snapshot for the dedup byte-compare. Strips/canonicalizes
-     * fields that get mutated by sidebar-open reactive cascades but aren't
-     * user-visible edits — without this, opening a content panel produces an
-     * undo step that "does nothing" when replayed.
-     *
-     * Known phantom sources (BP-5506):
-     *   - TipTap RTE writing back its empty-paragraph default on first mount
-     *     (e.g. `""` → `<p style="text-align: center;"></p>`).
-     *   - TipTap RTE writing back its default-style hydration on first mount
-     *     (e.g. plain `"Hello"` → `<p style="..."><span style="..."><mark ...>Hello</mark></span></p>`).
-     *   - TipTap re-emitting whole-content `<strong>`/`<em>`/`<u>`/`<s>` tags
-     *     to mirror the resolved `textStyle.fontWeight / fontStyle /
-     *     textDecoration` (e.g. plain `"text"` →
-     *     `<p>...<span>...<strong>text</strong></span></p>`).
-     *   - Lazy hydration of `*Style` objects when a content settings panel —
-     *     or section selection on the canvas — resolves `textStyleType` and
-     *     writes the full resolved style (fontFamily, fontSize, color,
-     *     fontWeight, fontStyle, letterSpacing, lineHeight, textDecoration)
-     *     onto the model. The `textStyleType` itself is the authoring
-     *     intent; the resolved keys are just cached values.
-     *   - `isModifiedAfterTemplateApplied` flipping on first edit gesture.
-     *   - `logoImageBase64Url` — the rendered logo PNG. Per-property logo
-     *     edits author through `editableLogoStore.logoEdits` (not in
-     *     `brandPageData`), so an undo would revert the canvas image but
-     *     leave the sidebar fields showing the user's typed value. Logo
-     *     property edits are excluded from V1 undo scope; BYO-upload undo
-     *     still works because that diff lives in `logoImage.logoDraftToken`.
-     *
-     * RTE strings are canonicalized by parsing the HTML with DOMParser and
-     * walking the tree; only attributeless format wrappers (and a tightly
-     * scoped set of hydration styles on `<p>` / `<span>` / `<mark>`) are
-     * collapsed. Real authoring intent (links, custom colors, partial-text
-     * formatting like `Hello <strong>world</strong>`) survives the walk
-     * because at least one node falls outside the hydration whitelist,
-     * and the walker bails to "preserve original" the moment that happens.
-     *
-     * Used ONLY for dedup comparison. Stored snapshots remain unchanged so
-     * `applyHistorySnapshot` always sees the real state.
-     */
-    // Tags TipTap re-emits purely to mirror the resolved textStyle on first
-    // hydration. None carry user authoring intent on their own when they are
-    // the sole element-child wrapping the entire content:
-    //   - <p>:    only its `text-align` style is meaningful, and that's already
-    //             captured in `textStyle.textAlign`.
-    //   - <span>: TipTap wraps content in a span with `font-family`, `font-size`,
-    //             `color`, `letter-spacing`, `line-height` resolved from the
-    //             textStyle. The textStyle object on the same content is the
-    //             authoritative source.
-    //   - <mark>: TipTap's highlight extension default — collapses regardless
-    //             of `data-color` / `style` attrs, mirroring the original
-    //             regex's behavior on a hydrated highlight.
-    //   - <strong>/<em>/<u>/<s>: attributeless tags that mirror
-    //             `fontWeight: bold` / `fontStyle: italic` / `textDecoration:
-    //             underline / line-through`. ONLY recognized as hydration when
-    //             they are the sole child of their parent — partial-content
-    //             usage like `Hello <strong>world</strong>` is a real edit.
-    // Anything else (`<a>`, `<br>`, `<span style="color: red">`, attributes on
-    // <strong>/<em>, etc.) is preserved as a real diff.
-    const STRUCTURAL_HYDRATION_TAGS = new Set(['P', 'SPAN', 'MARK']);
-    const FORMAT_HYDRATION_TAGS = new Set(['STRONG', 'EM', 'U', 'S']);
-    // Default style properties TipTap emits on a hydration <span> /
-    // <mark>. The textStyle resolver writes all of these onto the live
-    // model, so when TipTap re-emits them as inline style on its
-    // hydration span/mark there is no user-visible delta.
-    // Anything outside this whitelist (e.g. `text-decoration` mid-content,
-    // `text-shadow`, `text-transform`) is treated as a real edit.
-    const HYDRATION_INLINE_STYLE_PROPS = new Set([
-        'font-family',
-        'font-size',
-        'letter-spacing',
-        'line-height',
-        'color',
-        'background-color',
-    ]);
-    // Empty paragraph forms TipTap emits when an editor mounts on an empty
-    // string. Treated as equivalent to `""` for dedup.
-    function isEmptyRteHtml(value) {
-        if (typeof value !== 'string')
-            return false;
-        return /^<p(\s[^>]*)?>(<br\s*\/?>)?<\/p>$/.test(value);
-    }
-    function isHydrationOnlyAttributes(el) {
-        // Format tags (<strong>/<em>/<u>/<s>) must be attributeless. Anything
-        // with class/style/data-*/etc. is a real edit.
-        if (FORMAT_HYDRATION_TAGS.has(el.tagName))
-            return el.attributes.length === 0;
-        for (const attr of Array.from(el.attributes)) {
-            // <mark> may carry a `data-color` attr (TipTap highlight extension's
-            // default-and-resolved value). The accompanying `style` is checked
-            // against the same hydration-prop whitelist as <span>.
-            if (el.tagName === 'MARK' &&
-                (attr.name === 'data-color' || attr.name === 'style')) {
-                if (attr.name === 'data-color')
-                    continue;
-            }
-            else if (attr.name !== 'style') {
-                return false;
-            }
-            const decls = attr.value
-                .split(';')
-                .map((d) => d.trim())
-                .filter(Boolean);
-            if (el.tagName === 'P') {
-                for (const decl of decls) {
-                    const [prop] = decl.split(':').map((s) => s.trim());
-                    if (prop !== 'text-align')
-                        return false;
-                }
-            }
-            else if (el.tagName === 'SPAN' || el.tagName === 'MARK') {
-                for (const decl of decls) {
-                    const [prop, value] = decl.split(':').map((s) => s.trim());
-                    // Allow `color: inherit` on <mark> (TipTap stamps it on the
-                    // default highlight to inherit the span's color). Otherwise
-                    // require the prop to be in the hydration whitelist.
-                    if (el.tagName === 'MARK' &&
-                        prop === 'color' &&
-                        value === 'inherit') {
-                        continue;
-                    }
-                    if (!HYDRATION_INLINE_STYLE_PROPS.has(prop))
-                        return false;
-                }
-            }
-            else {
-                return false;
-            }
-        }
-        return true;
-    }
-    /**
-     * Walk a parsed HTML node tree. Return the joined text content if every
-     * descendant is hydration noise; return null if any node carries real
-     * authoring intent (links, partial formatting, custom styles, etc.).
-     *
-     * `isFormatTag` differs in how it's allowed to appear: a structural tag
-     * (P/SPAN/MARK) can have siblings; a format tag (STRONG/EM/U/S) is only
-     * allowed when it's the SOLE child of its parent. The caller enforces
-     * that at the iteration site.
-     */
-    function extractCanonicalText(node) {
-        if (node.nodeType === 3 /* TEXT_NODE */)
-            return node.textContent ?? '';
-        if (node.nodeType !== 1 /* ELEMENT_NODE */) {
-            // Comments, CDATA, etc. — treat as opaque (preserve original).
-            return null;
-        }
-        const el = node;
-        const isStructural = STRUCTURAL_HYDRATION_TAGS.has(el.tagName);
-        const isFormat = FORMAT_HYDRATION_TAGS.has(el.tagName);
-        if (!isStructural && !isFormat)
-            return null;
-        if (!isHydrationOnlyAttributes(el))
-            return null;
-        const children = Array.from(el.childNodes);
-        let out = '';
-        for (const child of children) {
-            // Format tags only count as hydration when they wrap the ENTIRE
-            // content of their parent. If a <strong>/<em>/<u>/<s> appears
-            // alongside any sibling (text or element), it's partial-content
-            // formatting — a real edit that can't be expressed via textStyle —
-            // so bail.
-            if (child.nodeType === 1 &&
-                FORMAT_HYDRATION_TAGS.has(child.tagName) &&
-                children.length > 1) {
-                return null;
-            }
-            const part = extractCanonicalText(child);
-            if (part === null)
-                return null;
-            out += part;
-        }
-        return out;
-    }
-    /**
-     * If `value` is TipTap's default-hydration wrapper around plain text
-     * (only hydration-noise elements wrapping bare text), return that bare
-     * text. Otherwise return the original string unchanged.
-     *
-     * This collapses the BP-5506 phantom where opening a content sidebar —
-     * or selecting a section on the canvas — mounts every RTE editor at
-     * once and writes back wrapped HTML with no user-visible delta.
-     */
-    function canonicalizeRteString(value) {
-        // Cheap exit: no tags at all.
-        if (!value.includes('<'))
-            return value;
-        if (isEmptyRteHtml(value))
-            return '';
-        // DOMParser is unavailable in some non-browser test environments;
-        // fall back to leaving the value as-is so the caller produces a
-        // real diff (i.e. fail open — never falsely collapse).
-        if (typeof DOMParser === 'undefined')
-            return value;
-        let doc;
-        try {
-            doc = new DOMParser().parseFromString(`<div id="__rte_root__">${value}</div>`, 'text/html');
-        }
-        catch {
-            return value;
-        }
-        const root = doc.getElementById('__rte_root__');
-        if (!root)
-            return value;
-        let out = '';
-        for (const child of Array.from(root.childNodes)) {
-            const part = extractCanonicalText(child);
-            if (part === null)
-                return value;
-            out += part;
-        }
-        return out;
-    }
-    function normalizeNode(node) {
-        if (Array.isArray(node))
-            return node.map(normalizeNode);
-        if (node === null || typeof node !== 'object')
-            return node;
-        const out = {};
-        for (const key of Object.keys(node)) {
-            let v = node[key];
-            // Strip the template-modified flag — it's meta-state that flips on
-            // first edit gesture (e.g. clicking into a panel) and does not
-            // represent a user-visible change.
-            if (key === 'isModifiedAfterTemplateApplied')
-                continue;
-            // Strip the rendered logo PNG. Logo property edits (text, color,
-            // font, outline, shadow) authored via the Logo sidebar live in
-            // `editableLogoStore.logoEdits` — which is NOT in `brandPageData`,
-            // so an undo would revert this base64 image on the canvas without
-            // touching the sidebar fields. Per V1 scope, logo property edits
-            // are non-undoable (parallels the PRD's admin-logo exclusion);
-            // BYO-upload undo still works because that change shows up in
-            // `logoImage.logoDraftToken`, not here. Stripping the field keeps
-            // those isolated render-output diffs out of the stack entirely.
-            if (key === 'logoImageBase64Url')
-                continue;
-            // Collapse RTE default-hydration wrappers down to the plain text
-            // they wrap. Plain "X" and `<p style="..."><span ...><mark ...>X
-            // </mark></span></p>` share the same canonical "X" so a sidebar
-            // open that mounts every editor at once doesn't generate phantom
-            // undo steps.
-            if (typeof v === 'string') {
-                v = canonicalizeRteString(v);
-            }
-            // Empty TipTap paragraphs collapse to "" — and an empty string is
-            // equivalent to the key being absent (JSON.stringify drops `undefined`),
-            // so skip the key entirely. Otherwise the normalizer would emit
-            // `"description": ""` here while the baseline snapshot — captured when
-            // `description` was `undefined` — has no `description` key at all,
-            // and the two normalized strings would differ.
-            if (isEmptyRteHtml(v) || v === '')
-                continue;
-            // textStyle / descriptionStyle / titleStyle / *Style objects.
-            //
-            // When `textStyleType` is set, the live store lazily fills in the
-            // resolved values (fontFamily, fontSize, color, fontWeight,
-            // fontStyle, letterSpacing, lineHeight, textDecoration, etc.) the
-            // first time a settings panel — or section-selection on the canvas
-            // — resolves `textStyleType` against `styles.textStyles.textStyleOptions`.
-            // None of those lazy fields represent a real user edit; the
-            // `textStyleType` itself is the authoring intent.
-            //
-            // Real user edits via the inline RTE toolbar set `textStyleType: undefined`
-            // (see useRichTextEditor.ts `fontStyleChanges = { ..., textStyleType: undefined }`),
-            // so we leave every key intact in that case — those values ARE the
-            // real authoring intent.
-            //
-            // Per-content style edits via the global Style panel land in
-            // `snapshot.styles.textStyles` (a separate sub-tree), so they still
-            // produce a real diff outside this branch.
-            if (v !== null &&
-                typeof v === 'object' &&
-                !Array.isArray(v) &&
-                /Style$/.test(key)) {
-                const styleObj = v;
-                const hasTextStyleType = styleObj.textStyleType !== undefined &&
-                    styleObj.textStyleType !== null;
-                if (hasTextStyleType) {
-                    // Drop everything except `textStyleType` itself + `textAlign`,
-                    // which is the user's per-instance alignment override (preserved
-                    // on hydration via `globalContentStyle = { ...resolved, textAlign: style?.textAlign }`).
-                    out[key] = {
-                        textStyleType: styleObj.textStyleType,
-                        ...(styleObj.textAlign !== undefined
-                            ? { textAlign: styleObj.textAlign }
-                            : {}),
-                    };
-                    continue;
-                }
-                // No textStyleType — these are real per-content overrides. Recurse
-                // normally so nested objects still get the standard treatment.
-                out[key] = normalizeNode(styleObj);
-                continue;
-            }
-            out[key] = normalizeNode(v);
-        }
-        return out;
-    }
-    function normalizeSnapshotForDedup(snapshotStr) {
-        try {
-            const parsed = JSON.parse(snapshotStr);
-            return JSON.stringify(normalizeNode(parsed));
-        }
-        catch {
-            return snapshotStr;
-        }
-    }
-    /**
-     * 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.
-     */
-    function commitEntry(args) {
-        const current = entries.value[currentIndex.value];
-        if (current) {
-            if (current.snapshot === args.snapshot)
-                return 'noop';
-            // Phantom-edit dedup: normalize both snapshots to ignore
-            // sidebar-open reactive cascades (RTE empty-paragraph init, lazy
-            // textStyle hydration, isModifiedAfterTemplateApplied flips). If
-            // they're equal after normalization, this capture has no
-            // user-visible diff vs. the entry at the pointer.
-            if (normalizeSnapshotForDedup(current.snapshot) ===
-                normalizeSnapshotForDedup(args.snapshot)) {
-                return 'noop';
-            }
-        }
-        if (args.snapshot.length > MAX_ENTRY_BYTES) {
-            eventTracker.sendHistoryOversizedEvent({
-                attempted_bytes: args.snapshot.length,
-                source: args.source,
-            });
-            return 'oversized';
-        }
-        const entry = {
-            snapshot: args.snapshot,
-            timestamp: new Date().toISOString(),
-            source: args.source,
-            actor: args.actor,
-            label: args.label,
-            sizeBytes: args.snapshot.length,
-            activePageId: args.activePageId,
-        };
-        // FR-11: truncate redo tail, then append.
-        const next = entries.value.slice(0, currentIndex.value + 1);
-        next.push(entry);
-        // FR-12: 40-entry cap. Drop oldest non-baseline (index 1) if we'd exceed.
-        let didEvict = false;
-        while (next.length > MAX_ENTRIES && next.length > 1) {
-            next.splice(1, 1);
-            didEvict = true;
-        }
-        // FR-13: keep total serialized size under 100 MB. Drop oldest
-        // non-baseline repeatedly until under budget. Baseline alone can exceed
-        // the budget on a very large page — in that pathological case we stop
-        // evicting at length 2 (baseline + newest) rather than dropping the
-        // baseline.
-        let totalBytes = next.reduce((sum, e) => sum + e.sizeBytes, 0);
-        while (totalBytes > MAX_MEMORY_BYTES && next.length > 2) {
-            totalBytes -= next[1].sizeBytes;
-            next.splice(1, 1);
-            didEvict = true;
-        }
-        entries.value = next;
-        currentIndex.value = next.length - 1;
-        if (didEvict) {
-            eventTracker.sendHistoryCappedEvent({
-                entries_count: next.length,
-                size_bytes: totalBytes,
-            });
-        }
-        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.
-    let idleTimerId = null;
-    let maxWaitTimerId = null;
-    function cancelPendingAutoCapture() {
-        if (idleTimerId !== null) {
-            clearTimeout(idleTimerId);
-            idleTimerId = null;
-        }
-        if (maxWaitTimerId !== null) {
-            clearTimeout(maxWaitTimerId);
-            maxWaitTimerId = null;
-        }
-    }
-    function installWatcher() {
-        if (watcherInstalled.value)
-            return;
-        cachedMakerStore = useBrandPageMakerStore();
-        const flush = () => {
-            cancelPendingAutoCapture();
-            if (isApplyingSnapshot.value)
-                return;
-            if (!baselineCaptured.value)
-                return;
-            const snapshot = serializeCurrentSnapshot();
-            if (!snapshot)
-                return;
-            const activePageId = getCurrentActivePageId();
-            // 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`).
-            const inSettleWindow = currentIndex.value === 0 &&
-                Date.now() - baselineCapturedAt < BASELINE_SETTLE_MS;
-            if (inSettleWindow) {
-                entries.value = [
-                    {
-                        ...entries.value[0],
-                        snapshot,
-                        timestamp: new Date().toISOString(),
-                        sizeBytes: snapshot.length,
-                        activePageId,
-                    },
-                ];
-                return;
-            }
-            commitEntry({
-                snapshot,
-                source: 'manual_edit',
-                actor: 'user',
-                activePageId,
-            });
-        };
-        // 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.
-        const scheduleAutoCapture = () => {
-            if (isApplyingSnapshot.value)
-                return;
-            if (idleTimerId !== null)
-                return;
-            idleTimerId = setTimeout(flush, CAPTURE_DEBOUNCE_MS);
-            maxWaitTimerId = setTimeout(flush, CAPTURE_MAX_WAIT_MS);
-        };
-        watch(() => cachedMakerStore.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.
-     */
-    function captureBaseline() {
-        if (baselineCaptured.value)
-            return;
-        installWatcher();
-        const snapshot = serializeCurrentSnapshot();
-        if (!snapshot)
-            return;
-        // Baseline starts a fresh stack of exactly 1 entry with pointer at 0.
-        entries.value = [
-            {
-                snapshot,
-                timestamp: new Date().toISOString(),
-                source: 'manual_edit',
-                actor: 'user',
-                label: 'baseline',
-                sizeBytes: snapshot.length,
-                activePageId: getCurrentActivePageId(),
-            },
-        ];
-        currentIndex.value = 0;
-        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.
-     */
-    function capture(args) {
-        if (isApplyingSnapshot.value)
-            return 'skipped';
-        if (!baselineCaptured.value)
-            return 'skipped';
-        const snapshot = serializeCurrentSnapshot();
-        if (!snapshot)
-            return 'skipped';
-        return commitEntry({
-            snapshot,
-            activePageId: getCurrentActivePageId(),
-            ...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).
-     */
-    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` through `nextTick` so Vue's reactive queue
-     * drains while the watcher guard is still set, preventing the restore 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.
-     */
-    async function applySnapshotString(snapshotStr, targetIndex, cameFromIndex) {
-        const brandPageMakerStore = useBrandPageMakerStore();
-        let snapshot;
-        try {
-            snapshot = JSON.parse(snapshotStr);
-        }
-        catch (error) {
-            console.error('history-store: failed to parse snapshot', error);
-            return;
-        }
-        const restoredPageIds = new Set();
-        snapshot.pages?.forEach((p) => {
-            if (p?.id)
-                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.
-        const sourceEntry = entries.value[cameFromIndex];
-        if (sourceEntry) {
-            const sourcePageIds = new Set();
-            try {
-                const sourceSnap = JSON.parse(sourceEntry.snapshot);
-                sourceSnap.pages?.forEach((p) => {
-                    if (p?.id)
-                        sourcePageIds.add(p.id);
-                });
-                for (const p of snapshot.pages ?? []) {
-                    if (p?.id && !sourcePageIds.has(p.id)) {
-                        resolvedActivePageId = p.id;
-                        break;
-                    }
-                }
-            }
-            catch {
-                // 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.
-        if (!resolvedActivePageId) {
-            for (let i = targetIndex; i >= 0; i--) {
-                const candidate = entries.value[i]?.activePageId;
-                if (candidate && restoredPageIds.has(candidate)) {
-                    resolvedActivePageId = candidate;
-                    break;
-                }
-            }
-        }
-        isApplyingSnapshot.value = true;
-        try {
-            await brandPageMakerStore.applyHistorySnapshot(snapshot, resolvedActivePageId);
-            await nextTick();
-        }
-        finally {
-            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.
-        const undoneActor = entries.value[currentIndex.value]?.actor;
-        const cameFromIndex = currentIndex.value;
-        currentIndex.value -= 1;
-        const target = entries.value[currentIndex.value];
-        if (target) {
-            await applySnapshotString(target.snapshot, currentIndex.value, cameFromIndex);
-        }
-        eventTracker.sendUndoEvent({
-            entries_count: entries.value.length,
-            actor: undoneActor,
-        });
-    }
-    /** Move the pointer forward one step and apply the entry at the new position. */
-    async function redo() {
-        if (!canRedo.value)
-            return;
-        const aiThreadStore = useAiWebsiteBuilderThreadStore();
-        if (aiThreadStore.isProcessing)
-            return;
-        const cameFromIndex = currentIndex.value;
-        currentIndex.value += 1;
-        const target = entries.value[currentIndex.value];
-        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.
-     */
-    function reset() {
-        if (!baselineCaptured.value)
-            return;
-        cancelPendingAutoCapture();
-        entries.value = [];
-        currentIndex.value = -1;
-        baselineCaptured.value = false;
-        baselineCapturedAt = 0;
-        captureBaseline();
-    }
-    // --- 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;
-    }
-    return {
-        // State
-        entries,
-        currentIndex,
-        isApplyingSnapshot,
-        baselineCaptured,
-        // Getters
-        canUndo,
-        canRedo,
-        // Actions
-        captureBaseline,
-        capture,
-        captureTemplateSwitch,
-        captureAiChangeset,
-        undo,
-        redo,
-        reset,
-        getCurrentSizeBytes,
-        getCurrentEntryCount,
-    };
-});