hyper-html-api 0.10.1 → 0.11.0

package/src/engine/diff.js

@@ -1,5 +1,6 @@
 import { EmptyListInsert } from './errors.js'
 import { extract } from './extract.js'
+import { finalChildCombinatorLeft } from './rule-syntax.js'
 import { matchRows } from './row-match.js'
 
 /**
@@ -47,10 +48,11 @@ export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, a
 
   const matches = matchRows(newItems, oldValues, shape, lockSuppliedRows(adapter, oldNodes, newItems, trace, opts))
 
-  const referenceNode = oldNodes[0] || templateSource
-  const parent = adapter.parent(referenceNode)
+  const parent = oldNodes.length > 0
+    ? adapter.parent(oldNodes[0])
+    : destinationFor(adapter, parentCtx, selector, templateSource, trace, opts)
   const anchorIdx = oldNodes.length > 0
-    ? indexInParent(adapter, parent, referenceNode)
+    ? indexInParent(adapter, parent, oldNodes[0])
     : 0
   const contiguous = isContiguousRun(adapter, oldNodes)
 
@@ -177,19 +179,181 @@ function indexInParent(adapter, parent, targetNode) {
 // product's variant) is found even when the immediate container has none.
 function findFallbackTemplate(adapter, parentCtx, selector, opts) {
   if (!opts.templateAttr) return null
+  // A leading ":scope >" anchors a row to its own context, so an ancestor seed
+  // bank can never answer that query: no element is a direct child of its own
+  // descendant. Dropping just that anchor searches the ancestors for the rest of
+  // the selector, so a checklist item seed still cannot pass for a comment seed.
+  const anchored = /^\s*:scope\s*>\s*/.test(selector)
+  const search = selector.replace(/^\s*:scope\s*>\s*/, '')
+  // The stripped anchor makes the rest of the selector far too loose on its own:
+  // "p" or "div" matches any seed in any ancestor, including the seed bank root
+  // itself. The seed's own selector says how deep its row's context sits and what
+  // that node has to look like, and its container has to be the one it names, so
+  // a person seed under div.people cannot answer for a checklist.
+  const steps = anchored ? childSteps(search) : 0
+  const container = finalChildCombinatorLeft(search)
   let scope = parentCtx
   while (scope) {
     // templateAttr:null opts out of the adapter's default cms-template skip — the
     // fallback lookup MUST see the seed element to clone it for grow-from-zero.
-    const candidates = adapter.find(scope, selector, { includeRulesTag: false, templateAttr: null })
+    const candidates = adapter.find(scope, search, { includeRulesTag: false, templateAttr: null })
     for (const n of candidates) {
-      if (adapter.attr(n, opts.templateAttr) != null) return n
+      if (adapter.attr(n, opts.templateAttr) == null) continue
+      if (anchored && !matchesContextShape(adapter, parentCtx, n, steps)) continue
+      if (container && !adapter.matches(adapter.parent(n), container)) continue
+      return n
     }
     scope = adapter.parent(scope)
   }
   return null
 }
 
