@livenetworks/ashlar 1.6.0 → 2.0.0

package/{js → components}/ln-core/README.md

@@ -1,32 +1,45 @@
 # ln-core
 
 Shared helper module imported by all components — re-exported from
-`js/ln-core/index.js`. No DOM attribute, no constructor, no
-MutationObserver. Source: `js/ln-core/`.
+`components/ln-core/index.js`. No DOM attribute, no constructor, no
+MutationObserver. Source: `components/ln-core/`.
 
 ## Helpers
 
 ln-core exposes helpers in these categories:
 
 - **Templates** — clone and populate `<template>` fragments
-- **Events** — dispatch standard and cancelable CustomEvents; shared data-request cycle for collection components (`requestData`)
+- **Events & Lifecycle** — dispatch standard/cancelable CustomEvents; shared data-request cycle (`requestData`); `registerComponent` for MutationObserver-backed auto-init
 - **DOM binding** — declarative data-attribute-driven rendering (`fill`, `renderList`, `fillTemplate`)
-- **Forms** — serialize/populate by field `name`
-- **Dictionaries** — extract i18n strings from hidden elements
-- **Discovery** — `registerComponent` for MutationObserver-backed auto-init
+- **Forms & Inputs** — serialize/populate by field `name`, intercept input value getters/setters (`interceptValueProperty`)
+- **Target & Event Predicates** — `shouldIgnoreClick`, `isTargetDisabled`, `isUsableTarget`, `isEditableTarget`
 - **Reactivity** — `reactiveState`, `deepReactive`, `createBatcher`
 - **Windowing** — sliding-window sparse cache for server-side virtualization (`createWindowCache`)
-- **Layout** — viewport-aware positioning, teleport, measurement
-- **Persistence** — localStorage wrappers with `ln:` prefix
-- **Hash codec** — namespaced URL fragment state (`hashParse`, `hashGet`, `hashSet`)
+- **Layout & Positioning** — viewport-aware positioning (`computePlacement`), measurement (`measureHidden`)
+- **Hash codec** — namespaced URL fragment state (`hashParse`, `hashGet`, `hashSet`, `hashSortEncode`, `hashSortDecode`, `hashFilterEncode`, `hashFilterDecode`, `resolveHashNamespace`)
 - **Cryptography** — high-performance Web Crypto helpers for encryption at rest (`crypto.js`)
-
-Source of truth: `js/ln-core/helpers.js`, `js/ln-core/reactive.js`, and `js/ln-core/crypto.js`. Import from `'../ln-core'` (barrel).
+- **Searching & Filtering** — query tokenization, multi-field and filter matching (`matching.js`)
+- **Comparing & Sorting** — type inference and localized/numeric comparison (`compare.js`)
+- **Progress Math** — clamp and percentage calculations (`progress.js`)
+- **Date Utilities** — flexible date input parsing and ISO formatting (`date.js`)
+- **Number Utilities** — locale-aware separators, number sanitizing, parsing, and formatting (`number.js`)
+- **Attribute Contracts & Parsers** — attribute specs, live getters, typed readers, and dev-time validation (`attrSpec`, `defineAttrs`, `attrStr`, `attrInt`, `attrFloat`, `attrBool`, `attrEnum`, `attrJson`, `validateAttrValue`, `isDevMode`) (`attrs.js`)
+
+Source of truth: modular sub-files in `components/ln-core/`. Import from `'../../ln-core'` (barrel).
+
+## Core Helpers & Submodules (`helpers.js`)
+
+`helpers.js` serves as the centralized, backward-compatible named barrel re-exporting the specialized domain submodules:
+- `template.js` — template cloning, declarative DOM binding (`fill`, `lnFill`, `fillTemplate`, `renderList`, `buildDict`).
+- `events.js` — CustomEvent dispatchers (`dispatch`, `dispatchCancelable`, `requestData`), debug sinks and dev mode checks.
+- `dom.js` — DOM guard and interactive target predicates (`guardBody`, `isVisible`, `shouldIgnoreClick`, `isUsableTarget`, etc.).
+- `form.js` — form method resolution, serialization, population, and `interceptValueProperty`.
+- `http.js` — URL assembly, HTTP headers compilation/parsing, and data mapper registry.
+- `locale.js` — locale detection (`getLocale`), observer, and locale fallback registry.
+- `lifecycle.js` — component registration (`registerComponent`), element scanning (`findElements`), and shared MutationObservers.
 
 ---
 
