hyper-html-api 0.3.0 → 0.5.0

package/src/upgrade/check.js

@@ -0,0 +1,116 @@
+/**
+ * Load-time update check. Reads the page's hyper-source / hyper-version meta
+ * tags, fetches the source anonymously, and compares versions. Results are
+ * cached in localStorage for 24 hours, keyed by source + current version so
+ * a fresh check happens immediately after an upgrade.
+ *
+ * Returns null whenever the subsystem should stay inert: missing meta tags,
+ * the page IS the canonical source, an unreachable/private source, or
+ * unparseable versions. Callers (the popover UI) never need to distinguish
+ * these cases.
+ */
+
+const CHECK_TTL_MS = 24 * 60 * 60 * 1000
+const CHECK_KEY_PREFIX = 'hha:upgrade-check:'
+
+export function readMeta(doc, name) {
+  const el = doc.querySelector(`meta[name="${name}"]`)
+  const content = el ? el.getAttribute('content') : null
+  return content && content.trim() ? content.trim() : null
+}
+
+export function parseVersion(v) {
+  if (typeof v !== 'string') return null
+  const cleaned = v.trim().replace(/^v/, '')
+  if (!/^\d+(\.\d+)*$/.test(cleaned)) return null
+  return cleaned.split('.').map(Number)
+}
+
+export function isNewerVersion(candidate, current) {
+  const a = parseVersion(candidate)
+  const b = parseVersion(current)
+  if (!a || !b) return false
+  const len = Math.max(a.length, b.length)
+  for (let i = 0; i < len; i++) {
+    const x = a[i] || 0
+    const y = b[i] || 0
+    if (x !== y) return x > y
+  }
+  return false
+}
+
+function storageGet(key) {
+  try {
+    const raw = globalThis.localStorage.getItem(key)
+    return raw ? JSON.parse(raw) : null
+  } catch {
+    return null
+  }
+}
+
+function storageSet(key, value) {
+  try {
+    globalThis.localStorage.setItem(key, JSON.stringify(value))
+  } catch {
+    /* storage unavailable (private mode): every check is uncached */
+  }
+}
+
+export async function checkForUpdate({
+  force = false,
+  doc,
+  loc,
+  fetchFn,
+  now,
+  ttlMs = CHECK_TTL_MS,
+} = {}) {
+  doc = doc || (typeof document !== 'undefined' ? document : null)
+  loc = loc || (typeof location !== 'undefined' ? location : null)
+  fetchFn = fetchFn || ((url) => fetch(url))
+  now = now ?? Date.now()
+  if (!doc) return null
+
+  const sourceUrl = readMeta(doc, 'hyper-source')
+  if (!sourceUrl) return null
+  const currentVersion = readMeta(doc, 'hyper-version')
+
+  let source
+  try {
+    source = new URL(sourceUrl, loc ? loc.href : undefined)
+  } catch {
+    return null
+  }
+  // Self-source guard: the canonical page carries a self-pointing
+  // hyper-source; it must never offer to upgrade from itself.
+  if (loc && source.origin === loc.origin && source.pathname === loc.pathname) {
+    return null
+  }
+
+  const cacheKey = `${CHECK_KEY_PREFIX}${source.href}:${currentVersion || 'none'}`
+  let sourceVersion
+  const cached = force ? null : storageGet(cacheKey)
+  if (cached && typeof cached.checkedAt === 'number' && now - cached.checkedAt < ttlMs) {
+    sourceVersion = cached.sourceVersion
+  } else {
+    try {
+      const res = await fetchFn(source.href)
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const text = await res.text()
+      const sourceDoc = new DOMParser().parseFromString(text, 'text/html')
+      sourceVersion = readMeta(sourceDoc, 'hyper-version')
+    } catch {
+      sourceVersion = null
+    }
+    storageSet(cacheKey, { checkedAt: now, sourceVersion })
+  }
+
+  if (!sourceVersion) return null
+  return {
+    // A fork without a hyper-version predates versioning: any source version
+    // counts as newer.
+    available: isNewerVersion(sourceVersion, currentVersion || '0.0.0'),
+    currentVersion,
+    sourceVersion,
+    sourceUrl: source.href,
+  }
+}

package/src/upgrade/errors.js

