hyper-html-api 0.6.5 → 0.8.1

package/src/engine/diff.js

@@ -1,7 +1,6 @@
 import { EmptyListInsert } from './errors.js'
 import { extract } from './extract.js'
-
-const SIMILARITY_THRESHOLD = 0.5
+import { matchRows } from './row-match.js'
 
 /**
  * Reconcile `newItems` (array of incoming items) into the DOM subtree matched
@@ -16,6 +15,8 @@ export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, a
 
   if (newItems.length === 0) {
     oldNodes.forEach((n) => adapter.remove(n))
+    // Still once per list: a consumer keyed by path has to learn it settled empty.
+    callHook(opts, 'onRowsApplied', trace.path, [])
     return
   }
 
@@ -28,8 +29,11 @@ export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, a
 
   const oldValues = oldNodes.map((n) => extractItem(adapter, n, shape, opts))
 
+  // Only a list that grew can need a clone, because matchRows pairs every row
+  // it can. Cloning unconditionally made a plain edit strip the ids off a
+  // template it never used, and warn about it, on every keystroke.
   let template = null
-  if (templateSource) {
+  if (needsTemplate && templateSource) {
     template = adapter.clone(templateSource)
     if (opts.templateAttr) adapter.removeAttr(template, opts.templateAttr)
     const stripped = adapter.stripIds(template)
@@ -41,7 +45,7 @@ export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, a
     }
   }
 
-  const matches = greedyMatch(newItems, oldValues, shape)
+  const matches = matchRows(newItems, oldValues, shape, lockSuppliedRows(adapter, oldNodes, newItems, trace, opts))
 
   const referenceNode = oldNodes[0] || templateSource
   const parent = adapter.parent(referenceNode)
@@ -83,19 +87,61 @@ export function listDiff(adapter, parentCtx, selector, shape, newItems, trace, a
       if (currentIdx === targetIdx) return
       adapter.insertAt(parent, node, targetIdx)
     })
-    writeItems(adapter, finalNodes, shape, newItems, trace, applyItem, opts)
-    return
+  } 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
+    // does not own. Anchoring every node to parent(oldNodes[0]) is what
+    // reparents a cross-parent list into its first container and compacts past
+    // unowned siblings, and both destroy content on a write that changed
+    // nothing. Leave every surviving node exactly where the author put it and
+    // only place the grown ones.
+    placeGrownItems(adapter, finalNodes, fresh, parent, anchorIdx)
   }
 
-  // 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 does
-  // not own. Anchoring every node to parent(oldNodes[0]) is what reparents a
-  // cross-parent list into its first container and compacts past unowned
-  // siblings, and both destroy content on a write that changed nothing. Leave
-  // every surviving node exactly where the author put it and only place the
-  // grown ones.
-  placeGrownItems(adapter, finalNodes, fresh, parent, anchorIdx)
   writeItems(adapter, finalNodes, shape, newItems, trace, applyItem, opts)
+
+  // writeItems can replace a node (@outerHTML on the item itself) and updates
+  // finalNodes in place, so this reports the nodes the list actually ended with.
+  callHook(opts, 'onRowsApplied', trace.path, finalNodes)
+}
+
+// Consumer code runs in the middle of an engine write, and onRowsApplied runs
+// after the list is already written. Letting it throw left the page written and
+// the apply reported as failed, which in hypercms meant an error banner, a stale
+// fingerprint, and a page that no longer matched it. A hook is an optional
+// report; a broken one is the consumer's bug to see, not a reason to abandon a
+// finished write.
+function callHook(opts, name, path, arg) {
+  if (typeof opts[name] !== 'function') return undefined
+  try {
+    return opts[name](path.slice(), arg)
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(`[hyper-html-api] ${name} threw at "${path.join('.') || '(root)'}"`, err)
+    return undefined
+  }
+}
+
+// A caller that already knows which node each incoming item belongs to can say
+// so, and content matching cannot tell two byte-identical rows apart however
+// good it gets. `identifyRows` returns an array parallel to newItems of
+// Node | null. A node that is not in this list right now is ignored, so a stale
+// handle degrades to matching rather than corrupting the list.
+function lockSuppliedRows(adapter, oldNodes, newItems, trace, opts) {
+  const supplied = callHook(opts, 'identifyRows', trace.path, newItems)
+  if (!Array.isArray(supplied)) return null
+  const locked = new Array(newItems.length).fill(-1)
+  const taken = new Set()
+  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
+    }
+  }
+  return locked
 }
 
 // Apply per-item content. Skip when the existing value already matches
@@ -120,46 +166,13 @@ function writeItems(adapter, finalNodes, shape, newItems, trace, applyItem, opts
 
 function extractItem(adapter, node, shape, opts) {
   if (shape === null) return adapter.text(node)
-  return extract(adapter, node, shape, opts)
-}
-
-function greedyMatch(newItems, oldValues, shape) {
-  const matches = new Array(newItems.length).fill(-1)
-  const taken = new Set()
-  newItems.forEach((newItem, i) => {
-    let bestIdx = -1
-    let bestScore = -1
-    oldValues.forEach((oldVal, j) => {
-      if (taken.has(j)) return
-      const score = similarity(newItem, oldVal, shape)
-      const closerIdx =
-        score === bestScore && bestIdx >= 0
-          ? Math.abs(j - i) < Math.abs(bestIdx - i)
-          : false
-      if (score > bestScore || closerIdx) {
-        bestScore = score
-        bestIdx = j
-      }
-    })
-    if (bestScore >= SIMILARITY_THRESHOLD) {
-      matches[i] = bestIdx
-      taken.add(bestIdx)
-    }
-  })
-  return matches
-}
-
-function similarity(a, b, shape) {
-  if (shape === null) return a === b ? 1 : 0
-  const fields = Object.keys(shape || {})
-  if (fields.length === 0) return 0
-  let equal = 0
-  for (const f of fields) {
-    if (JSON.stringify(a == null ? undefined : a[f]) === JSON.stringify(b == null ? undefined : b[f])) {
-      equal++
-    }
-  }
-  return equal / fields.length
+  // This is a per-row read whose path restarts at the row, so a caller's
+  // onRowsRead would see a nested list under a truncated path and bind it to the
+  // wrong parent. The read hook belongs to a top-level extract only, and
+  // engine.bind() hands one opts object to both halves, so the caller cannot
+  // always keep them apart. Drop it here instead of documenting a rule the API
+  // does not let everyone follow.
+  return extract(adapter, node, shape, opts.onRowsRead ? { ...opts, onRowsRead: undefined } : opts)
 }
 
 function indexInParent(adapter, parent, targetNode) {

package/src/engine/extract.js

@@ -3,17 +3,27 @@ import { MaxRuleDepthExceeded, MAX_RULE_DEPTH } from './errors.js'
 import { ruleAttrIndex } from './rule-syntax.js'
 
 export function extract(adapter, root, rules, opts = {}) {
+  if (Object.prototype.hasOwnProperty.call(opts, 'exclude') && adapter.semanticExclude === false) {
+    throw new Error('This adapter does not support semantic exclude queries; omit exclude or use the DOM adapter.')
+  }
   return extractAt(adapter, root, rules, { depth: 0, path: [] }, opts)
 }
 
 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, opts)
+  if (typeof rule === 'string') return extractScalar(adapter, ctx, rule, trace, opts)
 
   if (Array.isArray(rule)) {
     const [selector, shape] = rule
     const matches = adapter.find(ctx, selector, opts)
+    // The read-side mirror of apply's onRowsApplied: it tells a caller which
+    // node each item came from, so identity can be established before anything
+    // is written. Only pass this to a TOP-LEVEL extract. listDiff extracts each
+    // existing row through this same function with a fresh path, so an opts
+    // carrying this hook into apply() would report nested lists under a
+    // truncated path.
+    reportRows(opts, trace, matches)
     return matches.map((node, i) =>
       extractAt(adapter, node, shape, {
         depth: trace.depth + 1,
@@ -36,10 +46,14 @@ function extractAt(adapter, ctx, rule, trace, opts) {
   return null
 }
 
-function extractScalar(adapter, ctx, rule, opts) {
+function extractScalar(adapter, ctx, rule, trace, opts) {
   if (rule.endsWith('[]')) {
     const selector = rule.slice(0, -2)
-    return adapter.find(ctx, selector, opts).map((n) => adapter.text(n))
+    const matches = adapter.find(ctx, selector, opts)
+    // A scalar list is still a list, and its rows still need identity. Reported
+    // here as well as in the tuple branch, because this one returns before it.
+    reportRows(opts, trace, matches)
+    return matches.map((n) => adapter.text(n))
   }
 
   if (rule.startsWith('@')) {
@@ -61,6 +75,18 @@ function extractScalar(adapter, ctx, rule, opts) {
   return matches.length === 0 ? null : adapter.text(matches[0])
 }
 
+// The path is copied because the caller is handed it and every nested path is
+// built from the same array. A throwing hook must not abandon the extract.
+function reportRows(opts, trace, nodes) {
+  if (typeof opts.onRowsRead !== 'function') return
+  try {
+    opts.onRowsRead(trace.path.slice(), nodes)
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(`[hyper-html-api] onRowsRead threw at "${trace.path.join('.') || '(root)'}"`, err)
+  }
+}
+
 function readPropOrAttr(adapter, node, name) {
   if (DOM_PROPERTIES_SET.has(name)) {
     const v = adapter.prop(node, name)

package/src/engine/index.js

@@ -8,7 +8,7 @@ export { findRulesIn } from './rules-tag.js'
 export { parseStrict, parseRelaxed } from './rules.js'
 export { ruleAttrIndex, splitRule } from './rule-syntax.js'
 export * as errors from './errors.js'
-export { DOM_PROPERTIES, DOM_PROPERTIES_SET } from './dom-properties.js'
+export { DOM_PROPERTIES, DOM_PROPERTIES_SET, DOM_PROPERTIES_READ_ONLY_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

package/src/engine/row-match.js

@@ -0,0 +1,155 @@
+/**
+ * Map incoming list items onto the existing rows a list already has.
+ *
+ * A list arrives as plain JSON with no ids, so identity has to be inferred.
+ * The rule this file follows is that a list creates a node only when it grows
+ * and destroys one only when it shrinks: `matchRows` always pairs
+ * min(newItems.length, oldValues.length) rows. Content decides WHICH old row a
+ * new item is, never WHETHER it is one, because the field a person is editing
+ * is the same field that would have to prove who the row is.
+ *
+ * Two passes:
+ *   A. anchors, content appearing exactly once on each side is unambiguous and
+ *      matches wherever it moved to (this is what carries a reorder)
+ *   B. everything left over, aligned in order at minimum cost, so surviving
+ *      rows keep their relative order and edits stay put
+ */
+
+export function matchRows(newItems, oldValues, shape, locked) {
+  const n = newItems.length
+  const m = oldValues.length
+  const matches = new Array(n).fill(-1)
+  // A caller that knows which old row an item is keeps that pairing; the passes
+  // below only fill in what it did not answer for. Range-checked and deduped so
+  // the min(n, m) guarantee in the header holds for any `locked`, not only the
+  // sanitised one lockSuppliedRows produces.
+  if (locked) {
+    const seen = new Set()
+    for (let i = 0; i < n; i++) {
+      const j = locked[i]
+      if (!(j >= 0 && j < m) || seen.has(j)) continue
+      matches[i] = j
+      seen.add(j)
+    }
+  }
+  if (n === 0 || m === 0) return matches
+
+  const newKeys = newItems.map((item) => itemKey(item, shape))
+  const oldKeys = oldValues.map((item) => itemKey(item, shape))
+
+  const takenOld = new Array(m).fill(false)
+  for (const j of matches) if (j >= 0) takenOld[j] = true
+
+  // Uniqueness is counted over the rows still in play, never over the locked
+  // ones. A value can be duplicated across the whole list and still be the only
+  // unlocked row of its kind, and that is exactly the case a lock should make
+  // decidable: locking one of two identical rows leaves the other unambiguous.
+  // Counting the locked rows too left it looking as ambiguous as before, and
+  // since alignInOrder only ever produces order-preserving pairs, losing the
+  // anchor loses the ability to express a crossing move at all.
+  const oldByKey = new Map()
+  oldKeys.forEach((key, j) => {
+    if (takenOld[j]) return
+    oldByKey.set(key, oldByKey.has(key) ? -1 : j)
+  })
+  const newCounts = new Map()
+  newKeys.forEach((key, i) => {
+    if (matches[i] >= 0) return
+    newCounts.set(key, (newCounts.get(key) || 0) + 1)
+  })
+
+  newKeys.forEach((key, i) => {
+    if (matches[i] >= 0) return
+    if (newCounts.get(key) !== 1) return
+    const j = oldByKey.get(key)
+    if (j === undefined || j === -1 || takenOld[j]) return
+    matches[i] = j
+    takenOld[j] = true
+  })
+
+  const leftNew = []
+  for (let i = 0; i < n; i++) if (matches[i] < 0) leftNew.push(i)
+  const leftOld = []
+  for (let j = 0; j < m; j++) if (!takenOld[j]) leftOld.push(j)
+  if (leftNew.length === 0 || leftOld.length === 0) return matches
+
+  // 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)
+  for (const [i, j] of alignInOrder(leftNew, leftOld, cost)) matches[i] = j
+  return matches
+}
+
+// An item is an object only when its shape is one. Both `".r[]"` and
+// `[".r", "."]` produce string items, and Object.keys('.') is ["0"], which
+// compared the first CHARACTER of two strings as though it were a field.
+const isObjectShape = (shape) => typeof shape === 'object' && shape !== null
+
+function itemKey(item, shape) {
+  if (!isObjectShape(shape)) return item == null ? ' null' : String(item)
+  const fields = Object.keys(shape)
+  return JSON.stringify(
+    fields.map((f) => {
+      const encoded = JSON.stringify(item == null ? undefined : item[f])
+      return encoded === undefined ? ' undef' : encoded
+    }),
+  )
+}
+
+function differingFields(a, b, shape) {
+  if (!isObjectShape(shape)) return a === b ? 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++
+  }
+  return differing
+}
+
+// Pair every entry of the shorter list with one of the longer, keeping both in
+// order and minimising total cost. Returns [newIndex, oldIndex] pairs.
+function alignInOrder(newIdx, oldIdx, cost) {
+  if (newIdx.length <= oldIdx.length) return align(newIdx, oldIdx, cost, false)
+  return align(oldIdx, newIdx, (j, i) => cost(i, j), true)
+}
+
+function align(short, long, cost, flipped) {
+  const s = short.length
+  const l = long.length
+  const table = []
+  for (let i = 0; i <= s; i++) table.push(new Float64Array(l + 1).fill(Infinity))
+  const takeHere = []
+  for (let i = 0; i <= s; i++) takeHere.push(new Uint8Array(l + 1))
+  for (let j = 0; j <= l; j++) table[s][j] = 0
+
+  for (let i = s - 1; i >= 0; i--) {
+    for (let j = l - 1; j >= 0; j--) {
+      const take = cost(short[i], long[j]) + table[i + 1][j + 1]
+      const skip = table[i][j + 1]
+      if (take <= skip) {
+        table[i][j] = take
+        takeHere[i][j] = 1
+      } else {
+        table[i][j] = skip
+      }
+    }
+  }
+
+  const pairs = []
+  let i = 0
+  let j = 0
+  while (i < s && j < l) {
+    if (takeHere[i][j]) {
+      pairs.push(flipped ? [long[j], short[i]] : [short[i], long[j]])
+      i++
+      j++
+    } else {
+      j++
+    }
+  }
+  return pairs
+}

