@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/host/web.js

@@ -0,0 +1,216 @@
+/**
+ * The web host: the game in a browser tab, or in a frame such as itch.io's. It wraps the D-036
+ * link service (host/web-links.ts), the fullscreen helpers (platform/device.ts) and
+ * `localStorage` behind a guarded probe (save/storage.ts). Web storage is `localStorage` only.
+ *
+ * The mobile facets (ws/host-mobile) come from the page too: `lifecycle` from
+ * `visibilitychange` and `pagehide`/`pageshow`, `haptics` from `navigator.vibrate` when the
+ * browser has it, `safeArea` from `env(safe-area-inset-*)` read through a probe element and
+ * re-read on resize. The factories are exported so another host (a store app's) can reuse them
+ * for what its shell does not answer itself.
+ */
+import { fullscreenAvailable, isFullscreen, toggleFullscreen, watchFullscreen, } from '../platform/device.js';
+import { embedContext } from '../platform/links.js';
+import { probeStorage } from '../save/storage.js';
+import { clipboardWriteAllowed, copyText, openExternal } from './web-links.js';
+export function createWebHost(opts = {}) {
+    const win = opts.win ?? window;
+    let embed = null;
+    return {
+        kind: 'web',
+        requestFrame: (cb) => win.requestAnimationFrame(cb),
+        cancelFrame: (handle) => win.cancelAnimationFrame(handle),
+        get embed() {
+            embed ??= embedContext(win);
+            return embed;
+        },
+        openExternal: (url, o) => openExternal(url, o, win),
+        copyText: (text) => copyText(text, win),
+        clipboardWriteAllowed: () => clipboardWriteAllowed(win.document),
+        fullscreen: {
+            available: () => fullscreenAvailable(win.document),
+            get active() {
+                return isFullscreen(win.document);
+            },
+            toggle: (o) => toggleFullscreen(win.document.documentElement, o),
+            watch: (fn) => watchFullscreen(fn, win.document),
+        },
+        storage: {
+            kind: 'local',
+            // Merely reading `localStorage` throws in some sandboxed or third-party frames, so it is
+            // read inside the probe's guard.
+            open: () => probeStorage(() => win.localStorage),
+        },
+        lifecycle: createWebLifecycle(win),
+        haptics: createWebHaptics(win),
+        safeArea: createWebSafeArea(win),
+    };
+}
+/**
+ * The page's lifecycle as a `HostLifecycle`: `background` once the document is hidden or paged
+ * out (`pagehide`, `freeze`), `active` when it is visible again (`visibilitychange`, `pageshow`,
+ * `resume`). Each watcher sees a change only when the state differs from what it last saw.
+ */
+export function createWebLifecycle(win) {
+    const doc = win.document;
+    let pagedOut = false;
+    const state = () => pagedOut || doc.visibilityState === 'hidden' ? 'background' : 'active';
+    return {
+        get state() {
+            return state();
+        },
+        watch(fn) {
+            let last = state();
+            const emit = () => {
+                const s = state();
+                if (s === last)
+                    return;
+                last = s;
+                fn(s);
+            };
+            const onVis = () => {
+                if (doc.visibilityState !== 'hidden')
+                    pagedOut = false;
+                emit();
+            };
+            const onPageHide = () => {
+                pagedOut = true;
+                emit();
+            };
+            const onPageShow = () => {
+                pagedOut = false;
+                emit();
+            };
+            doc.addEventListener('visibilitychange', onVis);
+            doc.addEventListener('freeze', onPageHide);
+            doc.addEventListener('resume', onPageShow);
+            win.addEventListener('pagehide', onPageHide);
+            win.addEventListener('pageshow', onPageShow);
+            return () => {
+                doc.removeEventListener('visibilitychange', onVis);
+                doc.removeEventListener('freeze', onPageHide);
+                doc.removeEventListener('resume', onPageShow);
+                win.removeEventListener('pagehide', onPageHide);
+                win.removeEventListener('pageshow', onPageShow);
+            };
+        },
+    };
+}
+/** `navigator.vibrate` durations, ms. */
+const IMPACT_MS = { light: 10, medium: 20, heavy: 35 };
+const NOTIFICATION_PATTERN = {
+    success: [10, 40, 10],
+    warning: [25, 50, 25],
+    error: [40, 50, 40, 50, 40],
+};
+/**
+ * Haptics over `navigator.vibrate`, when the browser has it (Android Chrome does; iOS Safari
+ * does not, so `available()` is false there and every call is a no-op). A vibrate call outside a
+ * user gesture may be refused; that is ignored.
+ */
+export function createWebHaptics(win) {
+    const nav = win.navigator;
+    const vibrate = (pattern) => {
+        try {
+            nav?.vibrate?.(pattern);
+        }
+        catch {
+            // Not allowed here (no gesture yet, or a frame policy): silence is the fallback.
+        }
+    };
+    const available = () => typeof nav?.vibrate === 'function';
+    return {
+        available,
+        impact: (style) => {
+            if (available())
+                vibrate(IMPACT_MS[style] ?? IMPACT_MS.medium);
+        },
+        notification: (kind) => {
+            if (available())
+                vibrate(NOTIFICATION_PATTERN[kind] ?? NOTIFICATION_PATTERN.warning);
+        },
+        vibrate: (ms) => {
+            if (available() && ms > 0)
+                vibrate(Math.round(ms));
+        },
+    };
+}
+/**
+ * CSS px safe-area insets of `win`'s viewport, read through a probe element padded with
+ * `env(safe-area-inset-*)` (the `--tc-safe-*` custom properties override them, for emulation).
+ * Zero when the document has no body yet or the window cannot compute styles.
+ */
+export function readSafeAreaInsets(win, out) {
+    const doc = win.document;
+    out.top = out.right = out.bottom = out.left = 0;
+    if (!doc?.body || typeof win.getComputedStyle !== 'function')
+        return out;
+    const probe = doc.createElement('div');
+    probe.style.cssText =
+        'position:fixed;left:0;top:0;width:0;height:0;visibility:hidden;pointer-events:none;' +
+            'padding:var(--tc-safe-top,env(safe-area-inset-top,0px)) var(--tc-safe-right,env(safe-area-inset-right,0px)) ' +
+            'var(--tc-safe-bottom,env(safe-area-inset-bottom,0px)) var(--tc-safe-left,env(safe-area-inset-left,0px));';
+    doc.body.append(probe);
+    const cs = win.getComputedStyle(probe);
+    const px = (v) => Number.parseFloat(v ?? '') || 0;
+    out.top = px(cs.paddingTop);
+    out.right = px(cs.paddingRight);
+    out.bottom = px(cs.paddingBottom);
+    out.left = px(cs.paddingLeft);
+    probe.remove();
+    return out;
+}
+/**
+ * The viewport's safe area as a `HostSafeArea`. `insets()` reads the page once and then serves
+ * the cached values until a `resize` (or `orientationchange`) invalidates them; watchers are
+ * called after a resize only when a value changed.
+ */
+export function createWebSafeArea(win) {
+    const current = { top: 0, right: 0, bottom: 0, left: 0 };
+    let fresh = false;
+    const watchers = new Set();
+    const insets = () => {
+        if (!fresh) {
+            readSafeAreaInsets(win, current);
+            fresh = true;
+        }
+        return current;
+    };
+    const same = (a, b) => a.top === b.top && a.right === b.right && a.bottom === b.bottom && a.left === b.left;
+    const previous = { top: 0, right: 0, bottom: 0, left: 0 };
+    const onResize = () => {
+        if (watchers.size === 0) {
+            fresh = false;
+            return;
+        }
+        Object.assign(previous, current);
+        fresh = false;
+        insets();
+        if (same(previous, current))
+            return;
+        for (const fn of [...watchers])
+            fn(current);
+    };
+    let listening = false;
+    const listen = () => {
+        if (listening)
+            return;
+        listening = true;
+        win.addEventListener?.('resize', onResize);
+        win.addEventListener?.('orientationchange', onResize);
+    };
+    return {
+        insets: () => {
+            listen();
+            return insets();
+        },
+        watch(fn) {
+            listen();
+            insets();
+            watchers.add(fn);
+            return () => {
+                watchers.delete(fn);
+            };
+        },
+    };
+}

