myphp-runtime 0.0.0-stage → 1.29.0

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# myphp-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed access to the runtime of MyPHP apps,
+for their web frontends.
+
+MyPHP injects its runtime into every page of an app as `window.myphp`. This
+package gives it types and imports. The client that `myphp generate` writes
+for your bound PHP services is built on it, so you mostly use that:
+
+```ts
+import { Greeter, events } from "./myphp"; // generated
+
+const greeting = await Greeter.greet("Ada");
+events.tick.on((time) => console.log(time));
+```
+
+Install it from npm, `npm install myphp-runtime`, or depend on it from the
+MyPHP the app runs on, `"myphp-runtime": "file:<MyPHP>/packages/runtime"`,
+as `myphp init -template web` writes it. Its modules are TypeScript, which
+Vite and Bun take as they are.
+
+Use the package directly for the window and the platform:
+
+```ts
+import { currentWindow, isCallError, isMyPHP, runtime } from "myphp-runtime";
+
+if (isMyPHP() && runtime().platform === "darwin") {
+  document.body.classList.add("mac");
+}
+await currentWindow.toggleMaximize();
+```
+
+A PHP method that streams values through a `MyPHP\Channel` parameter takes
+a `Channel` in its place:
+
+```ts
+import { Channel } from "myphp-runtime";
+
+const lines = new Channel<string>();
+const done = Shell.tail("ls -R", lines);
+for await (const line of lines) console.log(line);
+await done;
+```
+
+A PHP method that throws rejects with a `CallError` (see
+`isCallError`). Outside a MyPHP window, e.g. when the dev server is opened in a
+browser, calls reject and `isMyPHP()` is false.
+
+`myphp-runtime/i18n` formats the messages of the app's catalogs in its pages,
+as `MyPHP\Message` does in PHP: messages of ICU MessageFormat, with the plural
+rules, numbers and dates of `Intl`. `myphp generate` writes a typed module of
+the catalogs next to the client (`locales.ts`) on top of it:
+
+```ts
+import { messages } from "./locales"; // generated
+
+status.textContent = messages.filesSelected(3); // "3 files selected"
+```
+
+`formatMessage(locale, message, args)` formats a message of your own.

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "myphp-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.29.0",
+  "description": "Typed access to the MyPHP runtime in the pages of MyPHP desktop apps",
+  "keywords": ["myphp", "desktop", "webview", "php"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/owner888/myphp.git",
+    "directory": "packages/runtime"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./i18n": "./src/i18n.ts"
+  },
+  "types": "./src/index.ts",
+  "files": ["src", "!src/**/*.test.ts", "README.md"],
+  "scripts": {
+    "test": "bun test"
+  }
+}

package/src/i18n.ts

