on_the_money 0.3.3 → 0.3.6

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.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,5 +1,7 @@
 # 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.
@@ -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.boot(options?)`, `the.title(str)`, `the.attr(el, ...)`. Live accessors: `the.dictionary`, `the.locale`.
 Live accessors on `the`: `the.dictionary`, `the.locale`.
 
 ## API
@@ -109,7 +111,7 @@ Polymorphic on a single disambiguator: `args[0] instanceof Element`. Three call
 | `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-*`.
+- **ARIA mapping** (key → attribute): `expanded`, `selected`, `hidden`, `checked`, `disabled`, `invalid`, `required`, `readonly`, `pressed`, `current` → `aria-*`. All other keys → `data-*`. Note: HTML `hidden` and `aria-hidden` are different concepts (layout vs accessibility tree); the mapping here is always to `aria-*`.
 - **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.
@@ -127,6 +129,27 @@ the.form(form);
 
 Returns a **nested** object (matches browser submission semantics). Compose with `the.flat` before feeding to `the(el, {...})`.
 
+### `the.title(str)` — set `document.title`
+
+`<title>` lives in `<head>`, outside the body subtree that `the()` walks for `[data-text]` mirroring. Use `the.title(str)` for dynamic page titles instead of `document.title = "..."`.
+
+```javascript
+the.title(`${user.name} — Dashboard`);
+```
+
+Returns the `<title>` element.
+
+### `the.attr(el, name, val)` / `the.attr(el, { ...attrs })` — plain attribute writes
+
+Writes attributes that aren't `data-*` or ARIA — `href`, `value`, `rel`, `for`, etc. Use this instead of `el.setAttribute(...)` so all DOM writes in app code go through the OTM surface.
+
+```javascript
+the.attr($("#post-link"), "href", `/posts/${slug}`);
+the.attr($("#prev"), { href: prevUrl, rel: "prev" });
+```
+
+Returns `el`. Throws if the second arg is neither a string nor a plain object.
+
 ### `the.flat(obj, sep = "_")` — nested-to-flat
 
 ```javascript
@@ -347,9 +370,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 +412,23 @@ 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. |
+| **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.
+
+### `--conformance` flag
+
+Append `--conformance` for a single machine-grep-able summary line at the end of output:
+
+```
+$ npx otm-lint --check ./src --conformance
+... violations ...
+OTM conformance: 3 violations
+```
 
