crawlforge-extractors 1.9.0 → 1.11.0

package/src/frameworkData.js

@@ -0,0 +1,323 @@
+/**
+ * frameworkData.js — decode the framework payloads a JSON parse cannot read.
+ *
+ * Nuxt 3 ships its state as a devalue `stringify` payload in
+ * <script type="application/json" id="__NUXT_DATA__" data-nuxt-data="…">: a
+ * flat array where every value is an index into the array, with Vue
+ * reactivity wrappers tagged as ["Reactive", i], ["ShallowRef", i], …. Parsed
+ * as plain JSON it is a list of numbers; decoded, it is the page's state.
+ *
+ * SvelteKit ships its load() data inline in the boot script as devalue
+ * `uneval` output — a JavaScript literal, read here with jsLiteral.js.
+ *
+ * Both readers return JSON-safe trees and never throw: anything they cannot
+ * decode comes back as a warning.
+ */
+
+import { unflatten } from 'devalue';
+import { parseExpressionAt } from 'acorn';
+
+import { evaluateLiteralNode } from './jsLiteral.js';
+
+// Nuxt's EmptyRef/EmptyShallowRef payload: '_' is undefined, '0n' is a zero
+// bigint, anything else is JSON (Nuxt reads it with destr, a forgiving
+// JSON.parse that falls back to the string).
+function reviveEmptyRef(data) {
+  if (data === '_') return undefined;
+  if (data === '0n') return 0;
+  if (typeof data !== 'string') return data;
+  try {
+    return JSON.parse(data);
+  } catch {
+    return data;
+  }
+}
+
+const identity = (data) => data;
+
+/**
+ * The revivers Nuxt 3 registers (app/plugins/revive-payload.client), minus
+ * Vue: a ref or reactive wrapper is just its value once it is data. Only
+ * Reactive, ShallowReactive and the devalue built-in Set were seen live on
+ * nuxt.com (2026-10-03); the rest follow Nuxt's source.
+ */
+const NUXT_REVIVERS = {
+  NuxtError: identity,
+  EmptyShallowRef: reviveEmptyRef,
+  EmptyRef: reviveEmptyRef,
+  ShallowRef: identity,
+  ShallowReactive: identity,
+  Ref: identity,
+  Reactive: identity
+};
+
+// Type tags devalue 6 decodes itself. Any other tag throws "Unknown type" in
+// unflatten, so it gets an identity reviver and a warning instead.
+const DEVALUE_BUILTIN_TYPES = new Set([
+  'Date', 'Set', 'Map', 'RegExp', 'Object', 'BigInt', 'null',
+  'Int8Array', 'Uint8Array', 'Uint8ClampedArray', 'Int16Array', 'Uint16Array',
+  'Float16Array', 'Int32Array', 'Uint32Array', 'Float32Array', 'Float64Array',
+  'BigInt64Array', 'BigUint64Array', 'DataView', 'ArrayBuffer',
+  'URL', 'URLSearchParams', 'Temporal.Duration', 'Temporal.Instant',
+  'Temporal.PlainDate', 'Temporal.PlainTime', 'Temporal.PlainDateTime',
+  'Temporal.PlainMonthDay', 'Temporal.PlainYearMonth', 'Temporal.ZonedDateTime'
+]);
+
+// Construction overrides that build JSON-safe leaves directly: no Date, URL,
+// Temporal or RegExp object is ever constructed from page input, and
+// Temporal — absent from Node — cannot fail the decode.
+const PARSE_OPERATIONS = {
+  fromPrimitive: (value) => {
+    if (typeof value === 'bigint') return value.toString();
+    if (typeof value === 'number' && !Number.isFinite(value)) return null;
+    return value === undefined ? null : value;
+  },
+  fromISOString: (iso) => (typeof iso === 'string' ? iso : null),
+  fromStringValue: (tag, text) => (typeof text === 'string' ? text : null),
+  fromRegExpInfo: (source, flags) => `/${source}/${flags ?? ''}`,
+  box: (value) => value
+};
+
+// The JSON-safe conversion is a recursive walk. Real Nuxt state is a few
+// dozen levels deep; past this, a branch is cut and reported.
+const MAX_DEPTH = 512;
+// Output cost: one unit per value plus one per 16 characters of string. The
+// devalue format shares every repeated value by index, so a small payload can
+// reference one large object or string a million times; written out, that
+// would expand without bound. Past this cost a repeated object is written as
+// a $ref and anything else as null.
+const MAX_OUTPUT_COST = 5_000_000;
+const CHARS_PER_COST_UNIT = 16;
+
+/** Append a key to a jsonPath.js-style path ("state.items[0]"). */
+const childPath = (path, key) =>
+  typeof key === 'number' ? `${path}[${key}]` : path === '' ? key : `${path}.${key}`;
+
+/** Copy entries onto a fresh object as own data properties ("__proto__" too). */
+function dataObject(entries) {
+  const out = {};
+  for (const [key, value] of entries) {
+    Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
+  }
+  return out;
+}
+
+/**
+ * Turn a decoded devalue graph into a JSON-safe tree.
+ *
+ * Map → plain object when every key is a string, else an array of [key,
+ * value] pairs; Set → array; typed arrays and ArrayBuffer → arrays of numbers;
+ * undefined / NaN / ±Infinity → null; bigint → string.
+ *
+ * Cycles cannot be represented in JSON, so a value reached again while it is
+ * still being written (an ancestor of itself) becomes { $ref: "<path>" },
+ * where <path> is its first occurrence in jsonPath.js syntax ("" is the
+ * root). A shared object reached a second time from elsewhere is written out
+ * again — until MAX_OUTPUT_COST is spent, after which it too is a $ref.
+ *
+ * @param {unknown} root
+ * @param {string[]} warnings
+ * @returns {unknown}
+ */
+function toJsonSafe(root, warnings) {
+  const firstPath = new Map();
+  const onStack = new Set();
+  let cost = 0;
+  let depthCut = false;
+  let overBudget = false;
+
+  function convert(value, path, depth) {
+    cost += typeof value === 'string' ? 1 + Math.floor(value.length / CHARS_PER_COST_UNIT) : 1;
+    if (value === undefined || value === null) return null;
+    const isObject = typeof value === 'object';
+    if (isObject && onStack.has(value)) return { $ref: firstPath.get(value) };
+    if (cost > MAX_OUTPUT_COST) {
+      overBudget = true;
+      return isObject && firstPath.has(value) ? { $ref: firstPath.get(value) } : null;
+    }
+    if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+    if (typeof value === 'bigint') return value.toString();
+    if (!isObject) return typeof value === 'string' || typeof value === 'boolean' ? value : null;
+    if (depth > MAX_DEPTH) {
+      depthCut = true;
+      return null;
+    }
+    if (!firstPath.has(value)) firstPath.set(value, path);
+
+    onStack.add(value);
+    const next = depth + 1;
+    let out;
+    if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+      const view = value instanceof ArrayBuffer || value instanceof DataView
+        ? new Uint8Array(value instanceof ArrayBuffer ? value : value.buffer,
+          value.byteOffset ?? 0, value.byteLength)
+        : value;
+      out = Array.from(view, (n) => (typeof n === 'bigint' ? n.toString() : n));
+      cost += out.length;
+    } else if (value instanceof Set) {
+      out = [];
+      for (const item of value) out.push(convert(item, childPath(path, out.length), next));
+    } else if (value instanceof Map) {
+      const entries = [...value];
+      out = entries.every(([key]) => typeof key === 'string')
+        ? dataObject(entries.map(([key, item]) => [key, convert(item, childPath(path, key), next)]))
+        : entries.map(([key, item], i) => [
+          convert(key, childPath(childPath(path, i), 0), next),
+          convert(item, childPath(childPath(path, i), 1), next)
+        ]);
+    } else if (Array.isArray(value) && value.length > MAX_OUTPUT_COST) {
+      // A sparse array can declare a length of 2^32-1 around two entries;
+      // walking every slot would hang, so only populated indices are kept.
+      warnings.push(`A sparse array of declared length ${value.length} at "${path}" was read as an object of its populated indices.`);
+      out = dataObject(Object.keys(value).map((key) => [key, convert(value[key], childPath(path, key), next)]));
+    } else if (Array.isArray(value)) {
+      out = new Array(value.length);
+      for (let i = 0; i < value.length; i++) out[i] = convert(value[i], childPath(path, i), next);
+    } else {
+      // Plain or null-prototype object.
+      out = dataObject(Object.keys(value).map((key) => [key, convert(value[key], childPath(path, key), next)]));
+    }
+    onStack.delete(value);
+    return out;
+  }
+
+  const result = convert(root, '', 0);
+  if (depthCut) warnings.push(`Branches nested deeper than ${MAX_DEPTH} levels were cut and read as null.`);
+  if (overBudget) {
+    warnings.push(`The decoded payload passed its output budget (${MAX_OUTPUT_COST} units); past it, repeated objects are written as { $ref } and other values as null.`);
+  }
+  return result;
+}
+
+/**
+ * Decode a parsed __NUXT_DATA__ block (Nuxt 3/4, devalue `stringify` format).
+ *
+ * @param {unknown} parsed the block's JSON.parse output
+ * @returns {{ value: unknown, warnings: string[] }} value is null when the
+ *   payload cannot be decoded; the reason is in warnings
+ */
+export function decodeNuxtData(parsed) {
+  const warnings = [];
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    return { value: null, warnings: ['__NUXT_DATA__ is not a devalue payload (expected a non-empty array); not decoded.'] };
+  }
+
+  const revivers = { ...NUXT_REVIVERS };
+  const unknown = new Set();
+  for (const entry of parsed) {
+    if (Array.isArray(entry) && typeof entry[0] === 'string'
+      && !DEVALUE_BUILTIN_TYPES.has(entry[0]) && !Object.hasOwn(revivers, entry[0])) {
+      unknown.add(entry[0]);
+    }
+  }
+  for (const type of unknown) revivers[type] = identity;
+  if (unknown.size > 0) {
+    warnings.push(`__NUXT_DATA__ uses reviver type(s) this reader does not know (${[...unknown].join(', ')}); each was read as its plain value.`);
+  }
+
+  let decoded;
+  try {
+    // A copy: unflatten appends to the array it is given when a custom
+    // reviver wraps a non-index payload, and the caller may still report the
+    // raw block.
+    decoded = unflatten(parsed.slice(), revivers, { operations: PARSE_OPERATIONS });
+  } catch (error) {
+    // Malformed indexes, a __proto__ key, a stack overflow on a pathological
+    // chain — all hostile-input failures, all reported rather than thrown.
+    warnings.push(`__NUXT_DATA__ could not be decoded: ${error instanceof Error ? error.message : String(error)}.`);
+    return { value: null, warnings };
+  }
+
+  try {
+    return { value: toJsonSafe(decoded, warnings), warnings };
+  } catch (error) {
+    warnings.push(`__NUXT_DATA__ decoded but could not be converted to JSON: ${error instanceof Error ? error.message : String(error)}.`);
+    return { value: null, warnings };
+  }
+}
+
+const SCRIPT_RE = /<script\b[^>]*>([\s\S]*?)<\/script\s*>/gi;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+const SVELTEKIT_GLOBAL_RE = /\b__sveltekit_[a-z0-9]+\s*=\s*\{/i;
+const KIT_START_RE = /\bkit\s*\.\s*start\s*\(/g;
+
+/**
+ * Find the `data` property of the options object in
+ * `kit.start(app, element, { node_ids, data, form, error })`.
+ * @param {string} body the boot script's text
+ * @returns {object|null} the acorn node of the data value
+ */
+function findStartData(body) {
+  KIT_START_RE.lastIndex = 0;
+  let match;
+  while ((match = KIT_START_RE.exec(body)) !== null) {
+    let call;
+    try {
+      call = parseExpressionAt(body, match.index, { ecmaVersion: 'latest' });
+    } catch {
+      continue;
+    }
+    const options = call.type === 'CallExpression' ? call.arguments[2] : null;
+    if (!options || options.type !== 'ObjectExpression') continue;
+    const prop = options.properties.find((p) => p.type === 'Property' && !p.computed
+      && (p.key.type === 'Identifier' ? p.key.name : p.key.value) === 'data');
+    if (prop) return prop.value;
+  }
+  return null;
+}
+
+/**
+ * Read SvelteKit's hydration data out of its inline boot script:
+ *
+ *   __sveltekit_8abmph = { base: …, version: "…" };
+ *   const element = document.currentScript.parentElement;
+ *   import("…/start.js").then(async (kit) => {
+ *     kit.init(__sveltekit_8abmph);
+ *     const app = await import("…/app.js");
+ *     kit.start(app, element, { node_ids: [0, 5], data: [ … ], form: null, error: null });
+ *   });
+ *
+ * (svelte.dev, 2026-10-03; older SvelteKit uses Promise.all([...]).then(
+ * ([kit, app]) => kit.start(…)), which reads the same.) Only `data` is
+ * evaluated — the other arguments are identifiers. Each data entry is one
+ * route node's load() output; an entry the literal evaluator refuses is null,
+ * with a warning naming its index.
+ *
+ * @param {string} html raw HTML
+ * @returns {{ value: unknown, warnings: string[] } | null} null when the page
+ *   has no SvelteKit boot script
+ */
+export function readSvelteKitData(html) {
+  const source = html.replace(HTML_COMMENT_RE, '');
+  SCRIPT_RE.lastIndex = 0;
+  let script;
+  while ((script = SCRIPT_RE.exec(source)) !== null) {
+    const body = script[1];
+    if (!SVELTEKIT_GLOBAL_RE.test(body)) continue;
+
+    const warnings = [];
+    const data = findStartData(body);
+    if (data === null) {
+      return { value: null, warnings: ['A SvelteKit boot script is present but its kit.start(…) data could not be located.'] };
+    }
+
+    // One budget across entries, so a page cannot multiply the evaluator's
+    // cap by splitting its payload into many entries.
+    const budget = { cost: 0 };
+    if (data.type !== 'ArrayExpression') {
+      const result = evaluateLiteralNode(data, budget);
+      if (!result.ok) warnings.push(`SvelteKit data was not evaluated (${result.reason}).`);
+      return { value: result.ok ? result.value : null, warnings };
+    }
+
+    const value = data.elements.map((element, i) => {
+      if (element === null) return null;
+      const result = evaluateLiteralNode(element, budget);
+      if (result.ok) return result.value;
+      warnings.push(`SvelteKit data[${i}] was not evaluated (${result.reason}); read as null.`);
+      return null;
+    });
+    return { value, warnings };
+  }
+  return null;
+}

package/src/jsLiteral.js

@@ -0,0 +1,266 @@
+/**
+ * jsLiteral.js — read a JavaScript literal without running it.
+ *
+ * Some pages ship their state as a JS expression rather than JSON: unquoted
+ * keys, `void 0`, `!0`, and the IIFE wrapper that Nuxt 2 and devalue.uneval
+ * (SvelteKit) emit to share repeated values:
+ *
+ *   window.__NUXT__=(function(a,b){return {x:a,y:[b]}}(1,"z"))
+ *
+ * This is static evaluation over an acorn AST. No code executes: there is no
+ * eval, no vm, no Function, and no property or global lookup. The IIFE form is
+ * read by binding each parameter name to its argument's literal value — a
+ * name → literal environment — and evaluating the single `return` expression
+ * against it. An identifier resolves only to a bound parameter (or the
+ * literal names undefined/NaN/Infinity); everything else is refused.
+ *
+ * Allowed, and nothing more:
+ *   - string/number/boolean/null literals; a bigint becomes its decimal string
+ *   - arrays (holes read as null) and objects with plain, non-computed keys
+ *   - unary - and + on numbers, !0 / !1, and void <literal> (undefined)
+ *   - template literals with no ${} expressions
+ *   - string + string
+ *   - (function(a,b){return <expr>}(<args>)) with simple identifier params
+ *   - new Date(<number|string>) and new RegExp(<string>[, <string>]), the
+ *     two constructors devalue.uneval emits for SvelteKit load data
+ *     (svelte.dev, 2026-10-03). Read as an ISO string and a "/src/flags"
+ *     string — the same JSON-safe forms frameworkData.js gives them.
+ *
+ * Output is JSON-safe: undefined, NaN and ±Infinity become null wherever they
+ * land in an array or object, and at the top level.
+ *
+ * The source is attacker-controlled, so the walk is bounded: nesting depth is
+ * capped, and a cost budget caps total work. A reference to an IIFE parameter
+ * is charged the full cost of its argument, because that is what the reader
+ * receives once the result is serialized — `(function(a){return [a,a,a]}(…))`
+ * nested a few levels deep would otherwise expand exponentially.
+ */
+
+import { parseExpressionAt } from 'acorn';
+
+const MAX_DEPTH = 512;
+
+// One unit per AST node, plus one per 16 characters of every string produced.
+// Generous for real pages (a 20 MB state blob costs ~2.5M), and it bounds the
+// output an IIFE can amplify a small source into.
+const MAX_COST = 5_000_000;
+const CHARS_PER_COST_UNIT = 16;
+
+class Refusal extends Error {}
+
+/**
+ * @param {{ cost: number }} budget
+ * @param {number} units
+ */
+function charge(budget, units) {
+  budget.cost += units;
+  if (budget.cost > MAX_COST) {
+    throw new Refusal(`the literal exceeds the evaluation budget of ${MAX_COST} units`);
+  }
+}
+
+/** @param {{ cost: number }} budget @param {string} text */
+function chargeString(budget, text) {
+  charge(budget, Math.ceil(text.length / CHARS_PER_COST_UNIT));
+  return text;
+}
+
+/** undefined, NaN and ±Infinity are not JSON; store them as null. */
+function jsonSafe(value) {
+  if (value === undefined) return null;
+  if (typeof value === 'number' && !Number.isFinite(value)) return null;
+  return value;
+}
+
+/**
+ * Look a name up in the IIFE parameter scope chain.
+ * @param {{ vars: Map<string, { value: unknown, cost: number }>, parent: object|null }|null} scope
+ * @param {string} name
+ */
+function lookup(scope, name) {
+  for (let s = scope; s !== null; s = s.parent) {
+    if (s.vars.has(name)) return s.vars.get(name);
+  }
+  return undefined;
+}
+
+/**
+ * The narrow IIFE shape: a plain function expression, simple identifier
+ * params, a body that is exactly one `return <expr>`.
+ * @param {any} callee
+ */
+function isLiteralIife(callee) {
+  return callee.type === 'FunctionExpression'
+    && !callee.async
+    && !callee.generator
+    && callee.params.every((param) => param.type === 'Identifier')
+    && callee.body.body.length === 1
+    && callee.body.body[0].type === 'ReturnStatement'
+    && callee.body.body[0].argument !== null;
+}
+
+/**
+ * Evaluate one node. Values are raw JS here (undefined, NaN allowed) so that
+ * `-Infinity` and `void 0` compose; containers store them JSON-safe.
+ * @returns {unknown}
+ */
+function evaluate(node, scope, depth, budget) {
+  if (depth > MAX_DEPTH) throw new Refusal(`nesting deeper than ${MAX_DEPTH} levels`);
+  charge(budget, 1);
+
+  switch (node.type) {
+    case 'Literal': {
+      if (node.regex) throw new Refusal('a regular expression literal');
+      if (typeof node.value === 'bigint') return node.value.toString();
+      if (typeof node.value === 'string') return chargeString(budget, node.value);
+      return node.value;
+    }
+
+    case 'ArrayExpression':
+      return node.elements.map((element) => {
+        if (element === null) return null;
+        if (element.type === 'SpreadElement') throw new Refusal('a spread element');
+        return jsonSafe(evaluate(element, scope, depth + 1, budget));
+      });
+
+    case 'ObjectExpression': {
+      const object = {};
+      for (const prop of node.properties) {
+        if (prop.type !== 'Property') throw new Refusal('a spread property');
+        if (prop.computed) throw new Refusal('a computed key');
+        if (prop.kind !== 'init' || prop.method) throw new Refusal('a method, getter or setter');
+        if (prop.shorthand) throw new Refusal(`a shorthand property "${prop.key.name}"`);
+        const key = prop.key.type === 'Identifier' ? prop.key.name : String(prop.key.value);
+        // defineProperty, not assignment: a "__proto__" key becomes an own
+        // data property instead of replacing the object's prototype. (In JS
+        // the literal would set the prototype; as data it is safer kept as a
+        // plain key.)
+        Object.defineProperty(object, key, {
+          value: jsonSafe(evaluate(prop.value, scope, depth + 1, budget)),
+          enumerable: true,
+          writable: true,
+          configurable: true
+        });
+      }
+      return object;
+    }
+
+    case 'UnaryExpression': {
+      const value = evaluate(node.argument, scope, depth + 1, budget);
+      if (node.operator === 'void') return undefined;
+      if ((node.operator === '-' || node.operator === '+') && typeof value === 'number') {
+        return node.operator === '-' ? -value : value;
+      }
+      if (node.operator === '!' && (typeof value === 'number' || typeof value === 'boolean')) {
+        return !value;
+      }
+      throw new Refusal(`the unary operator "${node.operator}" on a ${typeof value}`);
+    }
+
+    case 'Identifier': {
+      const binding = lookup(scope, node.name);
+      if (binding !== undefined) {
+        charge(budget, binding.cost);
+        return binding.value;
+      }
+      if (node.name === 'undefined') return undefined;
+      if (node.name === 'NaN') return NaN;
+      if (node.name === 'Infinity') return Infinity;
+      throw new Refusal(`the identifier "${node.name}"`);
+    }
+
+    case 'TemplateLiteral': {
+      const cooked = node.expressions.length === 0 ? node.quasis[0].value.cooked : null;
+      if (typeof cooked !== 'string') throw new Refusal('a template literal with expressions');
+      return chargeString(budget, cooked);
+    }
+
+    case 'BinaryExpression': {
+      if (node.operator !== '+') throw new Refusal(`the binary operator "${node.operator}"`);
+      const left = evaluate(node.left, scope, depth + 1, budget);
+      const right = evaluate(node.right, scope, depth + 1, budget);
+      if (typeof left !== 'string' || typeof right !== 'string') {
+        throw new Refusal('a "+" that is not string concatenation');
+      }
+      return chargeString(budget, left + right);
+    }
+
+    case 'NewExpression': {
+      const name = node.callee.type === 'Identifier' ? node.callee.name : null;
+      if ((name === 'Date' || name === 'RegExp') && lookup(scope, name) === undefined) {
+        const args = node.arguments.map((arg) => {
+          if (arg.type === 'SpreadElement') throw new Refusal('a spread argument');
+          return evaluate(arg, scope, depth + 1, budget);
+        });
+        if (name === 'Date' && args.length === 1
+          && (typeof args[0] === 'number' || typeof args[0] === 'string')) {
+          const date = new Date(args[0]);
+          return Number.isNaN(date.getTime()) ? null : date.toISOString();
+        }
+        if (name === 'RegExp' && args.length >= 1 && args.length <= 2
+          && args.every((arg) => typeof arg === 'string')) {
+          return chargeString(budget, `/${args[0]}/${args[1] ?? ''}`);
+        }
+      }
+      throw new Refusal('a constructor call');
+    }
+
+    case 'CallExpression': {
+      if (node.optional || !isLiteralIife(node.callee)) throw new Refusal('a function call');
+      // Arguments are evaluated in the caller's scope; each records what it
+      // cost so every later reference to it is charged the same.
+      const args = node.arguments.map((arg) => {
+        if (arg.type === 'SpreadElement') throw new Refusal('a spread argument');
+        const before = budget.cost;
+        const value = evaluate(arg, scope, depth + 1, budget);
+        return { value, cost: budget.cost - before };
+      });
+      const vars = new Map();
+      node.callee.params.forEach((param, i) => {
+        vars.set(param.name, args[i] ?? { value: undefined, cost: 0 });
+      });
+      return evaluate(node.callee.body.body[0].argument, { vars, parent: scope }, depth + 1, budget);
+    }
+
+    default:
+      throw new Refusal(`a ${node.type}`);
+  }
+}
+
+/**
+ * Statically evaluate an acorn ESTree expression node made only of literals.
+ *
+ * @param {object} node an acorn expression node
+ * @param {{ cost: number }} [budget] pass one object to several calls to make
+ *   them share one cost cap (readSvelteKitData evaluates entry by entry)
+ * @returns {{ ok: true, value: unknown } | { ok: false, reason: string }}
+ */
+export function evaluateLiteralNode(node, budget = { cost: 0 }) {
+  try {
+    return { ok: true, value: jsonSafe(evaluate(node, null, 0, budget)) };
+  } catch (error) {
+    if (error instanceof Refusal) return { ok: false, reason: `not a literal: ${error.message}` };
+    // A stack overflow before MAX_DEPTH (a small stack) is still a refusal.
+    return { ok: false, reason: `not evaluated: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+/**
+ * Parse the expression that starts at `start` in `text` and evaluate it.
+ *
+ * @param {string} text
+ * @param {number} [start]
+ * @returns {{ ok: true, value: unknown, end: number } | { ok: false, reason: string }}
+ */
+export function evaluateLiteralSource(text, start = 0) {
+  let node;
+  try {
+    node = parseExpressionAt(text, start, { ecmaVersion: 'latest' });
+  } catch (error) {
+    // acorn reports pathological nesting as a SyntaxError ("Not enough stack
+    // space"); a RangeError is possible too. Either way: refuse, never throw.
+    return { ok: false, reason: `not parseable: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const result = evaluateLiteralNode(node);
+  return result.ok ? { ok: true, value: result.value, end: node.end } : result;
+}