+// How many top-level child steps a stripped selector walks through ("p" is one,
+// "ul.checklist-items > li" is two), or null when a descendant, "+" or "~"
+// combinator makes the row's own context uncountable. Whitespace around a
+// combinator is part of it, not a descendant step of its own.
+function childSteps(selector) {
+  let depth = 0
+  let quote = null
+  let steps = 1
+  for (let i = 0; i < selector.length; i++) {
+    const ch = selector[i]
+    if (ch === '\\') {
+      i++
+    } else if (quote) {
+      if (ch === quote) quote = null
+    } else if (ch === '"' || ch === "'") {
+      quote = ch
+    } else if (ch === '[' || ch === '(') {
+      depth++
+    } else if (ch === ']' || ch === ')') {
+      if (depth > 0) depth--
+    } else if (depth === 0 && ch === '>') {
+      steps++
+    } else if (depth === 0 && (ch === '+' || ch === '~')) {
+      return null
+    } else if (depth === 0 && /\s/.test(ch)) {
+      if (!combinatorSpace(selector, i)) return null
+      while (i + 1 < selector.length && /\s/.test(selector[i + 1])) i++
+    }
+  }
+  return steps
+}
+
+// Whitespace written next to ">", "+" or "~" belongs to that combinator; with a
+// compound on both sides it is a descendant step of its own.
+function combinatorSpace(selector, index) {
+  let end = index
+  while (end < selector.length && /\s/.test(selector[end])) end++
+  const before = index > 0 ? selector[index - 1] : ''
+  const after = end < selector.length ? selector[end] : ''
+  return isCombinator(before) || isCombinator(after)
+}
+
+function isCombinator(ch) {
+  return ch === '>' || ch === '+' || ch === '~'
+}
+
+// The node a stripped ":scope > ..." seed's own selector climbs to has to have
+// this context's shape: the same tag, and every class this context carries. A
+// bank's row seed reaches a seed of its own kind, while an unrelated seed
+// (a person seed's div.people, the bank root's body) reaches something else.
+function matchesContextShape(adapter, parentCtx, candidate, steps) {
+  if (steps === null) return true
+  let node = candidate
+  for (let i = 0; i < steps; i++) {
+    node = adapter.parent(node)
+    if (!node) return false
+  }
+  const contextTag = adapter.prop(parentCtx, 'tagName')
+  // A document or fragment context has no tag or class of its own to compare.
+  if (!contextTag) return true
+  const tag = adapter.prop(node, 'tagName')
+  if (!tag || String(tag).toLowerCase() !== String(contextTag).toLowerCase()) return false
+  const own = new Set(classNames(adapter, node))
+  return classNames(adapter, parentCtx).every((name) => own.has(name))
+}
+
+function classNames(adapter, node) {
+  const value = adapter.attr(node, 'class')
+  return value ? String(value).split(/\s+/).filter(Boolean) : []
+}
+
+// Where the rows of an empty list go. The clone source says what a row looks
+// like; the selector's container inside the context says where rows live. A seed
+// that sits in a container of this context knows its own list, and stands in for
+// the selector whatever it looks like: the last ">" in a selector can trail a
+// descendant or sibling combinator, and then the text left of it is not the
+// row's parent. A seed from outside the context (a hidden bank) says nothing
+// about where the rows live, so the selector has to name the container.
+function destinationFor(adapter, parentCtx, selector, templateSource, trace, opts) {
+  const seedParent = adapter.parent(templateSource)
+  if (seedParent && isWithin(adapter, parentCtx, seedParent) && !isSeedOrNoData(adapter, seedParent, opts)) {
+    return seedParent
+  }
+  const container = finalChildCombinatorLeft(selector)
+  if (!container) {
+    throw new EmptyListInsert(
+      trace.path,
+      `the list selector "${selector}" names no container to hold the new rows — write it as "container > row" (for example "ol.comments > li") so the cloned row lands in the list`,
+    )
+  }
+  // ":scope" names the context itself. A document or a fragment is not a
+  // container that can hold rows, and placing a row at index zero of one would
+  // put it outside <html>, so it counts as no destination at all.
+  // find() already scopes the query to the context, so every candidate belongs
+  // to it; a candidate inside a seed bank or a no-data region does not.
+  const found = container === ':scope'
+    ? (adapter.prop(parentCtx, 'tagName') ? [parentCtx] : [])
+    : adapter.find(parentCtx, container, opts)
+  const destinations = found.filter((node) => !isSeedOrNoData(adapter, node, opts))
+  if (destinations.length === 0) {
+    throw new EmptyListInsert(
+      trace.path,
+      `no container matching "${container}" inside this context to hold the new rows`,
+    )
+  }
+  if (destinations.length > 1) {
+    throw new EmptyListInsert(
+      trace.path,
+      `"${container}" matches ${destinations.length} containers inside this context, so the new rows have no single destination`,
+    )
+  }
+  return destinations[0]
+}
+
+function isWithin(adapter, ancestor, node) {
+  let current = node
+  while (current) {
+    if (adapter.sameNode(current, ancestor)) return true
+    current = adapter.parent(current)
+  }
+  // A document (or cheerio's root) is not an element, so a parentElement walk
+  // from inside it stops at <html> and never reaches it. Ask the adapter whether
+  // it sees the node from there instead; a detached node in another tree stays
+  // outside, because that query cannot see it either.
+  if (adapter.parent(ancestor)) return false
+  return adapter
+    .find(ancestor, '*', { includeRulesTag: true, templateAttr: null })
+    .some((n) => adapter.sameNode(n, node))
+}
+
+// The no-data tokens the adapters already filter reads with, read here through
+// the adapter so both of them answer the same way.
+const NO_DATA_ATTRS = ['no-data', 'editor-ui']
+
+function isSeedOrNoData(adapter, node, opts) {
+  let current = node
+  while (current) {
+    if (opts.templateAttr && adapter.attr(current, opts.templateAttr) != null) return true
+    if (NO_DATA_ATTRS.some((name) => adapter.attr(current, name) != null)) return true
+    const clay = adapter.attr(current, 'clay')
+    if (clay && clay.split(/\s+/).some((token) => NO_DATA_ATTRS.includes(token))) return true
+    current = adapter.parent(current)
+  }
+  return false
+}
+
 // Puts finalNodes at anchorIdx onward among the parent's content children and leaves every other
 // child in its order. A node already in place is not touched, so an unchanged apply moves nothing.
 // The children are read once and each move is mirrored in a local copy: reading them per row, as

