hyper-html-api 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+Zero-Clause BSD
+=============
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
+DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# hyper-html-api
+
+Self-describing data layer for HTML files — a bidirectional engine that reads structured data out of an HTML page and writes structured data back into it, driven by a single declarative rules tag.
+
+Status: **early development** (Phase 0 — repo bootstrap). API shape and behavior are being ported from `hyperclay/server-lib/data-extractor.js`. See `plans/hyperclay/hyper-html-api/` in the workspace for the full specification.
+
+## Install
+
+```sh
+npm install hyper-html-api
+```
+
+## Rules tag
+
+Pages describe their data layer with a single script tag:
+
+```html
+<script type="application/hyper-html-api" id="hyper-html-api" data-rules-version="1">
+{
+  "title": "h1",
+  "user": { "name": ".user-name", "role": ".user-role" },
+  "products": [".product", { "name": ".name", "price": ".price" }],
+  "tags": ".tag[]"
+}
+</script>
+```
+
+## Browser API
+
+```js
+HyperHtmlApi.engine.extract(root, rules)       // → JSON
+HyperHtmlApi.engine.apply(root, rules, data)   // mutates the DOM
+HyperHtmlApi.engine.findRulesIn(root)          // → { rules, tagNode } | null
+HyperHtmlApi.engine.errors                     // error class refs
+```
+
+## Node API
+
+```js
+import { extract, apply, findRulesIn, errors } from 'hyper-html-api/engine'
+import cheerioAdapter from 'hyper-html-api/cheerio'
+import * as cheerio from 'cheerio'
+
+const $ = cheerio.load(html)
+const { rules } = findRulesIn(cheerioAdapter, $.root())
+const data = extract(cheerioAdapter, $.root(), rules)
+```
+
+## License
+
+0BSD

package/dist/hyper-html-api.min.js

