on_the_money 0.3.3 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,93 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] — 2026-05-23
+
+### Documentation
+
+- **Clarified the "DOM is the database" mandate.** Reframed to acknowledge that the database claim applies to UI signal state (theme, page, modal-open, form-error) — not to structured data, which lives in JS. The original line implied more than the framework actually does; the examples already show comments stored in a `Map` and posts in an array. Removes an overclaim without losing the soul.
+
+## [0.5.0] — 2026-05-23
+
+### Breaking
+
+- **Persistence is now opt-in.** Default behavior writes attributes only — nothing persists to `localStorage`. Declare `the.boot({ persistKeys: [...] })` to opt specific keys in. Replaces `ephemeralKeys` (the deny-list polarity). Consumers writing theme/locale-flavored apps pass `persistKeys: ["theme", "lang"]`; consumers writing page-render apps pass nothing or just `["lang"]`. The deny-list polarity was wrong for modern apps — the default punished state-as-signal patterns. (#69)
+- **Keys auto-convert to kebab-case** for attribute writes and `[data-text]` lookups. `the("chapterHasNav", x)` writes `data-chapter-has-nav`; `the("chapter_has_nav", x)` also normalizes to kebab. Round-trips via the platform's `dataset.chapterHasNav` accessor. CSS selectors and `[data-text="..."]` slot values must use kebab-case to match what JS writes. Single-word and already-kebab keys are unchanged. Single-word ARIA shortcut keys (`expanded`, etc.) still map correctly. (#70)
+
+### Added
+
+- **`the.match(pattern, path?)`** — Express-style `:name` segment extraction. Returns `{name: value}` (URI-decoded) or `null`. Scope: `:name` only — no optional, no regex constraints, no wildcards. (#71)
+- **`$.clone(parent, selector, { position })`** — pass `afterbegin` / `beforeend` (default) / `beforebegin` / `afterend` to insert at any position via `insertAdjacentElement`. The `mounted` event fires *after* insertion at the final position. (#72)
+
+### Documentation
+
+- **Production CSS purging** — README adds a "Production CSS purging" section with a PurgeCSS safelist pattern. No preset shipped; documenting the pattern keeps the framework agnostic about which purger consumers use. (#67)
+- **Reacting to state changes** — README documents `MutationObserver` against `document.body` as the canonical pattern for state-driven side effects (modal orchestration, focus management). The framework deliberately doesn't broadcast events on every write — the platform's primitive is the right tool. (#68)
+- **`_t()` with empty dictionary** — README documents the template-literal workaround for default-locale apps that want interpolation. No `options.template` API added; template literals are the platform's interpolation primitive. (#63)
+- **Key naming convention** documented under `the(...)` — kebab-case is the canonical surface.
+
+## [0.4.0] — 2026-05-23
+
+### Breaking
+
+- **Removed `the.attr(el, name, val)`.** It was an aesthetic helper that wrapped `el.setAttribute` for non-state attributes. The platform's `setAttribute` is the right primitive for HTML structure attributes; `the()` is for state. Two distinct concerns, two distinct primitives. No call-site uniformity gain was worth the API duplication and the consumer-confusion cost of "which writes go through OTM?".
+- **Reverted ARIA mapping to its closed 5-entry set:** `expanded`, `selected`, `hidden`, `checked`, `disabled`. **Criterion: HTML5 widget/form boolean states only.** No future expansion. The five added in 0.3.4 (`invalid`, `required`, `readonly`, `pressed`, `current`) go through `el.setAttribute("aria-...", val)` like any other HTML attribute. Without a stated criterion the ARIA map would grow forever; with one, the line is clear.
+- **Removed `the.title(str)`.** Title isn't state; making it a state-method was special-casing for symmetry's sake. Replaced by extending the global setter to walk the entire document (not just body) when looking for `[data-text="key"]` slots. Put `<title data-text="title">Default</title>` in `<head>` and `the("title", "X")` updates it — same pattern as every other reactive slot, no special-case API.
+- **Removed `--conformance` flag from `otm-lint`.** Exit code already encodes violation count; the flag duplicated that signal in output without distinct value.
+
+### Added
+
+- **`data-otm-dynamic` opt-out attribute for HTML-101.** `<template id="X" data-otm-dynamic>` is skipped by the orphan-template check. Use when a template is instantiated via dynamic IDs, aliased `$.clone` calls, or other indirection the regex-based detection misses.
+
+### Documentation
+
+- **README**: ARIA inclusion criterion documented (closed set, no future expansion).
+- **README**: lint-rule scope acknowledged honestly — `no-server-dom`, `no-document-query`, and `HTML-101` each have real loopholes; the README now describes them as "discipline aids, not enforcement boundaries."
+- **README**: plain attribute writes (`href`, `value`, `rel`) explicitly use `setAttribute` directly; the framework deliberately doesn't wrap them.
+- **README**: dynamic `<title>` and other `<head>` slot hydration via the body-rooted `the()` is documented as the canonical pattern.
+
+### Why this release
+
+A self-audit of 0.3.4–0.3.6 surfaced six items that violated the leanness mandate: aesthetic helpers, special-case methods, growing-without-criterion API surfaces, and performative lint rules without honest scope documentation. Each is resolved here in favor of clearer, leaner patterns. See #74.
+
+## [0.3.6] — 2026-05-23
+
+### Added
+
+- **`otm-lint` cross-file checks.** Three new rules that no per-format tool can do:
+  - **HTML-101 — orphan templates.** `<template id="X">` declared but never referenced by `$.clone(_, "#X")`. Catches dead-template drift after refactors. (#59.1)
+  - **HTML-102 — missing i18n keys.** `data-i18n="K"` references a key not in any locale dictionary loaded via the file's `<meta name="i18n">`. Previously silent-fallback-to-key was a runtime UX bug; now caught at lint time. (#59.3)
+  - **HTML-103 — placeholder token mismatch.** `data-i18n-{var}` attr has no matching `{var}` token in the dictionary entry. The token is silently dropped at runtime; the lint surfaces it. (#59.4)
+- **`--conformance` flag.** Appends a single machine-grep-able line: `OTM conformance: N violations`. Useful for CI gates and LLM tooling. (#59.5)
+
+### Changed
+
+- **`otm-lint` now walks `.html`, `.js`, and locale `.json` files** (was `.html` only). JS files contribute `$.clone(_, "#id")` references for orphan-template analysis. Locale JSONs load per HTML file's own `<meta name="i18n">` so multi-app scans (e.g. `examples/blog` + `examples/todo` with different locale sets) don't cross-contaminate.
+
+## [0.3.5] — 2026-05-23
+
+### Added
+
+- **`otm/no-server-dom`** — bans imports of `linkedom`, `jsdom`, `cheerio`, `parse5`, `htmlparser2`, `happy-dom`, `node-html-parser`, `parse5-htmlparser2-tree-adapter`, `fast-html-parser`. Catches the "render HTML server-side" instinct at the import line. (#58)
+- **`otm/no-document-query`** — bans `document.querySelector`, `getElementById`, `createElement`, `write`, etc. Forces consumers through `$()` / `$$()` / `$.clone()`. Bridge code (MutationObserver targets, etc.) uses `// eslint-disable-next-line otm/no-document-query`. (#58)
+
+### Changed
+
+- **ESLint config now matches `.ts`/`.tsx`/`.mts`/`.cts` files** in addition to `.js` variants. Consumers using Node 25 native TS execution (or any project with `.ts` files) no longer have OTM rules silently skip server-side code. README note: matching syntax still requires a TS-aware parser like `@typescript-eslint/parser`. (#57)
+- **All ESLint rule messages now include "Common LLM mistake: ..." hints** — turns rule output into a teaching surface. LLMs read rule messages more reliably than README sections, so corrections plant at the point of failure. (#59.6)
+
+## [0.3.4] — 2026-05-23
+
+### Added
+
+- **`the.title(str)`** — sets `document.title` and returns the `<title>` element. Closes the head-hydration gap; `the()` only walks body, so dynamic page titles previously required `document.title = "..."`. (#60)
+- **`the.attr(el, name, val)` / `the.attr(el, { attrs })`** — plain attribute writes for non-`data-*`/non-ARIA attributes (`href`, `value`, `rel`, `for`, etc.). Object form for batch. Lets app code stop calling `el.setAttribute(...)` directly. (#62)
+- **Extended ARIA mapping** in `the()`: adds `invalid`, `required`, `readonly`, `pressed`, `current` → `aria-*`. Common form/widget states no longer require `setAttribute` fallback. (#61)
+
+### Changed
+
+- **README preamble** explicitly signals that the file is the authoring context for AI agents. **`package.json` description** ends with "See README.md for the authoring context." Reduces inference cost for LLMs walking package metadata. (#59.7, modified — no satellite `LLMS.md` file)
+
 ## [0.3.3] — 2026-05-22
 
 ### Added

package/README.md

@@ -1,8 +1,10 @@
 # on_the_money.js
 
+> _This README is the authoring context for AI agents using `on_the_money`. Read top-to-bottom for a complete picture; everything you need to write an OTM app is here. No satellite docs._
+
 Opinionated, attribute-driven, standards-oriented modern framework for the web. <2KB gzip. Native browser APIs only. ESNext.
 
-State lives in DOM attributes. Reactivity comes from `[data-text]` and `[data-i18n]` selectors. Events use one delegated listener per `(parent, type)` pair. Routing uses the History API. Localization uses `Intl`. There is no virtual DOM, no JSX, no transpilation step, no proprietary tooling. The framework is a thin layer of conventions over the platform.
+UI signal state — theme, page, modal-open, form-error, the boolean and enum flags that drive visual transitions — lives in DOM attributes; structured data (lists of records, collections, async results) lives in JS like everywhere else. Reactivity comes from `[data-text]` and `[data-i18n]` selectors and from CSS attribute-selector rules. Events use one delegated listener per `(parent, type)` pair. Routing uses the History API. Localization uses `Intl`. There is no virtual DOM, no JSX, no transpilation step, no proprietary tooling. The framework is a thin layer of conventions over the platform.
 
 ## Install
 
@@ -65,7 +67,7 @@ Then write semantic HTML (`<main>`, `<nav>`, `<article>`, `<form>`, `<button>`,
 import { on, the, _t, route, $, $$ } from "on_the_money";
 ```
 
-Aliases on `the`: `the.t === _t`, `the.route === route`, `the.form(formEl)`, `the.flat(obj, sep?)`, `the.boot(options?)`.
+Aliases on `the`: `the.t === _t`, `the.route === route`, `the.form(formEl)`, `the.flat(obj, sep?)`, `the.match(pattern, path?)`, `the.boot(options?)`. Live accessors: `the.dictionary`, `the.locale`.
 Live accessors on `the`: `the.dictionary`, `the.locale`.
 
 ## API
@@ -103,13 +105,17 @@ Polymorphic on a single disambiguator: `args[0] instanceof Element`. Three call
 | Call | Behavior | Returns |
 | --- | --- | --- |
 | `the(key)` | Read body `data-KEY` (or aria-mapped equivalent). | `string \| null` |
-| `the(key, val)` | Write body attribute + `localStorage["otm:KEY"]` + descendant `[data-text="key"]`. | `document.body` |
+| `the(key, val)` | Write body attribute + descendant `[data-text="key"]`. Persists to `localStorage` only if `key` is in `persistKeys`. | `document.body` |
 | `the({ k: v, ... })` | Batch global write. | `document.body` |
 | `the(el, key)` | Read scoped attribute on `el`. | `string \| null` |
 | `the(el, key, val)` | Write scoped attribute on `el` + descendant `[data-text="key"]`. | `el` |
 | `the(el, { k: v, ... })` | Batch scoped write. | `el` |
 
-- **ARIA mapping** (key → attribute): `expanded`, `selected`, `hidden`, `checked`, `disabled` → `aria-*`. All other keys → `data-*`.
+- **Key naming.** Keys auto-convert to kebab-case for attribute writes and `[data-text]` lookups. `the("chapterHasNav", x)` writes `data-chapter-has-nav`. snake_case (`chapter_has_nav`) normalizes to kebab too. Single-word keys (`theme`, `user`) pass through unchanged. Round-trips via the platform's `dataset` API: `el.dataset.chapterHasNav` reads the same attribute. CSS selectors and `[data-text="..."]` slot values must use kebab-case to match what JS writes.
+- **Persistence is opt-in.** Default behavior writes attributes only — nothing persists to `localStorage`. Declare `the.boot({ persistKeys: ["theme", "lang"] })` to opt specific keys in. The boot replay loads only those keys back. Common persistKeys for an i18n + theme app: `["theme", "lang"]`.
+- **ARIA mapping** (closed set, key → attribute): `expanded`, `selected`, `hidden`, `checked`, `disabled` → `aria-*`. **Criterion: HTML5 widget/form boolean states only.** No future expansion. Other ARIA attributes (`aria-invalid`, `aria-controls`, `aria-describedby`, etc.) go through `el.setAttribute("aria-...", val)` like any other HTML attribute. Non-ARIA keys → `data-*` (after kebab conversion).
+- **Dynamic `<title>` and other `<head>` slots:** global `the(key, val)` writes walk the entire document for `[data-text="key"]` matches, not just body. Put `<title data-text="title">Default</title>` in `<head>` and `the("title", "X")` updates it.
+- **Plain HTML attributes (href, value, rel, etc.)** use `el.setAttribute(name, val)` directly. The framework deliberately doesn't wrap these — `the()` is for state; `setAttribute()` is for structure. Two distinct concerns, two distinct primitives.
 - **Booleans coerce** to `"true"`/`"false"` inside the setter. `the(el, "checked", true)` writes `"true"`.
 - **Values MUST be flat primitives.** Pass nested objects through `the.flat(...)` first.
 - **`the(key, undefined)` throws.** Two args means set; missing val is a contract violation.
@@ -144,7 +150,7 @@ Throws on non-object input.
 Importing the module does **nothing**. Call `the.boot()` at the consumer's entry point.
 
 ```javascript
-await the.boot({ signal, locales, dictionary, namespace, defaultLocale });
+await the.boot({ signal, locales, dictionary, namespace, defaultLocale, persistKeys });
 ```
 
 | Option | Type | Behavior |
@@ -154,7 +160,7 @@ await the.boot({ signal, locales, dictionary, namespace, defaultLocale });
 | `dictionary` | `object` | Inline dictionary; skips the fetch entirely. |
 | `namespace` | `string` | Sets `localStorage` prefix to `${namespace}:` (default `otm:`). Must be set before any state ops. |
 | `defaultLocale` | `string` | Locale your static HTML is already written in. When the resolved locale base matches this, the dictionary fetch and `_t()` hydration pass are skipped entirely — no network, no FOUC. Auto-detected from `<html lang>` if omitted. |
-| `ephemeralKeys` | `string[]` | Global state keys that **should not** persist to `localStorage`. Writes to these keys still update the body attribute and any `[data-text]` mirrors, but skip the storage write; the boot replay also skips them. Use for transient signals like `modal`, `loading`, `toast`. Scoped state (`the(el, ...)`) never persists regardless. |
+| `persistKeys` | `string[]` | Global state keys that **should** persist to `localStorage`. Default: empty — nothing persists. Writes still update the body attribute and any `[data-text]` mirrors regardless. Boot replay rehydrates only these keys. Use for stable preferences: `["theme", "lang"]`. Scoped state (`the(el, ...)`) never persists regardless. |
 
 Boot sequence:
 1. Resolve locale: `?lang=` query → `localStorage["${prefix}lang"]` → `navigator.language`. Writes `the.locale`.
@@ -207,6 +213,23 @@ route((pathname, search, hash) => {
 
 Fires the callback on initial mount, on `popstate`, on `hashchange`, and on intercepted internal `<a>` clicks. Skips interception for `data-external`, `target="_blank"`, and cross-origin hrefs. Hash-only same-page links are left to the browser; `hashchange` still triggers the callback.
 
+### `the.match(pattern, path?)` — pattern matching with named segments
+
+Express-style colon syntax. Extracts named segments from `path` (defaults to `window.location.pathname`). Decodes URI-encoded segments. Returns `{name: value}` on match, `null` on no match.
+
+```javascript
+the.match("/@:user/:work/:chapter", "/@alice/great-work/chapter-1");
+// → { user: "alice", work: "great-work", chapter: "chapter-1" }
+
+the.match("/about", "/about");
+// → {} (matched, no params)
+
+the.match("/:slug", "/about/extra");
+// → null (segment count doesn't match)
+```
+
+Scope: `:name` segments only. No optional segments, regex constraints, wildcards, or nested patterns. If your routing needs those, bring `path-to-regexp` or similar — `the.match` is the 80%-case helper, not a router framework.
+
 ### `$(context, selector)` / `$$(context, selector)` — context-aware DOM query
 
 ```javascript
@@ -216,13 +239,26 @@ $(".child");            // shorthand: context = document
 $$(".child");
 ```
 
-### `$.clone(parent, selector)` — template instantiation
+### `$.clone(parent, selector, options?)` — template instantiation
 
 ```javascript
 const el = $.clone("#list", "#tmp");
+const head = $.clone("#list", "#tmp", { position: "afterbegin" });   // prepend
+const sib  = $.clone(anchorEl, "#tmp", { position: "beforebegin" }); // insert before anchor
 ```
 
-Clones the first element of `<template selector>`, runs `_t(el)` for i18n hydration, appends to `parent`, dispatches a bubbling `mounted` CustomEvent (`detail: { parent }`), and returns the mounted element. Throws if `parent` or template is missing.
+Clones the first element of `<template selector>`, runs `_t(el)` for i18n hydration, inserts at `position` (default `beforeend` — append inside `parent`), dispatches a bubbling `mounted` CustomEvent (`detail: { parent }`) **after** insertion so the element is at its final position when the event fires. Returns the mounted element. Throws if `parent`/template is missing.
+
+`position` values mirror [`insertAdjacentElement`](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentElement):
+
+| Position | Where |
+| --- | --- |
+| `beforeend` (default) | Inside `parent`, after its last child. |
+| `afterbegin` | Inside `parent`, before its first child. |
+| `beforebegin` | As `parent`'s previous sibling. |
+| `afterend` | As `parent`'s next sibling. |
+
+For `beforebegin` and `afterend`, the first argument is a sibling reference, not a true parent.
 
 ## Patterns
 
@@ -298,6 +334,52 @@ on.emit(document.body, "modal-closed");
 off(); // detach when modal is destroyed
 ```
 
+### Routing with `the.match`
+
+```javascript
+route(() => {
+  const post = the.match("/posts/:slug");
+  if (post) return renderPost(post.slug);
+
+  const profile = the.match("/@:user");
+  if (profile) return renderProfile(profile.user);
+
+  if (location.pathname === "/") return renderHome();
+});
+```
+
+### Reacting to state changes (MutationObserver)
+
+The framework deliberately doesn't broadcast events on every `the()` write. To react to attribute changes, use the platform's primitive directly. This is the canonical pattern for state-driven UI hooks the framework can't express declaratively (modal orchestration, focus management, etc.):
+
+```javascript
+new MutationObserver(() => {
+  const wantModal = the("modal");
+  for (const dialog of $$("dialog[open]")) {
+    if (dialog.id !== `${wantModal}-modal`) dialog.close();
+  }
+  if (wantModal) $(`#${wantModal}-modal`)?.showModal();
+}).observe(document.body, { attributes: true, attributeFilter: ["data-modal"] });
+```
+
+`document.body` is the allowed identifier under `otm/no-document-query`. Filter by `attributeFilter` to scope the observer narrowly.
+
+### Working around `_t()` with an empty dictionary
+
+When `the.boot({ defaultLocale })` skips the dictionary fetch, programmatic `_t(key, options)` calls return the key (no template to interpolate against). For default-locale interpolation, use template literals or a small wrapper:
+
+```javascript
+// Template literal — the platform's interpolation primitive
+const greeting = `Hello, ${name}!`;
+
+// Or wrap once for callers that need a uniform API across locales
+function greet(name) {
+  return the.dictionary.greeting
+    ? _t("greeting", { name })
+    : `Hello, ${name}!`;
+}
+```
+
 ### Server-side rendering (no extra API)
 
 There's no SSR shim. Emit `data-*` attributes from the server:
@@ -347,9 +429,13 @@ export default [
 | `otm/flat-state` | bundled in `on_the_money` | Ban nested objects/arrays in `the()` calls. |
 | `otm/prefer-submit` | bundled in `on_the_money` | Warn on `on(btn, "click", ...)` for form data. |
 | `otm/no-style-mutation` | bundled in `on_the_money` | Ban `el.style.* = ...`. |
+| `otm/no-server-dom` | bundled in `on_the_money` | Ban imports of `linkedom`, `jsdom`, `cheerio`, `parse5`, etc. — emit JSON and let the OTM client hydrate. |
+| `otm/no-document-query` | bundled in `on_the_money` | Ban `document.querySelector`/`getElementById`/`createElement`/etc.; use `$`/`$$`/`$.clone`. Use `// eslint-disable-next-line otm/no-document-query` for legitimate bridge code (MutationObserver targets, etc.). |
 | `no-unsanitized/no-inner-html` | `eslint-plugin-no-unsanitized` | Ban `innerHTML`/`outerHTML`. |
 | `no-unsanitized/method` | `eslint-plugin-no-unsanitized` | Ban `document.write`, `insertAdjacentHTML`. |
 
+The recommended config matches `**/*.{js,mjs,cjs,ts,mts,cts,tsx,jsx}` — your TypeScript files are covered if you bring a TS-aware parser like `@typescript-eslint/parser`. OTM's rules read AST nodes that don't depend on type info, but the parser still has to understand the syntax.
+
 ### 2. CSS — Stylelint + bundled plugin
 
 Same pattern: the Stylelint plugin and config ship inside `on_the_money`. No separate `stylelint-plugin-otm` package.
@@ -385,8 +471,21 @@ npx otm-lint --check ./src
 | **HTML-017** | `<div data-action="...">` without `role`/`tabindex` | Use a `<button>` or other interactive element. |
 | **HTML-023** | `data-i18n="..."` without `<meta name="i18n">` | Declare the i18n endpoint. |
 | **HTML-024** | `data-available="..."` doesn't match locales folder | Keep the manifest aligned with the actual locale files. |
+| **HTML-101** | `<template id="X">` is never referenced by `$.clone(_, "#X")` | Either delete the orphan template or add the missing clone call. Catches dead-template drift after refactors. Detection is regex-based and matches the literal `$.clone(_, "#id")` shape — dynamic IDs (`` `#${id}` ``), aliased calls, or templates instantiated through indirection are missed. Use `data-otm-dynamic` on the `<template>` to opt out. |
+| **HTML-102** | `data-i18n="K"` references a key not in any locale dictionary | Add the key to your locale files, or fix the typo. Catches the silent-fallback-to-key UX bug at lint time. |
+| **HTML-103** | `data-i18n-{var}` attr has no matching `{var}` placeholder in the dictionary template | The token is silently dropped at runtime. Either remove the unused attr or add `{var}` to the template. |
+
+`otm-lint` walks `.html`, `.js`, and locale `.json` files. HTML files get the per-file rules above; `.js` files contribute `$.clone` references for HTML-101; locale dicts get loaded per HTML file's `<meta name="i18n">` for HTML-102/103. Default excludes: `node_modules`, `dist`, `.git`, dotdirs. Exit code is the violation count.
+
+### Lint-rule scope
 
-`otm-lint` default-excludes `node_modules`, `dist`, `.git`, and dotdirs. It only scans `.html` — everything else delegates to the layers above.
+These rules are **discipline aids, not enforcement boundaries.** Each catches the obvious shape; determined consumers can route around them:
+
+- `otm/no-server-dom` matches static `import` only. Dynamic `await import("linkedom")` and CJS `require()` are not caught.
+- `otm/no-document-query` catches `document.querySelector(...)` and friends at AST level. Chained calls (`document.body.querySelector(...)`, `document.getElementById("x").querySelector(...)`) are not caught — the call site has moved off `document`.
+- `HTML-101` regex-matches `$.clone(parent, "#id")` in `.js` files. Dynamic IDs and aliased calls are missed; use `data-otm-dynamic` to opt out of the check for templates instantiated indirectly.
+
+The rules' job is to catch the *first* mistake and surface a teaching message ("Common LLM mistake: ..."). Strong patterns + good editor feedback do the rest.
 
 ### Recommended companions (not shipped)
 
@@ -397,6 +496,30 @@ npx otm-lint --check ./src
 | Runtime a11y | `axe-core` via Playwright/Cypress against the rendered page |
 | Supply-chain | `npm audit`, `osv-scanner` |
 
+## Production CSS purging
+
+OTM's CSS depends on attribute selectors written at runtime (`body[data-page="home"]`, `[data-state="active"]`, etc.). Default tree-shakers like PurgeCSS scan HTML for tokens and can't see attribute values that don't exist at build time — they'll strip your state-driven rules. Configure the safelist to preserve them:
+
+```javascript
+// postcss.config.js
+import purgecss from "@fullhuman/postcss-purgecss";
+
+export default {
+  plugins: [
+    purgecss({
+      content: ["src/**/*.html", "src/**/*.js"],
+      defaultExtractor: (s) => s.match(/[A-Za-z0-9_-]+/g) || [],
+      safelist: {
+        standard: [/^aria-/, "hidden"],
+        deep: [/^\[data-/, /^aria-/, /role-/],
+      },
+    }),
+  ],
+};
+```
+
+The `defaultExtractor` tweak ensures attribute names tokenize correctly (the default extractor treats `id="foo"` as one opaque token). The `deep` safelist preserves any selector containing `[data-*]` or `aria-*` from being purged. Without these, every `[data-page="home"] main > section` style gets stripped in production.
+
 ## Suggested project layout
 
 ```

package/dist/on_the_money.min.js

@@ -1 +1 @@
-var w=class{static on(t,e,o,n){let r=typeof t=="string"?document.querySelector(t):t||document.body,a=i=>{let s=i.target.closest(o);s&&r.contains(s)&&n.call(s,i,s)};return r.addEventListener(e,a),()=>r.removeEventListener(e,a)}static emit(t,e,o){let n=typeof t=="string"?document.querySelector(t):t,r=new CustomEvent(e,{bubbles:!0,cancelable:!0,detail:o});n.dispatchEvent(r)}};var l=class c{static dictionary={};static locale=typeof navigator<"u"?navigator.language:"en-US";static prefix="otm:";static ephemeralKeys=new Set;static the(...t){if(t.length===0)throw new TypeError("the(): missing args");return t[0]instanceof Element?c.#e(t[0],t.slice(1)):c.#e(document.body,t)}static#e(t,e){let[o,n]=e,r=t===document.body;if(e.length===1&&typeof o=="string")return c.#o(t,o);if(e.length===2&&typeof o=="string"){if(typeof n>"u")throw new TypeError(`the(${JSON.stringify(o)}, undefined): val is required for set`);return c.#t(t,o,n),r&&!c.ephemeralKeys.has(o)&&localStorage.setItem(`${c.prefix}${o}`,n),t}if(e.length===1&&o?.constructor===Object){for(let[a,i]of Object.entries(o))c.#t(t,a,i),r&&!c.ephemeralKeys.has(a)&&localStorage.setItem(`${c.prefix}${a}`,i);return t}throw new TypeError(`the(): unrecognized call shape (${e.map(a=>typeof a).join(", ")})`)}static flat(t,e="_"){if(t===null||typeof t!="object")throw new TypeError("the.flat: input must be an object");let o={},n=(r,a)=>{if(r===null||typeof r!="object"){o[a]=r;return}for(let[i,s]of Object.entries(r))n(s,a?`${a}${e}${i}`:i)};return n(t,""),o}static form(t){let e={},o=t.querySelectorAll("input, select, textarea");for(let n of o){let r=n.name;if(!r||n.disabled)continue;let a=(n.type||"text").toLowerCase();if(a==="submit"||a==="button"||a==="reset"||(a==="checkbox"||a==="radio")&&!(n.checked??n.hasAttribute("checked")))continue;let i=n.value??n.getAttribute("value")??"";c.#n(e,r,i)}return e}static#n(t,e,o){let n=e.split(/[\[\]]/).filter(Boolean),r=t;for(let a=0;a<n.length;a++){let i=n[a];a===n.length-1?r[i]!==void 0?(Array.isArray(r[i])||(r[i]=[r[i]]),r[i].push(o)):r[i]=o:(r[i]=r[i]||{},r=r[i])}}static _t(t,e={}){if(typeof Node<"u"?t instanceof Node:t?.nodeType){let a=t.querySelectorAll?[t,...t.querySelectorAll("[data-i18n]")]:[t];for(let i of a)if(i.hasAttribute?.("data-i18n")){let s=i.getAttribute("data-i18n"),p={};for(let y of i.attributes)if(y.name.startsWith("data-i18n-")&&y.name!=="data-i18n-type"){let x=y.name.replace("data-i18n-","");p[x]=y.value}let h=i.getAttribute("data-i18n-type");i.textContent=c._t(s,{...p,type:h})}return t}if(!t)return c._t(document.body),"";let n=c.dictionary[t];if(!n){if(e.val!==void 0&&(e.type==="currency"||e.type==="date")){let a=e.type==="currency"?new Intl.NumberFormat(c.locale,{style:"currency",currency:"USD"}):new Intl.DateTimeFormat(c.locale);return e.type==="date"?a.format(new Date(e.val)):a.format(Number(e.val))}return t}if(typeof n=="object"){let a=e.qty!==void 0?Number(e.qty):0,i=new Intl.PluralRules(c.locale).select(a);n=n[i]||n.other||t}if(typeof n!="string")return t;let r=n;for(let[a,i]of Object.entries(e)){let s=i;if(a==="val"&&e.type){let p=Number(i),h=e.type==="currency"?new Intl.NumberFormat(c.locale,{style:"currency",currency:"USD"}):e.type==="date"?new Intl.DateTimeFormat(c.locale):new Intl.NumberFormat(c.locale);s=e.type==="date"?h.format(new Date(i)):h.format(p)}r=r.replace(`{${a}}`,s)}return r}static route(t){if(typeof window>"u")return;let e=()=>t(window.location.pathname,window.location.search,window.location.hash);window.addEventListener("popstate",e),window.addEventListener("hashchange",e),document.addEventListener("click",o=>{let n=o.target.closest("a");if(!n||!n.getAttribute("href")||n.hasAttribute("data-external")||n.target==="_blank")return;let r=new URL(n.getAttribute("href"),window.location.href);r.origin===window.location.origin&&(r.pathname===window.location.pathname&&r.search===window.location.search&&r.hash||(o.preventDefault(),window.history.pushState({},"",r.href),e()))}),e()}static#o(t,e){let n={expanded:"aria-expanded",selected:"aria-selected",hidden:"aria-hidden",checked:"aria-checked",disabled:"aria-disabled"}[e]||`data-${e}`;return t.getAttribute(n)}static#t(t,e,o){let r={expanded:"aria-expanded",selected:"aria-selected",hidden:"aria-hidden",checked:"aria-checked",disabled:"aria-disabled"}[e]||`data-${e}`,a=typeof o=="boolean"?o?"true":"false":o;if(t.setAttribute(r,a),t.querySelectorAll){let i=t.querySelectorAll(`[data-text="${e}"]`);for(let s of i)s.textContent=a}t.getAttribute?.("data-text")===e&&(t.textContent=a)}static async boot({signal:t,locales:e,dictionary:o,namespace:n,defaultLocale:r,ephemeralKeys:a}={}){n&&(c.prefix=`${n}:`),a&&(c.ephemeralKeys=new Set(a));let i=typeof window<"u"&&window.location?window.location.search:"",s=new URLSearchParams(i),p=(typeof navigator<"u"?navigator.language:null)||document.documentElement.lang||"en";c.locale=s.get("lang")||localStorage.getItem(`${c.prefix}lang`)||p;let h=r||document.documentElement.lang,y=c.locale.toLowerCase().split("-")[0],x=h?.toLowerCase().split("-")[0],A=!!x&&y===x;if(!A)if(o)c.dictionary=o;else{let u=document.querySelector('meta[name="i18n"]'),b=e||u?.getAttribute("content");if(b){let g=u?.getAttribute("data-fallback")||"en",$=(u?.getAttribute("data-available")||"").split(",").map(f=>f.trim().toLowerCase()),v=c.locale.toLowerCase(),E=v.split("-")[0],S=g;$.includes(v)?S=v:$.includes(E)&&(S=E);try{let f=await fetch(`${b}/${S}.json`,{signal:t});f.ok&&(c.dictionary=await f.json())}catch(f){if(t?.aborted)throw f;console.warn("otm: i18n fetch failed",f)}}}for(let u=0;u<localStorage.length;u++){let b=localStorage.key(u);if(b.startsWith(c.prefix)){let g=b.slice(c.prefix.length);if(g!=="lang"&&!c.ephemeralKeys.has(g)){let $=localStorage.getItem(b);c.#t(document.body,g,$)}}}A||c._t()}};var m=class{static $(t,e){let o=t,n=e;return typeof o=="string"&&(n=o,o=document),o.querySelector(n)}static $$(t,e){let o=t,n=e;return typeof o=="string"&&(n=o,o=document),Array.from(o.querySelectorAll(n))}static clone(t,e){let o=typeof t=="string"?document.querySelector(t):t,n=document.querySelector(e);if(!o)throw new Error(`Parent not found: ${t}`);if(!n)throw new Error(`Template not found: ${e}`);let r=n.content.cloneNode(!0).firstElementChild;l._t(r),o.appendChild(r);let a=new CustomEvent("mounted",{bubbles:!0,detail:{parent:o}});return r.dispatchEvent(a),r}};var q=w.on;q.emit=w.emit;var d=l.the,L=l._t,j=l.route;d.t=L;d.route=j;d.form=l.form;d.flat=l.flat;d.boot=l.boot;Object.defineProperty(d,"dictionary",{get:()=>l.dictionary,set:c=>{l.dictionary=c}});Object.defineProperty(d,"locale",{get:()=>l.locale,set:c=>{l.locale=c}});var N=m.$;N.clone=m.clone;var C=m.$$,P={on:q,the:d,$:N,$$:C,_t:L};export{N as $,C as $$,L as _t,P as default,q as on,j as route,d as the};
+var b=class{static on(t,e,a,n){let r=typeof t=="string"?document.querySelector(t):t||document.body,o=i=>{let s=i.target.closest(a);s&&r.contains(s)&&n.call(s,i,s)};return r.addEventListener(e,o),()=>r.removeEventListener(e,o)}static emit(t,e,a){let n=typeof t=="string"?document.querySelector(t):t,r=new CustomEvent(e,{bubbles:!0,cancelable:!0,detail:a});n.dispatchEvent(r)}};var l=class c{static dictionary={};static locale=typeof navigator<"u"?navigator.language:"en-US";static prefix="otm:";static persistKeys=new Set;static#t(t){return t.replace(/_/g,"-").replace(/([a-z0-9])([A-Z])/g,"$1-$2").toLowerCase()}static the(...t){if(t.length===0)throw new TypeError("the(): missing args");return t[0]instanceof Element?c.#n(t[0],t.slice(1)):c.#n(document.body,t)}static#n(t,e){let[a,n]=e,r=t===document.body;if(e.length===1&&typeof a=="string")return c.#a(t,c.#t(a));if(e.length===2&&typeof a=="string"){if(typeof n>"u")throw new TypeError(`the(${JSON.stringify(a)}, undefined): val is required for set`);let o=c.#t(a);return c.#e(t,o,n),r&&c.persistKeys.has(o)&&localStorage.setItem(`${c.prefix}${o}`,n),t}if(e.length===1&&a?.constructor===Object){for(let[o,i]of Object.entries(a)){let s=c.#t(o);c.#e(t,s,i),r&&c.persistKeys.has(s)&&localStorage.setItem(`${c.prefix}${s}`,i)}return t}throw new TypeError(`the(): unrecognized call shape (${e.map(o=>typeof o).join(", ")})`)}static match(t,e){let a=e??(typeof window<"u"&&window.location?window.location.pathname:""),n=[],o=t.replace(/[.*+?^${}()|[\]\\]/g,"\\$&").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g,(d,u)=>(n.push(u),"([^/]+)")),i=a.match(new RegExp(`^${o}$`));if(!i)return null;let s={};return n.forEach((d,u)=>{s[d]=decodeURIComponent(i[u+1])}),s}static flat(t,e="_"){if(t===null||typeof t!="object")throw new TypeError("the.flat: input must be an object");let a={},n=(r,o)=>{if(r===null||typeof r!="object"){a[o]=r;return}for(let[i,s]of Object.entries(r))n(s,o?`${o}${e}${i}`:i)};return n(t,""),a}static form(t){let e={},a=t.querySelectorAll("input, select, textarea");for(let n of a){let r=n.name;if(!r||n.disabled)continue;let o=(n.type||"text").toLowerCase();if(o==="submit"||o==="button"||o==="reset"||(o==="checkbox"||o==="radio")&&!(n.checked??n.hasAttribute("checked")))continue;let i=n.value??n.getAttribute("value")??"";c.#r(e,r,i)}return e}static#r(t,e,a){let n=e.split(/[\[\]]/).filter(Boolean),r=t;for(let o=0;o<n.length;o++){let i=n[o];o===n.length-1?r[i]!==void 0?(Array.isArray(r[i])||(r[i]=[r[i]]),r[i].push(a)):r[i]=a:(r[i]=r[i]||{},r=r[i])}}static _t(t,e={}){if(typeof Node<"u"?t instanceof Node:t?.nodeType){let o=t.querySelectorAll?[t,...t.querySelectorAll("[data-i18n]")]:[t];for(let i of o)if(i.hasAttribute?.("data-i18n")){let s=i.getAttribute("data-i18n"),d={};for(let y of i.attributes)if(y.name.startsWith("data-i18n-")&&y.name!=="data-i18n-type"){let $=y.name.replace("data-i18n-","");d[$]=y.value}let u=i.getAttribute("data-i18n-type");i.textContent=c._t(s,{...d,type:u})}return t}if(!t)return c._t(document.body),"";let n=c.dictionary[t];if(!n){if(e.val!==void 0&&(e.type==="currency"||e.type==="date")){let o=e.type==="currency"?new Intl.NumberFormat(c.locale,{style:"currency",currency:"USD"}):new Intl.DateTimeFormat(c.locale);return e.type==="date"?o.format(new Date(e.val)):o.format(Number(e.val))}return t}if(typeof n=="object"){let o=e.qty!==void 0?Number(e.qty):0,i=new Intl.PluralRules(c.locale).select(o);n=n[i]||n.other||t}if(typeof n!="string")return t;let r=n;for(let[o,i]of Object.entries(e)){let s=i;if(o==="val"&&e.type){let d=Number(i),u=e.type==="currency"?new Intl.NumberFormat(c.locale,{style:"currency",currency:"USD"}):e.type==="date"?new Intl.DateTimeFormat(c.locale):new Intl.NumberFormat(c.locale);s=e.type==="date"?u.format(new Date(i)):u.format(d)}r=r.replace(`{${o}}`,s)}return r}static route(t){if(typeof window>"u")return;let e=()=>t(window.location.pathname,window.location.search,window.location.hash);window.addEventListener("popstate",e),window.addEventListener("hashchange",e),document.addEventListener("click",a=>{let n=a.target.closest("a");if(!n||!n.getAttribute("href")||n.hasAttribute("data-external")||n.target==="_blank")return;let r=new URL(n.getAttribute("href"),window.location.href);r.origin===window.location.origin&&(r.pathname===window.location.pathname&&r.search===window.location.search&&r.hash||(a.preventDefault(),window.history.pushState({},"",r.href),e()))}),e()}static#o={expanded:"aria-expanded",selected:"aria-selected",hidden:"aria-hidden",checked:"aria-checked",disabled:"aria-disabled"};static#a(t,e){let a=c.#o[e]||`data-${e}`;return t.getAttribute(a)}static#e(t,e,a){let n=c.#o[e]||`data-${e}`,r=typeof a=="boolean"?a?"true":"false":a;t.setAttribute(n,r);let o=t===document.body&&typeof document<"u"?document.documentElement||document:t;if(o.querySelectorAll){let i=o.querySelectorAll(`[data-text="${e}"]`);for(let s of i)s.textContent=r}t.getAttribute?.("data-text")===e&&(t.textContent=r)}static async boot({signal:t,locales:e,dictionary:a,namespace:n,defaultLocale:r,persistKeys:o}={}){n&&(c.prefix=`${n}:`),o&&(c.persistKeys=new Set(o.map(f=>c.#t(f))));let i=typeof window<"u"&&window.location?window.location.search:"",s=new URLSearchParams(i),d=(typeof navigator<"u"?navigator.language:null)||document.documentElement.lang||"en";c.locale=s.get("lang")||localStorage.getItem(`${c.prefix}lang`)||d;let u=r||document.documentElement.lang,y=c.locale.toLowerCase().split("-")[0],$=u?.toLowerCase().split("-")[0],S=!!$&&y===$;if(!S)if(a)c.dictionary=a;else{let f=document.querySelector('meta[name="i18n"]'),w=e||f?.getAttribute("content");if(w){let g=f?.getAttribute("data-fallback")||"en",x=(f?.getAttribute("data-available")||"").split(",").map(p=>p.trim().toLowerCase()),v=c.locale.toLowerCase(),E=v.split("-")[0],A=g;x.includes(v)?A=v:x.includes(E)&&(A=E);try{let p=await fetch(`${w}/${A}.json`,{signal:t});p.ok&&(c.dictionary=await p.json())}catch(p){if(t?.aborted)throw p;console.warn("otm: i18n fetch failed",p)}}}for(let f=0;f<localStorage.length;f++){let w=localStorage.key(f);if(w.startsWith(c.prefix)){let g=w.slice(c.prefix.length);if(g!=="lang"&&c.persistKeys.has(g)){let x=localStorage.getItem(w);c.#e(document.body,g,x)}}}S||c._t()}};var h=class{static $(t,e){let a=t,n=e;return typeof a=="string"&&(n=a,a=document),a.querySelector(n)}static $$(t,e){let a=t,n=e;return typeof a=="string"&&(n=a,a=document),Array.from(a.querySelectorAll(n))}static clone(t,e,{position:a="beforeend"}={}){let n=typeof t=="string"?document.querySelector(t):t,r=document.querySelector(e);if(!n)throw new Error(`Parent not found: ${t}`);if(!r)throw new Error(`Template not found: ${e}`);let o=r.content.cloneNode(!0).firstElementChild;l._t(o),n.insertAdjacentElement(a,o);let i=new CustomEvent("mounted",{bubbles:!0,detail:{parent:n}});return o.dispatchEvent(i),o}};var L=b.on;L.emit=b.emit;var m=l.the,q=l._t,N=l.route;m.t=q;m.route=N;m.form=l.form;m.flat=l.flat;m.match=l.match;m.boot=l.boot;Object.defineProperty(m,"dictionary",{get:()=>l.dictionary,set:c=>{l.dictionary=c}});Object.defineProperty(m,"locale",{get:()=>l.locale,set:c=>{l.locale=c}});var j=h.$;j.clone=h.clone;var C=h.$$,F={on:L,the:m,$:j,$$:C,_t:q};export{j as $,C as $$,q as _t,F as default,L as on,N as route,m as the};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "on_the_money",
-	"version": "0.3.3",
-	"description": "Opinionated, attribute-driven, standards-oriented modern framework. <2KB gzip. Native browser APIs only.",
+	"version": "0.5.1",
+	"description": "Opinionated, attribute-driven, standards-oriented modern framework. <2KB gzip. Native browser APIs only. See README.md for the authoring context.",
 	"type": "module",
 	"main": "dist/on_the_money.min.js",
 	"module": "dist/on_the_money.min.js",

package/src/core/Select.js

@@ -28,7 +28,7 @@ export default class Select {
 	 * @param {string} selector - The template ID/selector
 	 * @returns {HTMLElement} The mounted element
 	 */
-	static clone(parent, selector) {
+	static clone(parent, selector, { position = "beforeend" } = {}) {
 		const container =
 			typeof parent === "string" ? document.querySelector(parent) : parent;
 		const template = document.querySelector(selector);
@@ -38,12 +38,10 @@ export default class Select {
 
 		const el = template.content.cloneNode(true).firstElementChild;
 
-		// Surgical hydration of the new fragment before mounting
 		The._t(el);
 
-		container.appendChild(el);
+		container.insertAdjacentElement(position, el);
 
-		// Trigger a 'mounted' custom event for lifecycle hooks
 		const event = new CustomEvent("mounted", {
 			bubbles: true,
 			detail: { parent: container },

package/src/core/The.js

@@ -3,7 +3,18 @@ export default class The {
 	static locale =
 		typeof navigator !== "undefined" ? navigator.language : "en-US";
 	static prefix = "otm:";
-	static ephemeralKeys = new Set();
+	// Default: nothing persists. Opt in per key via the.boot({ persistKeys }).
+	static persistKeys = new Set();
+
+	// Normalize keys to kebab-case for DOM attributes and [data-text] lookups.
+	// chapterHasNav → chapter-has-nav. chapter_has_nav → chapter-has-nav.
+	// expanded / mounted / theme → unchanged.
+	static #kebab(key) {
+		return key
+			.replace(/_/g, "-")
+			.replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+			.toLowerCase();
+	}
 
 	static the(...args) {
 		if (args.length === 0) {
@@ -20,7 +31,7 @@ export default class The {
 		const isGlobal = el === document.body;
 
 		if (args.length === 1 && typeof a === "string") {
-			return The.#get(el, a);
+			return The.#get(el, The.#kebab(a));
 		}
 		if (args.length === 2 && typeof a === "string") {
 			if (typeof b === "undefined") {
@@ -28,15 +39,17 @@ export default class The {
 					`the(${JSON.stringify(a)}, undefined): val is required for set`,
 				);
 			}
-			The.#set(el, a, b);
-			if (isGlobal && !The.ephemeralKeys.has(a))
-				localStorage.setItem(`${The.prefix}${a}`, b);
+			const k = The.#kebab(a);
+			The.#set(el, k, b);
+			if (isGlobal && The.persistKeys.has(k))
+				localStorage.setItem(`${The.prefix}${k}`, b);
 			return el;
 		}
 		if (args.length === 1 && a?.constructor === Object) {
-			for (const [k, v] of Object.entries(a)) {
+			for (const [rawKey, v] of Object.entries(a)) {
+				const k = The.#kebab(rawKey);
 				The.#set(el, k, v);
-				if (isGlobal && !The.ephemeralKeys.has(k))
+				if (isGlobal && The.persistKeys.has(k))
 					localStorage.setItem(`${The.prefix}${k}`, v);
 			}
 			return el;
@@ -47,6 +60,30 @@ export default class The {
 		);
 	}
 
+	static match(pattern, path) {
+		const subject =
+			path ??
+			(typeof window !== "undefined" && window.location
+				? window.location.pathname
+				: "");
+		const paramNames = [];
+		const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const regexSource = escaped.replace(
+			/:([a-zA-Z_][a-zA-Z0-9_]*)/g,
+			(_, name) => {
+				paramNames.push(name);
+				return "([^/]+)";
+			},
+		);
+		const m = subject.match(new RegExp(`^${regexSource}$`));
+		if (!m) return null;
+		const out = {};
+		paramNames.forEach((name, i) => {
+			out[name] = decodeURIComponent(m[i + 1]);
+		});
+		return out;
+	}
+
 	static flat(obj, sep = "_") {
 		if (obj === null || typeof obj !== "object") {
 			throw new TypeError("the.flat: input must be an object");
@@ -233,32 +270,36 @@ export default class The {
 		navigate();
 	}
 
+	// ARIA mapping: HTML5 widget/form boolean states only. Closed set; no future
+	// expansion. Other ARIA attributes (aria-invalid, aria-controls, etc.) go
+	// through el.setAttribute("aria-...", val) like any HTML attribute.
+	static #ariaMap = {
+		expanded: "aria-expanded",
+		selected: "aria-selected",
+		hidden: "aria-hidden",
+		checked: "aria-checked",
+		disabled: "aria-disabled",
+	};
+
 	static #get(el, key) {
-		const ariaMap = {
-			expanded: "aria-expanded",
-			selected: "aria-selected",
-			hidden: "aria-hidden",
-			checked: "aria-checked",
-			disabled: "aria-disabled",
-		};
-		const attr = ariaMap[key] || `data-${key}`;
+		const attr = The.#ariaMap[key] || `data-${key}`;
 		return el.getAttribute(attr);
 	}
 
 	static #set(el, key, val) {
-		const ariaMap = {
-			expanded: "aria-expanded",
-			selected: "aria-selected",
-			hidden: "aria-hidden",
-			checked: "aria-checked",
-			disabled: "aria-disabled",
-		};
-		const attr = ariaMap[key] || `data-${key}`;
+		const attr = The.#ariaMap[key] || `data-${key}`;
 		const out = typeof val === "boolean" ? (val ? "true" : "false") : val;
 		el.setAttribute(attr, out);
 
-		if (el.querySelectorAll) {
-			const items = el.querySelectorAll(`[data-text="${key}"]`);
+		// Global writes (body) walk the whole document so [data-text="key"]
+		// slots in <head> (e.g. <title data-text="title">) hydrate too.
+		// Scoped writes stay within el.
+		const root =
+			el === document.body && typeof document !== "undefined"
+				? document.documentElement || document
+				: el;
+		if (root.querySelectorAll) {
+			const items = root.querySelectorAll(`[data-text="${key}"]`);
 			for (const item of items) item.textContent = out;
 		}
 		if (el.getAttribute?.("data-text") === key) el.textContent = out;
@@ -270,10 +311,11 @@ export default class The {
 		dictionary,
 		namespace,
 		defaultLocale,
-		ephemeralKeys,
+		persistKeys,
 	} = {}) {
 		if (namespace) The.prefix = `${namespace}:`;
-		if (ephemeralKeys) The.ephemeralKeys = new Set(ephemeralKeys);
+		if (persistKeys)
+			The.persistKeys = new Set(persistKeys.map((k) => The.#kebab(k)));
 		const search =
 			typeof window !== "undefined" && window.location
 				? window.location.search
@@ -328,7 +370,7 @@ export default class The {
 			const fullKey = localStorage.key(i);
 			if (fullKey.startsWith(The.prefix)) {
 				const key = fullKey.slice(The.prefix.length);
-				if (key !== "lang" && !The.ephemeralKeys.has(key)) {
+				if (key !== "lang" && The.persistKeys.has(key)) {
 					const val = localStorage.getItem(fullKey);
 					The.#set(document.body, key, val);
 				}

package/src/core/index.js

@@ -12,6 +12,7 @@ the.t = _t;
 the.route = route;
 the.form = The.form;
 the.flat = The.flat;
+the.match = The.match;
 the.boot = The.boot;
 
 Object.defineProperty(the, "dictionary", {

package/src/eslint/config.js

@@ -2,6 +2,7 @@ import plugin from "./plugin.js";
 
 const recommended = [
 	{
+		files: ["**/*.{js,mjs,cjs,ts,mts,cts,tsx,jsx}"],
 		plugins: { otm: plugin },
 		rules: {
 			"otm/prefer-on": "error",
@@ -9,6 +10,8 @@ const recommended = [
 			"otm/flat-state": "error",
 			"otm/prefer-submit": "warn",
 			"otm/no-style-mutation": "error",
+			"otm/no-server-dom": "error",
+			"otm/no-document-query": "error",
 		},
 	},
 ];

package/src/eslint/plugin.js

@@ -1,6 +1,6 @@
 const meta = {
 	name: "eslint-plugin-otm",
-	version: "0.3.0",
+	version: "0.3.4",
 };
 
 const preferOn = {
@@ -12,7 +12,7 @@ const preferOn = {
 		},
 		messages: {
 			useOn:
-				"Direct addEventListener is forbidden. Use on() for event delegation.",
+				"Direct addEventListener is forbidden. Use on() for event delegation. Common LLM mistake: copying jQuery / React tutorial patterns — on() is the single delegated-listener idiom.",
 		},
 		schema: [],
 	},
@@ -36,7 +36,7 @@ const preferTheSet = {
 		},
 		messages: {
 			useThe:
-				"Direct text manipulation is forbidden. Use the() or [data-text] binding instead.",
+				"Direct text manipulation is forbidden. Use the() or [data-text] binding instead. Common LLM mistake: doing this server-side via linkedom/jsdom — same fix, emit JSON and let the OTM client render.",
 		},
 		schema: [],
 	},
@@ -64,7 +64,7 @@ const flatState = {
 		},
 		messages: {
 			notFlat:
-				"State must be flat. Nested objects or arrays are forbidden in the(). Use the.flat() to compose.",
+				"State must be flat. Nested objects or arrays are forbidden in the(). Common LLM mistake: passing a nested object — use the.flat(obj) to compose first.",
 		},
 		schema: [],
 	},
@@ -114,7 +114,7 @@ const preferSubmit = {
 		},
 		messages: {
 			useSubmit:
-				"Prefer using <form> submit events over direct button click listeners.",
+				"Prefer using <form> submit events over direct button click listeners. Common LLM mistake: per-button click handlers — one form submit handler captures every input route.",
 		},
 		schema: [],
 	},
@@ -147,7 +147,7 @@ const noStyleMutation = {
 		},
 		messages: {
 			noStyle:
-				"Direct style manipulation is forbidden. Use the() with attribute selectors instead.",
+				"Direct style manipulation is forbidden. Use the() with attribute selectors instead. Common LLM mistake: copying React/Vue inline-style patterns — CSS rules keyed off [data-state=...] handle state-driven styling cleanly.",
 		},
 		schema: [],
 	},
@@ -189,12 +189,100 @@ const noStyleMutation = {
 	},
 };
 
+const noServerDom = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Disallow imports of server-side DOM libraries.",
+		},
+		messages: {
+			noServerDom:
+				"Server-side DOM library '{{name}}' is forbidden. Common LLM mistake: rendering HTML server-side instead of emitting JSON. The OTM client hydrates static templates via $.clone() + the() — keep server output to data.",
+		},
+		schema: [],
+	},
+	create(context) {
+		const banned = new Set([
+			"linkedom",
+			"jsdom",
+			"cheerio",
+			"parse5",
+			"htmlparser2",
+			"happy-dom",
+			"node-html-parser",
+			"parse5-htmlparser2-tree-adapter",
+			"fast-html-parser",
+		]);
+		return {
+			ImportDeclaration(node) {
+				const src = node.source?.value;
+				if (typeof src === "string" && banned.has(src)) {
+					context.report({
+						node,
+						messageId: "noServerDom",
+						data: { name: src },
+					});
+				}
+			},
+		};
+	},
+};
+
+const noDocumentQuery = {
+	meta: {
+		type: "problem",
+		docs: {
+			description:
+				"Disallow direct document.* DOM queries; use $/$$/$.clone instead.",
+		},
+		messages: {
+			noDocumentQuery:
+				"Direct document.{{method}} is forbidden. Common LLM mistake: querying through document instead of OTM's selectors. Use $(selector) for one, $$(selector) for many, or $.clone(parent, '#tmpl') for templates.",
+		},
+		schema: [],
+	},
+	create(context) {
+		const banned = new Set([
+			"querySelector",
+			"querySelectorAll",
+			"getElementById",
+			"getElementsByClassName",
+			"getElementsByTagName",
+			"getElementsByName",
+			"createElement",
+			"createTextNode",
+			"createDocumentFragment",
+			"write",
+			"writeln",
+		]);
+		return {
+			CallExpression(node) {
+				const callee = node.callee;
+				if (
+					callee?.type === "MemberExpression" &&
+					callee.object?.type === "Identifier" &&
+					callee.object.name === "document" &&
+					banned.has(callee.property?.name)
+				) {
+					context.report({
+						node,
+						messageId: "noDocumentQuery",
+						data: { method: callee.property.name },
+					});
+				}
+			},
+		};
+	},
+};
+
 const rules = {
 	"prefer-on": preferOn,
 	"prefer-the-set": preferTheSet,
 	"flat-state": flatState,
 	"prefer-submit": preferSubmit,
 	"no-style-mutation": noStyleMutation,
+	"no-server-dom": noServerDom,
+	"no-document-query": noDocumentQuery,
 };
 
 const plugin = {
@@ -211,6 +299,8 @@ plugin.configs = {
 			"otm/flat-state": "error",
 			"otm/prefer-submit": "warn",
 			"otm/no-style-mutation": "error",
+			"otm/no-server-dom": "error",
+			"otm/no-document-query": "error",
 		},
 	},
 };

package/src/linter/Linter.js

@@ -119,6 +119,123 @@ export default class Linter {
 		}
 	}
 
+	static crossCheck({ htmlSources, jsSources }) {
+		const violations = [];
+
+		// HTML-101: orphan templates — <template id="X"> never referenced by $.clone(_, "#X")
+		const templates = new Map();
+		for (const { file, source } of htmlSources) {
+			const document = parse5.parse(source, { sourceCodeLocationInfo: true });
+			Linter.#traverse(document, (node) => {
+				if (node.nodeName === "template") {
+					const idAttr = node.attrs?.find((a) => a.name === "id");
+					const dynamic = node.attrs?.some(
+						(a) => a.name === "data-otm-dynamic",
+					);
+					if (dynamic) return;
+					if (idAttr?.value) {
+						const loc = node.sourceCodeLocation || {
+							startLine: 1,
+							startCol: 1,
+						};
+						templates.set(idAttr.value, {
+							file,
+							line: loc.startLine,
+							column: loc.startCol,
+						});
+					}
+				}
+			});
+		}
+
+		const cloneRefs = new Set();
+		for (const { source } of jsSources) {
+			const matches = source.matchAll(
+				/\$\.clone\s*\([^,)]+,\s*['"]#([^'"]+)['"]/g,
+			);
+			for (const m of matches) cloneRefs.add(m[1]);
+		}
+
+		for (const [id, info] of templates) {
+			if (!cloneRefs.has(id)) {
+				Linter.#addViolation(
+					violations,
+					info.file,
+					{ line: info.line, column: info.column },
+					"HTML-101",
+					`Orphan template: <template id="${id}"> is never referenced by $.clone(). Remove the template or add a clone call.`,
+				);
+			}
+		}
+
+		// HTML-102: data-i18n keys missing from the html file's own locale dictionaries
+		// HTML-103: data-i18n-{var} attrs reference template tokens that don't exist in the dictionary entry
+		for (const { file, source, dicts } of htmlSources) {
+			if (!dicts || dicts.length === 0) continue;
+
+			const document = parse5.parse(source, { sourceCodeLocationInfo: true });
+			Linter.#traverse(document, (node) => {
+				const attrs = node.attrs
+					? Object.fromEntries(node.attrs.map((a) => [a.name, a.value]))
+					: {};
+				if (!attrs["data-i18n"]) return;
+
+				const key = attrs["data-i18n"];
+				const params = [];
+				for (const attr of node.attrs) {
+					if (
+						attr.name.startsWith("data-i18n-") &&
+						attr.name !== "data-i18n-type"
+					) {
+						params.push(attr.name.replace("data-i18n-", ""));
+					}
+				}
+				const loc = node.sourceCodeLocation?.attrs?.["data-i18n"] ||
+					node.sourceCodeLocation || { startLine: 1, startCol: 1 };
+				const where = { line: loc.startLine, column: loc.startCol };
+
+				const foundIn = dicts.filter((d) => key in d.dict);
+				if (foundIn.length === 0) {
+					Linter.#addViolation(
+						violations,
+						file,
+						where,
+						"HTML-102",
+						`i18n key "${key}" is not declared in any locale dictionary (${dicts.map((d) => d.locale).join(", ")}).`,
+					);
+					return;
+				}
+
+				for (const { locale, dict } of foundIn) {
+					const entry = dict[key];
+					let template;
+					if (typeof entry === "string") template = entry;
+					else if (typeof entry === "object" && entry !== null) {
+						template = entry.other || entry.one || Object.values(entry)[0];
+					}
+					if (typeof template !== "string") continue;
+
+					const tokens = new Set();
+					for (const m of template.matchAll(/\{([^}]+)\}/g)) tokens.add(m[1]);
+
+					for (const param of params) {
+						if (!tokens.has(param)) {
+							Linter.#addViolation(
+								violations,
+								file,
+								where,
+								"HTML-103",
+								`data-i18n-${param} has no matching {${param}} token in dictionary entry "${key}" (locale "${locale}").`,
+							);
+						}
+					}
+				}
+			});
+		}
+
+		return violations;
+	}
+
 	static #traverse(node, visitor) {
 		visitor(node);
 		const children = node.childNodes || node.content?.childNodes;

package/src/linter/cli.js

@@ -19,33 +19,69 @@ export default class Cli {
 		return 0;
 	}
 
+	static #excludeDirs = new Set(["node_modules", "dist", ".git"]);
+
+	static async getFiles(dir, exts = [".html"]) {
+		const entries = await fs.readdir(dir, { withFileTypes: true });
+		const files = await Promise.all(
+			entries.map((res) => {
+				const resPath = path.resolve(dir, res.name);
+				if (res.isDirectory()) {
+					if (Cli.#excludeDirs.has(res.name) || res.name.startsWith("."))
+						return [];
+					return Cli.getFiles(resPath, exts);
+				}
+				return resPath;
+			}),
+		);
+		return Array.prototype.concat
+			.apply([], files)
+			.filter((f) => exts.includes(path.extname(f)));
+	}
+
 	static async scan(dir) {
-		const files = await Cli.getFiles(dir);
+		const allFiles = await Cli.getFiles(dir, [".html", ".js", ".json"]);
+		const htmlPaths = allFiles.filter((f) => f.endsWith(".html"));
+		const jsPaths = allFiles.filter((f) => f.endsWith(".js"));
 		let totalViolations = 0;
 
-		for (const file of files) {
+		const htmlSources = [];
+		for (const file of htmlPaths) {
 			const source = await fs.readFile(file, "utf-8");
 			let availableLocales = null;
+			const dicts = [];
 
-			if (file.endsWith(".html")) {
-				const match = source.match(/<meta\s+name="i18n"\s+content="([^"]+)"/);
-				if (match) {
-					const localesDir = path.resolve(
-						path.dirname(file),
-						match[1].startsWith("/") ? `.${match[1]}` : match[1],
-					);
-					try {
-						const entries = await fs.readdir(localesDir);
-						availableLocales = entries
-							.filter((f) => f.endsWith(".json"))
-							.map((f) => f.replace(".json", ""));
-					} catch {
-						// Folder not found or unreadable
+			const match = source.match(/<meta\s+name="i18n"\s+content="([^"]+)"/);
+			if (match) {
+				const localesDir = path.resolve(
+					path.dirname(file),
+					match[1].startsWith("/") ? `.${match[1]}` : match[1],
+				);
+				try {
+					const entries = await fs.readdir(localesDir);
+					availableLocales = entries
+						.filter((f) => f.endsWith(".json"))
+						.map((f) => f.replace(".json", ""));
+					for (const entry of entries) {
+						if (!entry.endsWith(".json")) continue;
+						const locale = entry.replace(".json", "");
+						try {
+							const raw = await fs.readFile(
+								path.join(localesDir, entry),
+								"utf-8",
+							);
+							dicts.push({ locale, dict: JSON.parse(raw) });
+						} catch {
+							// Skip unparseable locale file
+						}
 					}
+				} catch {
+					// Folder not found or unreadable
 				}
 			}
 
 			const violations = Linter.check(file, source, availableLocales);
+			htmlSources.push({ file, source, dicts });
 
 			if (violations.length > 0) {
 				totalViolations += violations.length;
@@ -53,34 +89,36 @@ export default class Cli {
 			}
 		}
 
+		const jsSources = [];
+		for (const file of jsPaths) {
+			const source = await fs.readFile(file, "utf-8");
+			jsSources.push({ file, source });
+		}
+
+		const crossViolations = Linter.crossCheck({
+			htmlSources,
+			jsSources,
+		});
+
+		if (crossViolations.length > 0) {
+			const byFile = new Map();
+			for (const v of crossViolations) {
+				if (!byFile.has(v.file)) byFile.set(v.file, []);
+				byFile.get(v.file).push(v);
+			}
+			for (const [file, vs] of byFile) Cli.report(file, vs);
+			totalViolations += crossViolations.length;
+		}
+
 		if (totalViolations === 0) {
 			console.log("✔ No violations found.");
 		} else {
 			console.log(
-				`\n✖ Found ${totalViolations} violations across ${files.length} files.`,
+				`\n✖ Found ${totalViolations} violations across ${htmlPaths.length} HTML files.`,
 			);
 		}
-		return totalViolations;
-	}
 
-	static #excludeDirs = new Set(["node_modules", "dist", ".git"]);
-
-	static async getFiles(dir) {
-		const entries = await fs.readdir(dir, { withFileTypes: true });
-		const files = await Promise.all(
-			entries.map((res) => {
-				const resPath = path.resolve(dir, res.name);
-				if (res.isDirectory()) {
-					if (Cli.#excludeDirs.has(res.name) || res.name.startsWith("."))
-						return [];
-					return Cli.getFiles(resPath);
-				}
-				return resPath;
-			}),
-		);
-		return Array.prototype.concat
-			.apply([], files)
-			.filter((f) => path.extname(f) === ".html");
+		return totalViolations;
 	}
 
 	static report(file, violations) {