hyper-html-api 0.8.0 → 0.9.0

package/README.md

@@ -48,6 +48,16 @@ extracts data and `set(data)` writes it back. Token resolution is
 document-scoped, so a tag mounted in `<head>` is found even when `bind` is given
 a body or form element; `get()`/`set()` stay scoped to that element.
 
+DOM bound operations exclude `no-data` and `editor-ui` regions by default.
+Both bare attributes and `clay` tokens work, and the exclusion is inherited by
+descendants. The filtered structure is shared by selectors, text and HTML
+reads, cloning, row matching, and insertion coordinates. Writes still update
+the corresponding live authored nodes. Pass `{ exclude: '.selector' }` to add a
+consumer exclusion, or `{ exclude: null }` for an explicit raw view such as a
+CMS reading its own form controls. The generic engine remains adapter neutral.
+The Cheerio adapter rejects semantic `exclude` options because it does not yet
+implement the same structural contract.
+
 ## Upgrade
 
 A page that was copied from a template can pull in the template's newer
@@ -120,6 +130,34 @@ const { rules } = findRulesIn(cheerioAdapter, $.root(), 'api')
 const data = extract(cheerioAdapter, $.root(), rules)
 ```
 
+### Writing content back
+
+`writeDocument` applies JSON to a document's source through its own rules tag, and
+returns the new source. It is the write half of a local data API: hyperclay-local's
+`POST /_/api/<file>` and HTML Clay's Go port both follow it, pinned by the `face: write`
+conformance cases.
+
+```js
+import { writeDocument } from 'hyper-html-api/write'
+import * as cheerio from 'cheerio'
+
+const { html, changed, spliced } = writeDocument(cheerio.load, src, { title: 'Groceries' })
+```
+
+- **Content only.** Every write goes through the policy in `conformance/write-policy.json`.
+  Text is written as text. A write refused by the policy (script and style targets,
+  `on*` handlers, `javascript:`/`vbscript:`/`data:` URLs, `@innerHTML`, `@outerHTML`, the
+  save and region markers) throws `WriteRefused`, which lists every refusal. Nothing is
+  written.
+- **Strict keys.** An unknown key or a rule whose selector matches nothing throws
+  `WriteRejected` before anything is applied. The document must have a rules tag for the
+  token (default `api`), or `NoRulesTag` is thrown.
+- **Byte-preserving.** Only the elements that changed are re-serialized and spliced into
+  the original source. The result is verified by reparsing, and when that proof fails the
+  whole document is rendered instead (`spliced: false`). A body that changes nothing
+  returns the source untouched with `changed: false`.
+- `no-data` and `editor-ui` regions are invisible to writes, as they are to reads.
+
 ## License
 
 MIT-0 (MIT No Attribution).

package/conformance/MANIFEST.json

@@ -1,6 +1,6 @@
 {
-  "engine": "0.6.0",
+  "engine": "0.8.1",
   "cheerio": "1.2.0",
-  "cases": 33,
+  "cases": 71,
   "note": "Versions the expectations were generated against. Parity means parity with THIS pair; regenerate deliberately, never as a side effect of an install."
 }

package/conformance/cases/no-data-list-skipped.expected.json

@@ -0,0 +1,6 @@
+{
+  "items": [
+    "A",
+    "B"
+  ]
+}

package/conformance/cases/no-data-list-skipped.html

@@ -0,0 +1 @@
+<ul><li editor-ui>Add</li><li>A</li><li>B</li></ul>

package/conformance/cases/no-data-list-skipped.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: query
+expect: ok
+note: editor-ui rows are not data, so find() skips them.

package/conformance/cases/no-data-list-skipped.parsed.json

@@ -0,0 +1,3 @@
+{
+  "items": "li[]"
+}

package/conformance/cases/no-data-list-skipped.rules

@@ -0,0 +1 @@
+{items:"li[]"}

package/conformance/cases/no-data-text-projected.expected.json

@@ -0,0 +1,3 @@
+{
+  "t": "Hi there"
+}

package/conformance/cases/no-data-text-projected.html

@@ -0,0 +1 @@
+<p id="x">Hi <span no-data>secret</span>there</p>

package/conformance/cases/no-data-text-projected.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: query
+expect: ok
+note: text reads project out no-data descendants.

package/conformance/cases/no-data-text-projected.parsed.json

@@ -0,0 +1,3 @@
+{
+  "t": "#x"
+}

package/conformance/cases/no-data-text-projected.rules

@@ -0,0 +1 @@
+{t:"#x"}

package/conformance/cases/props-type-is-attribute.expected.json

@@ -0,0 +1,5 @@
+{
+  "input": "text",
+  "script": null,
+  "style": null
+}

package/conformance/cases/props-type-is-attribute.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: query
+expect: ok
+note: "@type" reads the type attribute, matching HTML Clay. Elements with no type attribute read as null.

package/conformance/cases/write-attr-app-scheme.after.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{h:"#a@href"}</script><a id="a" href="obsidian://open?vault=x">x</a>

package/conformance/cases/write-attr-app-scheme.after.json

@@ -0,0 +1,3 @@
+{
+  "h": "obsidian://open?vault=x"
+}

package/conformance/cases/write-attr-app-scheme.data.json

@@ -0,0 +1 @@
+{"h":"obsidian://open?vault=x"}

package/conformance/cases/write-attr-app-scheme.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{h:"#a@href"}</script><a id=a href="/">x</a>

package/conformance/cases/write-attr-app-scheme.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: A custom app scheme is allowed; only javascript/vbscript/data are refused.

package/conformance/cases/write-attr-app-scheme.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-attr-href.after.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{h:"#a@href"}</script><a id="a" href="https://example.com/?a=1&amp;b=2">x</a>

package/conformance/cases/write-attr-href.after.json

@@ -0,0 +1,3 @@
+{
+  "h": "https://example.com/?a=1&b=2"
+}

package/conformance/cases/write-attr-href.data.json

@@ -0,0 +1 @@
+{"h":"https://example.com/?a=1&b=2"}

package/conformance/cases/write-attr-href.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{h:"#a@href"}</script><a id=a href="/">x</a>

package/conformance/cases/write-attr-href.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: Attribute write: an absolute https URL passes the scheme check.

package/conformance/cases/write-attr-href.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-checked-false.after.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{d:"#c@checked"}</script><input id="c" type="checkbox">

package/conformance/cases/write-checked-false.after.json

@@ -0,0 +1,3 @@
+{
+  "d": "false"
+}

package/conformance/cases/write-checked-false.data.json

@@ -0,0 +1 @@
+{"d":false}

package/conformance/cases/write-checked-false.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{d:"#c@checked"}</script><input id=c type=checkbox checked>

package/conformance/cases/write-checked-false.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: Boolean property write clears the checked attribute.

package/conformance/cases/write-checked-false.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-checked-true.after.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{d:"#c@checked"}</script><input id="c" type="checkbox" checked="">

package/conformance/cases/write-checked-true.after.json

@@ -0,0 +1,3 @@
+{
+  "d": "true"
+}

package/conformance/cases/write-checked-true.data.json

@@ -0,0 +1 @@
+{"d":true}

package/conformance/cases/write-checked-true.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{d:"#c@checked"}</script><input id=c type=checkbox>

package/conformance/cases/write-checked-true.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: Boolean property write sets the checked attribute.

package/conformance/cases/write-checked-true.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-crlf-multi.after.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang=en>
+<head><script data-rules-name="api" data-rules-version="1">{title:"h1",link:"#a@href",items:"li[]"}</script></head>
+<body>
+<h1 class="x">World</h1>
+<p>&copy; 2026<br/></p>
+<a id="a" href="/next">x</a>
+<ul>
+  <li>A</li>
+<li>B</li></ul>
+</body>
+</html>

package/conformance/cases/write-crlf-multi.after.json

@@ -0,0 +1,8 @@
+{
+  "title": "World",
+  "link": "/next",
+  "items": [
+    "A",
+    "B"
+  ]
+}

package/conformance/cases/write-crlf-multi.data.json

@@ -0,0 +1 @@
+{"title":"World","link":"/next","items":["A","B"]}

package/conformance/cases/write-crlf-multi.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang=en>
+<head><script data-rules-name="api" data-rules-version="1">{title:"h1",link:"#a@href",items:"li[]"}</script></head>
+<body>
+<h1 class='x'>Hello</h1>
+<p>&copy; 2026<br/></p>
+<a id=a href="/">x</a>
+<ul>
+  <li>A</li>
+</ul>
+</body>
+</html>

package/conformance/cases/write-crlf-multi.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: Three writes at once across a CRLF document: text, an attribute and a list grow.

package/conformance/cases/write-crlf-multi.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-fallback-implied.after.html

@@ -0,0 +1 @@
+<html lang="en"><head><script data-rules-name="api" data-rules-version="1">{l:"html@lang"}</script></head><body><p>x</p></body></html>

package/conformance/cases/write-fallback-implied.after.json

@@ -0,0 +1,3 @@
+{
+  "l": "en"
+}

package/conformance/cases/write-fallback-implied.data.json

@@ -0,0 +1 @@
+{"l":"en"}

package/conformance/cases/write-fallback-implied.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{l:"html@lang"}</script><p>x</p>

package/conformance/cases/write-fallback-implied.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: Writing the root element forces the whole-document render: spliced is false.

package/conformance/cases/write-fallback-implied.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": false
+}

package/conformance/cases/write-flatten.after.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{t:"#l"}</script><li id="l">Buy bread</li>

package/conformance/cases/write-flatten.after.json

@@ -0,0 +1,3 @@
+{
+  "t": "Buy bread"
+}

package/conformance/cases/write-flatten.data.json

@@ -0,0 +1 @@
+{"t":"Buy bread"}

package/conformance/cases/write-flatten.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{t:"#l"}</script><li id=l><input type=checkbox> Buy milk</li>

package/conformance/cases/write-flatten.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: A text write into an element with mixed content flattens its children to one text node.

package/conformance/cases/write-flatten.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-list-empty-no-seed.data.json

@@ -0,0 +1 @@
+{"items":["A"]}

package/conformance/cases/write-list-empty-no-seed.error.json

@@ -0,0 +1,8 @@
+{
+  "type": "EmptyListInsert",
+  "message": "cannot add items to empty list at \"items\" — no sibling to clone as template. Seed the list with a hidden item first.",
+  "status": 400,
+  "details": [
+    "items"
+  ]
+}

package/conformance/cases/write-list-empty-no-seed.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{items:"li[]"}</script><ul></ul>

package/conformance/cases/write-list-empty-no-seed.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: error
+note: Inserting into a list with no row to clone is a 400, not a silent no-op.

package/conformance/cases/write-list-grow-from-template.after.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{items:"li[]"}</script><ul><li>First</li><li cms-template=""></li></ul>

package/conformance/cases/write-list-grow-from-template.after.json

@@ -0,0 +1,5 @@
+{
+  "items": [
+    "First"
+  ]
+}

package/conformance/cases/write-list-grow-from-template.data.json

@@ -0,0 +1 @@
+{"items":["First"]}

package/conformance/cases/write-list-grow-from-template.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{items:"li[]"}</script><ul><li cms-template></li></ul>

package/conformance/cases/write-list-grow-from-template.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: A cms-template row is the clone source for a list that starts with no data rows.

package/conformance/cases/write-list-grow-from-template.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-list-object-clone.after.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{rows:["li",{name:"b",n:"i"}]}</script><ul><li id="r1"><b>A</b><i>1</i></li><li><b>B</b><i>2</i></li></ul>

package/conformance/cases/write-list-object-clone.after.json

@@ -0,0 +1,12 @@
+{
+  "rows": [
+    {
+      "name": "A",
+      "n": "1"
+    },
+    {
+      "name": "B",
+      "n": "2"
+    }
+  ]
+}

package/conformance/cases/write-list-object-clone.data.json

@@ -0,0 +1 @@
+{"rows":[{"name":"A","n":"1"},{"name":"B","n":"2"}]}

package/conformance/cases/write-list-object-clone.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{rows:["li",{name:"b",n:"i"}]}</script><ul><li id=r1><b>A</b><i>1</i></li></ul>

package/conformance/cases/write-list-object-clone.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: Object list rows clone the last row's shape and fill each item's rules.

package/conformance/cases/write-list-object-clone.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-list-scalar-grow.after.html

@@ -0,0 +1,4 @@
+<script data-rules-name="api" data-rules-version="1">{items:"li[]"}</script><ul>
+  <li>A</li>
+  <li>B</li>
+<li>C</li></ul>

package/conformance/cases/write-list-scalar-grow.after.json

@@ -0,0 +1,7 @@
+{
+  "items": [
+    "A",
+    "B",
+    "C"
+  ]
+}

package/conformance/cases/write-list-scalar-grow.data.json

@@ -0,0 +1 @@
+{"items":["A","B","C"]}

package/conformance/cases/write-list-scalar-grow.html

@@ -0,0 +1,4 @@
+<script data-rules-name="api" data-rules-version="1">{items:"li[]"}</script><ul>
+  <li>A</li>
+  <li>B</li>
+</ul>

package/conformance/cases/write-list-scalar-grow.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: Scalar list grow clones the last row and appends, preserving CRLF bytes.

package/conformance/cases/write-list-scalar-grow.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-list-scalar-shrink.after.html

@@ -0,0 +1,4 @@
+<script data-rules-name="api" data-rules-version="1">{items:"li[]"}</script><ul>
+  
+  <li>B</li>
+</ul>

package/conformance/cases/write-list-scalar-shrink.after.json

@@ -0,0 +1,5 @@
+{
+  "items": [
+    "B"
+  ]
+}

package/conformance/cases/write-list-scalar-shrink.data.json

@@ -0,0 +1 @@
+{"items":["B"]}

package/conformance/cases/write-list-scalar-shrink.html

@@ -0,0 +1,4 @@
+<script data-rules-name="api" data-rules-version="1">{items:"li[]"}</script><ul>
+  <li>A</li>
+  <li>B</li>
+</ul>

package/conformance/cases/write-list-scalar-shrink.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: Scalar list shrink removes the leading row and leaves the survivors in place.

package/conformance/cases/write-list-scalar-shrink.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-list-shrink-zero.after.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{items:"li[]"}</script><ul></ul>

package/conformance/cases/write-list-shrink-zero.after.json

@@ -0,0 +1,3 @@
+{
+  "items": []
+}

package/conformance/cases/write-list-shrink-zero.data.json

@@ -0,0 +1 @@
+{"items":[]}

package/conformance/cases/write-list-shrink-zero.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{items:"li[]"}</script><ul><li>A</li></ul>

package/conformance/cases/write-list-shrink-zero.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: An empty list body is a legal shrink to zero rows, unlike an insert.

package/conformance/cases/write-list-shrink-zero.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-no-data-kept.after.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{t:"#x"}</script><p id="x">Bye<span no-data="">UI</span></p>

package/conformance/cases/write-no-data-kept.after.json

@@ -0,0 +1,3 @@
+{
+  "t": "Bye"
+}

package/conformance/cases/write-no-data-kept.data.json

@@ -0,0 +1 @@
+{"t":"Bye"}

package/conformance/cases/write-no-data-kept.html

@@ -0,0 +1 @@
+<script data-rules-name="api" data-rules-version="1">{t:"#x"}</script><p id=x>Hi <span no-data>UI</span></p>

package/conformance/cases/write-no-data-kept.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: A no-data subtree is not part of the text write and survives it.

package/conformance/cases/write-no-data-kept.write.json

@@ -0,0 +1,4 @@
+{
+  "changed": true,
+  "spliced": true
+}

package/conformance/cases/write-no-rules-tag.data.json

@@ -0,0 +1 @@
+{}

package/conformance/cases/write-no-rules-tag.error.json

@@ -0,0 +1,6 @@
+{
+  "type": "NoRulesTag",
+  "message": "no <script data-rules-name~=\"api\"> rules tag in this document",
+  "status": 400,
+  "details": null
+}

package/conformance/cases/write-no-rules-tag.html

@@ -0,0 +1 @@
+<p>x</p>

package/conformance/cases/write-no-rules-tag.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: error
+note: A document without a rules tag cannot be written at all.

package/conformance/cases/write-noop.after.html

@@ -0,0 +1,3 @@
+<script data-rules-name="api" data-rules-version="1">{title:"h1"}</script>
+<h1 class='x'>Hello</h1>
+<p>&copy;<br/></p>

package/conformance/cases/write-noop.after.json

@@ -0,0 +1,3 @@
+{
+  "title": "Hello"
+}

package/conformance/cases/write-noop.data.json

@@ -0,0 +1 @@
+{"title":"Hello"}

package/conformance/cases/write-noop.html

@@ -0,0 +1,3 @@
+<script data-rules-name="api" data-rules-version="1">{title:"h1"}</script>
+<h1 class='x'>Hello</h1>
+<p>&copy;<br/></p>

package/conformance/cases/write-noop.meta

@@ -0,0 +1,4 @@
+tier: 1
+face: write
+expect: ok
+note: Writing the value already on disk changes nothing and still splices.