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

package/src/brand-page-maker/stores/history/history-store.ts

@@ -1,1041 +0,0 @@
-import { defineStore } from 'pinia';
-import { computed, nextTick, ref, shallowRef, toRaw, watch } from 'vue';
-import type { BrandPageModel } from '@brand-page';
-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';
-
-/**
- * A single history entry.
- *
- * `snapshot` is a **JSON-stringified** `BrandPageModel`, not a plain object.
- * Stringifying up-front has two benefits:
- *   1. Pinia's reactive proxy treats the string as a primitive — no traversal,
- *      no per-field getters/setters on our entries, no accidental shared refs
- *      with the live store.
- *   2. `sizeBytes === snapshot.length` is automatic and accurate for the V2
- *      memory-budget instrumentation.
- *
- * Sidecar state that doesn't live on `brandPageData` (the variations grid in
- * the Logo sidebar, the active `logoTemplateAsset`, the active
- * `logoDraftToken`) is restored on undo by `_syncLogoSettingsFromSnapshot`
- * via per-draft-token caches on the logo / editable-logo stores — keyed off
- * `logoImage.logoDraftToken` which IS in the snapshot.
- */
-export interface HistoryEntry {
-  /** JSON.stringify(BrandPageModel) at the moment of capture. */
-  snapshot: string;
-
-  /** ISO-8601 timestamp of when the entry was captured. */
-  timestamp: string;
-
-  /** What kind of change produced this entry. */
-  source: 'manual_edit' | 'template_switch' | 'ai_changeset' | 'rich_text';
-
-  /** Who authored the change. */
-  actor: 'user' | 'ai_builder';
-
-  /** Optional human-readable short description. Reserved for V2 UI / debugging. */
-  label?: string;
-
-  /** Serialized size in bytes (= snapshot.length in JS string semantics). */
-  sizeBytes: number;
-
-  /**
-   * The page the user was viewing when this entry was captured. Sidecar to the
-   * `BrandPageModel` snapshot — page-tab "selected" styling and the sidebar's
-   * `currentPage` getter both key off this id (via the route URL → routeStore →
-   * `pageNavigation.activePageId`). Snapshots only contain the document model,
-   * so without this we can't restore the URL/active-page on undo and the
-   * carousel highlight bleeds through to the page that no longer exists.
-   *
-   * Empty string when no page is active yet (e.g. earliest baseline before
-   * first router push). Always a real id once the editor has settled.
-   */
-  activePageId: string;
-}
-
-/**
- * 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<HistoryEntry[]>([]);
-  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: ReturnType<typeof useBrandPageMakerStore> | null = 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(): string | null {
-    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(): string {
-    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: unknown): boolean {
-    if (typeof value !== 'string') return false;
-
-    return /^<p(\s[^>]*)?>(<br\s*\/?>)?<\/p>$/.test(value);
-  }
-
-  function isHydrationOnlyAttributes(el: Element): boolean {
-    // 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: Node): string | null {
-    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 as Element;
-    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 as Element).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: string): string {
-    // 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: Document;
-
-    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: unknown): unknown {
-    if (Array.isArray(node)) return node.map(normalizeNode);
-
-    if (node === null || typeof node !== 'object') return node;
-
-    const out: Record<string, unknown> = {};
-
-    for (const key of Object.keys(node as Record<string, unknown>)) {
-      let v: unknown = (node as Record<string, unknown>)[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 as Record<string, unknown>;
-        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: string): string {
-    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: {
-    snapshot: string;
-    source: HistoryEntry['source'];
-    actor: HistoryEntry['actor'];
-    label?: string;
-    activePageId: string;
-  }): 'committed' | 'oversized' | 'noop' {
-    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: HistoryEntry = {
-      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: ReturnType<typeof setTimeout> | null = null;
-  let maxWaitTimerId: ReturnType<typeof setTimeout> | null = null;
-
-  function cancelPendingAutoCapture(): void {
-    if (idleTimerId !== null) {
-      clearTimeout(idleTimerId);
-      idleTimerId = null;
-    }
-
-    if (maxWaitTimerId !== null) {
-      clearTimeout(maxWaitTimerId);
-      maxWaitTimerId = null;
-    }
-  }
-
-  function installWatcher(): void {
-    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 = (): void => {
-      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(): void {
-    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: {
-    source: HistoryEntry['source'];
-    actor: HistoryEntry['actor'];
-    label?: string;
-  }): 'committed' | 'oversized' | 'noop' | 'skipped' {
-    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?: string,
-  ): 'committed' | 'oversized' | 'noop' | 'skipped' {
-    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?: string,
-  ): 'committed' | 'oversized' | 'noop' | 'skipped' {
-    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: string,
-    targetIndex: number,
-    cameFromIndex: number,
-  ): Promise<void> {
-    const brandPageMakerStore = useBrandPageMakerStore();
-
-    let snapshot: BrandPageModel;
-
-    try {
-      snapshot = JSON.parse(snapshotStr) as BrandPageModel;
-    } catch (error) {
-      console.error('history-store: failed to parse snapshot', error);
-
-      return;
-    }
-
-    const restoredPageIds = new Set<string>();
-
-    snapshot.pages?.forEach((p) => {
-      if (p?.id) restoredPageIds.add(p.id);
-    });
-
-    let resolvedActivePageId: string | undefined;
-
-    // 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<string>();
-
-      try {
-        const sourceSnap = JSON.parse(sourceEntry.snapshot) as BrandPageModel;
-
-        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(): Promise<void> {
-    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(): Promise<void> {
-    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(): void {
-    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(): number {
-    return entries.value.reduce((sum, e) => sum + e.sizeBytes, 0);
-  }
-
-  /** Total number of entries currently in the stack. */
-  function getCurrentEntryCount(): number {
-    return entries.value.length;
-  }
-
-  return {
-    // State
-    entries,
-    currentIndex,
-    isApplyingSnapshot,
-    baselineCaptured,
-
-    // Getters
-    canUndo,
-    canRedo,
-
-    // Actions
-    captureBaseline,
-    capture,
-    captureTemplateSwitch,
-    captureAiChangeset,
-    undo,
-    redo,
-    reset,
-    getCurrentSizeBytes,
-    getCurrentEntryCount,
-  };
-});