-## helpers.js
-
 ### cloneTemplate(name, componentTag)
 
 Clone a `<template data-ln-template="name">` element. Cached after first lookup.
@@ -114,12 +127,12 @@ window.lnCore.lnFill(modalEl, record);   // record → fill; null → reset/clea
 
 - Also dispatches `ln-fill` at `container` itself when it matches
   `[data-ln-form]` or `[data-ln-fillable]` — so `lnFill(formEl, record)` works
-  when called directly on a form element. Source: `js/ln-core/helpers.js` L164–165.
+  when called directly on a form element. Source: `components/ln-core/template.js` (`lnFill`).
 - `container` — any element; scans its entire subtree.
 - `record` — plain object or `null`.
 - Dispatches `ln-fill` (`bubbles: true`, `detail = record ?? null`) at each target.
 - Returns `container` for chaining.
-- Exported from `js/ln-core/index.js`; available at `window.lnCore.lnFill`.
+- Exported from `components/ln-core/index.js`; available at `window.lnCore.lnFill`.
 - Back-compat: `ln-form` also still accepts `ln-form:fill` / `ln-form:reset` (aliases).
 
 ### fillTemplate(clone, data)
@@ -143,7 +156,7 @@ fillTemplate(frag, { text: 'Engineering' });
   root element itself when it is an `Element`, since `querySelectorAll` does not include
   root). For each attribute whose value contains `{{`, replaces tokens via
   `el.setAttribute(attr.name, resolved)`. Uses `setAttribute` — never `innerHTML` —
-  so injection risk is the same as `data-ln-attr`. Source: `js/ln-core/helpers.js` L197–233.
+  so injection risk is the same as `data-ln-attr`. Source: `components/ln-core/template.js` (`fillTemplate`).
 - Missing keys produce empty string in both passes
 - No-op in either pass when no `{{` is present
 - Returns `clone` for chaining
@@ -153,7 +166,7 @@ fillTemplate(frag, { text: 'Engineering' });
 
 ### renderList(container, items, templateName, keyFn, fillFn, componentTag)
 
-Keyed list rendering with DOM reuse. Existing children matched by `data-ln-key` attribute.
+Keyed list rendering with DOM reuse. Existing children matched by `data-ln-render-key` attribute.
 
 ```js
 renderList(
@@ -168,7 +181,7 @@ renderList(
 
 - `keyFn(item)` returns a unique string key for each item
 - `fillFn(el, item, index)` updates the DOM element with item data
-- Reuses existing elements with matching `data-ln-key` (avoids re-clone)
+- Reuses existing elements with matching `data-ln-render-key` (avoids re-clone)
 - Replaces all container children atomically (`textContent = '' + appendChild(frag)`)
 - Calls `fillTemplate(clone, item)` automatically for newly-cloned elements — `{{ key }}` placeholders in the template resolve from the item data without extra wiring.
 
@@ -295,12 +308,12 @@ populated.forEach(function (el) { dispatch(el, 'input'); });
 - **Decoupled fill key (`data-ln-fill-as`)** — match key for the fill direction is
   `el.getAttribute('data-ln-fill-as') || el.name`. When `data-ln-fill-as` is set,
   the record key is the fill-as value and `name` stays as the form submission key.
-  Source: `populateForm` in `js/ln-core/helpers.js`.
+  Source: `populateForm` in `components/ln-core/form.js`.
 - **Checkbox string coercion** — a single checkbox (one element with that `name` in
   the form) whose fill value is a string is coerced via `_coerceBool`: `"false"`,
   `"0"`, `""`, `"off"`, `"no"` (case-insensitive, trimmed) → unchecked; anything
   else → checked. This handles `data-ln-fill-*` values which always arrive as
-  strings. Source: `_coerceBool` + `populateForm` in `js/ln-core/helpers.js`.
+  strings. Source: `_coerceBool` + `populateForm` in `components/ln-core/form.js`.
 - Checkbox + array → `checked` if `el.value` is in the array.
 - Checkbox group (same `name`, 2+ elements) + scalar → treated as comma-separated list (`"admin,editor"` → membership check).
 - Single checkbox + scalar → boolean coercion: `"false"/"0"/"off"/"no"/""` → unchecked; anything else → checked.
@@ -326,11 +339,13 @@ Read the raw machine value behind a formatted cell/item display. The single
 read path for value-based sort/filter across components.
 
 ```js
