decantr 0.9.0

package/reference/behaviors.md

@@ -0,0 +1,384 @@
+# Behavioral Primitives Reference
+
+`src/components/_behaviors.js` provides composable behavioral systems used by 70+ components. Each primitive wires up event listeners, ARIA state, and keyboard interactions so components stay thin — import the behavior, call it, and wire `destroy()` to `onDestroy()`.
+
+## Cleanup Contract
+
+**All primitives returning `destroy()` (or `deactivate()`/`disconnect()`) MUST be wired to `onDestroy()`.** Failure to do so leaks document listeners, timers, and observers when components are removed from the DOM. See `reference/component-lifecycle.md` for patterns.
+
+```javascript
+const overlay = createOverlay(trigger, panel, { trigger: 'click' });
+const listbox = createListbox(panel, { onSelect: handleSelect });
+onDestroy(() => { overlay.destroy(); listbox.destroy(); });
+```
+
+---
+
+## Overlay
+
+### `createOverlay(triggerEl, contentEl, opts?)`
+
+Managed floating layer with show/hide, click-outside, escape-to-close, and ARIA state.
+
+**Used by:** Tooltip, Popover, HoverCard, Dropdown, Select, Combobox, DatePicker, TimePicker, ColorPicker, Cascader, TreeSelect, Mentions, Command, NavigationMenu, ContextMenu, Popconfirm, Tour
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `triggerEl` | `HTMLElement` | — | Element that triggers the overlay |
+| `contentEl` | `HTMLElement` | — | Floating content element |
+| `opts.trigger` | `'click'\|'hover'\|'manual'` | `'click'` | Activation mode |
+| `opts.closeOnEscape` | `boolean` | `true` | Escape key closes overlay |
+| `opts.closeOnOutside` | `boolean` | `true` | Click outside closes overlay |
+| `opts.hoverDelay` | `number` | `200` | ms delay before showing (hover mode) |
+| `opts.hoverCloseDelay` | `number` | `150` | ms delay before hiding (hover mode) |
+| `opts.onOpen` | `Function` | — | Called when overlay opens |
+| `opts.onClose` | `Function` | — | Called when overlay closes |
+| `opts.usePopover` | `boolean` | `false` | Use Popover API instead of display toggle |
+
+**Returns:** `{ open(), close(), toggle(), isOpen(): boolean, destroy() }`
+
+**ARIA managed:** `aria-expanded` on `triggerEl` (`'true'`/`'false'`)
+
+```javascript
+const overlay = createOverlay(btn, panel, { trigger: 'hover', hoverDelay: 300 });
+onDestroy(() => overlay.destroy());
+```
+
+---
+
+## Navigation
+
+### `createListbox(containerEl, opts?)`
+
+Keyboard navigation + selection for option lists. Manages highlight, arrow keys, enter/space selection, type-ahead search, and scroll-into-view.
+
+**Used by:** Select, Combobox, Command, Cascader, TreeSelect, Transfer, Mentions, AutoComplete, ContextMenu, Dropdown
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `containerEl` | `HTMLElement` | — | Listbox container |
+| `opts.itemSelector` | `string` | `'.d-option'` | CSS selector for option elements |
+| `opts.activeClass` | `string` | `'d-option-active'` | Class for highlighted item |
+| `opts.disabledSelector` | `string` | `'.d-option-disabled'` | Selector for disabled items |
+| `opts.loop` | `boolean` | `true` | Loop at list boundaries |
+| `opts.orientation` | `'vertical'\|'horizontal'` | `'vertical'` | Arrow key axis |
+| `opts.multiSelect` | `boolean` | `false` | Allow multi-selection |
+| `opts.typeAhead` | `boolean` | `false` | Type-to-search (500ms buffer) |
+| `opts.onSelect` | `Function` | — | Called with `(element, index)` |
+| `opts.onHighlight` | `Function` | — | Called with `(element, index)` |
+
+**Returns:** `{ highlight(index), highlightNext(), highlightPrev(), selectCurrent(), getActiveIndex(): number, reset(), handleKeydown(e), destroy() }`
+
+**ARIA managed:** `aria-selected` on each option (`'true'`/`'false'`)
+
+**Keys handled:** ArrowDown/ArrowUp (or ArrowRight/ArrowLeft for horizontal), Home, End, Enter, Space, type-ahead characters
+
+```javascript
+const listbox = createListbox(panel, { typeAhead: true, onSelect: (el, i) => pick(i) });
+onDestroy(() => listbox.destroy());
+```
+
+### `createRovingTabindex(containerEl, opts?)`
+
+Roving tabindex pattern for groups. One element has `tabindex=0`, rest have `tabindex=-1`. Arrow keys move focus.
+
+**Used by:** Tabs, RadioGroup, ToggleGroup, Segmented, Menu, Menubar, ButtonGroup, Toolbar
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `containerEl` | `HTMLElement` | — | Container element |
+| `opts.itemSelector` | `string` | `'[role="tab"]'` | Selector for navigable items |
+| `opts.orientation` | `'horizontal'\|'vertical'\|'both'` | `'horizontal'` | Arrow key axes |
+| `opts.loop` | `boolean` | `true` | Loop at boundaries |
+| `opts.onFocus` | `Function` | — | Called with `(element, index)` |
+
+**Returns:** `{ focus(index), setActive(index), getActive(): number, destroy() }`
+
+**ARIA managed:** `tabindex` on each item (`'0'` or `'-1'`)
+
+**Keys handled:** ArrowRight/ArrowLeft (horizontal), ArrowDown/ArrowUp (vertical), Home, End
+
+```javascript
+const roving = createRovingTabindex(tabList, { itemSelector: '[role="tab"]' });
+onDestroy(() => roving.destroy());
+```
+
+### `createDisclosure(triggerEl, contentEl, opts?)`
+
+Expand/collapse with smooth height animation. Does not add document-level listeners.
+
+**Used by:** Accordion, Collapsible, Tree, NavigationMenu sections
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `triggerEl` | `HTMLElement` | — | Toggle trigger |
+| `contentEl` | `HTMLElement` | — | Collapsible content |
+| `opts.defaultOpen` | `boolean` | `false` | Initial state |
+| `opts.animate` | `boolean` | `true` | Smooth height transition |
+| `opts.onToggle` | `Function` | — | Called with `(isOpen)` |
+
+**Returns:** `{ open(), close(), toggle(), isOpen(): boolean }`
+
+**ARIA managed:** `aria-expanded` on `triggerEl`
+
+**Keys handled:** Enter, Space on trigger
+
+**Note:** No `destroy()` — uses only element-level listeners (cleaned up with the element).
+
+```javascript
+const disc = createDisclosure(header, body, { defaultOpen: true });
+```
+
+---
+
+## Focus
+
+### `createFocusTrap(containerEl)`
+
+Traps Tab/Shift+Tab cycling within focusable elements. Focuses first focusable on activate.
+
+**Used by:** Modal, Drawer, AlertDialog, Command
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `containerEl` | `HTMLElement` | Container to trap focus within |
+
+**Returns:** `{ activate(), deactivate() }`
+
+**Focusable selector:** `a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])`
+
+**Keys handled:** Tab, Shift+Tab
+
+**Cleanup:** Call `deactivate()` via `onDestroy()`.
+
+```javascript
+const trap = createFocusTrap(panel);
+trap.activate();
+onDestroy(() => trap.deactivate());
+```
+
+---
+
+## Interaction
+
+### `createDrag(el, opts)`
+
+Lightweight pointer-based drag handler. Tracks pointer movement with delta from start position.
+
+**Used by:** Slider, Resizable, Transfer, DnD sorting
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `el` | `HTMLElement` | Draggable element |
+| `opts.onMove` | `Function` | Called with `(x, y, dx, dy, event)` |
+| `opts.onStart` | `Function` | Called with `(x, y, event)` |
+| `opts.onEnd` | `Function` | Called with `(x, y, event)` |
+
+**Returns:** `{ destroy() }`
+
+```javascript
+const drag = createDrag(handle, { onMove: (x, y, dx, dy) => update(dx) });
+onDestroy(() => drag.destroy());
+```
+
+### `createHotkey(el, bindings)`
+
+Keyboard shortcut registration with modifier normalization, chord sequences, and Mac meta-key handling.
+
+**Used by:** Command, Modal, custom app shortcuts
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `el` | `HTMLElement\|Document` | Scope element for key events |
+| `bindings` | `Object<string, Function>` | Map of shortcut string to handler |
+
+**Shortcut format:** `'ctrl+k'`, `'shift+alt+n'`, `'meta+enter'`, `'g g'` (chord). Modifiers: `ctrl`, `shift`, `alt`, `meta`/`cmd`/`command`. On Mac, `ctrl` matches both Ctrl and Meta.
+
+**Returns:** `{ destroy(), update(newBindings) }`
+
+```javascript
+const hk = createHotkey(document, { 'ctrl+k': openSearch, 'g g': goTop });
+onDestroy(() => hk.destroy());
+```
+
+---
+
+## Scroll
+
+### `createVirtualScroll(containerEl, opts)`
+
+Renders only visible items + buffer for large lists. Fixed item height.
+
+**Used by:** DataTable, Tree (large), Transfer, Select (many options)
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `containerEl` | `HTMLElement` | — | Scrollable container |
+| `opts.itemHeight` | `number` | — | Fixed item height (px) |
+| `opts.totalItems` | `number` | — | Total item count |
+| `opts.buffer` | `number` | `5` | Extra items above/below viewport |
+| `opts.renderItem` | `Function` | — | `(index) => HTMLElement` |
+
+**Returns:** `{ refresh(), setTotal(n), destroy() }`
+
+```javascript
+const vs = createVirtualScroll(container, { itemHeight: 36, totalItems: 10000, renderItem: renderRow });
+onDestroy(() => vs.destroy());
+```
+
+### `createInfiniteScroll(containerEl, opts)`
+
+Triggers load-more when a sentinel element enters the viewport via IntersectionObserver.
+
+**Used by:** List (infinite mode), feeds, search results
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `containerEl` | `HTMLElement` | — | Scrollable container |
+| `opts.loadMore` | `Function` | — | Async callback to load more data |
+| `opts.threshold` | `number` | `200` | Distance (px) from bottom to trigger |
+| `opts.sentinel` | `HTMLElement` | auto-created | Custom sentinel element |
+
+**Returns:** `{ destroy(), loading(): boolean }`
+
+```javascript
+const inf = createInfiniteScroll(list, { loadMore: fetchNextPage, threshold: 300 });
+onDestroy(() => inf.destroy());
+```
+
+### `createScrollSpy(root, opts?)`
+
+Tracks which observed section is visible. Calls callback when active section changes.
+
+**Used by:** TableOfContents, workbench navigation, documentation layouts
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `root` | `HTMLElement\|null` | — | Scroll container (`null` = viewport) |
+| `opts.rootMargin` | `string` | `'-20% 0px -60% 0px'` | IntersectionObserver margin |
+| `opts.threshold` | `number` | `0` | Visibility threshold |
+| `opts.onActiveChange` | `Function` | — | Called with `(element)` |
+
+**Returns:** `{ observe(el), unobserve(el), disconnect() }`
+
+**Cleanup:** Call `disconnect()` via `onDestroy()`.
+
+```javascript
+const spy = createScrollSpy(null, { onActiveChange: (el) => highlight(el.id) });
+sections.forEach(s => spy.observe(s));
+onDestroy(() => spy.disconnect());
+```
+
+---
+
+## Layout
+
+### `createMasonry(containerEl, opts?)`
+
+Pinterest-style layout via shortest-column placement. Auto-recalculates on resize via ResizeObserver.
+
+**Used by:** Image galleries, card grids
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `containerEl` | `HTMLElement` | — | Container whose children are laid out |
+| `opts.columns` | `number` | `3` | Number of columns |
+| `opts.gap` | `number` | `16` | Gap between items (px) |
+
+**Returns:** `{ refresh(), setColumns(n), destroy() }`
+
+```javascript
+const masonry = createMasonry(grid, { columns: 4, gap: 24 });
+onDestroy(() => masonry.destroy());
+```
+
+---
+
+## Form
+
+### `createFormField(controlEl, opts?)`
+
+Wraps a form control with label, help text, error message, and required indicator. Manages ARIA attributes reactively.
+
+**Used by:** All form inputs (Input, Select, Checkbox, Switch, etc.)
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `controlEl` | `HTMLElement` | The input/select/textarea element |
+| `opts.label` | `string` | Label text |
+| `opts.error` | `string\|Function` | Static or reactive (getter) error message |
+| `opts.help` | `string` | Help text |
+| `opts.required` | `boolean` | Show required indicator |
+| `opts.class` | `string` | Additional CSS class on wrapper |
+
+**Returns:** `HTMLElement` (the `d-field` wrapper)
+
+**ARIA managed:** `aria-describedby` (links to help text), `aria-invalid`, `aria-errormessage` (links to error), `aria-hidden` on required indicator
+
+**Note:** No `destroy()` — uses `createEffect` for reactive error tracking (cleaned up by reactivity system).
+
+```javascript
+const input = h('input', { type: 'text', class: 'd-input' });
+const field = createFormField(input, { label: 'Email', error: () => emailErr(), required: true });
+```
+
+---
+
+## Utilities
+
+### `caret(direction?, opts?)`
+
+Shared chevron icon for dropdowns, accordions, and other disclosure components.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `direction` | `'down'\|'up'\|'right'\|'left'` | `'down'` | Arrow direction |
+| `opts` | `Object` | `{}` | Passed to `icon()`, plus optional `class` |
+
+**Returns:** `HTMLElement` (SVG icon with class `d-caret`)
+
+```javascript
+trigger.appendChild(caret('down'));
+```
+
+### `createCheckControl(opts?)`
+
+Styled checkbox for compound components. Returns same structure as Checkbox component.
+
+**Used by:** Transfer, Tree, TreeSelect, DataTable
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `opts` | `Object` | Attributes for `<input type="checkbox">` |
+
+**Returns:** `{ wrap: HTMLElement, input: HTMLInputElement }`
+
+```javascript
+const { wrap, input } = createCheckControl({ checked: true });
+row.appendChild(wrap);
+```
+
+---
+
+## Quick Reference
+
+| Primitive | Category | Has `destroy()`? | Document listeners? |
+|-----------|----------|-------------------|---------------------|
+| `createOverlay` | Overlay | Yes | Yes (keydown, mousedown) |
+| `createListbox` | Navigation | Yes | No (container only) |
+| `createRovingTabindex` | Navigation | Yes | No (container only) |
+| `createDisclosure` | Navigation | No | No |
+| `createFocusTrap` | Focus | `deactivate()` | No (container only) |
+| `createDrag` | Interaction | Yes | Yes (pointermove, pointerup during drag) |
+| `createHotkey` | Keyboard | Yes | Yes (keydown) |
+| `createVirtualScroll` | Scroll | Yes | No (container scroll) |
+| `createInfiniteScroll` | Scroll | Yes | No (IntersectionObserver) |
+| `createScrollSpy` | Scroll | `disconnect()` | No (IntersectionObserver) |
+| `createMasonry` | Layout | Yes | No (ResizeObserver) |
+| `createFormField` | Form | No | No |
+| `createCheckControl` | Utility | No | No |
+| `caret` | Utility | No | No |
+
+---
+
+**See also:** `reference/component-lifecycle.md`, `reference/compound-spacing.md`

