@sonenta/react-i18next 2.0.0

package/dist/index.js

@@ -0,0 +1,1299 @@
+// src/provider.tsx
+import {
+  createContext,
+  Fragment,
+  useContext,
+  useEffect,
+  useMemo,
+  useSyncExternalStore
+} from "react";
+
+// src/i18n.ts
+import {
+  createInstance as createInstance2
+} from "i18next";
+import { initReactI18next as initReactI18next2 } from "react-i18next";
+
+// src/catalog.ts
+var RTL_LANGS = /* @__PURE__ */ new Set([
+  "ar",
+  "arc",
+  "ckb",
+  "dv",
+  "fa",
+  "ha",
+  "he",
+  "khw",
+  "ks",
+  "ku",
+  "nqo",
+  "ps",
+  "sd",
+  "ug",
+  "ur",
+  "yi"
+]);
+function localeChain(locale) {
+  const parts = locale.split("-").filter(Boolean);
+  if (parts.length <= 1) return [locale];
+  const chain = [];
+  for (let i = parts.length; i >= 1; i--) chain.push(parts.slice(0, i).join("-"));
+  return chain;
+}
+async function loadCatalog(apiBase, fetchImpl = fetch) {
+  try {
+    const url = `${apiBase.replace(/\/+$/, "")}/v1/languages`;
+    const r = await fetchImpl(url, { method: "GET", credentials: "omit" });
+    if (!r.ok) return null;
+    const data = await r.json();
+    return Array.isArray(data) ? data : null;
+  } catch {
+    return null;
+  }
+}
+var LanguageCatalog = class {
+  _catalog = /* @__PURE__ */ new Map();
+  /** Merge catalog entries into the map, keyed by lower-cased BCP-47 code. */
+  merge(items) {
+    if (!items) return;
+    for (const item of items) {
+      if (item && typeof item.code === "string") {
+        this._catalog.set(item.code.toLowerCase(), item);
+      }
+    }
+  }
+  /** Catalog entry for a locale, walking variant→base (`fr-CA` → `fr`);
+   *  `undefined` when no entry in the chain matches. */
+  metaFor(locale) {
+    for (const l of localeChain(locale)) {
+      const hit = this._catalog.get(l.toLowerCase());
+      if (hit) return hit;
+    }
+    return void 0;
+  }
+  /**
+   * Text direction for a locale — i18next parity. Catalog `rtl` is
+   * authoritative (with variant→base inheritance); falls back to the built-in
+   * {@link RTL_LANGS} primary-subtag check before/without the catalog, else
+   * `'ltr'`.
+   */
+  dir(locale) {
+    const meta = this.metaFor(locale);
+    if (meta && typeof meta.rtl === "boolean") return meta.rtl ? "rtl" : "ltr";
+    const primary = locale.split("-")[0]?.toLowerCase();
+    return primary && RTL_LANGS.has(primary) ? "rtl" : "ltr";
+  }
+  /** Endonym (native name) for a locale from the catalog; `undefined` when the
+   *  catalog has no matching entry (no built-in fallback). */
+  nativeName(locale) {
+    return this.metaFor(locale)?.native_name;
+  }
+  /** Full catalog entry for a locale; `undefined` when unknown. */
+  languageMeta(locale) {
+    return this.metaFor(locale);
+  }
+};
+
+// src/engine.ts
+import {
+  createInstance
+} from "i18next";
+import { initReactI18next } from "react-i18next";
+
+// src/missing.ts
+var MissingKeyManager = class {
+  /** Newest-first ring buffer for in-app inspectors; capped at `bufferSize`. */
+  missingEvents = [];
+  transport;
+  missingHandler;
+  flushIntervalMs;
+  flushBatchSize;
+  bufferSize;
+  pending = [];
+  seen = /* @__PURE__ */ new Set();
+  // dedup `${language_code}/${namespace}/${key}`
+  timer = null;
+  constructor(opts) {
+    this.transport = opts.transport;
+    this.missingHandler = opts.missingHandler;
+    this.flushIntervalMs = opts.flushIntervalMs;
+    this.flushBatchSize = opts.flushBatchSize;
+    this.bufferSize = opts.bufferSize;
+  }
+  /**
+   * Record a (already-vetted) missing-key event. Dedups within the buffer,
+   * pushes onto the capped ring buffer + the pending batch, and force-flushes
+   * when the batch reaches `flushBatchSize`. No-op when `missingHandler` is
+   * `'off'` (matches legacy `_reportMissing`).
+   *
+   * Returns `true` only when the event was NEWLY recorded (not a dedup / not
+   * `off`). Callers MUST gate any re-render (`_notify`) on this — notifying on
+   * a deduped report is what caused the rc render-loop: a missing key re-fires
+   * the handler on every render, so an unconditional notify loops forever.
+   */
+  record(event) {
+    if (this.missingHandler === "off") return false;
+    const dedupKey = `${event.language_code}/${event.namespace}/${event.key}`;
+    if (this.seen.has(dedupKey)) return false;
+    this.seen.add(dedupKey);
+    this.missingEvents = [event, ...this.missingEvents].slice(0, this.bufferSize);
+    this.pending.push(event);
+    if (this.pending.length >= this.flushBatchSize) {
+      void this.flush();
+    }
+    return true;
+  }
+  /**
+   * Drain the pending batch to the transport. No-op (and keeps pending intact)
+   * when `'off'`; otherwise takes + clears pending and `await`s the transport,
+   * swallowing any error (best-effort delivery).
+   */
+  async flush() {
+    if (this.missingHandler === "off") return;
+    if (!this.pending.length) return;
+    const batch = this.pending.slice(0);
+    this.pending = [];
+    try {
+      await this.transport(batch);
+    } catch {
+    }
+  }
+  /** Arm the periodic flush loop. Guarded for non-browser runtimes / `'off'`. */
+  start() {
+    if (this.missingHandler === "off") return;
+    if (typeof setInterval !== "function") return;
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.flushIntervalMs);
+  }
+  /** Clear the periodic flush loop. */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+};
+
+// src/plurals.ts
+var CLDR = ["zero", "one", "two", "few", "many", "other"];
+function localeCategories(locale) {
+  try {
+    return new Intl.PluralRules(locale).resolvedOptions().pluralCategories;
+  } catch {
+    return ["other"];
+  }
+}
+function flattenPlurals(tree, locale) {
+  const cats = localeCategories(locale);
+  const out = {};
+  for (const [k, v] of Object.entries(tree)) {
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      const keys = Object.keys(v);
+      const isPlural = keys.length > 0 && keys.some((c) => CLDR.includes(c)) && keys.every((c) => typeof v[c] === "string");
+      if (isPlural) {
+        const vv = v;
+        const fallback = vv.other ?? vv[keys[0]];
+        for (const cat of /* @__PURE__ */ new Set([...keys, ...cats])) {
+          out[`${k}_${cat}`] = vv[cat] ?? fallback;
+        }
+      } else {
+        out[k] = flattenPlurals(v, locale);
+      }
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+// src/transport.ts
+var SDK_LIB = "@sonenta/react-i18next";
+var SDK_VER = true ? "2.0.0" : "0.0.0-dev";
+function defaultTransport(opts) {
+  return async (batch) => {
+    if (!batch.length) return;
+    const body = {
+      project_uuid: opts.projectUuid,
+      events: batch.map((e) => ({
+        key: e.key,
+        namespace: e.namespace,
+        language_code: e.language_code,
+        // Option A (#746): only send source_value when there's a real value;
+        // omit it otherwise (never the key name). Absent = "no default".
+        ...e.source_value !== void 0 ? { source_value: e.source_value } : {},
+        sdk_meta: {
+          lib: SDK_LIB,
+          ver: SDK_VER,
+          ...typeof window !== "undefined" ? { url: window.location?.href } : {},
+          ...e.sdk_meta ?? {}
+        }
+      }))
+    };
+    try {
+      await fetch(`${opts.apiBase.replace(/\/+$/, "")}/v1/missing`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `ApiKey ${opts.token}`
+        },
+        body: JSON.stringify(body),
+        // SDKs are best-effort; never block the render path
+        keepalive: true
+      });
+    } catch {
+    }
+  };
+}
+var logTransport = (batch) => {
+  for (const e of batch) {
+    console.warn("[sonenta] missing key", e);
+  }
+};
+
+// src/engine.ts
+async function detectKeySeparator(apiBase, projectUuid, version, token, f) {
+  try {
+    const url = `${apiBase.replace(/\/+$/, "")}/v1/projects/${projectUuid}/versions/${encodeURIComponent(version)}`;
+    const r = await f(url, {
+      method: "GET",
+      headers: { Authorization: `ApiKey ${token}` },
+      credentials: "omit"
+    });
+    if (!r.ok) return ".";
+    const meta = await r.json();
+    return meta.key_style === "flat" ? false : meta.key_separator || ".";
+  } catch {
+    return ".";
+  }
+}
+
+// src/key-registry.ts
+var GLOBAL = "__verbumia_key_registry__";
+var SEP = "\0";
+function split(fullKey, defaultNamespace) {
+  const idx = fullKey.indexOf(":");
+  if (idx > 0) {
+    return { namespace: fullKey.slice(0, idx), key: fullKey.slice(idx + 1) };
+  }
+  return { namespace: defaultNamespace, key: fullKey };
+}
+var KeyRegistry = class {
+  // One Set per mounted hook/Trans instance (keyed by an opaque token).
+  // The on-screen set is the UNION of all live instances' latest render.
+  _instances = /* @__PURE__ */ new Map();
+  // Provider mounts that have published us onto globalThis. Ref-counted so
+  // a multi-provider tree (or fast unmount/remount in tests) never leaves
+  // a stale global or unpublishes while another provider is still live.
+  _providers = 0;
+  /** Replace an instance's contributed key set (per-render hook producer). */
+  _set(token, keys) {
+    this._instances.set(token, keys);
+  }
+  /** Append ONE id to a token's set, lazy-creating it. Used by the
+   *  instance-level i18n.t wrap, which accumulates over the i18n
+   *  instance's lifetime (no per-render reset semantics). Safe to call
+   *  before `attach()` — the global publishes whenever a provider mounts. */
+  _track(token, id) {
+    let set = this._instances.get(token);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._instances.set(token, set);
+    }
+    set.add(id);
+  }
+  /** Drop an instance entirely (called on hook unmount or i18n stop). */
+  _delete(token) {
+    this._instances.delete(token);
+  }
+  /** Keys rendered by currently-mounted consumers. Stable insertion order. */
+  snapshot() {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const set of this._instances.values()) {
+      for (const id of set) {
+        if (seen.has(id)) continue;
+        seen.add(id);
+        const c = id.indexOf(SEP);
+        out.push({ namespace: id.slice(0, c), key: id.slice(c + 1) });
+      }
+    }
+    return out;
+  }
+  /** True when ANY producer has contributed ≥1 key. Cheap O(producers)
+   *  check exposed for DEV-time integration asserts ("did my
+   *  useTranslation imports end up wired to @sonenta/react-i18next?"). */
+  isPopulated() {
+    for (const set of this._instances.values()) {
+      if (set.size > 0) return true;
+    }
+    return false;
+  }
+  /** Escape hatch (router integrations / tests). Mount-tracking already
+   *  handles navigation, so this is rarely needed. */
+  reset() {
+    this._instances.clear();
+  }
+  /** Encode a resolved key into the internal id used by `_set`. */
+  encode(fullKey, defaultNamespace) {
+    const k = split(fullKey, defaultNamespace);
+    return `${k.namespace}${SEP}${k.key}`;
+  }
+  /** Provider mounted — publish the global (idempotent, ref-counted). */
+  attach() {
+    this._providers += 1;
+    if (this._providers === 1) {
+      globalThis[GLOBAL] = {
+        snapshot: () => this.snapshot(),
+        isPopulated: () => this.isPopulated(),
+        reset: () => this.reset()
+      };
+    }
+  }
+  /** Provider unmounted — unpublish when the last one goes away. */
+  detach() {
+    this._providers = Math.max(0, this._providers - 1);
+    if (this._providers === 0) {
+      this._instances.clear();
+      const g = globalThis;
+      if (g[GLOBAL]) delete g[GLOBAL];
+    }
+  }
+};
+var keyRegistry = new KeyRegistry();
+
+// src/i18n.ts
+var DEFAULT_API_BASE = "https://api.verbumia.dev";
+var DEFAULT_CDN_BASE = "https://cdn.verbumia.ca";
+var DEFAULT_FLUSH_MS = 5e3;
+var DEFAULT_BATCH = 50;
+var DEFAULT_BUFFER = 200;
+var DEFAULT_VERSION_SLUG = "main";
+function asArray(fb) {
+  if (fb == null) return [];
+  return (Array.isArray(fb) ? fb : [fb]).filter(Boolean);
+}
+var SonentaI18n = class {
+  ready = false;
+  locale;
+  fallbackLng;
+  missingEvents = [];
+  // The underlying real i18next instance (engine). Resolution/plurals/
+  // interpolation/context all run through this; the adapter only orchestrates
+  // loading + the missing-key gate + the React subscription.
+  _i18next;
+  // Original (native) i18next.changeLanguage, captured before we override the
+  // instance's changeLanguage to route through setLocale (#806 bug3). Used by
+  // _syncLanguage to switch the language WITHOUT re-entering our loader.
+  _origChangeLanguage;
+  // Token identifying THIS i18n instance in the on-screen key registry
+  // (#806 SeedSower instance-level producer — see _wrapInstanceT). Dropped
+  // in stop() so accumulated keys don't outlive a remounted provider.
+  _registryToken = /* @__PURE__ */ Symbol("sonenta.instance");
+  // Tracks which (version, locale, ns) we've actually fetched, and which came
+  // back with ≥1 top-level key. The missing-key gate needs `_hasContent`
+  // (200-with-content) to avoid the boot-flood when a namespace is unpublished
+  // or a fetch came back empty. i18next's own resource store can't carry this
+  // distinction (an empty {} bundle still `hasResourceBundle`).
+  _attempted = /* @__PURE__ */ new Set();
+  _hasContent = /* @__PURE__ */ new Set();
+  // Language catalog (#803): dir()/nativeName()/languageMeta(). Primed from
+  // config.languageCatalog and/or the public GET /v1/languages in start().
+  _catalog = new LanguageCatalog();
+  _catalogDisabled = false;
+  _config;
+  // Surface variant (#911). When set, each loaded (locale,ns) is composed as
+  // base ⊕ sparse `{ns}.{surface}.json` overlay (overlay wins per key). We
+  // cache the raw base tree + raw overlay trees so a surface switch recomposes
+  // WITHOUT refetching the base, and so a switch cleanly rebuilds base-then-
+  // overlay (no stale overlay keys). `undefined` ⇒ surface resolution off.
+  _surface;
+  _baseTree = /* @__PURE__ */ new Map();
+  // bundleKey -> raw base JSON
+  _overlayTree = /* @__PURE__ */ new Map();
+  // `${bundleKey}#${surface}` -> raw overlay JSON ({} sentinel on miss)
+  // Resolved asset refs (#911 minimal v1), keyed `${locale}/${ns}/${keyPath}`
+  // for the CURRENT composition (base assets, then overlay assets override).
+  _assets = /* @__PURE__ */ new Map();
+  _missing;
+  _listeners = /* @__PURE__ */ new Set();
+  // Stable snapshot reference for useSyncExternalStore. Rebuilt ONLY in _notify
+  // (when state actually changed) and returned as-is between notifications.
+  _snapshot;
+  // Effective key separator (#754): false = flat (literal lookups, so dotted
+  // keys like "App Version 6.3.8" work), a string = nested. Set from
+  // config.keySeparator (explicit override, wins) or auto-detected from the
+  // version's key_style/key_separator on start(). Defaults to ".".
+  _keySeparatorExplicit = false;
+  // Namespace separator (#754): false = no ns prefix parsing. Default ':'.
+  _nsSeparator = ":";
+  // Developer-supplied {{value, format}} formatter (#805-1), re-bound onto the
+  // live interpolator after init (i18next overwrites it during init).
+  _userFormat;
+  constructor(config) {
+    const removedRealtimeKeys = Object.keys(config).filter(
+      (k) => k === "liveUpdates" || k.startsWith("centrifugo")
+    );
+    if (removedRealtimeKeys.length > 0) {
+      throw new Error(
+        `@sonenta/react-i18next: ${removedRealtimeKeys.join(", ")} ${removedRealtimeKeys.length > 1 ? "were" : "was"} removed in 0.9.0 \u2014 realtime is now the @sonenta/realtime plugin. Remove them and pass \`plugins: [sonentaRealtime({ wsUrl })]\` to <SonentaProvider> instead.`
+      );
+    }
+    this.locale = config.defaultLocale;
+    this.fallbackLng = config.fallbackLng;
+    this._surface = config.surface;
+    let keySeparator = ".";
+    if (config.keySeparator !== void 0) {
+      keySeparator = config.keySeparator;
+      this._keySeparatorExplicit = true;
+    }
+    if (config.nsSeparator !== void 0) this._nsSeparator = config.nsSeparator;
+    this._config = {
+      apiBase: config.apiBase ?? DEFAULT_API_BASE,
+      cdnBase: config.cdnBase ?? DEFAULT_CDN_BASE,
+      missingHandler: config.missingHandler ?? "send",
+      token: config.token,
+      projectUuid: config.projectUuid,
+      namespaces: config.namespaces?.length ? config.namespaces : config.defaultNS ? [config.defaultNS] : ["common"],
+      flushIntervalMs: config.flushIntervalMs ?? DEFAULT_FLUSH_MS,
+      flushBatchSize: config.flushBatchSize ?? DEFAULT_BATCH,
+      missingEventsBufferSize: config.missingEventsBufferSize ?? DEFAULT_BUFFER,
+      version: config.version ?? config.versionSlug ?? DEFAULT_VERSION_SLUG,
+      env: config.env ?? "prod"
+    };
+    const transport = config.transport ?? (this._config.missingHandler === "log" ? logTransport : defaultTransport({
+      apiBase: this._config.apiBase,
+      token: this._config.token,
+      projectUuid: this._config.projectUuid
+    }));
+    this._missing = new MissingKeyManager({
+      transport,
+      missingHandler: this._config.missingHandler,
+      flushIntervalMs: this._config.flushIntervalMs,
+      flushBatchSize: this._config.flushBatchSize,
+      bufferSize: this._config.missingEventsBufferSize
+    });
+    this._userFormat = config.interpolation?.format;
+    const resources = {};
+    if (config.initialBundles) {
+      for (const [loc, byNs] of Object.entries(config.initialBundles)) {
+        for (const [ns2, tree] of Object.entries(byNs)) {
+          if (!tree || typeof tree !== "object") continue;
+          (resources[loc] ??= {})[ns2] = flattenPlurals(tree, loc);
+          this._baseTree.set(this._bundleKey(loc, ns2), tree);
+          if (Object.keys(tree).length > 0) {
+            this._hasContent.add(this._bundleKey(loc, ns2));
+          }
+        }
+      }
+    }
+    const interpolation = {
+      escapeValue: false,
+      format: this._userFormat
+    };
+    const ns = this._config.namespaces;
+    this._i18next = createInstance2();
+    this._i18next.use(initReactI18next2);
+    void this._i18next.init({
+      lng: this.locale,
+      fallbackLng: config.fallbackLng ?? false,
+      ns,
+      defaultNS: ns[0],
+      fallbackNS: false,
+      initAsync: false,
+      keySeparator,
+      nsSeparator: this._nsSeparator,
+      // #806 bug2: re-render react-i18next-native consumers when our async
+      // loads addResourceBundle (bindI18nStore catches 'added'/'removed'). The
+      // missing-key park is addResource SILENT, so it never emits 'added' →
+      // no re-render loop (the rc.1 forceStoreRerender-on-saveMissing regression).
+      react: {
+        bindI18n: "languageChanged loaded",
+        bindI18nStore: "added removed",
+        useSuspense: false
+      },
+      resources,
+      partialBundledLanguages: true,
+      // A nested-object (non-plural) key resolves to an object; legacy `t()`
+      // returns the raw key in that case, so map it back to the key here.
+      returnedObjectHandler: (key) => key,
+      // GATE (legacy three-condition gate): only report once the active
+      // locale's bundle exists AND has ≥1 key, AND we've flipped `ready` after a
+      // real fetch (`_attempted` + `_hasContent`). i18next fires the handler
+      // even for empty/absent bundles, so the filtering lives here.
+      saveMissing: this._config.missingHandler !== "off",
+      saveMissingTo: "all",
+      interpolation,
+      missingKeyHandler: this._handleMissing
+    });
+    this._origChangeLanguage = this._i18next.changeLanguage.bind(this._i18next);
+    this._i18next.changeLanguage = ((lng, ...rest) => {
+      if (typeof lng !== "string" || lng === this.locale) {
+        return this._origChangeLanguage(lng, ...rest);
+      }
+      return this.setLocale(lng).then(
+        () => this._i18next.getFixedT(this.locale, null)
+      );
+    });
+    this._wrapInstanceT();
+    this._rebindFormat();
+    this._catalogDisabled = config.disableLanguageCatalog === true;
+    this._catalog.merge(config.languageCatalog);
+    const active = config.initialBundles?.[this.locale];
+    if (active && this._config.namespaces.every(
+      (n) => active[n] && Object.keys(active[n]).length > 0
+    )) {
+      this.ready = true;
+    }
+    this._snapshot = this._buildSnapshot();
+  }
+  /** Re-bind the developer `{{value, format}}` formatter onto the live
+   *  interpolator (i18next overwrites `interpolation.format` during init). */
+  _rebindFormat() {
+    const userFormat = this._userFormat;
+    if (!userFormat) return;
+    const interpolator = this._i18next.services?.interpolator;
+    if (!interpolator) return;
+    const builtIn = this._i18next.options.interpolation?.format;
+    interpolator.format = ((value, format, lng, opts) => {
+      const out = userFormat(
+        value,
+        format,
+        lng,
+        opts ?? {}
+      );
+      if (out === value && builtIn) {
+        return builtIn(value, format, lng, opts);
+      }
+      return out;
+    });
+  }
+  /** Monkey-patch `i18next.t` so every resolved key feeds the on-screen
+   *  registry (#806). The override is an OWN property on the instance,
+   *  shadowing the prototype `t()` method; getFixedT-returned t functions
+   *  look up `this.t` dynamically (i18next v26 source ~line 2060), so
+   *  native `react-i18next` `useTranslation` / `<Trans>` go through it
+   *  too. Bookkeeping is wrapped in try/catch — a registry failure must
+   *  never break translation. */
+  _wrapInstanceT() {
+    const i18n = this._i18next;
+    const orig = i18n.t.bind(i18n);
+    const token = this._registryToken;
+    const defaultNs = () => this.defaultNamespace;
+    const wrapped = ((...args) => {
+      const result = orig(...args);
+      try {
+        const rawKey = args[0];
+        const opts = args[1] && typeof args[1] === "object" && !Array.isArray(args[1]) ? args[1] : void 0;
+        let keyStr;
+        if (typeof rawKey === "string") {
+          keyStr = rawKey;
+        } else if (Array.isArray(rawKey) && typeof rawKey[0] === "string") {
+          keyStr = rawKey[0];
+        }
+        if (keyStr) {
+          const optsNs = opts?.ns;
+          const ns = typeof optsNs === "string" ? optsNs : Array.isArray(optsNs) ? optsNs[0] : void 0;
+          const fullKey = ns && !keyStr.includes(":") ? `${ns}:${keyStr}` : keyStr;
+          keyRegistry._track(token, keyRegistry.encode(fullKey, defaultNs()));
+        }
+      } catch {
+      }
+      return result;
+    });
+    i18n.t = wrapped;
+  }
+  // ---- React subscription ----
+  subscribe = (listener) => {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  };
+  /** Stable snapshot accessor for useSyncExternalStore. The returned object
+   *  reference is identical between renders unless _notify fired. */
+  getSnapshot = () => this._snapshot;
+  _buildSnapshot() {
+    return {
+      ready: this.ready,
+      locale: this.locale,
+      language: this.locale,
+      setLocale: this.setLocale,
+      changeLanguage: this.changeLanguage,
+      t: this.t,
+      missingEvents: this.missingEvents,
+      flushMissing: this.flushMissing,
+      reload: this.reload,
+      refresh: this.refresh,
+      surface: this._surface,
+      setSurface: this.setSurface,
+      asset: this.asset,
+      dir: this.dir,
+      nativeName: this.nativeName,
+      languageMeta: this.languageMeta,
+      i18next: this._i18next
+    };
+  }
+  /** Bundle cache-key builder. Includes `version` so providers with different
+   *  `version` values never share state. Segments are slugs (no '/'). */
+  _bundleKey(locale, ns) {
+    return `${this._config.version}/${locale}/${ns}`;
+  }
+  _notify() {
+    this._snapshot = this._buildSnapshot();
+    for (const l of this._listeners) l();
+  }
+  /** Force react-i18next-NATIVE consumers (raw `useTranslation`/`<Trans>` on the
+   *  exposed instance) to re-render in the READY state, by emitting i18next's
+   *  `loaded` event (which react-i18next binds via `bindI18n`). Called AFTER
+   *  `ready=true`, so a missing key they render is re-evaluated once the gate is
+   *  open → it streams to `/v1/missing` (#806 native path; our own
+   *  `useTranslation` already re-renders via `_notify`). The missing-key park is
+   *  a SILENT addResource, so this never reopens the render loop (rc.1). */
+  _signalLoaded() {
+    this._i18next.emit("loaded", {});
+  }
+  // ---- Lifecycle ----
+  /** Default namespace (the first configured one) — used to attribute a bare
+   *  `t("key")` call when recording on-screen keys. */
+  get defaultNamespace() {
+    return this._config.namespaces[0];
+  }
+  /**
+   * Ordered lookup chain for an active locale: the locale itself, its
+   * base-language truncations (`fr-CA → fr`), then the configured
+   * `fallbackLng`(s) — deduped, order-preserving (the `fr-CA → fr → source`
+   * chain, #803). Used to drive bundle loading; i18next handles resolution
+   * fallback itself via its `languages` list.
+   */
+  _resolutionChain(locale) {
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const l of [...localeChain(locale), ...asArray(this.fallbackLng)]) {
+      if (l && !seen.has(l)) {
+        seen.add(l);
+        out.push(l);
+      }
+    }
+    return out;
+  }
+  /** Loads the configured namespaces for the active locale's full resolution
+   *  chain (locale → base → fallback), wires up the key separator + catalog,
+   *  flips `ready`, and arms the missing-key flush loop. */
+  async start(fetchImpl = fetch) {
+    keyRegistry.attach();
+    const targets = new Set(this._resolutionChain(this.locale));
+    await Promise.all([
+      ...[...targets].flatMap(
+        (loc) => this._config.namespaces.map(
+          (ns) => this._loadBundle(loc, ns, fetchImpl)
+        )
+      ),
+      // Best-effort: align the key separator with the version's key_style (#754).
+      this._loadKeyStyle(fetchImpl),
+      // Best-effort: load the public language catalog for dir()/nativeName().
+      this._loadCatalog(fetchImpl)
+    ]);
+    await this._syncLanguage();
+    this.ready = true;
+    this._missing.start();
+    this._notify();
+    this._signalLoaded();
+  }
+  /** Best-effort: read the version's `key_style` / `key_separator` (#754) so the
+   *  SDK resolves keys the way the project's bundles are shaped. Skipped when
+   *  the dev set `keySeparator` explicitly; on 403/404/offline keep the default. */
+  async _loadKeyStyle(fetchImpl) {
+    if (this._keySeparatorExplicit) return;
+    const sep = await detectKeySeparator(
+      this._config.apiBase,
+      this._config.projectUuid,
+      this._config.version,
+      this._config.token,
+      fetchImpl
+    );
+    this._i18next.options.keySeparator = sep;
+  }
+  /** Best-effort: fetch the PUBLIC language catalog and merge it in (#803).
+   *  Skipped when disabled; a failure keeps any embedded catalog. */
+  async _loadCatalog(fetchImpl) {
+    if (this._catalogDisabled) return;
+    this._catalog.merge(await loadCatalog(this._config.apiBase, fetchImpl));
+  }
+  /** Re-derive i18next's active language chain from the adapter's locale +
+   *  fallbackLng. `changeLanguage` recomputes `instance.languages`
+   *  (variant→base→fallback) so native resolution fallback is correct. */
+  async _syncLanguage() {
+    if (this._i18next.language !== this.locale) {
+      await this._origChangeLanguage(this.locale);
+    }
+  }
+  setLocale = async (next) => {
+    if (next === this.locale) return;
+    this.locale = next;
+    this.ready = false;
+    this._notify();
+    await Promise.all(
+      this._resolutionChain(next).flatMap(
+        (loc) => this._config.namespaces.filter((ns) => !this._attempted.has(this._bundleKey(loc, ns))).map((ns) => this._loadBundle(loc, ns))
+      )
+    );
+    await this._syncLanguage();
+    this.ready = true;
+    this._notify();
+    this._signalLoaded();
+  };
+  /** Alias of {@link setLocale} for react-i18next compatibility. */
+  changeLanguage = (next) => this.setLocale(next);
+  /** Alias of {@link locale} for react-i18next compatibility. */
+  get language() {
+    return this.locale;
+  }
+  /** The underlying real `i18next` instance (#806 bug1 / #805 drop-in). Exposed
+   *  on the class too (not just the snapshot) so `getI18n().i18next` works for
+   *  react-i18next drop-in (`<Trans i18n={…}>`, `useTranslation(ns, { i18n })`). */
+  get i18next() {
+    return this._i18next;
+  }
+  /** Text direction for a locale (default: active locale) — i18next parity.
+   *  Catalog `rtl` is authoritative (variant→base); falls back to the built-in
+   *  RTL list before/without the catalog (#803). */
+  dir = (lng) => this._catalog.dir(lng ?? this.locale);
+  /** Endonym (native name) for a locale from the catalog (default: active) —
+   *  the fallback for runtimes without `Intl.DisplayNames` (#803). */
+  nativeName = (lng) => this._catalog.nativeName(lng ?? this.locale);
+  /** Full language-catalog entry for a locale (default: active); `undefined`
+   *  when the catalog has no matching entry. */
+  languageMeta = (lng) => this._catalog.languageMeta(lng ?? this.locale);
+  stop() {
+    keyRegistry._delete(this._registryToken);
+    keyRegistry.detach();
+    this._missing.stop();
+  }
+  /**
+   * #806 plugin-context backing for `SonentaPluginContext.onLanguageChange`.
+   * Subscribes to i18next's `languageChanged` emitter and returns the
+   * unsubscribe function. Wraps the i18next event so plugins never have
+   * to touch the (prefix-private) `_i18next` field directly. Fires on
+   * every successful language change — `setLocale()` /
+   * `changeLanguage()` / the drop-in `i18next.changeLanguage()` (whose
+   * #806-bug3 override routes through `setLocale` which then runs the
+   * native `_origChangeLanguage` that actually fires the event).
+   */
+  onLanguageChange = (cb) => {
+    const handler = (lng) => cb(lng);
+    this._i18next.on("languageChanged", handler);
+    return () => {
+      this._i18next.off("languageChanged", handler);
+    };
+  };
+  /**
+   * Bust-refetch already-loaded bundles and re-render once. Iterate the
+   * `_attempted` cache keys (`${version}/${locale}/${ns}`), optionally filtered
+   * by `opts.locale` / `opts.namespace`, and re-pull each with `{ bust: true }`
+   * (so the mutable CDN `latest/` alias bypasses the HTTP cache). After all
+   * settle, `_notify()` once so React re-renders. Used by `@sonenta/realtime`
+   * on a `translations_published` push and as a manual refresh hook.
+   */
+  reload = async (opts = {}) => {
+    const targets = [];
+    for (const key of this._attempted) {
+      const parts = key.split("/");
+      const locale = parts[1];
+      const ns = parts[2];
+      if (!locale || !ns) continue;
+      if (opts.locale && opts.locale !== locale) continue;
+      if (opts.namespace && opts.namespace !== ns) continue;
+      targets.push({ locale, ns });
+    }
+    if (targets.length === 0) return;
+    await Promise.all(
+      targets.map(
+        (t2) => this._loadBundle(t2.locale, t2.ns, fetch, { bust: true })
+      )
+    );
+    this._notify();
+  };
+  /**
+   * Force every `useTranslation` consumer to re-render WITHOUT refetching —
+   * re-resolves `t()` against the CURRENT resources. For plugins that mutate
+   * i18next resources directly (e.g. `@sonenta/in-context` applies an edit
+   * via `i18next.addResource`) and need the snapshot to repaint right away.
+   * Repaints BOTH this SDK's `useTranslation`/`<Trans>` (via the store
+   * `_notify`) AND react-i18next-NATIVE consumers bound to the exposed
+   * instance (via the `loaded` event). Does NO bundle fetch, so an in-place
+   * override is never clobbered — unlike {@link reload}, which bust-refetches
+   * the CDN bundles. Additive (1.0.6); safe to call any time after mount.
+   */
+  refresh = () => {
+    this._notify();
+    this._signalLoaded();
+  };
+  get surface() {
+    return this._surface;
+  }
+  /** Switch the active surface (#911) and recompose every loaded (locale, ns)
+   *  as base ⊕ the new surface's overlay, then re-render. `undefined` drops to
+   *  base-only. No-op when unchanged. Overlays are fetched on demand + cached. */
+  setSurface = async (surface) => {
+    if (surface === this._surface) return;
+    this._surface = surface;
+    const targets = [];
+    for (const key of this._attempted) {
+      const parts = key.split("/");
+      const locale = parts[1];
+      const ns = parts[2];
+      if (locale && ns) targets.push({ locale, ns });
+    }
+    await Promise.all(
+      targets.map((t2) => this._composeBundle(t2.locale, t2.ns))
+    );
+    this._notify();
+    this._signalLoaded();
+  };
+  /** Asset variant ref (#911) for `key` under the active locale+surface, or
+   *  `undefined`. Walks the locale fallback chain like `t()` would. */
+  asset = (key, namespace) => {
+    let ns = namespace ?? this.defaultNamespace;
+    let bareKey = key;
+    if (typeof this._nsSeparator === "string" && this._nsSeparator) {
+      const idx = key.indexOf(this._nsSeparator);
+      if (idx > 0) {
+        ns = key.slice(0, idx);
+        bareKey = key.slice(idx + this._nsSeparator.length);
+      }
+    }
+    for (const loc of this._resolutionChain(this.locale)) {
+      const ref = this._assets.get(`${loc}/${ns}/${bareKey}`);
+      if (ref) return ref;
+    }
+    return void 0;
+  };
+  // ---- Translation ----
+  t = (key, optionsOrDefault, maybeOptions) => {
+    const options = typeof optionsOrDefault === "string" ? { ...maybeOptions ?? {}, defaultValue: optionsOrDefault } : optionsOrDefault;
+    const literal = this._probeLiteral(key);
+    if (literal !== void 0) {
+      const interpolator = this._i18next.services?.interpolator;
+      if (interpolator && options) {
+        return interpolator.interpolate(
+          literal,
+          options,
+          this.locale,
+          {}
+        );
+      }
+      return literal;
+    }
+    return this._i18next.t(
+      key,
+      options
+    );
+  };
+  /** Probe the EXACT literal value for a key across the active language chain
+   *  (no key split), honoring the configured nsSeparator to point at the right
+   *  (lng, ns). Returns the string hit, or `undefined` to fall through to the
+   *  native nested/plural resolution. Mirrors `sonentaResolveKey`'s probe but
+   *  is local so the adapter can interpolate the result. */
+  _probeLiteral(key) {
+    const nsSeparator = this._i18next.options.nsSeparator;
+    let probeNs = this.defaultNamespace;
+    let probeKey = key;
+    if (typeof nsSeparator === "string" && nsSeparator !== "") {
+      const idx = key.indexOf(nsSeparator);
+      if (idx > 0) {
+        probeNs = key.slice(0, idx);
+        probeKey = key.slice(idx + nsSeparator.length);
+      }
+    }
+    const langs = this._i18next.languages ?? [this._i18next.language].filter(Boolean);
+    for (const lng of langs) {
+      if (!lng) continue;
+      const v = this._i18next.getResource(lng, probeNs, probeKey, {
+        keySeparator: false
+      });
+      if (typeof v === "string") return v;
+    }
+    return void 0;
+  }
+  /**
+   * i18next `missingKeyHandler`: the legacy three-condition gate + #746
+   * source_value rule. Only report once we've fetched the active locale's
+   * bundle (`ready` + `_attempted` + `_hasContent`), so the first paint /
+   * an unpublished namespace / a 404→{} / 200→{} never floods the dashboard.
+   * `fallbackValue` is ignored — when no defaultValue was passed it === key,
+   * which must NEVER become a source_value.
+   */
+  _handleMissing = (lngs, ns, key, _fallbackValue, _updateMissing, options) => {
+    void _fallbackValue;
+    void _updateMissing;
+    const lng = lngs[0] ?? this.locale;
+    const cacheKey = this._bundleKey(this.locale, ns);
+    if (!this.ready || !this._attempted.has(cacheKey) || !this._hasContent.has(cacheKey)) {
+      return;
+    }
+    const recorded = this._missing.record({
+      key,
+      namespace: ns,
+      language_code: lng,
+      source_value: this._sourceValueFor(key, ns, options)
+    });
+    if (!recorded) return;
+    const rendered = typeof options?.defaultValue === "string" ? options.defaultValue : key;
+    try {
+      this._i18next.addResource(lng, ns, key, rendered, {
+        keySeparator: false,
+        silent: true
+      });
+    } catch {
+    }
+    this.missingEvents = this._missing.missingEvents;
+    this._notify();
+  };
+  flushMissing = () => this._missing.flush();
+  // ---- Internals ----
+  /**
+   * Resolve the `source_value` for a missing-key report (Option A, #746):
+   *   1. `options.defaultValue` — explicit developer-provided string.
+   *   2. The configured fallbackLng bundle's plain-string value (the
+   *      source/canonical locale). Excludes the active locale + its derived
+   *      base (display fallbacks, not the promotable "source").
+   *   3. Otherwise `undefined` — we never send the key name as a value (the key
+   *      already travels in `event.key`).
+   */
+  _sourceValueFor(key, ns, options) {
+    if (typeof options?.defaultValue === "string") {
+      return options.defaultValue;
+    }
+    for (const loc of asArray(this.fallbackLng)) {
+      if (loc === this.locale) continue;
+      const v = this._i18next.getResource(loc, ns, key);
+      if (typeof v === "string") return v;
+    }
+    return void 0;
+  }
+  async _loadBundle(locale, ns, fetchImpl = fetch, opts = {}) {
+    const cacheKey = this._bundleKey(locale, ns);
+    let url;
+    let init;
+    if (this._config.env === "dev") {
+      const qp = { language: locale, namespace: ns };
+      if (this._config.version && this._config.version !== "main") {
+        qp.version_slug = this._config.version;
+      }
+      const params = new URLSearchParams(qp);
+      url = `${this._config.apiBase.replace(/\/+$/, "")}/v1/projects/${this._config.projectUuid}/translations/runtime?${params.toString()}`;
+      init = {
+        method: "GET",
+        headers: { Authorization: `ApiKey ${this._config.token}` },
+        credentials: "omit"
+      };
+    } else {
+      url = `${this._config.cdnBase.replace(/\/+$/, "")}/p/${this._config.projectUuid}/${this._config.version}/latest/${locale}/${ns}.json`;
+      init = { method: "GET", credentials: "omit" };
+    }
+    if (opts.bust) {
+      init.cache = "reload";
+    }
+    const hadContent = this._hasContent.has(cacheKey);
+    try {
+      const r = await fetchImpl(url, init);
+      if (r.ok) {
+        const data = await r.json();
+        if (data && typeof data === "object" && Object.keys(data).length > 0) {
+          this._baseTree.set(cacheKey, data);
+          this._hasContent.add(cacheKey);
+        } else {
+          this._baseTree.set(cacheKey, {});
+          this._hasContent.delete(cacheKey);
+        }
+      } else if (hadContent) {
+      } else {
+        this._baseTree.set(cacheKey, {});
+        this._hasContent.delete(cacheKey);
+      }
+    } catch {
+      if (hadContent) {
+      } else {
+        this._baseTree.set(cacheKey, {});
+        this._hasContent.delete(cacheKey);
+      }
+    } finally {
+      this._attempted.add(cacheKey);
+    }
+    await this._composeBundle(locale, ns, fetchImpl, opts.bust);
+  }
+  /**
+   * Compose the i18next bundle for (locale, ns) as base ⊕ surface overlay
+   * (#911). Base is applied wholesale (replace), then — when a surface is
+   * active — the sparse overlay is deep-merged on top (overlay wins per key).
+   * Rebuilding base-first on every compose means a surface SWITCH cleanly
+   * resets to base before applying the new overlay (no stale overlay keys).
+   * Plurals: both base and overlay flatten through {@link flattenPlurals}, so
+   * an overlay plural dict fully replaces the base key's plural set.
+   */
+  async _composeBundle(locale, ns, fetchImpl = fetch, bust = false) {
+    const base = this._baseTree.get(this._bundleKey(locale, ns)) ?? {};
+    const assetPrefix = `${locale}/${ns}/`;
+    for (const k of this._assets.keys()) {
+      if (k.startsWith(assetPrefix)) this._assets.delete(k);
+    }
+    const baseTree = this._unwrapAssets(base, locale, ns);
+    this._i18next.addResourceBundle(
+      locale,
+      ns,
+      flattenPlurals(baseTree, locale),
+      false,
+      true
+    );
+    if (!this._surface) return;
+    const overlay = await this._loadOverlay(
+      locale,
+      ns,
+      this._surface,
+      fetchImpl,
+      bust
+    );
+    if (!overlay || Object.keys(overlay).length === 0) return;
+    const overlayTree = this._unwrapAssets(overlay, locale, ns);
+    this._i18next.addResourceBundle(
+      locale,
+      ns,
+      flattenPlurals(overlayTree, locale),
+      true,
+      true
+    );
+  }
+  /** Fetch (and cache) the sparse surface overlay `{ns}.{surface}.json` from
+   *  the CDN. Cached per (locale, ns, surface); a `{}` is cached on miss so a
+   *  surface switch never re-hits the network for a known-absent overlay.
+   *  Overlays live on the CDN only (the dev runtime endpoint has no overlay
+   *  shape yet) — `env: "dev"` returns `{}`. */
+  async _loadOverlay(locale, ns, surface, fetchImpl = fetch, bust = false) {
+    const key = `${this._bundleKey(locale, ns)}#${surface}`;
+    if (!bust && this._overlayTree.has(key)) return this._overlayTree.get(key);
+    if (this._config.env === "dev") {
+      this._overlayTree.set(key, {});
+      return {};
+    }
+    const url = `${this._config.cdnBase.replace(/\/+$/, "")}/p/${this._config.projectUuid}/${this._config.version}/latest/${locale}/${ns}.${surface}.json`;
+    const init = { method: "GET", credentials: "omit" };
+    if (bust) init.cache = "reload";
+    let overlay = {};
+    try {
+      const r = await fetchImpl(url, init);
+      if (r.ok) {
+        const data = await r.json();
+        if (data && typeof data === "object") overlay = data;
+      }
+    } catch {
+    }
+    this._overlayTree.set(key, overlay);
+    return overlay;
+  }
+  /**
+   * Strip `{ "$value", "$asset" }` asset envelopes (#911 minimal v1) out of a
+   * raw bundle tree: each envelope is replaced by its `$value` (string or
+   * plural dict) so `t()` resolves normally, and its `$asset` is recorded
+   * under `${locale}/${ns}/${keyPath}` for {@link asset}. Returns a NEW tree;
+   * the input is not mutated. Non-envelope nodes recurse as namespace groups.
+   */
+  _unwrapAssets(tree, locale, ns) {
+    const sep = typeof this._i18next.options.keySeparator === "string" ? this._i18next.options.keySeparator : ".";
+    const walk = (node, path) => {
+      if (!node || typeof node !== "object") return node;
+      const obj = node;
+      if (Object.prototype.hasOwnProperty.call(obj, "$value")) {
+        const a = obj.$asset;
+        if (a && typeof a.kind === "string" && typeof a.ref === "string") {
+          this._assets.set(`${locale}/${ns}/${path.join(sep)}`, {
+            kind: a.kind,
+            ref: a.ref
+          });
+        }
+        return obj.$value;
+      }
+      const out = {};
+      for (const [k, v] of Object.entries(obj)) {
+        out[k] = walk(v, [...path, k]);
+      }
+      return out;
+    };
+    return walk(tree, []);
+  }
+};
+
+// src/singleton.ts
+var _active = null;
+function _setActiveInstance(instance) {
+  _active = instance;
+}
+function _clearActiveInstance(instance) {
+  if (_active === instance) _active = null;
+}
+function getI18n() {
+  if (!_active) {
+    throw new Error(
+      "@sonenta/react-i18next: getI18n() was called before <SonentaProvider> mounted (no active i18n instance)."
+    );
+  }
+  return _active;
+}
+function getI18nSafe() {
+  return _active;
+}
+function t(key, optionsOrDefault, maybeOptions) {
+  if (_active) return _active.t(key, optionsOrDefault, maybeOptions);
+  const dv = typeof optionsOrDefault === "string" ? optionsOrDefault : optionsOrDefault?.defaultValue;
+  return typeof dv === "string" ? dv : key;
+}
+
+// src/surface.ts
+var DEFAULT_SURFACE_BREAKPOINTS = {
+  mobile: 640,
+  tablet: 1024
+};
+function surfaceForWidth(width, breakpoints = DEFAULT_SURFACE_BREAKPOINTS) {
+  if (width < breakpoints.mobile) return "mobile";
+  if (width < breakpoints.tablet) return "tablet";
+  return "desktop";
+}
+
+// src/provider.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var SonentaContext = createContext(null);
+function SonentaProvider({
+  children,
+  ...config
+}) {
+  const i18n = useMemo(() => new SonentaI18n(config), []);
+  useEffect(() => {
+    _setActiveInstance(i18n);
+    void i18n.start();
+    const teardowns = (config.plugins ?? []).map(
+      (p) => p.setup?.({
+        i18n,
+        config,
+        onLanguageChange: i18n.onLanguageChange
+      })
+    ).filter((t2) => typeof t2 === "function");
+    return () => {
+      teardowns.forEach((t2) => t2());
+      i18n.stop();
+      _clearActiveInstance(i18n);
+    };
+  }, [i18n]);
+  useEffect(() => {
+    if (!config.surface || !config.surfaceBreakpoints) return;
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function")
+      return;
+    const bp = config.surfaceBreakpoints === true ? DEFAULT_SURFACE_BREAKPOINTS : config.surfaceBreakpoints;
+    const sync = () => void i18n.setSurface(surfaceForWidth(window.innerWidth, bp));
+    sync();
+    const mqls = [bp.mobile, bp.tablet].map(
+      (px) => window.matchMedia(`(min-width: ${px}px)`)
+    );
+    mqls.forEach((mql) => mql.addEventListener("change", sync));
+    return () => mqls.forEach((mql) => mql.removeEventListener("change", sync));
+  }, [i18n]);
+  const value = useMemo(() => ({ i18n }), [i18n]);
+  return /* @__PURE__ */ jsxs(SonentaContext.Provider, { value, children: [
+    children,
+    (config.plugins ?? []).map(
+      (p) => p.render ? /* @__PURE__ */ jsx(Fragment, { children: p.render() }, p.name) : null
+    )
+  ] });
+}
+function useI18n() {
+  const ctx = useContext(SonentaContext);
+  if (!ctx) {
+    throw new Error("useTranslation/Trans must be used inside <SonentaProvider>");
+  }
+  return ctx.i18n;
+}
+function useI18nSnapshot() {
+  const i18n = useI18n();
+  return useSyncExternalStore(i18n.subscribe, i18n.getSnapshot, i18n.getSnapshot);
+}
+
+// src/hooks.ts
+import { useEffect as useEffect2, useMemo as useMemo2, useRef } from "react";
+function useTranslation(defaultNamespace) {
+  const i18n = useI18n();
+  const snapshot = useI18nSnapshot();
+  const renderedRef = useRef(/* @__PURE__ */ new Set());
+  renderedRef.current = /* @__PURE__ */ new Set();
+  const tokenRef = useRef(/* @__PURE__ */ Symbol("sonenta.t"));
+  const t2 = useMemo2(() => {
+    const fn = (key, optionsOrDefault, maybeOptions) => {
+      const fullKey = defaultNamespace && !key.includes(":") ? `${defaultNamespace}:${key}` : key;
+      renderedRef.current.add(
+        keyRegistry.encode(fullKey, i18n.defaultNamespace)
+      );
+      return i18n.t(fullKey, optionsOrDefault, maybeOptions);
+    };
+    return fn;
+  }, [i18n, defaultNamespace]);
+  useEffect2(() => {
+    keyRegistry._set(tokenRef.current, renderedRef.current);
+  });
+  useEffect2(() => {
+    const token = tokenRef.current;
+    return () => keyRegistry._delete(token);
+  }, []);
+  return { t: t2, i18n: snapshot };
+}
+
+// src/trans.tsx
+import { Children, cloneElement, isValidElement } from "react";
+import { Fragment as Fragment2, jsx as jsx2 } from "react/jsx-runtime";
+function Trans({
+  i18nKey,
+  defaults,
+  values,
+  components,
+  namespace
+}) {
+  const { t: t2 } = useTranslation(namespace);
+  const raw = t2(i18nKey, { ...values ?? {}, defaultValue: defaults ?? i18nKey });
+  if (!components || !components.length) return /* @__PURE__ */ jsx2(Fragment2, { children: raw });
+  return /* @__PURE__ */ jsx2(Fragment2, { children: splitOnComponents(raw, components) });
+}
+function splitOnComponents(text, components) {
+  const out = [];
+  const re = /<(\d+)>(.*?)<\/\1>/g;
+  let lastIndex = 0;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    if (m.index > lastIndex) out.push(text.slice(lastIndex, m.index));
+    const idx = Number(m[1]);
+    const inner = m[2];
+    const node = components[idx];
+    if (isValidElement(node)) {
+      out.push(
+        cloneElement(node, { key: `t-${m.index}` }, ...Children.toArray(inner ?? ""))
+      );
+    } else if (node !== void 0) {
+      out.push(node);
+    } else {
+      out.push(inner ?? "");
+    }
+    lastIndex = re.lastIndex;
+  }
+  if (lastIndex < text.length) out.push(text.slice(lastIndex));
+  return out;
+}
+export {
+  DEFAULT_SURFACE_BREAKPOINTS,
+  SonentaProvider,
+  Trans,
+  SonentaProvider as VerbumiaProvider,
+  defaultTransport,
+  getI18n,
+  getI18nSafe,
+  keyRegistry,
+  logTransport,
+  surfaceForWidth,
+  t,
+  useTranslation
+};
+//# sourceMappingURL=index.js.map