@panphora/sapjs 0.2.0

package/src/compile.js

@@ -0,0 +1,91 @@
+import { helperBundle } from "./helpers.js";
+
+// The frozen compile signature. These argument names are fixed forever.
+// App-registered formats extend the `fmt` namespace object, never this list,
+// so the source-keyed cache never invalidates.
+const ARGS = ["state", "item", "el", "root", "fmt", "num", "sum", "count", "avg", "min", "max", "plural", "days"];
+
+const cache = new Map();
+
+const STATE_REF = /\bstate\.([a-z][a-z0-9_]*)/g;
+const ITEM_REF = /\bitem\.([a-z][a-z0-9_]*)/g;
+
+function extractDeps(src) {
+  const state = new Set();
+  const item = new Set();
+  let m;
+  STATE_REF.lastIndex = 0;
+  while ((m = STATE_REF.exec(src))) state.add(m[1]);
+  ITEM_REF.lastIndex = 0;
+  while ((m = ITEM_REF.exec(src))) item.add(m[1]);
+  return { state, item };
+}
+
+// Compile an expression to a function with the frozen signature.
+// `statement` mode (for effect=) runs a statement body with no return.
+export function compile(src, statement = false) {
+  const key = (statement ? "!" : "") + src;
+  let entry = cache.get(key);
+  if (entry) return entry;
+  if (cache.size > 512) cache.clear();
+
+  try {
+    const body = statement ? `"use strict";\n${src}` : `"use strict"; return (${src});`;
+    const fn = new Function(...ARGS, body);
+    entry = { fn, src, statement, deps: extractDeps(src), error: null };
+  } catch (err) {
+    entry = { fn: null, src, statement, deps: { state: new Set(), item: new Set() }, error: err };
+  }
+  cache.set(key, entry);
+  return entry;
+}
+
+// Evaluate a compiled entry against an { state, item, el, root } context.
+// Throws if the expression throws (callers do preserve-on-error).
+export function run(entry, ctx) {
+  if (entry.error) throw entry.error;
+  return entry.fn(ctx.state, ctx.item, ctx.el ?? null, ctx.root, ...helperBundle());
+}
+
+export function clearCompileCache() {
+  cache.clear();
+}
+
+// Topologically sort calc bindings within a single scope object so a calc that
+// reads another calc evaluates after it. Cycles throw, naming the chain.
+export function topoSort(calcs) {
+  // calcs: array of { name, entry, ... } that share one owner object.
+  const byName = new Map();
+  for (const c of calcs) byName.set(c.name, c);
+  const out = [];
+  const state = new Map(); // name -> 0 visiting, 1 done
+  const stack = [];
+
+  function visit(c) {
+    const s = state.get(c.name);
+    if (s === 1) return;
+    if (s === 0) {
+      const cycle = [...stack.slice(stack.indexOf(c.name)), c.name].join(" -> ");
+      const err = new Error(`calc: cycle: ${cycle}`);
+      err.sapCode = "E07";
+      err.cycle = cycle;
+      throw err;
+    }
+    state.set(c.name, 0);
+    stack.push(c.name);
+    for (const dep of c.entry.deps.state) {
+      const d = byName.get(dep);
+      if (d && d !== c) visit(d);
+    }
+    for (const dep of c.entry.deps.item) {
+      const d = byName.get(dep);
+      if (d && d !== c) visit(d);
+    }
+    stack.pop();
+    state.set(c.name, 1);
+    out.push(c);
+  }
+
+  for (const c of calcs) visit(c);
+  return out;
+}

package/src/control-serialize.js