-const raw = readValue(td); // '1250.50' from data-ln-value, else trimmed text
+const raw = readValue(td); // '1250.50' from data-ln-value, datetime on <time>, value on <data>, else trimmed text
 ```
 
 - Returns `data-ln-value` attribute value if the element has it.
-- Otherwise returns `el.textContent.trim()`.
+- Returns `datetime` attribute if the element is `<time>` and has it.
+- Returns `value` attribute if the element is `<data>` and has it.
+- Otherwise falls back to `el.textContent.trim()`.
 - Used by `ln-table` for sort/filter.
 
 ### registerComponent(selector, attribute, ComponentFn, componentTag, options)
@@ -345,8 +360,9 @@ import { registerComponent } from '../ln-core';
 function _component(dom) { this.dom = dom; /* ... */ }
 
 registerComponent('data-ln-example', 'lnExample', _component, 'ln-example', {
-    extraAttributes: ['data-ln-example-state'],
-    onAttributeChange: function (target, name) { /* attribute → state bridge */ },
+    effects: {
+        'data-ln-example-state': function (target, name, oldValue) { /* attribute → state bridge */ }
+    },
     onInit: function (root) { /* post-init hook, per added subtree */ }
 });
 ```
@@ -355,18 +371,172 @@ registerComponent('data-ln-example', 'lnExample', _component, 'ln-example', {
   if it contains `[`, `.`, or `#` (e.g. `'[data-ln-foo]:not([disabled])'`).
 - `attribute` — JS-side key used both as `window[attribute]` (the
   constructor function) and `el[attribute]` (the per-element instance).
-- `options.extraAttributes` — additional attribute names to include in
-  the MutationObserver's `attributeFilter` (e.g. state attributes set
-  by coordinator).
-
-  > **Coverage rule:** `extraAttributes` must include every attribute your `onAttributeChange` handler — and any helper it calls synchronously — reads from the element as an input to what it renders or derives. The observed set is *primary attribute + `extraAttributes`*; an attribute read but not observed will not trigger a re-sync when it changes. Behaviour flags checked only at a transition (e.g. `data-ln-persist`, read at open/close to decide a side-effect) are exempt — a mid-life change to them is not meant to re-render.
-- `options.onAttributeChange(target, attrName)` — called when a
-  filtered attribute changes on an already-initialized element. The
+- `options.attributes` — the component's attribute table. One entry per host
+  attribute the component reads or reacts to. Derives the `effects` map, the
+  live-getter spec (via `attrSpec` at call site), and scopes `options.onAttrChange` —
+  only declared keys reach the catch-all. When present, `options.effects` is ignored.
+- `options.effects` — `{ attributeName: handler(target, name, oldValue) }`.
+  A per-attribute reaction dispatched by the shared attribute observer's
+  registry. Fires when the mutated element already owns an instance
+  (`el[attribute]` is truthy) and the attribute name starts with `data-ln-`.
+- `options.onAttrChange(target, name, oldValue)` — catch-all reaction for
+  any `data-ln-*` attribute on the host not covered by an `effects` key and
+  present in `options.attributes` when a table is supplied. Without a table, the
+  catch-all is unscoped and fires for every `data-ln-*` attribute on the host.
+  Same instance and prefix gate as `effects`.
+- `options.onAttributeChange(target, attrName)` — called when an attribute
+  in this registration's observed set (the selector's own attribute name,
+  plus `extraAttributes`) changes on an already-initialized element. The
   attribute → state bridge hook.
+- `options.extraAttributes` — additional attribute names, beyond the
+  selector's own, added to this registration's observed set in the shared
+  attribute registry (e.g. state attributes set by a coordinator). Read by
+  the `onAttributeChange` path.
 - `options.onInit(root)` — called after `findElements` per subtree
   (initial DOM, added childList nodes, attribute-mutated subtrees).
+- `options.onSubtreeChange(host, mutation)` — called on every `childList`
+  mutation inside this registration's observed subtree, where `host` is the
+  nearest ancestor (or the mutated node itself) matching `selector`. Runs
+  alongside, not instead of, the added/removed-node instantiation and
+  teardown `registerComponent` already performs.
 - Returns the constructor function (also stored at `window[attribute]`).
 