-`otm-lint` default-excludes `node_modules`, `dist`, `.git`, and dotdirs. It only scans `.html` — everything else delegates to the layers above.
+Useful for CI gates and LLM tooling that wants a one-line signal.
 
 ### Recommended companions (not shipped)
 

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,o,n){let r=typeof t=="string"?document.querySelector(t):t||document.body,c=i=>{let l=i.target.closest(o);l&&r.contains(l)&&n.call(l,i,l)};return r.addEventListener(e,c),()=>r.removeEventListener(e,c)}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 s=class a{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?a.#e(t[0],t.slice(1)):a.#e(document.body,t)}static#e(t,e){let[o,n]=e,r=t===document.body;if(e.length===1&&typeof o=="string")return a.#r(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 a.#t(t,o,n),r&&!a.ephemeralKeys.has(o)&&localStorage.setItem(`${a.prefix}${o}`,n),t}if(e.length===1&&o?.constructor===Object){for(let[c,i]of Object.entries(o))a.#t(t,c,i),r&&!a.ephemeralKeys.has(c)&&localStorage.setItem(`${a.prefix}${c}`,i);return t}throw new TypeError(`the(): unrecognized call shape (${e.map(c=>typeof c).join(", ")})`)}static title(t){return document.title=t,document.querySelector("title")}static attr(t,e,o){if(typeof e=="string")return t.setAttribute(e,o),t;if(e?.constructor===Object){for(let[n,r]of Object.entries(e))t.setAttribute(n,r);return t}throw new TypeError("the.attr: second arg must be a string or plain object")}static flat(t,e="_"){if(t===null||typeof t!="object")throw new TypeError("the.flat: input must be an object");let o={},n=(r,c)=>{if(r===null||typeof r!="object"){o[c]=r;return}for(let[i,l]of Object.entries(r))n(l,c?`${c}${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 c=(n.type||"text").toLowerCase();if(c==="submit"||c==="button"||c==="reset"||(c==="checkbox"||c==="radio")&&!(n.checked??n.hasAttribute("checked")))continue;let i=n.value??n.getAttribute("value")??"";a.#o(e,r,i)}return e}static#o(t,e,o){let n=e.split(/[\[\]]/).filter(Boolean),r=t;for(let c=0;c<n.length;c++){let i=n[c];c===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 c=t.querySelectorAll?[t,...t.querySelectorAll("[data-i18n]")]:[t];for(let i of c)if(i.hasAttribute?.("data-i18n")){let l=i.getAttribute("data-i18n"),p={};for(let y of i.attributes)if(y.name.startsWith("data-i18n-")&&y.name!=="data-i18n-type"){let v=y.name.replace("data-i18n-","");p[v]=y.value}let h=i.getAttribute("data-i18n-type");i.textContent=a._t(l,{...p,type:h})}return t}if(!t)return a._t(document.body),"";let n=a.dictionary[t];if(!n){if(e.val!==void 0&&(e.type==="currency"||e.type==="date")){let c=e.type==="currency"?new Intl.NumberFormat(a.locale,{style:"currency",currency:"USD"}):new Intl.DateTimeFormat(a.locale);return e.type==="date"?c.format(new Date(e.val)):c.format(Number(e.val))}return t}if(typeof n=="object"){let c=e.qty!==void 0?Number(e.qty):0,i=new Intl.PluralRules(a.locale).select(c);n=n[i]||n.other||t}if(typeof n!="string")return t;let r=n;for(let[c,i]of Object.entries(e)){let l=i;if(c==="val"&&e.type){let p=Number(i),h=e.type==="currency"?new Intl.NumberFormat(a.locale,{style:"currency",currency:"USD"}):e.type==="date"?new Intl.DateTimeFormat(a.locale):new Intl.NumberFormat(a.locale);l=e.type==="date"?h.format(new Date(i)):h.format(p)}r=r.replace(`{${c}}`,l)}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#n={expanded:"aria-expanded",selected:"aria-selected",hidden:"aria-hidden",checked:"aria-checked",disabled:"aria-disabled",invalid:"aria-invalid",required:"aria-required",readonly:"aria-readonly",pressed:"aria-pressed",current:"aria-current"};static#r(t,e){let o=a.#n[e]||`data-${e}`;return t.getAttribute(o)}static#t(t,e,o){let n=a.#n[e]||`data-${e}`,r=typeof o=="boolean"?o?"true":"false":o;if(t.setAttribute(n,r),t.querySelectorAll){let c=t.querySelectorAll(`[data-text="${e}"]`);for(let i of c)i.textContent=r}t.getAttribute?.("data-text")===e&&(t.textContent=r)}static async boot({signal:t,locales:e,dictionary:o,namespace:n,defaultLocale:r,ephemeralKeys:c}={}){n&&(a.prefix=`${n}:`),c&&(a.ephemeralKeys=new Set(c));let i=typeof window<"u"&&window.location?window.location.search:"",l=new URLSearchParams(i),p=(typeof navigator<"u"?navigator.language:null)||document.documentElement.lang||"en";a.locale=l.get("lang")||localStorage.getItem(`${a.prefix}lang`)||p;let h=r||document.documentElement.lang,y=a.locale.toLowerCase().split("-")[0],v=h?.toLowerCase().split("-")[0],A=!!v&&y===v;if(!A)if(o)a.dictionary=o;else{let d=document.querySelector('meta[name="i18n"]'),w=e||d?.getAttribute("content");if(w){let g=d?.getAttribute("data-fallback")||"en",x=(d?.getAttribute("data-available")||"").split(",").map(f=>f.trim().toLowerCase()),$=a.locale.toLowerCase(),E=$.split("-")[0],S=g;x.includes($)?S=$:x.includes(E)&&(S=E);try{let f=await fetch(`${w}/${S}.json`,{signal:t});f.ok&&(a.dictionary=await f.json())}catch(f){if(t?.aborted)throw f;console.warn("otm: i18n fetch failed",f)}}}for(let d=0;d<localStorage.length;d++){let w=localStorage.key(d);if(w.startsWith(a.prefix)){let g=w.slice(a.prefix.length);if(g!=="lang"&&!a.ephemeralKeys.has(g)){let x=localStorage.getItem(w);a.#t(document.body,g,x)}}}A||a._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;s._t(r),o.appendChild(r);let c=new CustomEvent("mounted",{bubbles:!0,detail:{parent:o}});return r.dispatchEvent(c),r}};var q=b.on;q.emit=b.emit;var u=s.the,L=s._t,j=s.route;u.t=L;u.route=j;u.form=s.form;u.flat=s.flat;u.boot=s.boot;u.title=s.title;u.attr=s.attr;Object.defineProperty(u,"dictionary",{get:()=>s.dictionary,set:a=>{s.dictionary=a}});Object.defineProperty(u,"locale",{get:()=>s.locale,set:a=>{s.locale=a}});var N=m.$;N.clone=m.clone;var C=m.$$,U={on:q,the:u,$:N,$$:C,_t:L};export{N as $,C as $$,L as _t,U as default,q as on,j as route,u 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.3.6",
+	"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/The.js

@@ -47,6 +47,25 @@ export default class The {
 		);
 	}
 