package/dist/host/xr.d.ts

@@ -0,0 +1,24 @@
+/// <reference path="../platform/xr-types.d.ts" preserve="true" />
+/**
+ * The XR host (ws/xr): a `Host` whose frames come from `XRSession.requestAnimationFrame`, so
+ * `GameLoop.setFrames(createXrHost(session, host))` moves a running game into the headset and
+ * every other host service (links, clipboard, fullscreen, storage, window, lifecycle, haptics,
+ * safe area) keeps coming from the host it wraps. The session hands each frame callback an `XRFrame`; the host keeps it in `frame`
+ * for the length of that tick (poses, input sources and the layer's textures are only valid
+ * then), so `XrSurface.views(host.frame)` and `XrPointerSource` read it from here.
+ */
+import type { Host } from './types.js';
+export interface XrHost extends Host {
+    readonly kind: 'xr';
+    readonly session: XRSession;
+    /** The host this one delegates everything but frames to. */
+    readonly base: Host;
+    /** The `XRFrame` of the frame callback that is running now; null between frames. */
+    readonly frame: XRFrame | null;
+}
+/**
+ * Wraps `session.requestAnimationFrame` / `cancelAnimationFrame` as a `FrameSource` and
+ * delegates every other `Host` member to `base`. Allocates nothing per frame once the loop's
+ * callback is stable (`GameLoop` passes the same function every time).
+ */
+export declare function createXrHost(session: XRSession, base: Host): XrHost;

