@sonenta/react-i18next 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,540 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { i18n } from 'i18next';
+
+/**
+ * Surface variants (#911) — a second resolution dimension layered ON TOP of
+ * the locale fallback chain. A "surface" (`desktop` / `mobile` / `tablet`) is
+ * an additive overlay: the base bundle applies to every surface, and a sparse
+ * surface overlay overrides individual keys for that surface only.
+ *
+ * This module is the framework-neutral surface helpers; the engine
+ * (`SonentaI18n`) owns the overlay loading/compose, and the provider wires
+ * the reactive viewport listener (web) — see `provider.tsx`.
+ */
+type Surface = "desktop" | "mobile" | "tablet";
+/** Min-width (px) thresholds that map a viewport width to a surface. A width
+ *  `< mobile` → `mobile`; `< tablet` → `tablet`; otherwise `desktop`. Mirrors
+ *  the common mobile-first breakpoint ladder. */
+interface SurfaceBreakpoints {
+    /** Upper bound (exclusive) of the `mobile` surface, in px. Default 640. */
+    mobile: number;
+    /** Upper bound (exclusive) of the `tablet` surface, in px. Default 1024. */
+    tablet: number;
+}
+declare const DEFAULT_SURFACE_BREAKPOINTS: SurfaceBreakpoints;
+/**
+ * Map a viewport width (px) to a {@link Surface} using `breakpoints`
+ * (defaults to {@link DEFAULT_SURFACE_BREAKPOINTS}). Framework-neutral and
+ * pure — React Native callers can feed it `useWindowDimensions().width` and
+ * pass the result to `i18n.setSurface(...)`; the web provider uses it
+ * internally against `window.innerWidth`.
+ */
+declare function surfaceForWidth(width: number, breakpoints?: SurfaceBreakpoints): Surface;
+
+type Locale = string;
+type Namespace = string;
+/** An asset variant ref carried by an overlay key (#911 minimal v1):
+ *  `{ "$value": <str|pluralDict>, "$asset": { kind, ref } }`. The translated
+ *  `$value` resolves through `t()` as usual; `$asset` is exposed via
+ *  `i18n.asset(key, ns?)`. */
+interface AssetRef {
+    kind: string;
+    ref: string;
+}
+/**
+ * A language-catalog entry — the subset of the public `GET /v1/languages`
+ * catalog the SDK uses to expose text direction and endonyms. Regional
+ * variants (`is_variant`) inherit `rtl`/`script` from their `parent_code`.
+ */
+interface LanguageMeta {
+    /** BCP-47 code, e.g. `fr`, `fr-CA`, `zh-Hant`. */
+    code: Locale;
+    /** Endonym (name in its own language), e.g. `français (Canada)`. */
+    native_name?: string;
+    /** English name, e.g. `French (Canada)`. */
+    english_name?: string;
+    /** Right-to-left script. */
+    rtl?: boolean;
+    /** ISO 15924 script code, e.g. `Latn`, `Arab`, `Hans`. */
+    script?: string;
+    /** True for a regional/script variant (e.g. `fr-CA`, `zh-Hant`). */
+    is_variant?: boolean;
+    /** Base language of a variant, e.g. `fr-CA` → `fr`. */
+    parent_code?: Locale | null;
+    /** CLDR plural categories present for this language. */
+    plural_categories?: string[];
+}
+interface MissingKeyEvent {
+    key: string;
+    namespace: Namespace;
+    language_code: Locale;
+    /**
+     * Canonical source-language value the developer asked for, WHEN one is
+     * available: the explicit `defaultValue` from `t()` first, else the
+     * fallback-language bundle value. OMITTED (undefined) when neither exists —
+     * the SDK never sends the key name as a value (the key is already in `key`).
+     * The backend promotes only a non-null `source_value`.
+     */
+    source_value?: string;
+    sdk_meta?: Record<string, unknown>;
+}
+type MissingHandlerMode = "send" | "log" | "off";
+type Transport = (batch: MissingKeyEvent[]) => void | Promise<void>;
+interface SonentaConfig {
+    /** API key — format `vrb_live_<prefix>.<secret>` with `missing:write` scope. */
+    token: string;
+    /** Project UUID this provider is bound to. */
+    projectUuid: string;
+    /** Namespaces to preload on mount. Defaults to `['common']`. */
+    namespaces?: Namespace[];
+    /**
+     * react-i18next-style alias for the default namespace. Convenience for
+     * single-namespace apps: when `namespaces` is omitted, the SDK loads
+     * `[defaultNS]`. Ignored when `namespaces` is provided (use that — its
+     * first entry is the default namespace).
+     */
+    defaultNS?: Namespace;
+    /**
+     * How keys map to the bundle structure. `false` = **flat** (keys are looked
+     * up literally, so dotted keys like `"App Version 6.3.8"` work); a string =
+     * **nested**, split on that separator (default `"."`). Explicit value here is
+     * an override; when omitted, the SDK auto-detects the project's
+     * `key_style` / `key_separator` from the version metadata (#754).
+     */
+    keySeparator?: string | false;
+    /**
+     * Separator between namespace and key in `t("ns:key")`. Default `":"`.
+     * Set `false` (or `""`) to disable namespace parsing so keys may contain
+     * `":"`. i18next-parity companion to `keySeparator`.
+     */
+    nsSeparator?: string | false;
+    /**
+     * Embedded build-time snapshot of translation bundles, keyed
+     * `locale -> namespace -> i18next tree` (the same shape as the CDN JSON).
+     * Primed synchronously on construction so the FIRST render is instant and
+     * works OFFLINE (before the first CDN/runtime fetch); the provider then
+     * swaps in fresh data when it arrives, with no flash. A failed initial fetch
+     * (offline) keeps the snapshot as last-known-good. Generate it with the
+     * `verbumia snapshot` CLI, or manually (fetch the CDN JSON and import it).
+     */
+    initialBundles?: Record<Locale, Record<Namespace, Record<string, unknown>>>;
+    /** Initial locale (BCP-47). */
+    defaultLocale: Locale;
+    /**
+     * Fallback locale(s) used when a key is missing in the active locale.
+     * Accepts a single locale or an ordered chain. Regional variants also fall
+     * back to their base language automatically (e.g. `fr-CA → fr`), so the full
+     * lookup order for an active `fr-CA` is `fr-CA → fr → fallbackLng…` — the
+     * `fr-CA → fr → source` chain (native i18next semantics). The CDN already
+     * serves variants as merged bundles, so this is defense-in-depth.
+     */
+    fallbackLng?: Locale | Locale[];
+    /**
+     * Embedded language catalog (offline/SSR/React Native), same items as the
+     * public `GET /v1/languages`. Primed synchronously so `dir()` / `nativeName()`
+     * work before — or entirely without — the network fetch; a successful fetch
+     * augments it. Pairs well with {@link SonentaConfig.initialBundles}.
+     */
+    languageCatalog?: LanguageMeta[];
+    /**
+     * Skip the best-effort fetch of the public language catalog
+     * (`GET {apiBase}/v1/languages`, no auth, CDN-cached) that powers `dir()` /
+     * `nativeName()`. Set when you don't need direction/endonym metadata, or
+     * you supply {@link SonentaConfig.languageCatalog} yourself.
+     */
+    disableLanguageCatalog?: boolean;
+    /**
+     * Interpolation hooks forwarded to i18next. Currently exposes `format`, the
+     * value formatter i18next invokes for `{{value, format}}` placeholders — wire
+     * your own date/number formatter here (the SDK does NOT bundle one).
+     *
+     * Example (date-fns):
+     * ```ts
+     * import { format as formatDate } from "date-fns";
+     * interpolation: {
+     *   format: (v, f) =>
+     *     f === "long" && v instanceof Date ? formatDate(v, "PPPP") : String(v),
+     * }
+     * ```
+     * i18next always keeps `escapeValue: false` (React escapes for us); only
+     * `format` is configurable here.
+     */
+    interpolation?: {
+        /**
+         * Called by i18next for each `{{value, format}}` placeholder. `value` is the
+         * interpolation variable, `format` the token after the comma (e.g. `"long"`,
+         * `"number"`), `lng` the active language, `options` the full `t()` options.
+         * Return the rendered string.
+         */
+        format?: (value: unknown, format: string | undefined, lng: string | undefined, options: Record<string, unknown>) => string;
+    };
+    /** Override the API base. Defaults to `https://api.verbumia.dev`. */
+    apiBase?: string;
+    /** Override the CDN base. Defaults to `https://cdn.verbumia.ca`. */
+    cdnBase?: string;
+    /**
+     * Optional plugins that hook into THIS provider's tree/registry — e.g.
+     * `@sonenta/feedback`. Plugins do NOT introduce a second React
+     * context; the provider calls `setup({ i18n, config })` once on mount
+     * and renders each plugin's `render()` as an ISOLATED sibling leaf
+     * after `children`, so enabling a plugin never re-renders the host app.
+     */
+    plugins?: SonentaPlugin[];
+    /**
+     * Optional override for missing-key delivery (in-app inspector,
+     * Storybook, Cypress mocks). When set, replaces the default POST.
+     */
+    transport?: Transport;
+    /** `send` (default) | `log` | `off` */
+    missingHandler?: MissingHandlerMode;
+    /** Flush cadence for the missing-key batch. Default 5_000ms. */
+    flushIntervalMs?: number;
+    /** Max events per batch before forcing a flush. Default 50. */
+    flushBatchSize?: number;
+    /** Optional ring buffer cap for `i18n.missingEvents`. Default 200. */
+    missingEventsBufferSize?: number;
+    /**
+     * Project version slug used when fetching bundles (BCP-style slug, e.g.
+     * `main`, `v2`). Maps to the
+     * `/p/{projectUuid}/{version}/latest/{lang}/{ns}.json` CDN path layout.
+     * Defaults to `main`. Included in the SDK's bundle cache keys, so two
+     * providers configured with different `version` values keep separate
+     * bundle caches.
+     */
+    version?: string;
+    /**
+     * @deprecated Use {@link SonentaConfig.version} instead. Kept as a
+     * back-compat alias of `version`; if both are set, `version` wins.
+     */
+    versionSlug?: string;
+    /**
+     * Surface variant (#911) — a second resolution dimension layered over the
+     * locale chain: `t()` returns the surface-specific value when an overlay
+     * provides one, else the base. Set the INITIAL surface here; it also
+     * becomes reactive when {@link SonentaConfig.surfaceBreakpoints} is set
+     * (the provider listens to the viewport on web). Omit to disable surface
+     * resolution entirely (base bundles only — fully back-compatible).
+     */
+    surface?: Surface;
+    /**
+     * Enable reactive surface detection from the viewport width (web): the
+     * provider maps `window.innerWidth` → surface via these min-width
+     * thresholds and calls `setSurface` on resize. Pass `true` for the default
+     * ladder (mobile <640 <tablet <1024 ≤desktop) or custom thresholds. On
+     * React Native (no `window`), set the initial {@link SonentaConfig.surface}
+     * and drive changes via `i18n.setSurface(surfaceForWidth(width))` from your
+     * own `useWindowDimensions`. Ignored when `surface` is unset.
+     */
+    surfaceBreakpoints?: SurfaceBreakpoints | boolean;
+    /**
+     * Deployment environment. Drives where the SDK fetches translations from:
+     *
+     * Maps to the customer's version model: a *promoted production*
+     * version is `"prod"`; any non-promoted (working) version is `"dev"`.
+     *
+     *   - "prod" (default): fetch from `cdnBase/p/<project>/<version>/latest/...`.
+     *     Cheap + cache-friendly. Freshness is the CDN `latest/` alias at
+     *     `max-age=60s` — a republish is picked up within ~a minute.
+     *   - "dev": fetch from `apiBase/v1/projects/<id>/translations/runtime`.
+     *     Live data, no CDN delay; the `token` (an API key with
+     *     env_type="dev" + populated ip/origin allowlist) is sent as
+     *     `Authorization: ApiKey ...`.
+     *
+     * Browser callers: `Origin` is automatically sent and validated against
+     * the key's origin_allowlist. Node clients (SSR, scripts) don't send
+     * Origin and must rely on `ip_allowlist`.
+     */
+    env?: "prod" | "dev";
+}
+/** Context handed to a plugin's `setup()` — the live i18n instance + the
+ * resolved provider config (apiBase, projectUuid, locale, …). A plugin
+ * reuses these instead of asking the customer to re-configure. */
+interface SonentaPluginContext {
+    i18n: I18nInstance;
+    config: SonentaConfig;
+    /**
+     * #806 — subscribe to RUNTIME language changes (alternative B in the
+     * SeedSower diagnosis: a stable, public plugin-context hook that does
+     * not couple plugins to the private `_i18next` field). Fires every
+     * time the active language changes via `setLocale()` /
+     * `changeLanguage()` / the drop-in `i18n.i18next.changeLanguage()`
+     * path. The handler receives the NEW language (BCP-47). The returned
+     * function unsubscribes — plugins MUST call it from their `setup()`
+     * teardown, otherwise the subscription survives the host's provider
+     * unmount.
+     *
+     * ADDITIVE: existing plugins that ignore the field keep working; the
+     * provider supplies it on every mount from 1.0.5 onwards. The shape
+     * mirrors a standard React-style `subscribe → unsubscribe` so other
+     * framework ports of the SDK (Vue, Svelte) can implement the same
+     * contract.
+     */
+    onLanguageChange(cb: (lng: Locale) => void): () => void;
+}
+/** A provider plugin. `setup` runs once on mount (optional teardown via
+ * the returned fn). `render` returns an isolated sibling node the
+ * provider mounts after `children` — its state never re-renders the app. */
+interface SonentaPlugin {
+    name: string;
+    setup?: (ctx: SonentaPluginContext) => void | (() => void);
+    render?: () => ReactNode;
+}
+interface I18nInstance {
+    /** True once the initial namespace bundles loaded for the active locale. */
+    ready: boolean;
+    locale: Locale;
+    /** Alias of `locale` for react-i18next compatibility. */
+    language: Locale;
+    setLocale: (l: Locale) => Promise<void>;
+    /**
+     * Alias of `setLocale` for react-i18next compatibility. Resolves once the
+     * new locale's namespace bundles have loaded.
+     */
+    changeLanguage: (l: Locale) => Promise<void>;
+    /**
+     * Translate a key. Exposed here mainly for out-of-React use via
+     * `getI18n()`; inside components prefer the `t` returned by
+     * `useTranslation()` (it also feeds the on-screen key registry).
+     */
+    t: TranslationFunction;
+    /** Recently captured missing-key events (most recent first). */
+    missingEvents: MissingKeyEvent[];
+    /** Force-flush the missing-key batch now. */
+    flushMissing: () => Promise<void>;
+    /**
+     * Bust-refetch already-loaded bundles and re-render. Without `opts`, all
+     * loaded `(locale, ns)` bundles are refreshed; pass `locale`/`namespace`
+     * to narrow. Used by `@sonenta/realtime` on a `translations_published`
+     * push and for manual refresh.
+     */
+    reload: (opts?: {
+        locale?: Locale;
+        namespace?: Namespace;
+    }) => Promise<void>;
+    /**
+     * Force every `useTranslation` consumer to re-render WITHOUT refetching —
+     * re-resolves `t()` against the CURRENT resources (both this SDK's hooks and
+     * react-i18next-native consumers on the exposed instance). For plugins that
+     * mutate i18next resources directly — e.g. `@sonenta/in-context` applies a
+     * live edit via `i18next.addResource` — and need the snapshot to repaint in
+     * place. Unlike {@link reload}, does NO fetch, so the override is not
+     * clobbered. Additive in 1.0.6.
+     */
+    refresh: () => void;
+    /**
+     * Active surface variant (#911), or `undefined` when surface resolution is
+     * off. `t()` resolves surface-overlay values on top of the base bundle.
+     */
+    surface: Surface | undefined;
+    /**
+     * Switch the active surface and recompose the loaded bundles (base ⊕ the
+     * new surface's sparse overlay), then re-render. Pass `undefined` to drop
+     * back to base-only. Loads each loaded namespace's `{ns}.{surface}.json`
+     * overlay on demand. The provider calls this from its viewport listener
+     * when `surfaceBreakpoints` is set; call it yourself on React Native.
+     */
+    setSurface: (surface: Surface | undefined) => Promise<void>;
+    /**
+     * The asset variant ref for a key under the ACTIVE locale+surface (#911
+     * minimal v1), or `undefined` when the resolved key carries no `$asset`.
+     * `t(key)` still returns the key's `$value`; this exposes the companion
+     * asset (e.g. an icon/image ref) for the host to render.
+     */
+    asset: (key: string, namespace?: Namespace) => AssetRef | undefined;
+    /**
+     * Text direction of a locale (defaults to the active locale) — i18next
+     * parity. Sourced from the language catalog's `rtl` (variant → base
+     * inheritance); falls back to a built-in RTL-language list when the catalog
+     * is not loaded. Apply to `<html dir>` or a container's `dir` attribute.
+     */
+    dir: (lng?: Locale) => "ltr" | "rtl";
+    /**
+     * Endonym (native name) of a locale from the catalog — the fallback for
+     * runtimes WITHOUT `Intl.DisplayNames` (React Native/Hermes, SSR). Returns
+     * `undefined` when the catalog has no entry. For UI-localized names prefer
+     * `Intl.DisplayNames(uiLocale, { type: "language" }).of(code)`; use this
+     * when that API is unavailable.
+     */
+    nativeName: (lng?: Locale) => string | undefined;
+    /**
+     * Full language-catalog entry for a locale (script, plural categories,
+     * parent, …), defaulting to the active locale; `undefined` if unknown.
+     */
+    languageMeta: (lng?: Locale) => LanguageMeta | undefined;
+    /**
+     * The underlying real `i18next` instance powering this SDK (thin-wrapper,
+     * #805). Exposed for react-i18next DROP-IN: pass it to react-i18next's own
+     * `<Trans i18n={…}>` or `useTranslation(ns, { i18n })` for rich JSX, or call
+     * any i18next API directly. Present on instances created by this SDK.
+     */
+    i18next?: i18n;
+}
+type TranslationOptions = Record<string, unknown> & {
+    defaultValue?: string;
+};
+interface TranslationFunction {
+    /**
+     * react-i18next-style positional fallback: `t('key', 'Default text')`,
+     * optionally with interpolation/options as a 3rd argument:
+     * `t('key', 'Hi {{name}}', { name })`.
+     */
+    (key: string, defaultValue: string, options?: TranslationOptions): string;
+    /** Native form: `t('key', { defaultValue, ...interpolation })`. */
+    (key: string, options?: TranslationOptions): string;
+}
+
+interface SonentaProviderProps extends SonentaConfig {
+    children: ReactNode;
+}
+declare function SonentaProvider({ children, ...config }: SonentaProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseTranslationResult {
+    t: TranslationFunction;
+    i18n: I18nInstance;
+}
+/** React hook — returns `{ t, i18n }`. Optional `defaultNamespace` lets you
+ *  drop the `ns:` prefix on every call.
+ *
+ *  Every key this hook resolves during a render is recorded into the
+ *  on-screen key registry (so a mounted `@sonenta/feedback` widget lists
+ *  only the strings rendered on the current view — spec ltm 373). The
+ *  contribution is keyed to THIS hook instance and dropped on unmount, so
+ *  navigating away removes its keys automatically. */
+declare function useTranslation(defaultNamespace?: string): UseTranslationResult;
+
+interface TransProps {
+    /** The translation key (optionally `ns:key`). */
+    i18nKey: string;
+    /** Default value if the key is missing — used as the fallback string. */
+    defaults?: string;
+    /** Variables interpolated into `{{var}}` placeholders. */
+    values?: Record<string, unknown>;
+    /** JSX components mapped by 0-based numeric index — `<0>bold</0>` etc. */
+    components?: ReactNode[];
+    /** Optional namespace shortcut. */
+    namespace?: string;
+}
+/** Bare-bones Trans component: resolves the key, interpolates values, and
+ *  swaps `<0>...</0>` placeholders into the supplied React components.
+ *  Keeps the surface minimal — full Trans semantics (nested keys, plural
+ *  trees, gender) land in V1.1. */
+declare function Trans({ i18nKey, defaults, values, components, namespace, }: TransProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Access the active i18n instance OUTSIDE React components — the
+ * react-i18next-style standalone singleton (e.g. for `t()`/`changeLanguage()`
+ * in plain modules, stores, or helpers).
+ *
+ * Returns the instance created by the mounted `<SonentaProvider>`; throws a
+ * clear error if no provider is mounted yet. Assumes a single app-wide
+ * provider (the common case); with multiple concurrent providers it returns
+ * the most recently mounted one.
+ */
+declare function getI18n(): I18nInstance;
+/**
+ * SAFE variant of {@link getI18n} (#805): returns the active i18n instance, or
+ * `null` when no provider is mounted yet — it does NOT throw. Use at module
+ * load / in plain helpers where a provider may not be mounted.
+ */
+declare function getI18nSafe(): I18nInstance | null;
+/**
+ * SAFE out-of-React translate (#805). Resolves against the active i18n instance
+ * when a provider is mounted; otherwise returns `options.defaultValue` (when a
+ * string) or the `key` — it NEVER throws. This makes module-load-time / helper
+ * `t()` calls safe before mount (the throwing {@link getI18n} would break them).
+ * Accepts both shapes: `t('k', { defaultValue })` and `t('k', 'Default', opts?)`.
+ */
+declare function t(key: string, optionsOrDefault?: (Record<string, unknown> & {
+    defaultValue?: string;
+    count?: number;
+}) | string, maybeOptions?: Record<string, unknown> & {
+    defaultValue?: string;
+    count?: number;
+}): string;
+
+/** Default transport: POST to `${apiBase}/v1/missing` with the API key. */
+declare function defaultTransport(opts: {
+    apiBase: string;
+    token: string;
+    projectUuid: string;
+}): Transport;
+/** Logs each event to console.warn — handy for dev. */
+declare const logTransport: Transport;
+
+/**
+ * On-screen key registry — the PRODUCER side of the tiny cross-package
+ * contract that `@sonenta/feedback` consumes via
+ * `globalThis.__verbumia_key_registry__` (see `@sonenta/feedback`'s
+ * `core/keys.ts`).
+ *
+ * Why this exists: the feedback widget must list only the translation
+ * strings RENDERED on the current screen (spec ltm 373) — NOT every
+ * project string. The widget can't know what's on screen; the i18n SDK
+ * does, because it resolves the keys. The registry exposes a minimal
+ * global with TWO producer paths feeding it:
+ *
+ *   1. HOOK-LEVEL — our own `useTranslation` / `Trans` push their
+ *      per-render key set via `_set(token, set)`. Mount-tracking handles
+ *      navigation: when a component unmounts, its keys drop out of the
+ *      union automatically.
+ *   2. INSTANCE-LEVEL — SonentaI18n wraps `i18next.t` so EVERY resolved
+ *      key (including those resolved through react-i18next's NATIVE
+ *      `useTranslation` / `<Trans>` bound to the exposed i18next, or
+ *      through a direct `i18n.t()` call) feeds `_track(token, id)`. This
+ *      makes the registry "instance-level producer", per #806 SeedSower
+ *      diagnosis: a 1.0.2 thin-wrapper drop-in lets host apps keep their
+ *      `from 'react-i18next'` imports, so the hook-level producer alone
+ *      misses 100% of those keys. Without this, the widget shows "no
+ *      strings on this view" even when the view is full of text.
+ *
+ * `snapshot()` is the UNION of both, deduped. The instance-level
+ * contribution accumulates for the i18n instance's lifetime (no per-
+ * component unmount signal), which is by-design: a stale superset is
+ * strictly better than a false empty.
+ *
+ * The published shape is intentionally tiny so any framework port of the
+ * i18n SDK can implement the same global without depending on feedback:
+ *
+ *   globalThis.__verbumia_key_registry__ = {
+ *     snapshot(): { namespace: string; key: string }[];
+ *     isPopulated(): boolean;
+ *     reset(): void;
+ *   }
+ */
+interface DeclaredKey {
+    namespace: string;
+    key: string;
+}
+declare class KeyRegistry {
+    private _instances;
+    private _providers;
+    /** Replace an instance's contributed key set (per-render hook producer). */
+    _set(token: symbol, keys: Set<string>): void;
+    /** 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: symbol, id: string): void;
+    /** Drop an instance entirely (called on hook unmount or i18n stop). */
+    _delete(token: symbol): void;
+    /** Keys rendered by currently-mounted consumers. Stable insertion order. */
+    snapshot(): DeclaredKey[];
+    /** 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(): boolean;
+    /** Escape hatch (router integrations / tests). Mount-tracking already
+     *  handles navigation, so this is rarely needed. */
+    reset(): void;
+    /** Encode a resolved key into the internal id used by `_set`. */
+    encode(fullKey: string, defaultNamespace: string): string;
+    /** Provider mounted — publish the global (idempotent, ref-counted). */
+    attach(): void;
+    /** Provider unmounted — unpublish when the last one goes away. */
+    detach(): void;
+}
+/** Process-wide singleton — there is exactly one on-screen registry. */
+declare const keyRegistry: KeyRegistry;
+
+export { type AssetRef, DEFAULT_SURFACE_BREAKPOINTS, type DeclaredKey, type I18nInstance, type LanguageMeta, type Locale, type MissingHandlerMode, type MissingKeyEvent, type Namespace, type SonentaConfig, type SonentaPlugin, type SonentaPluginContext, SonentaProvider, type Surface, type SurfaceBreakpoints, Trans, type TranslationFunction, type TranslationOptions, type Transport, type SonentaConfig as VerbumiaConfig, type SonentaPlugin as VerbumiaPlugin, type SonentaPluginContext as VerbumiaPluginContext, SonentaProvider as VerbumiaProvider, defaultTransport, getI18n, getI18nSafe, keyRegistry, logTransport, surfaceForWidth, t, useTranslation };