package/src/lib/content-dom.js

@@ -0,0 +1,110 @@
+// GENERATED from clayjs/src/lib/content-dom.js. Edit ClayJS and run `npm run propagate:foundation`.
+
+import { capabilitySelector, hasCapability } from './region-capabilities.js'
+
+const UNSUPPORTED_SELECTOR = /:(?:focus(?:-within|-visible)?|hover|active|visited|defined)\b/i
+
+function copyControlState(source, copy) {
+  if (!/^(INPUT|TEXTAREA|SELECT|OPTION)$/.test(source.tagName || '')) return
+  const type = (source.getAttribute?.('type') || '').toLowerCase()
+  if ('value' in source && 'value' in copy && source.tagName !== 'OPTION' && type !== 'checkbox' && type !== 'radio') copy.value = source.value
+  if ('checked' in source && 'checked' in copy) copy.checked = source.checked
+  if ('selected' in source && 'selected' in copy) copy.selected = source.selected
+  if (source.tagName === 'SELECT') {
+    for (let i = 0; i < source.options.length; i++) copy.options[i].selected = source.options[i].selected
+  }
+  if ('indeterminate' in source && 'indeterminate' in copy) copy.indeterminate = source.indeterminate
+}
+
+function matchesWithin(node, selector, boundary, inherit) {
+  if (inherit) return !!node.closest?.(selector)
+  let current = node
+  while (current?.nodeType === 1) {
+    if (current.matches(selector)) return true
+    if (current === boundary) break
+    current = current.parentElement
+  }
+  return false
+}
+
+function importTree(source, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps) {
+  if (source.nodeType === 1 && (
+    (inherit ? hasCapability(source, capability) : matchesWithin(source, capabilityMatch, boundary, false)) ||
+    (exclude && matchesWithin(source, exclude, boundary, inherit))
+  )) return null
+  const copy = targetDocument.importNode(source, false)
+  maps.cloneToLive.set(copy, source)
+  maps.liveToClone.set(source, copy)
+  const sourceChildren = source.nodeType === 1 && source.tagName === 'TEMPLATE' ? source.content : source
+  const copyChildren = copy.nodeType === 1 && copy.tagName === 'TEMPLATE' ? copy.content : copy
+  if (sourceChildren !== source) {
+    maps.cloneToLive.set(copyChildren, sourceChildren)
+    maps.liveToClone.set(sourceChildren, copyChildren)
+  }
+  for (const child of sourceChildren.childNodes || []) {
+    const childCopy = importTree(child, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps)
+    if (childCopy) {
+      copyChildren.appendChild(childCopy)
+      if (child.nodeType === 1) copyControlState(child, childCopy)
+    }
+  }
+  if (source.nodeType === 1) copyControlState(source, copy)
+  return copy
+}
+
+export function createContentView(context, { capability = 'data', exclude = null, inherit = true } = {}) {
+  if (!context) throw new TypeError('createContentView requires a DOM context')
+  const sourceDocument = context.nodeType === 9 ? context : context.ownerDocument
+  if (!sourceDocument?.implementation?.createHTMLDocument) {
+    throw new TypeError('createContentView requires an HTML DOM implementation')
+  }
+  const inertDocument = sourceDocument.implementation.createHTMLDocument('')
+  const cloneToLive = new WeakMap()
+  const liveToClone = new WeakMap()
+  const sourceRoot = context.nodeType === 9 ? context.documentElement : context
+  if (exclude) inertDocument.documentElement.matches(exclude)
+  const capabilityMatch = capabilitySelector(capability)
+  const root = importTree(sourceRoot, inertDocument, capability, capabilityMatch, exclude, sourceRoot, inherit, { cloneToLive, liveToClone })
+  if (context.nodeType === 9 && root) {
+    inertDocument.replaceChild(root, inertDocument.documentElement)
+    liveToClone.set(context, inertDocument)
+    cloneToLive.set(inertDocument, context)
+  }
+
+  const assertSelector = selector => {
+    if (UNSUPPORTED_SELECTOR.test(selector)) {
+      throw new Error(`Filtered content queries do not support stateful selector: ${selector}`)
+    }
+  }
+
+  return {
+    root,
+    document: inertDocument,
+    capability,
+    selector: capabilitySelector(capability),
+    cloneToLive,
+    liveToClone,
+    original(node) { return cloneToLive.get(node) || null },
+    cloneOf(node) { return liveToClone.get(node) || null },
+    query(selector, queryRoot = root) {
+      assertSelector(selector)
+      return Array.from(queryRoot.querySelectorAll(selector), node => cloneToLive.get(node) || node)
+    },
+    text(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected?.textContent || ''
+    },
+    html(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected?.innerHTML ?? ''
+    },
+    clone(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected ? inertDocument.importNode(projected, true) : null
+    },
+  }
+}
+
+export function cleanContentClone(node, options) {
+  return createContentView(node, options).root
+}

