hyper-undo 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# hyper-undo changelog
+
+## 0.1.0 — unreleased
+
+Initial release. DOM-state undo/redo via MutationObserver inverse-op replay.
+
+- Single `MutationObserver` per scope records primitive mutations
+  (attr-set/add/remove, text, childList add/remove) with computable inverses
+- Removed subtrees held by reference — undo restores the same live nodes
+  (listeners, focus, scroll, custom-attribute wiring preserved)
+- Two batching modes: explicit `commit(label, fn)` and 500ms idle auto-batch
+- Pause-before / commit-on-success helpers (`commitCaptured` / `discardCaptured`)
+  so a failed apply never leaves a no-op pair on the stack
+- Global Cmd+Z / Cmd+Shift+Z / Cmd+Y handler with a configurable
+  `shadowKeydownIn` bypass list for in-page code editors
+- Reuses hyperclayjs filter-attribute semantics
+  (`mutations-ignore` / `save-remove` / `save-ignore` / `save-freeze`)
+- Default singleton on `document.body`; `create({ scope })` for multi-scope use
+- Max-history eviction (default 100) releases removed-node references
+- Standalone npm package + vendor bundle for hyperclayjs (`window.hyperclay.undo`)
+
+### Refinements over the reference plan
+
+Two correctness fixes applied to the locked plan's reference skeletons:
+
+- `commitCaptured(label)` now flushes any pending idle batch BEFORE pushing the
+  captured commit. Without this, typing then immediately triggering a structural
+  op (before the 500ms idle close) would record the structural commit ahead of
+  the typing, inverting undo order.
+- `undo.create({ scope })` delegates getters explicitly instead of
+  object-spreading the scope instance. Spreading would snapshot `canUndo` /
+  `canRedo` / `history` / `isPaused` at create time, freezing them; explicit
+  delegation keeps them live.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Miranda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# hyper-undo
+
+DOM-state undo/redo for self-editing HTML pages. A single `MutationObserver`
+records primitive DOM mutations with computable inverses, batches them into
+labelled commits, and replays them backward (undo) or forward (redo). Removed
+subtrees are kept **by reference**, so undo restores the same live nodes:
+event listeners, focus, scroll position, and custom-attribute wiring all
+survive.
+
+Works standalone, or auto-wired into [hyperclayjs](https://github.com/panphora/hyperclayjs)
+as `window.hyperclay.undo`.
+
+## Mental model
+
+**The DOM is the state. Undo navigates between DOM states.** Each undoable
+operation is a transition recorded as inverse-able primitives, not a full
+snapshot. Snapshot-based undo re-clones from serialized HTML and loses live
+node identity; mutation-based replay keeps it.
+
+## Install
+
+```bash
+npm install hyper-undo
+```
+
+```js
+import { undo } from 'hyper-undo'
+
+undo.start({ scope: document.body, maxHistory: 100, bindKeys: true })
+
+undo.commit('User edited title', () => {
+  document.querySelector('h1').textContent = 'New title'
+})
+
+undo.undo()   // restores prior state
+undo.redo()   // re-applies the undone state
+```
+
+Or load the IIFE bundle directly (auto-attaches to `window.hyperclay.undo`):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/hyper-undo/dist/hyper-undo.min.js"></script>
+```
+
+## Via hyperclayjs
+
+The `smooth-sailing` preset includes hyper-undo and auto-starts the singleton on
+`document.body` (in edit mode only, with `bindKeys: true`). Cmd+Z works out of
+the box.
+
+```html
+<script type="module">
+  await import('https://cdn.jsdelivr.net/npm/hyperclayjs@1/src/hyperclay.js?preset=smooth-sailing')
+  hyperclay.undo.commit('Add product', () => addProduct())
+</script>
+```
+
+## API
+
+| Call | Effect |
+|---|---|
+| `undo.start(opts)` | start the singleton on `opts.scope` (default `document.body`) |
+| `undo.stop()` | disconnect observer, remove key bindings, clear stacks |
+| `undo.commit(label, fn)` | run a synchronous `fn`, push its mutations as one labelled commit |
+| `undo.commitCaptured(label)` | drain `observer.takeRecords()` and push as one commit (pause-before / commit-on-success pattern) |
+| `undo.discardCaptured()` | drain and throw away the captured records (failure path companion) |
+| `undo.flush()` | force-close the current idle batch as its own commit |
+| `undo.undo()` / `undo.redo()` | navigate history |
+| `undo.clear()` | clear both stacks |
+| `undo.pause()` / `undo.resume()` | recorder skips while paused |
+| `undo.on('change', fn)` / `undo.off('change', fn)` | subscribe to change events (fires after commit, undo, redo, clear) |
+| `undo.canUndo` / `undo.canRedo` | booleans (getters) |
+| `undo.history` | `[{ label, timestamp }, ...]`, oldest first; `timestamp` is `Date.now()` millis |
+| `undo.isPaused` | boolean (getter) |
+| `undo.defaults` | `{ shadowKeydownIn: [...] }` |
+| `undo.create(opts)` | a separate scope for advanced multi-scope use |
+
+### Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `scope` | `document.body` | element to observe |
+| `maxHistory` | `100` | older commits drop off the back; dropped commits release their removed-node references |
+| `idleWindowMs` | `500` | how long to wait before auto-closing a batch |
+| `idleLabel` | `'Edit'` | label for auto-closed batches |
+| `bindKeys` | `true` (singleton), `false` (`create`) | install the global Cmd+Z handler |
+| `shadowKeydownIn` | code-editor selectors (see below) | when `event.target.closest(selector)` matches, the global handler bails without `preventDefault` |
+| `ignoreAttribute` | `null` | predicate `(attrName, element) => boolean`; return true to skip recording that attribute mutation |
+| `debug` | `false` | console.log internal state transitions |
+
+## Batching
+
+Raw mutation records are too fine-grained (typing "hello" is five
+`characterData` records). Two batching modes share one collector:
+
+- **Explicit commit** — `undo.commit(label, fn)` wraps a synchronous chunk into
+  one labelled commit. Throws if `fn()` returns a Promise (mutations after the
+  first `await` would silently land in a different commit).
+- **Idle auto-batch** — mutations made outside an explicit commit collect until
+  the scope is idle for `idleWindowMs`, then close into one `Edit` commit.
+
+## Keyboard shortcuts
+
+`bindKeys: true` installs a `window` keydown capture-phase listener:
+
+| Combo | Action |
+|---|---|
+| Cmd+Z / Ctrl+Z | undo |
+| Cmd+Shift+Z / Ctrl+Shift+Z | redo |
+| Cmd+Y / Ctrl+Y | redo (Windows convention) |
+
+### In-page editors
+
+The handler short-circuits (without `preventDefault`) when `event.target` is
+inside any selector in `shadowKeydownIn`, so an embedded editor's own keymap
+handles the key. The default list covers CodeMirror v5/v6, Monaco, Ace, Quill,
+Tiptap, and ProseMirror:
+
+```js
+['.CodeMirror', '.cm-editor', '.monaco-editor', '.ace_editor', '.ql-editor', '.tiptap', '.ProseMirror']
+```
+
+Extend it for your own editor:
+
+```js
+undo.start({ shadowKeydownIn: [...undo.defaults.shadowKeydownIn, '.my-editor'] })
+```
+
+Outside the shadow list, the global Cmd+Z intercepts even inside plain
+`<input>`/`<textarea>`, so native char-level input-undo no longer fires there.
+That's intentional: page-state undo is what users expect for Cmd+Z on a
+self-editing page. Pass `bindKeys: false` to opt out entirely and bind your own
+handler.
+
+## Filter attributes
+
+A mutation is excluded from recording when its target's ancestor chain contains
+any of: `mutations-ignore`, `save-remove`, `save-ignore`, `save-freeze`. These
+mirror hyperclayjs's `_shouldIgnore` semantics; no new attribute is introduced.
+
+## Multi-scope (advanced)
+
+```js
+const pageUndo = undo.start()                                  // singleton on document.body, owns Cmd+Z
+const editorUndo = undo.create({ scope: editorRoot, bindKeys: false })
+editorUndo.start()
+// editorUndo.undo() / .redo() called manually; Cmd+Z still routes to pageUndo
+```
+
+Only one scope can own the global Cmd+Z binding at a time. Calling `start()`
+again with a *different* scope throws (use `create` for additional scopes);
+calling it again with the *same* scope warns and keeps the original config.
+
+## Form input typing (known gap)
+
+Pure-property `<input>`/`<textarea>` value changes are not `MutationRecord`s, so
+raw typing into a field isn't directly observable. Coverage:
+
+- **CMS form fields** flow through the engine, which mutates the page DOM — the
+  recorder sees the page mutation. ✓
+- **`[persist]` inputs** on a Hyperclay page mirror `el.value` to the `value`
+  attribute; **`[persist]` textareas** mirror to `data-value`. The recorder sees
+  the attribute mutation. ✓
+- **Plain `<input>`/`<textarea>` without `[persist]`** do NOT mirror; their
+  typing is invisible to the recorder. ✗
+
+For an unmirrored field, do one of: add `[persist]`, wrap the input handler in
+`undo.commit(label, fn)`, or accept that raw typing isn't undoable for that
+field.
+
+## What this does NOT do (v1)
+
+No persistence across reloads, no cross-tab sync, no semantic diffs (it records
+DOM ops, the label is the only semantic), no collaborative/OT undo, no tracking
+of non-DOM state, no "revert to saved" checkpoint.
+
+## License
+
+MIT

package/dist/hyper-undo.min.js

@@ -0,0 +1 @@
+var hyperundo=(()=>{var x=Object.defineProperty;var J=Object.getOwnPropertyDescriptor;var Q=Object.getOwnPropertyNames;var X=Object.prototype.hasOwnProperty;var Y=(e,r)=>{for(var o in r)x(e,o,{get:r[o],enumerable:!0})},$=(e,r,o,t)=>{if(r&&typeof r=="object"||typeof r=="function")for(let n of Q(r))!X.call(e,n)&&n!==o&&x(e,n,{get:()=>r[n],enumerable:!(t=J(r,n))||t.enumerable});return e};var ee=e=>$(x({},"__esModule",{value:!0}),e);var ie={};Y(ie,{default:()=>oe,undo:()=>V});function te(e,r=null){let o=[];if(e.type==="attributes"){let t=e.target,n=e.attributeName,i=e.oldValue,a=t.getAttribute(n);return i==null&&a!=null?o.push({kind:"attr-add",target:t,name:n,newValue:a}):i!=null&&a==null?o.push({kind:"attr-remove",target:t,name:n,oldValue:i}):i!==a&&o.push({kind:"attr-set",target:t,name:n,oldValue:i,newValue:a}),o}if(e.type==="characterData")return o.push({kind:"text",target:e.target,oldValue:e.oldValue,newValue:e.target.data}),o;if(e.type==="childList"){let t=e.target,n=e.nextSibling,i=r?Array.from(e.addedNodes).filter(u=>!r(u)):Array.from(e.addedNodes),a=r?Array.from(e.removedNodes).filter(u=>!r(u)):Array.from(e.removedNodes);return i.length>0&&o.push({kind:"add",parent:t,nodes:i,before:n}),a.length>0&&o.push({kind:"remove",parent:t,nodes:a,before:n}),o}return o}function S(e,r=null){let o=[],t=new Map;for(let n of e){if(n.type==="attributes"){let i=n.target,a=n.attributeName,u=t.get(i);u||(u=new Map,t.set(i,u)),u.has(a)||(u.set(a,{idx:o.length,oldValue:n.oldValue}),o.push(null));continue}for(let i of te(n,r))o.push(i)}for(let[n,i]of t)for(let[a,u]of i){let l=u.oldValue,p=n.getAttribute(a),f=null;l===p?f=null:l==null?f={kind:"attr-add",target:n,name:a,newValue:p}:p==null?f={kind:"attr-remove",target:n,name:a,oldValue:l}:f={kind:"attr-set",target:n,name:a,oldValue:l,newValue:p},o[u.idx]=f}return o.filter(n=>n!=null)}function D(e){switch(e.kind){case"attr-set":case"attr-add":e.target.setAttribute(e.name,e.newValue);return;case"attr-remove":e.target.removeAttribute(e.name);return;case"text":e.target.data=e.newValue;return;case"add":for(let r of e.nodes)e.before&&e.before.parentNode===e.parent?e.parent.insertBefore(r,e.before):e.parent.appendChild(r);return;case"remove":for(let r of e.nodes)r.parentNode===e.parent&&e.parent.removeChild(r);return}}function N(e){switch(e.kind){case"attr-set":e.target.setAttribute(e.name,e.oldValue);return;case"attr-add":e.target.removeAttribute(e.name);return;case"attr-remove":e.target.setAttribute(e.name,e.oldValue);return;case"text":e.target.data=e.oldValue;return;case"add":for(let r of e.nodes)r.parentNode===e.parent&&e.parent.removeChild(r);return;case"remove":for(let r of e.nodes)e.before&&e.before.parentNode===e.parent?e.parent.insertBefore(r,e.before):e.parent.appendChild(r);return}}var re=["mutations-ignore","save-remove","save-ignore","save-freeze"];function C(e,r,o){let t=e&&e.nodeType!==1?e.parentElement:e;for(;t&&t.nodeType===1;){for(let n of re)if(t.hasAttribute&&t.hasAttribute(n))return!0;t=t.parentElement}if(r&&o&&o.type==="attributes")try{if(r(o.attributeName,o.target))return!0}catch{}return!1}function L(){let e=new Map;function r(n,i){let a=e.get(n);return a||(a=new Set,e.set(n,a)),a.add(i),()=>o(n,i)}function o(n,i){let a=e.get(n);a&&a.delete(i)}function t(n,i){let a=e.get(n);if(a)for(let u of Array.from(a))try{u(i)}catch(l){console.error("[hyper-undo] listener threw",l)}}return{on:r,off:o,emit:t}}var ne={maxHistory:100,idleWindowMs:500,idleLabel:"Edit",ignoreAttribute:null,debug:!1};function E(e){let r={...ne,...e};if(!r.scope)throw new Error("hyper-undo: scope is required");let o=L(),t=[],n=[],i=[],a=null,u=null,l=0,p=!1;function f(...d){r.debug&&console.log("[hyper-undo]",...d)}function F(){p||(p=!0,u=new MutationObserver(y),u.observe(r.scope,{childList:!0,attributes:!0,characterData:!0,subtree:!0,attributeOldValue:!0,characterDataOldValue:!0}),f("started"))}function b(){p&&(p=!1,u&&(u.disconnect(),u=null),g(),t.length=0,n.length=0,i=[],l=0,f("stopped"))}function T(){let d=r.scope;return!!(d&&d.nodeType===1&&d.isConnected===!1)}function y(d){if(l>0)return;let c=I(d);if(c.length>0){for(let m of c)i.push(m);z()}}function I(d){let c=d.filter(m=>!C(m.target,r.ignoreAttribute,m));return S(c,m=>C(m,r.ignoreAttribute))}function z(){g(),a=setTimeout(P,r.idleWindowMs)}function g(){a!=null&&(clearTimeout(a),a=null)}function P(){if(a=null,i.length===0)return;let d=i;i=[],v(r.idleLabel,d)}function v(d,c){for(t.push({label:d,timestamp:Date.now(),primitives:c}),n.length=0;t.length>r.maxHistory;)t.shift();f("commit",d,"primitives:",c.length),o.emit("change")}function B(d,c){if(!p)throw new Error("hyper-undo: scope not started");y(u.takeRecords()),w();let m=c();if(m&&typeof m.then=="function")throw new Error("hyper-undo: commit() fn must be synchronous; returned a Promise");if(y(u.takeRecords()),i.length===0){o.emit("change");return}g();let j=i;i=[],v(d,j)}function H(d){if(!p)throw new Error("hyper-undo: scope not started");if(!u)return;if(l>1){u.takeRecords();return}w();let c=I(u.takeRecords());c.length!==0&&(g(),v(d,c))}function W(){u&&u.takeRecords()}function w(){l===0&&u&&y(u.takeRecords()),i.length!==0&&(g(),P())}function k(){l===0&&u&&y(u.takeRecords()),l++,f("paused",l)}function A(){l!==0&&(l--,l===0&&u&&u.takeRecords(),f("resumed",l))}function q(){if(T()){b();return}w();let d=t.pop();if(d){k();try{for(let c=d.primitives.length-1;c>=0;c--)try{N(d.primitives[c])}catch(m){f("undo primitive failed (continuing)",m)}}finally{A()}n.push(d),f("undo",d.label),o.emit("change")}}function G(){if(T()){b();return}w();let d=n.pop();if(d){k();try{for(let c of d.primitives)try{D(c)}catch(m){f("redo primitive failed (continuing)",m)}}finally{A()}t.push(d),f("redo",d.label),o.emit("change")}}function Z(){u&&u.takeRecords(),t.length=0,n.length=0,i=[],g(),f("cleared"),o.emit("change")}return{_config:r,start:F,stop:b,commit:B,commitCaptured:H,discardCaptured:W,flush:w,undo:q,redo:G,clear:Z,pause:k,resume:A,on:o.on,off:o.off,get canUndo(){return t.length>0},get canRedo(){return n.length>0},get isPaused(){return l>0},get history(){return t.map(d=>({label:d.label,timestamp:d.timestamp}))},get scope(){return r.scope}}}function _(e,r){let o=t=>{let n=e.scope;if(n&&n.nodeType===1&&n.isConnected===!1){r&&r();return}let i=t.target,a=e._config.shadowKeydownIn;if(i&&i.closest&&Array.isArray(a))for(let p of a)try{if(i.closest(p))return}catch{}if(!(t.metaKey||t.ctrlKey))return;let l=(t.key||"").toLowerCase();if(l==="z"&&!t.shiftKey){t.preventDefault(),t.stopPropagation(),e.undo();return}if(l==="z"&&t.shiftKey){t.preventDefault(),t.stopPropagation(),e.redo();return}if(l==="y"&&!t.shiftKey){t.preventDefault(),t.stopPropagation(),e.redo();return}};return window.addEventListener("keydown",o,!0),()=>window.removeEventListener("keydown",o,!0)}var K=[".CodeMirror",".cm-editor",".monaco-editor",".ace_editor",".ql-editor",".tiptap",".ProseMirror"],s=null,R=null,M=null,h=null;function U(e,r){if(h){if(h.inst===e)return h.cleanup;throw new Error("hyper-undo: another scope already owns the global Cmd+Z binding (bindKeys: true). Stop it first, or use bindKeys: false for additional scopes.")}let o=_(e,r);return h={inst:e,cleanup:o},o}function O(e){h&&h.inst===e&&(h.cleanup(),h=null)}var V={defaults:{shadowKeydownIn:K},start(e={}){let r=e.scope||(typeof document<"u"?document.body:null);if(!r)throw new Error("hyper-undo: no scope (need document.body or explicit { scope })");if(s){if(R===r)return console.warn("[hyper-undo] start() called again on existing singleton; ignoring new options"),s;throw new Error("hyper-undo: start() called with a different scope while the singleton is already started. Use undo.create({ scope }) for additional scopes, or call undo.stop() first.")}let o={...e,scope:r,shadowKeydownIn:e.shadowKeydownIn||K};return s=E(o),s.start(),R=r,e.bindKeys!==!1&&(M=U(s,()=>V.stop())),s},stop(){s&&(O(s),M=null,s.stop(),s=null,R=null)},create(e={}){let r=e.scope||(typeof document<"u"?document.body:null);if(!r)throw new Error("hyper-undo: no scope (need document.body or explicit { scope })");let o={...e,scope:r,shadowKeydownIn:e.shadowKeydownIn||K},t=E(o),n=null,i={_config:t._config,commit:t.commit,commitCaptured:t.commitCaptured,discardCaptured:t.discardCaptured,flush:t.flush,undo:t.undo,redo:t.redo,clear:t.clear,pause:t.pause,resume:t.resume,on:t.on,off:t.off,get canUndo(){return t.canUndo},get canRedo(){return t.canRedo},get isPaused(){return t.isPaused},get history(){return t.history},get scope(){return t.scope},start(){e.bindKeys&&(n=U(t,()=>i.stop())),t.start()},stop(){O(t),n=null,t.stop()}};return i},commit(e,r){return s?s.commit(e,r):void 0},commitCaptured(e){return s?s.commitCaptured(e):void 0},discardCaptured(){return s?s.discardCaptured():void 0},undo(){return s?s.undo():void 0},redo(){return s?s.redo():void 0},clear(){return s?s.clear():void 0},pause(){return s?s.pause():void 0},resume(){return s?s.resume():void 0},flush(){return s?s.flush():void 0},on(e,r){return s?s.on(e,r):void 0},off(e,r){return s?s.off(e,r):void 0},get canUndo(){return s?s.canUndo:!1},get canRedo(){return s?s.canRedo:!1},get history(){return s?s.history:[]},get isPaused(){return s?s.isPaused:!1}};var oe=V;return ee(ie);})();

package/index.js

@@ -0,0 +1 @@
+export { undo, default } from './src/index.js'

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "hyper-undo",
+  "version": "0.1.0",
+  "description": "DOM-state undo/redo via MutationObserver inverse-op replay. Standalone or paired with hyperclayjs.",
+  "keywords": [
+    "undo",
+    "redo",
+    "history",
+    "mutationobserver",
+    "dom",
+    "hyperclay"
+  ],
+  "homepage": "https://github.com/panphora/hyper-undo",
+  "bugs": {
+    "url": "https://github.com/panphora/hyper-undo/issues"
+  },
+  "license": "MIT",
+  "author": "David Miranda",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "dist",
+    "index.js",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "npx esbuild src/index.js --bundle --minify --format=iife --global-name=hyperundo --outfile=dist/hyper-undo.min.js",
+    "copy-to-hyperclayjs": "npm run build && node scripts/copy-to-hyperclayjs.js",
+    "test:node": "node --test 'test-node/**/*.test.js'",
+    "test": "npm run test:node",
+    "release": "./scripts/release.sh",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "jsdom": "^25.0.0"
+  }
+}

package/src/emitter.js

@@ -0,0 +1,22 @@
+export function createEmitter() {
+  const listeners = new Map()  // name → Set of fns
+
+  function on(name, fn) {
+    let set = listeners.get(name)
+    if (!set) { set = new Set(); listeners.set(name, set) }
+    set.add(fn)
+    return () => off(name, fn)
+  }
+  function off(name, fn) {
+    const set = listeners.get(name)
+    if (set) set.delete(fn)
+  }
+  function emit(name, payload) {
+    const set = listeners.get(name)
+    if (!set) return
+    for (const fn of Array.from(set)) {
+      try { fn(payload) } catch (e) { console.error('[hyper-undo] listener threw', e) }
+    }
+  }
+  return { on, off, emit }
+}

package/src/filter.js

@@ -0,0 +1,23 @@
+// Mirrors hyperclayjs/src/utilities/mutation.js _shouldIgnore exactly.
+// Walks the parent chain from `node` and returns true if any ancestor has
+// one of the four ignore attributes. `ignoreAttributePredicate` is an optional
+// caller-supplied predicate for additional filtering on attribute records.
+
+const IGNORE_ATTRS = ['mutations-ignore', 'save-remove', 'save-ignore', 'save-freeze']
+
+export function shouldIgnore(node, ignoreAttributePredicate, record) {
+  // For non-element nodes (like text nodes), start from parent.
+  let el = (node && node.nodeType !== 1) ? node.parentElement : node
+  while (el && el.nodeType === 1) {
+    for (const attr of IGNORE_ATTRS) {
+      if (el.hasAttribute && el.hasAttribute(attr)) return true
+    }
+    el = el.parentElement
+  }
+  if (ignoreAttributePredicate && record && record.type === 'attributes') {
+    try {
+      if (ignoreAttributePredicate(record.attributeName, record.target)) return true
+    } catch (_) {}
+  }
+  return false
+}

package/src/index.js

@@ -0,0 +1,147 @@
+import { createScope } from './scope.js'
+import { installKeys } from './keys.js'
+
+const DEFAULT_SHADOW_LIST = [
+  '.CodeMirror',
+  '.cm-editor',
+  '.monaco-editor',
+  '.ace_editor',
+  '.ql-editor',
+  '.tiptap',
+  '.ProseMirror',
+]
+
+let singleton = null         // the Scope instance returned by createScope
+let singletonScope = null    // the DOM element it's bound to (for diff-scope detection)
+let singletonKeys = null     // cleanup fn from installKeys, if bound
+let keyOwner = null          // { inst, cleanup } — the one scope owning global Cmd+Z
+
+// Only ONE scope may own the global Cmd+Z binding at a time (locked plan
+// decision). Idempotent for the same owner (so a repeated start() doesn't
+// double-bind); throws for a different live owner until it's stopped.
+function claimKeys(inst, onDetached) {
+  if (keyOwner) {
+    if (keyOwner.inst === inst) return keyOwner.cleanup
+    throw new Error(
+      'hyper-undo: another scope already owns the global Cmd+Z binding (bindKeys: true). ' +
+      'Stop it first, or use bindKeys: false for additional scopes.'
+    )
+  }
+  const cleanup = installKeys(inst, onDetached)
+  keyOwner = { inst, cleanup }
+  return cleanup
+}
+function releaseKeys(inst) {
+  if (keyOwner && keyOwner.inst === inst) {
+    keyOwner.cleanup()
+    keyOwner = null
+  }
+}
+
+const undo = {
+  defaults: { shadowKeydownIn: DEFAULT_SHADOW_LIST },
+
+  start(opts = {}) {
+    const scopeEl = opts.scope || (typeof document !== 'undefined' ? document.body : null)
+    if (!scopeEl) throw new Error('hyper-undo: no scope (need document.body or explicit { scope })')
+
+    if (singleton) {
+      if (singletonScope === scopeEl) {
+        console.warn('[hyper-undo] start() called again on existing singleton; ignoring new options')
+        return singleton
+      }
+      throw new Error(
+        'hyper-undo: start() called with a different scope while the singleton is already started. ' +
+        'Use undo.create({ scope }) for additional scopes, or call undo.stop() first.'
+      )
+    }
+
+    const config = {
+      ...opts,
+      scope: scopeEl,
+      shadowKeydownIn: opts.shadowKeydownIn || DEFAULT_SHADOW_LIST,
+    }
+    singleton = createScope(config)
+    singleton.start()
+    singletonScope = scopeEl
+    if (opts.bindKeys !== false) {
+      singletonKeys = claimKeys(singleton, () => undo.stop())
+    }
+    return singleton
+  },
+
+  stop() {
+    if (!singleton) return
+    releaseKeys(singleton)
+    singletonKeys = null
+    singleton.stop()
+    singleton = null
+    singletonScope = null
+  },
+
+  create(opts = {}) {
+    const scopeEl = opts.scope || (typeof document !== 'undefined' ? document.body : null)
+    if (!scopeEl) throw new Error('hyper-undo: no scope (need document.body or explicit { scope })')
+    const config = {
+      ...opts,
+      scope: scopeEl,
+      shadowKeydownIn: opts.shadowKeydownIn || DEFAULT_SHADOW_LIST,
+    }
+    const inst = createScope(config)
+    let keysCleanup = null
+    // Delegate explicitly (NOT object-spread) so the canUndo/canRedo/history/
+    // isPaused getters stay live — spreading would snapshot them at create time.
+    const wrapper = {
+      _config: inst._config,
+      commit: inst.commit,
+      commitCaptured: inst.commitCaptured,
+      discardCaptured: inst.discardCaptured,
+      flush: inst.flush,
+      undo: inst.undo,
+      redo: inst.redo,
+      clear: inst.clear,
+      pause: inst.pause,
+      resume: inst.resume,
+      on: inst.on,
+      off: inst.off,
+      get canUndo() { return inst.canUndo },
+      get canRedo() { return inst.canRedo },
+      get isPaused() { return inst.isPaused },
+      get history() { return inst.history },
+      get scope() { return inst.scope },
+      start() {
+        // Claim the global key binding first so a conflict throws before the
+        // observer starts (no partial start). claimKeys is idempotent for this
+        // same inst, so a repeated start() never double-binds.
+        if (opts.bindKeys) keysCleanup = claimKeys(inst, () => wrapper.stop())
+        inst.start()
+      },
+      stop() {
+        releaseKeys(inst)
+        keysCleanup = null
+        inst.stop()
+      },
+    }
+    return wrapper
+  },
+
+  // Singleton delegators
+  commit(label, fn)       { return singleton ? singleton.commit(label, fn) : undefined },
+  commitCaptured(label)   { return singleton ? singleton.commitCaptured(label) : undefined },
+  discardCaptured()       { return singleton ? singleton.discardCaptured() : undefined },
+  undo()                  { return singleton ? singleton.undo() : undefined },
+  redo()                  { return singleton ? singleton.redo() : undefined },
+  clear()                 { return singleton ? singleton.clear() : undefined },
+  pause()                 { return singleton ? singleton.pause() : undefined },
+  resume()                { return singleton ? singleton.resume() : undefined },
+  flush()                 { return singleton ? singleton.flush() : undefined },
+  on(name, fn)            { return singleton ? singleton.on(name, fn) : undefined },
+  off(name, fn)           { return singleton ? singleton.off(name, fn) : undefined },
+  get canUndo()           { return singleton ? singleton.canUndo : false },
+  get canRedo()           { return singleton ? singleton.canRedo : false },
+  get history()           { return singleton ? singleton.history : [] },
+  get isPaused()          { return singleton ? singleton.isPaused : false },
+}
+
+export { undo }
+export default undo

package/src/keys.js

@@ -0,0 +1,48 @@
+// Installs a single window-level keydown listener in capture phase.
+// Returns a cleanup function.
+
+export function installKeys(scope, onDetached) {
+  const handler = (event) => {
+    // If the scope root was removed from the document, release the global
+    // binding and let native Cmd+Z through instead of undoing a detached tree.
+    const scopeEl = scope.scope
+    if (scopeEl && scopeEl.nodeType === 1 && scopeEl.isConnected === false) {
+      if (onDetached) onDetached()
+      return
+    }
+
+    // Bypass for in-page editors (CodeMirror, Monaco, etc.)
+    const target = event.target
+    const shadow = scope._config.shadowKeydownIn
+    if (target && target.closest && Array.isArray(shadow)) {
+      for (const selector of shadow) {
+        try { if (target.closest(selector)) return }
+        catch (_) { /* invalid selector, skip */ }
+      }
+    }
+
+    const mod = event.metaKey || event.ctrlKey
+    if (!mod) return
+
+    const key = (event.key || '').toLowerCase()
+
+    if (key === 'z' && !event.shiftKey) {
+      event.preventDefault(); event.stopPropagation()
+      scope.undo()
+      return
+    }
+    if (key === 'z' && event.shiftKey) {
+      event.preventDefault(); event.stopPropagation()
+      scope.redo()
+      return
+    }
+    if (key === 'y' && !event.shiftKey) {
+      event.preventDefault(); event.stopPropagation()
+      scope.redo()
+      return
+    }
+  }
+
+  window.addEventListener('keydown', handler, true)
+  return () => window.removeEventListener('keydown', handler, true)
+}

package/src/primitives.js

@@ -0,0 +1,184 @@
+// One MutationRecord becomes one or more primitives. A childList record
+// with both addedNodes and removedNodes produces two primitives (one add,
+// one remove). Attribute and characterData each produce one.
+//
+// Each primitive carries everything needed to replay it in either direction
+// without re-reading the live DOM.
+
+export function recordToPrimitives(record, ignoreNode = null) {
+  const out = []
+
+  if (record.type === 'attributes') {
+    const target = record.target
+    const name = record.attributeName
+    const oldValue = record.oldValue
+    const newValue = target.getAttribute(name)
+
+    if (oldValue == null && newValue != null) {
+      out.push({ kind: 'attr-add', target, name, newValue })
+    } else if (oldValue != null && newValue == null) {
+      out.push({ kind: 'attr-remove', target, name, oldValue })
+    } else if (oldValue !== newValue) {
+      out.push({ kind: 'attr-set', target, name, oldValue, newValue })
+    }
+    return out
+  }
+
+  if (record.type === 'characterData') {
+    out.push({
+      kind: 'text',
+      target: record.target,
+      oldValue: record.oldValue,
+      newValue: record.target.data,
+    })
+    return out
+  }
+
+  if (record.type === 'childList') {
+    const parent = record.target
+    const before = record.nextSibling   // the slot to re-insert before
+    // The parent target already passed the caller's ignore filter, but an
+    // individual added/removed node can itself be an ignored subtree (e.g. a
+    // save-ignore CMS shell appended directly under <body>). Drop those nodes
+    // so undo never records or reverses them; emit no primitive if a side ends
+    // up empty.
+    const added = ignoreNode
+      ? Array.from(record.addedNodes).filter((n) => !ignoreNode(n))
+      : Array.from(record.addedNodes)
+    const removed = ignoreNode
+      ? Array.from(record.removedNodes).filter((n) => !ignoreNode(n))
+      : Array.from(record.removedNodes)
+    if (added.length > 0) {
+      out.push({ kind: 'add', parent, nodes: added, before })
+    }
+    if (removed.length > 0) {
+      out.push({ kind: 'remove', parent, nodes: removed, before })
+    }
+    return out
+  }
+
+  return out
+}
+
+// Convert a whole batch of records (one observer delivery, or one
+// takeRecords() drain) into primitives, coalescing repeated mutations of the
+// SAME (target, attributeName) within the batch.
+//
+// Why batch-level: MutationObserver does not expose a per-record NEW attribute
+// value, and by the time we run, the DOM already reflects every mutation in the
+// batch. So recordToPrimitives' `getAttribute(name)` can only read the FINAL
+// value. When an attribute is touched twice in one batch (e.g. add-then-remove,
+// or remove-then-readd-same), classifying each record off that final value
+// misclassifies or drops records and corrupts undo. We instead keep the FIRST
+// record's oldValue and the FINAL live value, emitting one primitive per
+// (target, name) — or none when they're equal (a net no-op within the batch).
+// Records arrive already filtered by the caller; order is preserved, with each
+// coalesced attribute primitive landing at its first occurrence.
+export function recordsToPrimitives(records, ignoreNode = null) {
+  const out = []
+  const seen = new Map()   // target → Map(name → { idx, oldValue })
+
+  for (const record of records) {
+    if (record.type === 'attributes') {
+      const target = record.target
+      const name = record.attributeName
+      let byName = seen.get(target)
+      if (!byName) { byName = new Map(); seen.set(target, byName) }
+      if (!byName.has(name)) {
+        byName.set(name, { idx: out.length, oldValue: record.oldValue })
+        out.push(null)   // placeholder, finalized below
+      }
+      // Repeat occurrences in this batch are folded into the first.
+      continue
+    }
+    for (const p of recordToPrimitives(record, ignoreNode)) out.push(p)
+  }
+
+  for (const [target, byName] of seen) {
+    for (const [name, info] of byName) {
+      const oldValue = info.oldValue
+      const newValue = target.getAttribute(name)
+      let prim = null
+      if (oldValue === newValue) {
+        prim = null                                              // net no-op
+      } else if (oldValue == null) {
+        prim = { kind: 'attr-add', target, name, newValue }
+      } else if (newValue == null) {
+        prim = { kind: 'attr-remove', target, name, oldValue }
+      } else {
+        prim = { kind: 'attr-set', target, name, oldValue, newValue }
+      }
+      out[info.idx] = prim
+    }
+  }
+
+  return out.filter((p) => p != null)
+}
+
+// Forward replay. Used by redo().
+export function replayForward(p) {
+  switch (p.kind) {
+    case 'attr-set':
+    case 'attr-add':
+      p.target.setAttribute(p.name, p.newValue)
+      return
+    case 'attr-remove':
+      p.target.removeAttribute(p.name)
+      return
+    case 'text':
+      p.target.data = p.newValue
+      return
+    case 'add':
+      for (const node of p.nodes) {
+        if (p.before && p.before.parentNode === p.parent) {
+          p.parent.insertBefore(node, p.before)
+        } else {
+          p.parent.appendChild(node)
+        }
+      }
+      return
+    case 'remove':
+      for (const node of p.nodes) {
+        if (node.parentNode === p.parent) {
+          p.parent.removeChild(node)
+        }
+      }
+      return
+  }
+}
+
+// Reverse replay. Used by undo().
+export function replayReverse(p) {
+  switch (p.kind) {
+    case 'attr-set':
+      p.target.setAttribute(p.name, p.oldValue)
+      return
+    case 'attr-add':
+      p.target.removeAttribute(p.name)
+      return
+    case 'attr-remove':
+      p.target.setAttribute(p.name, p.oldValue)
+      return
+    case 'text':
+      p.target.data = p.oldValue
+      return
+    case 'add':
+      // forward was add → reverse is remove
+      for (const node of p.nodes) {
+        if (node.parentNode === p.parent) {
+          p.parent.removeChild(node)
+        }
+      }
+      return
+    case 'remove':
+      // forward was remove → reverse is add. Re-insert at the same slot.
+      for (const node of p.nodes) {
+        if (p.before && p.before.parentNode === p.parent) {
+          p.parent.insertBefore(node, p.before)
+        } else {
+          p.parent.appendChild(node)
+        }
+      }
+      return
+  }
+}

package/src/scope.js

@@ -0,0 +1,259 @@
+import { recordsToPrimitives, replayForward, replayReverse } from './primitives.js'
+import { shouldIgnore } from './filter.js'
+import { createEmitter } from './emitter.js'
+
+const DEFAULTS = {
+  maxHistory: 100,
+  idleWindowMs: 500,
+  idleLabel: 'Edit',
+  ignoreAttribute: null,
+  debug: false,
+}
+
+export function createScope(opts) {
+  const config = { ...DEFAULTS, ...opts }
+  if (!config.scope) throw new Error('hyper-undo: scope is required')
+
+  const emitter = createEmitter()
+  const undoStack = []        // [{ label, timestamp, primitives }]
+  const redoStack = []        // same shape
+  let pendingPrimitives = []  // primitives collected since last commit
+  let idleTimer = null
+  let observer = null
+  let pauseDepth = 0       // reference-counted; recording is active only at 0
+  let started = false
+
+  function log(...args) { if (config.debug) console.log('[hyper-undo]', ...args) }
+
+  // --- Lifecycle ---
+
+  function start() {
+    if (started) return
+    started = true
+    observer = new MutationObserver(handleRecords)
+    observer.observe(config.scope, {
+      childList: true,
+      attributes: true,
+      characterData: true,
+      subtree: true,
+      attributeOldValue: true,
+      characterDataOldValue: true,
+    })
+    log('started')
+  }
+
+  function stop() {
+    if (!started) return
+    started = false
+    if (observer) { observer.disconnect(); observer = null }
+    clearIdleTimer()
+    undoStack.length = 0
+    redoStack.length = 0
+    pendingPrimitives = []
+    pauseDepth = 0   // reset so a reused (created) scope doesn't restart paused
+    log('stopped')
+  }
+
+  // The plan requires a scope whose root has been removed from the document to
+  // stop itself with its stack cleared. Detected lazily at the next undo/redo
+  // (and at the key handler in keys.js) rather than via a polling timer.
+  function scopeDisconnected() {
+    const el = config.scope
+    return !!(el && el.nodeType === 1 && el.isConnected === false)
+  }
+
+  // --- Observer callback ---
+
+  function handleRecords(records) {
+    if (pauseDepth > 0) return  // records remain in observer buffer until takeRecords() is called
+    const prims = convertRecords(records)
+    if (prims.length > 0) {
+      for (const p of prims) pendingPrimitives.push(p)
+      restartIdleTimer()
+    }
+  }
+
+  // Filter ignored records, then coalesce same-attribute repeats within the batch.
+  function convertRecords(records) {
+    const kept = records.filter((r) => !shouldIgnore(r.target, config.ignoreAttribute, r))
+    return recordsToPrimitives(kept, (node) => shouldIgnore(node, config.ignoreAttribute))
+  }
+
+  // --- Idle batching ---
+
+  function restartIdleTimer() {
+    clearIdleTimer()
+    idleTimer = setTimeout(closeIdleBatch, config.idleWindowMs)
+  }
+  function clearIdleTimer() {
+    if (idleTimer != null) { clearTimeout(idleTimer); idleTimer = null }
+  }
+  function closeIdleBatch() {
+    idleTimer = null
+    if (pendingPrimitives.length === 0) return
+    const primitives = pendingPrimitives
+    pendingPrimitives = []
+    pushCommit(config.idleLabel, primitives)
+  }
+
+  // --- Commit machinery ---
+
+  function pushCommit(label, primitives) {
+    undoStack.push({ label, timestamp: Date.now(), primitives })
+    redoStack.length = 0
+    while (undoStack.length > config.maxHistory) undoStack.shift()
+    log('commit', label, 'primitives:', primitives.length)
+    emitter.emit('change')
+  }
+
+  // Explicit commit: caller-driven, synchronous fn.
+  function commit(label, fn) {
+    if (!started) throw new Error('hyper-undo: scope not started')
+    // Drain anything already buffered from this same synchronous tick (e.g.
+    // typing whose observer callback hasn't fired yet) into pending, THEN close
+    // it as its own batch — so the explicit commit starts clean and prior work
+    // isn't swallowed under this label.
+    handleRecords(observer.takeRecords())
+    flush()
+    const result = fn()
+    if (result && typeof result.then === 'function') {
+      throw new Error('hyper-undo: commit() fn must be synchronous; returned a Promise')
+    }
+    // Drain records the observer hasn't fired callback for yet.
+    handleRecords(observer.takeRecords())
+    if (pendingPrimitives.length === 0) {
+      emitter.emit('change')
+      return
+    }
+    clearIdleTimer()
+    const primitives = pendingPrimitives
+    pendingPrimitives = []
+    pushCommit(label, primitives)
+  }
+
+  // Pause-before / commit-on-success pattern used by hypercms.
+  // Caller: pause() → run code → commitCaptured(label) on success / discardCaptured() on failure → resume().
+  function commitCaptured(label) {
+    if (!started) throw new Error('hyper-undo: scope not started')
+    if (!observer) return
+    // If an OUTER pause is still active (this capture frame is nested inside an
+    // exclusion pause), honor the outer "exclude everything" contract: discard
+    // the captured records instead of committing through the outer pause.
+    if (pauseDepth > 1) { observer.takeRecords(); return }
+    // Close any pending idle batch (e.g. in-progress typing captured BEFORE the
+    // pause) as its own commit FIRST, so the structural commit we're about to
+    // push lands AFTER it in history. Without this, type-then-immediately-add
+    // would record the structural op before the typing, inverting undo order.
+    flush()
+    const primitives = convertRecords(observer.takeRecords())
+    if (primitives.length === 0) return
+    clearIdleTimer()
+    pushCommit(label, primitives)
+  }
+
+  function discardCaptured() {
+    if (observer) observer.takeRecords()
+  }
+
+  // Force-close current idle batch as its own commit. Used by undo()/redo() and
+  // by the save seam (snapshot.js calls undo.flush() before cloning).
+  function flush() {
+    // Drain same-tick records the observer hasn't delivered yet so the batch
+    // boundary is correct (e.g. a synchronous save right after a DOM edit).
+    // Skip while paused — the paused caller (commitCaptured) drains the buffer
+    // itself, and draining here would route those records through the
+    // early-returning handleRecords and lose them.
+    if (pauseDepth === 0 && observer) handleRecords(observer.takeRecords())
+    if (pendingPrimitives.length === 0) return
+    clearIdleTimer()
+    closeIdleBatch()
+  }
+
+  // --- Pause/resume ---
+
+  // Reference-counted so nested pauses (e.g. a hypercms commit wrapping a
+  // live-sync morph that also pauses) only resume on the outermost release.
+  function pause() {
+    // On the outermost pause, drain anything already buffered from this same
+    // synchronous tick into pending FIRST, while still unpaused, so a pre-pause
+    // edit isn't swallowed into the captured/structural batch that follows.
+    if (pauseDepth === 0 && observer) handleRecords(observer.takeRecords())
+    pauseDepth++
+    log('paused', pauseDepth)
+  }
+  function resume() {
+    if (pauseDepth === 0) return  // underflow guard
+    pauseDepth--
+    // Discard records captured during the pause only on the outermost release.
+    if (pauseDepth === 0 && observer) observer.takeRecords()
+    log('resumed', pauseDepth)
+  }
+
+  // --- Undo/redo ---
+
+  function undo() {
+    if (scopeDisconnected()) { stop(); return }
+    flush()  // close any pending typing first
+    const c = undoStack.pop()
+    if (!c) return
+    pause()
+    try {
+      // Reverse order so a child restore happens before its parent restore.
+      for (let i = c.primitives.length - 1; i >= 0; i--) {
+        try { replayReverse(c.primitives[i]) }
+        catch (err) { log('undo primitive failed (continuing)', err) }
+      }
+    } finally { resume() }
+    redoStack.push(c)
+    log('undo', c.label)
+    emitter.emit('change')
+  }
+
+  function redo() {
+    if (scopeDisconnected()) { stop(); return }
+    flush()
+    const c = redoStack.pop()
+    if (!c) return
+    pause()
+    try {
+      for (const p of c.primitives) {
+        try { replayForward(p) }
+        catch (err) { log('redo primitive failed (continuing)', err) }
+      }
+    } finally { resume() }
+    undoStack.push(c)
+    log('redo', c.label)
+    emitter.emit('change')
+  }
+
+  function clear() {
+    // Discard any same-tick buffered records too, so a bootstrap mutation
+    // followed by clear() in the same turn doesn't resurface as a commit once
+    // the observer callback fires.
+    if (observer) observer.takeRecords()
+    undoStack.length = 0
+    redoStack.length = 0
+    pendingPrimitives = []
+    clearIdleTimer()
+    log('cleared')
+    emitter.emit('change')
+  }
+
+  // --- Public surface for the singleton wrapper ---
+
+  return {
+    _config: config,  // private: used by keys.js to read shadowKeydownIn
+    start, stop,
+    commit, commitCaptured, discardCaptured, flush,
+    undo, redo, clear,
+    pause, resume,
+    on: emitter.on, off: emitter.off,
+    get canUndo() { return undoStack.length > 0 },
+    get canRedo() { return redoStack.length > 0 },
+    get isPaused() { return pauseDepth > 0 },
+    get history() {
+      return undoStack.map(c => ({ label: c.label, timestamp: c.timestamp }))
+    },
+    get scope() { return config.scope },
+  }
+}