@@ -0,0 +1,36 @@
+export class UpgradeSourceUnreachable extends Error {
+  constructor(url, cause) {
+    super(`could not fetch upgrade source: ${url}`)
+    this.name = 'UpgradeSourceUnreachable'
+    this.sourceUrl = url
+    this.cause = cause
+  }
+}
+
+export class UpgradeSourceHasNoRules extends Error {
+  constructor(url) {
+    super(
+      `upgrade source has no rules tags; refusing to drop all existing data: ${url}`,
+    )
+    this.name = 'UpgradeSourceHasNoRules'
+    this.sourceUrl = url
+  }
+}
+
+export class UpgradeTransformInvalid extends Error {
+  constructor(message, cause) {
+    super(message)
+    this.name = 'UpgradeTransformInvalid'
+    this.cause = cause
+  }
+}
+
+export class UpgradeMultipleTransforms extends Error {
+  constructor(count) {
+    super(
+      `found ${count} script[type="text/hyper-upgrade"] tags; only one is allowed per document.`,
+    )
+    this.name = 'UpgradeMultipleTransforms'
+    this.count = count
+  }
+}

package/src/upgrade/extract-all.js

@@ -0,0 +1,26 @@
+import { extract } from '../engine/extract.js'
+import domAdapter from '../adapters/dom.js'
+import { collectRulesTags } from './rules-tags.js'
+import { readMeta } from './check.js'
+
+/**
+ * Keyed extraction: one entry per rules tag under `root`, keyed by the
+ * normalized data-rules-name value. This is the v1 side of an upgrade:
+ * pack the page's data into labeled boxes.
+ */
+export function extractAllFrom(adapter, root) {
+  const dataByName = {}
+  for (const { name, rules } of collectRulesTags(adapter, root)) {
+    dataByName[name] = extract(adapter, root, rules)
+  }
+  return dataByName
+}
+
+export function extractAll(root) {
+  const r = root || document
+  const doc = r.nodeType === 9 ? r : r.ownerDocument || r
+  return {
+    dataByName: extractAllFrom(domAdapter, r),
+    version: readMeta(doc, 'hyper-version'),
+  }
+}

package/src/upgrade/index.js

@@ -1,4 +1,13 @@
-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'
+export { checkForUpdate, readMeta, parseVersion, isNewerVersion } from './check.js'
+export { extractAll, extractAllFrom } from './extract-all.js'
+export { findTransformTag, evaluateTransform, TRANSFORM_TYPE } from './transform.js'
+export { migrateInto } from './migrate.js'
+export { run } from './run.js'
+export { shapeMatch, countScalarLeaves } from './shape-match.js'
+export { collectRulesTags, normalizeName } from './rules-tags.js'
+export {
+  UpgradeSourceUnreachable,
+  UpgradeSourceHasNoRules,
+  UpgradeTransformInvalid,
+  UpgradeMultipleTransforms,
+} from './errors.js'

package/src/upgrade/migrate.js

@@ -0,0 +1,36 @@
+import { apply } from '../engine/apply.js'
+import { collectRulesTags } from './rules-tags.js'
+import { shapeMatch, countScalarLeaves } from './shape-match.js'
+
+/**
+ * Pour keyed v1 data into the v2 document. Exact-name join: each v2 rules
+ * tag pulls the entry with the same normalized name; tags with no matching
+ * entry keep their template defaults; v1 entries with no matching tag are
+ * counted as discarded. Renames are the transform's job, not the join's.
+ */
+export function migrateInto(adapter, root, dataByName) {
+  const tags = collectRulesTags(adapter, root)
+  const totals = { carriedOver: 0, discarded: 0, listItems: 0 }
+  const byName = {}
+  const v2Names = new Set()
+
+  for (const { name, rules } of tags) {
+    v2Names.add(name)
+    if (!Object.prototype.hasOwnProperty.call(dataByName, name)) {
+      byName[name] = { carriedOver: 0, discarded: 0, listItems: 0 }
+      continue
+    }
+    const { data, summary } = shapeMatch(dataByName[name], rules)
+    apply(adapter, root, rules, data)
+    byName[name] = summary
+    totals.carriedOver += summary.carriedOver
+    totals.discarded += summary.discarded
+    totals.listItems += summary.listItems
+  }
+
+  for (const key of Object.keys(dataByName)) {
+    if (!v2Names.has(key)) totals.discarded += countScalarLeaves(dataByName[key])
+  }
+
+  return { totals, byName, rulesTagCount: tags.length }
+}

package/src/upgrade/rules-tags.js

