@urbicon-ui/i18n 6.3.9 → 6.3.10

package/dist/i18n/package-integration.js

@@ -15,32 +15,39 @@ import { getRegistry } from './registry.svelte.js';
  * out of the initial bundle as dynamic-import chunks, loaded only when activated.
  */
 export function createPackageI18n(packageName, translations, options) {
-    // Eager registration at module-init time. The previous lazy variant
-    // (queueMicrotask inside t()) returned the raw key on first call and
-    // never re-triggered the reactive expression that read it, so consumers
-    // saw `filter.button.add` instead of the translated string.
+    // Lazy, first-use registration — deliberately NOT at module-eval (Codeberg #22).
+    // A consumer's top-level `export const x = createPackageI18n(...)` must not call
+    // getRegistry() during module initialisation: in a reordered *production* chunk
+    // (Rollup, `sideEffects: false`) that call can run before the registry module's
+    // `class I18nRegistry` statement, hitting the class temporal dead zone →
+    // `new (undefined)()` → "is not a constructor" → blank page on hydration. The
+    // hoisted getRegistry() keeps the *getter* reachable, but the *class* it
+    // constructs is still a TDZ binding, so the hoist guard alone was insufficient.
     //
-    // Running synchronously here is safe: `createPackageI18n` is invoked at
-    // module top-level (`export const tableI18n = createPackageI18n(...)`),
-    // which is outside any $derived/$effect — so the SvelteMap mutation in
-    // `registerPackage` cannot trip the `state_unsafe_mutation` rule.
-    //
-    // Goes through `getRegistry()` (a hoisted function), NOT a module-const binding:
-    // this call fires at consumer module-eval time, and under Vite 8 / Rolldown a
-    // reordered chunk can run it before the registry module's body ran. A hoisted
-    // function binding survives that; the lazy getter then builds the registry on
-    // first touch, in whatever order the chunks happen to fire.
-    getRegistry().registerPackage(packageName, translations);
-    // Opt-in lazy locales (WP4): register dynamic-import loaders. The eager bundle
-    // above is the base; these cover the rest, loaded on demand by the provider /
-    // setLocale. Parity for lazy bundles is a runtime concern (validatePackageTranslations).
-    if (options?.loaders) {
+    // Deferring registration to the first useTranslate()/t()/exists() call removes
+    // the ordering dependency at the source: by render / first-call time every module
+    // is fully evaluated, so `new I18nRegistry()` is always safe. Registration is
+    // synchronous (it runs before the translate read), so the first call resolves the
+    // real string — unlike the old queueMicrotask variant that returned the raw key.
+    // registerPackage mutates the reactive SvelteMap, but first touch is a component
+    // init (`useTranslate` body) or a non-reactive call (`t`/tests), never inside a
+    // `$derived`, so it cannot trip `state_unsafe_mutation`.
+    let registered = false;
+    const ensureRegistered = () => {
+        if (registered)
+            return;
+        registered = true;
         const registry = getRegistry();
-        for (const [locale, loader] of Object.entries(options.loaders)) {
-            if (loader)
-                registry.registerPackageLoader(packageName, locale, loader);
+        registry.registerPackage(packageName, translations);
+        // Opt-in lazy locales (WP4): dynamic-import loaders alongside the eager base
+        // bundle, loaded on demand by the provider / setLocale.
+        if (options?.loaders) {
+            for (const [locale, loader] of Object.entries(options.loaders)) {
+                if (loader)
+                    registry.registerPackageLoader(packageName, locale, loader);
+            }
         }
-    }
+    };
     // Context-scoped hook — the SSR-correct, reactive accessor. Captures the
     // request-scoped locale state at component init (or `undefined` without a
     // provider → base locale), then resolves against the static registry. Reading
@@ -48,6 +55,7 @@ export function createPackageI18n(packageName, translations, options) {
     // call-sites re-render on locale change; reading the registry's SvelteMap makes
     // them re-render when a package registers more translations.
     const useTranslate = () => {
+        ensureRegistered();
         const state = useI18nState();
         const registry = getRegistry();
         return ((key, params, options) => registry.translate(key, state?.locale ?? BASE_LOCALE, state?.fallbackLocale ?? BASE_LOCALE, params, { packageName, ...options }));
@@ -56,15 +64,25 @@ export function createPackageI18n(packageName, translations, options) {
     // against the base locale — there is no request-scoped state outside a
     // component. Components use `useTranslate` for the reactive, provider-scoped
     // locale.
-    const t = ((key, params, options) => getRegistry().translate(key, BASE_LOCALE, BASE_LOCALE, params, {
-        packageName,
-        ...options
-    }));
-    const exists = (key) => getRegistry().exists(key, BASE_LOCALE, packageName);
-    const getLocales = () => getRegistry().getPackageLocales(packageName);
-    // No-op kept for API back-compat with callers that used to invoke `register()`
-    // before reading translations. Registration now happens eagerly above.
-    const register = () => { };
+    const t = ((key, params, options) => {
+        ensureRegistered();
+        return getRegistry().translate(key, BASE_LOCALE, BASE_LOCALE, params, {
+            packageName,
+            ...options
+        });
+    });
+    const exists = (key) => {
+        ensureRegistered();
+        return getRegistry().exists(key, BASE_LOCALE, packageName);
+    };
+    const getLocales = () => {
+        ensureRegistered();
+        return getRegistry().getPackageLocales(packageName);
+    };
+    // Eager-register escape hatch: a consumer that wants the package present before
+    // the first useTranslate()/t() (e.g. to preload a lazy locale) can call this.
+    // Previously a no-op; now it performs the idempotent first-use registration.
+    const register = () => ensureRegistered();
     return {
         useTranslate,
         t,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/i18n",
-  "version": "6.3.9",
+  "version": "6.3.10",
   "description": "Runes-based localization for Svelte 5 apps and the Urbicon UI design system",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@types/node": "^25.9.4",
-    "@urbicon-ui/shared-types": "6.3.9",
+    "@urbicon-ui/shared-types": "6.3.10",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",