package/dist/host/xr.js

@@ -0,0 +1,59 @@
+/**
+ * Wraps `session.requestAnimationFrame` / `cancelAnimationFrame` as a `FrameSource` and
+ * delegates every other `Host` member to `base`. Allocates nothing per frame once the loop's
+ * callback is stable (`GameLoop` passes the same function every time).
+ */
+export function createXrHost(session, base) {
+    let current = null;
+    let lastCb = null;
+    let lastWrapped = null;
+    const wrap = (cb) => {
+        if (cb === lastCb && lastWrapped)
+            return lastWrapped;
+        lastCb = cb;
+        lastWrapped = (time, xrFrame) => {
+            current = xrFrame;
+            try {
+                cb(time);
+            }
+            finally {
+                current = null;
+            }
+        };
+        return lastWrapped;
+    };
+    return {
+        kind: 'xr',
+        session,
+        base,
+        get frame() {
+            return current;
+        },
+        requestFrame: (cb) => session.requestAnimationFrame(wrap(cb)),
+        cancelFrame: (handle) => session.cancelAnimationFrame(handle),
+        get embed() {
+            return base.embed;
+        },
+        openExternal: (url, opts) => base.openExternal(url, opts),
+        copyText: (text) => base.copyText(text),
+        clipboardWriteAllowed: () => base.clipboardWriteAllowed(),
+        get fullscreen() {
+            return base.fullscreen;
+        },
+        get storage() {
+            return base.storage;
+        },
+        get window() {
+            return base.window;
+        },
+        get lifecycle() {
+            return base.lifecycle;
+        },
+        get haptics() {
+            return base.haptics;
+        },
+        get safeArea() {
+            return base.safeArea;
+        },
+    };
+}

