@jxsuite/runtime 1.3.2 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "1.3.2",
+  "version": "2.0.2",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,7 @@
   "exports": {
     ".": "./src/runtime.ts",
     "./expression": "./src/expression.ts",
+    "./pointer": "./src/pointer.ts",
     "./statements": "./src/statements.ts",
     "./types": "./src/types.ts"
   },
@@ -30,10 +31,10 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^1.5.0",
-    "@vue/reactivity": "3.5.40"
+    "@jxsuite/schema": "^1.8.0",
+    "@vue/reactivity": "3.5.41"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.1"
+    "@happy-dom/global-registrator": "^20.11.6"
   }
 }

package/src/cookie.ts

@@ -0,0 +1,104 @@
+/**
+ * The `Cookie` state `$prototype`'s reading and writing, split out because both halves are exactly
+ * the places a cookie binding goes wrong (RFC 6265bis).
+ *
+ * **Reading does not build a regular expression.** The cookie's name comes from the document, and
+ * the old reader interpolated it straight into a pattern — so a name containing a dot, a paren or a
+ * star silently matched the wrong cookie, and one containing an unbalanced bracket threw
+ * SyntaxError from a document that validates. There is nothing to escape here: the cookie header is
+ * a semicolon-separated list, so splitting it and comparing names is both correct and cheaper.
+ *
+ * **`HttpOnly` is absent on purpose, and must stay absent.** A cookie this prototype writes is
+ * written by script through `document.cookie`; the browser refuses to _set_ `HttpOnly` from script
+ * and refuses to _read back_ an `HttpOnly` cookie, so adding the attribute would produce a binding
+ * that writes a value it can never see again. Its absence is the correct behavior for a
+ * script-written cookie, not a missing feature.
+ *
+ * **`Expires` is not supported, and that is also deliberate.** `Max-Age` covers the same ground,
+ * RFC 6265bis §5.5 makes `Max-Age` win wherever both appear, and `Expires` takes an HTTP-date whose
+ * mis-spelling fails silently in the direction of a cookie that never expires.
+ */
+
+/** The cookie attributes an `external-class-def` may declare for the `Cookie` `$prototype`. */
+export interface CookieOptions {
+  domain?: string | undefined;
+  maxAge?: number | undefined;
+  path?: string | undefined;
+  sameSite?: string | undefined;
+  secure?: boolean | undefined;
+}
+
+/** Cookie names carrying RFC 6265bis §4.1.3 prefixes, which constrain their own attributes. */
+const HOST_PREFIX = "__Host-";
+const SECURE_PREFIX = "__Secure-";
+
+/**
+ * The raw (still percent-encoded) value of `name` in a `document.cookie` header, or null.
+ *
+ * @param {string} header The full `name=value; name=value` string.
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function readCookie(header: string, name: string): string | null {
+  for (const pair of header.split(";")) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) {
+      continue;
+    }
+    if (pair.slice(0, eq).trim() === name) {
+      return pair.slice(eq + 1);
+    }
+  }
+  return null;
+}
+
+/**
+ * Serialize one `document.cookie` assignment, applying the attribute rules a name's prefix and its
+ * `SameSite` value already imply.
+ *
+ * Three of those rules are enforced rather than left to the author, because a browser that
+ * disagrees with the attributes **silently drops the cookie** — the write appears to succeed and
+ * the value is simply never there again:
+ *
+ * - `__Host-` requires `Secure`, requires `Path=/`, and forbids `Domain` (RFC 6265bis §4.1.3.2). A
+ *   declared `path` or `domain` is overridden rather than honored, since honoring it would produce
+ *   a cookie no browser will store.
+ * - `__Secure-` requires `Secure` (§4.1.3.1).
+ * - `SameSite=None` requires `Secure` (§5.4.7); without it the cookie is rejected outright.
+ *
+ * @param {string} name
+ * @param {unknown} value JSON-encoded, then percent-encoded.
+ * @param {CookieOptions} options
+ * @returns {string}
+ */
+export function serializeCookie(name: string, value: unknown, options: CookieOptions): string {
+  const hostPrefixed = name.startsWith(HOST_PREFIX);
+  const parts = [`${name}=${encodeURIComponent(JSON.stringify(value))}`];
+
+  if (options.maxAge !== undefined) {
+    parts.push(`Max-Age=${options.maxAge}`);
+  }
+
+  const path = hostPrefixed ? "/" : options.path;
+  if (path) {
+    parts.push(`Path=${path}`);
+  }
+  if (options.domain && !hostPrefixed) {
+    parts.push(`Domain=${options.domain}`);
+  }
+
+  const { sameSite } = options;
+  const secure =
+    options.secure === true ||
+    hostPrefixed ||
+    name.startsWith(SECURE_PREFIX) ||
+    sameSite?.toLowerCase() === "none";
+  if (secure) {
+    parts.push("Secure");
+  }
+  if (sameSite) {
+    parts.push(`SameSite=${sameSite}`);
+  }
+
+  return parts.join("; ");
+}