package/reference/build-tooling.md

@@ -0,0 +1,275 @@
+# Build Tooling Reference
+
+Production build pipeline. Entry: `decantr build` or `node cli/commands/build.js`. Output: `dist/`.
+
+## Build Pipeline
+
+| Step | Description | File |
+|------|-------------|------|
+| 1. Config | Load `decantr.config.json`, merge defaults, apply CLI flag overrides | `cli/commands/build.js` |
+| 2. Resolve | BFS from `src/app.js` — resolve all static imports (decantr/* + relative) into module map | `tools/builder.js` `resolveModules()` |
+| 3. Incremental check | MD5 hash all source files + HTML, compare to cache — skip rebuild if unchanged | `tools/builder.js` |
+| 4. Bundle | Topological sort modules, rewrite imports/exports into IIFE with module variables (`_m0`, `_m1`, ...) | `tools/builder.js` `bundle()` |
+| 5. Tree shake | Remove unused exports per-module via usage graph analysis | `tools/builder.js` `treeShakeModule()` |
+| 6. Icon tree shake | Scan for `icon('name')` calls, prune unreferenced entries from `ESSENTIAL`/`EXTENDED` objects | `tools/builder.js` `treeShakeIcons()` |
+| 7. Style elimination | Detect used addon styles via `setStyle()`/`setTheme()` + Essence, remove unused addon modules | `tools/builder.js` `detectUsedStyles()` + `eliminateUnusedAddonStyles()` |
+| 8. Component CSS pruning | Map dependency graph to CSS sections, remove unused `componentCSSMap` entries | `tools/builder.js` `detectUsedComponents()` + `pruneComponentCSS()` |
+| 9. Code split | Detect `import()` calls, resolve each as separate chunk, inject runtime loader | `tools/builder.js` `resolveChunks()` |
+| 10. CSS extract | Scan all source for `css('...')` and `class: '...'` patterns, generate `@layer d.atoms{...}` | `tools/css-extract.js` |
+| 11. Static CSS extraction | If safe (`canStaticExtract()`), replace `css/index.js` with passthrough, remove `atoms.js` + `runtime.js` | `tools/builder.js` `staticExtractTransform()` |
+| 12. CSS purge | Scan bundled JS for referenced atom class names, strip unreferenced rules | `tools/builder.js` `purgeCSS()` |
+| 13. Minify | Strip comments, collapse whitespace, remove unnecessary semicolons | `tools/minify.js` |
+| 14. Write | Content-hashed filenames (`app.{hash}.js`, `app.{hash}.css`), rewrite HTML script/link tags | `tools/builder.js` |
+| 15. Copy public | Copy `public/` to `dist/`, transform all `.html` files with asset references | `tools/builder.js` |
+| 16. Report | Print per-asset sizes (raw, gzip, brotli), compression ratios, module breakdown (top 15) | `tools/builder.js` |
+| 17. Cache save | Write MD5 hashes to `node_modules/.decantr-cache/build-cache.json` | `tools/builder.js` |
+
+## Build-Time Style Elimination
+
+Non-core styles live in `src/css/styles/addons/` and are imported explicitly by user code (e.g., `import { clean } from 'decantr/styles/clean'`). Only `auradecantism` is a built-in. Unused addon style modules are detected and removed at build time.
+
+**Detection** (`detectUsedStyles()`):
+1. Scans all user source files for `setStyle('...')` and `setTheme('...')` calls
+2. Checks `decantr.essence.json` for `vintage.style` declarations (including sectioned essences)
+3. Checks `decantr.config.json` for style references
+4. Collects the set of actually-used style IDs
+
+**Elimination** (`eliminateUnusedAddonStyles()`):
+- Removes unused addon style module files (`src/css/styles/addons/*.js`) from the module map
+- Since addon styles are no longer imported by `theme-registry.js`, there are no import lines to remove from the registry
+
+The default style (auradecantism) is always kept as a built-in. Only addon styles explicitly referenced via `setStyle()`, `setTheme()`, or the Essence are shipped.
+
+## Component CSS Pruning
+
+Component CSS (`src/css/components.js`) is structured as a keyed object (`componentCSSMap`) with 78 sections. At build time, unused sections are pruned based on which components appear in the dependency graph.
+
+**Detection** (`detectUsedComponents()`):
+- Maps component source files found in the dependency graph to their corresponding CSS section keys via `COMPONENT_CSS_MAP`
+- The `global` section is always retained
+
+**Pruning** (`pruneComponentCSS()`):
+- Removes unused sections from `componentCSSMap` in the bundled output
+- A baseline app using no components prunes 77/78 sections (everything except `global`), saving ~65 KB raw
+
+## Static CSS Extraction
+
+When safe, the entire atom resolution runtime (`atoms.js` + `runtime.js`) is eliminated and replaced with a pre-generated static CSS file.
+
+**Safety valve** (`canStaticExtract()`):
+- Checks for `define()` calls in user code (custom atoms require runtime)
+- Checks for dynamic `css()` patterns (template literals, variable concatenation)
+- If either is detected, falls back to full runtime — no static extraction
+
+**Transform** (`staticExtractTransform()`):
+- Replaces `css/index.js` with a ~673 byte passthrough that converts `_group` to `d-group`, `_peer` to `d-peer`, and joins class names
+- Removes `atoms.js` and `runtime.js` from the module map entirely
+- All atom CSS rules are pre-generated into the static CSS file by `tools/css-extract.js`
+- Saves ~31 KB raw (atoms.js + runtime.js eliminated)
+
+**CSS generation** (`tools/css-extract.js` `generateCSS()`):
+- Handles all atom types: standard, responsive (`_sm:gc3`), container queries (`_cq640:gc3`), group/peer (`_gh:fgprimary`), opacity modifiers (`_bgprimary/50`), and arbitrary values (`_w[512px]`)
+- Output is a `@layer d.atoms{...}` block with all referenced atoms pre-resolved
+
+## Tree Shaking
+
+**Usage graph analysis** (`buildUsageGraph()`):
+1. For each module, collect which named exports are imported by other modules
+2. Side-effect imports (`import './foo'`) or namespace imports mark all exports as used (`*`)
+3. Per-module, exports not in the used set are candidates for removal
+
+**Removal logic** (`treeShakeModule()`):
+- Skip if wildcard (`*`) — module has side-effect consumers
+- For each unused export, count references within the module itself (`\bname\b` regex)
+- If `refCount >= 2`, the export is used internally — keep it
+- If `refCount < 2`, remove the full declaration (function body via brace counting, const/let via semicolon-at-depth-0)
+
+**Icon tree shaking** (`treeShakeIcons()`):
+- Scans bundled output for `icon('name')` calls
+- Rewrites `ESSENTIAL = {...}` and `EXTENDED = {...}` objects to include only referenced icon entries
+- Runs after main tree shake, before code splitting
+
+## Code Splitting
+
+**Detection**: `findDynamicImports()` scans all modules for `import('specifier')` patterns (relative or `decantr/*`).
+
+**Chunk generation** (`resolveChunks()`):
+1. For each dynamic import target not already in the main bundle, resolve its full dependency tree
+2. Remove modules already in main bundle (shared code stays in main)
+3. Bundle each chunk independently with tree shaking
+4. Wrap chunk as `window.__decantrChunk = (function(){...})();`
+5. Minify, content-hash filename: `{chunk-name}.{hash}.js`
+
+**Runtime loader** (injected into main bundle):
+```js
+function __decantrLoadChunk(url) {
+  return new Promise(function(r, e) {
+    var s = document.createElement('script');
+    s.src = url;
+    s.onload = function() { r(window.__decantrChunk) };
+    s.onerror = e;
+    document.head.appendChild(s);
+  })
+}
+```
+
+Dynamic `import()` calls rewritten to `__decantrLoadChunk('./assets/{chunk-file}')`.
+
+## Source Maps
+
+| Property | Value |
+|----------|-------|
+| Spec | V3 |
+| Encoding | VLQ (Base64) |
+| `sourcesContent` | Embedded (original source inlined) |
+| Output file | `assets/app.{hash}.js.map` |
+| Reference | `//# sourceMappingURL=./app.{hash}.js.map` appended to JS |
+
+Mappings track per-module: output line range mapped to source file + proportional source line. Column-level mapping is output-col-0 only.
+
+## Incremental Builds
+
+| Item | Detail |
+|------|--------|
+| Cache location | `{project}/node_modules/.decantr-cache/build-cache.json` |
+| Hash algorithm | MD5 |
+| Scope | All resolved module sources + `public/index.html` |
+| Combined hash | MD5 of `JSON.stringify(fileHashes) + htmlHash` |
+| Skip condition | Combined hash matches cache AND `dist/` directory exists |
+| Cache write | After successful build completes |
+
+## CSS Purging
+
+**Class name detection** — three scan passes over bundled JS:
+
+| Pass | Pattern | Extracts |
+|------|---------|----------|
+| String literals | `['"\`]([^'"\`]*?)['"\` ]` | Tokens containing `_`, split by whitespace, keep `_`-prefixed |
+| `css()` calls | `css\s*\(\s*['"\`](...)['"` ]\s*\)` | All whitespace-separated tokens |
+| `class:` props | `class:\s*['"](...)['"` ] | All whitespace-separated tokens |
+
+**Rule removal**: Parses CSS within `@layer d.atoms{...}`, extracts class name from each `.class{...}` rule, removes rules whose class name is not in the referenced set.
+
+## Minification
+
+`tools/minify.js` — zero-dependency JS minifier.
+
+| Step | Action |
+|------|--------|
+| 1 | Stash template literals (protect multi-line content) |
+| 2 | Strip JSDoc (`/** */`), block comments (`/* */`), single-line comments (`//`) |
+| 3 | Trim lines, skip empty lines |
+| 4 | Collapse whitespace outside strings (keep space only between `\w` characters) |
+| 5 | Remove semicolons before `}` |
+| 6 | Collapse newlines around braces |
+| 7 | Join statements — newline after `}`, space before `else`/`catch`/`finally`/`while` |
+| 8 | Restore stashed template literals |
+
+No variable renaming or advanced optimizations — structural minification only.
+
+## Bundle Analysis
+
+**Embeddable API** (`tools/analyzer.js`):
+```js
+import { analyzeBundle } from './tools/analyzer.js';
+const { report, stats } = analyzeBundle(bundledJS, cssOutput, { html });
+```
+
+**Standalone**:
+```
+node tools/analyzer.js [dist-dir]
+```
+
+**Output**: asset table (raw/gzip/brotli per file), module breakdown (top 10 by size with bar chart), compression ratios.
+
+**Built-in analysis** (in builder): when `analyze` is enabled, prints module breakdown (top 15) sorted by size descending, with percentage of total JS.
+
+**Compression**: gzip (default zlib) + Brotli quality 11 reported for all assets.
+
+## CLI Flags
+
+| Flag | Config Key | Default | Effect |
+|------|-----------|---------|--------|
+| `--no-sourcemap` | `sourcemap` | `true` | Skip source map generation |
+| `--no-analyze` | `analyze` | `true` | Skip module breakdown report |
+| `--no-incremental` | `incremental` | `true` | Force full rebuild (ignore cache) |
+| `--no-code-split` | `codeSplit` | `true` | Bundle all code into single file |
+| `--no-purge` | `purgeCSS` | `true` | Keep all CSS atoms (no dead CSS elimination) |
+| `--no-tree-shake` | `treeShake` | `true` | Keep all exports (no dead JS elimination) |
+
+All features enabled by default. CLI flags override config file values.
+
+## Config File
+
+`decantr.config.json` in project root. The `build` section:
+
+```json
+{
+  "build": {
+    "outDir": "dist",
+    "inline": false,
+    "sourcemap": true,
+    "analyze": true,
+    "incremental": true,
+    "codeSplit": true,
+    "purgeCSS": true,
+    "treeShake": true
+  }
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `outDir` | `string` | `"dist"` | Output directory (relative to project root) |
+| `inline` | `boolean` | `false` | Reserved — inline JS/CSS into HTML |
+| `sourcemap` | `boolean` | `true` | Generate V3 source maps |
+| `analyze` | `boolean` | `true` | Print module breakdown after build |
+| `incremental` | `boolean` | `true` | Enable MD5 hash cache for skip-if-unchanged |
+| `codeSplit` | `boolean` | `true` | Split dynamic imports into separate chunks |
+| `purgeCSS` | `boolean` | `true` | Remove unreferenced CSS atom rules |
+| `treeShake` | `boolean` | `true` | Remove unused JS exports |
+
+Config is loaded first, then CLI `--no-*` flags override to `false`.
+
+## Output Structure
+
+```
+dist/
+  index.html                    # Transformed HTML with asset references
+  assets/
+    app.{hash}.js               # Bundled + minified JS
+    app.{hash}.js.map           # Source map (if enabled)
+    app.{hash}.css              # Extracted + purged atomic CSS
+    {chunk}.{hash}.js           # Code-split chunks (if any)
+  ...                           # Copied public/ assets (non-HTML copied as-is, HTML transformed)
+```
+
+## Key Files
+
+| File | Role |
+|------|------|
+| `cli/commands/build.js` | CLI entry — config loading, flag parsing, invokes `build()` |
+| `tools/builder.js` | Core build pipeline — resolve, bundle, tree shake, code split, purge, report |
+| `tools/css-extract.js` | `extractClassNames()` + `generateCSS()` — scan source for atoms (including responsive, container query, group/peer, opacity, arbitrary), emit `@layer d.atoms` |
+| `tools/minify.js` | `minify()` — structural JS minification |
+| `tools/analyzer.js` | `analyzeBundle()` — standalone or embeddable bundle size analysis |
+
+## Bundle Optimization Results (Baseline App)
+
+| Metric | Before | After | Reduction |
+|--------|--------|-------|-----------|
+| Raw JS | 133.8 KB | 52.6 KB | 60.7% |
+| Gzip JS | 29.3 KB | 14.6 KB | 50.2% |
+| Brotli JS | 24.8 KB | 12.9 KB | 48.0% |
+
+Breakdown by optimization phase:
+
+| Phase | Savings (raw) | What is eliminated |
+|-------|---------------|-------------------|
+| Style elimination | ~17 KB | 4 unused style modules (clean, retro, glassmorphism, command-center) |
+| Component CSS pruning | ~65 KB | 77/78 unused `componentCSSMap` sections |
+| Static CSS extraction | ~31 KB | `atoms.js` + `runtime.js` (css() becomes passthrough) |
+
+---
+
+**See also:** `reference/dev-server-routes.md`, `reference/atoms.md`