+	static title(str) {
+		document.title = str;
+		return document.querySelector("title");
+	}
+
+	static attr(el, nameOrObj, val) {
+		if (typeof nameOrObj === "string") {
+			el.setAttribute(nameOrObj, val);
+			return el;
+		}
+		if (nameOrObj?.constructor === Object) {
+			for (const [k, v] of Object.entries(nameOrObj)) el.setAttribute(k, v);
+			return el;
+		}
+		throw new TypeError(
+			"the.attr: second arg must be a string or plain object",
+		);
+	}
+
 	static flat(obj, sep = "_") {
 		if (obj === null || typeof obj !== "object") {
 			throw new TypeError("the.flat: input must be an object");
@@ -233,27 +252,26 @@ export default class The {
 		navigate();
 	}
 
+	static #ariaMap = {
+		expanded: "aria-expanded",
+		selected: "aria-selected",
+		hidden: "aria-hidden",
+		checked: "aria-checked",
+		disabled: "aria-disabled",
+		invalid: "aria-invalid",
+		required: "aria-required",
+		readonly: "aria-readonly",
+		pressed: "aria-pressed",
+		current: "aria-current",
+	};
+
 	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);
 

package/src/core/index.js

@@ -13,6 +13,8 @@ the.route = route;
 the.form = The.form;
 the.flat = The.flat;
 the.boot = The.boot;
+the.title = The.title;
+the.attr = The.attr;
 
 Object.defineProperty(the, "dictionary", {
 	get: () => 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,119 @@ 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");
+					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

@@ -6,11 +6,14 @@ export default class Cli {
 	static async run(args = []) {
 		console.log("on_the_money.js Linter (Experimental)");
 
+		const wantConformance = args.includes("--conformance");
+
 		if (args.includes("--check")) {
 			const dirIndex = args.indexOf("--check") + 1;
 			const targetDir = args[dirIndex] || ".";
 			try {
-				return await Cli.scan(targetDir);
+				const total = await Cli.scan(targetDir, { wantConformance });
+				return total;
 			} catch (e) {
 				console.error(`Error scanning ${targetDir}: ${e.message}`);
 				return -1;
@@ -19,33 +22,69 @@ export default class Cli {
 		return 0;
 	}
 
-	static async scan(dir) {
-		const files = await Cli.getFiles(dir);
+	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, opts = {}) {
+		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 +92,40 @@ 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"]);
+		if (opts.wantConformance) {
+			console.log(`OTM conformance: ${totalViolations} violations`);
+		}
 
-	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) {