+### observeAttributes(names, handler)
+
+For components that own their own lifecycle (bespoke `childList` logic that
+doesn't fit `registerComponent`'s shape) and need only the attribute half of
+the shared attribute-observer invariant.
+
+```js
+import { observeAttributes } from '../ln-core';
+
+observeAttributes(['href'], function (el, name, oldValue) {
+    _processLink(el);
+});
+```
+
+- `names` — attribute names to watch. No `data-ln-` prefix gate, no instance
+  gate — every mutation of a watched name calls `handler`, on any element.
+- `handler(el, attributeName, oldValue)`.
+- Installs onto the same shared `MutationObserver` used by `registerComponent`
+  (one observer on `document.body`, no `attributeFilter`).
+- A component using `observeAttributes` must **not** run its own attribute
+  `MutationObserver` alongside it — that duplicates delivery.
+- Two standing exceptions keep their own private observer instead of using
+  this: `ln-progress` (observes an attribute on its **parent**, outside the
+  host-only boundary the shared observer covers) and `ln-icon` (the only
+  component in the library that imports nothing — pulling in `ln-core`'s
+  module-level side effects would roughly quadruple its standalone bundle
+  size). Neither is an oversight; do not migrate them.
+
+### setPersistSink(sink)
+
+Nullable persist restore/save sink. Installed/removed only by `ln-persist`
+(`components/ln-persist/src/ln-persist.js`) — mirrors `setDebugSink`'s shape
+exactly. `findElements` calls `window.lnCore._persistSink(el, selector)`
+for any element carrying `data-ln-persist`, immediately before constructing
+its owning component's instance, when the sink is installed.
+
+```js
+import { setPersistSink } from '../ln-core';
+
+setPersistSink(function (el, selector) {
+    // restore/save logic keyed off the registry's persist: entries
+});
+```
+
+- `sink(el, selector)` — called synchronously inside `findElements`, before
+  the element's component instance is constructed.
+- No sink installed (`ln-persist` not loaded) → the check is a no-op.
+- See `components/ln-persist/README.md` for the full restore/save contract.
+
+### defineAttrs(instance, dom, spec), attrSpec(table), attrEffects(table)
+
+Define live, getter-only properties on a component instance that read the DOM
+on every access. One table per component is the single source of truth for its
+host attributes, feeding `defineAttrs` via `attrSpec` and `registerComponent` via
+`attributes`.
+
+```js
+import { registerComponent, defineAttrs, attrSpec, attrInt, attrBool, attrList } from '../ln-core';
+
+const ATTRIBUTES = {
+    'data-ln-example-window':  { prop: '_windowSize', read: attrInt, fallback: 1000, effect: _applyWindowSize },
+    'data-ln-example-tags':    { prop: '_tags',       read: attrList },
+    'data-ln-example-no-sync': { prop: 'noSync',      read: attrBool }
+};
+
+const ATTR_SPEC = attrSpec(ATTRIBUTES);
+
+function _component(dom) {
+    defineAttrs(this, dom, ATTR_SPEC);
+}
+
+registerComponent('data-ln-example', 'lnExample', _component, 'ln-example', {
+    attributes: ATTRIBUTES
+});
+```
+
+- `table` — `{ [attributeName]: { prop, read, fallback, effect } }`.
+- `attrSpec(table)` — derives `{ propName: [reader, attributeName, fallback] }` for entries declaring `prop`.
+- `attrEffects(table)` — derives `{ [attributeName]: effect }` for entries declaring `effect` (returns `null` when empty).
+- `spec` — `{ propName: [reader, attributeName, fallback] }`.
+- `attrStr` — returns `fallback` when the attribute is absent, else the raw
+  string.
+- `attrInt` — `parseInt(..., 10)`; returns `fallback` on `NaN`. `"0"` stays
+  `0` — unlike the common `parseInt(attr, 10) || fallback` idiom, which maps
+  `"0"` to `fallback`. Check call sites relying on that idiom before swapping
+  them to `attrInt`.
+- `attrBool` — `(el, name, fallback)`: returns `fallback` when the attribute is absent, `false` when `"false"` or `"0"`, and `true` otherwise (`""`, `"true"`, `"1"`).
+- `attrList` — `(el.getAttribute(name) || '').split(',').map(trim).filter(Boolean)`.
+  Allocates a new array per read — do not call inside a per-row loop.
+- `reader` can be any function of that `(el, name, fallback)` shape, so a
+  component can pass its own for special-cased parsing.
+- **Getter-only — assignment throws** (`TypeError`, strict mode). Nothing is
+  copied into instance state, so there is no state to invalidate and no sync
+  step; a drifting copy is structurally impossible. Before migrating an
+  existing `this.prop = ...` assignment to a `defineAttrs` getter, grep for
+  every place the codebase assigns to that property after construction — a
+  hit means the property is not a pure attribute mirror and does not belong
+  in the spec. (`ln-data-store`'s `windowed` is excluded for exactly this
+  reason: `destroy()` assigns `this.windowed = false`.)
+- **Attribute names must be inline string literals or a `const` bound to a
+  literal — never concatenated or templated.**
+  `scripts/sync-ln-schemas.mjs:22-23` is a raw regex over file text; a
+  constructed name is invisible to it and the CI docs gate breaks silently.
+
+### Frozen-attribute convention
+
+A **frozen attribute** is a constructor-only attribute — one that physically
+cannot be re-read at runtime (e.g. an IndexedDB schema fixed at open time).
+When a frozen attribute is edited after init, the component writes
+`data-ln-{component}-frozen` on its own host, with the attempted attribute
+name as the value, and a co-located `*-dev.scss` rule surfaces it through the
+`dev-dom-error` mixin under `[data-ln-debug]`. Never `console.warn` for this
+case — it is a CSS-only dev affordance. See `ln-data-store` for the reference
+implementation (`_markFrozen`, `ln-data-store-dev.scss`).
+
+### holdInit() / releaseInit() / pendingCount() / queueBoot(fn)
+
+Boot gating primitives for asynchronous loading (such as external partial templates). Prevents components from initializing (sweeping the DOM) before all external resources have finished loading.
+
+```js
+import { holdInit, releaseInit, pendingCount, queueBoot } from '../ln-core';
+
+// In an async component's initialization:
+holdInit();
+fetch('/tpl.html').then(html => {
+    // populate DOM
+    releaseInit();
+});
+```
+
+- `holdInit()` — Increments the global boot holds counter (`window.lnCore._bootHolds`).
+- `releaseInit()` — Decrements the global boot holds counter. If the counter reaches zero, it drains the queue (`window.lnCore._bootQueue`) in push order.
+- `pendingCount()` — Returns the current number of active boot holds.
+- `queueBoot(fn)` — If `pendingCount() > 0`, queues the function in `_bootQueue`. Otherwise, schedules it immediately using `setTimeout(fn, 0)` (to match standard event loop scheduling).
+- Used internally by `registerComponent` and `ln-ui-coordinator` to prevent race conditions during async initialization.
+
 ---
 
 ## reactive.js
