@drip-apex/sdk 0.1.0 → 0.2.0

package/src/mutate.ts

@@ -1,92 +1,84 @@
 import { Mutation, MutationAction } from "./types";
-import { sanitizeHtml } from "./sanitize";
+import { isSafeMutationAttribute, sanitizeHtml } from "./sanitize";
 import { runMuted } from "./observer-mute";
-import { resetReassertSentinel } from "./reassert-sentinel";
-import { isStrictJsPolicy } from "./js";
+import {
+  addReassertSentinelOwners,
+  replayReassertSentinelEntry,
+  resetReassertSentinel,
+  resetReassertSentinelForOwner,
+} from "./reassert-sentinel";
+import { extractCurrencyTokens, type CurrencyToken } from "./money";
+import { queryAllDeep } from "./shadow";
 
 export type ApplyOptions = {
   root?: Document | HTMLElement;
-  onApplied?: (mutation: Mutation, element: Element, index: number) => void;
+  artifactId?: string;
+  epoch?: number;
+  ownerKeys?: readonly string[];
+  onApplied?: (mutation: Mutation, element: Element, index: number, journalSeq?: number) => void;
   onMiss?: (mutation: Mutation, index: number) => void;
+  preservePrices?: boolean;
+  priceTestExempt?: boolean;
+  onPricePreservationViolation?: (input: {
+    mutation: Mutation;
+    selector: string;
+    originalPriceTokens: CurrencyToken[];
+  }) => void;
 };
 
 const INSERT_ATTR = "data-drip-inserted";
 
-type AttributeSnapshot = {
-  kind: "attribute";
-  element: Element;
-  values: Array<{ name: string; value: string | null }>;
-};
+type ElementReference = { deref: () => Element | undefined };
 