@@ -0,0 +1,85 @@
+// The one place that knows how a form control's live state maps to the DOM
+// attributes that survive serialization (cloneNode / outerHTML).
+//
+// Browser form state lives in JS properties (.value, .checked, .selected), not
+// in attributes. A save serializes attributes, so that state is lost unless it
+// is copied into attributes first. This module is shared by sapjs (carrier
+// mirror) and hyperclayjs (persistent form input values) so the two never drift.
+//
+// Two phases:
+//   serializeControlToAttributes(el)        LIVE, cursor-safe. Run on every edit.
+//     A textarea writes an inert `data-value` attribute, because writing its
+//     `textContent` while focused destroys the cursor; everything else writes
+//     its real attribute (the WHATWG dirty-value flag keeps the display intact).
+//   finalizeControlForSave(target, source)  SAVE, on a detached clone. Reads live
+//     state from `source`, writes `target`'s attributes, and resolves a textarea
+//     `data-value` into real `textContent` so the saved HTML is clean.
+
+function inputType(el) {
+  return (el.getAttribute("type") || "text").toLowerCase();
+}
+
+export function serializeControlToAttributes(el) {
+  const tag = el.tagName;
+  if (tag === "INPUT") {
+    const type = inputType(el);
+    if (type === "checkbox" || type === "radio") {
+      if (el.checked) el.setAttribute("checked", "");
+      else el.removeAttribute("checked");
+    } else {
+      el.setAttribute("value", el.value);
+    }
+    return;
+  }
+  if (tag === "TEXTAREA") {
+    el.setAttribute("data-value", el.value);
+    return;
+  }
+  if (tag === "SELECT") {
+    const opts = el.options;
+    for (let i = 0; i < opts.length; i++) {
+      if (opts[i].selected) opts[i].setAttribute("selected", "");
+      else opts[i].removeAttribute("selected");
+    }
+  }
+}
+
+export function finalizeControlForSave(target, source = target) {
+  const tag = target.tagName;
+  if (tag === "INPUT") {
+    const type = inputType(target);
+    if (type === "checkbox" || type === "radio") {
+      if (source.checked) target.setAttribute("checked", "");
+      else target.removeAttribute("checked");
+    } else {
+      target.setAttribute("value", source.value);
+    }
+    return;
+  }
+  if (tag === "TEXTAREA") {
+    target.textContent = source.value;
+    target.removeAttribute("data-value");
+    return;
+  }
+  if (tag === "SELECT") {
+    const tOpts = target.options;
+    const sOpts = source.options;
+    for (let i = 0; i < tOpts.length; i++) {
+      if (sOpts[i] && sOpts[i].selected) tOpts[i].setAttribute("selected", "");
+      else tOpts[i].removeAttribute("selected");
+    }
+  }
+}
+
+// Load-time inverse of the textarea half of serialize. A saved file can still
+// carry a textarea's value in the cursor-safe data-value attribute (when no save
+// step finalized it into textContent), and the browser ignores data-value when
+// populating .value on load. Restore it so the value round-trips on reload.
+// Other control types round-trip natively (the browser seeds .value/.checked/
+// .selected from their attributes), so they need nothing here.
+export function rehydrateControlFromAttributes(el) {
+  if (el.tagName !== "TEXTAREA" || !el.hasAttribute("data-value")) return;
+  if (el === el.ownerDocument.activeElement) return; // mid-edit: leave it to persist
+  el.textContent = el.getAttribute("data-value");
+  el.removeAttribute("data-value");
+}

package/src/dom.js

