hyperclayjs 1.27.1 → 1.28.2

package/README.md

@@ -87,7 +87,7 @@ import 'hyperclayjs/presets/standard.js';
 | Module | Size | Description |
 |--------|------|-------------|
 | dialogs | 8.5KB | ask(), consent(), tell(), snippet() dialog functions |
-| the-modal | 22.5KB | Full modal window creation system - window.theModal |
+| the-modal | 22.8KB | Full modal window creation system - window.theModal |
 | toast | 15.8KB | Success/error message notifications, toast(msg, msgType) |
 
 ### Utilities (Core utilities (often auto-included))
@@ -97,7 +97,7 @@ import 'hyperclayjs/presets/standard.js';
 | cache-bust | 0.6KB | Cache-bust href/src attributes |
 | cookie | 1.4KB | Cookie management (often auto-included) |
 | debounce | 0.7KB | Function debouncing |
-| mutation | 13.8KB | DOM mutation observation (often auto-included) |
+| mutation | 14.7KB | DOM mutation observation (often auto-included) |
 | nearest | 3.4KB | Find nearest elements (often auto-included) |
 | throttle | 1.3KB | Function throttling |
 
@@ -123,14 +123,15 @@ import 'hyperclayjs/presets/standard.js';
 | Module | Size | Description |
 |--------|------|-------------|
 | file-upload | 11.3KB | File upload with progress |
-| live-sync | 15.5KB | Real-time DOM sync across browsers |
+| live-sync | 25.3KB | Real-time DOM sync across browsers |
 | send-message | 1.3KB | Message sending utility |
 
 ### Vendor Libraries (Third-party libraries)
 
 | Module | Size | Description |
 |--------|------|-------------|
-| hyper-morph | 17.2KB | DOM morphing with content-based element matching |
+| hyper-morph | 18.7KB | DOM morphing with content-based element matching |
+| hypercms | 88.7KB | Live edit-in-place CMS sidebar driven by a hyper-html-api rules tag. Pairs with [sortable] and [hyper-morph]. |
 
 ## Presets
 
@@ -144,7 +145,7 @@ Standard feature set for most use cases
 
 **Modules:** `save-core`, `snapshot`, `save-system`, `unsaved-warning`, `edit-mode-helpers`, `persist`, `option-visibility`, `event-attrs`, `dom-helpers`, `toast`, `save-toast`, `export-to-window`, `view-mode-excludes-edit-modules`
 
-### Everything (~236.1KB)
+### Everything (~337.3KB)
 All available features
 
 Includes all available modules across all categories.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperclayjs",
-  "version": "1.27.1",
+  "version": "1.28.2",
   "description": "Modular JavaScript library for building interactive malleable HTML files with Hyperclay",
   "type": "module",
   "main": "src/hyperclay.js",

package/src/communication/live-sync.js

