first commit

docs/foundation/data/packer-browser/src/i18n/messages.md

@@ -0,0 +1,91 @@
+# `i18n/messages`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`messages.ts` is the English defaults catalog plus the resolver hook for
+every user-visible error message thrown by `@suaveplan/packer-browser`.
+It exists so that `throw` sites in `src/` never carry inline English
+literals — instead they pass a `packer-browser.error.<CODE>.<scenario>`
+key to `resolvePackerBrowserMessage`, which an application can override
+by passing a custom `MessageResolver` (e.g. one backed by an i18n
+catalogue) to any public option bundle.
+
+## Features
+
+- `PACKER_BROWSER_MESSAGES` — frozen catalog covering every key
+  referenced from production code; missing entries fall back to the
+  bare key (visible in test output, never silently absent).
+- `defaultPackerBrowserResolver` — `MessageResolver` instance that
+  performs `{name}` placeholder interpolation from the resolver's
+  `params` argument.
+- `resolvePackerBrowserMessage(resolver, key, params?)` — helper used
+  at every `throw` site so the resolver-vs-default branch lives in one
+  place.
+- Placeholder syntax: `"{name}"` (not `"${name}"`) — biome's
+  `noTemplateCurlyInString` rule rejects the template-literal form
+  inside string literals.
+
+## Usage: Basic
+
+```ts
+import { resolvePackerBrowserMessage } from "@suaveplan/packer-browser";
+
+const msg = resolvePackerBrowserMessage(
+    undefined,
+    "packer-browser.error.RESOURCE_NOT_FOUND.http-status",
+    { status: 404, url: "/missing.packed" }
+);
+// "Packed resource fetch returned HTTP 404 for /missing.packed."
+```
+
+## Usage: Advanced
+
+```ts
+import type { MessageResolver } from "@suaveplan/packer-browser";
+import { createPackedResourceManager } from "@suaveplan/packer-browser";
+
+const frenchResolver: MessageResolver = (key, params) => {
+    const fr: Record<string, string> = {
+        "packer-browser.error.RESOURCE_NOT_FOUND.http-status":
+            "Ressource introuvable ({url}) — HTTP {status}.",
+    };
+    let out = fr[key] ?? key;
+    if (params !== undefined) {
+        for (const [k, v] of Object.entries(params)) {
+            out = out.replaceAll(`{${k}}`, String(v));
+        }
+    }
+    return out;
+};
+
+const manager = createPackedResourceManager({
+    messageResolver: frenchResolver,
+});
+```
+
+## API Reference
+
+- `PACKER_BROWSER_MESSAGES: PackerBrowserMessageCatalog` — frozen
+  English defaults; readonly `[key: string]: string`.
+- `defaultPackerBrowserResolver: MessageResolver` — looks up the key
+  in `PACKER_BROWSER_MESSAGES` and interpolates `{name}` from
+  `params`.
+- `resolvePackerBrowserMessage(resolver, key, params?): string` —
+  routes through `resolver ?? defaultPackerBrowserResolver`.
+- Re-exported types: `MessageResolver` (alias of
+  `@suaveplan/types`'s), `PackerBrowserMessageCatalog`.
+
+## Implementation Notes
+
+The catalog is sparse: only keys actually referenced from `src/`
+appear. A conformance test scans `src/**/*.ts` for resolver call sites
+and asserts every key has a catalog entry. Missing entries surface to
+the user as the bare key, which is intentional — silent fallback to a
+canned English string would mask a missing catalogue entry in
+production. Consumers wiring a custom `MessageResolver` should
+implement the same fallback (return the key verbatim when no
+translation exists) so the contract round-trips cleanly.