@livenetworks/ashlar 2.1.12 → 2.1.13

package/README.md

@@ -107,7 +107,7 @@ Combine autonomous components directly in semantic HTML — **zero initializatio
 
 ### 1. 🏛️ Dual-Core Architecture (SSR + Client-Side SPA)
 - **Backend-First Progressive HTML Enhancement (SSR):** Your backend (Laravel, Go, Django, Rails) delivers indexable, semantic HTML. Elements auto-activate via attributes (`data-ln-modal`, `data-ln-filter`, `data-ln-table`).
-- **Client-Side Single-Page Applications (SPA / JSON Mode):** Built-in client router (`ln-router`), compound hash-state codec (`hash.js`), 3-tier local storage (`ln-data-store`), and microtask-batched Proxy reactivity (`deepReactive`, `renderList`) when client JSON APIs are required.
+- **Client-Side Single-Page Applications (SPA / JSON Mode):** Built-in client router (`ln-router`), compound hash-state codec (`hash.js`), 3-tier local storage (`ln-data-store`), and microtask-batched state rendering (`createBatcher`, `renderList`) when client JSON APIs are required.
 
 ### 2. 🤖 AI-Native & MCP Surface
 - **Machine-Readable Component Corpus (`docs-mcp/`):** Schema-validated documentation served directly to AI agent workflows via Model Context Protocol (MCP).
@@ -184,7 +184,7 @@ Deep architectural blueprints detailing the engine driving `ln-ashlar`.
 | 📖 **[Architecture Philosophy](docs/architecture/philosophy.md)** | The DOM-First engineering manifesto detailing computing cycles, framework EOL risks, performance, security, **and full 17-category comparison tables**. |
 | 🔄 **[Data Flow Architecture](docs/architecture/data-flow.md)** | Rules governing how data moves. Splits responsibilities into **four isolated concerns**: Data (`ln-data-store` + `ln-data-coordinator`), Render (`ln-table`), Submit (`ln-form`), and Validate (`ln-validate`). Details the **parallel fan-out write pipeline** with Mermaid sequence diagrams. |
 | 🧭 **[3-Tier Local-First Storage Specs](docs/architecture/data-store-architecture.md)** | Technical reference for decoupling storage caches (`ln-data-store`), network gateways (`ln-*-connector`), and data transformations (`ln-mapper`). |
-| ⚡ **[Reactive Architecture Reference](docs/reactive.md)** | Blueprint on how components manage internal state using Proxy traps (`reactiveState` and `deepReactive`), batched microtask rendering, DOM bindings (`fill`, `renderList`), and attribute-to-state bridges. |
+| ⚡ **[Reactive Architecture Reference](docs/reactive.md)** | Blueprint on how components manage state using microtask batching (`createBatcher`), DOM bindings (`fill`, `renderList`), and attribute-to-state bridges. |
 | 📐 **[Design System Specifications](docs/architecture/reference.md)** | Complete styling specs covering CSS Custom Properties, layout grids, buttons, responsive breakpoints, typography hierarchies, dark mode theming, and icons. |
 | 🛡️ **[Security & Threat Mitigation](docs/architecture/security.md)** | Deep architectural security analysis covering Web Crypto API encryption-at-rest, strict CSP compliance (no dynamic eval), sensitive DOM attribute protections, and the same-origin AJAX fragment trust boundary. |
 | 🧠 **[Architect Overview Guide](docs/architecture/overview.md)** | Master developer guide introducing the DOM-First doctrine, component inventories, override architectures, and new project integration pipelines. |
@@ -270,6 +270,29 @@ For detailed manual instructions, properties, attributes, and events of individu
 
 ---
 
+---
+
+## 🎨 Dual CSS Engine Architecture
+
+`ln-ashlar` offers dual-engine visual styling with 100% design parity across all components and layouts:
+
+1. **Native Ashlar SCSS:** Class-free semantic HTML styling and design tokens. Optimized for minimal CSSOM invalidation by eliminating mixin selector explosions and `:not(:has())` bottlenecks.
+2. **Tailwind CSS v4 Engine:** Utility-first stylesheet compiled directly with Tailwind v4 `@theme` tokens (`npm run build:tailwind`).
+
+See [Theme Architecture & SCSS Guidelines](theme/README.md) for details.
+
+---
+
+## 🧪 Automated Testing & Performance Suite
+
+`ln-ashlar` includes an automated headless verification and benchmarking harness comparing both CSS engines:
+
+- **Visual & Design Suite (`npm run test:visual`):** Validates responsive layout, horizontal overflow, and reactive UI across all 67 demo admin pages.
+- **JS Performance Suite (`npm run test:perf`):** Benchmarks execution latency, DOM node churn, and JS heap memory across 46 interactive JS components.
+- **Historical Comparison (`npm run test:perf:compare`):** Tracks performance trends across git commits and alerts on performance regressions (`>20%`).
+
+See [Headless Testing Documentation](tests/headless/README.md) for full usage and options.
+
 ## 🖥️ Interactive Demo Site
 
 `ln-ashlar` ships with a complete local dashboard environment inside `demo/admin/`. The demo is itself a project consuming `ln-ashlar`, showing real-world layout structures, component setups, and customized semantic SCSS:

