@jxsuite/schema 1.5.0 → 1.8.1

package/src/format-registry.ts

@@ -10,6 +10,8 @@
  * (fetch + dynamic import) hosts.
  */
 
+import { mediaTypeEssence, mediaTypeProblem } from "./media-type";
+
 export type FormatCapability = "parse" | "serialize" | "discover" | "load";
 
 export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
@@ -22,8 +24,9 @@ export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
 /**
  * All well-known static capability roles across admission blocks (specs/extensions.md §8): format
  * roles plus project-section (`projectData`, `resolvePaths`), compile-away (`lower`), build-time
- * asset emission (`emit`), static asset mounts (`assets`), server-mount (`mount`), and connector
- * (`dialect`, `deploySchema`, `bindings`, `testConnection`) roles.
+ * asset emission (`emit`), `<head>` contribution (`head`), static asset mounts (`assets`),
+ * server-mount (`mount`), and connector (`dialect`, `deploySchema`, `bindings`, `testConnection`)
+ * roles.
  */
 export type ExtensionCapability =
   | FormatCapability
@@ -31,6 +34,7 @@ export type ExtensionCapability =
   | "resolvePaths"
   | "lower"
   | "emit"
+  | "head"
   | "assets"
   | "mount"
   | "dialect"
@@ -44,6 +48,7 @@ export const EXTENSION_CAPABILITIES: readonly ExtensionCapability[] = [
   "resolvePaths",
   "lower",
   "emit",
+  "head",
   "assets",
   "mount",
   "dialect",
@@ -160,6 +165,15 @@ export class FormatEntry {
   readonly classDef: ClassDefLike;
   readonly extensions: string[];
   readonly mediaType: string | null;
+  /**
+   * The media type without its parameters — `text/markdown` for `text/markdown; variant=GFM`.
+   *
+   * Anything that keys on a type rather than describing one wants this: a File System Access
+   * `accept` map, an editor language id. Those broke the moment a format declared the `variant`
+   * parameter RFC 7763 defines, which is a good reason for the distinction to exist in the type
+   * rather than in each caller's split.
+   */
+  readonly mediaTypeEssence: string | null;
   readonly documentKinds: FormatDocumentKind[];
   readonly exportTarget: boolean;
   readonly remote: boolean;
@@ -183,6 +197,7 @@ export class FormatEntry {
     const { format } = classDef;
     this.extensions = (format?.extensions ?? []).map((e) => e.toLowerCase());
     this.mediaType = format?.mediaType ?? null;
+    this.mediaTypeEssence = mediaTypeEssence(this.mediaType);
     this.documentKinds = format?.documentKinds ?? [];
     this.exportTarget = format?.exportTarget === true;
     this.remote = format?.remote === true;
@@ -234,6 +249,21 @@ export class FormatRegistry {
   constructor(entries: FormatEntry[]) {
     this.#entries = entries;
 
+    /*
+     * A declared media type reaches an HTTP header, an editor's file association and a Studio
+     * label. Nothing checked it before, so `text/markdown;variant GFM` — one missing `=` — would
+     * have been served to a browser verbatim as a malformed header value (RFC 6838 §4.2).
+     */
+    for (const entry of entries) {
+      if (entry.mediaType === null) {
+        continue;
+      }
+      const problem = mediaTypeProblem(entry.mediaType);
+      if (problem !== null) {
+        throw new Error(`Format "${entry.name}" declares an invalid mediaType: ${problem}`);
+      }
+    }
+
     // Ambiguous (extension, capability) claims are a configuration error.
     for (const cap of FORMAT_CAPABILITIES) {
       const seen = new Map<string, FormatEntry>();

package/src/guards.ts

@@ -19,9 +19,10 @@ import type {
   JxPrototypeDef,
   JxRef,
   JxServerFnDef,
-  JxStatement,
   JxStateObject,
+  JxStatement,
   JxStyle,
+  JxTagExpression,
 } from "../types";
 
 // ─── JSON shape guards ──────────────────────────────────────────────────────────
@@ -241,3 +242,63 @@ export function paramNames(parameters: JxFunctionDef["parameters"]): string[] {
   }
   return parameters.map((p) => (typeof p === "string" ? p : p.name));
 }
+
+/** Whether an element's `tagName` is a choice rather than a name. */
+export function isTagExpression(tagName: unknown): tagName is { $expression: JxTagExpression } {
+  return isJsonObject(tagName) && isJsonObject(tagName.$expression);
+}
+
+/**
+ * Every tag an element could be, without evaluating anything.
+ *
+ * ONE implementation, shared by the runtime, the three compiler targets and the studio, because
+ * four surfaces each writing their own enumeration is four chances to disagree about what an
+ * element can be — and disagreeing about that is how the `${…}` tagName shipped a page whose SSR
+ * markup and client render used different elements.
+ *
+ * A plain name yields itself, so every caller can treat the two forms alike.
+ */
+export function tagNameCandidates(tagName: unknown): string[] {
+  if (typeof tagName === "string") {
+    return [tagName];
+  }
+  if (!isTagExpression(tagName)) {
+    return [];
+  }
+  const expression = tagName.$expression;
+  if (expression.operator === "?:") {
+    return [...new Set([expression.value, expression.initial])];
+  }
+  return [...new Set([...Object.values(expression.cases), expression.default])];
+}
+
+/**
+ * The tag to show a human when the element could be several.
+ *
+ * The Outline draws one row per node and needs a label that is stable, short and honest: `a|div`
+ * says "this is one element whose tag is chosen" without pretending to know which. Rendering the
+ * first candidate would have been a quieter lie.
+ */
+export function displayTagName(tagName: unknown): string {
+  return typeof tagName === "string" ? tagName : tagNameCandidates(tagName).join("|");
+}
+
+/**
+ * Whether a `state` key is private (`spec.md` §5.6).
+ *
+ * A `#`-prefixed entry is ordinary state in every respect but one: it is not part of the
+ * component's interface. It never reaches the studio property panel, never appears in an exported
+ * CEM manifest, and is never settable through `$props` — which is the clause that needs a predicate
+ * rather than a convention, because the props paths are spread across two tiers.
+ *
+ * The rule lived inline at three call sites before it lived here, spelled `key.startsWith("#")`
+ * each time. That is survivable for two and a drift risk at four, and the interesting direction of
+ * drift is silent: a path that forgets the check does not fail, it just quietly makes a private
+ * entry writable from outside.
+ *
+ * @param {string} key - A `state` key
+ * @returns {boolean}
+ */
+export function isPrivateStateKey(key: string): boolean {
+  return key.startsWith("#");
+}

package/src/ijson.ts

@@ -0,0 +1,205 @@
+/**
+ * I-JSON (RFC 7493): the two ways a JSON document can parse cleanly and still mean something other
+ * than what it says.
+ *
+ * Both matter here more than they would elsewhere, because a Jx document does not stay JSON. It
+ * round-trips through markdown frontmatter and through a Yjs CRDT, and each crossing rebuilds the
+ * object from the parsed value — so anything `JSON.parse` quietly discarded is discarded for good,
+ * and the file the author reopens is not the file they wrote.
+ *
+ * - **Duplicate names** (§2.3). `JSON.parse` keeps the last and says nothing. In a hand-edited
+ *   document — two `state` keys after a bad merge, say — the first one's contents simply vanish.
+ * - **Numbers outside the IEEE 754 double range** (§2.2). `9007199254740993` parses to
+ *   `9007199254740992`, and the next serialization writes the wrong number back to disk.
+ *
+ * Implemented as a scan of the source text rather than a `JSON.parse` reviver, because by the time
+ * a reviver runs the duplicate is already gone. The scanner is deliberately small: it only needs to
+ * know where strings and object keys are, so it does not build a tree or validate the grammar —
+ * `JSON.parse` has already done that by the time this is called.
+ *
+ * @docs framework/agents/authoring-rules
+ */
+
+/** One I-JSON violation, located by the path of the object that contains it. */
+export interface IJsonProblem {
+  kind: "duplicate-key" | "unsafe-number";
+  /** Dotted path to the containing object, `""` at the root. */
+  path: string;
+  /** The duplicated key, or the number literal as written. */
+  detail: string;
+}
+
+const WHITESPACE = new Set([" ", "\t", "\n", "\r"]);
+
+/**
+ * Find I-JSON violations in already-valid JSON text.
+ *
+ * @param {string} text - JSON source that `JSON.parse` accepts
+ * @returns {IJsonProblem[]} Empty when the document is I-JSON
+ */
+export function findIJsonProblems(text: string): IJsonProblem[] {
+  const problems: IJsonProblem[] = [];
+  /**
+   * One frame per open `{` or `[`. Arrays carry a path too, so an object inside one is reported
+   * under the key that names the array rather than under whatever enclosed it.
+   */
+  const stack: { kind: "object" | "array"; path: string; keys?: Set<string> }[] = [];
+  /** The key most recently read, naming the value that follows it. */
+  let pendingKey: string | null = null;
+  let index = 0;
+
+  const currentPath = () => stack.at(-1)?.path ?? "";
+  const childPath = () =>
+    pendingKey === null ? currentPath() : joinPath(currentPath(), pendingKey);
+
+  const readString = (): string => {
+    // Assumes text[index] === '"'; returns the decoded value and leaves index past the closer.
+    index += 1;
+    let out = "";
+    while (index < text.length) {
+      const char = text[index]!;
+      if (char === "\\") {
+        const next = text[index + 1] ?? "";
+        // Only `\uXXXX` needs decoding to compare keys correctly; the rest map one-to-one.
+        if (next === "u") {
+          out += String.fromCodePoint(Number.parseInt(text.slice(index + 2, index + 6), 16));
+          index += 6;
+        } else {
+          out += ESCAPES[next] ?? next;
+          index += 2;
+        }
+        continue;
+      }
+      if (char === '"') {
+        index += 1;
+        return out;
+      }
+      out += char;
+      index += 1;
+    }
+    return out;
+  };
+
+  while (index < text.length) {
+    const char = text[index]!;
+
+    if (WHITESPACE.has(char) || char === "," || char === ":") {
+      index += 1;
+      continue;
+    }
+
+    if (char === "{" || char === "[") {
+      stack.push(
+        char === "{"
+          ? { keys: new Set(), kind: "object", path: childPath() }
+          : { kind: "array", path: childPath() },
+      );
+      pendingKey = null;
+      index += 1;
+      continue;
+    }
+    if (char === "}" || char === "]") {
+      stack.pop();
+      pendingKey = null;
+      index += 1;
+      continue;
+    }
+
+    if (char === '"') {
+      const value = readString();
+      /*
+       * A string is a key when it sits directly inside an object and a `:` follows. Inside an
+       * array it is an element, and the same text on the right of a `:` is a value.
+       */
+      const frame = stack.at(-1);
+      if (frame?.kind === "object" && nextMeaningful(text, index) === ":") {
+        if (frame.keys!.has(value)) {
+          problems.push({ detail: value, kind: "duplicate-key", path: frame.path });
+        }
+        frame.keys!.add(value);
+        pendingKey = value;
+      } else {
+        pendingKey = null;
+      }
+      continue;
+    }
+
+    if (char === "-" || (char >= "0" && char <= "9")) {
+      const start = index;
+      while (index < text.length && /[\d+.eE-]/.test(text[index]!)) {
+        index += 1;
+      }
+      const literal = text.slice(start, index);
+      if (!isSafeJsonNumber(literal)) {
+        problems.push({ detail: literal, kind: "unsafe-number", path: childPath() });
+      }
+      pendingKey = null;
+      continue;
+    }
+
+    // `true`, `false`, `null`. The grammar is already known good, so a run of letters is enough.
+    const before = index;
+    while (index < text.length && /[A-Za-z]/.test(text[index]!)) {
+      index += 1;
+    }
+    if (index === before) {
+      index += 1;
+    }
+    pendingKey = null;
+  }
+
+  return problems;
+}
+
+const ESCAPES: Record<string, string> = {
+  b: "\b",
+  f: "\f",
+  n: "\n",
+  r: "\r",
+  t: "\t",
+};
+
+/** The next non-whitespace character at or after `from`, or "" at the end. */
+function nextMeaningful(text: string, from: number): string {
+  let index = from;
+  while (index < text.length && WHITESPACE.has(text[index]!)) {
+    index += 1;
+  }
+  return text[index] ?? "";
+}
+
+function joinPath(parent: string, key: string): string {
+  return parent === "" ? key : `${parent}.${key}`;
+}
+
+/**
+ * True when a number literal survives a round trip through a double.
+ *
+ * Only integers are judged. A fractional literal is _always_ approximate in binary floating point —
+ * `0.1` is not representable either — so flagging those would flag most real documents and say
+ * nothing about whether the author's value survived.
+ *
+ * @param {string} literal
+ * @returns {boolean}
+ */
+export function isSafeJsonNumber(literal: string): boolean {
+  if (/[.eE]/.test(literal)) {
+    return true;
+  }
+  const value = Number(literal);
+  if (!Number.isFinite(value)) {
+    return false;
+  }
+  // The literal is an integer, so `String(Number(x))` reproduces it exactly when nothing was lost.
+  return String(value) === literal.replace(/^\+/, "");
+}
+
+/** A one-line description of a problem, for a build error or a warning. */
+export function describeIJsonProblem(problem: IJsonProblem): string {
+  const where = problem.path === "" ? "the document root" : `"${problem.path}"`;
+  return problem.kind === "duplicate-key"
+    ? `duplicate key "${problem.detail}" in ${where} — JSON.parse keeps the last one and ` +
+        "silently discards the first (RFC 7493 §2.3)"
+    : `number ${problem.detail} in ${where} cannot be represented exactly and will change when ` +
+        "the document is written back (RFC 7493 §2.2)";
+}

package/src/intl.ts

@@ -0,0 +1,155 @@
+/**
+ * The blessed `Intl` helpers: one list, read by everything that needs to know them.
+ *
+ * **The list used to exist in four places** — the runtime's allow-set, the runtime's dispatch
+ * table, the compiler's emitter, and a prose JSON-Schema description enumerating them by name. The
+ * description was the dangerous one: nothing checked it, so a helper could ship and the schema go
+ * on telling authors it did not exist. The names live here; the runtime and the schema description
+ * both read them, and a test asserts the two agree.
+ *
+ * **Why helpers and not the constructors.** ECMA-402's formatters are constructors, and a formula
+ * is a pure call — `new` is not in the expression grammar and should not be. Each helper wraps
+ * construct-then-format, which is the shape a document author wants anyway.
+ *
+ * **Every helper takes an explicit locale.** `new Intl.NumberFormat(undefined)` reads the _host's_
+ * locale, so the same document compiled on two machines emits different text. A call that names no
+ * locale gets the **page's** — which is a function of the route, not of the build machine — and
+ * failing that the fixed default below; see `site-architecture.md` §13.7.
+ *
+ * Pure data and no imports, so a browser bundle, the compiler and the schema generator can all read
+ * it without pulling anything else in.
+ *
+ * @docs studio/logic/formulas
+ */
+
+/**
+ * The locale a helper uses when a formula names none **and there is no page to ask**.
+ *
+ * **Not the host's.** `new Intl.NumberFormat(undefined)` reads the machine's locale, so the same
+ * document renders `1,234.5` on one build machine and `1.234,5` on another, and a site's output
+ * stops being a function of its input.
+ *
+ * A page's own locale is the better answer where there is one — a page under `/fr/` that formats a
+ * date means French, and it already said so in `<html lang>` — so `$page.locale` is consulted first
+ * (see `INTL_LOCALE_PARAM`). That preserves the property this constant exists for, because
+ * `$page.locale` is a function of the route and the document rather than of the machine. This value
+ * is what remains for a scope with no page: a component's own state, or the runtime evaluated
+ * standalone.
+ */
+export const DEFAULT_FORMAT_LOCALE = "en-US";
+
+/**
+ * The time zone `Intl/formatDate` uses when the formula's options name none.
+ *
+ * The same determinism argument as the locale, and worse in effect: a locale changes how a date
+ * reads, a time zone can change **which day it is**. A post timestamped `2026-08-16T02:00Z` renders
+ * as the 16th in UTC and the 15th in New York, so a build machine's zone would silently move dates
+ * in published HTML. UTC is the one zone that is the same everywhere.
+ */
+export const DEFAULT_TIME_ZONE = "UTC";
+
+/** One blessed helper: its callee path (after `window#/`) and what it wraps. */
+export interface IntlHelper {
+  /** The callee path an expression names, e.g. `Intl/formatNumber`. */
+  path: string;
+  /** The ECMA-402 constructor it wraps. */
+  api: string;
+  /** Parameter names, in order, for documentation and for the compiled call. */
+  params: string[];
+  /** One line, for the formula catalogue and the schema description. */
+  summary: string;
+}
+
+/**
+ * Every blessed `Intl` helper, in the order they are documented.
+ *
+ * **`DurationFormat` is deliberately absent.** Its baseline support is not universal, and a blessed
+ * global that throws on a browser Jx claims to support is worse than one that does not exist: the
+ * author writes a formula that works on their machine and fails on a visitor's.
+ */
+export const INTL_HELPERS: readonly IntlHelper[] = [
+  {
+    api: "Intl.NumberFormat",
+    params: ["value", "locale", "options"],
+    path: "Intl/formatNumber",
+    summary: "Format a number for a locale — grouping, decimals, currency, percent, units.",
+  },
+  {
+    api: "Intl.DateTimeFormat",
+    params: ["value", "locale", "options"],
+    path: "Intl/formatDate",
+    summary: "Format a date or timestamp for a locale. Pass `timeZone` in options.",
+  },
+  {
+    api: "Intl.RelativeTimeFormat",
+    params: ["value", "unit", "locale", "options"],
+    path: "Intl/formatRelativeTime",
+    summary: 'Format a relative time — `-3, "day"` becomes "3 days ago".',
+  },
+  {
+    api: "Intl.ListFormat",
+    params: ["values", "locale", "options"],
+    path: "Intl/formatList",
+    summary: 'Join a list the way a locale does — "a, b, and c", not a hand-written comma join.',
+  },
+  {
+    api: "Intl.PluralRules",
+    params: ["value", "locale", "options"],
+    path: "Intl/plural",
+    summary:
+      'Which plural category a number falls in ("one", "few", "other") — many languages have ' +
+      "more than two, so a ternary on `n === 1` is wrong outside English.",
+  },
+  {
+    api: "Intl.Collator",
+    params: ["a", "b", "locale", "options"],
+    path: "Intl/compare",
+    summary:
+      "Compare two strings for sorting. `<` and `sort()` order by UTF-16 code unit, which puts " +
+      '"Zebra" before "apple" and sorts every accented word into the wrong place.',
+  },
+  {
+    api: "Intl.DisplayNames",
+    params: ["code", "type", "locale", "options"],
+    path: "Intl/displayName",
+    summary:
+      'The name of a language, region, script or currency in a locale — "de" as "German" or ' +
+      '"Deutsch", from CLDR rather than a hand-kept table.',
+  },
+  {
+    api: "Intl.Segmenter",
+    params: ["value", "granularity", "locale"],
+    path: "Intl/segment",
+    summary:
+      "Split text into graphemes, words or sentences (UAX #29). `[...str]` splits code points, " +
+      "so it cuts an emoji with a skin-tone modifier in half.",
+  },
+] as const;
+
+/** Just the callee paths, for the runtime's allow-set. */
+export const INTL_HELPER_PATHS: readonly string[] = INTL_HELPERS.map((helper) => helper.path);
+
+/**
+ * Where each helper's `locale` argument sits, so a call that omits it can be given the page's.
+ *
+ * Derived from `params` rather than written out, for the reason this module exists at all: a
+ * hand-kept second list is what let the schema description drift from the implementation. The
+ * position differs per helper — `formatNumber` takes it second, `formatRelativeTime` third — and a
+ * table that disagreed with the signature would pass the wrong argument silently, which reads as a
+ * formatting bug rather than a wiring one.
+ */
+export const INTL_LOCALE_PARAM: Readonly<Record<string, number>> = Object.fromEntries(
+  INTL_HELPERS.map((helper) => [helper.path, helper.params.indexOf("locale")]),
+);
+
+/**
+ * The helper names as one clause, for the `call` operator's JSON-Schema description.
+ *
+ * Generated rather than typed out, because a hand-written enumeration is what let the schema drift
+ * from the implementation in the first place.
+ *
+ * @returns {string}
+ */
+export function intlHelpersClause(): string {
+  return `the Intl helpers ${INTL_HELPER_PATHS.join(", ")}`;
+}