@@ -0,0 +1,37 @@
+import { parseRelaxed } from '../engine/rules.js'
+import { SUPPORTED_VERSION } from '../engine/rules-tag.js'
+import { UnknownRulesVersion } from '../engine/errors.js'
+
+const RULES_SELECTOR = 'script[data-rules-name]'
+
+export function normalizeName(raw) {
+  return typeof raw === 'string' ? raw.trim().replace(/\s+/g, ' ') : ''
+}
+
+/**
+ * Collect every rules tag under `root` as [{ name, rules }], keyed by the
+ * whitespace-normalized data-rules-name attribute value. Duplicate names:
+ * first tag wins with a warning (mirrors findRulesIn). Unsupported
+ * data-rules-version throws so engine-format skew fails loudly instead of
+ * corrupting a migration.
+ */
+export function collectRulesTags(adapter, root) {
+  const tags = adapter.find(root, RULES_SELECTOR, { includeRulesTag: true })
+  const seen = new Set()
+  const out = []
+  for (const tag of tags) {
+    const name = normalizeName(adapter.attr(tag, 'data-rules-name'))
+    if (!name) continue
+    if (seen.has(name)) {
+      console.warn(
+        `hyper-html-api: duplicate rules tag name "${name}"; using the first.`,
+      )
+      continue
+    }
+    const version = adapter.attr(tag, 'data-rules-version')
+    if (version !== SUPPORTED_VERSION) throw new UnknownRulesVersion(version)
+    seen.add(name)
+    out.push({ name, rules: parseRelaxed(adapter.text(tag)) })
+  }
+  return out
+}

package/src/upgrade/run.js

@@ -0,0 +1,78 @@
+/**
+ * Parent-side upgrade runner (the whole flow, no iframe):
+ *
+ *   1. Pack: extract keyed data from the live page.
+ *   2. Download: fetch the source's pristine HTML, parse with DOMParser
+ *      (scripts never execute, so no runtime DOM noise can leak into what
+ *      gets saved).
+ *   3. Recipe: find the source's text/hyper-upgrade tag, evaluate it, and
+ *      reshape the data ({ [name]: data } in, same shape out).
+ *   4. Unpack: exact-name join + apply into the parsed copy.
+ *   5. Serialize and return. The caller decides how to save — hyperclayjs
+ *      uses saveHtml(); standalone users do their own thing.
+ */
+
+import domAdapter from '../adapters/dom.js'
+import { readMeta } from './check.js'
+import { extractAllFrom } from './extract-all.js'
+import { findTransformTag, evaluateTransform } from './transform.js'
+import { migrateInto } from './migrate.js'
+import { UpgradeSourceUnreachable, UpgradeSourceHasNoRules, UpgradeTransformInvalid } from './errors.js'
+
+export async function run({ sourceUrl, dataByName, fromVersion, doc, loc, fetchFn } = {}) {
+  doc = doc || (typeof document !== 'undefined' ? document : null)
+  loc = loc || (typeof location !== 'undefined' ? location : null)
+  fetchFn = fetchFn || ((url) => fetch(url))
+  if (!doc) throw new Error('upgrade.run requires a document context')
+
+  sourceUrl = sourceUrl || readMeta(doc, 'hyper-source')
+  if (!sourceUrl) {
+    throw new Error('upgrade.run: no sourceUrl given and no hyper-source meta tag found')
+  }
+  const source = new URL(sourceUrl, loc ? loc.href : undefined)
+  fromVersion = fromVersion !== undefined ? fromVersion : readMeta(doc, 'hyper-version')
+  dataByName = dataByName || extractAllFrom(domAdapter, doc)
+
+  let res
+  try {
+    res = await fetchFn(source.href)
+  } catch (err) {
+    throw new UpgradeSourceUnreachable(source.href, err)
+  }
+  if (!res.ok) {
+    throw new UpgradeSourceUnreachable(source.href, new Error(`HTTP ${res.status}`))
+  }
+  const text = await res.text()
+  const sourceDoc = new DOMParser().parseFromString(text, 'text/html')
+  const toVersion = readMeta(sourceDoc, 'hyper-version')
+
+  let map = dataByName
+  let transformApplied = false
+  const code = findTransformTag(domAdapter, sourceDoc)
+  if (code) {
+    const transform = await evaluateTransform(code)
+    const out = await transform(map, { fromVersion, toVersion })
+    if (!out || typeof out !== 'object' || Array.isArray(out)) {
+      throw new UpgradeTransformInvalid('transform must return a plain object map of { rulesName: data }')
+    }
+    map = out
+    transformApplied = true
+  }
+
+  const { totals, byName, rulesTagCount } = migrateInto(domAdapter, sourceDoc, map)
+  if (rulesTagCount === 0 && Object.keys(map).length > 0) {
+    throw new UpgradeSourceHasNoRules(source.href)
+  }
+
+  return {
+    html: serializeDocument(sourceDoc),
+    fromVersion,
+    toVersion,
+    summary: { transformApplied, totals, byName },
+  }
+}
+
+function serializeDocument(doc) {
+  const name = doc.doctype && doc.doctype.name ? doc.doctype.name : 'html'
+  return `<!DOCTYPE ${name}>\n` + doc.documentElement.outerHTML
+}

