document:changed — last-modified pill

Walkthrough

1. 1

   Subscribe via `builder.events.on(...)` after instantiation

   Every Builder instance owns a pub/sub events bus. Subscribe with builder.events.on(eventName, handler); unsubscribe with builder.events.off(eventName, handler). Use the Builder.EVENTS.* constants instead of typing the string — your editor catches typos and the constant is stable across versions.

   Listeners attach after new Builder({...}) — the bus exists from construction time, so registering before builder.load() means the very first document:changed after first paint also flows through.

   JavaScript Copy

   const builder = new Builder({
     mainContainer:     '#MyCanvas',
     widgetsContainer:  '#MyWidgets',
     settingsContainer: '#MySettings',
   });
   
   // Subscribe BEFORE load() so the very first edit fires through.
   builder.events.on(Builder.EVENTS.DOCUMENT_CHANGED, () => {
     document.getElementById('c1LastModifiedPill').textContent =
       'Last modified: ' + new Date().toLocaleTimeString();
   });
   
   builder.load(THEME_JSON, THEME_TEMPLATES, THEME_CONFIG_DATA, MEDIA_URL);

2. 2

   The bus debounces `document:changed` internally — one signal per burst

   A typing burst is dozens of mutations per second. Surfacing every one of those to the host would burn battery and triple-paint your pill. The engine wraps document:changed in a 120 ms trailing-edge debounce inside EventEmitter — your handler fires once when the burst settles, with the latest state.

   120 ms is two frames at 60 Hz: long enough to coalesce a sentence of typing, short enough to feel instant. Override per-instance with new Builder({ eventDebounceMs: 250 }) when you want quieter signals (e.g. autosave). Set to 0 for raw fire-on-every-mutation if you need it (you almost never do).

   JavaScript Copy

   // Default: 120 ms debounce. One pill update per typing burst.
   const builder = new Builder({ /* ...containers... */ });
   
   // Quieter — autosave fires once every 1.5 seconds of inactivity.
   const builderQuiet = new Builder({
     /* ...containers... */
     eventDebounceMs: 1500,
   });
   builderQuiet.events.on(Builder.EVENTS.DOCUMENT_CHANGED, () => {
     fetch('/backend/save.php', { method: 'POST', body: serialize(builderQuiet) });
   });

3. 3

   Render the pill — your call where + how

   The host owns the DOM around the canvas. The pill in the live demo above is one <span> with the same #c1LastModifiedPill ID this step's code targets. The handler reads new Date().toLocaleTimeString() on every fire — locale formatting + 12/24h conventions come free from the platform.

   For a real autosave UX, the same listener fires the network call: fetch(saveUrl, …), then on the response set the pill to "Saved 14:23:45 ✓". You don't need a separate save:click event — let document:changed drive both the indicator and the persistence.

   HTML Copy

   <header class="my-app__header">
     <h1>My CMS</h1>
     <span id="c1LastModifiedPill" class="pill pill--muted">
       Last modified: never
     </span>
   </header>
   
   <style>
   .pill {
     display: inline-flex;
     padding: 4px 10px;
     border-radius: 999px;
     background: #eef2ff;
     color: #4338ca;
     font-size: 12px;
     font-weight: 600;
   }
   .pill--muted { background: #f3f4f6; color: #6b7280; }
   </style>