hyper-html-api 0.1.0

package/src/engine/errors.js

@@ -0,0 +1,48 @@
+export class RulesParseError extends Error {
+  constructor(message, originalError) {
+    super(message)
+    this.name = 'RulesParseError'
+    this.cause = originalError
+  }
+}
+
+export class UnknownRulesVersion extends Error {
+  constructor(version) {
+    super(`unknown rules version: ${version}. Library supports "1".`)
+    this.name = 'UnknownRulesVersion'
+    this.version = version
+  }
+}
+
+export class MaxRuleDepthExceeded extends Error {
+  constructor(path) {
+    super(`rule depth exceeded 20 at path: ${path.join('.')}`)
+    this.name = 'MaxRuleDepthExceeded'
+    this.path = path
+  }
+}
+
+export class ShapeMismatch extends Error {
+  constructor(mismatches) {
+    super(`shape mismatch: ${mismatches.length} field(s) failed validation`)
+    this.name = 'ShapeMismatch'
+    this.mismatches = mismatches
+  }
+}
+
+export class EmptyListInsert extends Error {
+  constructor(path) {
+    super(
+      `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
+  }
+}
+
+export class UpgradeAlreadyRegistered extends Error {
+  constructor() {
+    super('upgrade transform already registered; only one registration is allowed per page.')
+    this.name = 'UpgradeAlreadyRegistered'
+  }
+}

package/src/engine/extract.js

@@ -0,0 +1,70 @@
+import { DOM_PROPERTIES_SET } from './dom-properties.js'
+import { MaxRuleDepthExceeded } from './errors.js'
+
+const MAX_DEPTH = 20
+
+export function extract(adapter, root, rules) {
+  return extractAt(adapter, root, rules, { depth: 0, path: [] })
+}
+
+function extractAt(adapter, ctx, rule, trace) {
+  if (trace.depth > MAX_DEPTH) throw new MaxRuleDepthExceeded(trace.path)
+
+  if (typeof rule === 'string') return extractScalar(adapter, ctx, rule)
+
+  if (Array.isArray(rule)) {
+    const [selector, shape] = rule
+    const matches = adapter.find(ctx, selector)
+    return matches.map((node, i) =>
+      extractAt(adapter, node, shape, {
+        depth: trace.depth + 1,
+        path: [...trace.path, i],
+      }),
+    )
+  }
+
+  if (typeof rule === 'object' && rule !== null) {
+    const result = {}
+    for (const [key, sub] of Object.entries(rule)) {
+      result[key] = extractAt(adapter, ctx, sub, {
+        depth: trace.depth + 1,
+        path: [...trace.path, key],
+      })
+    }
+    return result
+  }
+
+  return null
+}
+
+function extractScalar(adapter, ctx, rule) {
+  if (rule.endsWith('[]')) {
+    const selector = rule.slice(0, -2)
+    return adapter.find(ctx, selector).map((n) => adapter.text(n))
+  }
+
+  if (rule.startsWith('@')) {
+    return readPropOrAttr(adapter, ctx, rule.slice(1))
+  }
+
+  if (rule.includes('@')) {
+    const [selector, name] = rule.split('@')
+    const matches = selector ? adapter.find(ctx, selector) : [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)
+  return matches.length === 0 ? null : adapter.text(matches[0])
+}
+
+function readPropOrAttr(adapter, node, name) {
+  if (DOM_PROPERTIES_SET.has(name)) {
+    const v = adapter.prop(node, name)
+    return v == null ? null : String(v)
+  }
+  const v = adapter.attr(node, name)
+  return v ? v : null
+}

package/src/engine/index.js

@@ -0,0 +1,6 @@
+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'

package/src/engine/rules-tag.js

@@ -0,0 +1,18 @@
+import { parseStrict } from './rules.js'
+import { UnknownRulesVersion } from './errors.js'
+
+const RULES_TAG_ID = 'hyper-html-api'
+const SUPPORTED_VERSION = '1'
+
+export function findRulesIn(adapter, root) {
+  const candidates = adapter.find(root, `script#${RULES_TAG_ID}`, { includeRulesTag: true })
+  if (candidates.length === 0) return null
+
+  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)
+  return { rules, tagNode }
+}

package/src/engine/rules.js

@@ -0,0 +1,245 @@
+import { RulesParseError } from './errors.js'
+
+/**
+ * Strict JSON parser for script-tag rules bodies.
+ */
+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}`,
+      e,
+    )
+  }
+}
+
+/**
+ * Relaxed JSON parser for the ?data= URL parameter. Ported verbatim from
+ * the legacy hyperclay/server-lib/data-extractor.js parseExtractionRules()
+ * so existing URLs continue to parse identically.
+ */
+export function parseRelaxed(queryString) {
+  try {
+    return JSON.parse(queryString)
+  } catch (_) {
+    /* fall through to tokenizer */
+  }
+
+  const TokenType = {
+    BRACE_OPEN: '{',
+    BRACE_CLOSE: '}',
+    BRACKET_OPEN: '[',
+    BRACKET_CLOSE: ']',
+    COLON: ':',
+    COMMA: ',',
+    STRING: 'STRING',
+    SELECTOR: 'SELECTOR',
+    IDENTIFIER: 'IDENTIFIER',
+    NUMBER: 'NUMBER',
+    BOOLEAN: 'BOOLEAN',
+  }
+
+  function tokenize(input) {
+    const tokens = []
+    let i = 0
+
+    while (i < input.length) {
+      const char = input[i]
+
+      if (/\s/.test(char)) {
+        i++
+        continue
+      }
+
+      if ('{}'.includes(char)) {
+        tokens.push({ type: char, value: char })
+        i++
+        continue
+      }
+
+      if (char === '[') {
+        let isAttributeSelector = false
+        let j = i + 1
+
+        while (j < input.length && /\s/.test(input[j])) j++
+
+        if (j < input.length && /[a-zA-Z_]/.test(input[j])) {
+          isAttributeSelector = true
+        }
+
+        if (!isAttributeSelector) {
+          tokens.push({ type: char, value: char })
+          i++
+          continue
+        }
+      }
+
+      if (char === ']') {
+        tokens.push({ type: char, value: char })
+        i++
+        continue
+      }
+
+      if (char === ':') {
+        tokens.push({ type: TokenType.COLON, value: char })
+        i++
+        continue
+      }
+
+      if (char === ',') {
+        tokens.push({ type: TokenType.COMMA, value: char })
+        i++
+        continue
+      }
+
+      if (char === '"' || char === "'") {
+        const quote = char
+        let j = i + 1
+        while (j < input.length && input[j] !== quote) {
+          if (input[j] === '\\') j++
+          j++
+        }
+        tokens.push({
+          type: TokenType.STRING,
+          value: input.substring(i + 1, j),
+          quoted: true,
+        })
+        i = j + 1
+        continue
+      }
+
+      let j = i
+      let value
+
+      while (j < input.length && !/[{},]/.test(input[j])) {
+        if (input[j] === ':') {
+          const pseudoSelectors = [
+            ':first',
+            ':last',
+            ':nth-child',
+            ':nth-of-type',
+            ':first-child',
+            ':last-child',
+            ':first-of-type',
+            ':last-of-type',
+            ':only-child',
+            ':only-of-type',
+            ':hover',
+            ':focus',
+            ':active',
+            ':visited',
+            ':disabled',
+            ':enabled',
+            ':checked',
+            ':empty',
+            ':root',
+            ':target',
+            ':not',
+            ':before',
+            ':after',
+            ':nth-last-child',
+            ':nth-last-of-type',
+          ]
+
+          let isPseudoSelector = false
+          for (const pseudo of pseudoSelectors) {
+            const pseudoName = pseudo.substring(1)
+            const afterColon = input.substring(j + 1, j + 1 + pseudoName.length)
+            if (afterColon === pseudoName) {
+              isPseudoSelector = true
+              j += pseudoName.length
+              break
+            }
+          }
+
+          if (!isPseudoSelector) break
+        } else if (input[j] === '[') {
+          j++
+          while (j < input.length && input[j] !== ']') {
+            if (input[j] === '"' || input[j] === "'") {
+              const quote = input[j]
+              j++
+              while (j < input.length && input[j] !== quote) {
+                if (input[j] === '\\') j++
+                j++
+              }
+            }
+            j++
+          }
+          if (j < input.length && input[j] === ']') j++
+        } else {
+          j++
+        }
+      }
+      value = input.substring(i, j)
+
+      let type = TokenType.IDENTIFIER
+
+      if (/^-?\d+(\.\d+)?$/.test(value)) {
+        type = TokenType.NUMBER
+      } else if (value === 'true' || value === 'false' || value === 'null') {
+        type = TokenType.BOOLEAN
+      } else if (/^[.#@\[]|[.#@\[]| /.test(value)) {
+        type = TokenType.SELECTOR
+      }
+
+      tokens.push({ type, value, quoted: false })
+      i = j
+    }
+
+    return tokens
+  }
+
+  function tokensToJSON(tokens) {
+    let result = ''
+
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i]
+
+      if ('{}'.includes(token.type) || '[]'.includes(token.type)) {
+        result += token.value
+        continue
+      }
+
+      if (token.type === TokenType.COLON) {
+        result += token.value
+        continue
+      }
+
+      if (token.type === TokenType.COMMA) {
+        result += token.value
+        continue
+      }
+
+      if (token.type === TokenType.STRING && token.quoted) {
+        result += `"${token.value}"`
+        continue
+      }
+
+      if (token.type === TokenType.NUMBER || token.type === TokenType.BOOLEAN) {
+        result += token.value
+        continue
+      }
+
+      if (token.type === TokenType.SELECTOR || token.type === TokenType.IDENTIFIER) {
+        result += `"${token.value}"`
+        continue
+      }
+
+      result += `"${token.value}"`
+    }
+
+    return result
+  }
+
+  try {
+    const tokens = tokenize(queryString)
+    const jsonString = tokensToJSON(tokens)
+    return JSON.parse(jsonString)
+  } catch (error) {
+    throw new RulesParseError('Invalid extraction rules syntax: ' + error.message, error)
+  }
+}

package/src/hyper-html-api.js

@@ -0,0 +1,39 @@
+import * as engineMod from './engine/index.js'
+import * as upgradeMod from './upgrade/index.js'
+import domAdapter from './adapters/dom.js'
+
+const engine = {
+  extract: (root, rules) => engineMod.extract(domAdapter, root, rules),
+  apply: (root, rules, data) => engineMod.apply(domAdapter, root, rules, data),
+  findRulesIn: (root) => engineMod.findRulesIn(domAdapter, root),
+  parseStrict: engineMod.parseStrict,
+  parseRelaxed: engineMod.parseRelaxed,
+  errors: engineMod.errors,
+  DOM_PROPERTIES: engineMod.DOM_PROPERTIES,
+}
+
+const cms = {}
+
+const upgrade = {
+  registerUpgrade: upgradeMod.registerUpgrade,
+  run: upgradeMod.run,
+  shapeMatch: upgradeMod.shapeMatch,
+  isHelperMode: upgradeMod.isHelperMode,
+}
+
+// Helper-mode auto-boot: when the library loads inside an iframe whose URL
+// carries `?_hyperHtmlApi=upgrade-helper`, we wire up the postMessage handshake
+// immediately so authors don't have to add any boot code themselves. Their
+// `registerUpgrade(...)` calls (which run inline as v2's scripts execute) are
+// captured by the registry before the handshake message fires.
+if (typeof window !== 'undefined' && upgradeMod.isHelperMode(window.location)) {
+  upgradeMod.bootHelper({ win: window, doc: document })
+}
+
+// Named exports ensure the IIFE namespace exposes engine/cms/upgrade as direct
+// properties on the `HyperHtmlApi` global, rather than nesting them under a
+// `.default` key the way `export default` alone would.
+export { engine, cms, upgrade }
+
+const HyperHtmlApi = { engine, cms, upgrade }
+export default HyperHtmlApi

package/src/upgrade/helper.js

@@ -0,0 +1,143 @@
+/**
+ * Helper-mode boot path. When the library loads in an iframe whose URL
+ * includes `?_hyperHtmlApi=upgrade-helper&parentOrigin=...`, it skips its
+ * normal idle state and instead participates in the postMessage protocol
+ * defined in upgrade-plan.md:
+ *
+ *   1. Once the iframe document is ready, post `hha:upgrade-ready` to
+ *      `parentOrigin` with the v2 rules + version + whether a transform
+ *      was registered.
+ *   2. Wait for the parent's `hha:upgrade-data` message carrying v1Data.
+ *   3. Run the registered transform (if any), shape-match against v2's
+ *      rules, then `engine.apply` to the iframe DOM.
+ *   4. Serialize `documentElement.outerHTML` and post `hha:upgrade-result`
+ *      back to the parent.
+ *
+ * Errors at any step bubble out as `hha:upgrade-error`.
+ */
+
+import { findRulesIn } from '../engine/rules-tag.js'
+import { extract } from '../engine/extract.js'
+import { apply } from '../engine/apply.js'
+import domAdapter from '../adapters/dom.js'
+import { getRegisteredTransform } from './registry.js'
+import { shapeMatch } from './shape-match.js'
+
+const HELPER_QUERY = '_hyperHtmlApi'
+const HELPER_VALUE = 'upgrade-helper'
+const PARENT_ORIGIN_QUERY = 'parentOrigin'
+
+export function isHelperMode(loc = typeof location !== 'undefined' ? location : null) {
+  if (!loc) return false
+  try {
+    const params = new URLSearchParams(loc.search)
+    return params.get(HELPER_QUERY) === HELPER_VALUE
+  } catch {
+    return false
+  }
+}
+
+export function getParentOrigin(loc = typeof location !== 'undefined' ? location : null) {
+  if (!loc) return null
+  const params = new URLSearchParams(loc.search)
+  return params.get(PARENT_ORIGIN_QUERY)
+}
+
+export function bootHelper({ win, doc, parentOrigin } = {}) {
+  win = win || (typeof window !== 'undefined' ? window : null)
+  doc = doc || (typeof document !== 'undefined' ? document : null)
+  if (!win || !doc) return
+  parentOrigin = parentOrigin || getParentOrigin(win.location)
+  if (!parentOrigin) return
+
+  const start = () => runHandshake({ win, doc, parentOrigin })
+
+  if (doc.readyState === 'loading') {
+    doc.addEventListener('DOMContentLoaded', start, { once: true })
+  } else {
+    start()
+  }
+}
+
+function runHandshake({ win, doc, parentOrigin }) {
+  let found
+  try {
+    found = findRulesIn(domAdapter, doc.body)
+  } catch (e) {
+    return postError(win, parentOrigin, e)
+  }
+  if (!found) {
+    return postError(
+      win,
+      parentOrigin,
+      new Error('helper-mode: no rules tag in v2 document'),
+    )
+  }
+  const rules = found.rules
+  const version = readMeta(doc, 'hyper-version')
+  const hasTransform = !!getRegisteredTransform()
+
+  const onMessage = (e) => {
+    if (e.source !== win.parent) return
+    if (e.origin !== parentOrigin) return
+    const msg = e.data
+    if (!msg || msg.type !== 'hha:upgrade-data') return
+    win.removeEventListener('message', onMessage)
+    try {
+      const result = runUpgrade({ doc, rules, v1Data: msg.v1Data })
+      win.parent.postMessage(
+        { type: 'hha:upgrade-result', html: result.html, summary: result.summary },
+        parentOrigin,
+      )
+    } catch (err) {
+      postError(win, parentOrigin, err)
+    }
+  }
+  win.addEventListener('message', onMessage)
+
+  win.parent.postMessage(
+    { type: 'hha:upgrade-ready', rules, version, hasTransform },
+    parentOrigin,
+  )
+}
+
+function runUpgrade({ doc, rules, v1Data }) {
+  const transform = getRegisteredTransform()
+  let transformed = v1Data
+  let didTransform = false
+  if (transform) {
+    transformed = transform(v1Data)
+    didTransform = true
+  }
+  const { data, summary } = shapeMatch(transformed, rules)
+  apply(domAdapter, doc.body, rules, data)
+  // Re-extract to confirm the apply landed; surface as part of summary.
+  const applied = extract(domAdapter, doc.body, rules)
+  const html =
+    '<!DOCTYPE html>\n' + doc.documentElement.outerHTML
+  return {
+    html,
+    summary: { ...summary, transformApplied: didTransform, appliedFieldCount: countLeaves(applied) },
+  }
+}
+
+function postError(win, parentOrigin, err) {
+  win.parent.postMessage(
+    { type: 'hha:upgrade-error', name: err?.name || 'Error', message: err?.message || String(err) },
+    parentOrigin,
+  )
+}
+
+function readMeta(doc, name) {
+  const el = doc.querySelector(`meta[name="${name}"]`)
+  return el ? el.getAttribute('content') : null
+}
+
+function countLeaves(v) {
+  if (v == null) return 0
+  if (Array.isArray(v)) return v.reduce((n, x) => n + countLeaves(x), 0)
+  if (typeof v === 'object') {
+    return Object.values(v).reduce((n, x) => n + countLeaves(x), 0)
+  }
+  return 1
+}

package/src/upgrade/index.js

@@ -0,0 +1,4 @@
+export { registerUpgrade, getRegisteredTransform, _resetRegistryForTests } from './registry.js'
+export { shapeMatch } from './shape-match.js'
+export { run } from './runner.js'
+export { isHelperMode, getParentOrigin, bootHelper } from './helper.js'

package/src/upgrade/registry.js

@@ -0,0 +1,19 @@
+import { UpgradeAlreadyRegistered } from '../engine/errors.js'
+
+let registered = null
+
+export function registerUpgrade(fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('registerUpgrade expects a function (v1Data) => v2Data')
+  }
+  if (registered) throw new UpgradeAlreadyRegistered()
+  registered = fn
+}
+
+export function getRegisteredTransform() {
+  return registered
+}
+
+export function _resetRegistryForTests() {
+  registered = null
+}

package/src/upgrade/runner.js

@@ -0,0 +1,92 @@
+/**
+ * Iframe-based upgrade runner.
+ *
+ * Loads the v2 source URL in a hidden iframe with the `_hyperHtmlApi=upgrade-helper`
+ * query param. The helper inside the iframe handles transform + apply +
+ * serialize; the parent only orchestrates the postMessage handshake and
+ * returns the resulting HTML + summary to the caller.
+ *
+ *   const { html, summary } = await run({ sourceUrl, v1Data })
+ *
+ * The caller decides what to do with `html` (e.g. POST to `/save`, render
+ * in a preview pane, etc.). The runner deliberately doesn't touch the
+ * network beyond the iframe load.
+ */
+
+const DEFAULT_TIMEOUT_MS = 15000
+
+export async function run({
+  sourceUrl,
+  v1Data,
+  v1Version = null,
+  parent = typeof window !== 'undefined' ? window : null,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  hidden = true,
+} = {}) {
+  if (!parent) throw new Error('upgrade.run requires a window context')
+  if (!sourceUrl) throw new Error('upgrade.run requires sourceUrl')
+
+  const helperUrl = buildHelperUrl(sourceUrl, parent.location.origin)
+  const expectedOrigin = new URL(helperUrl, parent.location.href).origin
+
+  const iframe = parent.document.createElement('iframe')
+  if (hidden) {
+    iframe.style.cssText =
+      'position:absolute;left:-9999px;top:-9999px;width:1px;height:1px;border:0;'
+  }
+  iframe.setAttribute('aria-hidden', 'true')
+  iframe.src = helperUrl
+  parent.document.body.appendChild(iframe)
+
+  let cleanup = () => {}
+  try {
+    return await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`upgrade.run: helper iframe timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+
+      const onMessage = (e) => {
+        if (e.source !== iframe.contentWindow) return
+        if (e.origin !== expectedOrigin) return
+        const msg = e.data
+        if (!msg || typeof msg !== 'object') return
+
+        if (msg.type === 'hha:upgrade-ready') {
+          iframe.contentWindow.postMessage(
+            { type: 'hha:upgrade-data', v1Data, v1Version },
+            expectedOrigin,
+          )
+          return
+        }
+        if (msg.type === 'hha:upgrade-result') {
+          clearTimeout(timer)
+          resolve({ html: msg.html, summary: msg.summary })
+          return
+        }
+        if (msg.type === 'hha:upgrade-error') {
+          clearTimeout(timer)
+          const err = new Error(msg.message || 'helper error')
+          err.name = msg.name || 'UpgradeHelperError'
+          reject(err)
+          return
+        }
+      }
+
+      parent.addEventListener('message', onMessage)
+      cleanup = () => {
+        parent.removeEventListener('message', onMessage)
+        clearTimeout(timer)
+        if (iframe.parentNode) iframe.parentNode.removeChild(iframe)
+      }
+    })
+  } finally {
+    cleanup()
+  }
+}
+
+function buildHelperUrl(sourceUrl, parentOrigin) {
+  const url = new URL(sourceUrl, typeof location !== 'undefined' ? location.href : undefined)
+  url.searchParams.set('_hyperHtmlApi', 'upgrade-helper')
+  url.searchParams.set('parentOrigin', parentOrigin)
+  return url.toString()
+}