package/src/upgrade/shape-match.js

@@ -28,6 +28,9 @@ function walk(rule, v1, summary) {
       return v1
     }
     if (v1 === undefined || v1 === null) return undefined
+    // A scalar slot can't hold an object/array from v1; leave the template
+    // default (collectDiscards counts the dropped leaves).
+    if (typeof v1 === 'object') return undefined
     summary.carriedOver++
     return v1
   }
@@ -77,7 +80,7 @@ function collectDiscards(rule, v1, summary) {
   }
 }
 
-function countScalarLeaves(v) {
+export function countScalarLeaves(v) {
   if (v === null || v === undefined) return 0
   if (Array.isArray(v)) return v.reduce((n, x) => n + countScalarLeaves(x), 0)
   if (typeof v === 'object') {

package/src/upgrade/transform.js

@@ -0,0 +1,51 @@
+import { UpgradeMultipleTransforms, UpgradeTransformInvalid } from './errors.js'
+
+export const TRANSFORM_TYPE = 'text/hyper-upgrade'
+
+/**
+ * The migration recipe is a non-executing script tag in the source HTML:
+ *
+ *   <script type="text/hyper-upgrade">
+ *   export default (dataByName, { fromVersion, toVersion }) => dataByName
+ *   </script>
+ *
+ * Browsers ignore unknown script types, so it never runs on the source page
+ * itself; the upgrading fork reads it out of the fetched pristine copy and
+ * evaluates it on demand. Returns the tag's code, or null when absent.
+ */
+export function findTransformTag(adapter, root) {
+  const tags = adapter.find(root, `script[type="${TRANSFORM_TYPE}"]`)
+  if (tags.length === 0) return null
+  if (tags.length > 1) throw new UpgradeMultipleTransforms(tags.length)
+  const code = adapter.text(tags[0])
+  return code || null
+}
+
+// Bundlers rewrite a bare dynamic import() when emitting non-ESM formats; the
+// Function indirection keeps it a native browser import() at runtime.
+const dynamicImport = new Function('url', 'return import(url)')
+
+/**
+ * Evaluate transform code as a real ES module (Blob URL import). The module
+ * must `export default` a function; it may be async. Relative imports won't
+ * resolve from a Blob URL; absolute (CDN) imports work.
+ */
+export async function evaluateTransform(code) {
+  const blob = new Blob([code], { type: 'text/javascript' })
+  const url = URL.createObjectURL(blob)
+  let mod
+  try {
+    mod = await dynamicImport(url)
+  } catch (err) {
+    throw new UpgradeTransformInvalid(
+      `transform failed to load: ${err && err.message ? err.message : err}`,
+      err,
+    )
+  } finally {
+    URL.revokeObjectURL(url)
+  }
+  if (typeof mod.default !== 'function') {
+    throw new UpgradeTransformInvalid('transform must `export default` a function')
+  }
+  return mod.default
+}

package/src/upgrade.js

@@ -0,0 +1,14 @@
+// Lean upgrade entry: the DOM-bound engine + the template-upgrade flow,
+// WITHOUT cms. This is what `hyper-html-api/upgrade` exports and what
+// hyperclayjs vendors for its `upgrade` module.
+import { engine } from './dom-api.js'
+import { checkForUpdate } from './upgrade/check.js'
+import { run } from './upgrade/run.js'
+import { extractAll } from './upgrade/extract-all.js'
+import { shapeMatch } from './upgrade/shape-match.js'
+
+export const upgrade = { checkForUpdate, run, extractAll, shapeMatch }
+export { engine }
+
+const HyperHtmlApiUpgrade = { engine, upgrade }
+export default HyperHtmlApiUpgrade

package/src/upgrade/helper.js

@@ -1,143 +0,0 @@
-/**
- * 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/registry.js

@@ -1,19 +0,0 @@
-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
-}