package/src/lib/region-capabilities.js

@@ -0,0 +1,71 @@
+// GENERATED from clayjs/src/lib/region-capabilities.js. Edit ClayJS and run `npm run propagate:foundation`.
+
+export const CAPABILITIES = Object.freeze({
+  data: Object.freeze({ tokens: ['no-data'], bundles: ['editor-ui'] }),
+  save: Object.freeze({ tokens: ['no-save'], bundles: ['editor-ui'] }),
+  snapshot: Object.freeze({ tokens: ['no-snapshot'], bundles: ['editor-ui'] }),
+  watch: Object.freeze({ tokens: ['no-watch'], bundles: ['editor-ui'] }),
+  undo: Object.freeze({ tokens: ['no-undo'], bundles: ['editor-ui'] }),
+  history: Object.freeze({ tokens: [], bundles: ['editor-ui'] }),
+})
+
+export const BUNDLES = Object.freeze({
+  'editor-ui': Object.freeze(['no-data', 'no-save', 'no-snapshot', 'no-watch', 'no-undo']),
+})
+
+export const POLICY_TOKENS = Object.freeze([
+  'no-save',
+  'no-snapshot',
+  'no-trigger-autosave',
+  'no-dirty',
+  'no-watch',
+  'no-undo',
+  'no-data',
+  'freeze',
+  'editor-ui',
+])
+
+export function hasPolicyToken(element, token) {
+  if (!element || element.nodeType !== 1) return false
+  const clay = element.getAttribute?.('clay')
+  return !!(
+    (clay && clay.split(/\s+/).includes(token)) ||
+    element.hasAttribute?.(token)
+  )
+}
+
+export function expandsTo(element, token) {
+  if (hasPolicyToken(element, token)) return true
+  for (const [bundle, members] of Object.entries(BUNDLES)) {
+    if (members.includes(token) && hasPolicyToken(element, bundle)) return true
+  }
+  return false
+}
+
+export function capabilitySelector(capability) {
+  const definition = CAPABILITIES[capability]
+  if (!definition) throw new Error(`Unknown region capability: ${capability}`)
+  return [...definition.tokens, ...definition.bundles]
+    .flatMap(token => [`[clay~="${token}"]`, `[${token}]`])
+    .join(', ')
+}
+
+export function closestWithCapability(node, capability) {
+  let element = node && node.nodeType === 1 ? node : node?.parentElement
+  while (element && element.nodeType === 1) {
+    const definition = CAPABILITIES[capability]
+    if (!definition) throw new Error(`Unknown region capability: ${capability}`)
+    if (definition.tokens.some(token => expandsTo(element, token)) ||
+        definition.bundles.some(bundle => hasPolicyToken(element, bundle))) return element
+    element = element.parentElement
+  }
+  return null
+}
+
+export function hasCapability(node, capability) {
+  return !!closestWithCapability(node, capability)
+}
+
+export function isPolicyAttribute(name) {
+  return name === 'clay' || POLICY_TOKENS.includes(name)
+}