package/src/expression.ts

@@ -7,8 +7,15 @@
  * @module expression
  */
 
+import {
+  DEFAULT_FORMAT_LOCALE,
+  DEFAULT_TIME_ZONE,
+  INTL_HELPER_PATHS,
+  INTL_LOCALE_PARAM,
+} from "@jxsuite/schema/intl";
 import type { JxExpressionNode, JxExpressionOperand } from "@jxsuite/schema/types";
 import type { JxScope } from "./types.ts";
+import { readPath, refAccessor, refSegments } from "./pointer.ts";
 
 /** The runtime's expression node — the schema's expression model. */
 export type ExpressionNode = JxExpressionNode;
@@ -177,11 +184,9 @@ export const BLESSED_GLOBALS = new Set([
   // String
   "String/fromCharCode",
   "String/fromCodePoint",
-  // Intl (synthetic helpers — see BLESSED_HELPERS; Intl formatters are constructors,
-  // So the plain-function call shape wraps construct-then-format)
-  "Intl/formatNumber",
-  "Intl/formatDate",
-  "Intl/formatRelativeTime",
+  // Intl helpers come from @jxsuite/schema/intl — see BLESSED_HELPERS. One list, so the runtime,
+  // The compiler and the JSON-Schema description cannot drift apart.
+  ...INTL_HELPER_PATHS,
 ]);
 
 /**
@@ -190,23 +195,85 @@ export const BLESSED_GLOBALS = new Set([
  * these; the compiler emits the equivalent inline construct-then-format expression.
  */
 const BLESSED_HELPERS: Record<string, (...a: unknown[]) => unknown> = {
+  "Intl/compare": (a, b, locale, options) =>
+    new Intl.Collator(
+      (locale as string | undefined) ?? DEFAULT_FORMAT_LOCALE,
+      options as Intl.CollatorOptions | undefined,
+    ).compare(a as string, b as string),
+  "Intl/displayName": (code, type, locale, options) =>
+    new Intl.DisplayNames((locale as string | undefined) ?? DEFAULT_FORMAT_LOCALE, {
+      ...(options as Intl.DisplayNamesOptions | undefined),
+      type: (type as Intl.DisplayNamesType | undefined) ?? "language",
+    }).of(code as string),
   "Intl/formatDate": (value, locale, options) =>
-    new Intl.DateTimeFormat(
-      locale as string | undefined,
-      options as Intl.DateTimeFormatOptions | undefined,
-    ).format(new Date(value as string | number | Date)),
+    new Intl.DateTimeFormat((locale as string | undefined) ?? DEFAULT_FORMAT_LOCALE, {
+      timeZone: DEFAULT_TIME_ZONE,
+      ...(options as Intl.DateTimeFormatOptions | undefined),
+    }).format(new Date(value as string | number | Date)),
+  "Intl/formatList": (values, locale, options) =>
+    new Intl.ListFormat(
+      (locale as string | undefined) ?? DEFAULT_FORMAT_LOCALE,
+      options as Intl.ListFormatOptions | undefined,
+    ).format(values as string[]),
   "Intl/formatNumber": (value, locale, options) =>
     new Intl.NumberFormat(
-      locale as string | undefined,
+      (locale as string | undefined) ?? DEFAULT_FORMAT_LOCALE,
       options as Intl.NumberFormatOptions | undefined,
     ).format(value as number),
   "Intl/formatRelativeTime": (value, unit, locale, options) =>
     new Intl.RelativeTimeFormat(
-      locale as string | undefined,
+      (locale as string | undefined) ?? DEFAULT_FORMAT_LOCALE,
       options as Intl.RelativeTimeFormatOptions | undefined,
     ).format(value as number, unit as Intl.RelativeTimeFormatUnit),
+  "Intl/plural": (value, locale, options) =>
+    new Intl.PluralRules(
+      (locale as string | undefined) ?? DEFAULT_FORMAT_LOCALE,
+      options as Intl.PluralRulesOptions | undefined,
+    ).select(value as number),
+  /* Returns the segments as plain strings, because a formula's value has to be JSON — the
+     Segmenter's own iterator of {segment, index, isWordLike} records is not. */
+  "Intl/segment": (value, granularity, locale) =>
+    [
+      ...new Intl.Segmenter((locale as string | undefined) ?? DEFAULT_FORMAT_LOCALE, {
+        granularity: (granularity as "grapheme" | "sentence" | "word" | undefined) ?? "grapheme",
+      }).segment(value as string),
+    ].map((part) => part.segment),
 };
 
