hyper-html-api 0.1.0 → 0.3.0

package/src/dom-api.js

@@ -0,0 +1,60 @@
+import * as engineMod from './engine/index.js'
+import domAdapter from './adapters/dom.js'
+
+// The DOM-bound engine: every engine call pre-wired with the DOM adapter. Lives
+// here (instead of inline in hyper-html-api.js) so both the full CDN bundle and
+// the lean `data.js` entry share one definition.
+export const engine = {
+  extract: (root, rules, opts) => engineMod.extract(domAdapter, root, rules, opts),
+  apply: (root, rules, data, opts) => engineMod.apply(domAdapter, root, rules, data, opts),
+  findRulesIn: (root, token) => engineMod.findRulesIn(domAdapter, root, token),
+  findRules: (root, source) => engineMod.resolveRules(domAdapter, root, source),
+  bind: (root, source, opts) => engineMod.bind(domAdapter, root, source, opts),
+  parseStrict: engineMod.parseStrict,
+  parseRelaxed: engineMod.parseRelaxed,
+  errors: engineMod.errors,
+  DOM_PROPERTIES: engineMod.DOM_PROPERTIES,
+}
+
+const isNode = (x) => !!x && typeof x.nodeType === 'number'
+
+// Autodetect the page's single rules tag when no `source` is given.
+// engine.findRulesIn(root) (no token) silently takes the FIRST of many tags, so
+// the sugar counts the tags itself to enforce the one-tag rule with clear,
+// distinct errors for "none" vs "multiple".
+function autodetect(root) {
+  const searchRoot = (root && root.ownerDocument) ? root.ownerDocument : root
+  const tags = domAdapter.find(searchRoot, 'script[data-rules-name]', { includeRulesTag: true })
+  if (tags.length === 0) {
+    throw new Error('hyper-html-api: no rules tag found. Add <script type="application/json" data-rules-name="…" data-rules-version="1"> or pass rules.')
+  }
+  if (tags.length > 1) {
+    throw new Error('hyper-html-api: multiple rules tags found; pass a name, e.g. extractData("api").')
+  }
+  // findRulesIn (no token) returns the one tag's rules and enforces data-rules-version="1".
+  return engineMod.findRulesIn(domAdapter, searchRoot).rules
+}
+
+// extractData()                       → document + autodetect
+// extractData(el)                     → el + autodetect
+// extractData('api' | {title:'h1'})   → document + named/inline rules
+// extractData(el, 'api' | {...})      → explicit root + source
+// One-shot read; returns the extracted data.
+export function extractData(a, b) {
+  const root = isNode(a) ? a : document
+  const source = isNode(a) ? b : a
+  if (source === undefined) return engineMod.extract(domAdapter, root, autodetect(root))
+  return engine.bind(root, source).get()
+}
+
+// applyData(root, data, source?) — writes `data` INTO the live DOM under `root`,
+// using a named/inline `source` or (when omitted) the page's single rules tag.
+// MUTATES the DOM and returns `root`.
+export function applyData(root, data, source) {
+  if (!isNode(root)) {
+    throw new Error('hyper-html-api: applyData(root, data, source?) needs a DOM root as the first argument.')
+  }
+  if (source === undefined) engineMod.apply(domAdapter, root, autodetect(root), data)
+  else engine.bind(root, source).set(data)
+  return root
+}

package/src/engine/apply.js