@@ -0,0 +1,182 @@
+// DOM walking that respects scope boundaries, plus declaration parsing and id stamping.
+
+let idSeq = 0;
+
+export function ensureId(el, prefix = "sap") {
+  if (!el.id) el.id = `${prefix}-${(idSeq++).toString(36)}`;
+  return el.id;
+}
+
+export function isScopeBoundary(el) {
+  return el.hasAttribute("scope") || el.hasAttribute("items") || el.hasAttribute("detail");
+}
+
+export function isInert(el) {
+  return el.hasAttribute("sap-ignore") || el.hasAttribute("template");
+}
+
+// Walk descendants that belong to scopeEl's own scope. Stops descent at nested
+// boundaries (scope/items/detail) and skips inert subtrees (sap-ignore/template).
+// visit(el, isBoundary) is called for every owned element including boundaries.
+export function walkOwned(scopeEl, visit) {
+  for (const child of scopeEl.children) descend(child);
+  function descend(el) {
+    if (el.nodeType !== 1) return;
+    if (isInert(el)) return;
+    const boundary = isScopeBoundary(el);
+    visit(el, boundary);
+    if (!boundary) for (const c of el.children) descend(c);
+  }
+}
+
+export function nearestScopeEl(el) {
+  let cur = el;
+  while (cur) {
+    if (cur.hasAttribute("sap") || cur.hasAttribute("scope") || cur.hasAttribute("item") || cur.hasAttribute("detail")) {
+      return cur;
+    }
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+export function nearestAppEl(el) {
+  let cur = el;
+  while (cur) {
+    if (cur.hasAttribute && cur.hasAttribute("sap")) return cur;
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+export function nearestItemEl(el) {
+  let cur = el;
+  while (cur) {
+    if (cur.hasAttribute("detail")) return cur; // a detail panel resolves like a row
+    if (cur.hasAttribute("item")) return cur;
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+export function isInsideDetail(el) {
+  let cur = el;
+  while (cur) {
+    if (cur.hasAttribute("detail")) return cur;
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+export function ownedBind(scopeEl, field) {
+  let found = null;
+  walkOwned(scopeEl, (el) => {
+    if (!found && el.getAttribute("bind") === field) found = el;
+  });
+  return found;
+}
+
+export function ownedItems(scopeEl, name) {
+  let found = null;
+  walkOwned(scopeEl, (el) => {
+    if (!found && el.getAttribute("items") === name) found = el;
+  });
+  return found;
+}
+
+export function rowsOf(listEl) {
+  return [...listEl.children].filter((c) => c.hasAttribute("item") && !c.hasAttribute("template"));
+}
+
+export function templateOf(listEl) {
+  return [...listEl.children].find((c) => c.hasAttribute("item") && c.hasAttribute("template")) || null;
+}
+
+export function parseStateDecl(str) {
+  const out = [];
+  if (!str) return out;
+  for (const raw of str.trim().split(/\s+/)) {
+    if (!raw) continue;
+    let token = raw;
+    let def;
+    const eq = token.indexOf("=");
+    if (eq >= 0) {
+      def = token.slice(eq + 1);
+      token = token.slice(0, eq);
+    }
+    const parts = token.split(":");
+    const name = parts[0];
+    let type = "string";
+    let transient = false;
+    for (const p of parts.slice(1)) {
+      if (p === "num") type = "num";
+      else if (p === "bool") type = "bool";
+      else if (p === "transient") transient = true;
+    }
+    out.push({ name, type, default: def, transient });
+  }
+  return out;
+}
+
+export function parseTyped(value, type) {
+  if (type === "num") {
+    if (value == null || value === "") return 0;
+    const n = Number(value);
+    return Number.isNaN(n) ? 0 : n;
+  }
+  if (type === "bool") return value === "true" || value === "" || value === "1";
+  return value == null ? "" : value;
+}
+
+export function serializeTyped(value, type) {
+  if (type === "bool") return value ? "true" : "false";
+  return value == null ? "" : String(value);
+}
+
+// Transient state fields (state="x:transient") live on a runtime-only property,
+// never an attribute, so they drive the app but are stripped from the saved DOM.
+// The value attribute is removed on read; the state= declaration itself stays.
+export function readTransient(el, decl) {
+  const store = el._sapTransient || (el._sapTransient = {});
+  if (!(decl.name in store)) {
+    let raw = el.getAttribute(decl.name);
+    if (raw == null) raw = decl.default != null ? decl.default : decl.type === "num" ? "0" : decl.type === "bool" ? "false" : "";
+    store[decl.name] = parseTyped(raw, decl.type);
+  }
+  if (el.hasAttribute(decl.name)) el.removeAttribute(decl.name);
+  return store[decl.name];
+}
+
+export function writeTransient(el, decl, value) {
+  (el._sapTransient || (el._sapTransient = {}))[decl.name] = value;
+  if (el.hasAttribute(decl.name)) el.removeAttribute(decl.name);
+}
+
+// Find the list element a path points at, resolving nearest-scope-first.
+// "cards" -> nearest owned items=cards; "doing.cards" -> [scope=doing] > [items=cards].
+export function resolveListEl(appRoot, fromEl, path) {
+  const segs = String(path).split(".");
+  const listName = segs[segs.length - 1];
+  if (segs.length === 1) {
+    const up = findItemsUp(fromEl, listName);
+    if (up) return up;
+    if (appRoot.getAttribute("items") === listName) return appRoot;
+    return appRoot.querySelector(`[items="${listName}"]`);
+  }
+  const scopeName = segs[segs.length - 2];
+  const scopeEl = [...appRoot.querySelectorAll(`[scope="${scopeName}"]`)].find((s) =>
+    ownedItems(s, listName)
+  );
+  return scopeEl ? ownedItems(scopeEl, listName) : null;
+}
+
+function findItemsUp(fromEl, name) {
+  let scope = nearestScopeEl(fromEl);
+  while (scope) {
+    if (scope.getAttribute("items") === name) return scope; // the scope element is itself the list
+    const found = ownedItems(scope, name);
+    if (found) return found;
+    scope = nearestScopeEl(scope.parentElement);
+  }
+  return null;
+}

package/src/errors.js

@@ -0,0 +1,190 @@
+// Error grammar, the E-code registry, the teaching dictionary, beacons, and
+// per-app diagnostics that drive the green line and Sap.report().
+
+export const REGISTRY = {
+  E01: { slug: "foreign-dialect", behavior: "HALT" },
+  E02: { slug: "moustaches-in-text", behavior: "HALT" },
+  E04: { slug: "duplicate-declaration", behavior: "HALT" },
+  E05: { slug: "reserved-name", behavior: "HALT" },
+  E06: { slug: "global-html-name", behavior: "HALT" },
+  E07: { slug: "calc-cycle", behavior: "ERR" },
+  E08: { slug: "expression-syntax", behavior: "HALT" },
+  E10: { slug: "orphan-item", behavior: "HALT" },
+  E12: { slug: "unknown-state-key", behavior: "ERR" },
+  E15: { slug: "write-to-undeclared-key", behavior: "ERR" },
+  E16: { slug: "write-to-computed-field", behavior: "ERR" },
+  E17: { slug: "unresolvable-action-target", behavior: "HALT" },
+  E18: { slug: "paint-on-form-control", behavior: "HALT" },
+  E20: { slug: "bind-on-non-control", behavior: "HALT" },
+  E22: { slug: "format-type", behavior: "ERR" },
+  E24: { slug: "runtime-expression-throw", behavior: "ERR" },
+  E26: { slug: "circuit-breaker", behavior: "HALT" },
+  E30: { slug: "attr-on-bound-control", behavior: "HALT" },
+  E31: { slug: "password-without-transient", behavior: "HALT" },
+  E32: { slug: "file-bind", behavior: "HALT" },
+  E33: { slug: "dialog-state-open", behavior: "HALT" },
+  E34: { slug: "transient-persist-collision", behavior: "HALT" },
+  W03: { slug: "unknown-colon-attribute", behavior: "WARN" },
+  W04: { slug: "expression-in-when", behavior: "WARN" },
+  W30: { slug: "nonzero-mount-writes", behavior: "WARN" },
+};
+
+export const NATIVE_BOOLEANS = [
+  "disabled", "readonly", "required", "checked", "selected",
+  "multiple", "open", "inert", "autofocus", "novalidate", "hidden",
+];
+
+export const HTML_GLOBALS = new Set([
+  "title", "style", "hidden", "lang", "dir", "translate", "class", "id",
+  "nonce", "autofocus", "tabindex", "contenteditable", "spellcheck",
+  "draggable", "role", "slot", "part", "name", "value", "type",
+  "itemscope", "itemtype", "itemid", "itemprop", "itemref",
+]);
+
+export const RESERVED = new Set([
+  "sap", "scope", "items", "item", "template", "bind", "calc", "text", "show",
+  "attr", "set", "trigger", "move", "sort", "detail", "effect", "invalid",
+  "confirm", "transient", "default", "persist", "sortable",
+  // editmode is a hyperclayjs platform prefix (editmode:onclick), reserved so a
+  // co-loaded admin attribute never collides with a Sap state field name.
+  "editmode",
+]);
+
+export function cssPath(el) {
+  if (!el || el.nodeType !== 1) return "?";
+  if (el.id) return `${el.tagName.toLowerCase()}#${el.id}`;
+  const parts = [];
+  let cur = el;
+  let depth = 0;
+  while (cur && cur.nodeType === 1 && depth < 4) {
+    let seg = cur.tagName.toLowerCase();
+    if (cur.hasAttribute("sap")) seg += "[sap]";
+    else if (cur.parentElement) {
+      const sibs = [...cur.parentElement.children].filter((c) => c.tagName === cur.tagName);
+      if (sibs.length > 1) seg += `:nth-of-type(${sibs.indexOf(cur) + 1})`;
+    }
+    parts.unshift(seg);
+    if (cur.hasAttribute("sap")) break;
+    cur = cur.parentElement;
+    depth++;
+  }
+  return parts.join(" > ");
+}
+
+// Translate a foreign-dialect attribute to its Sap spelling, or null if unknown.
+export function teachForAttr(name) {
+  const n = name.toLowerCase();
+  if (/^x-text$|^x-html$/.test(n)) return `use text="state.x" (Sap paints text only)`;
+  if (/^x-show$|^v-show$|^v-if$/.test(n)) return `use show="expr" (toggles native hidden)`;
+  if (/^x-model$|^v-model$/.test(n)) return `use bind="field"`;
+  if (/^@|^x-on:|^v-on:|^on:/.test(n)) return `use native onclick + Sap(this) (no event directive)`;
+  if (/^:|^x-bind:class$|^v-bind:class$/.test(n)) return `use class:NAME="expr" or attr:NAME="expr"`;
+  if (/^x-for$|^v-for$/.test(n)) return `use items="name" on the container and item template on the row`;
+  if (/^x-data$/.test(n)) return `declare state with state= / bind / items (no JS state object)`;
+  if (/^x-init$/.test(n)) return `use a <script> or onclick + Sap(this)`;
+  if (/^bind:/.test(n)) return `use bind="field"; one-way paint is attr:NAME="expr"`;
+  if (/^x-/.test(n) || /^v-/.test(n)) return `this is a foreign-dialect attribute; Sap has no x-/v- attributes`;
+  return null;
+}
+
+export class HaltError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.sapCode = code;
+    this.isHalt = true;
+  }
+}
+
+// Per-app diagnostics collector.
+export class Diagnostics {
+  constructor(appName) {
+    this.appName = appName;
+    this.errors = [];
+    this.warnings = [];
+    this.halted = false;
+    this.haltReason = null;
+  }
+
+  block(code, el, info = {}) {
+    const slug = (REGISTRY[code] || {}).slug || "error";
+    const rec = {
+      code,
+      slug,
+      el: cssPath(el),
+      attr: info.attr || null,
+      expr: info.expr || null,
+      key: info.key || null,
+      problem: info.problem || "",
+      didYouMean: info.didYouMean || null,
+      fix: info.fix || null,
+      phase: info.phase || "runtime",
+    };
+    const out = ["\n" + (code[0] === "W" ? "sap ⚠ " : "sap ✗ ") + code + " " + slug];
+    out.push(`  at ${rec.el}${rec.attr ? ` — ${rec.attr}="${rec.expr ?? ""}"` : ""}`);
+    if (rec.problem) out.push(`  problem: ${rec.problem}`);
+    if (rec.didYouMean) out.push(`  did you mean: ${rec.didYouMean}`);
+    if (rec.fix) out.push(`  fix: ${rec.fix}`);
+    console.error(out.join("\n"));
+    return rec;
+  }
+
+  error(code, el, info = {}) {
+    const rec = this.block(code, el, info);
+    this.errors.push(rec);
+    return rec;
+  }
+
+  warn(code, el, info = {}) {
+    const rec = this.block(code, el, info);
+    this.warnings.push(rec);
+    return rec;
+  }
+
+  report() {
+    return {
+      ok: this.errors.length === 0 && !this.halted,
+      app: this.appName,
+      halted: this.halted,
+      haltReason: this.haltReason,
+      errors: this.errors.slice(),
+      warnings: this.warnings.slice(),
+    };
+  }
+}
+
+export function setBeacon(el, code) {
+  if (el && el.getAttribute("sap-error") !== code) el.setAttribute("sap-error", code);
+}
+
+export function clearBeacon(el) {
+  if (el && el.hasAttribute("sap-error")) el.removeAttribute("sap-error");
+}
+
+// Levenshtein-based did-you-mean against a set of candidate names.
+export function didYouMean(name, candidates) {
+  let best = null;
+  let bestD = 3;
+  for (const c of candidates) {
+    const d = lev(name, c);
+    if (d < bestD) {
+      bestD = d;
+      best = c;
+    }
+  }
+  return best;
+}
+
+function lev(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...new Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++)
+    for (let j = 1; j <= n; j++)
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+  return dp[m][n];
+}

package/src/helpers.js

@@ -0,0 +1,119 @@
+// The frozen helper set and the format registry.
+// These are passed into every compiled expression as the tail arguments.
+
+export function num(v) {
+  if (typeof v === "number") return v;
+  if (v == null || v === "") return 0;
+  const n = Number(typeof v === "string" ? v.replace(/[$,%\s]/g, "") : v);
+  return Number.isNaN(n) ? 0 : n;
+}
+
+function values(rows, k) {
+  if (!Array.isArray(rows)) return [];
+  if (k == null) return rows;
+  return rows.map((r) => (typeof k === "function" ? k(r) : r == null ? undefined : r[k]));
+}
+
+export function sum(rows, k) {
+  return values(rows, k).reduce((a, v) => a + num(v), 0);
+}
+
+export function count(rows, pred) {
+  if (!Array.isArray(rows)) return 0;
+  if (pred == null) return rows.length;
+  return rows.reduce((a, r) => a + (pred(r) ? 1 : 0), 0);
+}
+
+export function avg(rows, k) {
+  const v = values(rows, k);
+  if (!v.length) return 0;
+  return sum(rows, k) / v.length;
+}
+
+export function min(rows, k) {
+  const v = values(rows, k).filter((x) => x != null && x !== "");
+  if (!v.length) return 0;
+  if (v.every((x) => typeof x === "number" || !Number.isNaN(Number(x)))) {
+    return Math.min(...v.map(Number));
+  }
+  return v.reduce((a, b) => (String(a) <= String(b) ? a : b));
+}
+
+export function max(rows, k) {
+  const v = values(rows, k).filter((x) => x != null && x !== "");
+  if (!v.length) return 0;
+  if (v.every((x) => typeof x === "number" || !Number.isNaN(Number(x)))) {
+    return Math.max(...v.map(Number));
+  }
+  return v.reduce((a, b) => (String(a) >= String(b) ? a : b));
+}
+
+export function plural(n, singular, pluralForm) {
+  const word = num(n) === 1 ? singular : pluralForm != null ? pluralForm : singular + "s";
+  return `${n} ${word}`;
+}
+
+export function days(a, b) {
+  const da = new Date(a);
+  const db = new Date(b);
+  if (Number.isNaN(+da) || Number.isNaN(+db)) return 0;
+  return Math.round((db - da) / 86400000);
+}
+
+function n(v) {
+  return typeof v === "number" ? v : Number(v);
+}
+
+// The format registry. Extensible via Sap.formats.foo = fn.
+export const formats = {
+  usd: (v) => "$" + n(v).toLocaleString("en-US", { maximumFractionDigits: 0 }),
+  usd2: (v) =>
+    "$" + n(v).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 }),
+  pct: (v) => Math.round(n(v)) + "%",
+  pct1: (v) => n(v).toFixed(1) + "%",
+  int: (v) => Math.round(n(v)).toLocaleString("en-US"),
+  num: (v) => n(v).toLocaleString("en-US"),
+  num2: (v) =>
+    n(v).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 }),
+  compact: (v) => n(v).toLocaleString("en-US", { notation: "compact" }),
+  date: (v) => {
+    const d = new Date(v);
+    return Number.isNaN(+d) ? String(v) : d.toLocaleDateString("en-US");
+  },
+  clock: (v) => {
+    const ms = n(v);
+    const total = Math.floor(ms / 100);
+    const tenths = total % 10;
+    const secs = Math.floor(total / 10) % 60;
+    const mins = Math.floor(total / 600);
+    return `${mins}:${String(secs).padStart(2, "0")}.${tenths}`;
+  },
+};
+
+const NUMERIC = new Set(["usd", "usd2", "pct", "pct1", "int", "num", "num2", "compact", "clock"]);
+
+// Apply a named format. Numeric formats throw a tagged E22 error on non-finite input
+// so paint can fail loudly rather than serialize "NaN".
+export function applyFormat(name, v) {
+  if (!name) return v == null ? "" : String(v);
+  const f = formats[name];
+  if (typeof f !== "function") {
+    const e = new Error(`unknown format "${name}"`);
+    e.sapCode = "E22";
+    throw e;
+  }
+  if (NUMERIC.has(name)) {
+    const x = typeof v === "number" ? v : Number(v);
+    if (!Number.isFinite(x)) {
+      const e = new Error(`format "${name}" received ${typeof v === "string" ? `"${v}"` : v}`);
+      e.sapCode = "E22";
+      throw e;
+    }
+  }
+  return f(v);
+}
+
+// The bundle handed to every compiled expression, in frozen argument order.
+export function helperBundle() {
+  return [formats, num, sum, count, avg, min, max, plural, days];
+}