@@ -0,0 +1,2 @@
+var HyperHtmlApi=(()=>{var B=Object.defineProperty;var ce=Object.getOwnPropertyDescriptor;var le=Object.getOwnPropertyNames;var ae=Object.prototype.hasOwnProperty;var ee=(e,t)=>{for(var r in t)B(e,r,{get:t[r],enumerable:!0})},ue=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of le(t))!ae.call(e,n)&&n!==r&&B(e,n,{get:()=>t[n],enumerable:!(o=ce(t,n))||o.enumerable});return e};var de=e=>ue(B({},"__esModule",{value:!0}),e);var Be={};ee(Be,{cms:()=>ie,default:()=>qe,engine:()=>se,upgrade:()=>fe});var C=["textContent","innerText","innerHTML","outerHTML","value","checked","selected","disabled","readOnly","type","tagName","nodeName","nodeType","nodeValue","childElementCount","id","className","classList","href","src","action","baseURI","offsetWidth","offsetHeight","clientWidth","clientHeight","scrollWidth","scrollHeight","dataset","currentSrc","duration","paused","title","documentURI","contentType"],O=new Set(C);var D={};ee(D,{EmptyListInsert:()=>b,MaxRuleDepthExceeded:()=>E,RulesParseError:()=>x,ShapeMismatch:()=>M,UnknownRulesVersion:()=>T,UpgradeAlreadyRegistered:()=>w});var x=class extends Error{constructor(t,r){super(t),this.name="RulesParseError",this.cause=r}},T=class extends Error{constructor(t){super(`unknown rules version: ${t}. Library supports "1".`),this.name="UnknownRulesVersion",this.version=t}},E=class extends Error{constructor(t){super(`rule depth exceeded 20 at path: ${t.join(".")}`),this.name="MaxRuleDepthExceeded",this.path=t}},M=class extends Error{constructor(t){super(`shape mismatch: ${t.length} field(s) failed validation`),this.name="ShapeMismatch",this.mismatches=t}},b=class extends Error{constructor(t){super(`cannot add items to empty list at "${t.join(".")}" \u2014 no sibling to clone as template. Seed the list with a hidden item first.`),this.name="EmptyListInsert",this.path=t}},w=class extends Error{constructor(){super("upgrade transform already registered; only one registration is allowed per page."),this.name="UpgradeAlreadyRegistered"}};var pe=20;function A(e,t,r){return $(e,t,r,{depth:0,path:[]})}function $(e,t,r,o){if(o.depth>pe)throw new E(o.path);if(typeof r=="string")return he(e,t,r);if(Array.isArray(r)){let[n,s]=r;return e.find(t,n).map((i,f)=>$(e,i,s,{depth:o.depth+1,path:[...o.path,f]}))}if(typeof r=="object"&&r!==null){let n={};for(let[s,c]of Object.entries(r))n[s]=$(e,t,c,{depth:o.depth+1,path:[...o.path,s]});return n}return null}function he(e,t,r){if(r.endsWith("[]")){let n=r.slice(0,-2);return e.find(t,n).map(s=>e.text(s))}if(r.startsWith("@"))return te(e,t,r.slice(1));if(r.includes("@")){let[n,s]=r.split("@"),c=n?e.find(t,n):[t];return c.length===0?null:te(e,c[0],s)}if(r===".")return e.text(t);let o=e.find(t,r);return o.length===0?null:e.text(o[0])}function te(e,t,r){if(O.has(r)){let n=e.prop(t,r);return n==null?null:String(n)}let o=e.attr(t,r);return o||null}var ye=.5;function W(e,t,r,o,n,s,c){let i=e.find(t,r);if(n.length===0){i.forEach(d=>e.remove(d));return}if(n.length>i.length&&i.length===0)throw new b(s.path);let a=i.map(d=>me(e,d,o)),u=null;if(i.length>0){u=e.clone(i[0]);let d=e.stripIds(u);d>0&&console.warn(`[hyper-html-api] stripped ${d} id attribute(s) from cloned template at "${s.path.join(".")||"(root)"}"`)}let p=ge(n,a,o),l=e.parent(i[0]),R=Ae(e,l,i[0]),y=new Set,h=n.map((d,m)=>{let S=p[m];if(S>=0)return y.add(S),i[S];let v=e.clone(u);return e.stripIds(v),v});i.forEach((d,m)=>{y.has(m)||e.remove(d)}),y.forEach(d=>e.remove(i[d])),h.forEach((d,m)=>{e.insertAt(l,d,R+m)}),h.forEach((d,m)=>{if(o===null){let S=n[m];e.text(d,S==null?"":String(S))}else c(e,d,o,n[m],{depth:s.depth+1,path:[...s.path,m]})})}function me(e,t,r){return r===null?e.text(t):A(e,t,r)}function ge(e,t,r){let o=new Array(e.length).fill(-1),n=new Set;return e.forEach((s,c)=>{let i=-1,f=-1;t.forEach((a,u)=>{if(n.has(u))return;let p=Ee(s,a,r),l=p===f&&i>=0?Math.abs(u-c)<Math.abs(i-c):!1;(p>f||l)&&(f=p,i=u)}),f>=ye&&(o[c]=i,n.add(i))}),o}function Ee(e,t,r){if(r===null)return e===t?1:0;let o=Object.keys(r||{});if(o.length===0)return 0;let n=0;for(let s of o)JSON.stringify(e?.[s])===JSON.stringify(t?.[s])&&n++;return n/o.length}function Ae(e,t,r){let o=e.children(t);for(let n=0;n<o.length;n++)if(e.sameNode(o[n],r))return n;return-1}var Re=20,re=new Set(["checked","selected","disabled","readOnly","paused"]);function L(e,t,r,o){let n=[];if(F(r,o,[],n),n.length)throw new M(n);j(e,t,r,o,{depth:0,path:[]})}function j(e,t,r,o,n){if(n.depth>Re)throw new E(n.path);if(o!==void 0){if(typeof r=="string")return Se(e,t,r,o,n);if(Array.isArray(r)){let[s,c]=r;return W(e,t,s,c,o,n,j)}if(typeof r=="object"&&r!==null)for(let[s,c]of Object.entries(r))j(e,t,c,o==null?o:o[s],{depth:n.depth+1,path:[...n.path,s]})}}function Se(e,t,r,o,n){if(r.endsWith("[]")){let c=r.slice(0,-2);return W(e,t,c,null,o,n,j)}if(r.startsWith("@"))return ne(e,t,r.slice(1),o);if(r.includes("@")){let[c,i]=r.split("@"),f=c?e.find(t,c):[t];return f.length===0?void 0:ne(e,f[0],i,o)}if(r==="."){e.text(t,o==null?"":String(o));return}let s=e.find(t,r);s.length!==0&&e.text(s[0],o==null?"":String(o))}function ne(e,t,r,o){O.has(r)?e.prop(t,r,xe(r,o)):e.attr(t,r,o==null?"":String(o))}function xe(e,t){return t==null?re.has(e)?!1:"":re.has(e)?!!t:t}function F(e,t,r,o){if(!(t==null||t==="")){if(typeof e=="string"){if(e.endsWith("[]")){Array.isArray(t)?t.forEach((n,s)=>{typeof n=="object"&&n!==null&&o.push({path:N([...r,s]),expected:"scalar",got:I(n)})}):o.push({path:N(r),expected:"array",got:I(t)});return}typeof t=="object"&&o.push({path:N(r),expected:"scalar",got:I(t)});return}if(Array.isArray(e)){if(!Array.isArray(t)){o.push({path:N(r),expected:"array",got:I(t)});return}let n=e[1];t.forEach((s,c)=>F(n,s,[...r,c],o));return}if(typeof e=="object"&&e!==null){if(Array.isArray(t)||typeof t!="object"){o.push({path:N(r),expected:"object",got:I(t)});return}for(let[n,s]of Object.entries(e))F(s,t[n],[...r,n],o)}}}function I(e){return e===null?"null":Array.isArray(e)?"array":typeof e}function N(e){return e.join(".")}function P(e){try{return JSON.parse(e)}catch(t){throw new x(`hyper-html-api script tags require strict JSON. Relaxed JSON (unquoted keys, single quotes, trailing commas) is only supported in the ?data= URL parameter. Original error: ${t.message}`,t)}}function J(e){try{return JSON.parse(e)}catch{}let t={BRACE_OPEN:"{",BRACE_CLOSE:"}",BRACKET_OPEN:"[",BRACKET_CLOSE:"]",COLON:":",COMMA:",",STRING:"STRING",SELECTOR:"SELECTOR",IDENTIFIER:"IDENTIFIER",NUMBER:"NUMBER",BOOLEAN:"BOOLEAN"};function r(n){let s=[],c=0;for(;c<n.length;){let i=n[c];if(/\s/.test(i)){c++;continue}if("{}".includes(i)){s.push({type:i,value:i}),c++;continue}if(i==="["){let p=!1,l=c+1;for(;l<n.length&&/\s/.test(n[l]);)l++;if(l<n.length&&/[a-zA-Z_]/.test(n[l])&&(p=!0),!p){s.push({type:i,value:i}),c++;continue}}if(i==="]"){s.push({type:i,value:i}),c++;continue}if(i===":"){s.push({type:t.COLON,value:i}),c++;continue}if(i===","){s.push({type:t.COMMA,value:i}),c++;continue}if(i==='"'||i==="'"){let p=i,l=c+1;for(;l<n.length&&n[l]!==p;)n[l]==="\\"&&l++,l++;s.push({type:t.STRING,value:n.substring(c+1,l),quoted:!0}),c=l+1;continue}let f=c,a;for(;f<n.length&&!/[{},]/.test(n[f]);)if(n[f]===":"){let p=[":first",":last",":nth-child",":nth-of-type",":first-child",":last-child",":first-of-type",":last-of-type",":only-child",":only-of-type",":hover",":focus",":active",":visited",":disabled",":enabled",":checked",":empty",":root",":target",":not",":before",":after",":nth-last-child",":nth-last-of-type"],l=!1;for(let R of p){let y=R.substring(1);if(n.substring(f+1,f+1+y.length)===y){l=!0,f+=y.length;break}}if(!l)break}else if(n[f]==="["){for(f++;f<n.length&&n[f]!=="]";){if(n[f]==='"'||n[f]==="'"){let p=n[f];for(f++;f<n.length&&n[f]!==p;)n[f]==="\\"&&f++,f++}f++}f<n.length&&n[f]==="]"&&f++}else f++;a=n.substring(c,f);let u=t.IDENTIFIER;/^-?\d+(\.\d+)?$/.test(a)?u=t.NUMBER:a==="true"||a==="false"||a==="null"?u=t.BOOLEAN:/^[.#@\[]|[.#@\[]| /.test(a)&&(u=t.SELECTOR),s.push({type:u,value:a,quoted:!1}),c=f}return s}function o(n){let s="";for(let c=0;c<n.length;c++){let i=n[c];if("{}".includes(i.type)||"[]".includes(i.type)){s+=i.value;continue}if(i.type===t.COLON){s+=i.value;continue}if(i.type===t.COMMA){s+=i.value;continue}if(i.type===t.STRING&&i.quoted){s+=`"${i.value}"`;continue}if(i.type===t.NUMBER||i.type===t.BOOLEAN){s+=i.value;continue}if(i.type===t.SELECTOR||i.type===t.IDENTIFIER){s+=`"${i.value}"`;continue}s+=`"${i.value}"`}return s}try{let n=r(e),s=o(n);return JSON.parse(s)}catch(n){throw new x("Invalid extraction rules syntax: "+n.message,n)}}var Oe="hyper-html-api",Te="1";function _(e,t){let r=e.find(t,`script#${Oe}`,{includeRulesTag:!0});if(r.length===0)return null;let o=r[0],n=e.attr(o,"data-rules-version");if(n!==Te)throw new T(n);let s=e.text(o);return{rules:P(s),tagNode:o}}var G=null;function V(e){if(typeof e!="function")throw new TypeError("registerUpgrade expects a function (v1Data) => v2Data");if(G)throw new w;G=e}function H(){return G}function U(e,t){let r={carriedOver:0,discarded:0,listItems:0},o=Y(t,e,r);return X(t,e,r),{data:o,summary:r}}function Y(e,t,r){if(typeof e=="string")return e.endsWith("[]")?Array.isArray(t)?(r.listItems+=t.length,r.carriedOver+=t.length,t):void 0:t==null?void 0:(r.carriedOver++,t);if(Array.isArray(e)){let[,o]=e;return Array.isArray(t)?(r.listItems+=t.length,t.map(n=>Y(o,n,r))):void 0}if(typeof e=="object"&&e!==null){let o={};for(let[n,s]of Object.entries(e)){let c=Y(s,t?.[n],r);c!==void 0&&(o[n]=c)}return o}}function X(e,t,r){if(t!=null){if(typeof e=="object"&&e!==null&&!Array.isArray(e)){if(typeof t!="object"||Array.isArray(t))return;let o=new Set(Object.keys(e));for(let n of Object.keys(t))o.has(n)?X(e[n],t[n],r):r.discarded+=k(t[n]);return}if(Array.isArray(e)&&Array.isArray(t)){let o=e[1];t.forEach(n=>X(o,n,r));return}typeof e=="string"&&!e.endsWith("[]")&&typeof t=="object"&&t!==null&&(r.discarded+=k(t))}}function k(e){return e==null?0:Array.isArray(e)?e.reduce((t,r)=>t+k(r),0):typeof e=="object"?Object.values(e).reduce((t,r)=>t+k(r),0):1}async function z({sourceUrl:e,v1Data:t,v1Version:r=null,parent:o=typeof window<"u"?window:null,timeoutMs:n=15e3,hidden:s=!0}={}){if(!o)throw new Error("upgrade.run requires a window context");if(!e)throw new Error("upgrade.run requires sourceUrl");let c=be(e,o.location.origin),i=new URL(c,o.location.href).origin,f=o.document.createElement("iframe");s&&(f.style.cssText="position:absolute;left:-9999px;top:-9999px;width:1px;height:1px;border:0;"),f.setAttribute("aria-hidden","true"),f.src=c,o.document.body.appendChild(f);let a=()=>{};try{return await new Promise((u,p)=>{let l=setTimeout(()=>{p(new Error(`upgrade.run: helper iframe timed out after ${n}ms`))},n),R=y=>{if(y.source!==f.contentWindow||y.origin!==i)return;let h=y.data;if(!(!h||typeof h!="object")){if(h.type==="hha:upgrade-ready"){f.contentWindow.postMessage({type:"hha:upgrade-data",v1Data:t,v1Version:r},i);return}if(h.type==="hha:upgrade-result"){clearTimeout(l),u({html:h.html,summary:h.summary});return}if(h.type==="hha:upgrade-error"){clearTimeout(l);let d=new Error(h.message||"helper error");d.name=h.name||"UpgradeHelperError",p(d);return}}};o.addEventListener("message",R),a=()=>{o.removeEventListener("message",R),clearTimeout(l),f.parentNode&&f.parentNode.removeChild(f)}})}finally{a()}}function be(e,t){let r=new URL(e,typeof location<"u"?location.href:void 0);return r.searchParams.set("_hyperHtmlApi","upgrade-helper"),r.searchParams.set("parentOrigin",t),r.toString()}var we="hyper-html-api";function Ie(e){return e&&e.nodeType===1&&e.id===we&&e.tagName==="SCRIPT"}function Ne(e){return e?(e.nodeType===9||e.nodeType===11,e):null}var Le={find(e,t,r={}){let o=Ne(e);if(!o||!o.querySelectorAll)return[];let n=Array.from(o.querySelectorAll(t));return r.includeRulesTag?n:n.filter(s=>!Ie(s))},parent(e){return e?e.parentElement:null},children(e){return e?Array.from(e.children):[]},text(e,t){if(t===void 0)return(e.textContent||"").trim();e.textContent=t},attr(e,t,r){if(r===void 0)return e.hasAttribute&&e.hasAttribute(t)?e.getAttribute(t):null;e.setAttribute(t,r)},prop(e,t,r){if(r===void 0){let o=e?e[t]:void 0;return o!==void 0?o:null}e[t]=r},clone(e){return e.cloneNode(!0)},insertAt(e,t,r){let o=e.children[r]||null;e.insertBefore(t,o)},remove(e){e&&e.parentNode&&e.parentNode.removeChild(e)},stripIds(e){let t=0;return e.id&&(e.removeAttribute("id"),t++),(e.querySelectorAll?e.querySelectorAll("[id]"):[]).forEach(o=>{o.removeAttribute("id"),t++}),t},sameNode(e,t){return e===t}},g=Le;var Pe="_hyperHtmlApi",_e="upgrade-helper",Ue="parentOrigin";function q(e=typeof location<"u"?location:null){if(!e)return!1;try{return new URLSearchParams(e.search).get(Pe)===_e}catch{return!1}}function oe(e=typeof location<"u"?location:null){return e?new URLSearchParams(e.search).get(Ue):null}function Z({win:e,doc:t,parentOrigin:r}={}){if(e=e||(typeof window<"u"?window:null),t=t||(typeof document<"u"?document:null),!e||!t||(r=r||oe(e.location),!r))return;let o=()=>Ce({win:e,doc:t,parentOrigin:r});t.readyState==="loading"?t.addEventListener("DOMContentLoaded",o,{once:!0}):o()}function Ce({win:e,doc:t,parentOrigin:r}){let o;try{o=_(g,t.body)}catch(f){return K(e,r,f)}if(!o)return K(e,r,new Error("helper-mode: no rules tag in v2 document"));let n=o.rules,s=je(t,"hyper-version"),c=!!H(),i=f=>{if(f.source!==e.parent||f.origin!==r)return;let a=f.data;if(!(!a||a.type!=="hha:upgrade-data")){e.removeEventListener("message",i);try{let u=De({doc:t,rules:n,v1Data:a.v1Data});e.parent.postMessage({type:"hha:upgrade-result",html:u.html,summary:u.summary},r)}catch(u){K(e,r,u)}}};e.addEventListener("message",i),e.parent.postMessage({type:"hha:upgrade-ready",rules:n,version:s,hasTransform:c},r)}function De({doc:e,rules:t,v1Data:r}){let o=H(),n=r,s=!1;o&&(n=o(r),s=!0);let{data:c,summary:i}=U(n,t);L(g,e.body,t,c);let f=A(g,e.body,t);return{html:`<!DOCTYPE html>
+`+e.documentElement.outerHTML,summary:{...i,transformApplied:s,appliedFieldCount:Q(f)}}}function K(e,t,r){e.parent.postMessage({type:"hha:upgrade-error",name:r?.name||"Error",message:r?.message||String(r)},t)}function je(e,t){let r=e.querySelector(`meta[name="${t}"]`);return r?r.getAttribute("content"):null}function Q(e){return e==null?0:Array.isArray(e)?e.reduce((t,r)=>t+Q(r),0):typeof e=="object"?Object.values(e).reduce((t,r)=>t+Q(r),0):1}var se={extract:(e,t)=>A(g,e,t),apply:(e,t,r)=>L(g,e,t,r),findRulesIn:e=>_(g,e),parseStrict:P,parseRelaxed:J,errors:D,DOM_PROPERTIES:C},ie={},fe={registerUpgrade:V,run:z,shapeMatch:U,isHelperMode:q};typeof window<"u"&&q(window.location)&&Z({win:window,doc:document});var ke={engine:se,cms:ie,upgrade:fe},qe=ke;return de(Be);})();

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "hyper-html-api",
+  "description": "self-describing data layer for HTML files — extract, apply, CMS, upgrade",
+  "keywords": [
+    "HTML",
+    "DOM",
+    "data",
+    "extract",
+    "apply",
+    "CMS"
+  ],
+  "version": "0.1.0",
+  "homepage": "https://github.com/panphora/hyper-html-api",
+  "bugs": {
+    "url": "https://github.com/panphora/hyper-html-api/issues"
+  },
+  "license": "0BSD",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "src/**/*.js",
+    "dist/*.js"
+  ],
+  "main": "src/hyper-html-api.js",
+  "module": "src/hyper-html-api.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/hyper-html-api.js",
+    "./engine": "./src/engine/index.js",
+    "./cheerio": "./src/adapters/cheerio.js",
+    "./dom": "./src/adapters/dom.js"
+  },
+  "scripts": {
+    "build": "npx esbuild src/hyper-html-api.js --bundle --minify --format=iife --global-name=HyperHtmlApi --outfile=dist/hyper-html-api.min.js",
+    "prepublishOnly": "npm run build",
+    "copy-to-hyperclayjs": "npm run build && node scripts/copy-to-hyperclayjs.js",
+    "demo": "http-server . -p 5693 -c-1 -o /demo/",
+    "test": "web-test-runner",
+    "test:debug": "web-test-runner --manual --open",
+    "test:chrome": "web-test-runner --playwright --browsers chromium",
+    "test:firefox": "web-test-runner --concurrency 1 --playwright --browsers firefox",
+    "test:webkit": "web-test-runner --playwright --browsers webkit",
+    "test:all": "web-test-runner --concurrency 1 --playwright --browsers chromium firefox webkit",
+    "test:node": "node --test 'test-node/**/*.test.js'",
+    "test:ci": "npm run test:node && npm run test:all -- --fail-only && node test/lib/ensure-full-coverage.js",
+    "test:coverage": "npm run test:chrome && node test/lib/ensure-full-coverage.js",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panphora/hyper-html-api.git"
+  },
+  "devDependencies": {
+    "@web/test-runner": "^0.20.0",
+    "@web/test-runner-playwright": "^0.11.0",
+    "chai": "^4.3.6",
+    "chai-dom": "^1.11.0",
+    "cheerio": "^1.0.0-rc.12",
+    "esbuild": "^0.24.0",
+    "http-server": "^14.1.1",
+    "jsdom": "^29.0.2",
+    "lcov-parse": "^1.0.0",
+    "mocha": "^11.0.1",
+    "prettier": "^3.4.2",
+    "sinon": "^9.2.4"
+  }
+}

package/src/adapters/cheerio.js

@@ -0,0 +1,93 @@
+const RULES_TAG_ID = 'hyper-html-api'
+
+function isRulesTag(node) {
+  if (!node || !node.attr) return false
+  if (node.attr('id') !== RULES_TAG_ID) return false
+  const tag = node.prop ? node.prop('tagName') : ''
+  return String(tag || '').toUpperCase() === 'SCRIPT'
+}
+
+function toWrappers(cheerioSet) {
+  const out = []
+  for (let i = 0; i < cheerioSet.length; i++) out.push(cheerioSet.eq(i))
+  return out
+}
+
+const cheerioAdapter = {
+  find(ctx, selector, opts = {}) {
+    if (!ctx || !ctx.find) return []
+    const matches = toWrappers(ctx.find(selector))
+    if (opts.includeRulesTag) return matches
+    return matches.filter((n) => !isRulesTag(n))
+  },
+
+  parent(node) {
+    if (!node || !node.parent) return null
+    const p = node.parent()
+    return p && p.length ? p : null
+  },
+
+  children(node) {
+    if (!node || !node.children) return []
+    return toWrappers(node.children())
+  },
+
+  text(node, value) {
+    if (value === undefined) return node.text().trim()
+    node.text(value)
+  },
+
+  attr(node, name, value) {
+    if (value === undefined) {
+      const v = node.attr(name)
+      return v !== undefined ? v : null
+    }
+    node.attr(name, value)
+  },
+
+  prop(node, name, value) {
+    if (value === undefined) {
+      const v = node.prop(name)
+      return v !== undefined ? v : null
+    }
+    node.prop(name, value)
+  },
+
+  clone(node) {
+    return node.clone()
+  },
+
+  insertAt(parent, node, index) {
+    const siblings = parent.children()
+    if (index >= siblings.length) parent.append(node)
+    else siblings.eq(index).before(node)
+  },
+
+  remove(node) {
+    if (node) node.remove()
+  },
+
+  stripIds(node) {
+    let count = 0
+    if (node.attr('id')) {
+      node.removeAttr('id')
+      count++
+    }
+    node.find('[id]').each(function () {
+      if (this.attribs && this.attribs.id !== undefined) {
+        delete this.attribs.id
+        count++
+      }
+    })
+    return count
+  },
+
+  sameNode(a, b) {
+    if (!a || !b) return false
+    const aEl = a[0]
+    const bEl = b[0]
+    return !!aEl && aEl === bEl
+  },
+}
+
+export default cheerioAdapter

package/src/adapters/dom.js

@@ -0,0 +1,83 @@
+const RULES_TAG_ID = 'hyper-html-api'
+
+function isRulesTag(node) {
+  return node && node.nodeType === 1 && node.id === RULES_TAG_ID && node.tagName === 'SCRIPT'
+}
+
+function resolveSearchRoot(ctx) {
+  if (!ctx) return null
+  if (ctx.nodeType === 9) return ctx
+  if (ctx.nodeType === 11) return ctx
+  return ctx
+}
+
+const dom = {
+  find(ctx, selector, opts = {}) {
+    const root = resolveSearchRoot(ctx)
+    if (!root || !root.querySelectorAll) return []
+    const all = Array.from(root.querySelectorAll(selector))
+    if (opts.includeRulesTag) return all
+    return all.filter((n) => !isRulesTag(n))
+  },
+
+  parent(node) {
+    return node ? node.parentElement : null
+  },
+
+  children(node) {
+    return node ? Array.from(node.children) : []
+  },
+
+  text(node, value) {
+    if (value === undefined) return (node.textContent || '').trim()
+    node.textContent = value
+  },
+
+  attr(node, name, value) {
+    if (value === undefined) {
+      return node.hasAttribute && node.hasAttribute(name) ? node.getAttribute(name) : null
+    }
+    node.setAttribute(name, value)
+  },
+
+  prop(node, name, value) {
+    if (value === undefined) {
+      const v = node ? node[name] : undefined
+      return v !== undefined ? v : null
+    }
+    node[name] = value
+  },
+
+  clone(node) {
+    return node.cloneNode(true)
+  },
+
+  insertAt(parent, node, index) {
+    const ref = parent.children[index] || null
+    parent.insertBefore(node, ref)
+  },
+
+  remove(node) {
+    if (node && node.parentNode) node.parentNode.removeChild(node)
+  },
+
+  stripIds(node) {
+    let count = 0
+    if (node.id) {
+      node.removeAttribute('id')
+      count++
+    }
+    const inner = node.querySelectorAll ? node.querySelectorAll('[id]') : []
+    inner.forEach((el) => {
+      el.removeAttribute('id')
+      count++
+    })
+    return count
+  },
+
+  sameNode(a, b) {
+    return a === b
+  },
+}
+
+export default dom

package/src/adapters/index.js

@@ -0,0 +1,2 @@
+export { default as dom } from './dom.js'
+export { default as cheerio } from './cheerio.js'

package/src/engine/apply.js

@@ -0,0 +1,139 @@
+import { DOM_PROPERTIES_SET } from './dom-properties.js'
+import { MaxRuleDepthExceeded, ShapeMismatch } from './errors.js'
+import { listDiff } from './diff.js'
+
+const MAX_DEPTH = 20
+
+const BOOLEAN_PROPS = new Set(['checked', 'selected', 'disabled', 'readOnly', 'paused'])
+
+export function apply(adapter, root, rules, data) {
+  const mismatches = []
+  validateShape(rules, data, [], mismatches)
+  if (mismatches.length) throw new ShapeMismatch(mismatches)
+
+  applyAt(adapter, root, rules, data, { depth: 0, path: [] })
+}
+
+export function applyAt(adapter, ctx, rule, value, trace) {
+  if (trace.depth > MAX_DEPTH) throw new MaxRuleDepthExceeded(trace.path)
+  if (value === undefined) return
+
+  if (typeof rule === 'string') return applyScalar(adapter, ctx, rule, value, trace)
+
+  if (Array.isArray(rule)) {
+    const [selector, shape] = rule
+    return listDiff(adapter, ctx, selector, shape, value, trace, applyAt)
+  }
+
+  if (typeof rule === 'object' && rule !== null) {
+    for (const [key, sub] of Object.entries(rule)) {
+      applyAt(
+        adapter,
+        ctx,
+        sub,
+        value == null ? value : value[key],
+        { depth: trace.depth + 1, path: [...trace.path, key] },
+      )
+    }
+  }
+}
+
+function applyScalar(adapter, ctx, rule, value, trace) {
+  if (rule.endsWith('[]')) {
+    const selector = rule.slice(0, -2)
+    return listDiff(adapter, ctx, selector, null, value, trace, applyAt)
+  }
+
+  if (rule.startsWith('@')) {
+    return writePropOrAttr(adapter, ctx, rule.slice(1), value)
+  }
+
+  if (rule.includes('@')) {
+    const [selector, name] = rule.split('@')
+    const matches = selector ? adapter.find(ctx, selector) : [ctx]
+    if (matches.length === 0) return
+    return writePropOrAttr(adapter, matches[0], name, value)
+  }
+
+  if (rule === '.') {
+    adapter.text(ctx, value == null ? '' : String(value))
+    return
+  }
+
+  const matches = adapter.find(ctx, rule)
+  if (matches.length === 0) return
+  adapter.text(matches[0], value == null ? '' : String(value))
+}
+
+function writePropOrAttr(adapter, node, name, value) {
+  if (DOM_PROPERTIES_SET.has(name)) {
+    adapter.prop(node, name, coercePropValue(name, value))
+  } else {
+    adapter.attr(node, name, value == null ? '' : String(value))
+  }
+}
+
+function coercePropValue(name, value) {
+  if (value === null || value === undefined) {
+    return BOOLEAN_PROPS.has(name) ? false : ''
+  }
+  if (BOOLEAN_PROPS.has(name)) return Boolean(value)
+  return value
+}
+
+function validateShape(rule, value, path, mismatches) {
+  if (value === undefined || value === null || value === '') return
+
+  if (typeof rule === 'string') {
+    if (rule.endsWith('[]')) {
+      if (!Array.isArray(value)) {
+        mismatches.push({ path: pathStr(path), expected: 'array', got: typeofX(value) })
+      } else {
+        value.forEach((v, i) => {
+          if (typeof v === 'object' && v !== null) {
+            mismatches.push({
+              path: pathStr([...path, i]),
+              expected: 'scalar',
+              got: typeofX(v),
+            })
+          }
+        })
+      }
+      return
+    }
+    if (typeof value === 'object') {
+      mismatches.push({ path: pathStr(path), expected: 'scalar', got: typeofX(value) })
+    }
+    return
+  }
+
+  if (Array.isArray(rule)) {
+    if (!Array.isArray(value)) {
+      mismatches.push({ path: pathStr(path), expected: 'array', got: typeofX(value) })
+      return
+    }
+    const shape = rule[1]
+    value.forEach((item, i) => validateShape(shape, item, [...path, i], mismatches))
+    return
+  }
+
+  if (typeof rule === 'object' && rule !== null) {
+    if (Array.isArray(value) || typeof value !== 'object') {
+      mismatches.push({ path: pathStr(path), expected: 'object', got: typeofX(value) })
+      return
+    }
+    for (const [k, sub] of Object.entries(rule)) {
+      validateShape(sub, value[k], [...path, k], mismatches)
+    }
+  }
+}
+
+function typeofX(v) {
+  if (v === null) return 'null'
+  if (Array.isArray(v)) return 'array'
+  return typeof v
+}
+
+function pathStr(path) {
+  return path.join('.')
+}

package/src/engine/diff.js

@@ -0,0 +1,129 @@
+import { EmptyListInsert } from './errors.js'
+import { extract } from './extract.js'
+
+const SIMILARITY_THRESHOLD = 0.5
+
+/**
+ * Reconcile `newItems` (array of incoming items) into the DOM subtree matched
+ * by `parentCtx.find(selector)`. `shape` is null for scalar lists (items are
+ * strings) or the rule shape for object lists.
+ *
+ * applyItem is passed in (normally `applyAt` from apply.js) to avoid a
+ * circular import; object-list items use it to recursively apply their shape.
+ */
+export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, applyItem) {
+  const oldNodes = adapter.find(parentCtx, selector)
+
+  if (newItems.length === 0) {
+    oldNodes.forEach((n) => adapter.remove(n))
+    return
+  }
+
+  const needsTemplate = newItems.length > oldNodes.length
+  if (needsTemplate && oldNodes.length === 0) throw new EmptyListInsert(trace.path)
+
+  const oldValues = oldNodes.map((n) => extractItem(adapter, n, shape))
+
+  let template = null
+  if (oldNodes.length > 0) {
+    template = adapter.clone(oldNodes[0])
+    const stripped = adapter.stripIds(template)
+    if (stripped > 0) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[hyper-html-api] stripped ${stripped} id attribute(s) from cloned template at "${trace.path.join('.') || '(root)'}"`,
+      )
+    }
+  }
+
+  const matches = greedyMatch(newItems, oldValues, shape)
+
+  const parent = adapter.parent(oldNodes[0])
+  const anchorIdx = indexInParent(adapter, parent, oldNodes[0])
+
+  const used = new Set()
+  const finalNodes = newItems.map((_, i) => {
+    const oldIdx = matches[i]
+    if (oldIdx >= 0) {
+      used.add(oldIdx)
+      return oldNodes[oldIdx]
+    }
+    const cloned = adapter.clone(template)
+    adapter.stripIds(cloned)
+    return cloned
+  })
+
+  oldNodes.forEach((n, i) => {
+    if (!used.has(i)) adapter.remove(n)
+  })
+
+  used.forEach((i) => adapter.remove(oldNodes[i]))
+
+  finalNodes.forEach((node, i) => {
+    adapter.insertAt(parent, node, anchorIdx + i)
+  })
+
+  finalNodes.forEach((node, i) => {
+    if (shape === null) {
+      const v = newItems[i]
+      adapter.text(node, v == null ? '' : String(v))
+    } else {
+      applyItem(adapter, node, shape, newItems[i], {
+        depth: trace.depth + 1,
+        path: [...trace.path, i],
+      })
+    }
+  })
+}
+
+function extractItem(adapter, node, shape) {
+  if (shape === null) return adapter.text(node)
+  return extract(adapter, node, shape)
+}
+
+function greedyMatch(newItems, oldValues, shape) {
+  const matches = new Array(newItems.length).fill(-1)
+  const taken = new Set()
+  newItems.forEach((newItem, i) => {
+    let bestIdx = -1
+    let bestScore = -1
+    oldValues.forEach((oldVal, j) => {
+      if (taken.has(j)) return
+      const score = similarity(newItem, oldVal, shape)
+      const closerIdx =
+        score === bestScore && bestIdx >= 0
+          ? Math.abs(j - i) < Math.abs(bestIdx - i)
+          : false
+      if (score > bestScore || closerIdx) {
+        bestScore = score
+        bestIdx = j
+      }
+    })
+    if (bestScore >= SIMILARITY_THRESHOLD) {
+      matches[i] = bestIdx
+      taken.add(bestIdx)
+    }
+  })
+  return matches
+}
+
+function similarity(a, b, shape) {
+  if (shape === null) return a === b ? 1 : 0
+  const fields = Object.keys(shape || {})
+  if (fields.length === 0) return 0
+  let equal = 0
+  for (const f of fields) {
+    if (JSON.stringify(a == null ? undefined : a[f]) === JSON.stringify(b == null ? undefined : b[f])) {
+      equal++
+    }
+  }
+  return equal / fields.length
+}
+
+function indexInParent(adapter, parent, targetNode) {
+  const siblings = adapter.children(parent)
+  for (let i = 0; i < siblings.length; i++) {
+    if (adapter.sameNode(siblings[i], targetNode)) return i
+  }
+  return -1
+}

package/src/engine/dom-properties.js

@@ -0,0 +1,52 @@
+/**
+ * Names that are read/written via the DOM/cheerio .prop() interface rather
+ * than .attr(). Copied verbatim from hyperclay/server-lib/data-extractor.js
+ * so the new engine preserves byte-identical output.
+ */
+export const DOM_PROPERTIES = [
+  'textContent',
+  'innerText',
+  'innerHTML',
+  'outerHTML',
+
+  'value',
+  'checked',
+  'selected',
+  'disabled',
+  'readOnly',
+  'type',
+
+  'tagName',
+  'nodeName',
+  'nodeType',
+  'nodeValue',
+  'childElementCount',
+
+  'id',
+  'className',
+  'classList',
+
+  'href',
+  'src',
+  'action',
+  'baseURI',
+
+  'offsetWidth',
+  'offsetHeight',
+  'clientWidth',
+  'clientHeight',
+  'scrollWidth',
+  'scrollHeight',
+
+  'dataset',
+
+  'currentSrc',
+  'duration',
+  'paused',
+
+  'title',
+  'documentURI',
+  'contentType',
+]
+
+export const DOM_PROPERTIES_SET = new Set(DOM_PROPERTIES)