How it actually
works.

01 The Style Map

Before anything can be scanned or injected, chai-wind needs a source of truth: a plain JavaScript object mapping class name strings to CSS declaration strings. Everything else in the engine reads from or writes to this object.

02 applyStyleString()

Once a class name matches, we have a CSS string like "padding-left: 16px; padding-right: 16px". Three different browser APIs can write inline styles - only one is safe.

With the right API chosen, the parsing pipeline itself is straightforward:

03 processElement()

The core function that takes a single DOM node and applies all matching chai styles to it. Three early-exit guards run upfront - each has a specific, non-obvious reason.

The nodeType guard matters because the DOM tree contains many non-element nodes. Accessing .classList on a text node returns undefined, causing a silent crash.

04 scanDOM()

The initial full-DOM pass. Uses a targeted CSS attribute selector so the browser's native selector engine - written in C++ - does the heavy filtering before a single line of JavaScript runs.

05 MutationObserver

scanDOM() runs once at initialisation. But real applications constantly mutate the DOM - React renders, Vue updates templates, plain JS inserts elements on user interaction. Any element added after the scan would miss the styling pass entirely. The MutationObserver API solves this.

The observer is configured with four options, each chosen deliberately:

observer.observe(document.body, {
  childList:      true,  // watch nodes added/removed
  subtree:        true,  // entire tree, not just direct children
  attributes:     true,  // watch attribute changes
  attributeFilter: ["class"], // only class changes - ignore id, style, data-*
});

The callback handles two mutation types:

06 RAF Batching

The observer callback doesn't process nodes immediately. Instead it collects them in a Set and schedules a single requestAnimationFrame flush. This is the batch-and-drain pattern.

let _pendingNodes = new Set();
let _rafId = null;

function _flushPending() {
  _pendingNodes.forEach((node) => {
    processElement(node);
    node.querySelectorAll?.('[class*="chai-"]').forEach(processElement);
  });
  _pendingNodes.clear();
  _rafId = null;
}

// In the observer callback:
if (!_rafId) {
  _rafId = requestAnimationFrame(_flushPending); // schedule once
}

07 Init & readyState

When chai-wind's script executes, the HTML parser may still be running - meaning document.body doesn't yet contain all its elements. The initialisation block checks document.readyState to decide whether to run immediately or wait.

if (document.readyState === "loading") {
  // Parser still running - wait for it to finish
  document.addEventListener("DOMContentLoaded", () => {
    ChaiWind.init({ debug: true });
  });
} else {
  // DOM is already available - init immediately
  ChaiWind.init({ debug: true });
}

08 Full Data Flow

Every layer in one picture - from the HTML file loading to a styled element on screen.

09 Public API

Four methods are exposed on window.ChaiWind. Three are functional; one is a developer ergonomics helper.

ChaiWind.init({
  debug: true, // log matched elements to console
  styles: { // extend the style map before first scan
    "my-card": "background:#fff; border-radius:8px"
  }
});

ChaiWind.register({
  "chai-card-elevated": `
    background-color: #fff;
    border-radius: 12px;
    box-shadow: 0 8px 24px rgba(0,0,0,0.12);
    padding: 24px
  `
});

The key insight in register() is that it targets only elements that need updating:

10 Key Takeaways

chai-wind is small, but it exercises a dense cluster of browser APIs. Building it from scratch surfaces behaviours that are easy to take for granted:

• The DOM is a live tree, not a snapshot. querySelectorAll gives you a static NodeList at the moment of calling, but the DOM keeps changing. MutationObserver is the right tool for tracking changes - not polling with setInterval.
• style.setProperty() vs cssText is not trivial. Overwriting cssText is only safe if you own all inline styles on that element. The moment any other code touches them, you have a conflict. setProperty is additive and cooperative.
• classList is a proper API, not a string split. It handles whitespace edge cases, provides add/remove/toggle, and fires MutationObserver attribute events when you use it.
• nodeType guards matter. The DOM tree contains many non-element nodes. Defensive guards at the top of DOM-walking functions prevent silent undefined errors that are hard to debug.
• DOMContentLoaded vs readyState. Scripts in <head> without defer run before the body is parsed. Checking readyState and falling back to DOMContentLoaded makes a DOM-manipulation script safe regardless of where it's placed.
• Batching via requestAnimationFrame. Processing mutations synchronously in the observer callback can cause layout thrash. Collecting into a Set and flushing on the next frame coalesces many changes into one pass.