+/**
+ * Fill in a helper's omitted `locale` argument from the page's own locale.
+ *
+ * A page under `/fr/` that formats a date without naming a locale means French: the route said so,
+ * `<html lang>` says so, and `hreflang` tells every crawler so. Requiring the author to repeat it
+ * at every call site is how a translated page ends up with English dates and English number
+ * grouping on it — a defect that is invisible to the person who built the site in their own
+ * language, and obvious to every reader of the other one.
+ *
+ * Determinism is untouched, which is the property `DEFAULT_FORMAT_LOCALE` exists to protect:
+ * `$page.locale` is a function of the route and the document (site-architecture.md §13.4), not of
+ * the machine the build runs on. A scope with no `$page` — a component's own state, the runtime
+ * used standalone — keeps the fixed default.
+ *
+ * @param {string} path - Helper callee path, e.g. `Intl/formatNumber`
+ * @param {unknown[]} args - Resolved arguments, in declaration order
+ * @param {JxScope} state
+ * @returns {unknown[]}
+ */
+function withPageLocale(path: string, args: unknown[], state: JxScope): unknown[] {
+  const index = INTL_LOCALE_PARAM[path];
+  if (index === undefined || index < 0 || args[index] != null) {
+    return args;
+  }
+  const page = (state as { $page?: { locale?: unknown } }).$page;
+  const locale = page?.locale;
+  if (typeof locale !== "string" || locale === "") {
+    return args;
+  }
+  const filled = [...args];
+  filled[index] = locale;
+  return filled;
+}
+
 /** Whether a `window#/…` callee ref is on the blessed pure-globals list. */
 export function isBlessedGlobal(ref: string): boolean {
   return ref.startsWith("window#/") && BLESSED_GLOBALS.has(ref.slice("window#/".length));
@@ -339,15 +406,16 @@ function resolveExprRef(ref: string, state: JxScope, event: Event | null, iterCt
     return parts.length > 2 ? getPath(base, parts.slice(2).join("/")) : base;
   }
   if (ref.startsWith("#/state/")) {
-    const sub = ref.slice("#/state/".length);
-    const slash = sub.indexOf("/");
-    if (slash === -1) {
-      return state[sub];
-    }
-    return getPath(state[sub.slice(0, slash)], sub.slice(slash + 1));
+    // One call, not a hand-split leading token: slicing at the first `/` skipped unescaping it, so
+    // `#/state/a~1b/c` looked for a member called `a~1b` rather than `a/b`.
+    return readPath(state, ref.slice("#/state/".length));
   }
   if (ref.startsWith("parent#/")) {
-    return state[ref.slice("parent#/".length)];
+    /*
+     * A prop name may be a path into the prop. This read the whole path as one key and returned
+     * undefined for `parent#/user/name`, while the lowerer above compiled it to a walk.
+     */
+    return readPath(state, ref.slice("parent#/".length));
   }
   if (ref.startsWith("window#/")) {
     return getPath(globalThis.window, ref.slice("window#/".length));
@@ -355,7 +423,7 @@ function resolveExprRef(ref: string, state: JxScope, event: Event | null, iterCt
   if (ref.startsWith("document#/")) {
     return getPath(globalThis.document, ref.slice("document#/".length));
   }
-  return state[ref] ?? null;
+  return readPath(state, ref) ?? null;
 }
 
 /** Resolve a $ref to a writable location — returns { obj, key } for assignment. */
@@ -394,7 +462,12 @@ function resolveWritableRef(
     if (slash === -1) {
       return { key: sub, obj: state };
     }
-    const parts = sub.split("/");
+    /*
+     * The same tokenizer the read path uses. It used to split on `/` alone while the read split on
+     * `/[./]/`, so a write to `#/state/a/b.c` created a key `"b.c"` that the matching read — which
+     * walked `b` then `c` — could never see. The write simply vanished.
+     */
+    const parts = refSegments(sub);
     const lastKey = parts.pop();
     let obj = state;
     // Pointer paths address objects by construction (validated by the schema).
@@ -473,7 +546,7 @@ function evaluateNode(
       const globalPath = calleeRef.slice("window#/".length);
       const helper = BLESSED_HELPERS[globalPath];
       if (helper) {
-        return helper(...argValues);
+        return helper(...withPageLocale(globalPath, argValues, state));
       }
       const fn = getPath(globalThis.window, globalPath) as (...a: unknown[]) => unknown;
       const lastSlash = globalPath.lastIndexOf("/");
@@ -822,20 +895,18 @@ function compileRef(ref: string, opts: CompileOpts) {
     return "_acc";
   }
   if (ref.startsWith("$args/")) {
-    const parts = ref.slice("$args/".length).split("/");
-    return `_args${parts.map((p) => `[${JSON.stringify(p)}]`).join("")}`;
+    return refAccessor("_args", ref.slice("$args/".length));
   }
 
   if (ref.startsWith("event#/")) {
-    const path = ref.slice("event#/".length);
-    return `${e}.${path.replaceAll("/", ".")}`;
+    return refAccessor(e, ref.slice("event#/".length));
   }
 
   if (ref.startsWith("$map/")) {
     const parts = ref.split("/");
     const [, key] = parts;
     if (key === "item") {
-      return parts.length > 2 ? `_item.${parts.slice(2).join(".")}` : "_item";
+      return parts.length > 2 ? refAccessor("_item", parts.slice(2).join("/")) : "_item";
     }
     if (key === "index") {
       return "_index";
@@ -844,21 +915,24 @@ function compileRef(ref: string, opts: CompileOpts) {
   }
 
   if (ref.startsWith("#/state/")) {
-    const path = ref.slice("#/state/".length);
-    return `${s}.${path.replaceAll("/", ".")}`;
+    return refAccessor(s, ref.slice("#/state/".length));
   }
 
   if (ref.startsWith("parent#/")) {
-    return `${s}.${ref.slice("parent#/".length)}`;
+    return refAccessor(s, ref.slice("parent#/".length));
   }
   if (ref.startsWith("window#/")) {
-    return `window.${ref.slice("window#/".length).replaceAll("/", ".")}`;
+    return refAccessor("window", ref.slice("window#/".length));
   }
   if (ref.startsWith("document#/")) {
-    return `document.${ref.slice("document#/".length).replaceAll("/", ".")}`;
+    return refAccessor("document", ref.slice("document#/".length));
   }
 
-  return `${s}.${ref}`;
+  /*
+   * An unrecognized scheme is still a path under state. Pasting it raw emitted `s.a/b`, which is
+   * not a parse error but a division against an undeclared identifier.
+   */
+  return refAccessor(s, ref);
 }
 
 /** Compile a writable $ref target to its JS equivalent (for LHS of assignment). */
@@ -883,19 +957,52 @@ function compileTarget(target: unknown, opts: CompileOpts): string {
  *
  * @param {string} path - The `window#/`-stripped callee path (e.g. "Intl/formatNumber")
  * @param {string[]} args - Already-compiled argument expressions
+ * @param {CompileOpts} opts
  * @returns {string | null}
  */
-function compileHelperCall(path: string, args: string[]): string | null {
+function compileHelperCall(path: string, args: string[], opts: CompileOpts): string | null {
   const a = (i: number) => args[i] ?? "undefined";
+  /*
+   * The same defaults the interpreter applies, inlined — see @jxsuite/schema/intl. The page's own
+   * locale comes first and the fixed one behind it, so an island formats in the language of the
+   * page it is on. `?.` and not `.`: a component's state has no `$page`, and neither does the
+   * runtime evaluated standalone.
+   */
+  const L = `(${opts.statePrefix ?? "state"}?.$page?.locale ?? ${JSON.stringify(DEFAULT_FORMAT_LOCALE)})`;
+  const Z = JSON.stringify(DEFAULT_TIME_ZONE);
   switch (path) {
     case "Intl/formatNumber": {
-      return `new Intl.NumberFormat(${a(1)}, ${a(2)}).format(${a(0)})`;
+      return `new Intl.NumberFormat(${a(1)} ?? ${L}, ${a(2)}).format(${a(0)})`;
     }
     case "Intl/formatDate": {
-      return `new Intl.DateTimeFormat(${a(1)}, ${a(2)}).format(new Date(${a(0)}))`;
+      return (
+        `new Intl.DateTimeFormat(${a(1)} ?? ${L}, ` +
+        `{timeZone: ${Z}, ...${a(2)}}).format(new Date(${a(0)}))`
+      );
     }
     case "Intl/formatRelativeTime": {
-      return `new Intl.RelativeTimeFormat(${a(2)}, ${a(3)}).format(${a(0)}, ${a(1)})`;
+      return `new Intl.RelativeTimeFormat(${a(2)} ?? ${L}, ${a(3)}).format(${a(0)}, ${a(1)})`;
+    }
+    case "Intl/formatList": {
+      return `new Intl.ListFormat(${a(1)} ?? ${L}, ${a(2)}).format(${a(0)})`;
+    }
+    case "Intl/plural": {
+      return `new Intl.PluralRules(${a(1)} ?? ${L}, ${a(2)}).select(${a(0)})`;
+    }
+    case "Intl/compare": {
+      return `new Intl.Collator(${a(2)} ?? ${L}, ${a(3)}).compare(${a(0)}, ${a(1)})`;
+    }
+    case "Intl/displayName": {
+      return (
+        `new Intl.DisplayNames(${a(2)} ?? ${L}, ` +
+        `{...${a(3)}, type: ${a(1)} ?? 'language'}).of(${a(0)})`
+      );
+    }
+    case "Intl/segment": {
+      return (
+        `[...new Intl.Segmenter(${a(2)} ?? ${L}, {granularity: ${a(1)} ?? 'grapheme'})` +
+        `.segment(${a(0)})].map((p) => p.segment)`
+      );
     }
     default: {
       return null;
@@ -925,7 +1032,7 @@ export function compileExpression(node: ExpressionNode, opts: CompileOpts = {}):
       if (!isBlessedGlobal(calleeRef)) {
         throw new Error(`$expression: "${calleeRef}" is not a blessed pure global`);
       }
-      const helperJs = compileHelperCall(calleeRef.slice("window#/".length), args);
+      const helperJs = compileHelperCall(calleeRef.slice("window#/".length), args, opts);
       if (helperJs) {
         return helperJs;
       }
@@ -1038,13 +1145,9 @@ export function compileExpression(node: ExpressionNode, opts: CompileOpts = {}):
 
 // ─── Utilities ───────────────────────────────────────────────────────────────
 
-/** Resolve a dotted/slashed path on an object. */
+/** Resolve a `$ref` path on an object, through the one tokenizer (`pointer.ts`). */
 function getPath(obj: unknown, path: string): unknown {
-  let current: unknown = obj;
-  for (const k of path.split(/[./]/)) {
-    current = (current as Record<string, unknown>)?.[k];
-  }
-  return current;
+  return readPath(obj, path);
 }
 
 // ─── Statement-Engine Surface (spec §20) ─────────────────────────────────────

package/src/pointer.ts

@@ -0,0 +1,130 @@
+/**
+ * The one `$ref` path grammar — the tokenizer, and the JavaScript accessor built from it.
+ *
+ * There used to be five, and they disagreed. Two read paths split a path on `/` **and** `.`; the
+ * compiler's build-time evaluator split on `/` alone; `resolveWritableRef` split on `/` alone, so a
+ * write to `#/state/a/b.c` landed on a key the matching read could never see; and four lowering
+ * functions did neither — they ran `replaceAll("/", ".")` and emitted the result as raw member
+ * access. That last one is why `#/state/items/0` compiled to `s.items.0`, a SyntaxError, while the
+ * build reported success.
+ *
+ * Segments are separated by `/` and nothing else, which is RFC 6901 §3: the ABNF excludes only `/`
+ * and `~` from a reference token, so `.` is an ordinary character and `#/state/user.name` denotes
+ * one member literally named `user.name`. Making the dot ordinary is what lets all five paths share
+ * this file — it was the only rule they differed on.
+ *
+ * @docs framework/concepts/references
+ */
+
+/** `~1` is `/` and `~0` is `~`; RFC 6901 §4 fixes this order so `~01` becomes `~1`, not `/`. */
+export function unescapeToken(token: string): string {
+  return token.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+
+/** `~` and `/` are the two characters a token cannot carry literally (RFC 6901 §3). */
+export function escapeToken(key: string): string {
+  return key.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+/**
+ * Split a `$ref` path — the part after its scheme — into member names.
+ *
+ * An empty path is no segments rather than one empty segment, so `#/state/` reads `state` itself
+ * rather than a member named "".
+ *
+ * @param {string} path - E.g. `user/name`, `items/0`, `a~1b`
+ * @returns {string[]} Unescaped member names
+ */
+export function refSegments(path: string): string[] {
+  if (path === "") {
+    return [];
+  }
+  return path.split("/").map((token) => unescapeToken(token));
+}
+
+/**
+ * Walk a value along a `$ref` path, or `undefined` where the path leaves the object.
+ *
+ * @param {unknown} root
+ * @param {string} path
+ * @returns {unknown}
+ */
+export function readPath(root: unknown, path: string): unknown {
+  let current = root;
+  for (const key of refSegments(path)) {
+    current = (current as Record<string, unknown> | null | undefined)?.[key];
+  }
+  return current;
+}
+
+/**
+ * A segment that can follow a `.` — deliberately ASCII-only, so anything exotic takes the bracket
+ * branch rather than relying on this regex to model ECMAScript's full identifier grammar. Reserved
+ * words are fine: `s.class` and `s.new` are legal member accesses.
+ */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * A JavaScript expression reading `path` from `base`.
+ *
+ * Dotted where a segment is genuinely an identifier, bracketed with a JSON-quoted key where it is
+ * not — the emitted module is read in devtools by the site's author, and `state.cart.push(3)` is
+ * worth keeping over `state["cart"].push(3)`.
+ *
+ * The bug was never dot notation; it was dot notation with no other branch. The compiler ran
+ * `replaceAll("/", ".")` unconditionally, so `#/state/items/0` became `s.items.0` — a SyntaxError
+ * emitted by a build that reported success — and a key holding a hyphen or a space did the same.
+ * `$args/` already bracketed everything, which is why shipped `$args/values/0` formulas worked
+ * while `#/state/items/0` did not. One rule now, with the safe branch as the fallback.
+ *
+ * @param {string} base - Receiver expression, e.g. `s` or `_args`
+ * @param {string} path
+ * @returns {string}
+ */
+export function refAccessor(base: string, path: string): string {
+  let expr = base;
+  for (const key of refSegments(path)) {
+    expr += IDENTIFIER.test(key) ? `.${key}` : `[${JSON.stringify(key)}]`;
+  }
+  return expr;
+}
+
+/**
+ * An object-literal key: bare where it is an identifier, JSON-quoted where it is not.
+ *
+ * Both forms are valid JavaScript, so this is only about what the emitted module reads like — and
+ * quoting is the branch that has to exist, because a document may legally declare a state key of
+ * `user.name` and pasting that raw produced `user.name: 1,`, a SyntaxError.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+export function objectKey(key: string): string {
+  return IDENTIFIER.test(key) ? key : JSON.stringify(key);
+}
+
+/**
+ * A safe identifier naming one binding in a generated `bind`/`on` map.
+ *
+ * The key is emitted as an object-literal key _and_ as a `data-bind` attribute value _and_ as
+ * `on.<key>` member access, so unlike {@link objectKey} it cannot fall back to quoting — it has to
+ * be an identifier outright. Every character outside `[A-Za-z0-9_$]` becomes `_` and a leading
+ * digit gains a prefix; nothing else is touched.
+ *
+ * `$` is deliberately kept. Folding it would rename the `$handler` key while the emitted call site
+ * still said `on.$handler`, unbinding the handler with no error anywhere. Runs of `_` are likewise
+ * left alone: collapsing them made `a__b` and `a_b` collide for cosmetic reasons.
+ *
+ * Distinct paths can still collide (`a/b` and `a.b` both give `a_b`); callers needing uniqueness
+ * compare the paths themselves.
+ *
+ * @param {string} ref - The ref, prefix already stripped by the caller
+ * @returns {string}
+ */
+export function refBindingKey(ref: string): string {
+  const safe = ref.replaceAll(/[^A-Za-z0-9_$]/g, "_");
+  if (safe === "") {
+    return "ref";
+  }
+  return /^\d/.test(safe) ? `_${safe}` : safe;
+}