@my-swu/simulator-client 0.1.6 → 0.1.7

package/dist/i18n/card-print-catalog.js

@@ -0,0 +1,260 @@
+import { resolveLocale } from './locale.js';
+const fieldNames = ['title', 'subtitle', 'text', 'deployBox', 'epicAction', 'rules'];
+/** Requires complete full-print data from a format-2 compiler shard. */
+export function requiredPrints(input) {
+    if (input.prints == null)
+        throw new Error('format 2 card catalog lacks prints');
+    return input.prints;
+}
+/** Copies and validates full physical-print fields without accepting stale source strings. */
+export function copyPrints(source, manifest, locale) {
+    const sourceIds = Object.keys(source).sort();
+    const aliasIds = Object.keys(manifest.canonicalAliases).sort();
+    if (sourceIds.length !== aliasIds.length || sourceIds.some((id, index) => id !== aliasIds[index])) {
+        throw new Error('card catalog print set does not match manifest aliases');
+    }
+    const prints = Object.create(null);
+    for (const [printId, entry] of Object.entries(source)) {
+        if (!isPositiveNumericId(printId) || !isRecord(entry) || !isRecord(entry.fields)) {
+            throw new Error(`invalid card catalog print ${printId}`);
+        }
+        const requestedPrintId = entry.requestedPrintId;
+        const canonicalCardId = entry.canonicalCardId;
+        if (!Number.isSafeInteger(requestedPrintId) || requestedPrintId !== Number(printId)
+            || !Number.isSafeInteger(canonicalCardId) || canonicalCardId <= 0
+            || manifest.canonicalAliases[printId] !== canonicalCardId) {
+            throw new Error(`invalid card catalog print identity ${printId}`);
+        }
+        const fields = Object.create(null);
+        if (Object.keys(entry.fields).length !== fieldNames.length) {
+            throw new Error(`incomplete card catalog print fields ${printId}`);
+        }
+        for (const field of fieldNames) {
+            const value = entry.fields[field];
+            if (value == null)
+                throw new Error(`incomplete card catalog print fields ${printId}`);
+            fields[field] = copyPrintField(value, field, printId, canonicalCardId, locale, manifest);
+        }
+        prints[printId] = Object.freeze({
+            canonicalCardId,
+            requestedPrintId,
+            fields: Object.freeze(fields),
+        });
+    }
+    return Object.freeze(prints);
+}
+/** Validates one requested/resolved full-field provenance pair. */
+function copyPrintField(value, fieldName, printId, canonicalCardId, locale, manifest) {
+    if (!isRecord(value) || !hasExactKeys(value, ['requested', 'resolved', 'status'])) {
+        throw new Error(`invalid card catalog print field ${printId}`);
+    }
+    const requested = copyRequestedField(value.requested, printId, locale);
+    const resolved = copyResolvedField(value.resolved, printId, canonicalCardId, manifest);
+    const status = copyPrintStatus(value.status, printId);
+    if (requested.kind === 'source' && requested.sourcePrintId !== Number(printId)) {
+        throw new Error(`invalid card catalog requested source print ${printId}`);
+    }
+    if (fieldName === 'title' && resolved.field.state !== 'value') {
+        throw new Error(`card catalog title lacks a usable resolved value ${printId}`);
+    }
+    if (status.kind === 'source') {
+        if (requested.kind !== 'source' || requested.sourceLocale !== locale
+            || resolved.sourceLocale !== locale || resolved.effectiveBaseline != null
+            || resolved.sourcePrintId !== Number(printId)
+            || requested.sourceRevision !== resolved.sourceRevision
+            || requested.presence !== sourceFieldPresence(resolved.field)) {
+            throw new Error(`invalid card catalog print source provenance ${printId}`);
+        }
+    }
+    else {
+        if (resolved.sourceLocale !== 'en') {
+            throw new Error(`invalid card catalog print fallback locale ${printId}`);
+        }
+        if (status.reason === 'missingLocale' && requested.kind !== 'missingLocale') {
+            throw new Error(`invalid card catalog missing locale fallback ${printId}`);
+        }
+        if (status.reason === 'missingRequiredTitle'
+            && (fieldName !== 'title' || requested.kind !== 'source'
+                || (requested.presence !== 'missing' && requested.presence !== 'null'))) {
+            throw new Error(`invalid card catalog missing title fallback ${printId}`);
+        }
+        if (status.reason === 'missingSourceField'
+            && (fieldName === 'title' || requested.kind !== 'source'
+                || (requested.presence !== 'missing' && requested.presence !== 'null')
+                || resolved.field.state !== 'value' || resolved.field.value.length === 0)) {
+            throw new Error(`invalid card catalog missing source field fallback ${printId}`);
+        }
+        if (status.reason === 'staleEffectiveText' && resolved.effectiveBaseline == null) {
+            throw new Error(`stale card catalog print fallback lacks effective baseline ${printId}`);
+        }
+        if (status.reason === 'staleEffectiveText' && requested.kind !== 'source') {
+            throw new Error(`invalid card catalog stale source fallback ${printId}`);
+        }
+    }
+    return Object.freeze({ requested, resolved, status });
+}
+/** Copies requested source presence without retaining stale source text twice. */
+function copyRequestedField(value, printId, locale) {
+    if (!isRecord(value) || typeof value.kind !== 'string') {
+        throw new Error(`invalid card catalog requested field ${printId}`);
+    }
+    if (value.kind === 'missingLocale' && hasExactKeys(value, ['kind', 'requestedPrintId'])
+        && value.requestedPrintId === Number(printId)) {
+        return Object.freeze({ kind: 'missingLocale', requestedPrintId: value.requestedPrintId });
+    }
+    if (value.kind === 'source' && hasExactKeys(value, [
+        'kind', 'sourcePrintId', 'sourceLocale', 'sourceRevision', 'presence',
+    ])) {
+        const sourceLocale = value.sourceLocale;
+        const sourceRevision = value.sourceRevision;
+        const presence = value.presence;
+        if (!isPositiveNumber(value.sourcePrintId) || typeof sourceLocale !== 'string'
+            || typeof sourceRevision !== 'string' || !isHash(sourceRevision)
+            || (presence !== 'missing' && presence !== 'null' && presence !== 'value')
+            || requiredLocale(sourceLocale, `card catalog requested field ${printId}`) !== locale) {
+            throw new Error(`invalid card catalog requested field ${printId}`);
+        }
+        return Object.freeze({
+            kind: 'source',
+            sourcePrintId: value.sourcePrintId,
+            sourceLocale,
+            sourceRevision,
+            presence,
+        });
+    }
+    throw new Error(`invalid card catalog requested field ${printId}`);
+}
+/** Copies resolved literal source and its optional effective-English identity. */
+function copyResolvedField(value, printId, canonicalCardId, manifest) {
+    if (!isRecord(value) || !hasOnlyKeys(value, [
+        'sourcePrintId', 'sourceLocale', 'sourceRevision', 'field', 'effectiveBaseline',
+    ])) {
+        throw new Error(`invalid card catalog resolved field ${printId}`);
+    }
+    const sourceLocaleValue = value.sourceLocale;
+    const sourceRevision = value.sourceRevision;
+    if (!isPositiveNumber(value.sourcePrintId) || typeof sourceLocaleValue !== 'string'
+        || typeof sourceRevision !== 'string' || !isHash(sourceRevision)) {
+        throw new Error(`invalid card catalog resolved field ${printId}`);
+    }
+    const sourceLocale = requiredLocale(sourceLocaleValue, `card catalog resolved field ${printId}`);
+    const field = copySourceField(value.field, printId);
+    const effectiveBaseline = value.effectiveBaseline === undefined
+        ? undefined
+        : copyEffectiveBaseline(value.effectiveBaseline, printId, canonicalCardId, manifest);
+    if (manifest.canonicalAliases[String(value.sourcePrintId)] !== canonicalCardId) {
+        throw new Error(`invalid card catalog resolved source print ${printId}`);
+    }
+    return Object.freeze({
+        sourcePrintId: value.sourcePrintId,
+        sourceLocale,
+        sourceRevision,
+        field,
+        ...(effectiveBaseline == null ? {} : { effectiveBaseline }),
+    });
+}
+/** Validates a field's three lossless source states. */
+function copySourceField(value, printId) {
+    if (!isRecord(value) || typeof value.state !== 'string') {
+        throw new Error(`invalid card catalog resolved source field ${printId}`);
+    }
+    if ((value.state === 'missing' || value.state === 'null') && hasExactKeys(value, ['state'])) {
+        return Object.freeze({ state: value.state });
+    }
+    if (value.state === 'value' && typeof value.value === 'string' && hasExactKeys(value, ['state', 'value'])) {
+        return Object.freeze({ state: 'value', value: value.value });
+    }
+    throw new Error(`invalid card catalog resolved source field ${printId}`);
+}
+/** Returns the requested-field state represented by a resolved lossless field. */
+function sourceFieldPresence(field) {
+    return field.state;
+}
+/** Validates stale effective-English content against canonical contract identity. */
+function copyEffectiveBaseline(value, printId, canonicalCardId, manifest) {
+    if (!isRecord(value) || !hasExactKeys(value, ['canonicalCardId', 'semanticFingerprint'])
+        || value.canonicalCardId !== canonicalCardId || typeof value.semanticFingerprint !== 'string'
+        || !isHash(value.semanticFingerprint)
+        || manifest.contractFingerprints[String(canonicalCardId)] !== value.semanticFingerprint) {
+        throw new Error(`invalid card catalog effective baseline ${printId}`);
+    }
+    return Object.freeze({ canonicalCardId, semanticFingerprint: value.semanticFingerprint });
+}
+/** Copies full-field status without allowing segmentation debt into direct print fields. */
+function copyPrintStatus(value, printId) {
+    if (!isRecord(value) || typeof value.kind !== 'string') {
+        throw new Error(`invalid card catalog print status ${printId}`);
+    }
+    if (value.kind === 'source' && hasExactKeys(value, ['kind']))
+        return Object.freeze({ kind: 'source' });
+    if (value.kind === 'fallback' && hasExactKeys(value, ['kind', 'reason'])
+        && (value.reason === 'missingLocale' || value.reason === 'missingRequiredTitle' || value.reason === 'missingSourceField'
+            || value.reason === 'staleEffectiveText')) {
+        return Object.freeze({ kind: 'fallback', reason: value.reason });
+    }
+    throw new Error(`invalid card catalog print status ${printId}`);
+}
+/** Creates a mutation-safe shallow snapshot of full-print JSON before hashing. */
+export function snapshotPrints(value) {
+    if (!isRecord(value))
+        throw new Error('invalid card catalog prints');
+    const prints = Object.create(null);
+    for (const [printId, entry] of Object.entries(value)) {
+        if (!isRecord(entry) || !isRecord(entry.fields))
+            throw new Error(`invalid card catalog print ${printId}`);
+        const fields = Object.create(null);
+        for (const [field, fieldValue] of Object.entries(entry.fields)) {
+            if (!isRecord(fieldValue) || !isRecord(fieldValue.requested) || !isRecord(fieldValue.resolved)
+                || !isRecord(fieldValue.status))
+                throw new Error(`invalid card catalog print field ${printId}`);
+            const resolved = { ...fieldValue.resolved };
+            if (isRecord(resolved.field))
+                resolved.field = { ...resolved.field };
+            if (isRecord(resolved.effectiveBaseline))
+                resolved.effectiveBaseline = { ...resolved.effectiveBaseline };
+            fields[field] = {
+                requested: { ...fieldValue.requested },
+                resolved: resolved,
+                status: { ...fieldValue.status },
+            };
+        }
+        prints[printId] = {
+            canonicalCardId: entry.canonicalCardId,
+            requestedPrintId: entry.requestedPrintId,
+            fields,
+        };
+    }
+    return prints;
+}
+/** Rejects unexpected remotely supplied field names. */
+function hasExactKeys(value, keys) {
+    return Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+/** Allows one optional key while still rejecting unknown remote catalog fields. */
+function hasOnlyKeys(value, keys) {
+    return Object.keys(value).every(key => keys.includes(key))
+        && ['sourcePrintId', 'sourceLocale', 'sourceRevision', 'field'].every(key => Object.hasOwn(value, key));
+}
+/** Narrows parsed JSON to own enumerable data before structured validation. */
+function isRecord(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Validates positive integer ids from untrusted serialized catalog input. */
+function isPositiveNumber(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+/** Validates a serialized positive integer object key. */
+function isPositiveNumericId(value) {
+    return /^\d+$/.test(value) && isPositiveNumber(Number(value));
+}
+/** Ensures a loaded catalog uses an exact supported base locale identifier. */
+function requiredLocale(value, subject) {
+    const locale = resolveLocale(value);
+    if (locale !== value)
+        throw new Error(`unsupported ${subject} locale ${value}`);
+    return locale;
+}
+/** Checks one lower-case SHA-256 digest. */
+function isHash(value) {
+    return /^[a-f0-9]{64}$/.test(value);
+}

package/dist/i18n/catalog.d.ts

@@ -0,0 +1,8 @@
+import type { CardTextCatalogManifestInput, PreparedCardTextCatalog, PreparedMessageCatalog, SimulatorMessageCatalogInput } from './types.js';
+/** Validates and compiles one UI catalog before it is exposed to synchronous formatters. */
+export declare function prepareMessageCatalog(input: SimulatorMessageCatalogInput): PreparedMessageCatalog;
+/**
+ * Validates, freezes, and integrity-checks one separately loaded locale shard.
+ * Loading may await Web Crypto; synchronous formatting never reads assets or hashes.
+ */
+export declare function prepareCardTextCatalog(manifestInput: CardTextCatalogManifestInput, input: unknown): Promise<PreparedCardTextCatalog>;

package/dist/i18n/catalog.js

@@ -0,0 +1,195 @@
+import IntlMessageFormat from 'intl-messageformat';
+import { copyPrints, requiredPrints, snapshotPrints } from './card-print-catalog.js';
+import { simulatorMessageIds, simulatorMessageParameterTypes } from './generated/message-types.js';
+import { validateIcuMessage } from './icu.js';
+import { resolveLocale } from './locale.js';
+/** Validates and compiles one UI catalog before it is exposed to synchronous formatters. */
+export function prepareMessageCatalog(input) {
+    if (input.formatVersion !== 1)
+        throw new Error(`unsupported message catalog format ${input.formatVersion}`);
+    const locale = requiredLocale(input.locale, 'message catalog');
+    const messages = Object.create(null);
+    const formatters = new Map();
+    for (const id of simulatorMessageIds) {
+        if (!Object.hasOwn(input.messages, id))
+            throw new Error(`message catalog lacks ${id}`);
+        const template = input.messages[id];
+        if (typeof template !== 'string')
+            throw new Error(`message catalog lacks ${id}`);
+        messages[id] = template;
+        formatters.set(id, validateIcuMessage(locale, id, template, simulatorMessageParameterTypes[id]));
+    }
+    if (Object.keys(input.messages).length !== simulatorMessageIds.length)
+        throw new Error('message catalog has unknown ids');
+    return Object.freeze({ locale, messages: Object.freeze(messages), formatters });
+}
+/**
+ * Validates, freezes, and integrity-checks one separately loaded locale shard.
+ * Loading may await Web Crypto; synchronous formatting never reads assets or hashes.
+ */
+export async function prepareCardTextCatalog(manifestInput, input) {
+    const snapshot = snapshotCardCatalog(input);
+    if (snapshot.formatVersion !== 1 && snapshot.formatVersion !== 2) {
+        throw new Error(`unsupported card catalog format ${snapshot.formatVersion}`);
+    }
+    const locale = requiredLocale(snapshot.locale, 'card catalog');
+    validateManifestShape(manifestInput);
+    const manifest = copyManifest(manifestInput);
+    if (manifest.formatVersion !== snapshot.formatVersion) {
+        throw new Error('card catalog shard and manifest format mismatch');
+    }
+    const expectedShard = manifest.localeShards[locale];
+    if (expectedShard == null)
+        throw new Error(`card catalog manifest lacks ${locale} shard`);
+    const shardJson = JSON.stringify(snapshot, null, 2);
+    if (new TextEncoder().encode(shardJson).byteLength !== expectedShard.byteSize
+        || await sha256(shardJson) !== expectedShard.contentHash) {
+        throw new Error(`card catalog ${locale} shard integrity failed`);
+    }
+    if (locale === 'en' && manifest.englishBaseline !== expectedShard.contentHash) {
+        throw new Error('card catalog English baseline integrity failed');
+    }
+    if (await sha256(JSON.stringify(manifestIdentity(manifest))) !== manifest.contentHash) {
+        throw new Error('card catalog manifest integrity failed');
+    }
+    const cards = copyCards(snapshot.cards, manifest, locale);
+    const prints = snapshot.formatVersion === 2
+        ? copyPrints(requiredPrints(snapshot), manifest, locale)
+        : Object.freeze(Object.create(null));
+    return Object.freeze({ locale, manifest, cards, prints });
+}
+/** Ensures a loaded catalog uses an exact supported base locale identifier. */
+function requiredLocale(value, subject) {
+    const locale = resolveLocale(value);
+    if (locale !== value)
+        throw new Error(`unsupported ${subject} locale ${value}`);
+    return locale;
+}
+/** Rejects malformed or incomplete compiler manifest data before its digest is trusted. */
+function validateManifestShape(manifest) {
+    if ((manifest.formatVersion !== 1 && manifest.formatVersion !== 2)
+        || !isHash(manifest.contentHash) || !isHash(manifest.sourceGeneration)
+        || !isHash(manifest.englishBaseline)) {
+        throw new Error('invalid card text catalog format');
+    }
+    for (const locale of ['de', 'en', 'es', 'fr', 'it']) {
+        const shard = manifest.localeShards[locale];
+        if (shard == null || !isHash(shard.contentHash) || !Number.isSafeInteger(shard.byteSize) || shard.byteSize < 0) {
+            throw new Error(`invalid card text catalog ${locale} shard metadata`);
+        }
+    }
+    for (const [cardId, fingerprint] of Object.entries(manifest.contractFingerprints)) {
+        if (!/^\d+$/.test(cardId) || !isHash(fingerprint))
+            throw new Error('invalid card catalog fingerprint');
+    }
+    for (const [printId, canonicalId] of Object.entries(manifest.canonicalAliases)) {
+        if (!/^\d+$/.test(printId) || !Number.isSafeInteger(canonicalId) || canonicalId <= 0) {
+            throw new Error('invalid card catalog alias');
+        }
+    }
+}
+/** Copies only own records, preserving no caller-owned mutable objects or prototype fields. */
+function copyCards(source, manifest, locale) {
+    const cards = Object.create(null);
+    for (const [cardId, slots] of Object.entries(source)) {
+        if (!/^\d+$/.test(cardId) || slots == null || !Object.hasOwn(manifest.contractFingerprints, cardId)) {
+            throw new Error(`invalid card catalog card id ${cardId}`);
+        }
+        const copiedSlots = Object.create(null);
+        for (const [slot, entry] of Object.entries(slots)) {
+            if (slot.length === 0 || typeof entry?.plainText !== 'string') {
+                throw new Error(`invalid card catalog slot ${cardId}:${slot}`);
+            }
+            const sourceLocale = requiredLocale(entry.sourceLocale, `card catalog slot ${cardId}:${slot}`);
+            const status = copyStatus(entry.status, cardId, slot);
+            if (status.kind === 'notApplicable' && entry.plainText !== '') {
+                throw new Error(`invalid card catalog empty slot ${cardId}:${slot}`);
+            }
+            if ((status.kind === 'source' || status.kind === 'notApplicable') && sourceLocale !== locale) {
+                throw new Error(`card catalog source locale mismatch ${cardId}:${slot}`);
+            }
+            if (status.kind === 'fallback' && sourceLocale !== 'en') {
+                throw new Error(`card catalog fallback locale mismatch ${cardId}:${slot}`);
+            }
+            copiedSlots[slot] = Object.freeze({ plainText: entry.plainText, sourceLocale, status });
+        }
+        cards[cardId] = Object.freeze(copiedSlots);
+    }
+    return Object.freeze(cards);
+}
+/** Copies input before asynchronous hashing so caller mutation cannot change authenticated data. */
+function snapshotCardCatalog(input) {
+    if (!isRecord(input) || typeof input.formatVersion !== 'number' || typeof input.locale !== 'string' || !isRecord(input.cards)) {
+        throw new Error('invalid card catalog input');
+    }
+    const cards = Object.create(null);
+    for (const [cardId, slots] of Object.entries(input.cards)) {
+        if (!isRecord(slots))
+            throw new Error(`invalid card catalog card id ${cardId}`);
+        const copiedSlots = Object.create(null);
+        for (const [slot, entry] of Object.entries(slots)) {
+            if (!isRecord(entry) || !isRecord(entry.status))
+                throw new Error(`invalid card catalog slot ${cardId}:${slot}`);
+            copiedSlots[slot] = {
+                plainText: entry.plainText,
+                sourceLocale: entry.sourceLocale,
+                status: { ...entry.status },
+            };
+        }
+        cards[cardId] = copiedSlots;
+    }
+    const prints = input.prints === undefined ? undefined : snapshotPrints(input.prints);
+    return prints === undefined
+        ? Object.freeze({ formatVersion: input.formatVersion, locale: input.locale, cards })
+        : Object.freeze({ formatVersion: input.formatVersion, locale: input.locale, cards, prints });
+}
+/** Narrows parsed JSON to own enumerable data before structured validation. */
+function isRecord(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Copies and narrows a compiler-emitted source state. */
+function copyStatus(status, cardId, slot) {
+    if (status?.kind === 'source' || status?.kind === 'notApplicable')
+        return Object.freeze({ kind: status.kind });
+    if (status?.kind === 'fallback'
+        && (status.reason === 'missingLocale' || status.reason === 'staleEffectiveText' || status.reason === 'unreviewedSegmentation')) {
+        return Object.freeze({ kind: 'fallback', reason: status.reason });
+    }
+    throw new Error(`invalid card catalog status ${cardId}:${slot}`);
+}
+/** Makes an independently owned immutable manifest copy. */
+function copyManifest(input) {
+    const localeShards = Object.create(null);
+    for (const [locale, shard] of Object.entries(input.localeShards)) {
+        localeShards[locale] = Object.freeze({ ...shard });
+    }
+    return Object.freeze({
+        ...input,
+        localeShards: Object.freeze(localeShards),
+        canonicalAliases: Object.freeze({ ...input.canonicalAliases }),
+        contractFingerprints: Object.freeze({ ...input.contractFingerprints }),
+    });
+}
+/** Serializes exact Rust manifest identity, omitting only its self hash. */
+function manifestIdentity(manifest) {
+    return {
+        formatVersion: manifest.formatVersion,
+        sourceGeneration: manifest.sourceGeneration,
+        englishBaseline: manifest.englishBaseline,
+        localeShards: manifest.localeShards,
+        canonicalAliases: manifest.canonicalAliases,
+        contractFingerprints: manifest.contractFingerprints,
+    };
+}
+/** Uses Web Crypto during asset loading, where asynchronous work is explicitly allowed. */
+async function sha256(value) {
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle == null)
+        throw new Error('Web Crypto is required to prepare card text catalogs');
+    const bytes = new Uint8Array(await subtle.digest('SHA-256', new TextEncoder().encode(value)));
+    return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+/** Checks one lower-case SHA-256 digest. */
+function isHash(value) {
+    return /^[a-f0-9]{64}$/.test(value);
+}

package/dist/i18n/diagnostics.d.ts

@@ -0,0 +1,6 @@
+import type { CardTextDiagnosticSink, CardTextResolver, PreparedMessageCatalog } from './types.js';
+/**
+ * Creates an isolated resolver that reports each unavailable historical reference once.
+ * Consumers choose the sink, so formatter code neither logs globally nor exposes raw keys.
+ */
+export declare function createCardTextResolver(messages: PreparedMessageCatalog, reportDiagnostic?: CardTextDiagnosticSink): CardTextResolver;

package/dist/i18n/diagnostics.js

@@ -0,0 +1,19 @@
+import { resolveCardText } from './fallback.js';
+/**
+ * Creates an isolated resolver that reports each unavailable historical reference once.
+ * Consumers choose the sink, so formatter code neither logs globally nor exposes raw keys.
+ */
+export function createCardTextResolver(messages, reportDiagnostic) {
+    const reported = new Set();
+    return Object.freeze({
+        resolve(catalog, reference) {
+            return resolveCardText(catalog, messages, reference, diagnostic => {
+                const key = `${diagnostic.kind}:${diagnostic.cardId}:${diagnostic.slot}:${diagnostic.contractFingerprint}`;
+                if (reported.has(key))
+                    return;
+                reported.add(key);
+                reportDiagnostic?.(diagnostic);
+            });
+        },
+    });
+}

package/dist/i18n/fallback.d.ts

@@ -0,0 +1,3 @@
+import type { CardTextDiagnosticSink, CardTextRef, PreparedCardTextCatalog, PreparedMessageCatalog, ResolvedCardText } from './types.js';
+/** Resolves literal card prose by exact card, stable slot, and semantic fingerprint. */
+export declare function resolveCardText(catalog: PreparedCardTextCatalog, messages: PreparedMessageCatalog, reference: CardTextRef, reportDiagnostic?: CardTextDiagnosticSink): ResolvedCardText;

package/dist/i18n/fallback.js

@@ -0,0 +1,40 @@
+import { formatMessage } from './format.js';
+/** Resolves literal card prose by exact card, stable slot, and semantic fingerprint. */
+export function resolveCardText(catalog, messages, reference, reportDiagnostic) {
+    const cardId = String(reference.cardId);
+    const expected = own(catalog.manifest.contractFingerprints, cardId);
+    if (expected !== reference.contractFingerprint)
+        return unavailable(messages, reference, 'fingerprintMismatch', reportDiagnostic);
+    const slots = own(catalog.cards, cardId);
+    const entry = slots == null ? undefined : own(slots, reference.slot);
+    if (entry == null)
+        return unavailable(messages, reference, 'unknownReference', reportDiagnostic);
+    if (entry.status.kind === 'notApplicable') {
+        return { plainText: '', resolvedLocale: catalog.locale, status: 'notApplicable', diagnostic: 'notApplicable' };
+    }
+    return {
+        plainText: entry.plainText,
+        resolvedLocale: entry.sourceLocale,
+        status: entry.status.kind,
+        ...(entry.status.kind === 'fallback' ? { fallbackReason: entry.status.reason } : {}),
+    };
+}
+/** Looks up an own catalog key so a user-controlled ref cannot traverse prototypes. */
+function own(object, key) {
+    return Object.hasOwn(object, key) ? object[key] : undefined;
+}
+function unavailable(messages, reference, kind, reportDiagnostic) {
+    const diagnostic = {
+        kind,
+        cardId: reference.cardId,
+        slot: reference.slot,
+        contractFingerprint: reference.contractFingerprint,
+    };
+    reportDiagnostic?.(diagnostic);
+    return {
+        plainText: formatMessage(messages, 'abilityUnavailable'),
+        resolvedLocale: messages.locale,
+        status: 'unavailable',
+        diagnostic: kind,
+    };
+}

package/dist/i18n/format.d.ts

@@ -0,0 +1,8 @@
+import { type ParameterlessSimulatorMessageId, type SimulatorMessageId, type SimulatorMessageParams } from './generated/message-types.js';
+import type { LegacyLiteralText, PreparedMessageCatalog } from './types.js';
+/** Formats a parameterless SDK-owned ICU message. */
+export declare function formatMessage<TId extends ParameterlessSimulatorMessageId>(catalog: PreparedMessageCatalog, id: TId): string;
+/** Formats a parameterized SDK-owned ICU message with its exact generated values. */
+export declare function formatMessage<TId extends Exclude<SimulatorMessageId, ParameterlessSimulatorMessageId>>(catalog: PreparedMessageCatalog, id: TId, values: SimulatorMessageParams[TId]): string;
+/** Returns recorded legacy prose as literal data, never as an ICU template. */
+export declare function formatLegacyLiteral(value: LegacyLiteralText): string;

package/dist/i18n/format.js

@@ -0,0 +1,29 @@
+import { simulatorMessageParameterTypes, } from './generated/message-types.js';
+export function formatMessage(catalog, id, values) {
+    const formatter = catalog.formatters.get(id);
+    if (formatter == null)
+        throw new Error(`prepared message catalog lacks ${id}`);
+    validateIntegerValues(id, values);
+    const result = formatter.format(values);
+    return Array.isArray(result) ? result.join('') : String(result);
+}
+/**
+ * Guards generated integer fields at the one JavaScript boundary before ICU
+ * formatting. Rust stores these values as `i64`; accepting a float, non-finite
+ * number, or unsafe JavaScript integer would create display data Rust cannot
+ * serialize or compare faithfully.
+ */
+function validateIntegerValues(id, values) {
+    for (const [name, type] of Object.entries(simulatorMessageParameterTypes[id])) {
+        if (type !== 'integer')
+            continue;
+        const value = values?.[name];
+        if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+            throw new Error(`invalid integer message value ${id}.${name}`);
+        }
+    }
+}
+/** Returns recorded legacy prose as literal data, never as an ICU template. */
+export function formatLegacyLiteral(value) {
+    return value.text;
+}