@@ -448,7 +618,7 @@ 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 js/COMPONENTS.md](../../js/COMPONENTS.md#reactive-rendering-pattern).
+[Reactive Rendering Pattern in components/COMPONENTS.md](../../components/COMPONENTS.md#reactive-rendering-pattern).
 
 ---
 
@@ -549,26 +719,6 @@ panel.setAttribute('data-ln-placement', placement);
   pair → clamps to viewport edge if nothing fits.
 - Pure function. No DOM side effects.
 
-### teleportToBody(el)
-
-Move an element into `<body>`, leaving a comment placeholder so it can
-be restored to its original parent.
-
-```js
-const restore = teleportToBody(panel);
-// ... later
-restore();
-```
-
-- Returns a cleanup function that restores the element to its origin.
-- No-op + no-op cleanup if the element is already in `<body>` or
-  parent is missing.
-- Used for floating UI that needs to escape `overflow: hidden`
-  ancestors (popovers, dropdowns).
-- Does NOT set inline styles — the caller's CSS rule (e.g.
-  `[data-ln-popover] { position: fixed }`) is responsible for
-  positioning context.
-
 ### measureHidden(el)
 
 Read `offsetWidth` / `offsetHeight` of an element that may currently
@@ -587,93 +737,8 @@ const { width, height } = measureHidden(panel);
 
 ---
 
-## persist.js
-
-### persistGet(component, el)
-
-Read persisted value for an element. Returns the parsed JSON value or `null` (not found, or storage unavailable).
-
-- `component` — component name string (e.g. `'toggle'`, `'tabs'`, `'filter'`)
-- `el` — DOM element with `data-ln-persist` attribute
-
-Storage key resolved from `el`: uses `data-ln-persist` value if non-empty, otherwise element's `id`. If neither exists, emits `console.warn` and returns `null`.
-
-```js
-import { persistGet } from '../ln-core';
-const saved = persistGet('toggle', el); // null | 'open' | 'close'
-```
-
-### persistSet(component, el, value)
-
-Write a value to localStorage. Value is JSON-serialized. Silently no-ops if localStorage is unavailable or full.
-
-```js
-import { persistSet } from '../ln-core';
-persistSet('toggle', el, 'open');
-persistSet('sort', el, { field: 'name', column: null, direction: 'desc' });
-persistSet('filter', el, null);  // explicitly clears
-```
-
-### persistRemove(component, el)
-
-Remove a single persisted value for a specific element.
-
-```js
-import { persistRemove } from '../ln-core';
-persistRemove('tabs', el);
-```
-
-### persistClear(component)
-
-Remove ALL persisted values for a given component type. Scans all localStorage keys matching `ln:{component}:*`.
-
-```js
-import { persistClear } from '../ln-core';
-persistClear('toggle');     // removes all ln:toggle:* keys
-persistClear('sort'); // removes all ln:sort:* keys
-```
-
-Useful for "reset to defaults" functionality.
-
-### Storage key format
-
-```
-ln:{component}:{pagePath}:{id}
-```
-
-- `pagePath` — `location.pathname`, lowercase, trailing slash stripped, or `/` for root
-- `id` — element's `id` attribute, or the explicit `data-ln-persist="custom-key"` value
-
-Examples:
-```
-ln:toggle:/admin/users:sidebar
-ln:tabs:/settings:settings-tabs
-ln:sort:/admin/orders:orders-table-name
-ln:filter:/admin/users:status-filter
-```
-
-### Opt-in HTML attribute
-
-```html
-<!-- Uses element id as storage key -->
-<section id="sidebar" data-ln-toggle="close" data-ln-persist>
-
-<!-- Explicit key (no id needed) -->
-<section data-ln-toggle="close" data-ln-persist="sidebar-section">
-```
-
-Persistence is always opt-in. Elements without `data-ln-persist` are never touched.
-
-Components that support `data-ln-persist` document the stored value
-shape in their own READMEs (ln-toggle, ln-accordion, ln-tabs,
-ln-sort, ln-filter).
-
-### Graceful degradation
-
-- localStorage disabled (private browsing) → silent no-op, components work normally without persistence
-- localStorage full → silent no-op on write, existing data preserved
-- Stale data (panel removed from DOM, column index out of range) → orphan key ignored gracefully
-- Missing `id` + no explicit key → `console.warn` once, persistence skipped for that element
+Persistence now lives in the standalone `ln-persist` component — see
+`components/ln-persist/README.md`.
 
 ---
 
@@ -763,15 +828,17 @@ const key = getCryptoKey(); // null or CryptoKey
 
 - **Returns** `CryptoKey` or `null` if no key has been derived yet.
 
-### encryptData(plainData, key = null)
+### encryptData(plainData, keyOrOptions = null)
 
-Encrypt any serializable value (objects/arrays are converted to JSON strings).
+Encrypt any serializable value (objects/arrays are converted to JSON strings). Enforces fail-closed semantics (throws `Error` if no key is set or encryption fails).
 
 ```js
 import { encryptData } from '../ln-core';
 
 const result = await encryptData({ text: 'Sensitive message' });
 // {
+//   v: 1,
+//   alg: 'AES-GCM',
 //   encrypted: true,
 //   iv: 'base64-iv-string...',
 //   data: 'base64-ciphertext...'
@@ -779,23 +846,134 @@ const result = await encryptData({ text: 'Sensitive message' });
 ```
 
 - **`plainData`** — any primitive value, array, or object.
-- **`key`** — optional custom `CryptoKey`. Defaults to the active global key.
-- **Returns** `Promise<Object>` containing `encrypted: true`, base64 `iv`, and base64 `data`. Returns raw `plainData` if no active key is available.
+- **`keyOrOptions`** — optional custom `CryptoKey` or options object `{ key?: CryptoKey }`. Defaults to the active key.
+- **Returns** `Promise<Object>` containing version 1 envelope (`v: 1`, `alg: 'AES-GCM'`, `encrypted: true`, `iv`, `data`). Throws `Error` on failure.
 
-### decryptData(encryptedObject, key = null)
+### decryptData(encryptedObject, keyOrOptions = null)
 
-Decrypt an encrypted object back into its original form (automatically parsing JSON strings back to objects).
+Decrypt an encrypted envelope back into its original form (automatically parsing JSON strings back to objects). Supports both v1 envelopes and legacy v0 unversioned envelopes. Enforces fail-closed semantics unless `{ silent: true }` is specified.
 
 ```js
 import { decryptData } from '../ln-core';
 
 const decrypted = await decryptData(result);
 console.log(decrypted.text); // 'Sensitive message'
+
+// Resilient bulk-read mode:
+const resilient = await decryptData(corruptObject, { silent: true });
+// returns { ...corruptObject, decryptionError: true } instead of throwing
 ```
 
 - **`encryptedObject`** — an object generated by `encryptData`.
-- **`key`** — optional custom `CryptoKey`. Defaults to the active global key.
-- **Returns** `Promise<any>`. The original plain data, or `{ ...encryptedObject, decryptionError: true }` if decryption failed (e.g., incorrect key).
+- **`keyOrOptions`** — optional custom `CryptoKey` or options object `{ key?: CryptoKey, silent?: boolean }`.
+- **Returns** `Promise<any>`. The original plain data. Throws `Error` on decryption failure or missing key unless `{ silent: true }` is passed.
+
+---
+
+## matching.js
+
+Pure string searching, tokenization, and multi-filter matching engine.
+
+### normalizeSearchTerm(raw)
+
+Trims and lowercases user search queries.
+
+### tokenizeSearchQuery(raw)
+
+Splits query on whitespace for multi-term AND matching. Returns an array of lowercase search tokens.
+
+### matchesSearchTokens(text, tokens)
+
+Evaluates whether text contains all search tokens (case-insensitive AND match).
+
+### matchesFilterValues(text, values)
+
+Evaluates whether text matches any of the active filter values (case-insensitive OR match).
+
+---
+
+## compare.js
+
+Type inference and localized/numeric comparison engine.
+
+### detectValueType(values)
+
+Iterates values in a dataset or column. If all non-empty values are finite numbers, returns `'number'`; otherwise returns `'string'`.
+
+### compareValues(a, b, type, locale)
+
+Performs null-safe comparison (-1, 0, 1):
+- `null`/`undefined` collation: sorts first or last deterministically.
+- `type === 'number'`: numeric difference `a - b`.
+- `type === 'string'`: localized comparison via `Intl.Collator(locale, { numeric: true, sensitivity: 'base' })`.
+
+---
+
+## progress.js
+
+Pure mathematical clamping and progress calculations.
+
+### calculateProgress(rawValue, rawMax, min = 0)
+
+Computes `{ value, min, max, clampedValue, percentage }` where percentage is bounded between 0% and 100%.
+
+---
+
+## date.js
+
+Pure date input parsing and ISO formatting.
+
+### parseDateInput(raw)
+
+Parses Date objects, ISO strings (`YYYY-MM-DD` or `YYYY-MM-DDTHH:mm:ssZ`), and Unix seconds/milliseconds timestamps into a valid `Date` instance (or `null` if invalid).
+
+A date-only `YYYY-MM-DD` string is read as local midnight of that calendar day, not UTC midnight (the native `Date` reading), so it round-trips through `formatDateToISO` unchanged in every timezone. A non-existent calendar date (`2026-02-31`) returns `null`.
+
+### formatDateToISO(date)
+
+Converts a `Date` instance to standard `YYYY-MM-DD` string representation.
+
+---
+
+## number.js
+
+Locale-aware number sanitizing, parsing, and formatting with cached `Intl.NumberFormat` instances.
+
+### getSeparators(locale)
+
+Extracts group and decimal separators dynamically from `Intl.NumberFormat` for any BCP 47 locale tag (e.g. `'en-US'`, `'mk-MK'`, `'de-DE'`, `'fr-FR'`).
+
+### cleanNumericString(raw, groupSep, decimalSep)
+
+Strips currency symbols, whitespace, and thousands separators, normalizing the decimal separator to `.` for reliable `parseFloat`.
+
+### parseNumber(raw, locale)
+
+Parses localized user input or raw strings into a valid `Number` or `NaN`.
+
+### formatNumber(num, locale, options)
+
+Formats a numeric value using `Intl.NumberFormat` with cached formatters. Supports `maxDecimals` and `userDecimals` constraints.
+
+---
+
+## Target & Event Predicates (`dom.js`)
+
+### shouldIgnoreClick(event)
+
+Returns `true` if the mouse click was triggered with modifier keys (`Ctrl`, `Meta`, `Shift`, `Alt`) or a non-primary mouse button (`button !== 0`).
+
+### isTargetDisabled(element)
+
+Returns `true` if the element or any ancestor is disabled (`.disabled`), marked with `aria-disabled="true"`, or contained inside an `[inert]` element.
+
+### isUsableTarget(element, action)
+
+Returns `true` if the target is connected to the DOM, visible (`isVisible`), enabled (`!isTargetDisabled`), and implements the target method (e.g. `el.click` or `el.focus`).
+
+### isEditableTarget(element)
+
+Returns `true` if the element is an `<input>`, `<textarea>`, `<select>`, or `[contenteditable]` container where global shortcut keys should avoid triggering unless explicitly opted-in.
 
 ---
 
@@ -870,11 +1048,12 @@ Sort coerces with `parseFloat(raw) || 0`. Formatted display text breaks it:
 
 ### The split
 
-- `data-ln-value` — the VALUE. Universal. Read by `ln-core.readValue`.
+- `data-ln-value` — the VALUE. Universal raw attribute. Read by `ln-core.readValue`.
+- `datetime` / `value` — native HTML5 machine values on `<time>` and `<data>` elements, also read directly by `ln-core.readValue`.
 - **Type is inferred, not declared.** `ln-core.detectValueType` scans the current value set once
   per sort operation — no `data-ln-*-sort` type attribute exists anymore. All non-empty values
   finite numbers → numeric compare; otherwise `ln-core.compareValues` + `Intl.Collator` string
-  compare. See `js/ln-sort/README.md`.
+  compare. See `components/ln-sort/README.md`.
 
 ### The reader
 
@@ -894,3 +1073,49 @@ the server's job: Blade/PHP in SSR mode, or the API payload in data-driven mode.
 - **Data-driven** — the raw value lives in the record field (API payload); the
   rendered element may also carry `data-ln-value`. Sorting runs on the record
   field. Never sort formatted text.
+
+---
+
+## attrs.js
+
+Standardized attribute readers, spec generators, live getter mappers, and dev-time type validation.
+
+### `attrStr(el, name, fallback)`
+Reads a string attribute. Returns `fallback` if attribute is null or empty.
+
+### `attrInt(el, name, fallback)`
+Parses integer from attribute (`parseInt(val, 10)`). Returns `fallback` if parsing results in `NaN`.
+
+### `attrFloat(el, name, fallback)`
+Parses floating point number from attribute (`parseFloat(val)`). Returns `fallback` if parsing results in `NaN`.
+
+### `attrBool(el, name, fallback = false)`
+Evaluates boolean attribute presence and values. Returns `fallback` if attribute is absent. If present, returns `false` when value is `'false'` or `'0'`, and `true` otherwise (`""`, `'true'`, `'1'`).
+
+### `attrEnum(values, fallback)`
+Higher-order function returning a cached reader function for a set of permitted string enum values. (Illustrative usage; authoritative contracts are defined in each component's documentation, e.g. [`ln-modal`](../../docs-mcp/components/ln-modal.md)):
+```js
+const readState = attrEnum(['open', 'close'], 'close');
+const state = readState(el, 'data-ln-modal');
+```
+
+### `attrJson(el, name, fallback)`
+Safely parses JSON string attribute. Returns `fallback` if attribute is missing or contains invalid JSON syntax.
+
+### `attrSpec(spec)`
+Generates an attribute definition spec for `defineAttrs`. Automatically infers the appropriate reader function from `entry.type` if `entry.read` is omitted. For full component specifications, see individual component docs and schemas:
+```js
+// Illustrative attribute table combining host enum and typed options:
+const ATTRIBUTES = {
+    'data-ln-modal':        { type: 'enum', values: ['open', 'close'], fallback: 'close', effect: _syncAttribute },
+    'data-ln-scroll-delay': { prop: 'delay', type: 'integer', fallback: 450 }
+};
+const ATTR_SPEC = attrSpec(ATTRIBUTES);
+```
+
+### `defineAttrs(target, el, spec)`
+Installs live getters on `target` mapping property names to dynamic attribute reads on `el`.
+
+### `validateAttrValue(entry, value, attrName, componentTag)`
+Validates attribute string against entry constraints (`enum`, `integer`, `float`, `boolean`, `min`, `max`, etc.) and outputs descriptive `console.warn` in dev mode.
+