hyper-html-api 0.10.0 → 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)
 
@@ -76,17 +78,7 @@ export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, a
   })
 
   if (contiguous) {
-    // 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) => {
-      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)
-    })
+    placeContiguous(adapter, parent, anchorIdx, finalNodes, fresh)
   } else {
     // The matched nodes are not a contiguous run of siblings, so this list has
     // no DOM order to restore: any repositioning would move elements the list
@@ -132,14 +124,13 @@ function lockSuppliedRows(adapter, oldNodes, newItems, trace, opts) {
   if (!Array.isArray(supplied)) return null
   const locked = new Array(newItems.length).fill(-1)
   const taken = new Set()
+  const position = new Map(oldNodes.map((n, j) => [adapter.identity(n), j]))
   for (let i = 0; i < newItems.length; i++) {
     if (!supplied[i]) continue
-    for (let j = 0; j < oldNodes.length; j++) {
-      if (taken.has(j) || !adapter.sameNode(oldNodes[j], supplied[i])) continue
-      locked[i] = j
-      taken.add(j)
-      break
-    }
+    const j = position.get(adapter.identity(supplied[i]))
+    if (j === undefined || taken.has(j)) continue
+    locked[i] = j
+    taken.add(j)
   }
   return locked
 }
@@ -188,19 +179,224 @@ 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
+// this used to, made a list write cost the square of its length.
+//
+// Every surviving node sits at or after its target when its turn comes, because the run started at
+// anchorIdx and the earlier targets are already filled. So removing a node from the copy never
+// shifts the target it is moving to.
+function placeContiguous(adapter, parent, anchorIdx, finalNodes, fresh) {
+  const siblings = adapter.children(parent)
+  const order = siblings.map((s) => adapter.identity(s))
+  // Past the end of the content children, insertAt appends to the very end of the
+  // parent when the parent has no no-data child, which is past any trailing text:
+  // "after the last content child" is NOT what it does there, and the document
+  // has to come out byte-identical. So the first row that lands past the end still
+  // goes through insertAt, and the rows after it follow that node, which is now
+  // the parent's last child. Only one row ever pays for the index insert, because
+  // the targets only move forward and the local copy grows with them.
+  let appended = false
+  finalNodes.forEach((node, i) => {
+    const id = adapter.identity(node)
+    const target = anchorIdx + i
+    if (order[target] === id) return
+    if (!fresh[i]) {
+      const current = order.indexOf(id)
+      if (current !== -1) {
+        order.splice(current, 1)
+        siblings.splice(current, 1)
+      }
+    }
+    const at = Math.min(target, siblings.length)
+    if (at < siblings.length) adapter.insertBefore(siblings[at], node)
+    else if (!siblings.length) adapter.insertAt(parent, node, 0)
+    else if (appended) adapter.insertAfter(siblings[siblings.length - 1], node)
+    else {
+      adapter.insertAt(parent, node, target)
+      appended = true
+    }
+    order.splice(at, 0, id)
+    siblings.splice(at, 0, node)
+  })
+}
+
 // Repositioning only means something when the list occupies a contiguous run of
 // element siblings under one parent. Two containers, or an unowned sibling
 // sitting between two owned nodes, has no list order to restore.
@@ -208,11 +404,11 @@ function isContiguousRun(adapter, nodes) {
   if (nodes.length <= 1) return true
   const parent = adapter.parent(nodes[0])
   if (!parent) return false
-  const siblings = adapter.children(parent)
+  const position = new Map(adapter.children(parent).map((s, i) => [adapter.identity(s), i]))
   const indices = []
   for (const node of nodes) {
-    const i = siblings.findIndex((s) => adapter.sameNode(s, node))
-    if (i === -1) return false
+    const i = position.get(adapter.identity(node))
+    if (i === undefined) return false
     indices.push(i)
   }
   indices.sort((a, b) => a - b)

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/row-match.js

@@ -76,7 +76,8 @@ export function matchRows(newItems, oldValues, shape, locked) {
   // Changed content outranks displacement: the scale is larger than any total
   // displacement this list can produce, so position only ever breaks a tie.
   const scale = n * m + 1
-  const cost = (i, j) => differingFields(newItems[i], oldValues[j], shape) * scale + Math.abs(i - j)
+  const differing = fieldDistance(newItems, oldValues, shape)
+  const cost = (i, j) => differing(i, j) * scale + Math.abs(i - j)
   for (const [i, j] of alignInOrder(leftNew, leftOld, cost)) matches[i] = j
   return matches
 }
@@ -97,17 +98,22 @@ function itemKey(item, shape) {
   )
 }
 
-function differingFields(a, b, shape) {
-  if (!isObjectShape(shape)) return a === b ? 0 : 1
+// How many fields differ between new item i and old item j. Each item's fields are encoded once
+// here: the alignment table asks this for every pair, and encoding per pair made it the dominant
+// cost of a large list.
+function fieldDistance(newItems, oldValues, shape) {
+  if (!isObjectShape(shape)) return (i, j) => (newItems[i] === oldValues[j] ? 0 : 1)
   const fields = Object.keys(shape)
-  if (fields.length === 0) return 0
-  let differing = 0
-  for (const f of fields) {
-    const av = JSON.stringify(a == null ? undefined : a[f])
-    const bv = JSON.stringify(b == null ? undefined : b[f])
-    if (av !== bv) differing++
+  const encode = (item) => fields.map((f) => JSON.stringify(item == null ? undefined : item[f]))
+  const newCodes = newItems.map(encode)
+  const oldCodes = oldValues.map(encode)
+  return (i, j) => {
+    const a = newCodes[i]
+    const b = oldCodes[j]
+    let differing = 0
+    for (let k = 0; k < fields.length; k++) if (a[k] !== b[k]) differing++
+    return differing
   }
-  return differing
 }
 
 // Pair every entry of the shorter list with one of the longer, keeping both in

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
+}