@@ -1,47 +1,63 @@
-import { DOM_PROPERTIES_SET } from './dom-properties.js'
-import { MaxRuleDepthExceeded, ShapeMismatch } from './errors.js'
+import {
+  DOM_PROPERTIES_WRITE_SET,
+  DOM_PROPERTIES_READ_ONLY_SET,
+} from './dom-properties.js'
+import {
+  MaxRuleDepthExceeded,
+  MAX_RULE_DEPTH,
+  RuleTargetReadOnly,
+  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) {
+export function apply(adapter, root, rules, data, opts = {}) {
   const mismatches = []
   validateShape(rules, data, [], mismatches)
   if (mismatches.length) throw new ShapeMismatch(mismatches)
 
-  applyAt(adapter, root, rules, data, { depth: 0, path: [] })
+  applyAt(adapter, root, rules, data, { depth: 0, path: [] }, opts)
 }
 
-export function applyAt(adapter, ctx, rule, value, trace) {
-  if (trace.depth > MAX_DEPTH) throw new MaxRuleDepthExceeded(trace.path)
-  if (value === undefined) return
+// applyAt returns the (possibly new) ctx node. Most rules don't change
+// ctx, but writes targeting `@outerHTML` on ctx itself replace the node;
+// downstream code (object-rule sub-walks, listDiff) needs to refresh its
+// pointer from the return value.
+export function applyAt(adapter, ctx, rule, value, trace, opts = {}) {
+  if (trace.depth > MAX_RULE_DEPTH) throw new MaxRuleDepthExceeded(trace.path)
+  if (value === undefined) return ctx
 
-  if (typeof rule === 'string') return applyScalar(adapter, ctx, rule, value, trace)
+  if (typeof rule === 'string') return applyScalar(adapter, ctx, rule, value, trace, opts)
 
   if (Array.isArray(rule)) {
     const [selector, shape] = rule
-    return listDiff(adapter, ctx, selector, shape, value, trace, applyAt)
+    listDiff(adapter, ctx, selector, shape, value, trace, applyAt, opts)
+    return ctx
   }
 
   if (typeof rule === 'object' && rule !== null) {
     for (const [key, sub] of Object.entries(rule)) {
-      applyAt(
+      const newCtx = applyAt(
         adapter,
         ctx,
         sub,
         value == null ? value : value[key],
         { depth: trace.depth + 1, path: [...trace.path, key] },
+        opts,
       )
+      if (newCtx && newCtx !== ctx) ctx = newCtx
     }
+    return ctx
   }
+  return ctx
 }
 
-function applyScalar(adapter, ctx, rule, value, trace) {
+function applyScalar(adapter, ctx, rule, value, trace, opts) {
   if (rule.endsWith('[]')) {
     const selector = rule.slice(0, -2)
-    return listDiff(adapter, ctx, selector, null, value, trace, applyAt)
+    listDiff(adapter, ctx, selector, null, value, trace, applyAt, opts)
+    return ctx
   }
 
   if (rule.startsWith('@')) {
@@ -49,28 +65,43 @@ function applyScalar(adapter, ctx, rule, value, trace) {
   }
 
   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)
+    const at = rule.lastIndexOf('@')
+    const selector = rule.slice(0, at)
+    const name = rule.slice(at + 1)
+    const matches = selector ? adapter.find(ctx, selector, opts) : [ctx]
+    if (matches.length === 0) return ctx
+    writePropOrAttr(adapter, matches[0], name, value)
+    return ctx
   }
 
   if (rule === '.') {
     adapter.text(ctx, value == null ? '' : String(value))
-    return
+    return ctx
   }
 
-  const matches = adapter.find(ctx, rule)
-  if (matches.length === 0) return
+  const matches = adapter.find(ctx, rule, opts)
+  if (matches.length === 0) return ctx
   adapter.text(matches[0], value == null ? '' : String(value))
+  return ctx
 }
 
+// Returns the (possibly new) node. For outerHTML, the original is detached
+// and a freshly parsed element takes its place; that new node is returned.
+// For every other write, returns the original node unchanged.
 function writePropOrAttr(adapter, node, name, value) {
-  if (DOM_PROPERTIES_SET.has(name)) {
+  if (DOM_PROPERTIES_READ_ONLY_SET.has(name)) {
+    throw new RuleTargetReadOnly(name)
+  }
+  if (name === 'outerHTML') {
+    const html = value == null ? '' : String(value)
+    return adapter.replaceWith(node, html)
+  }
+  if (DOM_PROPERTIES_WRITE_SET.has(name)) {
     adapter.prop(node, name, coercePropValue(name, value))
-  } else {
-    adapter.attr(node, name, value == null ? '' : String(value))
+    return node
   }
+  adapter.attr(node, name, value == null ? '' : String(value))
+  return node
 }
 
 function coercePropValue(name, value) {
@@ -82,7 +113,10 @@ function coercePropValue(name, value) {
 }
 
 function validateShape(rule, value, path, mismatches) {
-  if (value === undefined || value === null || value === '') return
+  // undefined = key omitted by caller; treat as "skip this rule entirely".
+  // null / '' are valid for scalar rules (clears the value), but NOT for
+  // list or object rules — those mismatch explicitly.
+  if (value === undefined) return
 
   if (typeof rule === 'string') {
     if (rule.endsWith('[]')) {
@@ -101,7 +135,9 @@ function validateShape(rule, value, path, mismatches) {
       }
       return
     }
-    if (typeof value === 'object') {
+    // Scalar rule. null / '' are valid (clears text/attribute). Reject
+    // only nested objects/arrays.
+    if (value !== null && typeof value === 'object') {
       mismatches.push({ path: pathStr(path), expected: 'scalar', got: typeofX(value) })
     }
     return
@@ -118,7 +154,7 @@ function validateShape(rule, value, path, mismatches) {
   }
 
   if (typeof rule === 'object' && rule !== null) {
-    if (Array.isArray(value) || typeof value !== 'object') {
+    if (value === null || Array.isArray(value) || typeof value !== 'object') {
       mismatches.push({ path: pathStr(path), expected: 'object', got: typeofX(value) })
       return
     }

package/src/engine/diff.js

@@ -11,8 +11,8 @@ const SIMILARITY_THRESHOLD = 0.5
  * 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)
+export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, applyItem, opts = {}) {
+  const oldNodes = adapter.find(parentCtx, selector, opts)
 
   if (newItems.length === 0) {
     oldNodes.forEach((n) => adapter.remove(n))
@@ -20,13 +20,18 @@ export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, a
   }
 
   const needsTemplate = newItems.length > oldNodes.length
-  if (needsTemplate && oldNodes.length === 0) throw new EmptyListInsert(trace.path)
+  let templateSource = oldNodes[0] || null
+  if (needsTemplate && !templateSource) {
+    templateSource = findFallbackTemplate(adapter, parentCtx, selector, opts)
+    if (!templateSource) throw new EmptyListInsert(trace.path)
+  }
 
-  const oldValues = oldNodes.map((n) => extractItem(adapter, n, shape))
+  const oldValues = oldNodes.map((n) => extractItem(adapter, n, shape, opts))
 
   let template = null
-  if (oldNodes.length > 0) {
-    template = adapter.clone(oldNodes[0])
+  if (templateSource) {
+    template = adapter.clone(templateSource)
+    if (opts.templateAttr) adapter.removeAttr(template, opts.templateAttr)
     const stripped = adapter.stripIds(template)
     if (stripped > 0) {
       // eslint-disable-next-line no-console
@@ -38,8 +43,11 @@ export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, a
 
   const matches = greedyMatch(newItems, oldValues, shape)
 
-  const parent = adapter.parent(oldNodes[0])
-  const anchorIdx = indexInParent(adapter, parent, oldNodes[0])
+  const referenceNode = oldNodes[0] || templateSource
+  const parent = adapter.parent(referenceNode)
+  const anchorIdx = oldNodes.length > 0
+    ? indexInParent(adapter, parent, referenceNode)
+    : 0
 
   const used = new Set()
   const finalNodes = newItems.map((_, i) => {
@@ -53,32 +61,46 @@ export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, a
     return cloned
   })
 
+  // Remove only unmatched old nodes. Matched nodes stay attached so DOM
+  // identity (focus, observers, animations) survives the reorder.
   oldNodes.forEach((n, i) => {
     if (!used.has(i)) adapter.remove(n)
   })
 
-  used.forEach((i) => adapter.remove(oldNodes[i]))
-
+  // Place each final node at its target index. If the node is already
+  // there, do nothing (no-op apply on unchanged data drops zero state).
+  // Otherwise insertAt moves an attached node (DOM/cheerio both treat
+  // insertBefore on an attached node as "move to here").
   finalNodes.forEach((node, i) => {
-    adapter.insertAt(parent, node, anchorIdx + i)
+    const targetIdx = anchorIdx + i
+    const siblings = adapter.children(parent)
+    const currentIdx = siblings.findIndex((s) => adapter.sameNode(s, node))
+    if (currentIdx === targetIdx) return
+    adapter.insertAt(parent, node, targetIdx)
   })
 
+  // Apply per-item content. Skip when the existing value already matches
+  // — saves a write on no-op applies and avoids spurious mutation events.
   finalNodes.forEach((node, i) => {
     if (shape === null) {
       const v = newItems[i]
-      adapter.text(node, v == null ? '' : String(v))
+      const target = v == null ? '' : String(v)
+      if (adapter.text(node) !== target) adapter.text(node, target)
     } else {
-      applyItem(adapter, node, shape, newItems[i], {
+      // applyItem may replace the node (e.g. @outerHTML on the item itself);
+      // capture the return so finalNodes stays current for later passes.
+      const newNode = applyItem(adapter, node, shape, newItems[i], {
         depth: trace.depth + 1,
         path: [...trace.path, i],
-      })
+      }, opts)
+      if (newNode && newNode !== node) finalNodes[i] = newNode
     }
   })
 }
 
-function extractItem(adapter, node, shape) {
+function extractItem(adapter, node, shape, opts) {
   if (shape === null) return adapter.text(node)
-  return extract(adapter, node, shape)
+  return extract(adapter, node, shape, opts)
 }
 
 function greedyMatch(newItems, oldValues, shape) {
@@ -127,3 +149,19 @@ function indexInParent(adapter, parent, targetNode) {
   }
   return -1
 }
+
+// Look for a template-marked node matching the selector. Walks up from
+// parentCtx so a template defined once in an ancestor (e.g. on a sibling
+// product's variant) is found even when the immediate container has none.
+function findFallbackTemplate(adapter, parentCtx, selector, opts) {
+  if (!opts.templateAttr) return null
+  let scope = parentCtx
+  while (scope) {
+    const candidates = adapter.find(scope, selector, { includeRulesTag: false })
+    for (const n of candidates) {
+      if (adapter.attr(n, opts.templateAttr) != null) return n
+    }
+    scope = adapter.parent(scope)
+  }
+  return null
+}

package/src/engine/dom-properties.js

@@ -1,7 +1,10 @@
 /**
- * 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.
+ * Names that are read via the DOM/cheerio .prop() interface rather than
+ * .attr(). The original allowlist is preserved for read parity with the
+ * legacy hyperclay/server-lib/data-extractor.js, with two exceptions
+ * (`href`, `src`, `action`) that are now READ via .attr() too so the
+ * round-trip stays byte-stable (writes always go through .attr() for these
+ * — see DOM_PROPERTIES_WRITE_SET).
  */
 export const DOM_PROPERTIES = [
   'textContent',
@@ -26,9 +29,6 @@ export const DOM_PROPERTIES = [
   'className',
   'classList',
 
-  'href',
-  'src',
-  'action',
   'baseURI',
 
   'offsetWidth',
@@ -50,3 +50,50 @@ export const DOM_PROPERTIES = [
 ]
 
 export const DOM_PROPERTIES_SET = new Set(DOM_PROPERTIES)
+
+/**
+ * Subset of DOM_PROPERTIES that is safe to WRITE via .prop(). Everything
+ * else routes through .attr() (literal attribute) or throws
+ * RuleTargetReadOnly. Notably absent: href/src/action (URL normalization)
+ * and outerHTML (handled via adapter.replaceWith).
+ */
+export const DOM_PROPERTIES_WRITE_SET = new Set([
+  'textContent',
+  'innerText',
+  'innerHTML',
+  'value',
+  'checked',
+  'selected',
+  'disabled',
+  'readOnly',
+  'type',
+  'id',
+  'className',
+  'title',
+])
+
+/**
+ * Props that throw on write (DOM enforces read-only, our engine catches
+ * before reaching the adapter so the error type is consistent).
+ */
+export const DOM_PROPERTIES_READ_ONLY_SET = new Set([
+  'tagName',
+  'nodeName',
+  'nodeType',
+  'nodeValue',
+  'childElementCount',
+  'classList',
+  'baseURI',
+  'documentURI',
+  'contentType',
+  'offsetWidth',
+  'offsetHeight',
+  'clientWidth',
+  'clientHeight',
+  'scrollWidth',
+  'scrollHeight',
+  'currentSrc',
+  'duration',
+  'paused',
+  'dataset',
+])

package/src/engine/errors.js

@@ -14,9 +14,11 @@ export class UnknownRulesVersion extends Error {
   }
 }
 
+export const MAX_RULE_DEPTH = 20
+
 export class MaxRuleDepthExceeded extends Error {
   constructor(path) {
-    super(`rule depth exceeded 20 at path: ${path.join('.')}`)
+    super(`rule depth exceeded ${MAX_RULE_DEPTH} at path: ${path.join('.')}`)
     this.name = 'MaxRuleDepthExceeded'
     this.path = path
   }
@@ -40,6 +42,14 @@ export class EmptyListInsert extends Error {
   }
 }
 
+export class RuleTargetReadOnly extends Error {
+  constructor(name) {
+    super(`cannot write to read-only DOM property "${name}"`)
+    this.name = 'RuleTargetReadOnly'
+    this.target = name
+  }
+}
+
 export class UpgradeAlreadyRegistered extends Error {
   constructor() {
     super('upgrade transform already registered; only one registration is allowed per page.')

package/src/engine/extract.js

@@ -1,25 +1,23 @@
 import { DOM_PROPERTIES_SET } from './dom-properties.js'
-import { MaxRuleDepthExceeded } from './errors.js'
+import { MaxRuleDepthExceeded, MAX_RULE_DEPTH } from './errors.js'
 
-const MAX_DEPTH = 20
-
-export function extract(adapter, root, rules) {
-  return extractAt(adapter, root, rules, { depth: 0, path: [] })
+export function extract(adapter, root, rules, opts = {}) {
+  return extractAt(adapter, root, rules, { depth: 0, path: [] }, opts)
 }
 
-function extractAt(adapter, ctx, rule, trace) {
-  if (trace.depth > MAX_DEPTH) throw new MaxRuleDepthExceeded(trace.path)
+function extractAt(adapter, ctx, rule, trace, opts) {
+  if (trace.depth > MAX_RULE_DEPTH) throw new MaxRuleDepthExceeded(trace.path)
 
-  if (typeof rule === 'string') return extractScalar(adapter, ctx, rule)
+  if (typeof rule === 'string') return extractScalar(adapter, ctx, rule, opts)
 
   if (Array.isArray(rule)) {
     const [selector, shape] = rule
-    const matches = adapter.find(ctx, selector)
+    const matches = adapter.find(ctx, selector, opts)
     return matches.map((node, i) =>
       extractAt(adapter, node, shape, {
         depth: trace.depth + 1,
         path: [...trace.path, i],
-      }),
+      }, opts),
     )
   }
 
@@ -29,7 +27,7 @@ function extractAt(adapter, ctx, rule, trace) {
       result[key] = extractAt(adapter, ctx, sub, {
         depth: trace.depth + 1,
         path: [...trace.path, key],
-      })
+      }, opts)
     }
     return result
   }
@@ -37,10 +35,10 @@ function extractAt(adapter, ctx, rule, trace) {
   return null
 }
 
-function extractScalar(adapter, ctx, rule) {
+function extractScalar(adapter, ctx, rule, opts) {
   if (rule.endsWith('[]')) {
     const selector = rule.slice(0, -2)
-    return adapter.find(ctx, selector).map((n) => adapter.text(n))
+    return adapter.find(ctx, selector, opts).map((n) => adapter.text(n))
   }
 
   if (rule.startsWith('@')) {
@@ -48,15 +46,17 @@ function extractScalar(adapter, ctx, rule) {
   }
 
   if (rule.includes('@')) {
-    const [selector, name] = rule.split('@')
-    const matches = selector ? adapter.find(ctx, selector) : [ctx]
+    const at = rule.lastIndexOf('@')
+    const selector = rule.slice(0, at)
+    const name = rule.slice(at + 1)
+    const matches = selector ? adapter.find(ctx, selector, opts) : [ctx]
     if (matches.length === 0) return null
     return readPropOrAttr(adapter, matches[0], name)
   }
 
   if (rule === '.') return adapter.text(ctx)
 
-  const matches = adapter.find(ctx, rule)
+  const matches = adapter.find(ctx, rule, opts)
   return matches.length === 0 ? null : adapter.text(matches[0])
 }
 

package/src/engine/index.js

@@ -1,6 +1,40 @@
+import { extract } from './extract.js'
+import { apply } from './apply.js'
+import { findRulesIn } from './rules-tag.js'
+
 export { extract } from './extract.js'
 export { apply } from './apply.js'
 export { findRulesIn } from './rules-tag.js'
 export { parseStrict, parseRelaxed } from './rules.js'
 export * as errors from './errors.js'
 export { DOM_PROPERTIES, DOM_PROPERTIES_SET } from './dom-properties.js'
+
+// source: object literal → use as-is (no tag); string → look up by token.
+// For an element root, search the whole document (root.ownerDocument) so a
+// head-mounted tag is found; get/set still scope to the passed root.
+// For a Document root or the cheerio $.root(), ownerDocument is absent → no-op.
+export function resolveRules(adapter, root, source) {
+  if (source && typeof source === 'object') {
+    return { rules: source, tagNode: null }
+  }
+  if (typeof source === 'string') {
+    const searchRoot = (root && root.ownerDocument) ? root.ownerDocument : root
+    return findRulesIn(adapter, searchRoot, source)
+  }
+  return null
+}
+
+export function bind(adapter, root, source, opts) {
+  const found = resolveRules(adapter, root, source)
+  if (!found) {
+    const what = typeof source === 'string' ? `data-rules-name~="${source}"` : 'the provided rules object'
+    throw new Error(`hyper-html-api: could not resolve rules for ${what}`)
+  }
+  const { rules, tagNode } = found
+  return {
+    rules,
+    tagNode,                                                // informational only; null for a literal object
+    get: () => extract(adapter, root, rules, opts),         // opts (skip/templateAttr) forwarded
+    set: (data) => apply(adapter, root, rules, data, opts),
+  }
+}

package/src/engine/rules-tag.js

@@ -1,18 +1,40 @@
-import { parseStrict } from './rules.js'
+import { parseRelaxed } from './rules.js'
 import { UnknownRulesVersion } from './errors.js'
 
-const RULES_TAG_ID = 'hyper-html-api'
 const SUPPORTED_VERSION = '1'
+const TOKEN_RE = /^[a-zA-Z0-9_-]+$/
 
-export function findRulesIn(adapter, root) {
-  const candidates = adapter.find(root, `script#${RULES_TAG_ID}`, { includeRulesTag: true })
+// findRulesIn(adapter, root)         → first script[data-rules-name] (tooling/no-token)
+// findRulesIn(adapter, root, token)  → first script[data-rules-name~="token"]
+export function findRulesIn(adapter, root, token) {
+  let selector
+  if (token === undefined) {
+    selector = 'script[data-rules-name]'
+  } else {
+    // Validate BEFORE interpolating into the selector (rejects, never sanitizes).
+    // The charset also forecloses selector injection through the ~= match.
+    if (typeof token !== 'string' || !TOKEN_RE.test(token)) {
+      throw new Error(`hyper-html-api: invalid rules token ${JSON.stringify(token)} (must match ${TOKEN_RE})`)
+    }
+    selector = `script[data-rules-name~="${token}"]`
+  }
+
+  // includeRulesTag:true is REQUIRED: isRulesTag now matches any data-rules-name
+  // script, so without the flag adapter.find would filter out the very tag we select.
+  const candidates = adapter.find(root, selector, { includeRulesTag: true })
   if (candidates.length === 0) return null
+  if (token !== undefined && candidates.length > 1) {
+    console.warn(`hyper-html-api: ${candidates.length} rules tags match data-rules-name~="${token}"; using the first.`)
+  }
 
   const tagNode = candidates[0]
   const version = adapter.attr(tagNode, 'data-rules-version')
   if (version !== SUPPORTED_VERSION) throw new UnknownRulesVersion(version)
 
-  const body = adapter.text(tagNode)
-  const rules = parseStrict(body)
+  // Script tag bodies accept the same relaxed JSON syntax as the ?data=
+  // URL parameter: unquoted keys, single-quoted strings, trailing commas.
+  // parseRelaxed tries strict JSON.parse first, so valid JSON keeps
+  // parsing identically.
+  const rules = parseRelaxed(adapter.text(tagNode))
   return { rules, tagNode }
 }

package/src/engine/rules.js

@@ -1,16 +1,17 @@
 import { RulesParseError } from './errors.js'
 
 /**
- * Strict JSON parser for script-tag rules bodies.
+ * Strict JSON parser. Public export kept for callers that explicitly want
+ * strict semantics (no unquoted keys, no single quotes, no trailing
+ * commas). The script-tag path uses parseRelaxed instead — see
+ * rules-tag.js.
  */
 export function parseStrict(body) {
   try {
     return JSON.parse(body)
   } catch (e) {
     throw new RulesParseError(
-      '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: ${e.message}`,
+      `Invalid strict JSON: ${e.message}`,
       e,
     )
   }
@@ -106,6 +107,7 @@ export function parseRelaxed(queryString) {
           type: TokenType.STRING,
           value: input.substring(i + 1, j),
           quoted: true,
+          sourceQuote: quote,
         })
         i = j + 1
         continue
@@ -210,12 +212,29 @@ export function parseRelaxed(queryString) {
       }
 
       if (token.type === TokenType.COMMA) {
+        // Drop trailing commas. JSON.parse rejects them; relaxed authors
+        // expect them to work.
+        const next = tokens[i + 1]
+        if (next && (next.type === '}' || next.type === ']')) {
+          continue
+        }
         result += token.value
         continue
       }
 
       if (token.type === TokenType.STRING && token.quoted) {
-        result += `"${token.value}"`
+        let v = token.value
+        if (token.sourceQuote === "'") {
+          // Single-quoted source: \' was escaping the outer quote in the
+          // source; once we re-wrap in double quotes it's a plain '.
+          v = v.replace(/\\'/g, "'")
+          // Unescaped " inside the value needs to be \"-escaped for JSON.
+          // "Unescaped" = preceded by an even number of backslashes.
+          v = v.replace(/(\\*)"/g, (m, slashes) =>
+            slashes.length % 2 === 0 ? slashes + '\\"' : m,
+          )
+        }
+        result += `"${v}"`
         continue
       }