@@ -0,0 +1,738 @@
+/**
+ * Formats the messages of a MyPHP app's catalogs in its pages: messages of
+ * ICU MessageFormat, as MyPHP\Message formats them in PHP, with the plural
+ * rules, numbers and dates of the browser's `Intl` (mygo-runtime/i18n).
+ * The module `myphp generate` writes next to the TypeScript client
+ * (`locales.ts`) is built on it:
+ *
+ * ```ts
+ * import { messages } from "./locales";
+ *
+ * status.textContent = messages.filesSelected(3); // "3 files selected"
+ * ```
+ *
+ * Use {@link formatMessage} directly to format a message of your own.
+ *
+ * @module
+ */
+
+/** A part of a parsed message. */
+export type MessagePart =
+  | string
+  | { type: "pound" }
+  | { type: "arg"; name: string }
+  | { type: "number" | "date" | "time"; name: string; style: string }
+  | {
+      type: "plural" | "selectordinal" | "select";
+      name: string;
+      offset: number;
+      cases: { key: string; parts: MessagePart[] }[];
+    };
+
+/** The error of a message that does not parse. */
+export class MessageSyntaxError extends Error {
+  constructor(
+    /** The message. */
+    readonly source: string,
+    /** Where in it the error is, in UTF-16 code units. */
+    readonly offset: number,
+    reason: string,
+  ) {
+    super(`${reason} at offset ${offset} of ${JSON.stringify(source)}`);
+    this.name = "MessageSyntaxError";
+  }
+}
+
+const pluralKeywords = ["zero", "one", "two", "few", "many", "other"];
+
+function isPatternSpace(c: string): boolean {
+  return /^[\t\n\v\f\r \u0085\u200e\u200f\u2028\u2029]$/.test(c);
+}
+
+function isPatternSyntax(c: string): boolean {
+  const r = c.codePointAt(0)!;
+  if (r < 0x80) {
+    return (r >= 0x21 && r <= 0x2f) || (r >= 0x3a && r <= 0x40) || (r >= 0x5b && r <= 0x5e) || r === 0x60 || (r >= 0x7b && r <= 0x7e);
+  }
+  return (
+    (r >= 0xa1 && r <= 0xa7) || r === 0xa9 || r === 0xab || r === 0xac || r === 0xae || r === 0xb0 || r === 0xb1 ||
+    r === 0xb6 || r === 0xbb || r === 0xbf || r === 0xd7 || r === 0xf7 ||
+    (r >= 0x2010 && r <= 0x2027) || (r >= 0x2030 && r <= 0x203e) || (r >= 0x2041 && r <= 0x2053) ||
+    (r >= 0x2055 && r <= 0x205e) || (r >= 0x2190 && r <= 0x245f) || (r >= 0x2500 && r <= 0x2775) ||
+    (r >= 0x2794 && r <= 0x2bff) || (r >= 0x2e00 && r <= 0x2e7f) || (r >= 0x3001 && r <= 0x3003) ||
+    (r >= 0x3008 && r <= 0x3020) || r === 0x3030 || r === 0xfd3e || r === 0xfd3f || r === 0xfe45 || r === 0xfe46
+  );
+}
+
+const decimalRe = /^-?\d+(\.\d+)?$/;
+
+/**
+ * Parses a message of ICU MessageFormat, as MyPHP\Message::parse does:
+ * the same messages parse, and fail, in PHP and in pages.
+ */
+export function parseMessage(source: string): MessagePart[] {
+  let i = 0;
+  const s = source;
+  const fail = (reason: string): never => {
+    throw new MessageSyntaxError(source, i, reason);
+  };
+  const space = () => {
+    while (i < s.length && isPatternSpace(s[i]!)) i++;
+  };
+  const word = (): string => {
+    const start = i;
+    while (i < s.length) {
+      const c = String.fromCodePoint(s.codePointAt(i)!);
+      if (isPatternSpace(c) || isPatternSyntax(c)) break;
+      i += c.length;
+    }
+    return s.slice(start, i);
+  };
+  const validName = (name: string): boolean =>
+    /^\d/.test(name) ? /^(0|[1-9]\d*)$/.test(name) : /^[\p{L}_]/u.test(name);
+
+  const message = (depth: number, inPlural: boolean): MessagePart[] => {
+    if (depth > 32) fail("arguments nest too deep");
+    const parts: MessagePart[] = [];
+    let text = "";
+    const flush = () => {
+      if (text !== "") parts.push(text);
+      text = "";
+    };
+    while (i < s.length) {
+      const c = s[i]!;
+      if (c === "'") {
+        i++;
+        if (s[i] === "'") {
+          text += "'";
+          i++;
+        } else if (i < s.length && (s[i] === "{" || s[i] === "}" || (s[i] === "#" && inPlural))) {
+          while (i < s.length) {
+            if (s[i] === "'") {
+              if (s[i + 1] === "'") {
+                text += "'";
+                i += 2;
+                continue;
+              }
+              i++;
+              break;
+            }
+            text += s[i];
+            i++;
+          }
+        } else {
+          text += "'";
+        }
+      } else if (c === "{") {
+        flush();
+        parts.push(argument(depth));
+      } else if (c === "}") {
+        break;
+      } else if (c === "#" && inPlural) {
+        flush();
+        parts.push({ type: "pound" });
+        i++;
+      } else {
+        text += c;
+        i++;
+      }
+    }
+    flush();
+    return parts;
+  };
+
+  const argument = (depth: number): MessagePart => {
+    i++; // {
+    space();
+    const name = word();
+    if (name === "") fail("an argument has no name");
+    if (!validName(name)) fail(`${JSON.stringify(name)} is not an argument name`);
+    space();
+    if (i >= s.length) fail(`unclosed argument {${name}`);
+    if (s[i] === "}") {
+      i++;
+      return { type: "arg", name };
+    }
+    if (s[i] !== ",") fail(`expected , or } after the argument name ${JSON.stringify(name)}`);
+    i++;
+    space();
+    const type = word();
+    space();
+    if (type === "number" || type === "date" || type === "time") {
+      let style = "";
+      if (s[i] === ",") {
+        i++;
+        const start = i;
+        let nest = 0;
+        for (;;) {
+          if (i >= s.length) fail("unclosed style");
+          const c = s[i];
+          if (c === "'") {
+            const end = s.indexOf("'", i + 1);
+            if (end < 0) fail("unclosed quote in a style");
+            i = end + 1;
+            continue;
+          }
+          if (c === "{") nest++;
+          if (c === "}") {
+            if (nest === 0) break;
+            nest--;
+          }
+          i++;
+        }
+        style = s.slice(start, i).replace(/^[\s\u0085\u200e\u200f]+|[\s\u0085\u200e\u200f]+$/g, "");
+        if (style === "") fail(`the ${type} argument ${JSON.stringify(name)} has an empty style`);
+      }
+      if (s[i] !== "}") fail(`unclosed argument {${name}, ${type}`);
+      i++;
+      return { type, name, style };
+    }
+    if (type === "") fail(`the argument ${JSON.stringify(name)} has no type`);
+    if (type !== "plural" && type !== "selectordinal" && type !== "select") {
+      fail(`unknown argument type ${JSON.stringify(type)} (want number, date, time, plural, selectordinal or select)`);
+    }
+    if (s[i] !== ",") fail(`expected , after ${type}`);
+    i++;
+    const plural = type !== "select";
+    let offset = 0;
+    space();
+    if (plural && s.startsWith("offset:", i)) {
+      i += "offset:".length;
+      space();
+      const start = i;
+      while (i < s.length && s[i]! >= "0" && s[i]! <= "9") i++;
+      if (start === i || i - start > 15) fail("offset: needs a number");
+      offset = Number(s.slice(start, i));
+    }
+    const cases: { key: string; parts: MessagePart[] }[] = [];
+    for (;;) {
+      space();
+      if (i >= s.length) fail(`unclosed ${type} argument ${JSON.stringify(name)}`);
+      if (s[i] === "}") {
+        i++;
+        break;
+      }
+      let key: string;
+      if (plural && s[i] === "=") {
+        i++;
+        const start = i;
+        while (i < s.length && /[0-9.]/.test(s[i]!)) i++;
+        const value = s.slice(start, i);
+        if (!/^\d+(\.\d+)?$/.test(value)) fail(`=${value} is not a number`);
+        key = "=" + value;
+      } else {
+        key = word();
+        if (key === "") fail(`expected a case of the ${type} argument ${JSON.stringify(name)}`);
+        if (plural && !pluralKeywords.includes(key)) {
+          fail(`${JSON.stringify(key)} is not a plural category (zero, one, two, few, many, other)`);
+        }
+      }
+      if (cases.some((c) => c.key === key)) fail(`the ${type} argument ${JSON.stringify(name)} has the case ${key} twice`);
+      space();
+      if (s[i] !== "{") fail(`expected { after the case ${key}`);
+      i++;
+      const parts = message(depth + 1, plural);
+      if (i >= s.length) fail(`unclosed case ${key}`);
+      i++; // }
+      cases.push({ key, parts });
+    }
+    if (!cases.some((c) => c.key === "other")) fail(`the ${type} argument ${JSON.stringify(name)} has no other case`);
+    return { type: type as "plural" | "selectordinal" | "select", name, offset, cases };
+  };
+
+  const parts = message(0, false);
+  if (i < s.length) fail("unmatched }");
+  return parts;
+}
+
+/** A number as a page formats it: its value, and its visible fraction digits. */
+interface Num {
+  value: number;
+  /** The fraction digits a string of a decimal number shows, as 2 for "1.50". */
+  digits?: number;
+  /** The decimal number as written, for the cases of exact values. */
+  text: string;
+}
+
+function toNum(v: unknown): Num | undefined {
+  if (typeof v === "number") return Number.isFinite(v) ? { value: v, text: String(v) } : undefined;
+  if (typeof v === "bigint") return { value: Number(v), text: v.toString() };
+  if (typeof v === "string") {
+    const t = v.trim();
+    if (!decimalRe.test(t)) return undefined;
+    return { value: Number(t), digits: t.includes(".") ? t.split(".")[1]!.length : 0, text: t };
+  }
+  return undefined;
+}
+
+/** Writes n less offset, with the fraction digits of n. */
+function minus(n: Num, offset: number): Num {
+  if (offset === 0) return n;
+  const value = n.value - offset;
+  if (n.digits !== undefined) return { value, digits: n.digits, text: value.toFixed(n.digits) };
+  return { value, text: String(value) };
+}
+
+/** Whether a number written as text equals an exact case, "=1" for 1.0. */
+function exactEquals(text: string, exact: string): boolean {
+  if (text.startsWith("-")) return false;
+  const norm = (s: string) => {
+    let [i, f = ""] = s.split(".");
+    i = i!.replace(/^0+(?=\d)/, "");
+    f = f.replace(/0+$/, "");
+    return f === "" ? i : `${i}.${f}`;
+  };
+  return /^\d+(\.\d+)?$/.test(text) && norm(text) === norm(exact);
+}
+
+const caches = new Map<string, Intl.PluralRules | Intl.NumberFormat | Intl.DateTimeFormat>();
+
+function cached<T extends Intl.PluralRules | Intl.NumberFormat | Intl.DateTimeFormat>(key: string, make: () => T): T {
+  let v = caches.get(key) as T | undefined;
+  if (!v) {
+    v = make();
+    if (caches.size > 256) caches.clear();
+    caches.set(key, v);
+  }
+  return v;
+}
+
+function safeLocale(locale: string): string | undefined {
+  try {
+    return Intl.getCanonicalLocales(locale)[0];
+  } catch {
+    return undefined;
+  }
+}
+
+function pluralCategory(locale: string, n: Num, type: "cardinal" | "ordinal"): string {
+  const digits = n.digits;
+  const pr = cached(`p|${locale}|${type}|${digits ?? ""}`, () =>
+    new Intl.PluralRules(safeLocale(locale), digits === undefined ? { type } : { type, minimumFractionDigits: digits, maximumFractionDigits: digits }),
+  );
+  return (pr as Intl.PluralRules).select(Math.abs(n.value));
+}
+
+/** The hooks that write numbers and dates, which tests and apps may replace. */
+export const formatters = {
+  /**
+   * Writes a number in an ICU number style: "" (the default), "integer",
+   * "percent", or a skeleton ("::percent .00"), of which this formatter
+   * reads percent, integer, precision-integer, the precision of fraction
+   * digits (.00, .0#, .##), group-off and currency/, and writes the rest
+   * as the default. MyPHP\Message reads the same, but currencies.
+   */
+  number(locale: string, n: number, style: string, digits?: number): string {
+    const options: Intl.NumberFormatOptions & { roundingMode?: string } = {};
+    const stems = style.startsWith("::") ? style.slice(2).trim().split(/\s+/) : [style];
+    let fraction = false;
+    for (const stem of stems) {
+      if (stem === "integer" || stem === "precision-integer") {
+        options.maximumFractionDigits = 0;
+        options.roundingMode = "halfEven";
+      } else if (stem === "percent") {
+        options.style = "percent";
+        options.roundingMode = "halfEven";
+      } else if (stem === "group-off") {
+        options.useGrouping = false;
+      } else if (/^\.[0#]+$/.test(stem)) {
+        options.minimumFractionDigits = stem.split("0").length - 1;
+        options.maximumFractionDigits = stem.length - 1;
+        fraction = true;
+      } else if (stem.startsWith("currency/")) {
+        options.style = "currency";
+        options.currency = stem.slice("currency/".length);
+      }
+    }
+    if (digits !== undefined && !fraction && options.style === undefined && options.maximumFractionDigits === undefined) {
+      options.minimumFractionDigits = options.maximumFractionDigits = Math.min(digits, 100);
+    }
+    const nf = cached(`n|${locale}|${JSON.stringify(options)}`, () => new Intl.NumberFormat(safeLocale(locale), options));
+    return (nf as Intl.NumberFormat).format(n);
+  },
+  /**
+   * Writes a time: its date, its time or both ("datetime"), in an ICU
+   * style, "short", "medium" (the default), "long" or "full", or a
+   * skeleton of CLDR ("::yMMMd"), which Intl finds the locale's pattern
+   * of as MyPHP\DateFormatter does.
+   */
+  date(locale: string, d: Date, kind: "date" | "time" | "datetime", style: string): string {
+    const s = (["short", "medium", "long", "full"].includes(style) ? style : "medium") as "short" | "medium" | "long" | "full";
+    const options: Intl.DateTimeFormatOptions = style.startsWith("::")
+      ? skeletonOptions(style.slice(2).trim())
+      : kind === "date"
+        ? { dateStyle: s }
+        : kind === "time"
+          ? { timeStyle: s }
+          : { dateStyle: "short", timeStyle: "short" };
+    const df = cached(`d|${locale}|${JSON.stringify(options)}`, () => new Intl.DateTimeFormat(safeLocale(locale), options));
+    return (df as Intl.DateTimeFormat).format(d);
+  },
+};
+
+/**
+ * The options of Intl.DateTimeFormat of a skeleton of CLDR, "yMMMd" or
+ * "jm": V8 makes the skeleton back of them, and finds its pattern with
+ * ICU's DateTimePatternGenerator. An hour letter other than j is an
+ * hourCycle, as in MyPHP\DateFormatter. EEEEEE, CLDR's short weekday
+ * ("Mo"), has no option of Intl: it is the abbreviated one ("Mon"), where
+ * MyPHP writes the short one.
+ */
+export function skeletonOptions(skeleton: string): Intl.DateTimeFormatOptions {
+  const o: Intl.DateTimeFormatOptions = {};
+  for (const [field] of skeleton.matchAll(/([A-Za-z])\1*/g)) {
+    const n = field.length;
+    switch (field[0]) {
+      case "y":
+        o.year = n === 2 ? "2-digit" : "numeric";
+        break;
+      case "M":
+      case "L":
+        o.month = n === 1 ? "numeric" : n === 2 ? "2-digit" : n === 3 ? "short" : n === 4 ? "long" : "narrow";
+        break;
+      case "d":
+        o.day = n === 2 ? "2-digit" : "numeric";
+        break;
+      case "E":
+      case "c":
+        o.weekday = n === 4 ? "long" : n === 5 ? "narrow" : "short";
+        break;
+      case "j":
+      case "h":
+      case "H":
+      case "K":
+      case "k":
+        o.hour = n === 2 ? "2-digit" : "numeric";
+        if (field[0] === "h") o.hourCycle = "h12";
+        if (field[0] === "H") o.hourCycle = "h23";
+        if (field[0] === "K") o.hourCycle = "h11";
+        if (field[0] === "k") o.hourCycle = "h24";
+        break;
+      case "m":
+        o.minute = n === 2 ? "2-digit" : "numeric";
+        break;
+      case "s":
+        o.second = n === 2 ? "2-digit" : "numeric";
+        break;
+      case "z":
+      case "v":
+        o.timeZoneName = n >= 4 ? "long" : "short";
+        break;
+    }
+  }
+  return o;
+}
+
+function valueString(locale: string, v: unknown): string {
+  if (typeof v === "string") return v;
+  if (v instanceof Date) return formatters.date(locale, v, "datetime", "short");
+  if (v === null || v === undefined) return "";
+  if (typeof v === "number" || typeof v === "bigint") {
+    const n = toNum(v);
+    return n ? formatters.number(locale, n.value, "", n.digits) : String(v);
+  }
+  if (v instanceof Error) return v.message;
+  return String(v);
+}
+
+/** Transforms the text of a message for a pseudo locale. */
+interface Pseudo {
+  text(s: string): string;
+  placeholder(s: string): string;
+  wrap(s: string): string;
+}
+
+const accented: Record<string, string> = {
+  a: "å", b: "ƀ", c: "ç", d: "ð", e: "é", f: "ƒ", g: "ĝ", h: "ĥ", i: "î", j: "ĵ", k: "ķ", l: "ļ", m: "ɱ",
+  n: "ñ", o: "ö", p: "þ", q: "ǫ", r: "ŕ", s: "š", t: "ţ", u: "û", v: "ṽ", w: "ŵ", x: "ẋ", y: "ý", z: "ž",
+  A: "Å", B: "Ɓ", C: "Ç", D: "Ð", E: "É", F: "Ƒ", G: "Ĝ", H: "Ĥ", I: "Î", J: "Ĵ", K: "Ķ", L: "Ļ", M: "Ṁ",
+  N: "Ñ", O: "Ö", P: "Þ", Q: "Ǫ", R: "Ŕ", S: "Š", T: "Ţ", U: "Û", V: "Ṽ", W: "Ŵ", X: "Ẋ", Y: "Ý", Z: "Ž",
+};
+
+const padWords = "one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen seventeen eighteen nineteen twenty".split(" ");
+
+const RLM = "\u200f";
+const RLO = "\u202e";
+const PDF = "\u202c";
+
+/** The pseudo locales, which test layouts without translations. */
+export const pseudoLocales = ["en-XA", "ar-XB"] as const;
+
+function canonical(tag: string): string {
+  return safeLocale(tag.replace(/_/g, "-").split(/[.@]/)[0]!) ?? "";
+}
+
+/** Strips the extensions of a canonical tag, as "-u-ca-buddhist". */
+function stripExtensions(tag: string): string {
+  const parts = tag.split("-");
+  const i = parts.findIndex((p, i) => i > 0 && p.length === 1);
+  return i < 0 ? tag : parts.slice(0, i).join("-");
+}
+
+/** Reports whether tag is a pseudo locale: en-XA or ar-XB. */
+export function isPseudoLocale(tag: string): boolean {
+  return (pseudoLocales as readonly string[]).includes(stripExtensions(canonical(tag)));
+}
+
+function pseudoFor(locale: string): Pseudo | undefined {
+  switch (stripExtensions(canonical(locale))) {
+    case "en-XA": {
+      let length = 0;
+      return {
+        text(s) {
+          let out = "";
+          for (const c of s) {
+            out += accented[c] ?? c;
+            length++;
+          }
+          return out;
+        },
+        placeholder: (s) => s,
+        wrap(s) {
+          const pad = Math.floor((length * 2 + 4) / 5);
+          let out = "[" + s;
+          for (let i = 0, n = 0; n < pad; i++) {
+            const w = padWords[i % padWords.length]!;
+            out += " " + w;
+            n += 1 + w.length;
+          }
+          return out + "]";
+        },
+      };
+    }
+    case "ar-XB":
+      return {
+        text: (s) => s.replace(/[^\s]+/gu, (w) => RLM + RLO + w + PDF + RLM),
+        placeholder: (s) => RLM + s + RLM,
+        wrap: (s) => s,
+      };
+  }
+  return undefined;
+}
+
+function formatParts(
+  parts: MessagePart[],
+  locale: string,
+  pluralLocale: string,
+  args: Record<string, unknown>,
+  pseudo: Pseudo | undefined,
+  pound: { num?: Num; raw?: unknown } | undefined,
+): string {
+  let out = "";
+  const placeholder = (s: string) => (pseudo ? pseudo.placeholder(s) : s);
+  for (const part of parts) {
+    if (typeof part === "string") {
+      out += pseudo ? pseudo.text(part) : part;
+      continue;
+    }
+    if (part.type === "pound") {
+      if (!pound) {
+        out += "#";
+      } else if (pound.num) {
+        out += placeholder(formatters.number(locale, pound.num.value, "", pound.num.digits));
+      } else {
+        out += placeholder(valueString(locale, pound.raw));
+      }
+      continue;
+    }
+    if (!Object.prototype.hasOwnProperty.call(args, part.name)) {
+      out += `{${part.name}}`;
+      continue;
+    }
+    const v = args[part.name];
+    switch (part.type) {
+      case "arg":
+        out += placeholder(valueString(locale, v));
+        break;
+      case "number": {
+        const n = toNum(v);
+        out += placeholder(n ? formatters.number(locale, n.value, part.style, n.digits) : valueString(locale, v));
+        break;
+      }
+      case "date":
+      case "time":
+        out += placeholder(v instanceof Date ? formatters.date(locale, v, part.type, part.style) : valueString(locale, v));
+        break;
+      case "select": {
+        const key = typeof v === "string" ? v : typeof v === "number" ? (toNum(v)?.text ?? String(v)) : String(v);
+        const c = part.cases.find((c) => c.key === key) ?? part.cases.find((c) => c.key === "other")!;
+        out += formatParts(c.parts, locale, pluralLocale, args, pseudo, pound);
+        break;
+      }
+      case "plural":
+      case "selectordinal": {
+        const n = toNum(v);
+        const other = part.cases.find((c) => c.key === "other")!;
+        if (!n) {
+          out += formatParts(other.parts, locale, pluralLocale, args, pseudo, { raw: v });
+          break;
+        }
+        let chosen = part.cases.find((c) => c.key.startsWith("=") && exactEquals(n.text, c.key.slice(1)));
+        const shown = minus(n, part.offset);
+        if (!chosen) {
+          const cat = pluralCategory(pluralLocale, shown, part.type === "plural" ? "cardinal" : "ordinal");
+          chosen = part.cases.find((c) => c.key === cat) ?? other;
+        }
+        out += formatParts(chosen.parts, locale, pluralLocale, args, pseudo, { num: shown });
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+const parsedCache = new Map<string, MessagePart[]>();
+
+function parsed(message: string): MessagePart[] {
+  let parts = parsedCache.get(message);
+  if (!parts) {
+    parts = parseMessage(message);
+    parsedCache.set(message, parts);
+  }
+  return parts;
+}
+
+/**
+ * Formats a message of ICU MessageFormat with the values of its arguments
+ * for locale, as MyPHP\Message::format does: its plural rules
+ * pick the cases, its conventions write numbers and dates, and the pseudo
+ * locales en-XA and ar-XB transform the message. An argument args lacks is
+ * written as it is, `{name}`. Throws a {@link MessageSyntaxError} for a
+ * message that does not parse.
+ */
+export function formatMessage(locale: string, message: string, args: Record<string, unknown> = {}): string {
+  const pseudo = pseudoFor(locale);
+  return format(parsed(message), pseudo ? "en" : locale, pseudo ? "en" : locale, args, pseudo);
+}
+
+function format(parts: MessagePart[], locale: string, pluralLocale: string, args: Record<string, unknown>, pseudo: Pseudo | undefined): string {
+  const out = formatParts(parts, locale, pluralLocale, args, pseudo, undefined);
+  return pseudo ? pseudo.wrap(out) : out;
+}
+
+/** The data of a catalog, as the module `myphp generate` writes has it. */
+export interface CatalogData {
+  /** The source language, which every message falls back to. */
+  source: string;
+  /** The languages of the catalog: the source, then the others. */
+  languages: string[];
+  /** For each language, the languages it falls back along: itself, its parents, the source. */
+  fallbacks: Record<string, string[]>;
+  /** The names of the arguments of each key, in the order its function takes them. */
+  params: Record<string, string[]>;
+  /** The messages of each language by key. */
+  messages: Record<string, Record<string, string>>;
+}
+
+/** A catalog of messages in a page, which {@link createCatalog} returns. */
+export interface Catalog<M> {
+  /** The languages of the catalog: the source, then the others. */
+  readonly languages: readonly string[];
+  /** Formats the message of key in locale, or returns key without one. */
+  format(locale: string, key: string, args?: Record<string, unknown>): string;
+  /** Returns the language of the catalog whose messages locale says. */
+  resolve(locale: string): string;
+  /** The messages in the language the page shows, read at each call. */
+  messages(): M;
+  /** The messages in the language of locale. */
+  messagesIn(locale: string): M;
+}
+
+/**
+ * Returns the language the page shows: the app's, which the MyPHP runtime
+ * holds (`window.myphp.locale`, set before the page's scripts run), else
+ * the browser's first preferred language.
+ */
+export function currentLocale(): string {
+  const rt = (globalThis as { myphp?: { locale?: unknown } }).myphp;
+  const locale = typeof rt?.locale === "function" ? (rt.locale as () => unknown)() : rt?.locale;
+  if (typeof locale === "string" && locale !== "") return locale;
+  if (typeof navigator !== "undefined") return navigator.languages?.[0] ?? navigator.language ?? "";
+  return "";
+}
+
+/** Creates the catalog of a module `myphp generate` wrote. */
+export function createCatalog<M>(data: CatalogData): Catalog<M> {
+  const resolved = new Map<string, string>();
+  const resolve = (locale: string): string => {
+    let r = resolved.get(locale);
+    if (r !== undefined) return r;
+    r = data.source;
+    const tag = stripExtensions(canonical(locale));
+    if (data.languages.includes(tag)) {
+      r = tag;
+    } else if (tag !== "" && !isPseudoLocale(tag)) {
+      // The tag without its last subtags, then a language written in the
+      // same script, as zh-Hant for zh-TW.
+      const found = truncations(tag).find((t) => data.languages.includes(t)) ?? sameScript(tag, data.languages);
+      if (found) r = found;
+    }
+    resolved.set(locale, r);
+    return r;
+  };
+  const has = (o: object, k: string): boolean => Object.prototype.hasOwnProperty.call(o, k);
+  const lookup = (locale: string, key: string): [string, string] | undefined => {
+    const lang = isPseudoLocale(locale) ? data.source : resolve(locale);
+    for (const t of data.fallbacks[lang] ?? [data.source]) {
+      // Own keys only: a key named as a property of every object, as
+      // "toString", is a message only where the catalog has it.
+      const messages = has(data.messages, t) ? data.messages[t] : undefined;
+      const m = messages && has(messages, key) ? messages[key] : undefined;
+      if (m !== undefined) return [m, t];
+    }
+    return undefined;
+  };
+  const formatKey = (locale: string, key: string, args: Record<string, unknown> = {}): string => {
+    const found = lookup(locale, key);
+    if (!found) return key;
+    const [message, lang] = found;
+    let parts: MessagePart[];
+    try {
+      parts = parsed(message);
+    } catch {
+      return key;
+    }
+    const pseudo = pseudoFor(locale);
+    const numbers = pseudo || locale === "" ? lang : locale;
+    return format(parts, numbers, lang, args, pseudo);
+  };
+  const bind = (locale: () => string): M => {
+    const out: Record<string, (...values: unknown[]) => string> = {};
+    for (const [key, names] of Object.entries(data.params)) {
+      out[key] = (...values: unknown[]) => {
+        const args: Record<string, unknown> = {};
+        names.forEach((name, i) => (args[name] = values[i]));
+        return formatKey(locale(), key, args);
+      };
+    }
+    return out as M;
+  };
+  return {
+    languages: data.languages,
+    format: formatKey,
+    resolve,
+    messages: () => bind(currentLocale),
+    messagesIn: (locale) => bind(() => locale),
+  };
+}
+
+function truncations(tag: string): string[] {
+  const parts = tag.split("-");
+  const out: string[] = [];
+  for (let n = parts.length; n > 0; n--) out.push(parts.slice(0, n).join("-"));
+  return out;
+}
+
+/** The first of langs in the language and script of tag. */
+function sameScript(tag: string, langs: string[]): string | undefined {
+  try {
+    const want = new Intl.Locale(tag).maximize();
+    const same = langs.filter((l) => {
+      const have = new Intl.Locale(l).maximize();
+      return have.language === want.language && have.script === want.script;
+    });
+    return same.find((l) => new Intl.Locale(l).maximize().region === want.region) ?? same[0];
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,268 @@
+/**
+ * Typed access to the MyPHP runtime, which MyPHP injects into every page of
+ * an app as `window.myphp`. The client that `myphp generate` writes for your PHP
+ * services is built on it; use it directly for window controls and the
+ * platform:
+ *
+ * ```ts
+ * import { currentWindow, runtime } from "myphp-runtime";
+ *
+ * if (runtime().platform === "darwin") document.body.classList.add("mac");
+ * await currentWindow.toggleMaximize();
+ * ```
+ *
+ * @module
+ */
+import type {
+  Channel as ChannelType,
+  Direction,
+  LocaleChange,
+  Runtime,
+  ThemePreferences,
+  WindowControls,
+} from "./types";
+
+export type { Direction, LocaleChange, Platform, Runtime, ThemePreferences, WindowControls } from "./types";
+
+declare global {
+  interface Window {
+    /** The MyPHP runtime; missing outside MyPHP windows. */
+    myphp?: Runtime;
+  }
+}
+
+/** Reports whether the page runs inside a MyPHP window. */
+export function isMyPHP(): boolean {
+  return typeof globalThis === "object" && (globalThis as { myphp?: Runtime }).myphp !== undefined;
+}
+
+/**
+ * Returns the MyPHP runtime. Throws when the page is not running inside a
+ * MyPHP window, e.g. when the dev server is opened in a regular browser.
+ */
+export function runtime(): Runtime {
+  const rt = (globalThis as { myphp?: Runtime }).myphp;
+  if (!rt) throw new Error("myphp: runtime not found; is this page running inside a MyPHP window?");
+  return rt;
+}
+
+/**
+ * Calls a bound PHP method by name, e.g. `call("Greeter.greet", "Ada")`.
+ * Prefer the typed client generated by `myphp generate`. A PHP exception rejects
+ * with a {@link CallError}.
+ */
+export function call<T = unknown>(method: string, ...args: unknown[]): Promise<T> {
+  try {
+    return runtime().call<T>(method, ...args);
+  } catch (err) {
+    return Promise.reject(err);
+  }
+}
+
+/**
+ * A stream of values from a PHP method that takes a `MyPHP\Channel`.
+ * Create one, pass it to the call in place of that parameter, and iterate
+ * it or handle its values with `onmessage`:
+ *
+ * ```ts
+ * const lines = new Channel<string>();
+ * const done = Shell.tail("ping -c 3 example.com", lines);
+ * for await (const line of lines) output.append(line + "\n");
+ * await done;
+ * ```
+ *
+ * It closes when the method returns; `close()`, or breaking out of the
+ * loop, stops the method. A channel serves one call.
+ */
+export type Channel<T = unknown> = ChannelType<T>;
+
+/** Creates a {@link Channel}, optionally with its `onmessage` handler. */
+export const Channel = function <T>(onmessage?: (value: T) => void): Channel<T> {
+  return runtime().channel<T>(onmessage);
+} as unknown as new <T = unknown>(onmessage?: (value: T) => void) => Channel<T>;
+
+/** Subscribes to a PHP event by name. Returns a function that unsubscribes. */
+export function on<T = unknown>(name: string, listener: (payload: T) => void): () => void {
+  return runtime().on<T>(name, listener);
+}
+
+/** Like {@link on}, but unsubscribes after the first event. */
+export function once<T = unknown>(name: string, listener: (payload: T) => void): () => void {
+  return runtime().once<T>(name, listener);
+}
+
+/**
+ * The language the app shows, a BCP 47 tag such as "en" or "zh-Hans"
+ * (`App::locale()`): the page has it from document start, so its first paint
+ * can be in it.
+ *
+ * ```ts
+ * document.documentElement.lang = locale();
+ * document.documentElement.dir = direction();
+ * ```
+ */
+export function locale(): string {
+  return runtime().locale;
+}
+
+/** The direction the language the app shows is written in: "ltr" or "rtl". */
+export function direction(): Direction {
+  return runtime().dir;
+}
+
+/**
+ * Subscribes to changes of the language the app shows, as `App::setLocale()`
+ * makes them, or the user's languages while the app follows them. The
+ * listener hears only of a language the page did not have: a page loaded
+ * after a change starts with the new one. Returns a function that
+ * unsubscribes.
+ *
+ * ```ts
+ * onLocaleChange((tag, dir) => {
+ *   document.documentElement.lang = tag;
+ *   document.documentElement.dir = dir;
+ * });
+ * ```
+ */
+export function onLocaleChange(listener: (locale: string, dir: Direction) => void): () => void {
+  return on<LocaleChange>("myphp:locale", (p) => listener(p.locale, p.dir));
+}
+
+/** A typed event sent by the PHP side, declared with `new Event(...)`. */
+export interface PhpEvent<T> {
+  readonly name: string;
+  /** Subscribes to the event and returns a function that unsubscribes. */
+  on(listener: (payload: T) => void): () => void;
+  /** Like on, but unsubscribes after the first event. */
+  once(listener: (payload: T) => void): () => void;
+}
+
+/** Returns the typed event `name`; the generated client declares them. */
+export function event<T>(name: string): PhpEvent<T> {
+  return {
+    name,
+    on: (listener) => on<T>(name, listener),
+    once: (listener) => once<T>(name, listener),
+  };
+}
+
+/** The error of a call whose PHP method threw. */
+export interface CallError extends Error {
+  readonly name: "CallError";
+  /** The method that failed, e.g. "Greeter.greet". */
+  readonly method: string;
+}
+
+/** Reports whether err comes from a PHP method that threw. */
+export function isCallError(err: unknown): err is CallError {
+  return err instanceof Error && err.name === "CallError";
+}
+
+/** Files dropped on the window, e.g. from Finder or Explorer. */
+export interface FileDrop {
+  /** Absolute paths of the dropped files and directories. */
+  paths: string[];
+  /** Where they were dropped, in CSS pixels, like `clientX`. */
+  x: number;
+  /** Where they were dropped, in CSS pixels, like `clientY`. */
+  y: number;
+}
+
+/**
+ * Subscribes to files dropped on the window, with their paths, which DOM
+ * drop events do not tell. Only the app's own pages get them. Returns a
+ * function that unsubscribes.
+ *
+ * ```ts
+ * onFileDrop(({ paths, x, y }) => {
+ *   const target = document.elementFromPoint(x, y);
+ * });
+ * ```
+ */
+export function onFileDrop(listener: (drop: FileDrop) => void): () => void {
+  return on<FileDrop>("myphp:file-drop", listener);
+}
+
+/** The document a window shows (`new Documents(...)`), as PHP describes it. */
+export interface DocumentState {
+  /** The file name, or a name such as "Untitled 2" while untitled. */
+  name: string;
+  /** The file, "" while the document is untitled. */
+  path: string;
+  /** Whether the document has unsaved changes. */
+  edited: boolean;
+  /** Whether its file can't be written: saving asks for another. */
+  readOnly: boolean;
+  /** Whether another app changed its file while it had unsaved changes. */
+  conflict: boolean;
+  /** Whether its file was deleted: saving writes it again. */
+  deleted: boolean;
+}
+
+/**
+ * Subscribes to the state of the window's document: edited, saved,
+ * renamed, moved, changed by another app. Only the app's own pages get it.
+ * Returns a function that unsubscribes.
+ *
+ * ```ts
+ * onDocumentState(({ name, edited }) => {
+ *   heading.textContent = edited ? `${name} (edited)` : name;
+ * });
+ * ```
+ */
+export function onDocumentState(listener: (state: DocumentState) => void): () => void {
+  return on<DocumentState>("myphp:document-state", listener);
+}
+
+/**
+ * Subscribes to the window's document being read from its file again:
+ * reverted, or changed by another app while it had no unsaved changes.
+ * Fetch its content again, with the service bound to
+ * `$documents->service()`. Returns a function that unsubscribes.
+ */
+export function onDocumentReload(listener: () => void): () => void {
+  return on<unknown>("myphp:document-reload", () => listener());
+}
+
+/**
+ * Returns the accent color and the accessibility settings of the desktop
+ * (`Theme::preferences()` in PHP), current from document start on.
+ * Throws outside MyPHP, as {@link runtime} does.
+ *
+ * ```ts
+ * const { accent, reduceTransparency } = preferences();
+ * ```
+ *
+ * CSS gets the accent and the text scale from the `--myphp-accent` and
+ * `--myphp-text-scale` variables of `:root`.
+ */
+export function preferences(): ThemePreferences {
+  return runtime().preferences;
+}
+
+/**
+ * Subscribes to changes of the desktop's preferences, which
+ * {@link preferences} returns; the listener gets the new ones. Returns a
+ * function that unsubscribes.
+ *
+ * ```ts
+ * const apply = (p: ThemePreferences) => root.classList.toggle("opaque", p.reduceTransparency);
+ * apply(preferences());
+ * onPreferences(apply);
+ * ```
+ */
+export function onPreferences(listener: (preferences: ThemePreferences) => void): () => void {
+  return on<ThemePreferences>("myphp:preferences", listener);
+}
+
+/** The window hosting the page, e.g. for a custom title bar. */
+export const currentWindow: WindowControls = {
+  minimize: async () => runtime().window.minimize(),
+  maximize: async () => runtime().window.maximize(),
+  unmaximize: async () => runtime().window.unmaximize(),
+  toggleMaximize: async () => runtime().window.toggleMaximize(),
+  isMaximized: async () => runtime().window.isMaximized(),
+  toggleFullScreen: async () => runtime().window.toggleFullScreen(),
+  close: async () => runtime().window.close(),
+  setTitle: async (title) => runtime().window.setTitle(title),
+};

package/src/types.ts

@@ -0,0 +1,105 @@
+/** The operating system, using Node.js' `process.platform` names. */
+export type Platform = "darwin" | "linux" | "win32";
+
+/** The direction a language is written in: left to right, or right to left. */
+export type Direction = "ltr" | "rtl";
+
+/** The payload of the `myphp:locale` event. */
+export interface LocaleChange {
+  /** The language the app shows now, e.g. "zh-Hans". */
+  locale: string;
+  /** The direction it is written in. */
+  dir: Direction;
+}
+
+/** Controls for the window hosting the page, handy for custom title bars. */
+export interface WindowControls {
+  minimize(): Promise<void>;
+  maximize(): Promise<void>;
+  unmaximize(): Promise<void>;
+  toggleMaximize(): Promise<void>;
+  isMaximized(): Promise<boolean>;
+  toggleFullScreen(): Promise<void>;
+  close(): Promise<void>;
+  setTitle(title: string): Promise<void>;
+}
+
+/**
+ * A stream of values from a PHP method that takes a `MyPHP\Channel`,
+ * passed to the call in its place. Iterate it, or handle the values with
+ * `onmessage`: values that arrive before either wait for it. The channel
+ * closes when the method returns, or calls `Close`, once its values are
+ * taken; `close()` stops the method.
+ */
+export interface Channel<T = unknown> extends AsyncIterable<T> {
+  /** Called with each value, instead of iterating. */
+  onmessage: ((value: T) => void) | null;
+  /** Called when the channel closes. */
+  onclose: (() => void) | null;
+  /** Whether the channel is closed. */
+  readonly closed: boolean;
+  /**
+   * Closes the channel, dropping values not taken yet: the PHP method's
+   * `send()` fails and it stops. Breaking out of a
+   * `for await` loop over the channel closes it too.
+   */
+  close(): void;
+}
+
+/**
+ * The accent color and the accessibility settings of the desktop, as
+ * `MyPHP\ThemePreferences` encodes them.
+ */
+export interface ThemePreferences {
+  /** The accent color of the desktop's controls as "#rrggbb", or null where the desktop has none. */
+  accent: string | null;
+  /** Whether the desktop asks for less motion; `prefers-reduced-motion` tells it too. */
+  reduceMotion: boolean;
+  /**
+   * Whether the desktop asks for opaque surfaces in place of translucent
+   * ones: macOS's Reduce Transparency, Windows's transparency effects
+   * turned off. Linux desktops have no such setting.
+   */
+  reduceTransparency: boolean;
+  /** Whether the desktop asks for more contrast; `prefers-contrast` tells it too. */
+  highContrast: boolean;
+  /** How many times larger than usual text should be; 1 is usual. */
+  textScale: number;
+}
+
+/** The runtime MyPHP injects into every page as `window.myphp`. */
+export interface Runtime {
+  /** Calls a bound PHP method, e.g. `call("Greeter.greet", "Ada")`. */
+  call<T = unknown>(method: string, ...args: unknown[]): Promise<T>;
+  /**
+   * Creates a channel to pass to a call of a PHP method that streams values
+   * through a `MyPHP\Channel` parameter. A channel serves one call.
+   */
+  channel<T = unknown>(onmessage?: (value: T) => void): Channel<T>;
+  /** Subscribes to a PHP event. Returns a function that unsubscribes. */
+  on<T = unknown>(event: string, listener: (payload: T) => void): () => void;
+  /** Like `on`, but unsubscribes after the first event. */
+  once<T = unknown>(event: string, listener: (payload: T) => void): () => void;
+  /** The operating system. */
+  readonly platform: Platform;
+  /** The id of the `MyPHP\Window` hosting this page. */
+  readonly windowId: number;
+  /** MyPHP version. */
+  readonly version: string;
+  /**
+   * The desktop's preferences, current from document start on; the
+   * `myphp:preferences` event tells their changes.
+   */
+  readonly preferences: ThemePreferences;
+  /**
+   * The language the app shows, a BCP 47 tag such as "en" or "zh-Hans"
+   * (`App::locale()`): of the languages the app is written in, the one the
+   * user reads best, or the one `App::setLocale()` chose. A page has it from
+   * document start, and the `myphp:locale` event tells of changes.
+   */
+  readonly locale: string;
+  /** The direction `locale` is written in, for `<html dir>`. */
+  readonly dir: Direction;
+  /** The window hosting this page. */
+  readonly window: WindowControls;
+}