History keyboard shortcuts — chord ladder + max-history stepper

Walkthrough

1. 1

   The engine ships with Cmd-Z / Cmd-Shift-Z / Cmd-Y wired — buyer has to do nothing

   Builder.js:746-767 attaches a keydown listener on document (capture phase) that converts (Cmd|Ctrl)+Z → builder.history.undo(); (Cmd|Ctrl)+Shift+Z and (Cmd|Ctrl)+Y → builder.history.redo(). The handler skips inputs / textareas / contenteditable so text editors handle their own undo natively. Mac and Windows / Linux both work — the engine checks metaKey || ctrlKey.

   Try it now in the live demo. Click any block on the canvas, change something via the settings panel, then press ⌘Z (or Ctrl+Z). The Undo / Redo buttons in the header reflect the new state (driven by the same history:change listener wired below). Boot state is at the baseline — Undo greys out; Redo greys out; once you make ONE change both light up.

   Want to opt OUT of the built-in chords (e.g., your app needs Cmd-Z for a different action)? Pass { historyShortcuts: false } into the Builder constructor. The engine then leaves the keyboard alone — wire your own listener that calls builder.history.undo() + builder.history.redo() on whatever chord you pick.

   JavaScript Copy

   // Default — engine wires Cmd-Z / Cmd-Shift-Z / Cmd-Y for free.
   const builder = new Builder({
     mainContainer:     '#MyCanvas',
     widgetsContainer:  '#MyWidgets',
     settingsContainer: '#MySettings',
     // historyShortcuts: true  ← default, no need to set
   });
   
   // Opt-out — engine ignores the keyboard, you wire your own.
   const builderManual = new Builder({
     mainContainer:     '#MyCanvas',
     widgetsContainer:  '#MyWidgets',
     settingsContainer: '#MySettings',
     historyShortcuts:  false,
   });
   
   // Then wire whatever chord you want:
   document.addEventListener('keydown', (e) => {
     const mod = e.metaKey || e.ctrlKey;
     if (!mod) return;
     if (e.key === 'z' && !e.shiftKey) builderManual.undo();
     if (e.key === 'z' &&  e.shiftKey) builderManual.redo();
   });

2. 2

   Reactive Undo / Redo buttons + step counter — `history:change` is the single source of truth

   The header carries an Undo button + Redo button + a step-counter pill ("Step 3 / 7"). All three reflect engine state via ONE history:change listener. Engine emits the event from HistoryManager._notifyChange() on every undo / redo / commit / clear with this payload:

   {\n  canUndo:      boolean,    // pointer > 0\n  canRedo:      boolean,    // pointer < size - 1\n  size:         number,     // total stack length\n  currentIndex: number,     // 0-based pointer position\n  currentEntry: { labelKey, timestamp, ... }\n}

   Mutating button state in the click handler instead of the listener is the easiest way to desync — keyboard shortcuts, programmatic builder.undo() calls, and `Cmd-Shift-Backspace` rewinds all skip the click path but still emit the event. The listener-as-UI-source-of-truth pattern (locked in D13.C.8) means: click handlers stay one-line (builder.undo()); listener owns repaint; programmatic flips update through SAME path with zero per-caller wiring.

   This example is the SECOND consumer of history:change in the demo (the first was W6.C.3 events tier). Locks the rule: "any UI surface that reflects history state subscribes to history:change + reads payload fields, never reads engine state imperatively in a render-loop."

   JavaScript Copy

   const undoBtn = document.getElementById('c17UndoBtn');
   const redoBtn = document.getElementById('c17RedoBtn');
   const counter = document.getElementById('c17StepCounter');
   
   function renderHistoryUi(state) {
     // state shape: { canUndo, canRedo, size, currentIndex, currentEntry }
     undoBtn.disabled = !state.canUndo;
     redoBtn.disabled = !state.canRedo;
     // currentIndex is 0-based; show 1-based for buyers.
     counter.textContent = `Step ${state.currentIndex + 1} / ${state.size}`;
   }
   
   // Subscribe — engine emits on every undo/redo/commit/clear.
   builder.events.on('history:change', renderHistoryUi);
   
   // Boot snapshot — engine doesn't re-emit history:change on subscribe.
   // Read once after load() resolves.
   renderHistoryUi({
     canUndo:      builder.history.canUndo(),
     canRedo:      builder.history.canRedo(),
     size:         builder.history.size(),
     currentIndex: builder.history.getCurrentIndex(),
     currentEntry: null,
   });
   
   // Click handlers — one-line each; the listener owns the repaint.
   undoBtn.addEventListener('click', () => builder.undo());
   redoBtn.addEventListener('click', () => builder.redo());

3. 3

   Extend the ladder + flip the stack ceiling — Cmd-Shift-Backspace rewinds, max-stepper changes maxSize

   Custom chord — rewind to start. Cmd-Shift-Backspace (or Ctrl-Shift-Backspace) jumps the pointer back to entry 0 in one move via builder.history.jumpTo(builder.history.getEntries()[0].id). Useful when the buyer wants a "reset to baseline" affordance without nuking the stack (Cmd-Z still walks back through individual edits afterwards). Wire any chord this way: listen on document, check modifiers, look up the entry id, call jumpTo.

   Max-history stepper — `history.maxSize`. Engine default is 50 entries. Above this the stack trims oldest-first on each push. Reduce to 10 for memory-constrained embeds (an in-app email composer that ships in a tiny iframe) or raise to 200 for power-users on a full-screen editor. The setting takes effect on the NEXT push — already-stored entries above the new ceiling stay until the next commit trims them. The stepper in the header is a <input type="number"> bound to history.maxSize with a 5-200 range so a fat-fingered 1 doesn't lose the engine's baseline.

   Surface the depth pill. The step counter from Step 2 already shows current/max. Add a "Depth limit: N" pill so the buyer's power-users see when they're at the ceiling + can raise the limit before losing entries. The whole UI surface is <30 lines of host code; the engine handles the trimming + payload semantics.

   JavaScript Copy

   // Custom chord — Cmd-Shift-Backspace rewinds to entry 0.
   document.addEventListener('keydown', (e) => {
     const mod = e.metaKey || e.ctrlKey;
     if (!mod || !e.shiftKey) return;
     // Backspace key — Mac users typically have Delete labelled Backspace.
     if (e.key !== 'Backspace') return;
     e.preventDefault();
     const entries = builder.history.getEntries();
     if (entries.length > 0) builder.history.jumpTo(entries[0].id);
   });
   
   // Optional: surface the chord as a button too — keyboard discovery is hard.
   document.getElementById('c17RewindBtn').addEventListener('click', () => {
     const entries = builder.history.getEntries();
     if (entries.length > 0) builder.history.jumpTo(entries[0].id);
   });
   
   // Max-history stepper — flips builder.history.maxSize on the fly.
   const stepper = document.getElementById('c17MaxStepper');
   stepper.value = builder.history.maxSize;   // boot value (engine default = 50)
   stepper.addEventListener('change', (e) => {
     const next = Math.max(5, Math.min(200, parseInt(e.target.value, 10) || 50));
     builder.history.maxSize = next;
     stepper.value = next;       // clamp visible value
   });
   
   // Listener already wired in Step 2 covers updates — no extra subscribe needed.
   // jumpTo emits 'history:change' so Undo/Redo buttons + step counter follow.