-type ContentSnapshot = {
-  kind: "content";
-  element: Element;
-  property: "innerHTML" | "textContent";
-  value: string | null;
+type ElementBaseline = {
+  attributeValues: Map<string, string | null>;
+  contentTouched: boolean;
+  innerHTML?: string;
+  textContent?: string | null;
+  styleAttributeTouched: boolean;
+  styleAttributeValue: string | null;
+  styleValues: Map<string, { value: string; priority: string }>;
+  parent: Node | null;
+  nextSibling: Node | null;
 };
 
-type StyleSnapshot = {
-  kind: "style";
-  element: HTMLElement;
-  values: Array<{ name: string; value: string; priority: string }>;
+export type MutationJournalEntry = {
+  seq: number;
+  artifactId: string;
+  owners: Set<string>;
+  target: { selector: string; index: number; el: ElementReference };
+  mutation: Mutation;
+  epoch: number;
+  kind: "mutation" | "insert" | "adopt-insert";
+  insertKey?: string;
+  nodes?: Node[];
+  state: "applied" | "invalidated";
 };
 
-type RemoveSnapshot = {
-  kind: "remove";
-  element: Element;
-  parent: Node | null;
-  nextSibling: Node | null;
+type MutationJournal = {
+  entries: MutationJournalEntry[];
+  baselines: WeakMap<Element, ElementBaseline>;
+  fallbackArtifactId: string;
 };
 
-type InsertSnapshot = {
-  kind: "insert";
-  nodes: Node[];
+let journalSequence = 0;
+let applicationContextSequence = 0;
+// Sequence order is the treatment order. A rollback restores one baseline,
+// removes dead entries, and replays every surviving entry in this order.
+const mutationJournal: MutationJournal = {
+  entries: [],
+  baselines: new WeakMap(),
+  fallbackArtifactId: "runtime",
 };
 
-type MutationSnapshot =
-  | AttributeSnapshot
-  | ContentSnapshot
-  | StyleSnapshot
-  | RemoveSnapshot
-  | InsertSnapshot;
-
-const mutationSnapshots: MutationSnapshot[] = [];
-
-const URL_ATTRIBUTES = new Set(["href", "src", "action", "formaction", "xlink:href"]);
-const SAFE_DATA_URL_MEDIA_TYPES = new Set([
-  "image/png",
-  "image/jpeg",
-  "image/gif",
-  "image/webp",
-  "image/avif",
-]);
-
-export function isSafeMutationAttribute(name: string, value: string | null): boolean {
-  const normalizedName = name.trim().toLowerCase();
-  if (!normalizedName || normalizedName.startsWith("on") || normalizedName === "srcdoc") {
-    return false;
-  }
-  if (value === null || !URL_ATTRIBUTES.has(normalizedName)) return true;
-  const normalizedValue = value.replace(/[\u0000-\u0020]+/g, "").toLowerCase();
-  if (normalizedValue.startsWith("javascript:")) return false;
-  if (!normalizedValue.startsWith("data:")) return true;
-  const mediaType = normalizedValue.slice(5).split(/[;,]/, 1)[0];
-  return SAFE_DATA_URL_MEDIA_TYPES.has(mediaType);
-}
+// Reassertion bypasses the normal application chokepoint, so remember mutation
+// objects rejected by the price guard and never replay them later.
+const priceRejectedMutations = new WeakSet<Mutation>();
+
+export { isSafeMutationAttribute } from "./sanitize";
 
 function sanitizeMutationHtml(html: string): string {
-  const sanitized = sanitizeHtml(html);
-  if (!isStrictJsPolicy()) return sanitized;
-  const template = document.createElement("template");
-  template.innerHTML = sanitized;
-  for (const element of Array.from(template.content.querySelectorAll("*"))) {
-    for (const attribute of Array.from(element.attributes)) {
-      if (!isSafeMutationAttribute(attribute.name, attribute.value)) {
-        element.removeAttribute(attribute.name);
-      }
-    }
-  }
-  return template.innerHTML;
+  return sanitizeHtml(html);
 }
 
 export function normalizeCssPropertyName(name: string): string {
@@ -120,106 +112,206 @@ export function isInsertAction(action: MutationAction): boolean {
   return action === "insertBefore" || action === "insertAfter";
 }
 
-function snapshotMutation(
-  mutation: Mutation,
+function elementReference(element: Element): ElementReference {
+  const WeakRefClass = (globalThis as typeof globalThis & {
+    WeakRef?: new (value: Element) => ElementReference;
+  }).WeakRef;
+  return WeakRefClass ? new WeakRefClass(element) : { deref: () => element };
+}
+
+function mutationAttributeNames(mutation: Mutation): string[] {
+  const names = new Set<string>();
+  if (mutation.attribute) names.add(mutation.attribute.name);
+  Object.keys(mutation.attributes ?? {}).forEach((name) => names.add(name));
+  return Array.from(names);
+}
+
+function canonicalAttributeName(element: Element, name: string): string {
+  const namespace = element.namespaceURI;
+  return namespace === null || namespace === "http://www.w3.org/1999/xhtml"
+    ? name.trim().toLowerCase()
+    : name;
+}
+
+function isContentMutation(mutation: Mutation): boolean {
+  return mutation.action === "html" || mutation.action === "text" || mutation.action === "setText";
+}
+
+function mutationStyleNames(mutation: Mutation): string[] {
+  if (mutation.action !== "style" && mutation.action !== "setStyle") return [];
+  return Object.keys(mutation.styles ?? {}).map(normalizeCssPropertyName);
+}
+
+function captureElementBaseline(
+  journal: MutationJournal,
   element: Element,
-  snapshots: MutationSnapshot[] = mutationSnapshots,
-): void {
-  switch (mutation.action) {
-    case "html":
-      snapshots.push({
-        kind: "content",
-        element,
-        property: "innerHTML",
-        value: element.innerHTML,
-      });
-      break;
-    case "text":
-    case "setText":
-      snapshots.push({
-        kind: "content",
-        element,
-        property: "textContent",
-        value: element.textContent,
-      });
-      break;
-    case "attribute": {
-      const names = new Set<string>();
-      if (mutation.attribute) names.add(mutation.attribute.name);
-      if (mutation.attributes) {
-        Object.keys(mutation.attributes).forEach((name) => names.add(name));
+  mutation: Mutation,
+): ElementBaseline {
+  let baseline = journal.baselines.get(element);
+  if (!baseline) {
+    baseline = {
+      attributeValues: new Map(),
+      contentTouched: false,
+      styleAttributeTouched: false,
+      styleAttributeValue: null,
+      styleValues: new Map(),
+      parent: element.parentNode,
+      nextSibling: element.nextSibling,
+    };
+    journal.baselines.set(element, baseline);
+  }
+
+  const attributeNames = mutationAttributeNames(mutation)
+    .map((name) => canonicalAttributeName(element, name));
+  const styleNames = mutationStyleNames(mutation);
+  let capturedStyleAliasNow = false;
+  if ((!baseline.styleAttributeTouched) &&
+      (styleNames.length > 0 || attributeNames.includes("style"))) {
+    baseline.styleAttributeValue = element.getAttribute("style");
+    baseline.styleAttributeTouched = true;
+    capturedStyleAliasNow = true;
+  }
+  for (const name of attributeNames) {
+    if (!baseline.attributeValues.has(name)) {
+      baseline.attributeValues.set(
+        name,
+        name === "style" && baseline.styleAttributeTouched
+          ? baseline.styleAttributeValue
+          : element.getAttribute(name),
+      );
+    }
+  }
+  if (styleNames.length > 0) {
+    let originalStyle: CSSStyleDeclaration;
+    if (capturedStyleAliasNow) {
+      // This CSSOM is still pristine: the current style mutation has not run.
+      // It also keeps non-DOM Element mocks useful when their attribute and
+      // CSSStyleDeclaration views are not wired together like a browser's.
+      originalStyle = (element as HTMLElement).style;
+    } else if (baseline.styleAttributeTouched) {
+      const originalStyleElement = document.createElement("div");
+      const originalStyleAttribute = baseline.styleAttributeValue;
+      if (originalStyleAttribute !== null && originalStyleAttribute !== undefined) {
+        originalStyleElement.setAttribute("style", originalStyleAttribute);
       }
-      snapshots.push({
-        kind: "attribute",
-        element,
-        values: Array.from(names).map((name) => ({
-          name,
-          value: element.getAttribute(name),
-        })),
-      });
-      break;
+      originalStyle = originalStyleElement.style;
+    } else {
+      originalStyle = (element as HTMLElement).style;
     }
-    case "style":
-    case "setStyle": {
-      const style = (element as HTMLElement).style;
-      const names = Object.keys(mutation.styles ?? {}).map(normalizeCssPropertyName);
-      snapshots.push({
-        kind: "style",
-        element: element as HTMLElement,
-        values: names.map((name) => ({
-          name,
-          value: style.getPropertyValue(name),
-          priority: style.getPropertyPriority(name),
-        })),
-      });
-      break;
+    for (const name of styleNames) {
+      if (!baseline.styleValues.has(name)) {
+        baseline.styleValues.set(name, {
+          value: originalStyle.getPropertyValue(name),
+          priority: originalStyle.getPropertyPriority(name),
+        });
+      }
     }
-    case "remove":
-      snapshots.push({
-        kind: "remove",
-        element,
-        parent: element.parentNode,
-        nextSibling: element.nextSibling,
-      });
-      break;
   }
+  if (
+    !baseline.contentTouched &&
+    isContentMutation(mutation)
+  ) {
+    if (typeof element.innerHTML === "string") baseline.innerHTML = element.innerHTML;
+    baseline.textContent = element.textContent;
+    baseline.contentTouched = true;
+  }
+  return baseline;
 }
 
-function restoreSnapshot(snapshot: MutationSnapshot): void {
-  switch (snapshot.kind) {
-    case "content":
-      if (snapshot.property === "innerHTML") {
-        snapshot.element.innerHTML = snapshot.value ?? "";
-      } else {
-        snapshot.element.textContent = snapshot.value;
-      }
-      break;
-    case "attribute":
-      for (const { name, value } of snapshot.values) {
-        if (value === null) snapshot.element.removeAttribute(name);
-        else snapshot.element.setAttribute(name, value);
-      }
-      break;
-    case "style":
-      for (const { name, value, priority } of snapshot.values) {
-        if (value) snapshot.element.style.setProperty(name, value, priority);
-        else snapshot.element.style.removeProperty(name);
-      }
-      break;
-    case "remove":
-      if (!snapshot.parent || snapshot.element.parentNode) return;
-      try {
-        snapshot.parent.insertBefore(snapshot.element, snapshot.nextSibling);
-      } catch {
-        snapshot.parent.appendChild(snapshot.element);
-      }
-      break;
-    case "insert":
-      for (const node of snapshot.nodes) node.parentNode?.removeChild(node);
-      break;
+type BaselineRestoreScope = {
+  attributes: Set<string>;
+  content: boolean;
+  position: boolean;
+  styles: Set<string>;
+};
+
+function restoreScopeForEntry(
+  scope: BaselineRestoreScope,
+  element: Element,
+  entry: MutationJournalEntry,
+): void {
+  if (entry.kind !== "mutation") return;
+  scope.position = true;
+  if (isContentMutation(entry.mutation)) scope.content = true;
+  mutationAttributeNames(entry.mutation)
+    .forEach((name) => scope.attributes.add(canonicalAttributeName(element, name)));
+  mutationStyleNames(entry.mutation).forEach((name) => scope.styles.add(name));
+}
+
+function restoreElementBaseline(
+  element: Element,
+  baseline: ElementBaseline,
+  scope: BaselineRestoreScope,
+): void {
+  if (scope.position && baseline.parent && !element.parentNode) {
+    try {
+      baseline.parent.insertBefore(element, baseline.nextSibling);
+    } catch {
+      baseline.parent.appendChild(element);
+    }
+  }
+  if (scope.content && baseline.contentTouched) {
+    if (baseline.innerHTML !== undefined) element.innerHTML = baseline.innerHTML;
+    else if (baseline.textContent !== undefined) element.textContent = baseline.textContent;
+  }
+  const style = (element as HTMLElement).style;
+  for (const name of scope.styles) {
+    const valueAndPriority = baseline.styleValues.get(name);
+    if (!valueAndPriority) continue;
+    const { value, priority } = valueAndPriority;
+    if (value) style.setProperty(name, value, priority);
+    else style.removeProperty(name);
+  }
+  // Restore attributes after CSSOM properties so a tracked `style` attribute
+  // preserves its pristine spelling as well as its pristine declarations.
+  for (const name of scope.attributes) {
+    if (!baseline.attributeValues.has(name)) continue;
+    const value = baseline.attributeValues.get(name);
+    if (value === null) element.removeAttribute(name);
+    else if (value !== undefined) element.setAttribute(name, value);
   }
 }
 
+function artifactIdentity(
+  journal: MutationJournal,
+  ownerKeys: readonly string[],
+  artifactId?: string,
+): string {
+  return artifactId ?? ownerKeys[0] ?? journal.fallbackArtifactId;
+}
+
+function appendJournalEntry(
+  journal: MutationJournal,
+  mutation: Mutation,
+  element: Element,
+  targetIndex: number,
+  ownerKeys: readonly string[],
+  artifactId: string | undefined,
+  kind: MutationJournalEntry["kind"],
+  epoch: number,
+  insertKey?: string,
+  nodes?: Node[],
+): MutationJournalEntry {
+  const entry: MutationJournalEntry = {
+    seq: ++journalSequence,
+    artifactId: artifactIdentity(journal, ownerKeys, artifactId),
+    owners: new Set(ownerKeys),
+    target: {
+      selector: mutation.selector,
+      index: targetIndex,
+      el: elementReference(element),
+    },
+    mutation,
+    epoch,
+    kind,
+    insertKey,
+    nodes,
+    state: "applied",
+  };
+  journal.entries.push(entry);
+  return entry;
+}
+
 export function applyToElement(mutation: Mutation, element: Element): void {
   switch (mutation.action) {
     case "html":
@@ -231,8 +323,7 @@ export function applyToElement(mutation: Mutation, element: Element): void {
       break;
     case "attribute":
       if (mutation.attribute) {
-        if (!isStrictJsPolicy() ||
-            isSafeMutationAttribute(mutation.attribute.name, mutation.attribute.value)) {
+        if (isSafeMutationAttribute(mutation.attribute.name, mutation.attribute.value)) {
           if (mutation.attribute.value === null) {
             element.removeAttribute(mutation.attribute.name);
           } else {
@@ -242,7 +333,7 @@ export function applyToElement(mutation: Mutation, element: Element): void {
       }
       if (mutation.attributes) {
         for (const [name, value] of Object.entries(mutation.attributes)) {
-          if (isStrictJsPolicy() && !isSafeMutationAttribute(name, value)) continue;
+          if (!isSafeMutationAttribute(name, value)) continue;
           if (value === null) element.removeAttribute(name);
           else element.setAttribute(name, value);
         }
@@ -287,74 +378,226 @@ export function markInserted(el: Element, key: string): void {
   (el as HTMLElement).setAttribute(INSERT_ATTR, key);
 }
 
-function applyTrackedMutationWithSnapshots(
+function collectInsertedNodes(mutation: Mutation, element: Element): Node[] {
+  const parent = element.parentNode;
+  if (!parent || typeof mutation.html !== "string") return [];
+  const previousSibling = element.previousSibling;
+  const nextSibling = element.nextSibling;
+  applyToElement(mutation, element);
+  const nodes: Node[] = [];
+  let current = mutation.action === "insertBefore"
+    ? (previousSibling ? previousSibling.nextSibling : parent.firstChild)
+    : element.nextSibling;
+  const boundary = mutation.action === "insertBefore" ? element : nextSibling;
+  while (current && current !== boundary) {
+    nodes.push(current);
+    current = current.nextSibling;
+  }
+  return nodes;
+}
+
+function insertedElements(nodes: readonly Node[]): Element[] {
+  return nodes.filter((node): node is Element => node instanceof Element);
+}
+
+function adoptedInsertNodes(
+  journal: MutationJournal,
+  element: Element,
+  key: string,
+): Node[] {
+  for (let index = journal.entries.length - 1; index >= 0; index -= 1) {
+    const entry = journal.entries[index];
+    if (
+      entry.insertKey === key &&
+      entry.target.el.deref() === element &&
+      entry.nodes?.some((node) => node.parentNode)
+    ) {
+      return entry.nodes;
+    }
+  }
+  const parent = element.parentElement;
+  if (!parent) return [];
+  return Array.from(parent.querySelectorAll("[" + INSERT_ATTR + "]")).filter(
+    (candidate) => candidate.getAttribute(INSERT_ATTR) === key,
+  );
+}
+
+function applyTrackedMutationWithJournal(
   mutation: Mutation,
   element: Element,
-  snapshots: MutationSnapshot[],
+  journal: MutationJournal,
   key?: string,
-): Element | null {
+  ownerKeys: readonly string[] = [],
+  artifactId?: string,
+  targetIndex = 0,
+  epoch = 0,
+): { inserted: Element | null; entry?: MutationJournalEntry } {
   return runMuted(() => {
+    captureElementBaseline(journal, element, mutation);
     if (isInsertAction(mutation.action)) {
-      const parent = element.parentNode;
-      if (!parent || typeof mutation.html !== "string") return null;
-      const previousSibling = element.previousSibling;
-      const nextSibling = element.nextSibling;
-      applyToElement(mutation, element);
-      const insertedNodes: Node[] = [];
-      let current = mutation.action === "insertBefore"
-        ? (previousSibling ? previousSibling.nextSibling : parent.firstChild)
-        : element.nextSibling;
-      const boundary = mutation.action === "insertBefore" ? element : nextSibling;
-      while (current && current !== boundary) {
-        insertedNodes.push(current);
-        current = current.nextSibling;
-      }
-      const insertedElements = insertedNodes.filter(
-        (node): node is Element => node instanceof Element,
+      const nodes = collectInsertedNodes(mutation, element);
+      const elements = insertedElements(nodes);
+      if (key) elements.forEach((inserted) => markInserted(inserted, key));
+      if (!nodes.length) return { inserted: null };
+      const entry = appendJournalEntry(
+        journal,
+        mutation,
+        element,
+        targetIndex,
+        ownerKeys,
+        artifactId,
+        "insert",
+        epoch,
+        key,
+        nodes,
       );
-      if (key) insertedElements.forEach((inserted) => markInserted(inserted, key));
-      if (insertedNodes.length) snapshots.push({ kind: "insert", nodes: insertedNodes });
-      return insertedElements[0] ?? null;
+      return { inserted: elements[0] ?? null, entry };
     }
-    snapshotMutation(mutation, element, snapshots);
+    const entry = appendJournalEntry(
+      journal,
+      mutation,
+      element,
+      targetIndex,
+      ownerKeys,
+      artifactId,
+      "mutation",
+      epoch,
+    );
     applyToElement(mutation, element);
-    return null;
+    return { inserted: null, entry };
   });
 }
 
-export function applyTrackedMutation(mutation: Mutation, element: Element, key?: string): Element | null {
-  return applyTrackedMutationWithSnapshots(mutation, element, mutationSnapshots, key);
+export function applyTrackedMutation(
+  mutation: Mutation,
+  element: Element,
+  key?: string,
+  ownerKeys: readonly string[] = [],
+  artifactId?: string,
+  onJournal?: (entry: MutationJournalEntry) => void,
+  epoch = 0,
+): Element | null {
+  let targetIndex = 0;
+  try {
+    targetIndex = queryAllDeep(mutation.selector).indexOf(element);
+    if (targetIndex < 0) targetIndex = 0;
+  } catch {}
+  if (key && isInsertAction(mutation.action) && isInsertDuplicate(element, key)) {
+    const nodes = adoptedInsertNodes(mutationJournal, element, key);
+    const entry = appendJournalEntry(
+      mutationJournal,
+      mutation,
+      element,
+      targetIndex,
+      ownerKeys,
+      artifactId,
+      "adopt-insert",
+      epoch,
+      key,
+      nodes,
+    );
+    onJournal?.(entry);
+    return insertedElements(nodes)[0] ?? null;
+  }
+  const result = applyTrackedMutationWithJournal(
+    mutation,
+    element,
+    mutationJournal,
+    key,
+    ownerKeys,
+    artifactId,
+    targetIndex,
+    epoch,
+  );
+  if (result.entry) onJournal?.(result.entry);
+  return result.inserted;
+}
+
+/** Reject a just-applied guarded mutation without disturbing earlier treatments. */
+export function rejectTrackedMutation(
+  entry: MutationJournalEntry | undefined,
+  element: Element,
+  innerHTML: string,
+): void {
+  runMuted(() => { element.innerHTML = innerHTML; });
+  if (!entry) return;
+  priceRejectedMutations.add(entry.mutation);
+  entry.state = "invalidated";
+  mutationJournal.entries = mutationJournal.entries.filter((candidate) => candidate !== entry);
+  // Fail closed at mutation level: a price-violating mutation is suppressed on
+  // every element, so already-applied sibling targets roll back instead of
+  // drifting outside reassert coverage.
+  const doomed = new Set(
+    mutationJournal.entries.filter((candidate) => candidate.mutation === entry.mutation),
+  );
+  for (const candidate of doomed) candidate.state = "invalidated";
+  if (doomed.size > 0) rollbackJournalEntries(mutationJournal, doomed);
 }
 
-// Every pre-apply innerHTML captured for the element's html mutations. The
-// reassert sentinel uses these to attribute subtree changes: a framework
-// hydration revert restores one of these pre-states (the server original,
-// or — for stacked treatments — an earlier treatment's content), while
-// variant-owned widget activity produces content none of them ever had.
+// The sentinel treats the baseline and earlier journal values as framework
+// restore targets. Other content can be variant-owned widget state.
 export function matchesOriginalInnerHtmlSnapshot(element: Element, current: string): boolean {
-  for (const snapshot of mutationSnapshots) {
-    if (
-      snapshot.kind === "content" &&
-      snapshot.element === element &&
-      snapshot.property === "innerHTML" &&
-      typeof snapshot.value === "string"
-    ) {
-      if (snapshot.value === current) return true;
+  if (mutationJournal.baselines.get(element)?.innerHTML === current) return true;
+  for (const entry of mutationJournal.entries) {
+    if (entry.target.el.deref() !== element || entry.mutation.action !== "html") continue;
+    if (typeof entry.mutation.html === "string" && sanitizeMutationHtml(entry.mutation.html) === current) {
+      return true;
     }
   }
   return false;
 }
 
-function applyMutationsWithSnapshots(
+function applyPriceGuardedMutation(
+  mutation: Mutation,
+  element: Element,
+  journal: MutationJournal,
+  key: string,
+  options: ApplyOptions,
+  index: number,
+  targetIndex: number,
+): void {
+  const guardedPrices = extractCurrencyTokens(element.textContent ?? "");
+  const guardedSnapshot = guardedPrices.length > 0 ? element.innerHTML : null;
+  const result = applyTrackedMutationWithJournal(
+    mutation,
+    element,
+    journal,
+    key,
+    options.ownerKeys,
+    options.artifactId,
+    targetIndex,
+    options.epoch ?? 0,
+  );
+  if (guardedSnapshot !== null) {
+    const remaining = extractCurrencyTokens(element.textContent ?? "");
+    const preserved = guardedPrices.every((token) =>
+      remaining.some((candidate) =>
+        candidate.symbol === token.symbol && candidate.cents === token.cents));
+    if (!preserved) {
+      rejectTrackedMutation(result.entry, element, guardedSnapshot);
+      options.onPricePreservationViolation?.({
+        mutation,
+        selector: mutation.selector,
+        originalPriceTokens: guardedPrices,
+      });
+      return;
+    }
+  }
+  options.onApplied?.(mutation, element, index, result.entry?.seq);
+}
+
+function applyMutationsWithJournal(
   mutations: Mutation[],
   options: ApplyOptions,
-  snapshots: MutationSnapshot[],
+  journal: MutationJournal,
 ): void {
   const root = options.root || document;
   mutations.forEach((mutation, index) => {
-    let elements: NodeListOf<Element>;
+    let elements: Element[];
     try {
-      elements = root.querySelectorAll(mutation.selector);
+      elements = root === document
+        ? queryAllDeep(mutation.selector)
+        : Array.from(root.querySelectorAll(mutation.selector));
     } catch {
       options.onMiss?.(mutation, index);
       return;
@@ -363,29 +606,77 @@ function applyMutationsWithSnapshots(
       options.onMiss?.(mutation, index);
       return;
     }
-    elements.forEach((element) => {
+    elements.forEach((element, targetIndex) => {
       const key = getMutationKey(mutation, index);
       if (isInsertAction(mutation.action)) {
-        if (isInsertDuplicate(element, key)) return;
-        applyTrackedMutationWithSnapshots(mutation, element, snapshots, key);
-        options.onApplied?.(mutation, element, index);
+        if (isInsertDuplicate(element, key)) {
+          const entry = appendJournalEntry(
+            journal,
+            mutation,
+            element,
+            targetIndex,
+            options.ownerKeys ?? [],
+            options.artifactId,
+            "adopt-insert",
+            options.epoch ?? 0,
+            key,
+            adoptedInsertNodes(journal, element, key),
+          );
+          options.onApplied?.(mutation, element, index, entry.seq);
+          return;
+        }
+        const result = applyTrackedMutationWithJournal(
+          mutation,
+          element,
+          journal,
+          key,
+          options.ownerKeys,
+          options.artifactId,
+          targetIndex,
+          options.epoch ?? 0,
+        );
+        options.onApplied?.(mutation, element, index, result.entry?.seq);
         return;
       }
-      applyTrackedMutationWithSnapshots(mutation, element, snapshots, key);
-      options.onApplied?.(mutation, element, index);
+      // Content changes are guarded; hiding or styling a price element can be
+      // a legitimate compare-at-price treatment and is intentionally allowed.
+      const priceBearingContent = mutation.action === "html"
+        || mutation.action === "text"
+        || mutation.action === "setText";
+      if (options.preservePrices && !options.priceTestExempt && priceBearingContent) {
+        applyPriceGuardedMutation(mutation, element, journal, key, options, index, targetIndex);
+        return;
+      }
+      const result = applyTrackedMutationWithJournal(
+        mutation,
+        element,
+        journal,
+        key,
+        options.ownerKeys,
+        options.artifactId,
+        targetIndex,
+        options.epoch ?? 0,
+      );
+      options.onApplied?.(mutation, element, index, result.entry?.seq);
     });
   });
 }
 
 export function applyMutations(mutations: Mutation[], options: ApplyOptions = {}): void {
-  applyMutationsWithSnapshots(mutations, options, mutationSnapshots);
+  applyMutationsWithJournal(mutations, options, mutationJournal);
 }
 
 export function reassertNonStructuralMutations(mutations: Mutation[], options: ApplyOptions = {}): void {
   const root = options.root || document;
   mutations.forEach((mutation, index) => {
-    if (isInsertAction(mutation.action) || mutation.action === "remove") return;
-    const elements = root.querySelectorAll(mutation.selector);
+    if (
+      isInsertAction(mutation.action)
+      || mutation.action === "remove"
+      || priceRejectedMutations.has(mutation)
+    ) return;
+    const elements = root === document
+      ? queryAllDeep(mutation.selector)
+      : Array.from(root.querySelectorAll(mutation.selector));
     elements.forEach((element) => {
       runMuted(() => applyToElement(mutation, element));
       options.onApplied?.(mutation, element, index);
@@ -393,14 +684,231 @@ export function reassertNonStructuralMutations(mutations: Mutation[], options: A
   });
 }
 
-export function resetAppliedMutations(): void {
-  resetReassertSentinel();
+function resolveJournalTarget(
+  journal: MutationJournal,
+  entry: MutationJournalEntry,
+): Element | undefined {
+  const current = entry.target.el.deref();
+  if (current && (entry.mutation.action === "remove" || current.isConnected !== false)) {
+    return current;
+  }
+  try {
+    const replacement = queryAllDeep(entry.target.selector)[entry.target.index];
+    if (replacement) {
+      captureElementBaseline(journal, replacement, entry.mutation);
+      entry.target.el = elementReference(replacement);
+      return replacement;
+    }
+  } catch {}
+  return current;
+}
+
+function replayInsertEntry(
+  journal: MutationJournal,
+  entry: MutationJournalEntry,
+  element: Element,
+): void {
+  const key = entry.insertKey;
+  if (key && isInsertDuplicate(element, key)) {
+    entry.nodes = adoptedInsertNodes(journal, element, key);
+    entry.kind = "adopt-insert";
+    entry.state = "applied";
+    return;
+  }
+  const nodes = collectInsertedNodes(entry.mutation, element);
+  if (key) insertedElements(nodes).forEach((inserted) => markInserted(inserted, key));
+  entry.nodes = nodes;
+  entry.kind = "insert";
+  entry.state = "applied";
+}
+
+function replayTouchedTargets(
+  journal: MutationJournal,
+  touched: Set<Element>,
+  restoreScopes: Map<Element, BaselineRestoreScope>,
+): void {
+  for (const [element, scope] of restoreScopes) {
+    const baseline = journal.baselines.get(element);
+    if (baseline) restoreElementBaseline(element, baseline, scope);
+  }
+  for (const entry of journal.entries) {
+    const element = resolveJournalTarget(journal, entry);
+    if (!element || !touched.has(element)) continue;
+    if (entry.kind === "insert" || entry.kind === "adopt-insert") {
+      replayInsertEntry(journal, entry, element);
+    } else {
+      applyToElement(entry.mutation, element);
+      entry.state = "applied";
+      replayReassertSentinelEntry(entry.seq, element);
+    }
+  }
+}
+
+function addRestoreScope(
+  scopes: Map<Element, BaselineRestoreScope>,
+  element: Element,
+  entry: MutationJournalEntry,
+): void {
+  let scope = scopes.get(element);
+  if (!scope) {
+    scope = { attributes: new Set(), content: false, position: false, styles: new Set() };
+    scopes.set(element, scope);
+  }
+  restoreScopeForEntry(scope, element, entry);
+}
+
+function pruneElementBaseline(journal: MutationJournal, element: Element): void {
+  const baseline = journal.baselines.get(element);
+  if (!baseline) return;
+  const remaining = journal.entries.filter((entry) => entry.target.el.deref() === element);
+  if (remaining.length === 0) {
+    journal.baselines.delete(element);
+    return;
+  }
+  const contentNeeded = remaining.some((entry) =>
+    entry.kind === "mutation" && isContentMutation(entry.mutation));
+  if (!contentNeeded) {
+    baseline.contentTouched = false;
+    delete baseline.innerHTML;
+    delete baseline.textContent;
+  }
+  const attributeNames = new Set(remaining.flatMap((entry) =>
+    entry.kind === "mutation"
+      ? mutationAttributeNames(entry.mutation).map((name) => canonicalAttributeName(element, name))
+      : []));
+  for (const name of baseline.attributeValues.keys()) {
+    if (!attributeNames.has(name)) baseline.attributeValues.delete(name);
+  }
+  const styleNames = new Set(remaining.flatMap((entry) =>
+    entry.kind === "mutation" ? mutationStyleNames(entry.mutation) : []));
+  for (const name of baseline.styleValues.keys()) {
+    if (!styleNames.has(name)) baseline.styleValues.delete(name);
+  }
+  if (!attributeNames.has("style") && styleNames.size === 0) {
+    baseline.styleAttributeTouched = false;
+    baseline.styleAttributeValue = null;
+  }
+}
+
+function rollbackJournalEntries(
+  journal: MutationJournal,
+  doomed: Set<MutationJournalEntry>,
+  options: { preserveReplacementTargets?: boolean } = {},
+): void {
+  if (doomed.size === 0) return;
+  const touched = new Set<Element>();
+  const restoreScopes = new Map<Element, BaselineRestoreScope>();
+  for (const entry of doomed) {
+    // A teardown owns the exact node Apex mutated, not a later framework node
+    // that happens to match the same selector/index. SPA frameworks commonly
+    // replace route subtrees before reInit() reconciles Page activation. Using
+    // resolveJournalTarget() here would adopt that replacement and restore the
+    // old route's baseline into it (innerHTML/textContent included), detaching
+    // the framework's listeners. When the selector now resolves to a different
+    // node, the disconnected target has been retired and needs no rollback.
+    const element = options.preserveReplacementTargets
+      ? entry.target.el.deref()
+      : resolveJournalTarget(journal, entry);
+    let supersededByFrameworkNode = false;
+    if (options.preserveReplacementTargets && element?.isConnected === false) {
+      try {
+        const current = document.querySelectorAll(entry.target.selector)[entry.target.index];
+        supersededByFrameworkNode = Boolean(current && current !== element);
+      } catch {}
+    }
+    if (element && !supersededByFrameworkNode) {
+      touched.add(element);
+      addRestoreScope(restoreScopes, element, entry);
+    }
+  }
+  for (let index = journal.entries.length - 1; index >= 0; index -= 1) {
+    if (doomed.has(journal.entries[index])) journal.entries.splice(index, 1);
+  }
   runMuted(() => {
-    for (let i = mutationSnapshots.length - 1; i >= 0; i -= 1) {
-      restoreSnapshot(mutationSnapshots[i]);
+    for (const entry of doomed) {
+      for (const node of entry.nodes ?? []) {
+        const survives = journal.entries.some((candidate) => candidate.nodes?.includes(node));
+        if (!survives) node.parentNode?.removeChild(node);
+      }
     }
+    replayTouchedTargets(journal, touched, restoreScopes);
   });
-  mutationSnapshots.length = 0;
+  touched.forEach((element) => pruneElementBaseline(journal, element));
+}
+
+function resetJournal(journal: MutationJournal): void {
+  const doomed = new Set(journal.entries);
+  rollbackJournalEntries(journal, doomed);
+  journal.baselines = new WeakMap();
+}
+
+export function resetAppliedMutations(): void {
+  resetReassertSentinel();
+  resetJournal(mutationJournal);
+}
+
+export function resetAppliedMutationsForOwner(
+  ownerKey: string,
+  artifactId?: string,
+  options: { preserveReplacementTargets?: boolean } = {},
+): void {
+  const doomed = new Set<MutationJournalEntry>();
+  for (const entry of mutationJournal.entries) {
+    if (artifactId !== undefined && entry.artifactId !== artifactId) continue;
+    if (!entry.owners.delete(ownerKey)) continue;
+    if (entry.owners.size === 0) doomed.add(entry);
+  }
+  resetReassertSentinelForOwner(ownerKey, artifactId);
+  rollbackJournalEntries(mutationJournal, doomed, options);
+}
+
+export function addAppliedMutationOwners(
+  existingOwnerKeys: ReadonlySet<string>,
+  ownerKeys: readonly string[],
+  artifactId?: string,
+): void {
+  if (existingOwnerKeys.size === 0 || ownerKeys.length === 0) return;
+  for (const entry of mutationJournal.entries) {
+    if (artifactId !== undefined && entry.artifactId !== artifactId) continue;
+    if (
+      !Array.from(existingOwnerKeys).some((ownerKey) =>
+        entry.owners.has(ownerKey)
+      )
+    ) continue;
+    ownerKeys.forEach((ownerKey) => entry.owners.add(ownerKey));
+  }
+  addReassertSentinelOwners(existingOwnerKeys, ownerKeys, artifactId);
+}
+
+export function invalidateArtifact(artifactId: string): void {
+  mutationJournal.entries.forEach((entry) => {
+    if (entry.artifactId === artifactId) entry.state = "invalidated";
+  });
+}
+
+export function replayArtifact(artifactId: string): void {
+  const selected = mutationJournal.entries.filter((entry) => entry.artifactId === artifactId);
+  if (!selected.length) return;
+  const touched = new Set<Element>();
+  const restoreScopes = new Map<Element, BaselineRestoreScope>();
+  for (const entry of selected) {
+    entry.state = "invalidated";
+    const element = resolveJournalTarget(mutationJournal, entry);
+    if (element) {
+      touched.add(element);
+      addRestoreScope(restoreScopes, element, entry);
+    }
+  }
+  runMuted(() => replayTouchedTargets(mutationJournal, touched, restoreScopes));
+}
+
+export function replayForOwner(ownerKey: string): void {
+  const artifactIds = new Set(
+    mutationJournal.entries
+      .filter((entry) => entry.owners.has(ownerKey))
+      .map((entry) => entry.artifactId),
+  );
+  artifactIds.forEach(replayArtifact);
 }
 
 export type MutationApplicationContext = {
@@ -410,32 +918,33 @@ export type MutationApplicationContext = {
 };
 
 /**
- * Owns only the DOM snapshots created through this context. Rolling it back
- * restores the state that existed immediately before its mutations, without
- * touching shopper assignment mutations tracked by the main SDK runtime.
+ * Owns only the journal entries created through this context. Rollback
+ * restores its baseline without touching shopper assignment entries.
  */
 export function createMutationApplicationContext(): MutationApplicationContext {
-  const snapshots: MutationSnapshot[] = [];
+  const journal: MutationJournal = {
+    entries: [],
+    baselines: new WeakMap(),
+    fallbackArtifactId: "context-" + ++applicationContextSequence,
+  };
   return {
     apply(mutations, options = {}) {
-      applyMutationsWithSnapshots(mutations, options, snapshots);
+      applyMutationsWithJournal(mutations, options, journal);
     },
     rollback() {
-      runMuted(() => {
-        for (let i = snapshots.length - 1; i >= 0; i -= 1) {
-          restoreSnapshot(snapshots[i]);
-        }
-      });
-      snapshots.length = 0;
+      resetJournal(journal);
     },
     get snapshotCount() {
-      return snapshots.length;
+      return journal.entries.length;
     },
   };
 }
 
 /** @internal — exposed for unit testing only. Tree-shaken from production build. */
 export const __test = {
+  baselineAttributeNames(element: Element): string[] {
+    return Array.from(mutationJournal.baselines.get(element)?.attributeValues.keys() ?? []);
+  },
   normalizeCssPropertyName,
 };