@@ -50,16 +50,31 @@ class LiveSync {
     // High-water mark of server seqs we've seen on this channel (own echoes
     // count too). Server-broadcast payloads carry a monotonic seq
     // (Date.now()-based). We drop anything <= this to guard against rare
-    // cases where a stale message lands after a newer one — e.g. buffered
+    // cases where a stale message lands after a newer one, e.g. buffered
     // replay, alt backend after reconnect, or an own-save echo arriving
     // after a peer's newer broadcast.
     this.lastSeenSeq = 0;
 
-    // Promise chain used to serialize overlapping applyUpdate() calls.
-    // A morph with external scripts returns a Promise; without chaining, two
-    // SSE events arriving back-to-back would interleave their morphs on the
-    // same DOM.
-    this._applyChain = Promise.resolve();
+    // rAF-paced single-flight queue. Incoming updates overwrite a pending
+    // slot; on each animation frame, if a slot is set and no morph is in
+    // flight, run one morph against the latest pending payload. Burst
+    // arrivals collapse to one morph per frame, keeping the receiver from
+    // falling behind under load. A morph with external scripts returns a
+    // Promise, so the in-flight flag prevents overlap.
+    this._pendingHtml = null;
+    this._pendingSeq = null;
+    this._pendingIdentityMap = null;
+    this._morphInFlight = false;
+    this._rafHandle = null;
+
+    // Identity tracking for content-based morphing across live-sync updates.
+    // Synthetic IDs (`<clientId>:<counter>`) live here only — never written to
+    // the DOM, never serialized into saved HTML. The WeakMap holds them
+    // against the live elements so that the next save can produce the same
+    // identityMap, and afterNodeMorphed transfers IDs from incoming parsed
+    // elements onto the live elements they morphed into.
+    this.idCounter = this._loadIdCounter();
+    this.liveWeakMap = new WeakMap();
 
     // Callbacks
     this.onConnect = null;
@@ -127,7 +142,6 @@ class LiveSync {
     // Reset state for new connection
     this.lastHtml = null;
     this.lastSeenSeq = 0;
-    this._applyChain = Promise.resolve();
 
     console.log('[LiveSync] Starting for:', this.currentFile);
     this.connect();
@@ -150,6 +164,149 @@ class LiveSync {
     }
 
     clearTimeout(this.debounceTimer);
+
+    // Cancel any pending frame and clear the queue. A morph already in
+    // flight cannot be aborted; the isDestroyed check in _runPending guards
+    // its post-morph rescheduling so the queue stops cleanly.
+    if (this._rafHandle != null) {
+      this._cancelFrame(this._rafHandle);
+      this._rafHandle = null;
+    }
+    this._pendingHtml = null;
+    this._pendingSeq = null;
+    this._pendingIdentityMap = null;
+  }
+
+  _loadIdCounter() {
+    try {
+      const raw = sessionStorage.getItem('livesync-id-counter');
+      const n = parseInt(raw || '0', 10);
+      return Number.isFinite(n) && n > 0 ? n : 0;
+    } catch (e) {
+      return 0;
+    }
+  }
+
+  _persistIdCounter() {
+    try {
+      sessionStorage.setItem('livesync-id-counter', String(this.idCounter));
+    } catch (e) {
+      // Storage full / sandboxed — fall back to in-memory only.
+    }
+  }
+
+  _mintId() {
+    this.idCounter++;
+    this._persistIdCounter();
+    return `${this.clientId}:${this.idCounter}`;
+  }
+
+  /**
+   * Walk the live DOM and the snapshot clone in lockstep. Path keys come
+   * from the clone (= what the receiver will see, after [snapshot-remove]
+   * and snapshotHooks). WeakMap lookup happens against the live element so
+   * synthetic IDs persist across saves.
+   *
+   * The live walk filters [snapshot-remove] to mirror the clone's earlier
+   * strip in captureSnapshot. If child counts diverge anywhere (an
+   * onbeforesnapshot handler added/removed siblings on the clone), the
+   * subtree is skipped — better to fall back to content scoring there than
+   * emit misaligned IDs.
+   *
+   * @param {Element} liveRoot
+   * @param {Element} cloneRoot
+   * @returns {Object} identityMap keyed by dot-path
+   */
+  _buildIdentityMap(liveRoot, cloneRoot) {
+    const map = {};
+    if (!liveRoot || !cloneRoot) return map;
+
+    const visit = (live, clone, path) => {
+      let id = this.liveWeakMap.get(live);
+      if (!id) {
+        id = this._mintId();
+        this.liveWeakMap.set(live, id);
+      }
+      map[path] = id;
+
+      const liveKids = [];
+      for (const c of live.children) {
+        if (!c.hasAttribute('snapshot-remove')) liveKids.push(c);
+      }
+      const cloneKids = clone.children;
+
+      if (liveKids.length !== cloneKids.length) {
+        this._log(
+          `identity map: subtree skipped at "${path}" (live=${liveKids.length}, clone=${cloneKids.length})`
+        );
+        return;
+      }
+
+      for (let i = 0; i < liveKids.length; i++) {
+        visit(liveKids[i], cloneKids[i], path === '' ? String(i) : `${path}.${i}`);
+      }
+    };
+
+    visit(liveRoot, cloneRoot, '');
+    return map;
+  }
+
+  /**
+   * Walk a single parsed tree, invoking cb(element, path) at each Element.
+   * Paths use the same dot-segment scheme as _buildIdentityMap so the
+   * receiver can look up IDs by the path the sender emitted.
+   */
+  _walkParsedTree(root, cb) {
+    if (!root) return;
+    const visit = (el, path) => {
+      cb(el, path);
+      const kids = el.children;
+      for (let i = 0; i < kids.length; i++) {
+        visit(kids[i], path === '' ? String(i) : `${path}.${i}`);
+      }
+    };
+    visit(root, '');
+  }
+
+  /**
+   * Fill liveWeakMap entries for live elements that the matcher's
+   * afterNodeMorphed didn't reach. createNode's no-id-children
+   * optimization (hyper-morph importNode path) inserts a clone of the
+   * parsed element without invoking morphNode, so afterNodeMorphed never
+   * fires for those subtrees and their synthetic IDs would be lost. On
+   * the receiver's next save, _buildIdentityMap would mint fresh IDs for
+   * the same logical elements, breaking convergence for newly-added
+   * ambiguous siblings — exactly the case identity-map exists to fix.
+   *
+   * Walks live and parsed in lockstep using the same path scheme as
+   * _buildIdentityMap. Filters [snapshot-remove] from the live side to
+   * stay aligned with the sender's clone view. Aborts a subtree on
+   * child-count divergence (e.g. local save-ignore additions) — those
+   * elements fall through to content scoring on the next round, which
+   * is the same fallback as a sender-side lockstep skip.
+   *
+   * @param {Element} liveRoot - post-morph live tree root
+   * @param {Element} parsedRoot - parsed-tree root (still has identityMap WeakMap entries)
+   * @param {Object} identityMap - path → id map from the SSE payload
+   */
+  _fillInIdsAfterMorph(liveRoot, parsedRoot, identityMap) {
+    if (!liveRoot || !parsedRoot || !identityMap) return;
+    const visit = (live, parsed, path) => {
+      const id = identityMap[path];
+      if (id && !this.liveWeakMap.has(live)) {
+        this.liveWeakMap.set(live, id);
+      }
+      const liveKids = [];
+      for (const c of live.children) {
+        if (!c.hasAttribute('snapshot-remove')) liveKids.push(c);
+      }
+      const parsedKids = parsed.children;
+      if (liveKids.length !== parsedKids.length) return;
+      for (let i = 0; i < liveKids.length; i++) {
+        visit(liveKids[i], parsedKids[i], path === '' ? String(i) : `${path}.${i}`);
+      }
+    };
+    visit(liveRoot, parsedRoot, '');
   }
 
   /**
@@ -210,7 +367,7 @@ class LiveSync {
         return;
       }
 
-      const { html, sender, seq } = data;
+      const { html, sender, seq, identityMap } = data;
 
       // Staleness check runs FIRST — compared against the high-water mark of
       // seqs we've seen (own echoes count too, see below). `seq` is optional
@@ -240,8 +397,8 @@ class LiveSync {
       }
 
       this._log(`Received update from: ${sender} (my clientId: ${this.clientId}, seq=${seq})`);
-      this.applyUpdate(html, seq);
-      if (this.onUpdate) this.onUpdate({ html, sender, seq });
+      this.applyUpdate(html, seq, identityMap);
+      if (this.onUpdate) this.onUpdate({ html, sender, seq, identityMap });
     };
 
     // Native EventSource auto-reconnects on transient errors
@@ -268,12 +425,17 @@ class LiveSync {
         return;
       }
 
-      const { documentElement } = event.detail;
-      if (!documentElement) return;
+      const { documentElement: clone } = event.detail;
+      if (!clone) return;
 
+      // Capture both synchronously inside the event handler — captureSnapshot's
+      // caller continues to mutate the clone (strip [save-remove], run hooks)
+      // after dispatchEvent returns, so reading outerHTML and walking children
+      // must happen now.
       this._log('snapshot-ready received, preparing to send');
-      const html = documentElement.outerHTML;
-      this.sendUpdate(html);
+      const html = clone.outerHTML;
+      const identityMap = this._buildIdentityMap(document.documentElement, clone);
+      this.sendUpdate(html, identityMap);
     };
 
     document.addEventListener('hyperclay:snapshot-ready', this._snapshotHandler);
@@ -283,7 +445,7 @@ class LiveSync {
    * Send full HTML to the server (debounced)
    * Only updates lastHtml after successful save
    */
-  sendUpdate(html) {
+  sendUpdate(html, identityMap) {
     clearTimeout(this.debounceTimer);
 
     this.debounceTimer = setTimeout(() => {
@@ -300,7 +462,8 @@ class LiveSync {
         headers: { 'Content-Type': 'application/json', 'Page-URL': window.location.href },
         body: JSON.stringify({
           html: html,
-          sender: this.clientId
+          sender: this.clientId,
+          identityMap: identityMap
         })
       }).then(response => {
         if (response.ok) {
@@ -316,39 +479,96 @@ class LiveSync {
   }
 
   /**
-   * Apply an update received from the server.
-   * Morphs the entire document (head and body).
+   * Apply an update received from the server. Morphs the entire document.
    *
-   * Serialized via a promise chain so concurrent SSE events don't produce
-   * overlapping morphs (morph can return a Promise when external scripts load).
+   * Updates land in a single pending slot. On each animation frame, the
+   * latest pending payload is morphed once; intermediate updates that
+   * arrived between frames are skipped because they would be replaced
+   * milliseconds later anyway. Burst arrivals collapse to roughly one morph
+   * per frame, so the receiver always shows current state instead of
+   * playing back a backlog of stale snapshots.
    *
    * @param {string} html - Full document HTML
    * @param {number} [seq] - Optional monotonic seq from the server
-   * @returns {Promise<void>}
+   * @param {Object} [identityMap] - Optional element-identity map from sender
    */
-  applyUpdate(html, seq) {
-    // Serialize concurrent updates onto a single promise chain. `.catch` on
-    // the combined result both logs the failure (so it isn't a silent
-    // unhandled rejection) AND heals the chain so subsequent updates aren't
-    // blocked by it. `_applyChain` and the returned promise are the same
-    // caught promise — callers that fire-and-forget are safe.
-    const result = this._applyChain
-      .then(() => this._doApplyUpdate(html, seq))
-      .catch((err) => {
-        console.error('[LiveSync] applyUpdate failed:', err);
-      });
-    this._applyChain = result;
-    return result;
+  applyUpdate(html, seq, identityMap) {
+    if (this.isDestroyed) return;
+    this._pendingHtml = html;
+    this._pendingSeq = seq;
+    this._pendingIdentityMap = identityMap;
+    this._scheduleNextFrame();
+  }
+
+  /**
+   * Schedule the next-frame morph if one isn't already pending. Skipped when
+   * a morph is in flight; the morph's post-completion check will reschedule
+   * if a newer payload arrived during it.
+   */
+  _scheduleNextFrame() {
+    if (this.isDestroyed) return;
+    if (this._rafHandle != null) return;
+    if (this._morphInFlight) return;
+    this._rafHandle = this._requestFrame(() => this._runPending());
+  }
+
+  /**
+   * Drain the pending slot once. Errors are caught and logged so a single
+   * failed morph does not stop the queue.
+   */
+  async _runPending() {
+    this._rafHandle = null;
+    if (this.isDestroyed) return;
+
+    const html = this._pendingHtml;
+    const seq = this._pendingSeq;
+    const identityMap = this._pendingIdentityMap;
+    this._pendingHtml = null;
+    this._pendingSeq = null;
+    this._pendingIdentityMap = null;
+    if (html == null) return;
+
+    this._morphInFlight = true;
+    try {
+      await this._doApplyUpdate(html, seq, identityMap);
+    } catch (err) {
+      console.error('[LiveSync] applyUpdate failed:', err);
+    } finally {
+      this._morphInFlight = false;
+    }
+
+    // A newer payload may have arrived during the morph. Schedule another
+    // frame to drain it. Without this, late-arriving updates would sit
+    // forever until the next applyUpdate call.
+    if (!this.isDestroyed && this._pendingHtml != null) {
+      this._scheduleNextFrame();
+    }
+  }
+
+  _requestFrame(cb) {
+    if (typeof window !== 'undefined' && typeof window.requestAnimationFrame === 'function') {
+      return window.requestAnimationFrame(cb);
+    }
+    return setTimeout(cb, 16);
+  }
+
+  _cancelFrame(handle) {
+    if (typeof window !== 'undefined' && typeof window.cancelAnimationFrame === 'function') {
+      window.cancelAnimationFrame(handle);
+      return;
+    }
+    clearTimeout(handle);
   }
 
   /**
-   * Actual morph work. Do not call directly — use applyUpdate() so calls
-   * serialize.
+   * Actual morph work. Do not call directly. Use applyUpdate() so calls
+   * pass through the rAF queue and don't overlap.
    * @param {string} html
    * @param {number} [seq]
+   * @param {Object} [identityMap]
    * @returns {Promise<void>}
    */
-  async _doApplyUpdate(html, seq) {
+  async _doApplyUpdate(html, seq, identityMap) {
     this._log('applyUpdate - pausing mutations and morphing');
     this.isPaused = true;
 
@@ -366,6 +586,32 @@ class LiveSync {
     const parser = new DOMParser();
     const newDoc = parser.parseFromString(html, 'text/html');
 
+    // Build the parsed-tree WeakMap from the incoming identityMap. The
+    // sender emitted paths off its clone, which is exactly what we just
+    // parsed, so the same path scheme indexes into both trees.
+    const parsedWeakMap = new WeakMap();
+    if (identityMap && typeof identityMap === 'object' && !Array.isArray(identityMap)) {
+      this._walkParsedTree(newDoc.documentElement, (el, path) => {
+        const id = identityMap[path];
+        if (id) parsedWeakMap.set(el, id);
+      });
+    }
+
+    const liveWeakMap = this.liveWeakMap;
+    // Priority: synthetic IDs win when present (they're updated after every
+    // morph via afterNodeMorphed). data-id / id is the durable fallback that
+    // covers the bootstrap window and any element that hasn't been paired yet.
+    const key = (el) =>
+      liveWeakMap.get(el) ||
+      parsedWeakMap.get(el) ||
+      (el.getAttribute && el.getAttribute('data-id')) ||
+      el.id ||
+      null;
+    const afterNodeMorphed = (oldEl, newEl) => {
+      const id = parsedWeakMap.get(newEl);
+      if (id) liveWeakMap.set(oldEl, id);
+    };
+
     try {
       // Morph entire document. We MUST await — HyperMorph.morph returns a
       // Promise when `scripts: { handle: true }` needs to wait for external
@@ -376,12 +622,24 @@ class LiveSync {
         morphStyle: 'outerHTML',
         ignoreActiveValue: true,
         head: { style: 'merge' },
-        scripts: { handle: true, matchMode: 'smart' }
+        scripts: { handle: true, matchMode: 'smart' },
+        key,
+        callbacks: { afterNodeMorphed }
       });
 
       // Restore viewport. Done after morph so layout has settled.
       window.scrollTo(scrollX, scrollY);
 
+      // Fill in any IDs the matcher's afterNodeMorphed missed. Brand-new
+      // elements come in via hyper-morph's importNode optimization, which
+      // skips morphNode and thus afterNodeMorphed; their parsedWeakMap IDs
+      // never make it onto liveWeakMap. Without this pass, the receiver
+      // would mint fresh IDs on its next save for those elements,
+      // breaking convergence exactly for newly-added ambiguous siblings.
+      if (identityMap && typeof identityMap === 'object' && !Array.isArray(identityMap)) {
+        this._fillInIdsAfterMorph(document.documentElement, newDoc.documentElement, identityMap);
+      }
+
       // Only mark lastHtml after a successful morph so that a failed apply
       // doesn't desync our state and cause the next outbound save to be
       // mistakenly skipped as "unchanged". Note: lastSeenSeq is advanced at
@@ -449,6 +707,8 @@ if (typeof window !== 'undefined') {
   }
 }
 
-// Export for hyperclayjs module system
-export { liveSync };
+// Export for hyperclayjs module system. The class itself is exported so
+// tests can create fresh instances without driving the singleton's
+// EventSource/snapshot wiring.
+export { liveSync, LiveSync };
 export default liveSync;

package/src/hyperclay.js

@@ -1,7 +1,7 @@
 /**
  * DO NOT EDIT THIS FILE DIRECTLY — it is generated from build/hyperclay.template.js
  *
- * HyperclayJS v1.27.1 - Minimal Browser-Native Loader
+ * HyperclayJS v1.28.2 - Minimal Browser-Native Loader
  *
  * Modules auto-init when imported (no separate init call needed).
  * Include `export-to-window` feature to export to window.hyperclay.
@@ -61,6 +61,7 @@ const MODULE_PATHS = {
   "style-injection": "./dom-utilities/insertStyleTag.js",
   "form-data": "./dom-utilities/getDataFromForm.js",
   "hyper-morph": "./vendor/hyper-morph.vendor.js",
+  "hypercms": "./vendor/hypercms.vendor.js",
   "slugify": "./string-utilities/slugify.js",
   "copy-to-clipboard": "./string-utilities/copy-to-clipboard.js",
   "query-params": "./string-utilities/query.js",
@@ -139,6 +140,7 @@ const PRESETS = {
       "all-js",
       "style-injection",
       "form-data",
+      "hypercms",
       "slugify",
       "copy-to-clipboard",
       "query-params",
@@ -187,6 +189,7 @@ const PRESETS = {
       "style-injection",
       "form-data",
       "hyper-morph",
+      "hypercms",
       "slugify",
       "copy-to-clipboard",
       "query-params",
@@ -337,6 +340,7 @@ export const insertStyleTag = window.hyperclayModules['style-injection']?.insert
 export const getDataFromForm = window.hyperclayModules['form-data']?.getDataFromForm ?? window.hyperclayModules['form-data']?.default;
 export const HyperMorph = window.hyperclayModules['hyper-morph']?.HyperMorph ?? window.hyperclayModules['hyper-morph']?.default;
 export const morph = window.hyperclayModules['hyper-morph']?.morph ?? window.hyperclayModules['hyper-morph']?.default;
+export const cms = window.hyperclayModules['hypercms']?.cms ?? window.hyperclayModules['hypercms']?.default;
 export const slugify = window.hyperclayModules['slugify']?.slugify ?? window.hyperclayModules['slugify']?.default;
 export const copyToClipboard = window.hyperclayModules['copy-to-clipboard']?.copyToClipboard ?? window.hyperclayModules['copy-to-clipboard']?.default;
 export const query = window.hyperclayModules['query-params']?.query ?? window.hyperclayModules['query-params']?.default;

package/src/ui/prompts.js

@@ -114,7 +114,9 @@ export function tell(promptText, ...content) {
  * Display a modal with a code snippet and copy functionality
  * @param {string} title - The modal heading
  * @param {string} content - The code to display
- * @param {string} extraContent - Optional warning/info text below the copy button
+ * @param {string} extraContent - Optional raw HTML rendered below the copy button.
+ *   Callers style their own container; use `<div class="snippet-warning">…</div>`
+ *   for the standard yellow-bordered warning box.
  */
 export function snippet(title, content, extraContent = '') {
 
@@ -126,11 +128,7 @@ export function snippet(title, content, extraContent = '') {
 
     <button type="button" class="micromodal__secondary-btn copy-snippet-btn" style="margin-bottom: 14px;">copy</button>
 
-    ${extraContent ? `
-      <div class="snippet-warning">
-        ${extraContent}
-      </div>
-    ` : ''}
+    ${extraContent || ''}
   `;
 
   // Use the existing modal system

package/src/ui/theModal.js

@@ -530,6 +530,23 @@ const modalCss = `<style class="micromodal-css">
   max-width: 420px;
 }
 
+.micromodal .snippet-link-box {
+  padding: 0.75rem;
+  border: 2px solid #F6F7F9;
+  background-color: transparent;
+  font-size: 0.875rem;
+  margin-top: 0.75rem;
+}
+
+.micromodal .snippet-link-box a {
+  color: #F6F7F9;
+  text-decoration: underline;
+}
+
+.micromodal .snippet-link-box a:hover {
+  color: #E5E7EB;
+}
+
 .micromodal button.micromodal__close {
   clip-path: polygon(0% 4%, 0% 0%, 100% 0%, 100% 100%, 94% 100%);
   position: absolute;

package/src/utilities/mutation.js

@@ -280,7 +280,7 @@ const Mutation = {
           if (node.nodeType === 1 && !this._shouldIgnore(node)) {
             const removedNodes = [node, ...node.querySelectorAll('*')];
             this._log(`Processing ${removedNodes.length} removed nodes`, { removedNodes });
-            
+
             for (const element of removedNodes) {
               const change = {
                 type: 'remove',
@@ -294,6 +294,29 @@ const Mutation = {
             }
           }
         }
+
+        // Bubble text-node child changes (e.g. `el.textContent = 'foo'`) up
+        // to the parent element so onAnyChange fires. Typed callbacks
+        // (addElement, removeElement) stay element-only by design.
+        let hasTextNodeChanges = false;
+        for (const node of mutation.addedNodes) {
+          if (node.nodeType === 3) { hasTextNodeChanges = true; break; }
+        }
+        if (!hasTextNodeChanges) {
+          for (const node of mutation.removedNodes) {
+            if (node.nodeType === 3) { hasTextNodeChanges = true; break; }
+          }
+        }
+        if (hasTextNodeChanges && mutation.target.nodeType === 1) {
+          const change = {
+            type: 'characterData',
+            element: mutation.target,
+            oldValue: undefined,
+            newValue: mutation.target.textContent
+          };
+          changes.push(change);
+          changesByType.characterData.push(change);
+        }
       }
       
       if (mutation.type === 'attributes') {
@@ -404,7 +427,8 @@ const Mutation = {
       attributes: true,
       subtree: true,
       characterData: true,
-      attributeOldValue: true
+      attributeOldValue: true,
+      characterDataOldValue: true
     });
     this._observing = true;
     this._log('Observation started');