package/components/COMPONENTS.md

@@ -69,7 +69,7 @@ Every component is an IIFE (Immediately Invoked Function Expression). Shared hel
 
 ```javascript
 import { dispatch } from '../ln-core';
-import { deepReactive, createBatcher } from '../ln-core';
+import { createBatcher } from '../ln-core';
 
 (function () {
     const DOM_SELECTOR = 'data-ln-{name}';
@@ -96,8 +96,6 @@ import { deepReactive, createBatcher } from '../ln-core';
 | `fillTemplate(clone, data)` | Replace `{{ key }}` text-node placeholders in cloned template with `data[key]` values |
 | `buildDict(root, selector)` | Read hidden i18n elements once at init, return plain object, remove from DOM |
 | `renderList(container, items, tpl, keyFn, fillFn, tag)` | Keyed list rendering with DOM reuse |
-| `reactiveState(initial, onChange)` | Shallow Proxy — onChange(prop, value, old) per set |
-| `deepReactive(obj, onChange)` | Deep Proxy — onChange() on any nested change |
 | `createBatcher(renderFn, afterRender)` | Coalesce multiple sync state changes into one render |
 
 Import only what the component needs. Vite tree-shakes unused exports.
@@ -213,80 +211,86 @@ function _domObserver() {
 
 ---
 
-## Reactive Rendering Pattern
-
-When a component has **multiple internal state properties** that together drive DOM updates, use `reactiveState` + `createBatcher` + `fill()` from ln-core. This eliminates manual querySelector chains and coalesces multiple synchronous state changes into a single DOM update.
-
-### The three primitives
-
-| Helper | Role |
-|--------|------|
-| `reactiveState(initial, onChange)` | Proxy — calls `onChange(prop, value, old)` on every top-level property set |
-| `createBatcher(renderFn, afterRender)` | Coalesces sync state changes into one `renderFn` call via `queueMicrotask` |
-| `fill(root, data)` | Writes state to DOM via `data-ln-field`, `data-ln-attr`, `data-ln-show`, `data-ln-class` |
-
-### Pattern
-
-```javascript
-import { reactiveState, createBatcher, fill, dispatch } from '../ln-core';
-
-function _component(dom) {
-    this.dom = dom;
-    const self = this;
-
-    const queueRender = createBatcher(
-        function () { self._render(); },      // runs after current sync block
-        function () { self._afterRender(); }  // runs after render — dispatch events here
-    );
-
-    this.state = reactiveState({ key: null, value: null }, queueRender);
-}
-
-_component.prototype._render = function () {
-    fill(this.dom, this.state);
-    // additional DOM logic derived from state
-};
-
-_component.prototype._afterRender = function () {
-    dispatch(this.dom, 'ln-component:changed', { key: this.state.key });
-};
-```
-
-When multiple properties change in the same sync block:
-
-```javascript
-this.state.key = 'status';   // queues render
-this.state.value = 'active'; // queues again — same microtask, no duplicate
-// → microtask fires → _render() once → _afterRender() once
-```
-
-### `reactiveState` vs `deepReactive`
-
-| | `reactiveState` | `deepReactive` |
-|---|---|---|
-| **Depth** | Shallow — top-level sets only | Deep — nested object/array mutations |
-| **onChange args** | `(prop, value, old)` | `()` — no args |
-| **Use when** | Flat state with primitive values | State contains nested objects or arrays |
-
-### `fill()` — limitations
-
-`fill()` sets `textContent` for `data-ln-field` — it does **not** set `.value` on `<input>`, `<textarea>`, or `<select>`. For form elements, set `.value` manually after `fill()`.
-
-### When to use
-
-Use reactive rendering when a component has **2+ state properties** that together drive DOM, and multiple changes happen in the same sync block.
-
-**Don't use it for:**
-- Single boolean state — `this.isOpen = true; dom.classList.toggle(...)` is simpler
-- Event-driven rendering — components that receive data via `set-data` events (ln-table)
-- One-shot renders — clone template + fill once, no ongoing state
-
-### Used in
-
-*No library component currently uses this pattern. It remains documented for project-level components that need multi-property reactive state.*
-
----
-
+## Reactive Rendering Pattern
+
+When a component has **multiple internal state properties** or frequent updates that drive DOM updates, use `createBatcher` + `fill()` from ln-core. This eliminates manual querySelector chains and coalesces multiple synchronous state changes into a single DOM update.
+
+### The core primitives
+
+| Helper | Role |
+|--------|------|
+| `createBatcher(renderFn, afterRender)` | Coalesces sync state changes into one `renderFn` call via `queueMicrotask` |
+| `fill(root, data)` | Writes state to DOM via `data-ln-field`, `data-ln-attr`, `data-ln-show`, `data-ln-class` |
+
+### Pattern
+
+```javascript
+import { createBatcher, fill, dispatch } from '../ln-core';
+
+function _component(dom) {
+    this.dom = dom;
+    const self = this;
+
+    this.state = { key: null, value: null };
+
+    this.queueRender = createBatcher(
+        function () {
+            if (!self._destroyed) {
+                self._render();
+            }
+        },      // runs after current sync block
+        function () {
+            if (!self._destroyed) {
+                self._afterRender();
+            }
+        }  // runs after render — dispatch events here
+    );
+}
+
+_component.prototype._render = function () {
+    fill(this.dom, this.state);
+    // additional DOM logic derived from state
+};
+
+_component.prototype._afterRender = function () {
+    dispatch(this.dom, 'ln-component:changed', { key: this.state.key });
+};
+
+_component.prototype.update = function (key, value) {
+    this.state.key = key;
+    this.state.value = value;
+    this.queueRender(); // Multiple sync updates trigger exactly ONE render pass
+};
+```
+
+When multiple properties change in the same sync block:
+
+```javascript
+this.state.key = 'status';
+this.state.value = 'active';
+this.queueRender();
+// → microtask fires → _render() once → _afterRender() once
+```
+
+### `fill()` — limitations
+
+`fill()` sets `textContent` for `data-ln-field` — it does **not** set `.value` on `<input>`, `<textarea>`, or `<select>`. For form elements, set `.value` manually after `fill()`.
+
+### When to use
+
+Use `createBatcher` when a component has **frequent or multiple state updates** (e.g. search input, filter checkboxes, sorting), and multiple updates can occur in the same synchronous cycle.
+
+**Don't use it for:**
+- Single boolean state — `this.isOpen = true; dom.classList.toggle(...)` is simpler
+- Event-driven rendering — components that receive data via `set-data` events (ln-table)
+- One-shot renders — clone template + fill once, no ongoing state
+
+### Used in
+
+Used in `ln-search`, `ln-filter`, `ln-list`, and `ln-data-coordinator` for microtask render coalescing.
+
+---
+
 ## CustomEvent Communication
 
 Components do NOT know about each other. Communication ONLY via CustomEvent.
@@ -985,7 +989,7 @@ The component calls `_ensureDefaultItemTemplate()` at the top of `_initUpload()`
 
 | Component | Pattern | Data Attr | Description |
 |-----------|---------|-----------|------|
-| ln-core | Shared module | — | cloneTemplate, cloneTemplateScoped, dispatch, dispatchCancelable, fill, fillTemplate, renderList, buildDict, guardBody, findElements, reactiveState, deepReactive, createBatcher, createWindowCache |
+| ln-core | Shared module | — | cloneTemplate, cloneTemplateScoped, dispatch, dispatchCancelable, fill, fillTemplate, renderList, buildDict, guardBody, findElements, createBatcher, createWindowCache |
 | ln-toggle | Instance | `data-ln-toggle` | Generic toggle (sidebar, collapse) |
 | ln-accordion | Instance | `data-ln-accordion` | Wrapper — only one toggle open at a time |
 | ln-tabs | Instance | `data-ln-tabs` | Tab navigation — URL hash (anchor triggers) or localStorage persist (button triggers) |

package/components/ln-core/README.md

@@ -13,7 +13,7 @@ ln-core exposes helpers in these categories:
 - **DOM binding** — declarative data-attribute-driven rendering (`fill`, `renderList`, `fillTemplate`)
 - **Forms & Inputs** — serialize/populate by field `name`, intercept input value getters/setters (`interceptValueProperty`)
 - **Target & Event Predicates** — `shouldIgnoreClick`, `isTargetDisabled`, `isUsableTarget`, `isEditableTarget`
-- **Reactivity** — `reactiveState`, `deepReactive`, `createBatcher`
+- **Reactivity & Batching** — microtask-coalesced render batcher (`createBatcher`)
 - **Windowing** — sliding-window sparse cache for server-side virtualization (`createWindowCache`)
 - **Layout & Positioning** — viewport-aware positioning (`computePlacement`), measurement (`measureHidden`)
 - **Hash codec** — namespaced URL fragment state (`hashParse`, `hashGet`, `hashSet`, `hashSortEncode`, `hashSortDecode`, `hashFilterEncode`, `hashFilterDecode`, `resolveHashNamespace`)
@@ -542,37 +542,6 @@ fetch('/tpl.html').then(html => {
 
 ## reactive.js
 
-### reactiveState(initial, onChange)
-
-Shallow `Proxy` — fires `onChange(prop, value, old)` on every property set. No-op if value hasn't changed.
-
-```js
-const state = reactiveState({ searchTerm: '', sortCol: -1 }, function (prop, value, old) {
-    batchRender();
-});
-```
-
-- Returns a Proxy wrapping a shallow copy of `initial`
-- Only tracks direct property assignments (not nested objects)
-- Used by `ln-filter` for flat state
-
-### deepReactive(obj, onChange)
-
-Deep `Proxy` — recursively wraps nested objects and arrays. Fires `onChange()` (no args) on any nested mutation.
-
-```js
-const state = deepReactive({ toasts: [], files: [] }, function () {
-    batchRender();
-});
-state.toasts.push({ title: 'Hello' }); // triggers onChange
-```
-
-- Wraps existing nested objects on creation
-- Auto-wraps newly assigned objects/arrays
-- `deleteProperty` also triggers `onChange`
-- Internal `Symbol('deepReactive')` flag prevents double-wrapping
-- Used by `ln-toast`, `ln-upload` for complex state
-
 ### createBatcher(renderFn, afterRender)
 
 Coalesce multiple synchronous state changes into a single `renderFn` call via `queueMicrotask`.
@@ -586,43 +555,28 @@ const batchRender = createBatcher(
 
 - Multiple calls to `schedule()` within the same microtask result in one `renderFn` call
 - Optional `afterRender` callback fires after each render
-- Pattern: `deepReactive(state, batchRender)` — every state mutation schedules a batched render
-
----
-
-## Reactive Rendering Pattern
-
-The three reactive primitives (`reactiveState` / `deepReactive` +
-`createBatcher` + `fill`) are designed to be used together. They are
-the canonical ln-ashlar render loop:
-
-1. **State mutation.** Component code assigns to a property on a
-   reactive proxy (`this.state.value = 'x'`). The proxy fires its
-   onChange callback.
-2. **Microtask queue.** The onChange is wired to a `createBatcher`
-   schedule function. Any number of synchronous assignments in the
-   same sync block schedule a single microtask.
-3. **One render.** When the microtask fires, the batcher calls
-   `renderFn` exactly once. `renderFn` typically calls `fill(this.dom,
-   this.state)` (or `renderList` for keyed collections) to project
-   state into the DOM, then the optional `afterRender` callback fires
-   (commonly used to dispatch a `ln-{component}:rendered` event).
-
-Two assignments on the same tick produce one DOM update. External
-callers that need to set several properties at once do not need a
-`batch()` helper — the batcher handles it.
-
-The pattern is: **state mutation → microtask queue → one render**.
-Never wire a reactive onChange directly to `_render()` without a
-batcher between them — you will get one render per assignment, and
-the DOM will thrash.
-
-For the full decision matrix (`reactiveState` vs `deepReactive`, when
-to use this pattern at all, anti-patterns), see
-[Reactive Rendering Pattern in components/COMPONENTS.md](../../components/COMPONENTS.md#reactive-rendering-pattern).
+- Pattern: used in `ln-search`, `ln-filter`, `ln-list`, `ln-data-coordinator` to debounce/coalesce state and render operations
 
 ---
 
+## Reactive Rendering Pattern
+
+The `createBatcher` primitive and DOM rendering helpers (`fill`, `renderList`) are designed to be used together as the canonical ln-ashlar microtask render loop:
+
+1. **State mutation.** Component updates internal data properties (e.g. `this.state.key = 'val'`).
+2. **Microtask queue.** The component triggers the `schedule()` function returned by `createBatcher`. Any number of synchronous assignments in the same sync block schedule a single microtask.
+3. **One render.** When the microtask fires, the batcher calls `renderFn` exactly once. `renderFn` typically calls `fill(this.dom, this.state)` (or `renderList` for keyed collections) to project state into the DOM, then the optional `afterRender` callback fires (commonly used to dispatch a `ln-{component}:rendered` or changed event).
+
+Two state assignments on the same tick produce one DOM update:
+
+The pattern is: **state mutation → microtask queue → one render**.
+Never wire sync state updates directly to immediate DOM writes when multiple attributes or filter parameters can change simultaneously — batching prevents layout thrashing.
+
+For further details, see
+[Reactive Rendering Pattern in components/COMPONENTS.md](../../components/COMPONENTS.md#reactive-rendering-pattern).
+
+---
+
 ## window-cache.js
 
 ### createWindowCache(config)
@@ -981,7 +935,7 @@ Returns `true` if the element is an `<input>`, `<textarea>`, `<select>`, or `[co
 ## Typical Usage Pattern
 
 ```js
-import { dispatch, dispatchCancelable, guardBody, findElements, deepReactive, createBatcher, fill, renderList } from '../ln-core';
+import { dispatch, dispatchCancelable, guardBody, findElements, createBatcher, fill, renderList } from '../ln-core';
 
 (function () {
     const DOM_SELECTOR = 'data-ln-example';
@@ -997,8 +951,10 @@ import { dispatch, dispatchCancelable, guardBody, findElements, deepReactive, cr
         const self = this;
 
         // Reactive state + batched rendering
-        const batchRender = createBatcher(function () { self._render(); });
-        this.state = deepReactive({ items: [] }, batchRender);
+                this.state = { items: [] };
+        this.batchRender = createBatcher(function () {
+            if (!self._destroyed) self._render();
+        });
 
         return this;
     }

package/components/ln-core/index.js

@@ -1,5 +1,5 @@
 export { cloneTemplate, cloneTemplateScoped, dispatch, dispatchCancelable, requestData, fill, lnFill, fillTemplate, renderList, buildDict, guardBody, findElements, isVisible, shouldIgnoreClick, isTargetDisabled, isUsableTarget, isEditableTarget, serializeForm, populateForm, resolveFormMethod, getLocale, readValue, detectValueType, compareValues, registerComponent, shouldInterceptLink, buildUrl, getHeaders, parseHeaders, registerDataMapper, getDataMapper, interceptValueProperty, registerLocaleFallback, getLocaleFallback, holdInit, releaseInit, pendingCount, queueBoot, ensureLocaleObserver, observeAttributes, observeLifecycle, withoutLifecycle, setDebugSink, setPersistSink, isDevMode, hasActiveDebug } from './helpers.js';
-export { reactiveState, deepReactive, createBatcher } from './reactive.js';
+export { createBatcher } from './reactive.js';
 export { createWindowCache } from './window-cache.js';
 export { hashParse, hashGet, hashSet, hashLinkClick, resolveHashNamespace, hashSortEncode, hashSortDecode, hashFilterEncode, hashFilterDecode } from './hash.js';
 export { queryParse, queryGet, querySet, resolveQueryParam, querySortEncode, querySortDecode, queryFilterEncode, queryFilterDecode } from './query.js';

package/components/ln-core/reactive.js

@@ -1,62 +1,3 @@
-// ─── Shallow Reactive ──────────────────────────────────────
-
-export function reactiveState(initial, onChange) {
-	return new Proxy(Object.assign({}, initial), {
-		set(target, prop, value) {
-			const old = target[prop];
-			if (old === value) return true;
-			target[prop] = value;
-			onChange(prop, value, old);
-			return true;
-		}
-	});
-}
-
-// ─── Deep Reactive ─────────────────────────────────────────
-
-const PROXY_FLAG = Symbol('deepReactive');
-
-export function deepReactive(obj, onChange) {
-	function wrap(target) {
-		if (target === null || typeof target !== 'object') return target;
-		if (target[PROXY_FLAG]) return target;
-
-		// Recursively wrap existing nested objects/arrays
-		const keys = Object.keys(target);
-		for (let i = 0; i < keys.length; i++) {
-			const val = target[keys[i]];
-			if (val !== null && typeof val === 'object') {
-				target[keys[i]] = wrap(val);
-			}
-		}
-
-		return new Proxy(target, {
-			get(t, prop) {
-				if (prop === PROXY_FLAG) return true;
-				return t[prop];
-			},
-			set(t, prop, value) {
-				const old = t[prop];
-				if (value !== null && typeof value === 'object') {
-					value = wrap(value);
-				}
-				t[prop] = value;
-				if (old !== value) onChange();
-				return true;
-			},
-			deleteProperty(t, prop) {
-				if (prop in t) {
-					delete t[prop];
-					onChange();
-				}
-				return true;
-			}
-		});
-	}
-
-	return wrap(obj);
-}
-
 // ─── Render Batcher ────────────────────────────────────────
 
 export function createBatcher(renderFn, afterRender) {