package/dist/i18n/i18n.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The string store: one table per locale (inline or loaded on demand), parsed once into an AST
+ * per key, looked up along a fallback chain, swapped at runtime with a subscription so the UI
+ * re-renders. Numbers, dates, durations and lists go through `Intl` for the current locale.
+ */
+import { type MessageArgs, type MessageAst } from './message.js';
+import { type TextDirection } from './negotiate.js';
+/** Nested string table: `{ menu: { start: 'Start' } }` is the key `menu.start`. */
+export type Table = {
+    readonly [key: string]: string | Table;
+};
+/** A table, or a loader for one (`() => import('./ru.json')` works: a lone `default` is unwrapped). */
+export type TableSource = Table | (() => Promise<Table | {
+    default: Table;
+}>);
+/** What `t` returns for a key no table in the chain has. Default `'key'`: the key itself. */
+export type MissingPolicy = 'key' | 'throw' | ((key: string, locale: string) => string);
+export interface I18nDesc {
+    /** The starting locale: a key of `tables`, or a tag whose language one of them shares. */
+    locale: string;
+    /** Looked up after the locale and its language, in order. */
+    fallback?: string | readonly string[];
+    tables: Record<string, TableSource>;
+    missing?: MissingPolicy;
+    /** Called once per missing key and locale, whatever `missing` does. */
+    onMissing?: (key: string, locale: string) => void;
+}
+export interface DurationOptions {
+    /** `digital` (default): `m:ss` or `h:mm:ss` in the locale's digits. Others: words per unit. */
+    style?: 'digital' | 'long' | 'short' | 'narrow';
+    /** Show the hours field even when it is zero (digital style). */
+    hours?: 'auto' | 'always';
+}
+export interface I18n {
+    /** The active locale, as named in `tables`. */
+    readonly locale: string;
+    /** Every locale that has a table, in table order. */
+    readonly locales: readonly string[];
+    readonly direction: TextDirection;
+    /** Resolves when the starting locale and its fallback chain are loaded. */
+    readonly ready: Promise<void>;
+    /** The message for `key` formatted with `args`, from the first table in the chain that has it. */
+    t(key: string, args?: MessageArgs): string;
+    /** Whether any table in the chain has `key`. */
+    has(key: string): boolean;
+    /** Loads `locale` and its chain if needed, then swaps and notifies. Rejects for an unknown locale. */
+    setLocale(locale: string): Promise<void>;
+    /** Called after every locale swap. Returns unsubscribe. */
+    subscribe(fn: (i18n: I18n) => void): () => void;
+    formatNumber(value: number, opts?: Intl.NumberFormatOptions): string;
+    formatDate(value: Date | number, opts?: Intl.DateTimeFormatOptions): string;
+    formatDuration(ms: number, opts?: DurationOptions): string;
+    formatList(items: readonly string[], opts?: Intl.ListFormatOptions): string;
+}
+type Compiled = ReadonlyMap<string, MessageAst | string>;
+/** Flattens a table to dotted keys and parses every string. Throws `MessageSyntaxError`. */
+export declare function compileTable(table: Table, locale: string): Compiled;
+export declare function createI18n(desc: I18nDesc): I18n;
+export {};

package/dist/i18n/i18n.js

