hyper-html-api 0.14.0 → 0.15.0

package/src/dom-api.js

@@ -4,9 +4,12 @@ import domAdapter, { createDomAdapter } 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.
+// Calls default `codecs` to the ones registered with engine.codecs.register.
+const withCodecs = (opts) => ({ codecs: engineMod.registeredCodecs(), ...opts })
+
 export const engine = {
-  extract: (root, rules, opts = {}) => engineMod.extract(createDomAdapter(root, opts), root, rules, opts),
-  apply: (root, rules, data, opts = {}) => engineMod.apply(createDomAdapter(root, { ...opts, _write: true }), root, rules, data, opts),
+  extract: (root, rules, opts = {}) => engineMod.extract(createDomAdapter(root, opts), root, rules, withCodecs(opts)),
+  apply: (root, rules, data, opts = {}) => engineMod.apply(createDomAdapter(root, { ...opts, _write: true }), root, rules, data, withCodecs(opts)),
   findRulesIn: (root, token) => engineMod.findRulesIn(domAdapter, root, token),
   findRules: (root, source) => engineMod.resolveRules(domAdapter, root, source),
   bind: (root, source, opts = {}) => {
@@ -15,12 +18,14 @@ export const engine = {
       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 callOpts = withCodecs({ version: found.version, ...opts })
     return {
       ...found,
-      get: () => engineMod.extract(createDomAdapter(root, opts), root, found.rules, opts),
-      set: data => engineMod.apply(createDomAdapter(root, { ...opts, _write: true }), root, found.rules, data, opts),
+      get: () => engineMod.extract(createDomAdapter(root, opts), root, found.rules, callOpts),
+      set: data => engineMod.apply(createDomAdapter(root, { ...opts, _write: true }), root, found.rules, data, callOpts),
     }
   },
+  codecs: { register: engineMod.registerCodec, get: engineMod.getCodec },
   parseStrict: engineMod.parseStrict,
   parseRelaxed: engineMod.parseRelaxed,
   // Adapter-free, like the parsers above: a consumer that has to split a rule
@@ -38,7 +43,7 @@ function defaultRules(root) {
   const searchRoot = root && root.ownerDocument ? root.ownerDocument : root
   const found = engineMod.findRulesIn(domAdapter, searchRoot, 'api')
   if (!found) throw new engineMod.errors.NoRulesTag('api')
-  return found.rules
+  return { rules: found.rules, version: found.version }
 }
 
 function containingTree(root) {
@@ -119,8 +124,8 @@ function assertNoReadOnlyTargets(rule, value) {
   }
 }
 
-function guardedApply(root, rules, data) {
-  const opts = { templateAttr: 'cms-template' }
+function guardedApply(root, rules, data, version) {
+  const opts = withCodecs({ templateAttr: 'cms-template', version })
   const liveTree = containingTree(root)
   const rootPath = childIndexPath(liveTree, root)
   const detachedTree = cloneContainingTree(liveTree)
@@ -145,7 +150,8 @@ function guardedApply(root, rules, data) {
 
 function exposeWriteError(error) {
   if (!(error instanceof Error)) return error
-  const code = error.name || 'Error'
+  const keepsCode = error instanceof engineMod.errors.UnknownCodec || error instanceof engineMod.errors.CodecRefused
+  const code = keepsCode ? error.code : error.name || 'Error'
   try {
     error.code = code
   } catch {
@@ -182,7 +188,10 @@ function exposeWriteError(error) {
 export function extractData(a, b) {
   const root = isNode(a) ? a : document
   const source = isNode(a) ? b : a
-  if (source === undefined) return engineMod.extract(createDomAdapter(root), root, defaultRules(root))
+  if (source === undefined) {
+    const { rules, version } = defaultRules(root)
+    return engineMod.extract(createDomAdapter(root), root, rules, withCodecs({ version }))
+  }
   return engine.bind(root, source).get()
 }
 
@@ -193,8 +202,8 @@ 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.')
     }
-    const rules = source === undefined ? defaultRules(root) : engine.bind(root, source).rules
-    guardedApply(root, rules, data)
+    const { rules, version } = source === undefined ? defaultRules(root) : engine.bind(root, source)
+    guardedApply(root, rules, data, version)
   } catch (error) {
     throw exposeWriteError(error)
   }

package/src/engine/apply.js

@@ -10,13 +10,15 @@ import {
   ShapeMismatch,
 } from './errors.js'
 import { listDiff } from './diff.js'
-import { ruleAttrIndex, splitRule } from './rule-syntax.js'
+import { codecOf, ruleAttrIndex, splitRule } from './rule-syntax.js'
 import { isCustomPropertyName, setStyleVar } from './style-vars.js'
+import { checkCodecRules, codecForRule } from './codecs.js'
 
 export function apply(adapter, root, rules, data, 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.')
   }
+  checkCodecRules(rules, opts)
   const mismatches = []
   validateShape(rules, data, [], mismatches)
   if (mismatches.length) throw new ShapeMismatch(mismatches)
@@ -64,6 +66,13 @@ function applyScalar(adapter, ctx, rule, value, trace, opts) {
     return ctx
   }
 
+  const codec = codecForRule(rule, opts)
+  if (codec) {
+    const matches = codec.selector ? adapter.find(ctx, codec.selector, opts) : [ctx]
+    if (matches.length) codec.codec.write(adapter, matches[0], value, { query: opts.query })
+    return ctx
+  }
+
   if (rule.startsWith('@')) {
     return writePropOrAttr(adapter, ctx, rule.slice(1), value)
   }
@@ -156,6 +165,8 @@ function validateShape(rule, value, path, mismatches) {
   if (value === undefined) return
 
   if (typeof rule === 'string') {
+    // A codec judges its own value when it writes.
+    if (codecOf(rule)) return
     if (rule.endsWith('[]')) {
       if (!Array.isArray(value)) {
         mismatches.push({ path: pathStr(path), expected: 'array', got: typeofX(value) })

package/src/engine/codecs.js

@@ -0,0 +1,80 @@
+import { MAX_RULE_DEPTH, RulesParseError, UnknownCodec } from './errors.js'
+import { codecOf } from './rule-syntax.js'
+
+// A codec reads and writes one element's whole value as JSON, for content the
+// rule grammar cannot describe (a sheet's grid). It is named by the rule form
+// "selector@codec(name)", valid only under data-rules-version="2" and only as the
+// value of a top level key.
+//
+// codec = {
+//   name,
+//   read(adapter, node, ctx)          -> JSON value       ctx = { query?, view?, region? }
+//   write(adapter, node, value, ctx)  -> void | { regions }
+//   patch?(adapter, node, ops, ctx)   -> { changed, stale, regions }
+//   same(written, reread)             -> boolean
+//   styles?: string[]
+//   cut?(src, marker)                 -> { rest, regions }
+// }
+
+const NAME_RE = /^[a-z][a-z0-9-]*$/
+const registry = new Map()
+
+// The browser registry. Hosts pass `codecs` per call instead, so no state is
+// shared between requests.
+export function registerCodec(name, codec) {
+  if (typeof name !== 'string' || !NAME_RE.test(name)) {
+    throw new Error(`hyper-html-api: invalid codec name ${JSON.stringify(name)} (must match ${NAME_RE})`)
+  }
+  if (!codec || typeof codec.read !== 'function' || typeof codec.write !== 'function' || typeof codec.same !== 'function') {
+    throw new Error(`hyper-html-api: codec "${name}" needs read, write and same functions`)
+  }
+  registry.set(name, codec)
+}
+
+export function getCodec(name) {
+  return registry.get(name) ?? null
+}
+
+export function registeredCodecs() {
+  return Object.fromEntries(registry)
+}
+
+export const NEEDS_VERSION_2 = 'The @codec(name) rule form needs a rules tag with data-rules-version="2".'
+export const NEEDS_TOP_LEVEL = 'A @codec(name) rule must be the value of a top level key.'
+
+// The codec a rule names, or null for any other rule. Assumes checkCodecRules
+// already accepted the tree.
+export function codecForRule(rule, opts) {
+  const form = codecOf(rule)
+  return form ? { ...form, codec: opts.codecs[form.name] } : null
+}
+
+// Walks the whole rule tree once, before anything is read or written, so a
+// rules tree the call cannot honor refuses without a partial write. A codec
+// rule read as a plain attribute would return null for the whole value, and a
+// null that reaches a draft store or a guard baseline looks like the owner
+// emptied it, which is why every refusal here is loud.
+export function checkCodecRules(rules, opts = {}) {
+  const version = opts.version ?? '1'
+  const codecs = opts.codecs ?? {}
+  walk(rules, 0)
+
+  function walk(rule, depth) {
+    if (depth > MAX_RULE_DEPTH) return
+    if (typeof rule === 'string') {
+      const form = codecOf(rule)
+      if (!form) return
+      if (version !== '2') throw new RulesParseError(NEEDS_VERSION_2)
+      if (depth !== 1) throw new RulesParseError(NEEDS_TOP_LEVEL)
+      if (!Object.prototype.hasOwnProperty.call(codecs, form.name)) throw new UnknownCodec(form.name)
+      return
+    }
+    if (Array.isArray(rule)) {
+      walk(rule[1], depth + 1)
+      return
+    }
+    if (rule && typeof rule === 'object') {
+      for (const sub of Object.values(rule)) walk(sub, depth + 1)
+    }
+  }
+}

package/src/engine/errors.js

@@ -8,7 +8,7 @@ export class RulesParseError extends Error {
 
 export class UnknownRulesVersion extends Error {
   constructor(version) {
-    super(`unknown rules version: ${version}. Library supports "1".`)
+    super(`unknown rules version: ${version}. Library supports "1" and "2".`)
     this.name = 'UnknownRulesVersion'
     this.version = version
   }
@@ -92,3 +92,22 @@ export class WriteRejected extends Error {
     this.unmatched = unmatched
   }
 }
+
+export class UnknownCodec extends Error {
+  constructor(name) {
+    super(`unknown codec "${name}": no codec by that name is given to this call`)
+    this.name = 'UnknownCodec'
+    this.code = 'unknown-codec'
+    this.codec = name
+  }
+}
+
+// Thrown by a codec that will not take a write, with its own code (for
+// example "sheet-not-canonical"). A client error, like UnknownCodec.
+export class CodecRefused extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = 'CodecRefused'
+    this.code = code
+  }
+}

package/src/engine/extract.js

@@ -2,11 +2,13 @@ import { DOM_PROPERTIES_SET } from './dom-properties.js'
 import { MaxRuleDepthExceeded, MAX_RULE_DEPTH } from './errors.js'
 import { ruleAttrIndex, splitRule } from './rule-syntax.js'
 import { isCustomPropertyName, readStyleVar } from './style-vars.js'
+import { checkCodecRules, codecForRule } from './codecs.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.')
   }
+  checkCodecRules(rules, opts)
   return extractAt(adapter, root, rules, { depth: 0, path: [] }, opts)
 }
 
@@ -57,6 +59,9 @@ function extractScalar(adapter, ctx, rule, trace, opts) {
     return matches.map((n) => adapter.text(n))
   }
 
+  const codec = codecForRule(rule, opts)
+  if (codec) return readCodec(adapter, ctx, codec, opts)
+
   if (rule.startsWith('@')) {
     return readPropOrAttr(adapter, ctx, rule.slice(1))
   }
@@ -79,6 +84,12 @@ function extractScalar(adapter, ctx, rule, trace, opts) {
   return matches.length === 0 ? null : adapter.text(matches[0])
 }
 
+function readCodec(adapter, ctx, { selector, codec }, opts) {
+  const matches = selector ? adapter.find(ctx, selector, opts) : [ctx]
+  if (matches.length === 0) return null
+  return codec.read(adapter, matches[0], { query: opts.query, view: opts.view, region: opts.region })
+}
+
 // 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) {

package/src/engine/index.js

@@ -6,7 +6,9 @@ export { extract } from './extract.js'
 export { apply } from './apply.js'
 export { findRulesIn } from './rules-tag.js'
 export { parseStrict, parseRelaxed } from './rules.js'
-export { ruleAttrIndex, splitRule } from './rule-syntax.js'
+export { ruleAttrIndex, splitRule, codecOf } from './rule-syntax.js'
+export { registerCodec, getCodec, registeredCodecs, checkCodecRules } from './codecs.js'
+export { SUPPORTED_VERSION, SUPPORTED_VERSIONS } from './rules-tag.js'
 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, checkCustomPropertyValue, urlScheme } from './write-policy.js'
@@ -21,7 +23,7 @@ export { trackAdapter, spliceDocument } from './splice.js'
 // 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 }
+    return { rules: source, tagNode: null, version: '1' }
   }
   if (typeof source === 'string') {
     const searchRoot = (root && root.ownerDocument) ? root.ownerDocument : root
@@ -36,11 +38,13 @@ export function bind(adapter, root, source, opts) {
     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
+  const { rules, tagNode, version } = found
+  const callOpts = { version, ...opts }
   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),
+    version,
+    get: () => extract(adapter, root, rules, callOpts),     // opts (skip/templateAttr/codecs) forwarded
+    set: (data) => apply(adapter, root, rules, data, callOpts),
   }
 }

package/src/engine/round-trip.js

@@ -4,7 +4,7 @@ import {
   coercePropValue,
 } from './dom-properties.js'
 import { WriteNotRoundTripped } from './errors.js'
-import { ruleAttrIndex, splitRule } from './rule-syntax.js'
+import { codecOf, ruleAttrIndex, splitRule } from './rule-syntax.js'
 import { isCustomPropertyName } from './style-vars.js'
 
 // Props whose read-side value keeps its whitespace. Every other text rule reads
@@ -18,22 +18,28 @@ const UNTRIMMED_PROPS = new Set(['textContent', 'innerText'])
 // 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.
-export function assertRoundTrip(rules, requested, actual) {
-  check(rules, requested, actual, [])
+// A codec value is compared by its codec's own same(), from `codecs`.
+export function assertRoundTrip(rules, requested, actual, codecs = {}) {
+  check(rules, requested, actual, [], codecs)
 }
 
-function check(rule, want, got, path) {
+function check(rule, want, got, path, codecs) {
   if (want === undefined) return
   if (typeof rule === 'string') {
+    const form = codecOf(rule)
+    if (form) {
+      if (!codecs[form.name].same(want, got)) fail(path)
+      return
+    }
     checkScalarRule(rule, want, got, path)
     return
   }
   if (Array.isArray(rule)) {
-    checkList(rule[1], want, got, path)
+    checkList(rule[1], want, got, path, codecs)
     return
   }
   if (typeof rule === 'object' && rule !== null) {
-    checkObject(rule, want, got, path)
+    checkObject(rule, want, got, path, codecs)
   }
 }
 
@@ -71,16 +77,16 @@ function checkTextList(want, got, path) {
   for (let i = 0; i < want.length; i++) checkText(want[i], got[i], [...path, i])
 }
 
-function checkObject(rule, want, got, path) {
+function checkObject(rule, want, got, path, codecs) {
   if (!isPlainObject(want) || !isPlainObject(got)) fail(path)
   for (const [key, sub] of Object.entries(rule)) {
-    check(sub, want[key], got[key], [...path, key])
+    check(sub, want[key], got[key], [...path, key], codecs)
   }
 }
 
-function checkList(shape, want, got, path) {
+function checkList(shape, want, got, path, codecs) {
   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])
+  for (let i = 0; i < want.length; i++) check(shape, want[i], got[i], [...path, i], codecs)
 }
 
 function checkPropOrAttr(name, want, got, path) {

package/src/engine/rule-syntax.js

@@ -10,6 +10,8 @@
 // rule into `a[href="mailto:hi` and `example.com"]`, which reads downstream as
 // an invalid selector when the rule the author wrote was correct.
 
+import { RulesParseError } from './errors.js'
+
 // Index of the separator "@", or -1 when the rule has no prop part.
 export function ruleAttrIndex(rule) {
   let depth = 0
@@ -122,3 +124,17 @@ function isSingleCompound(selector, start) {
   }
   return true
 }
+
+const CODEC_PROP = /^codec\(([a-z][a-z0-9-]*)\)$/
+
+// { selector, name } when a scalar rule calls a codec, else null.
+export function codecOf(rule) {
+  if (typeof rule !== 'string') return null
+  const at = ruleAttrIndex(rule)
+  if (at === -1) return null
+  const match = CODEC_PROP.exec(rule.slice(at + 1))
+  if (!match) return null
+  const { selector, all } = splitRule(rule)
+  if (all) throw new RulesParseError('A @codec(name) rule cannot use [*].')
+  return { selector, name: match[1] }
+}

package/src/engine/rules-tag.js

@@ -2,6 +2,7 @@ import { parseRelaxed } from './rules.js'
 import { UnknownRulesVersion } from './errors.js'
 
 export const SUPPORTED_VERSION = '1'
+export const SUPPORTED_VERSIONS = ['1', '2']
 const TOKEN_RE = /^[a-zA-Z0-9_-]+$/
 
 // findRulesIn(adapter, root)         → first script[data-rules-name] (tooling/no-token)
@@ -29,12 +30,12 @@ export function findRulesIn(adapter, root, token) {
 
   const tagNode = candidates[0]
   const version = adapter.attr(tagNode, 'data-rules-version')
-  if (version !== SUPPORTED_VERSION) throw new UnknownRulesVersion(version)
+  if (!SUPPORTED_VERSIONS.includes(version)) throw new UnknownRulesVersion(version)
 
   // 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 }
+  return { rules, tagNode, version }
 }

package/src/engine/write-plan.js

@@ -1,4 +1,5 @@
 import { splitRule } from './rule-syntax.js'
+import { checkCodecRules } from './codecs.js'
 
 function isPlainObject(v) {
   return v !== null && typeof v === 'object' && !Array.isArray(v)
@@ -13,6 +14,7 @@ function label(path) {
 // Shape problems are left to apply(), which already reports them. Inside list
 // items only unknown keys are checked, because new rows do not exist yet.
 export function planWrite(adapter, root, rules, data, opts = {}) {
+  checkCodecRules(rules, opts)
   const unknownKeys = []
   const unmatched = []
 

package/src/patch-document.js

@@ -0,0 +1,122 @@
+import cheerioAdapter from './adapters/cheerio.js'
+import { checkCodecRules } from './engine/codecs.js'
+import { CodecRefused, NoRulesTag } from './engine/errors.js'
+import { findRulesIn } from './engine/rules-tag.js'
+import { codecOf } from './engine/rule-syntax.js'
+import { pickTab, sheet, tabNodes } from './codecs/sheet.js'
+import { CodecMiss, QueryRefused, holeMarker, patchGrid, scanGrid } from './codecs/sheet.vendor.js'
+import { holesHold } from './read.js'
+
+export const NOT_CANONICAL_MESSAGE =
+  'This sheet was edited outside the sheet editor, so the API cannot patch it: open the sheet in the editor and save once.'
+
+// Applies a patch list to a sheet document's source, rewriting only the rows it
+// touches. `load` is cheerio.load. patch is
+//   [{ sheet?, range: "B3", values: [[450]] } | { sheet?, append: [["Porto", 12]] }]
+// where `sheet` is a tab name or id (none means the first tab). Values are typed
+// input: null clears, a number or boolean is that value, a string starting with
+// "=" is a formula, any other string is text.
+//
+// options.newId() names appended rows (default: random ids); a test or the
+// conformance runner passes a counter so the output is the same on every run.
+//
+// Returns { html, changed: { cells, rows }, stale: true }: the host cannot
+// recalculate, so every patched table carries `stale` until a browser saves it.
+// Throws before producing output: NoRulesTag; RulesParseError or UnknownCodec for
+// a rules tag that cannot hold a sheet; CodecRefused 'no-sheet' when no single
+// sheet rule matches; QueryRefused (bad_patch, bad_value, bad_range,
+// outside_sheet, covered_cell, unknown_sheet) for a patch the sheet cannot take;
+// CodecRefused 'sheet-not-canonical' (hosts answer 409) for a table edited
+// outside the editor.
+export function patchDocument(load, src, patch, options = {}) {
+  const { token = 'api', newId } = options
+  if (!Array.isArray(patch) || patch.length === 0) {
+    throw new QueryRefused('bad_patch', 'patch is a non-empty list of operations')
+  }
+  const tabs = locateTabs(load, src, token)
+
+  const groups = new Map()
+  for (const op of patch) {
+    if (!op || typeof op !== 'object' || Array.isArray(op)) {
+      throw new QueryRefused('bad_patch', 'an operation is { sheet, range, values } or { sheet, append }')
+    }
+    const { sheet: wanted, ...gridOp } = op
+    const tab = pickTab(tabs, wanted)
+    if (!groups.has(tab)) groups.set(tab, [])
+    groups.get(tab).push(gridOp)
+  }
+
+  const edits = []
+  let cells = 0
+  let rows = 0
+  for (const [tab, ops] of groups) {
+    if (!tab.region) throw new CodecRefused('sheet-not-canonical', NOT_CANONICAL_MESSAGE)
+    const { bytes, changed } = patchGrid(src.slice(tab.region.start, tab.region.end), ops, newId ? { newId } : {})
+    edits.push({ ...tab.region, bytes })
+    cells += changed.cells
+    rows += changed.rows
+  }
+
+  edits.sort((a, b) => b.start - a.start)
+  let html = src
+  for (const edit of edits) html = html.slice(0, edit.start) + edit.bytes + html.slice(edit.end)
+  return { html, changed: { cells, rows }, stale: true }
+}
+
+// [{ id, name, region: { start, end } | null }]: region is where the tab's
+// canonical table sits in src, or null when the table is missing or not canonical.
+// The cut route first, as readDocument reads; when its holes do not verify, one
+// parse with source positions, then a strict scan at each table's start.
+function locateTabs(load, src, token) {
+  const marker = holeMarker(src)
+  const { rest, regions } = sheet.cut(src, marker)
+  if (regions.length > 0) {
+    const $ = load(rest)
+    const root = $.root()
+    const found = findRulesIn(cheerioAdapter, root, token)
+    if (!found) throw new NoRulesTag(token)
+    const container = sheetContainer(root, found)
+    if (holesHold($, root, found.rules, 'sheet', marker, regions.length)) {
+      return tabNodes(cheerioAdapter, container).map(({ id, name, table }) => ({
+        id, name, region: table ? holeRegion(table, marker, regions) : null,
+      }))
+    }
+  }
+
+  const root = load(src, { sourceCodeLocationInfo: true }).root()
+  const found = findRulesIn(cheerioAdapter, root, token)
+  if (!found) throw new NoRulesTag(token)
+  const container = sheetContainer(root, found)
+  return tabNodes(cheerioAdapter, container).map(({ id, name, table }) => ({
+    id, name, region: table ? scannedRegion(table, src) : null,
+  }))
+}
+
+function sheetContainer(root, found) {
+  checkCodecRules(found.rules, { version: found.version, codecs: { sheet } })
+  const rules = found.rules
+  const forms = rules && typeof rules === 'object' && !Array.isArray(rules)
+    ? Object.values(rules).map(codecOf).filter((form) => form && form.name === 'sheet')
+    : []
+  if (forms.length !== 1) throw new CodecRefused('no-sheet', 'this document has no single @codec(sheet) rule to patch')
+  const node = forms[0].selector ? cheerioAdapter.find(root, forms[0].selector)[0] : root
+  if (!node) throw new CodecRefused('no-sheet', "the document's @codec(sheet) rule matches no element")
+  return node
+}
+
+function holeRegion(table, marker, regions) {
+  const hole = cheerioAdapter.attr(table, 'data-hole')
+  if (!hole || !hole.startsWith(`${marker}-`)) return null
+  return regions[Number(hole.slice(marker.length + 1))] ?? null
+}
+
+function scannedRegion(table, src) {
+  const start = table.get(0)?.sourceCodeLocation?.startOffset
+  if (start == null) return null
+  try {
+    return { start, end: scanGrid(src, start) }
+  } catch (error) {
+    if (error instanceof CodecMiss) return null
+    throw error
+  }
+}