on_the_money 0.7.2 → 0.8.1

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.8.1] — 2026-07-25
+
+### Fixed
+
+- Restored the `otm-lint` executable in the npm manifest by using npm 11's normalized bin target path. `0.8.0` omitted the bin during publication.
+
+## [0.8.0] — 2026-07-25
+
+### Added
+
+- Public TypeScript declarations for every package subpath, compiler-checked against representative consumer calls.
+- Real-browser contract tests across Chromium, Firefox, and WebKit.
+- `live()` `onError(error, raw)` hook for malformed JSON frames; without a hook the error warns, and either way the connection remains open.
+
+### Changed
+
+- **Breaking:** `the()` now enforces flat state at runtime: strings, finite numbers, booleans, and `null` deletion only. Previously objects and other unsupported values reached the DOM through implicit string coercion.
+- The shipped Stylelint plugin's direct `postcss-selector-parser` import is now a declared runtime dependency.
+
+### Fixed
+
+- `the.form()` rejects `__proto__`, `prototype`, and `constructor` bracket-path segments, preventing form field names from traversing or mutating inherited prototypes.
+- EJS code and comment tags are neutralized before markup linting, so raw HTML tokens inside template code cannot push parse5 into RAWTEXT mode and hide the rest of the file. (#146)
+
 ## [0.7.2] — 2026-07-20
 
 ### Changed

package/README.md

@@ -152,12 +152,12 @@ Polymorphic on a single disambiguator: `args[0] instanceof Element`. Three call
 
 - **Truly one-off attributes** still use `el.setAttribute(name, val)` directly, colocated with the write (Discipline #2). `data-bind` is for attributes that carry per-element *state-derived data* (every card's link); `setAttribute` is for structural one-offs. If you're writing the same `setAttribute` line in every clone loop, that's a `data-bind`.
 - **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.
+- **Values MUST be strings, finite numbers, booleans, or `null`.** Numbers and booleans stringify; `null` deletes. Objects, arrays, functions, symbols, bigint, `NaN`, and infinities throw at runtime. Pass nested objects through `the.flat(...)` first.
 - **`the(key, undefined)` throws.** Two args means set; missing val is a contract violation.
 
 ### `the.form(formEl)` — form extraction
 
-Walks `input, select, textarea` descendants. Skips unnamed, disabled, submit/button/reset controls, file inputs, and unchecked checkboxes/radios. Parses bracket-notation names into a nested object:
+Walks `input, select, textarea` descendants. Skips unnamed, disabled, submit/button/reset controls, file inputs, and unchecked checkboxes/radios. Parses bracket-notation names into a nested object. Unsafe path segments (`__proto__`, `prototype`, `constructor`) throw instead of entering the result graph:
 
 ```javascript
 the.form(form);
@@ -358,6 +358,7 @@ const reply = await ch.request({ type: "filter", q: "cats" }, { takeLatest: true
 | Option | Behavior |
 | --- | --- |
 | `onMessage(type, data, at)` | Every non-reply frame. Unknown types must be ignorable — the vocabulary is append-only. |
+| `onError(error, raw)` | Malformed JSON frame. Without this callback, `live()` warns; either way the connection remains open. |
 | `onDown()` / `onUp()` | Link state hooks. Fail closed in `onDown`: a dead socket should surface the degraded truth. |
 | `signal` | `AbortSignal`; abort closes the socket and stops reconnecting. |
 

package/dist/on_the_money.min.js

@@ -1 +1 @@
-var g=class{static on(t,e,n,c){let o=typeof t=="string"?document.querySelector(t):t||document.body;if(!o)throw new Error(`on(): parent selector matched nothing: ${t}`);let r=i=>{let s=i.target.closest(n);s&&o.contains(s)&&c.call(s,i,s)};return o.addEventListener(e,r),()=>o.removeEventListener(e,r)}static emit(t,e,n){let c=typeof t=="string"?document.querySelector(t):t,o=new CustomEvent(e,{bubbles:!0,cancelable:!0,detail:n});c.dispatchEvent(o)}};var l=class a{static dictionary={};static locale=typeof navigator<"u"?navigator.language:"en";static prefix="otm:";static persistKeys=new Set;static#e(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?a.#o(t[0],t.slice(1)):a.#o(document.body,t)}static#o(t,e){let[n,c]=e,o=t===document.body;if(e.length===1&&typeof n=="string")return a.#d(t,a.#e(n));if(e.length===2&&typeof n=="string"){if(typeof c>"u")throw new TypeError(`the(${JSON.stringify(n)}, undefined): val is required for set`);return a.#i(t,o,n,c),t}if(e.length===1&&n?.constructor===Object){for(let[r,i]of Object.entries(n))a.#i(t,o,r,i);return t}throw new TypeError(`the(): unrecognized call shape (${e.map(r=>typeof r).join(", ")})`)}static match(t,e){let n=e??(typeof window<"u"&&window.location?window.location.pathname:""),c=[],r=t.replace(/[.*+?^${}()|[\]\\]/g,"\\$&").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g,(u,f)=>(c.push(f),"([^/]+)")),i=n.match(new RegExp(`^${r}$`));if(!i)return null;let s={};return c.forEach((u,f)=>{s[u]=decodeURIComponent(i[f+1])}),s}static flat(t,e="_"){if(t===null||typeof t!="object")throw new TypeError("the.flat: input must be an object");let n={},c=(o,r)=>{if(o===null||typeof o!="object"){n[r]=o;return}for(let[i,s]of Object.entries(o))c(s,r?`${r}${e}${i}`:i)};return c(t,""),n}static form(t){let e={},n=t.querySelectorAll("input, select, textarea");for(let c of n){let o=c.name;if(!o||c.disabled)continue;let r=(c.type||"text").toLowerCase();if(r==="submit"||r==="button"||r==="reset"||r==="file"||(r==="checkbox"||r==="radio")&&!(c.checked??c.hasAttribute("checked")))continue;if(c.tagName==="SELECT"&&c.hasAttribute("multiple")){let s="selectedOptions"in c?c.selectedOptions:c.querySelectorAll("option[selected]");for(let u of s)a.#r(e,o,u.value);continue}let i=c.value??c.getAttribute("value")??"";a.#r(e,o,i)}return e}static#r(t,e,n){let c=e.endsWith("[]"),o=e.split(/[\[\]]/).filter(Boolean),r=t;for(let i=0;i<o.length;i++){let s=o[i];i===o.length-1?c?(r[s]||=[],r[s].push(n)):r[s]!==void 0?(Array.isArray(r[s])||(r[s]=[r[s]]),r[s].push(n)):r[s]=n:(r[s]=r[s]||{},r=r[s])}}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 o of c)if(o.hasAttribute?.("data-i18n")){let r=o.getAttribute("data-i18n"),i={};for(let f of o.attributes)if(f.name.startsWith("data-i18n-")&&f.name!=="data-i18n-type"){let A=f.name.replace("data-i18n-","");i[A]=f.value}let s=o.getAttribute("data-i18n-type"),u=a.#a(r,{...i,type:s});u!==null&&(o.textContent=u)}return t}return t?a.#a(t,e)??t:(a._t(document.body),"")}static#c(t){if(!t.currency)throw new TypeError('_t: type "currency" requires an explicit currency (options.currency or data-i18n-currency)');return t.currency}static#a(t,e){let n=a.dictionary[t];if(!n){if(e.val!==void 0&&(e.type==="currency"||e.type==="date")){let o=e.type==="currency"?new Intl.NumberFormat(a.locale,{style:"currency",currency:a.#c(e)}):new Intl.DateTimeFormat(a.locale);return e.type==="date"?o.format(new Date(e.val)):o.format(Number(e.val))}return null}if(typeof n=="object"){let o=e.qty!==void 0?Number(e.qty):0,r=new Intl.PluralRules(a.locale).select(o);n=n[r]||n.other||t}if(typeof n!="string")return t;let c=n;for(let[o,r]of Object.entries(e)){let i=r;if(o==="val"&&e.type){let s=Number(r),u=e.type==="currency"?new Intl.NumberFormat(a.locale,{style:"currency",currency:a.#c(e)}):e.type==="date"?new Intl.DateTimeFormat(a.locale):new Intl.NumberFormat(a.locale);i=e.type==="date"?u.format(new Date(r)):u.format(s)}c=c.replaceAll(`{${o}}`,()=>i)}return c}static#t=null;static route(t,{match:e}={}){if(typeof window>"u")return;if(a.#t)throw new Error("route(): a router is already active \u2014 call its unsubscribe first");let n=()=>t(window.location.pathname,window.location.search,window.location.hash);a.#t=n;let c=o=>{if(o.metaKey||o.ctrlKey||o.shiftKey||o.altKey||o.button>0)return;let r=o.target.closest("a");if(!r||!r.getAttribute("href")||r.hasAttribute("data-external")||r.hasAttribute("download")||r.target==="_blank"||e&&!r.matches(e))return;let i=new URL(r.getAttribute("href"),window.location.href);i.origin===window.location.origin&&(i.pathname===window.location.pathname&&i.search===window.location.search&&i.hash||(o.preventDefault(),i.href!==window.location.href&&(window.history.pushState({},"",i.href),n())))};return window.addEventListener("popstate",n),window.addEventListener("hashchange",n),document.addEventListener("click",c),n(),()=>{window.removeEventListener("popstate",n),window.removeEventListener("hashchange",n),document.removeEventListener("click",c),a.#t=null}}static go(t){if(typeof window>"u")return;if(!a.#t)throw new Error("route.go(): no active router \u2014 call route() first");let e=new URL(t,window.location.href);e.href!==window.location.href&&(window.history.pushState({},"",e.href),a.#t())}static#f={expanded:"aria-expanded",selected:"aria-selected",hidden:"aria-hidden",checked:"aria-checked",disabled:"aria-disabled"};static#n(t,e){return t===document.body?`data-${e}`:a.#f[e]||`data-${e}`}static#i(t,e,n,c){let o=a.#e(n);if(c===null){a.#m(t,o),e&&a.persistKeys.has(o)&&localStorage.removeItem(`${a.prefix}${o}`);return}a.#s(t,o,c),e&&a.persistKeys.has(o)&&localStorage.setItem(`${a.prefix}${o}`,c)}static#d(t,e){return t.getAttribute(a.#n(t,e))}static#s(t,e,n){let c=typeof n=="boolean"?n?"true":"false":n;t.setAttribute(a.#n(t,e),c),a.#l(t,e,c,!1)}static#m(t,e){t.removeAttribute(a.#n(t,e)),a.#l(t,e,"",!0)}static#l(t,e,n,c){let o=t===document.body&&typeof document<"u"?document.documentElement||document:t;if(o.querySelectorAll){for(let r of o.querySelectorAll(`[data-text="${e}"]`))r.textContent=n;for(let r of o.querySelectorAll(`[data-bind*="${e}"]`))a.#u(r,e,n,c)}t.getAttribute?.("data-text")===e&&(t.textContent=n),a.#u(t,e,n,c)}static#u(t,e,n,c){let o=t.getAttribute?.("data-bind");if(o)for(let r of o.split(/\s+/)){let i=r.indexOf(":");if(i<1||r.slice(i+1)!==e)continue;let s=r.slice(0,i);c?t.removeAttribute(s):t.setAttribute(s,n)}}static async boot({signal:t,locales:e,dictionary:n,namespace:c,defaultLocale:o,persistKeys:r}={}){c&&(a.prefix=`${c}:`),r&&(a.persistKeys=new Set(r.map(d=>a.#e(d))));let i=typeof window<"u"&&window.location?window.location.search:"",s=new URLSearchParams(i),u=document.documentElement.lang||(typeof navigator<"u"?navigator.language:null)||"en";a.locale=s.get("lang")||localStorage.getItem(`${a.prefix}lang`)||u;let f=o||document.documentElement.lang,A=a.locale.toLowerCase().split("-")[0],S=f?.toLowerCase().split("-")[0],L=!!S&&A===S;if(n)a.dictionary=n;else if(!L){let d=document.querySelector('meta[name="i18n"]'),y=e||d?.getAttribute("content");if(y){let h=d?.getAttribute("data-fallback")||"en",v=(d?.getAttribute("data-available")||"").split(",").map(w=>w.trim().toLowerCase()),E=a.locale.toLowerCase(),q=E.split("-")[0],$=h;v.includes(E)?$=E:v.includes(q)&&($=q);let C=async w=>{let b=await fetch(`${y}/${w}.json`,{signal:t});if(!b.ok)throw new Error(`HTTP ${b.status} for ${w}.json`);return b.json()};try{a.dictionary=await C($)}catch(w){if(t?.aborted)throw w;if(console.warn(`otm: i18n fetch failed for "${$}"`,w),$!==h)try{a.dictionary=await C(h)}catch(b){if(t?.aborted)throw b;console.warn(`otm: i18n fallback "${h}" failed`,b)}}}}for(let d=0;d<localStorage.length;d++){let y=localStorage.key(d);if(y.startsWith(a.prefix)){let h=y.slice(a.prefix.length);if(h!=="lang"&&a.persistKeys.has(h)){let v=localStorage.getItem(y);a.#s(document.body,h,v)}}}L||a._t()}};var p=class a{static $(t,e){let n=t,c=e;return typeof n=="string"&&(c=n,n=document),n.querySelector(c)}static $$(t,e){let n=t,c=e;return typeof n=="string"&&(c=n,n=document),Array.from(n.querySelectorAll(c))}static clone(t,e,{position:n="beforeend"}={}){let c=typeof t=="string"?document.querySelector(t):t,o=document.querySelector(e);if(!c)throw new Error(`Parent not found: ${t}`);if(!o)throw new Error(`Template not found: ${e}`);let r=o.content.cloneNode(!0).firstElementChild;l._t(r),c.insertAdjacentElement(n,r);let i=new CustomEvent("mounted",{bubbles:!0,detail:{parent:c}});return r.dispatchEvent(i),r}static cloneEach(t,e,n,c){let o=typeof t=="string"?document.querySelector(t):t;if(!o)throw new Error(`Parent not found: ${t}`);o.replaceChildren();let r=[],i=0;for(let s of n){let u=a.clone(o,e);c?.(u,s,i++),r.push(u)}return r}};var N=g.on;N.emit=g.emit;var m=l.the,j=l._t,T=l.route;T.go=l.go;m.t=j;m.route=T;m.form=l.form;m.flat=l.flat;m.match=l.match;m.boot=l.boot;Object.defineProperty(m,"dictionary",{get:()=>l.dictionary,set:a=>{l.dictionary=a}});Object.defineProperty(m,"locale",{get:()=>l.locale,set:a=>{l.locale=a}});var x=p.$;x.clone=p.clone;x.cloneEach=p.cloneEach;var I=p.$$,z={on:N,the:m,$:x,$$:I,_t:j};export{x as $,I as $$,j as _t,z as default,N as on,T as route,m as the};
+var g=class{static on(t,e,r,a){let n=typeof t=="string"?document.querySelector(t):t||document.body;if(!n)throw new Error(`on(): parent selector matched nothing: ${t}`);let c=i=>{let s=i.target.closest(r);s&&n.contains(s)&&a.call(s,i,s)};return n.addEventListener(e,c),()=>n.removeEventListener(e,c)}static emit(t,e,r){let a=typeof t=="string"?document.querySelector(t):t,n=new CustomEvent(e,{bubbles:!0,cancelable:!0,detail:r});a.dispatchEvent(n)}};var u=class o{static dictionary={};static locale=typeof navigator<"u"?navigator.language:"en";static prefix="otm:";static persistKeys=new Set;static#e(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?o.#r(t[0],t.slice(1)):o.#r(document.body,t)}static#r(t,e){let[r,a]=e,n=t===document.body;if(e.length===1&&typeof r=="string")return o.#m(t,o.#e(r));if(e.length===2&&typeof r=="string"){if(typeof a>"u")throw new TypeError(`the(${JSON.stringify(r)}, undefined): val is required for set`);return o.#i(t,n,r,a),t}if(e.length===1&&r?.constructor===Object){for(let[c,i]of Object.entries(r))o.#i(t,n,c,i);return t}throw new TypeError(`the(): unrecognized call shape (${e.map(c=>typeof c).join(", ")})`)}static match(t,e){let r=e??(typeof window<"u"&&window.location?window.location.pathname:""),a=[],c=t.replace(/[.*+?^${}()|[\]\\]/g,"\\$&").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g,(l,f)=>(a.push(f),"([^/]+)")),i=r.match(new RegExp(`^${c}$`));if(!i)return null;let s={};return a.forEach((l,f)=>{s[l]=decodeURIComponent(i[f+1])}),s}static flat(t,e="_"){if(t===null||typeof t!="object")throw new TypeError("the.flat: input must be an object");let r={},a=(n,c)=>{if(n===null||typeof n!="object"){r[c]=n;return}for(let[i,s]of Object.entries(n))a(s,c?`${c}${e}${i}`:i)};return a(t,""),r}static form(t){let e={},r=t.querySelectorAll("input, select, textarea");for(let a of r){let n=a.name;if(!n||a.disabled)continue;let c=(a.type||"text").toLowerCase();if(c==="submit"||c==="button"||c==="reset"||c==="file"||(c==="checkbox"||c==="radio")&&!(a.checked??a.hasAttribute("checked")))continue;if(a.tagName==="SELECT"&&a.hasAttribute("multiple")){let s="selectedOptions"in a?a.selectedOptions:a.querySelectorAll("option[selected]");for(let l of s)o.#o(e,n,l.value);continue}let i=a.value??a.getAttribute("value")??"";o.#o(e,n,i)}return e}static#o(t,e,r){let a=e.endsWith("[]"),n=e.split(/[\[\]]/).filter(Boolean),c=n.find(s=>["__proto__","prototype","constructor"].includes(s));if(c)throw new TypeError(`the.form: unsafe field name ${JSON.stringify(e)} contains forbidden path segment ${JSON.stringify(c)}`);let i=t;for(let s=0;s<n.length;s++){let l=n[s];s===n.length-1?a?(i[l]||=[],i[l].push(r)):i[l]!==void 0?(Array.isArray(i[l])||(i[l]=[i[l]]),i[l].push(r)):i[l]=r:(i[l]=i[l]||{},i=i[l])}}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 n of a)if(n.hasAttribute?.("data-i18n")){let c=n.getAttribute("data-i18n"),i={};for(let f of n.attributes)if(f.name.startsWith("data-i18n-")&&f.name!=="data-i18n-type"){let A=f.name.replace("data-i18n-","");i[A]=f.value}let s=n.getAttribute("data-i18n-type"),l=o.#a(c,{...i,type:s});l!==null&&(n.textContent=l)}return t}return t?o.#a(t,e)??t:(o._t(document.body),"")}static#c(t){if(!t.currency)throw new TypeError('_t: type "currency" requires an explicit currency (options.currency or data-i18n-currency)');return t.currency}static#a(t,e){let r=o.dictionary[t];if(!r){if(e.val!==void 0&&(e.type==="currency"||e.type==="date")){let n=e.type==="currency"?new Intl.NumberFormat(o.locale,{style:"currency",currency:o.#c(e)}):new Intl.DateTimeFormat(o.locale);return e.type==="date"?n.format(new Date(e.val)):n.format(Number(e.val))}return null}if(typeof r=="object"){let n=e.qty!==void 0?Number(e.qty):0,c=new Intl.PluralRules(o.locale).select(n);r=r[c]||r.other||t}if(typeof r!="string")return t;let a=r;for(let[n,c]of Object.entries(e)){let i=c;if(n==="val"&&e.type){let s=Number(c),l=e.type==="currency"?new Intl.NumberFormat(o.locale,{style:"currency",currency:o.#c(e)}):e.type==="date"?new Intl.DateTimeFormat(o.locale):new Intl.NumberFormat(o.locale);i=e.type==="date"?l.format(new Date(c)):l.format(s)}a=a.replaceAll(`{${n}}`,()=>i)}return a}static#t=null;static route(t,{match:e}={}){if(typeof window>"u")return;if(o.#t)throw new Error("route(): a router is already active \u2014 call its unsubscribe first");let r=()=>t(window.location.pathname,window.location.search,window.location.hash);o.#t=r;let a=n=>{if(n.metaKey||n.ctrlKey||n.shiftKey||n.altKey||n.button>0)return;let c=n.target.closest("a");if(!c||!c.getAttribute("href")||c.hasAttribute("data-external")||c.hasAttribute("download")||c.target==="_blank"||e&&!c.matches(e))return;let i=new URL(c.getAttribute("href"),window.location.href);i.origin===window.location.origin&&(i.pathname===window.location.pathname&&i.search===window.location.search&&i.hash||(n.preventDefault(),i.href!==window.location.href&&(window.history.pushState({},"",i.href),r())))};return window.addEventListener("popstate",r),window.addEventListener("hashchange",r),document.addEventListener("click",a),r(),()=>{window.removeEventListener("popstate",r),window.removeEventListener("hashchange",r),document.removeEventListener("click",a),o.#t=null}}static go(t){if(typeof window>"u")return;if(!o.#t)throw new Error("route.go(): no active router \u2014 call route() first");let e=new URL(t,window.location.href);e.href!==window.location.href&&(window.history.pushState({},"",e.href),o.#t())}static#f={expanded:"aria-expanded",selected:"aria-selected",hidden:"aria-hidden",checked:"aria-checked",disabled:"aria-disabled"};static#n(t,e){return t===document.body?`data-${e}`:o.#f[e]||`data-${e}`}static#i(t,e,r,a){let n=o.#e(r);if(a===null){o.#p(t,n),e&&o.persistKeys.has(n)&&localStorage.removeItem(`${o.prefix}${n}`);return}let c=o.#d(n,a);o.#s(t,n,c),e&&o.persistKeys.has(n)&&localStorage.setItem(`${o.prefix}${n}`,c)}static#d(t,e){if(typeof e=="string")return e;if(typeof e=="boolean")return e?"true":"false";if(typeof e=="number"&&Number.isFinite(e))return String(e);throw new TypeError(`the(${JSON.stringify(t)}, ...): state value must be a string, finite number, boolean, or null`)}static#m(t,e){return t.getAttribute(o.#n(t,e))}static#s(t,e,r){t.setAttribute(o.#n(t,e),r),o.#l(t,e,r,!1)}static#p(t,e){t.removeAttribute(o.#n(t,e)),o.#l(t,e,"",!0)}static#l(t,e,r,a){let n=t===document.body&&typeof document<"u"?document.documentElement||document:t;if(n.querySelectorAll){for(let c of n.querySelectorAll(`[data-text="${e}"]`))c.textContent=r;for(let c of n.querySelectorAll(`[data-bind*="${e}"]`))o.#u(c,e,r,a)}t.getAttribute?.("data-text")===e&&(t.textContent=r),o.#u(t,e,r,a)}static#u(t,e,r,a){let n=t.getAttribute?.("data-bind");if(n)for(let c of n.split(/\s+/)){let i=c.indexOf(":");if(i<1||c.slice(i+1)!==e)continue;let s=c.slice(0,i);a?t.removeAttribute(s):t.setAttribute(s,r)}}static async boot({signal:t,locales:e,dictionary:r,namespace:a,defaultLocale:n,persistKeys:c}={}){a&&(o.prefix=`${a}:`),c&&(o.persistKeys=new Set(c.map(d=>o.#e(d))));let i=typeof window<"u"&&window.location?window.location.search:"",s=new URLSearchParams(i),l=document.documentElement.lang||(typeof navigator<"u"?navigator.language:null)||"en";o.locale=s.get("lang")||localStorage.getItem(`${o.prefix}lang`)||l;let f=n||document.documentElement.lang,A=o.locale.toLowerCase().split("-")[0],x=f?.toLowerCase().split("-")[0],L=!!x&&A===x;if(r)o.dictionary=r;else if(!L){let d=document.querySelector('meta[name="i18n"]'),y=e||d?.getAttribute("content");if(y){let p=d?.getAttribute("data-fallback")||"en",E=(d?.getAttribute("data-available")||"").split(",").map(w=>w.trim().toLowerCase()),v=o.locale.toLowerCase(),q=v.split("-")[0],$=p;E.includes(v)?$=v:E.includes(q)&&($=q);let N=async w=>{let b=await fetch(`${y}/${w}.json`,{signal:t});if(!b.ok)throw new Error(`HTTP ${b.status} for ${w}.json`);return b.json()};try{o.dictionary=await N($)}catch(w){if(t?.aborted)throw w;if(console.warn(`otm: i18n fetch failed for "${$}"`,w),$!==p)try{o.dictionary=await N(p)}catch(b){if(t?.aborted)throw b;console.warn(`otm: i18n fallback "${p}" failed`,b)}}}}for(let d=0;d<localStorage.length;d++){let y=localStorage.key(d);if(y.startsWith(o.prefix)){let p=y.slice(o.prefix.length);if(p!=="lang"&&o.persistKeys.has(p)){let E=localStorage.getItem(y);o.#s(document.body,p,E)}}}L||o._t()}};var h=class o{static $(t,e){let r=t,a=e;return typeof r=="string"&&(a=r,r=document),r.querySelector(a)}static $$(t,e){let r=t,a=e;return typeof r=="string"&&(a=r,r=document),Array.from(r.querySelectorAll(a))}static clone(t,e,{position:r="beforeend"}={}){let a=typeof t=="string"?document.querySelector(t):t,n=document.querySelector(e);if(!a)throw new Error(`Parent not found: ${t}`);if(!n)throw new Error(`Template not found: ${e}`);let c=n.content.cloneNode(!0).firstElementChild;u._t(c),a.insertAdjacentElement(r,c);let i=new CustomEvent("mounted",{bubbles:!0,detail:{parent:a}});return c.dispatchEvent(i),c}static cloneEach(t,e,r,a){let n=typeof t=="string"?document.querySelector(t):t;if(!n)throw new Error(`Parent not found: ${t}`);n.replaceChildren();let c=[],i=0;for(let s of r){let l=o.clone(n,e);a?.(l,s,i++),c.push(l)}return c}};var C=g.on;C.emit=g.emit;var m=u.the,j=u._t,T=u.route;T.go=u.go;m.t=j;m.route=T;m.form=u.form;m.flat=u.flat;m.match=u.match;m.boot=u.boot;Object.defineProperty(m,"dictionary",{get:()=>u.dictionary,set:o=>{u.dictionary=o}});Object.defineProperty(m,"locale",{get:()=>u.locale,set:o=>{u.locale=o}});var S=h.$;S.clone=h.clone;S.cloneEach=h.cloneEach;var O=h.$$,z={on:C,the:m,$:S,$$:O,_t:j};export{S as $,O as $$,j as _t,z as default,C as on,T as route,m as the};

package/package.json

@@ -1,25 +1,50 @@
 {
 	"name": "on_the_money",
-	"version": "0.7.2",
+	"version": "0.8.1",
 	"description": "Opinionated, attribute-driven, standards-oriented modern framework. Native browser APIs only. See README.md for the authoring context.",
 	"type": "module",
 	"main": "src/core/index.js",
 	"module": "src/core/index.js",
 	"bin": {
-		"otm-lint": "./src/linter/main.js"
+		"otm-lint": "src/linter/main.js"
 	},
 	"exports": {
-		".": "./src/core/index.js",
-		"./live": "./src/live/index.js",
-		"./clipboard": "./src/clipboard/index.js",
-		"./test": "./src/test/index.js",
-		"./eslint-plugin": "./src/eslint/plugin.js",
-		"./eslint-config": "./src/eslint/config.js",
-		"./stylelint-plugin": "./src/stylelint/plugin.js",
-		"./stylelint-config": "./src/stylelint/config.js"
+		".": {
+			"types": "./src/core/index.d.ts",
+			"default": "./src/core/index.js"
+		},
+		"./live": {
+			"types": "./src/live/index.d.ts",
+			"default": "./src/live/index.js"
+		},
+		"./clipboard": {
+			"types": "./src/clipboard/index.d.ts",
+			"default": "./src/clipboard/index.js"
+		},
+		"./test": {
+			"types": "./src/test/index.d.ts",
+			"default": "./src/test/index.js"
+		},
+		"./eslint-plugin": {
+			"types": "./src/eslint/plugin.d.ts",
+			"default": "./src/eslint/plugin.js"
+		},
+		"./eslint-config": {
+			"types": "./src/eslint/config.d.ts",
+			"default": "./src/eslint/config.js"
+		},
+		"./stylelint-plugin": {
+			"types": "./src/stylelint/plugin.d.ts",
+			"default": "./src/stylelint/plugin.js"
+		},
+		"./stylelint-config": {
+			"types": "./src/stylelint/config.d.ts",
+			"default": "./src/stylelint/config.js"
+		}
 	},
 	"files": [
 		"src/**/*.js",
+		"src/**/*.d.ts",
 		"!src/**/*.test.js",
 		"dist",
 		"README.md",
@@ -29,8 +54,10 @@
 	"scripts": {
 		"build": "esbuild src/core/index.js --bundle --minify --format=esm --outfile=dist/on_the_money.min.js",
 		"test": "node --test --test-concurrency=1 src/core/*.test.js src/live/*.test.js src/clipboard/*.test.js src/linter/*.test.js src/eslint/*.test.js src/stylelint/*.test.js test/*.test.js",
+		"test:browser": "playwright test",
+		"test:types": "tsc --project tsconfig.types.json",
 		"test:coverage": "node --test --test-concurrency=1 --experimental-test-coverage --test-coverage-lines=50 --test-coverage-branches=50 --test-coverage-functions=50 src/core/*.test.js src/live/*.test.js src/clipboard/*.test.js src/linter/*.test.js src/eslint/*.test.js src/stylelint/*.test.js test/*.test.js",
-		"check": "npm run lint && npm run lint:examples && npm run build && npm run test && npm run test:coverage",
+		"check": "npm run lint && npm run lint:examples && npm run build && npm run test && npm run test:coverage && npm run test:types && npm run test:browser",
 		"lint": "biome check ./src ./test ./examples",
 		"lint:examples": "eslint examples/ && stylelint \"examples/**/*.css\"",
 		"lint:fix": "biome check --write ./src ./test ./examples",
@@ -42,7 +69,8 @@
 		"node": ">=24.0.0"
 	},
 	"dependencies": {
-		"parse5": "7.2.1"
+		"parse5": "7.2.1",
+		"postcss-selector-parser": "7.1.1"
 	},
 	"peerDependencies": {
 		"linkedom": ">=0.18",
@@ -58,11 +86,12 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "1.9.4",
+		"@playwright/test": "1.62.0",
 		"esbuild": "0.25.0",
 		"eslint": "10.4.0",
 		"linkedom": "0.18.6",
-		"postcss-selector-parser": "7.1.1",
-		"stylelint": "17.11.1"
+		"stylelint": "17.11.1",
+		"typescript": "5.9.2"
 	},
 	"license": "MIT"
 }

package/src/clipboard/index.d.ts

@@ -0,0 +1,8 @@
+export interface ClipboardOptions {
+	resetMs?: number;
+}
+
+export function clipboard(options?: ClipboardOptions): (() => void) | null;
+
+declare const api: { clipboard: typeof clipboard };
+export default api;

package/src/core/The.js

@@ -133,6 +133,14 @@ export default class The {
 		// depend on cardinality.
 		const isArrayLeaf = key.endsWith("[]");
 		const parts = key.split(/[\[\]]/).filter(Boolean);
+		const forbidden = parts.find((part) =>
+			["__proto__", "prototype", "constructor"].includes(part),
+		);
+		if (forbidden) {
+			throw new TypeError(
+				`the.form: unsafe field name ${JSON.stringify(key)} contains forbidden path segment ${JSON.stringify(forbidden)}`,
+			);
+		}
 		let current = obj;
 		for (let i = 0; i < parts.length; i++) {
 			const part = parts[i];
@@ -365,9 +373,19 @@ export default class The {
 				localStorage.removeItem(`${The.prefix}${k}`);
 			return;
 		}
-		The.#set(el, k, v);
+		const out = The.#stateValue(k, v);
+		The.#set(el, k, out);
 		if (isGlobal && The.persistKeys.has(k))
-			localStorage.setItem(`${The.prefix}${k}`, v);
+			localStorage.setItem(`${The.prefix}${k}`, out);
+	}
+
+	static #stateValue(key, val) {
+		if (typeof val === "string") return val;
+		if (typeof val === "boolean") return val ? "true" : "false";
+		if (typeof val === "number" && Number.isFinite(val)) return String(val);
+		throw new TypeError(
+			`the(${JSON.stringify(key)}, ...): state value must be a string, finite number, boolean, or null`,
+		);
 	}
 
 	static #get(el, key) {
@@ -375,9 +393,8 @@ export default class The {
 	}
 
 	static #set(el, key, val) {
-		const out = typeof val === "boolean" ? (val ? "true" : "false") : val;
-		el.setAttribute(The.#attr(el, key), out);
-		The.#mirror(el, key, out, false);
+		el.setAttribute(The.#attr(el, key), val);
+		The.#mirror(el, key, val, false);
 	}
 
 	static #delete(el, key) {

package/src/core/index.d.ts

@@ -0,0 +1,100 @@
+export type StateValue = string | number | boolean | null;
+export type State = Record<string, StateValue>;
+export type DictionaryEntry = string | Record<string, string>;
+export type Dictionary = Record<string, DictionaryEntry>;
+
+export interface TranslationOptions {
+	[key: string]: unknown;
+	type?: "currency" | "date" | string;
+	currency?: string;
+	qty?: number | string;
+	val?: unknown;
+}
+
+export interface BootOptions {
+	signal?: AbortSignal;
+	locales?: string;
+	dictionary?: Dictionary;
+	namespace?: string;
+	defaultLocale?: string;
+	persistKeys?: string[];
+}
+
+export interface The {
+	(key: string): string | null;
+	(key: string, value: StateValue): HTMLElement;
+	(values: State): HTMLElement;
+	<T extends Element>(element: T, key: string): string | null;
+	<T extends Element>(element: T, key: string, value: StateValue): T;
+	<T extends Element>(element: T, values: State): T;
+	t: typeof _t;
+	route: Route;
+	form(form: HTMLFormElement): Record<string, unknown>;
+	flat(object: object, separator?: string): Record<string, unknown>;
+	match(pattern: string, path?: string): Record<string, string> | null;
+	boot(options?: BootOptions): Promise<void>;
+	dictionary: Dictionary;
+	locale: string;
+}
+
+export interface Route {
+	(
+		callback: (pathname: string, search: string, hash: string) => void,
+		options?: { match?: string },
+	): (() => void) | undefined;
+	go(path: string): void;
+}
+
+export interface Select {
+	<E extends Element = Element>(selector: string): E | null;
+	<E extends Element = Element>(
+		context: ParentNode,
+		selector: string,
+	): E | null;
+	clone(
+		parent: Element | string,
+		selector: string,
+		options?: { position?: InsertPosition },
+	): HTMLElement;
+	cloneEach<T>(
+		parent: Element | string,
+		selector: string,
+		items: Iterable<T>,
+		fill?: (element: HTMLElement, item: T, index: number) => void,
+	): HTMLElement[];
+}
+
+export interface SelectAll {
+	<E extends Element = Element>(selector: string): E[];
+	<E extends Element = Element>(context: ParentNode, selector: string): E[];
+}
+
+export interface On {
+	(
+		parent: Element | Document | string | null,
+		event: string,
+		selector: string,
+		handler: (this: Element, event: Event, target: Element) => void,
+	): () => void;
+	emit(element: Element | string, event: string, detail?: unknown): void;
+}
+
+export function _t(key: string, options?: TranslationOptions): string;
+export function _t<T extends Node>(node: T): T;
+export function _t(): string;
+
+export const the: The;
+export const route: Route;
+export const $: Select;
+export const $$: SelectAll;
+export const on: On;
+
+declare const api: {
+	on: On;
+	the: The;
+	$: Select;
+	$$: SelectAll;
+	_t: typeof _t;
+};
+
+export default api;

package/src/eslint/config.d.ts

@@ -0,0 +1,2 @@
+declare const config: object[];
+export default config;

package/src/eslint/plugin.d.ts

@@ -0,0 +1,2 @@
+declare const plugin: object;
+export default plugin;

package/src/linter/Linter.js

@@ -1,10 +1,12 @@
-import * as parse5 from "parse5";
+import Markup from "./Markup.js";
 
 export default class Linter {
 	static check(file, source, availableLocales = null) {
 		if (!file.endsWith(".html")) return [];
 		const violations = [];
-		const document = parse5.parse(source, { sourceCodeLocationInfo: true });
+		const document = Markup.parse(file, source, {
+			sourceCodeLocationInfo: true,
+		});
 		Linter.#checkHtmlRules(document, violations, file, availableLocales);
 		return violations;
 	}
@@ -142,7 +144,9 @@ export default class Linter {
 		// 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 });
+			const document = Markup.parse(file, source, {
+				sourceCodeLocationInfo: true,
+			});
 			Linter.#traverse(document, (node) => {
 				if (node.nodeName === "template") {
 					const idAttr = node.attrs?.find((a) => a.name === "id");
@@ -190,7 +194,9 @@ export default class Linter {
 		for (const { file, source, dicts } of htmlSources) {
 			if (!dicts || dicts.length === 0) continue;
 
-			const document = parse5.parse(source, { sourceCodeLocationInfo: true });
+			const document = Markup.parse(file, source, {
+				sourceCodeLocationInfo: true,
+			});
 			Linter.#traverse(document, (node) => {
 				const attrs = node.attrs
 					? Object.fromEntries(node.attrs.map((a) => [a.name, a.value]))
@@ -257,7 +263,9 @@ export default class Linter {
 		const globalWriteKeys = Linter.#globalWriteKeys(jsSources);
 
 		for (const { file, source } of htmlSources) {
-			const document = parse5.parse(source, { sourceCodeLocationInfo: true });
+			const document = Markup.parse(file, source, {
+				sourceCodeLocationInfo: true,
+			});
 			Linter.#traverse(document, (node) => {
 				if (node.nodeName !== "template") return;
 				Linter.#traverse(node, (inner) => {
@@ -304,7 +312,9 @@ export default class Linter {
 
 		const actionValues = new Set();
 		for (const { file, source } of htmlSources) {
-			const document = parse5.parse(source, { sourceCodeLocationInfo: true });
+			const document = Markup.parse(file, source, {
+				sourceCodeLocationInfo: true,
+			});
 			Linter.#traverse(document, (node) => {
 				const action = node.attrs?.find((a) => a.name === "data-action");
 				if (!action?.value) return;
@@ -343,13 +353,14 @@ export default class Linter {
 			for (const m of source.matchAll(/\[data-([a-z0-9-]+)/g))
 				consumed.add(m[1]);
 		}
-		for (const { source } of htmlSources) {
+		for (const { file, source } of htmlSources) {
+			const markup = Markup.source(file, source);
 			// Inline <style> blocks ride along in the raw HTML source.
-			for (const m of source.matchAll(/\[data-([a-z0-9-]+)/g))
+			for (const m of markup.matchAll(/\[data-([a-z0-9-]+)/g))
 				consumed.add(m[1]);
-			for (const m of source.matchAll(/data-text=["']([\w-]+)["']/g))
+			for (const m of markup.matchAll(/data-text=["']([\w-]+)["']/g))
 				consumed.add(m[1]);
-			for (const m of source.matchAll(/data-bind=["']([^"']+)["']/g)) {
+			for (const m of markup.matchAll(/data-bind=["']([^"']+)["']/g)) {
 				for (const pair of m[1].split(/\s+/)) {
 					const i = pair.indexOf(":");
 					if (i >= 1) consumed.add(pair.slice(i + 1));
@@ -383,7 +394,9 @@ export default class Linter {
 		const spanPairs = new Set(); // includes data-otm-dynamic spans — they
 		// still satisfy the css→span direction; only the span→css check is waived
 		for (const { file, source } of htmlSources) {
-			const document = parse5.parse(source, { sourceCodeLocationInfo: true });
+			const document = Markup.parse(file, source, {
+				sourceCodeLocationInfo: true,
+			});
 			Linter.#traverse(document, (node) => {
 				for (const attr of node.attrs ?? []) {
 					const m = attr.name.match(/^data-([a-z0-9-]+)-key$/);
@@ -412,7 +425,8 @@ export default class Linter {
 		const spanRefs = [];
 		const refPairs = new Set();
 		for (const { file, source } of styleTexts) {
-			for (const m of source.matchAll(
+			const styleSource = Markup.source(file, source);
+			for (const m of styleSource.matchAll(
 				/\[data-([a-z0-9-]+?)-key=["']?([\w-]+)["']?\]/g,
 			)) {
 				refPairs.add(`${m[1]} ${m[2]}`);
@@ -420,7 +434,7 @@ export default class Linter {
 					group: m[1],
 					value: m[2],
 					file,
-					line: Linter.#lineOf(source, m.index),
+					line: Linter.#lineOf(styleSource, m.index),
 				});
 			}
 		}

package/src/linter/Markup.js

@@ -0,0 +1,14 @@
+import * as parse5 from "parse5";
+
+export default class Markup {
+	static source(file, source) {
+		if (!file.endsWith(".ejs")) return source;
+		return source.replace(/<%[\s\S]*?%>/g, (tag) =>
+			tag.replace(/[^\r\n]/g, " "),
+		);
+	}
+
+	static parse(file, source, options) {
+		return parse5.parse(Markup.source(file, source), options);
+	}
+}

package/src/linter/cli.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import * as parse5 from "parse5";
 import Linter from "./Linter.js";
+import Markup from "./Markup.js";
 
 export default class Cli {
 	static async run(args = []) {
@@ -23,8 +23,8 @@ export default class Cli {
 	static #excludeDirs = new Set(["node_modules", "dist", ".git"]);
 
 	// parse5, not regex — attribute order must not matter.
-	static #findI18nMeta(source) {
-		const doc = parse5.parse(source);
+	static #findI18nMeta(file, source) {
+		const doc = Markup.parse(file, source);
 		let content = null;
 		const walk = (node) => {
 			if (content) return;
@@ -85,7 +85,7 @@ export default class Cli {
 			let availableLocales = null;
 			const dicts = [];
 
-			const metaContent = Cli.#findI18nMeta(source);
+			const metaContent = Cli.#findI18nMeta(file, source);
 			if (metaContent) {
 				const localesDir = path.resolve(
 					path.dirname(file),

package/src/live/Live.js

@@ -131,7 +131,12 @@ export default class Live {
 		let msg;
 		try {
 			msg = JSON.parse(raw);
-		} catch {
+		} catch (cause) {
+			const error = new SyntaxError("otm live: malformed JSON frame", {
+				cause,
+			});
+			if (this.#options.onError) this.#options.onError(error, raw);
+			else console.warn(error, raw);
 			return;
 		}
 		const pending = msg?.req_id != null ? this.#pending.get(msg.req_id) : null;

package/src/live/index.d.ts

@@ -0,0 +1,46 @@
+export interface LiveFrame {
+	[key: string]: unknown;
+	type?: string;
+	data?: unknown;
+	at?: unknown;
+	req_id?: number;
+}
+
+export interface LiveOptions {
+	onMessage?: (type: string | undefined, data: unknown, at: unknown) => void;
+	onError?: (error: SyntaxError, raw: string) => void;
+	onDown?: () => void;
+	onUp?: () => void;
+	signal?: AbortSignal;
+}
+
+export interface LiveChannel {
+	send(frame: LiveFrame): void;
+	request<T extends LiveFrame = LiveFrame>(
+		frame: LiveFrame,
+		options?: { timeoutMs?: number; takeLatest?: boolean },
+	): Promise<T | null>;
+}
+
+export interface SseOptions {
+	types?: string[];
+	onMessage?: (type: string, data: unknown, lastEventId: string) => void;
+	onDown?: () => void;
+	onUp?: () => void;
+	signal?: AbortSignal;
+}
+
+export function backoffDelay(attempt: number, random?: () => number): number;
+export function live(channel: string, options?: LiveOptions): LiveChannel;
+export function live(
+	channel: { fromState: string },
+	options?: LiveOptions,
+): LiveChannel | null;
+export function sse(path: string, options?: SseOptions): object;
+
+declare const api: {
+	live: typeof live;
+	sse: typeof sse;
+};
+
+export default api;

package/src/stylelint/config.d.ts

@@ -0,0 +1,2 @@
+declare const config: object;
+export default config;

package/src/stylelint/plugin.d.ts

@@ -0,0 +1,2 @@
+declare const plugin: object;
+export default plugin;

package/src/test/index.d.ts

@@ -0,0 +1,10 @@
+export interface DOMSetup {
+	document: Document;
+	window: Window;
+	[key: string]: unknown;
+}
+
+export function setupDOM(
+	html?: string,
+	options?: { url?: string; language?: string },
+): DOMSetup;