@@ -0,0 +1,241 @@
+/**
+ * The string store: one table per locale (inline or loaded on demand), parsed once into an AST
+ * per key, looked up along a fallback chain, swapped at runtime with a subscription so the UI
+ * re-renders. Numbers, dates, durations and lists go through `Intl` for the current locale.
+ */
+import { createIntlCache, formatMessage, parseMessage, } from './message.js';
+import { directionOf, languageOf } from './negotiate.js';
+/** Flattens a table to dotted keys and parses every string. Throws `MessageSyntaxError`. */
+export function compileTable(table, locale) {
+    const out = new Map();
+    const visit = (node, prefix) => {
+        for (const k of Object.keys(node)) {
+            const v = node[k];
+            const key = prefix ? `${prefix}.${k}` : k;
+            if (typeof v === 'string') {
+                const ast = parseMessage(v, key);
+                out.set(key, ast.length === 1 && typeof ast[0] === 'string' ? ast[0] : ast);
+            }
+            else if (v && typeof v === 'object') {
+                visit(v, key);
+            }
+            else {
+                throw new TypeError(`i18n: table "${locale}" key "${key}" is not a string or object`);
+            }
+        }
+    };
+    visit(table, '');
+    return out;
+}
+function unwrap(loaded) {
+    const keys = Object.keys(loaded);
+    if (keys.length === 1 && keys[0] === 'default' && typeof loaded.default === 'object') {
+        return loaded.default;
+    }
+    return loaded;
+}
+export function createI18n(desc) {
+    const sources = desc.tables;
+    const locales = Object.keys(sources);
+    if (locales.length === 0)
+        throw new Error('i18n: tables is empty');
+    const fallbacks = desc.fallback === undefined
+        ? []
+        : typeof desc.fallback === 'string'
+            ? [desc.fallback]
+            : desc.fallback;
+    const missing = desc.missing ?? 'key';
+    const intl = createIntlCache();
+    const compiled = new Map();
+    const pending = new Map();
+    const subscribers = new Set();
+    const reported = new Set();
+    const formats = new Map();
+    let locale = desc.locale;
+    let ready = Promise.resolve();
+    let direction = directionOf(locale);
+    let chain = [];
+    let generation = 0;
+    /** The table key for `tag`: exact, else one sharing its language. Null when none. */
+    const resolve = (tag) => {
+        if (tag in sources)
+            return tag;
+        const lower = tag.toLowerCase();
+        const exact = locales.find((l) => l.toLowerCase() === lower);
+        if (exact)
+            return exact;
+        const lang = languageOf(tag);
+        return locales.find((l) => languageOf(l) === lang) ?? null;
+    };
+    /** Table keys to consult for `key`, most specific first, each once. */
+    const chainFor = (resolved) => {
+        const out = [];
+        const push = (tag) => {
+            const r = resolve(tag);
+            if (r && !out.includes(r))
+                out.push(r);
+        };
+        push(resolved);
+        push(languageOf(resolved));
+        for (const f of fallbacks) {
+            push(f);
+            push(languageOf(f));
+        }
+        return out;
+    };
+    const load = (key) => {
+        if (compiled.has(key))
+            return null;
+        const source = sources[key];
+        if (typeof source !== 'function') {
+            compiled.set(key, compileTable(source, key));
+            return null;
+        }
+        let p = pending.get(key);
+        if (!p) {
+            p = source().then((loaded) => {
+                compiled.set(key, compileTable(unwrap(loaded), key));
+                pending.delete(key);
+            }, (err) => {
+                pending.delete(key);
+                throw err;
+            });
+            pending.set(key, p);
+        }
+        return p;
+    };
+    const apply = (resolved, keys) => {
+        locale = resolved;
+        direction = directionOf(resolved);
+        chain = keys.map((k) => ({ locale: k, table: compiled.get(k) }));
+        for (const fn of subscribers)
+            fn(api);
+    };
+    const find = (key) => {
+        for (let i = 0; i < chain.length; i++)
+            if (chain[i].table.has(key))
+                return chain[i];
+        return null;
+    };
+    const cached = (kind, opts, make) => {
+        const k = `${kind}|${locale}|${opts ? JSON.stringify(opts) : ''}`;
+        let f = formats.get(k);
+        if (!f) {
+            f = make();
+            formats.set(k, f);
+        }
+        return f;
+    };
+    const setLocale = (tag) => {
+        const resolved = resolve(tag);
+        if (!resolved)
+            return Promise.reject(new Error(`i18n: no table for locale "${tag}"`));
+        const keys = chainFor(resolved);
+        const gen = ++generation;
+        const loads = [];
+        for (const k of keys) {
+            const p = load(k);
+            if (p)
+                loads.push(p);
+        }
+        if (loads.length === 0) {
+            apply(resolved, keys);
+            return Promise.resolve();
+        }
+        return Promise.all(loads).then(() => {
+            // A later setLocale won; leave its result in place.
+            if (gen !== generation)
+                return;
+            apply(resolved, keys);
+        });
+    };
+    const api = {
+        get locale() {
+            return locale;
+        },
+        locales,
+        get direction() {
+            return direction;
+        },
+        get ready() {
+            return ready;
+        },
+        t(key, args) {
+            const layer = find(key);
+            if (!layer) {
+                const tag = `${locale}\u0000${key}`;
+                if (desc.onMissing && !reported.has(tag)) {
+                    reported.add(tag);
+                    desc.onMissing(key, locale);
+                }
+                if (missing === 'key')
+                    return key;
+                if (missing === 'throw')
+                    throw new Error(`i18n: missing "${key}" in "${locale}"`);
+                return missing(key, locale);
+            }
+            const entry = layer.table.get(key);
+            return typeof entry === 'string' ? entry : formatMessage(entry, args, layer.locale, intl);
+        },
+        has(key) {
+            return find(key) !== null;
+        },
+        setLocale,
+        subscribe(fn) {
+            subscribers.add(fn);
+            return () => {
+                subscribers.delete(fn);
+            };
+        },
+        formatNumber(value, opts) {
+            return cached('n', opts, () => new Intl.NumberFormat(locale, opts)).format(value);
+        },
+        formatDate(value, opts) {
+            return cached('d', opts, () => new Intl.DateTimeFormat(locale, opts)).format(value);
+        },
+        formatDuration(ms, opts) {
+            const total = Math.max(0, Math.floor(ms / 1000));
+            const hours = Math.floor(total / 3600);
+            const minutes = Math.floor((total % 3600) / 60);
+            const seconds = total % 60;
+            const style = opts?.style ?? 'digital';
+            if (style === 'digital') {
+                const two = cached('n', { minimumIntegerDigits: 2, useGrouping: false }, () => new Intl.NumberFormat(locale, { minimumIntegerDigits: 2, useGrouping: false }));
+                const one = cached('n', { useGrouping: false }, () => new Intl.NumberFormat(locale, { useGrouping: false }));
+                if (hours > 0 || opts?.hours === 'always') {
+                    return `${one.format(hours)}:${two.format(minutes)}:${two.format(seconds)}`;
+                }
+                return `${one.format(minutes)}:${two.format(seconds)}`;
+            }
+            const DF = Intl.DurationFormat;
+            const parts = {};
+            if (hours > 0)
+                parts.hours = hours;
+            if (minutes > 0)
+                parts.minutes = minutes;
+            if (seconds > 0 || total === 0)
+                parts.seconds = seconds;
+            // `Intl.DurationFormat` prints nothing for an all-zero duration; the unit path says "0 seconds".
+            if (DF && total > 0) {
+                return cached('dur', { style }, () => new DF(locale, { style })).format(parts);
+            }
+            // Older engines: one unit per field, joined as a list.
+            const items = [];
+            const unitDisplay = style === 'long' ? 'long' : style;
+            for (const unit of ['hour', 'minute', 'second']) {
+                const v = parts[`${unit}s`];
+                if (v === undefined)
+                    continue;
+                items.push(cached('n', { style: 'unit', unit, unitDisplay }, () => new Intl.NumberFormat(locale, { style: 'unit', unit, unitDisplay })).format(v));
+            }
+            return api.formatList(items, { style: style === 'long' ? 'long' : 'narrow', type: 'unit' });
+        },
+        formatList(items, opts) {
+            if (typeof Intl.ListFormat !== 'function')
+                return items.join(', ');
+            return cached('l', opts, () => new Intl.ListFormat(locale, opts)).format(items);
+        },
+    };
+    ready = setLocale(desc.locale);
+    return api;
+}