package/src/engine/dom-properties.js

@@ -97,3 +97,19 @@ export const DOM_PROPERTIES_READ_ONLY_SET = new Set([
   'paused',
   'dataset',
 ])
+
+/**
+ * Form properties whose value is a boolean rather than a string. Shared by
+ * apply() and the round-trip guard so there is one conversion, not two.
+ */
+export const BOOLEAN_PROPS = new Set(['checked', 'selected', 'disabled', 'readOnly', 'paused'])
+
+export function coercePropValue(name, value) {
+  if (value === null || value === undefined) {
+    return BOOLEAN_PROPS.has(name) ? false : ''
+  }
+  // Form state and attribute round-trips deliver booleans as strings, and
+  // Boolean("false") is true: writing "false" would CHECK an unchecked box.
+  if (BOOLEAN_PROPS.has(name)) return value === 'false' ? false : Boolean(value)
+  return value
+}

package/src/engine/errors.js

@@ -33,9 +33,11 @@ export class ShapeMismatch extends Error {
 }
 
 export class EmptyListInsert extends Error {
-  constructor(path) {
+  constructor(path, reason) {
     super(
-      `cannot add items to empty list at "${path.join('.')}" — no sibling to clone as template. Seed the list with a hidden item first.`,
+      reason
+        ? `cannot add items to empty list at "${path.join('.')}" — ${reason}`
+        : `cannot add items to empty list at "${path.join('.')}" — no sibling to clone as template. Seed the list with a hidden item first.`,
     )
     this.name = 'EmptyListInsert'
     this.path = path
@@ -58,6 +60,22 @@ export class WriteRefused extends Error {
   }
 }
 
+function pathLabel(path) {
+  const label = path.reduce(
+    (out, part) => (typeof part === 'number' ? `${out}[${part}]` : out ? `${out}.${part}` : String(part)),
+    '',
+  )
+  return label || '(root)'
+}
+
+export class WriteNotRoundTripped extends Error {
+  constructor(path) {
+    super(`write did not round-trip at "${pathLabel(path)}"`)
+    this.name = 'WriteNotRoundTripped'
+    this.path = path
+  }
+}
+
 export class NoRulesTag extends Error {
   constructor(token) {
     super(`no <script data-rules-name~="${token}"> rules tag in this document`)

package/src/engine/extract.js

@@ -93,5 +93,5 @@ function readPropOrAttr(adapter, node, name) {
     return v == null ? null : String(v)
   }
   const v = adapter.attr(node, name)
-  return v ? v : null
+  return v == null ? null : v
 }

package/src/engine/index.js

@@ -11,6 +11,7 @@ export * as errors from './errors.js'
 export { DOM_PROPERTIES, DOM_PROPERTIES_SET, DOM_PROPERTIES_READ_ONLY_SET } from './dom-properties.js'
 export { WRITE_POLICY, guardAdapter, checkAttribute, urlScheme } from './write-policy.js'
 export { planWrite } from './write-plan.js'
+export { assertRoundTrip } from './round-trip.js'
 export { trackAdapter, spliceDocument } from './splice.js'
 
 // source: object literal → use as-is (no tag); string → look up by token.

package/src/engine/round-trip.js

@@ -0,0 +1,171 @@
+import {
+  DOM_PROPERTIES_SET,
+  DOM_PROPERTIES_WRITE_SET,
+  coercePropValue,
+} from './dom-properties.js'
+import { WriteNotRoundTripped } from './errors.js'
+import { ruleAttrIndex } from './rule-syntax.js'
+
+// Props whose read-side value keeps its whitespace. Every other text rule reads
+// trimmed, which is what writeText compares against.
+const UNTRIMMED_PROPS = new Set(['textContent', 'innerText'])
+
+// Elements whose content loses one leading LF to the HTML parser: the tokenizer
+// drops a newline that immediately follows the start tag.
+const NEWLINE_DROPPING_TAGS = new Set(['pre', 'textarea'])
+
+// Compares what the caller asked for against a fresh extraction of the
+// serialized source, so a write that serialized away or never landed throws
+// WriteNotRoundTripped instead of returning a false success. Only the supplied
+// projection is checked: omitted keys and undefined are skipped exactly as the
+// writer skips them, which is what keeps partial updates working. `source` is
+// the adapter, root and options that extraction read, so the guard can see
+// which element a text rule matched instead of guessing from its selector.
+export function assertRoundTrip(rules, requested, actual, source) {
+  check(rules, requested, actual, [], source ? { ...source, rules } : null)
+}
+
+function check(rule, want, got, path, source) {
+  if (want === undefined) return
+  if (typeof rule === 'string') {
+    checkScalarRule(rule, want, got, path, source)
+    return
+  }
+  if (Array.isArray(rule)) {
+    checkList(rule[1], want, got, path, source)
+    return
+  }
+  if (typeof rule === 'object' && rule !== null) {
+    checkObject(rule, want, got, path, source)
+  }
+}
+
+function checkScalarRule(rule, want, got, path, source) {
+  if (rule.endsWith('[]')) {
+    checkTextList(want, got, path)
+    return
+  }
+  if (rule.startsWith('@')) {
+    checkPropOrAttr(rule.slice(1), want, got, path, '', source)
+    return
+  }
+  const at = ruleAttrIndex(rule)
+  if (at !== -1) {
+    checkPropOrAttr(rule.slice(at + 1), want, got, path, rule.slice(0, at), source)
+    return
+  }
+  checkText(want, got, path)
+}
+
+function checkText(want, got, path) {
+  if (textOf(want) !== textOf(got)) fail(path)
+}
+
+function checkTextList(want, got, path) {
+  if (!Array.isArray(want) || !Array.isArray(got) || want.length !== got.length) fail(path)
+  for (let i = 0; i < want.length; i++) checkText(want[i], got[i], [...path, i])
+}
+
+function checkObject(rule, want, got, path, source) {
+  if (!isPlainObject(want) || !isPlainObject(got)) fail(path)
+  for (const [key, sub] of Object.entries(rule)) {
+    check(sub, want[key], got[key], [...path, key], source)
+  }
+}
+
+function checkList(shape, want, got, path, source) {
+  if (!Array.isArray(want) || !Array.isArray(got) || want.length !== got.length) fail(path)
+  for (let i = 0; i < want.length; i++) check(shape, want[i], got[i], [...path, i], source)
+}
+
+function checkPropOrAttr(name, want, got, path, selector, source) {
+  if (!DOM_PROPERTIES_SET.has(name)) {
+    if (want == null) {
+      if (got != null) fail(path)
+      return
+    }
+    if (!sameString(String(want), got)) fail(path)
+    return
+  }
+  if (UNTRIMMED_PROPS.has(name)) {
+    if (!sameUntrimmed(String(want ?? ''), got, selector, path, source)) fail(path)
+    return
+  }
+  if (DOM_PROPERTIES_WRITE_SET.has(name)) {
+    if (got !== String(coercePropValue(name, want))) fail(path)
+    return
+  }
+  if (want == null) {
+    if (got != null) fail(path)
+    return
+  }
+  if (!sameString(String(want), got)) fail(path)
+}
+
+function textOf(value) {
+  return normalizeNewlines(String(value ?? '').trim())
+}
+
+// A document normalizes newlines: parsing turns CRLF and a lone CR into LF, so
+// a value that differs only by that is the value the source carries.
+function normalizeNewlines(value) {
+  return value.replace(/\r\n?/g, '\n')
+}
+
+function sameString(want, got) {
+  return got != null && normalizeNewlines(want) === normalizeNewlines(got)
+}
+
+// @textContent compares exactly, with one exception: a leading newline after a
+// pre/textarea start tag never reaches the DOM, so it cannot come back.
+function sameUntrimmed(want, got, selector, path, source) {
+  if (got == null) return false
+  const wantText = normalizeNewlines(want)
+  const gotText = normalizeNewlines(got)
+  if (wantText === gotText) return true
+  return wantText.startsWith('\n') && wantText.slice(1) === gotText && dropsLeadingNewline(selector, path, source)
+}
+
+// Which element the rule matched decides the allowance, not how its selector is
+// spelled: an ID or class selector names a pre just as "pre" does. An element
+// that cannot be found refuses, which is the safe answer: the caller compares
+// exactly.
+function dropsLeadingNewline(selector, path, source) {
+  const node = matchedNode(selector, path, source)
+  if (!node) return false
+  const tag = source.adapter.prop(node, 'tagName')
+  return tag != null && NEWLINE_DROPPING_TAGS.has(String(tag).toLowerCase())
+}
+
+// The element a scalar rule reads, found the way extraction found it: walk the
+// rule tree by the reported path to the rule's own context, then match the
+// rule's selector there. Only called for a text rule whose value lost a leading
+// newline, so an ordinary write pays nothing for it.
+function matchedNode(selector, path, source) {
+  if (!source || !source.adapter || !source.root) return null
+  const { adapter, root, opts } = source
+  let rule = source.rules
+  let ctx = root
+  for (const key of path) {
+    if (Array.isArray(rule)) {
+      const match = adapter.find(ctx, rule[0], opts)[key]
+      if (!match) return null
+      ctx = match
+      rule = rule[1]
+    } else if (isPlainObject(rule)) {
+      rule = rule[key]
+    } else {
+      return null
+    }
+  }
+  if (!selector) return ctx
+  return adapter.find(ctx, selector, opts)[0] || null
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function fail(path) {
+  throw new WriteNotRoundTripped(path)
+}

package/src/engine/rule-syntax.js

@@ -41,3 +41,74 @@ export function splitRule(rule) {
   if (at === -1) return { selector: rule, prop: null }
   return { selector: rule.slice(0, at), prop: rule.slice(at + 1) || null }
 }
+
+// The list grammar needs a second split: "container > row" says where a row
+// goes. Only the FINAL top-level ">" separates them, and a ">" inside brackets,
+// parens or quotes is not a combinator at all: a[data-note="a > b"] and
+// :is(a > b) both carry one, and splitting there names a container that cannot
+// exist. A top-level "," is a group whose members may name different
+// containers, so the fallback refuses it rather than guessing one of them.
+//
+// What follows that ">" also has to be the ONE compound selector it introduces.
+// "ul > li span" and "ul > li + li" put the row below that ">", so its left
+// side is not the row's parent and cannot stand in as the row's container.
+//
+// Left side of that final top-level ">", or null when the selector names no
+// container for the row.
+export function finalChildCombinatorLeft(selector) {
+  let depth = 0
+  let quote = null
+  let found = -1
+  let group = false
+  for (let i = 0; i < selector.length; i++) {
+    const ch = selector[i]
+    if (ch === '\\') {
+      i++
+    } else if (quote) {
+      if (ch === quote) quote = null
+    } else if (ch === '"' || ch === "'") {
+      quote = ch
+    } else if (ch === '[' || ch === '(') {
+      depth++
+    } else if (ch === ']' || ch === ')') {
+      if (depth > 0) depth--
+    } else if (depth === 0 && ch === '>') {
+      found = i
+    } else if (depth === 0 && ch === ',') {
+      group = true
+    }
+  }
+  if (group || found === -1) return null
+  if (!isSingleCompound(selector, found + 1)) return null
+  return selector.slice(0, found).trim() || null
+}
+
+// The text after the ">", ignoring the whitespace that belongs to the
+// combinator itself, is a single compound selector when no top-level
+// descendant, "+" or "~" follows it. Depth and quotes are tracked the same way
+// as above, so whitespace inside a[title="a b"] or :is(a b) is not a
+// combinator.
+function isSingleCompound(selector, start) {
+  let i = start
+  const end = selector.replace(/\s+$/, '').length
+  while (i < end && /\s/.test(selector[i])) i++
+  let depth = 0
+  let quote = null
+  for (; i < end; i++) {
+    const ch = selector[i]
+    if (ch === '\\') {
+      i++
+    } else if (quote) {
+      if (ch === quote) quote = null
+    } else if (ch === '"' || ch === "'") {
+      quote = ch
+    } else if (ch === '[' || ch === '(') {
+      depth++
+    } else if (ch === ']' || ch === ')') {
+      if (depth > 0) depth--
+    } else if (depth === 0 && (ch === '+' || ch === '~' || /\s/.test(ch))) {
+      return false
+    }
+  }
+  return true
+}

package/src/engine/write-policy.js

@@ -105,6 +105,9 @@ export function guardAdapter(adapter, policy = WRITE_POLICY) {
       if (value === undefined) return adapter.attr(node, name)
       if (allowAttr(node, name, value)) adapter.attr(node, name, value)
     },
+    removeAttr(node, name) {
+      if (allowAttr(node, name, null)) adapter.removeAttr(node, name)
+    },
     prop(node, name, value) {
       if (value === undefined) return adapter.prop(node, name)
       if (policy.refusedRuleForms.includes(name)) return refuse(node, `"@${name}" writes HTML, only text is allowed`)

package/src/write.js

@@ -1,8 +1,10 @@
 import cheerioAdapter from './adapters/cheerio.js'
 import { apply } from './engine/apply.js'
+import { extract } from './engine/extract.js'
 import { findRulesIn } from './engine/rules-tag.js'
 import { guardAdapter } from './engine/write-policy.js'
 import { planWrite } from './engine/write-plan.js'
+import { assertRoundTrip } from './engine/round-trip.js'
 import { trackAdapter, spliceDocument } from './engine/splice.js'
 import { NoRulesTag, RulesParseError, WriteRejected } from './engine/errors.js'
 
@@ -10,8 +12,8 @@ import { NoRulesTag, RulesParseError, WriteRejected } from './engine/errors.js'
 // (options.rules) or the document's own rules tag, under the content-only
 // policy. `load` is cheerio.load, passed in so this package keeps cheerio out
 // of its browser bundles. Returns the new source and whether anything changed.
-// Throws NoRulesTag, RulesParseError, WriteRejected, WriteRefused, ShapeMismatch
-// or EmptyListInsert, always before producing any output.
+// Throws NoRulesTag, RulesParseError, WriteRejected, WriteRefused, ShapeMismatch,
+// EmptyListInsert or WriteNotRoundTripped, always before producing any output.
 export function writeDocument(load, src, data, options = {}) {
   const { token = 'api' } = options
   const $ = load(src, { sourceCodeLocationInfo: true })
@@ -29,11 +31,41 @@ export function writeDocument(load, src, data, options = {}) {
   }
   const plan = planWrite(cheerioAdapter, root, rules, data)
   if (plan.unknownKeys.length || plan.unmatched.length) throw new WriteRejected(plan.unknownKeys, plan.unmatched)
+  const opts = { templateAttr: 'cms-template' }
   const tracker = trackAdapter(cheerioAdapter)
   const guarded = guardAdapter(tracker)
-  apply(guarded, root, rules, data, { templateAttr: 'cms-template' })
+  apply(guarded, root, rules, data, opts)
   guarded.assertClean()
-  if (tracker.dirty.size === 0) return { html: src, changed: false, spliced: true }
-  const { html, spliced } = spliceDocument(load, src, $, tracker)
+  const { html, spliced } = tracker.dirty.size === 0
+    ? { html: src, spliced: true }
+    : spliceDocument(load, src, $, tracker)
+  // The in-memory tree is not the contract: only the source the caller gets
+  // back is. Re-parse it and compare the caller's projection, so a write that
+  // serialization dropped throws instead of returning a false success. Only the
+  // rules the payload names are re-extracted: a one-field write on a large page
+  // pays for the field it wrote, not for every rule in the document.
+  const written = writtenRules(rules, data)
+  const writtenRoot = load(html).root()
+  assertRoundTrip(written, data, extract(cheerioAdapter, writtenRoot, written, opts), {
+    adapter: cheerioAdapter,
+    root: writtenRoot,
+    opts,
+  })
   return { html, changed: html !== src, spliced }
 }
+
+// The top-level subset of `rules` that the payload names, which is exactly what
+// the guard checks: an omitted rule is not part of this write and must not be
+// able to fail it. A scalar or list rule already IS the whole projection.
+function writtenRules(rules, data) {
+  if (!isPlainObject(rules) || !isPlainObject(data)) return rules
+  const subset = {}
+  for (const key of Object.keys(data)) {
+    if (Object.prototype.hasOwnProperty.call(rules, key)) subset[key] = rules[key]
+  }
+  return subset
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}