package/dist/i18n/index.d.ts

@@ -0,0 +1,3 @@
+export { compileTable, createI18n, type DurationOptions, type I18n, type I18nDesc, type MissingPolicy, type Table, type TableSource, } from './i18n.js';
+export { type ArgNode, createIntlCache, type FormatNode, formatMessage, type HashNode, type IntlCache, type MessageArgs, type MessageArgValue, type MessageAst, type MessageNode, MessageSyntaxError, type PluralNode, parseMessage, type SelectNode, } from './message.js';
+export { directionOf, languageOf, negotiateLocale, RTL_LANGUAGES, requestedLocales, type TextDirection, } from './negotiate.js';

package/dist/i18n/index.js

@@ -0,0 +1,3 @@
+export { compileTable, createI18n, } from './i18n.js';
+export { createIntlCache, formatMessage, MessageSyntaxError, parseMessage, } from './message.js';
+export { directionOf, languageOf, negotiateLocale, RTL_LANGUAGES, requestedLocales, } from './negotiate.js';

package/dist/i18n/message.d.ts

@@ -0,0 +1,72 @@
+/**
+ * ICU-style message syntax: a parser that runs once per string when a table loads, and a
+ * formatter that walks the resulting AST and builds only the output string.
+ *
+ * Supported forms:
+ * - `{name}`: an argument. Numbers go through `Intl.NumberFormat`, dates through
+ *   `Intl.DateTimeFormat`, everything else through `String`.
+ * - `{n, number}`, `{n, number, integer | percent}`; `{d, date}`, `{d, date, short | medium |
+ *   long | full}`; `{d, time}`, `{d, time, short | medium | long | full}`.
+ * - `{count, plural, offset:1 =0 {none} one {# item} other {# items}}`: `Intl.PluralRules`
+ *   cardinal categories (`zero one two few many other`), exact `=N` forms checked first, `#` the
+ *   number minus the offset, formatted for the locale. `selectordinal` uses ordinal rules.
+ * - `{g, select, male {he} female {she} other {they}}`.
+ * - `'{'` quotes a special character (`{ } #`), `''` is one apostrophe; any other apostrophe is
+ *   literal.
+ *
+ * Every error names the key and the 1-based column where parsing stopped.
+ */
+export type MessageArgValue = string | number | boolean | Date | null | undefined;
+export type MessageArgs = Readonly<Record<string, MessageArgValue>>;
+export interface ArgNode {
+    kind: 'arg';
+    name: string;
+}
+export interface FormatNode {
+    kind: 'number' | 'date' | 'time';
+    name: string;
+    style: string | null;
+}
+export interface HashNode {
+    kind: 'hash';
+}
+export interface PluralNode {
+    kind: 'plural';
+    name: string;
+    ordinal: boolean;
+    offset: number;
+    /** `=N` forms, keyed by the exact value. */
+    exact: ReadonlyMap<number, MessageAst>;
+    /** `zero one two few many`, when present. */
+    categories: ReadonlyMap<string, MessageAst>;
+    other: MessageAst;
+}
+export interface SelectNode {
+    kind: 'select';
+    name: string;
+    cases: ReadonlyMap<string, MessageAst>;
+    other: MessageAst;
+}
+/** Literal text is a plain string. */
+export type MessageNode = string | ArgNode | FormatNode | HashNode | PluralNode | SelectNode;
+export type MessageAst = readonly MessageNode[];
+export declare class MessageSyntaxError extends Error {
+    readonly key: string;
+    /** 1-based column in the message where parsing stopped. */
+    readonly column: number;
+    constructor(key: string, column: number, detail: string);
+}
+/** Parses one message. Throws `MessageSyntaxError` naming `key` and the column. */
+export declare function parseMessage(source: string, key?: string): MessageAst;
+/** Per-locale `Intl` objects, built once and reused by every format call. */
+export interface IntlCache {
+    plural(locale: string, ordinal: boolean): Intl.PluralRules;
+    number(locale: string, style: string | null): Intl.NumberFormat;
+    date(locale: string, kind: 'date' | 'time', style: string | null): Intl.DateTimeFormat;
+}
+export declare function createIntlCache(): IntlCache;
+/**
+ * Formats a parsed message for `locale`. A missing argument renders as `{name}` so the UI never
+ * shows an empty string. Allocates only the output string.
+ */
+export declare function formatMessage(ast: MessageAst, args: MessageArgs | undefined, locale: string, intl: IntlCache): string;