@kromatv/sdk 0.1.40-canary.0

package/types/core/src/server-origin.d.ts

@@ -0,0 +1,12 @@
+export interface ResolvedOrigin {
+    url: string;
+    secure: boolean;
+}
+/** Resolves which scheme a typed address actually speaks: an address without
+ * one is probed https first; an explicit scheme is honoured as typed. Null
+ * means nothing answered, which is not the same as insecure. */
+export declare function resolveServerOrigin(address: string, opts?: {
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    port?: number;
+}): Promise<ResolvedOrigin | null>;

package/types/core/src/slug.d.ts

@@ -0,0 +1,4 @@
+/** The URL segment a display name folds to: lowercased, accents dropped, every
+ * run of anything else turned into one `-`, with no leading or trailing one.
+ * Idempotent: a slug read back off a URL folds to itself. */
+export declare function slugify(raw: string): string;

package/types/core/src/subtitles.d.ts

@@ -0,0 +1,20 @@
+export declare function isTextSubtitle(codec: string): boolean;
+export interface Cue {
+    start: number;
+    end: number;
+    text: string;
+}
+/** Parses WebVTT into cues sorted by start time. */
+export declare function parseVtt(raw: string): Cue[];
+type CueHit = {
+    text: string;
+    index: number;
+};
+/** `hint` is the index this returned last time; passing it back keeps normal
+ *  playback O(1) amortised, and a seek re-syncs with a binary search. */
+export declare function activeCueText(cues: Cue[], t: number, hint: number): CueHit;
+import type { MessageKey } from './i18n';
+/** `stage` values come from the server's GenRegistry. */
+export declare function subtitleStageKey(stage: string): MessageKey;
+export declare function subtitleEtaTime(sec: number): string;
+export {};

package/types/i18n/src/announce.d.ts

@@ -0,0 +1,15 @@
+import type { Catalog } from './types';
+/** One locale's catalog, or a loader that fetches it when the locale is wanted. */
+export type CatalogOrLoader = Catalog | (() => Promise<Catalog>);
+/** A namespace's catalogs by locale, as the module that carries them hands
+ *  them over. */
+export type NamespaceCatalogs = Readonly<Record<string, CatalogOrLoader>>;
+export interface Announced {
+    readonly namespace: string;
+    readonly catalogs: NamespaceCatalogs;
+}
+/** Hand a namespace to whichever engine drains the queue, now or later. Called
+ *  by the module `@kroma/i18n/vite` generates per namespace. */
+export declare function announceCatalogs(namespace: string, catalogs: NamespaceCatalogs): void;
+/** Take every announcement made so far, and every one to come. */
+export declare function drainAnnouncements(next: (announced: Announced) => void): void;

package/types/i18n/src/catalog-types.d.ts

@@ -0,0 +1,7 @@
+import type { CatalogPath } from './layout';
+export interface CatalogTypesSource {
+    readonly files: readonly CatalogPath[];
+    /** The locale whose files type the keys: the complete one. */
+    readonly defaultLocale: string;
+}
+export declare function renderCatalogTypes({ files, defaultLocale }: CatalogTypesSource): string;

package/types/i18n/src/chain.d.ts

@@ -0,0 +1,22 @@
+import type { Catalog, PluralRule, TVars } from './types';
+/** The catalogs a lookup walks, most specific first. A scoped translator puts
+ *  the scope's own catalogs ahead of the base ones, and each locale is followed
+ *  by the default locale it falls back to. */
+export type Chain = readonly Catalog[];
+/** Render `key` against `chain`, or `undefined` when no catalog in it knows the
+ *  key. Plural variants are resolved inside the first catalog that answers, so
+ *  a locale can never take a variant from a language whose template it will not
+ *  also use. */
+export declare function translateChain(chain: Chain, locale: string, key: string, vars?: TVars, plural?: PluralRule): string | undefined;
+/** What a lookup found: the index in the chain that answered, `-1` when
+ *  nothing did, and the message it rendered. */
+export interface Resolved {
+    readonly at: number;
+    readonly text: string | undefined;
+}
+/** Render `key` and say which catalog it came from, in one walk. Pairs with
+ *  `CatalogStore.sources` to name the catalog that spoke, which is what the key
+ *  inspector reports. Kept apart from {@link translateChain} rather than
+ *  wrapping it: the plain path runs for every string the app draws and does not
+ *  allocate. */
+export declare function resolveInChain(chain: Chain, locale: string, key: string, vars?: TVars, plural?: PluralRule): Resolved;

package/types/i18n/src/define.d.ts

@@ -0,0 +1,39 @@
+import { type I18n, type I18nConfig } from './i18n';
+import type { Locale, Messages } from './registry';
+import type { Catalog, LocaleSet } from './types';
+export interface DefineI18nConfig extends Pick<I18nConfig<Record<string, Catalog>>, 'plural' | 'lazy'> {
+    /** One catalog per locale, keyed by code, holding what ships up front. The
+     *  default locale's names every language under `lang.<code>`, which is what
+     *  the locale set reads before any other message is needed. */
+    catalogs: Readonly<Record<string, Catalog>>;
+    defaultLocale: Locale;
+}
+type AppI18n = I18n<Locale, Messages>;
+export interface DefinedI18n extends LocaleSet<Locale> {
+    readonly i18n: AppI18n;
+    readonly translate: AppI18n['translate'];
+    readonly translator: AppI18n['translator'];
+    readonly addCatalogs: AppI18n['add'];
+}
+/**
+ * The app's one instance, typed by the registry rather than by what is passed
+ * in: with catalogs discovered from a folder, the values say `string` and the
+ * `@kroma/i18n/vite` plugin's declaration says which locales and keys exist.
+ *
+ * ```ts
+ * export const { i18n, translate, LOCALES, DEFAULT_LOCALE } = defineI18n({
+ *   catalogs, lazy, defaultLocale: 'fr',
+ * });
+ * ```
+ *
+ * The instance also takes every namespace a chunk announces on import (see
+ * `announceCatalogs`), so a screen's messages are on their way before it
+ * renders and `useT` can wait for them.
+ *
+ * There is no separate table of language names: a catalog names its own
+ * language under `lang.<code>` (`"lang.fr": "Français"` in `fr/lang.json`),
+ * which is the entry the picker renders anyway, so writing it twice is how the
+ * two drift apart.
+ */
+export declare function defineI18n(config: DefineI18nConfig): DefinedI18n;
+export {};

package/types/i18n/src/dev-overrides.d.ts

@@ -0,0 +1,39 @@
+import type { CatalogSource, TVars } from './types';
+/** One message, as the engine resolved it. `from` is the catalog that
+ *  answered, or `undefined` when none did, and `text` is what would have
+ *  rendered: the chain has already been walked, so an inspector only formats,
+ *  and one that merely watches hands `text` straight back. */
+export interface Rendered {
+    readonly key: string;
+    readonly from: CatalogSource | undefined;
+    readonly locale: string;
+    readonly text: string;
+    readonly vars: TVars | undefined;
+}
+/** Renders a message as something other than its text: the key it came from,
+ *  a mark an overlay reads, or the text itself for an inspector that only
+ *  watches. */
+export type KeyInspector = (rendered: Rendered) => string;
+/** What the app renders in: every locale it can answer, and the one it
+ *  resolved for itself before any override. */
+export interface AppLocales {
+    readonly codes: readonly string[];
+    readonly resolved: string;
+}
+export declare function activeKeyInspector(): KeyInspector | null;
+/** Route every message every instance renders through `next`, or `null` to
+ *  stop. Page-wide on purpose, through a record on `globalThis`: the dev tools
+ *  are one switch, and they reach an engine they were never handed - a module's
+ *  front end bundles its own. */
+export declare function installKeyInspector(next: KeyInspector | null): void;
+/** Say what the app renders in, so the tools can offer its locales without
+ *  being handed the app's own table. `null` when the last provider unmounts. */
+export declare function installAppLocales(next: AppLocales | null): void;
+export declare function activeAppLocales(): AppLocales | null;
+export declare function activeLocaleOverride(): string | null;
+/** Render every provider in `next` instead of the locale the app resolved, or
+ *  `null` to give it back. Nothing is persisted and no account preference
+ *  moves: this lasts as long as the page does. */
+export declare function installLocaleOverride(next: string | null): void;
+export declare function overridesRevision(): number;
+export declare function onOverridesChange(listener: () => void): () => void;

package/types/i18n/src/i18n.d.ts

@@ -0,0 +1,61 @@
+import type { NamespaceCatalogs } from './announce';
+import { type SCHEMA_KEY } from './store';
+import type { Catalog, Catalogs, PluralRule, TVars } from './types';
+/** A catalog's messages: everything but the `$schema` pointer. Distinct from
+ *  `Messages` in ./registry, which is the augmented map for the whole app. */
+export type CatalogMessages<C> = Omit<C, typeof SCHEMA_KEY>;
+/** Namespaces offered for fetching: by name, then by locale. */
+export type LazyCatalogs = Readonly<Record<string, NamespaceCatalogs>>;
+/** A translator bound to one scope: the scope's own keys are not knowable from
+ *  here, so any string is accepted while the base keys still autocomplete. */
+export type ScopedTranslate<K extends string> = (key: K | (string & {}), vars?: TVars) => string;
+export interface I18n<L extends string, M extends Catalog> {
+    readonly defaultLocale: L;
+    /** Every locale the base catalogs answer in, the default one first. */
+    locales(): readonly L[];
+    /** Render one message. Unknown keys render as the key itself, which is a
+     *  visible placeholder rather than an empty hole. */
+    translate(locale: L, key: keyof M & string, vars?: TVars): string;
+    /** A translator bound to a locale. Pass a scope to put that scope's added
+     *  catalogs ahead of the base ones. */
+    translator(locale: L): (key: keyof M & string, vars?: TVars) => string;
+    translator(locale: L, scope: string): ScopedTranslate<keyof M & string>;
+    /** Add a scope's catalogs at runtime, as a module being loaded would.
+     *  Returns a disposer; adding the same scope again replaces it. */
+    add(scope: string, catalogs: Catalogs<string>): () => void;
+    /** A namespace the running code needs, as the chunk carrying it says on
+     *  evaluation: a catalog given outright lands now, a loader is fetched for
+     *  every warmed locale. */
+    register(namespace: string, catalogs: NamespaceCatalogs): void;
+    /** Fetch every needed namespace in `locale`, now and as more are registered.
+     *  The provider calls it for the locale it renders. */
+    warm(locale: L): void;
+    /** What is still being fetched for `locale`, to suspend on; `null` when
+     *  everything needed has landed. */
+    pending(locale: L): Promise<void> | null;
+    /** A snapshot that changes whenever a scope is added or removed, or a
+     *  locale's fetches have all landed. */
+    version(): number;
+    subscribe(listener: () => void): () => void;
+}
+export interface I18nConfig<C extends Record<string, Record<string, string>>> {
+    catalogs: C;
+    defaultLocale: keyof C & string;
+    /** Override plural category selection. Only needed where `Intl.PluralRules`
+     *  is absent or disagrees with a peer implementation you have to match. */
+    plural?: PluralRule;
+    /** Namespaces not shipped in `catalogs`, fetched per locale when a key of
+     *  theirs misses. */
+    lazy?: LazyCatalogs;
+}
+/**
+ * Build a translator from JSON catalogs.
+ *
+ * `$t(key)` references inside the catalogs are expanded here, once, so
+ * translating stays a single interpolation pass. The message-key type comes
+ * from the default locale's catalog, which is therefore the one that has to be
+ * complete: every other locale falls back to it.
+ */
+export declare function createI18n<const C extends Record<string, Record<string, string>>, const D extends keyof C & string>(config: I18nConfig<C> & {
+    defaultLocale: D;
+}): I18n<keyof C & string, CatalogMessages<C[D]>>;

package/types/i18n/src/index.d.ts

@@ -0,0 +1,11 @@
+export { type DefinedI18n, type DefineI18nConfig, defineI18n } from './define';
+export { type AppLocales, activeAppLocales, installAppLocales, installKeyInspector, installLocaleOverride, type KeyInspector, onOverridesChange, type Rendered, } from './dev-overrides';
+export { createI18n, type I18n, type I18nConfig, type ScopedTranslate } from './i18n';
+export { hasToken, interpolate, tokensIn } from './interpolate';
+export { catalogsByLocale, namespaceOf, sourcesByNamespace } from './layout';
+export { createLocales, LABEL_NAMESPACE } from './locales';
+export { expandRefs, hasUnresolvedRef } from './nest';
+export { resolvePluralKey, selectCategory } from './plural';
+export type { Locale, MessageKey, Messages, Register, Translate } from './registry';
+export { SCHEMA_KEY } from './store';
+export type { Catalog, CatalogSource, Catalogs, LocaleSet, PluralCategory, PluralRule, TVars, } from './types';

package/types/i18n/src/interpolate.d.ts

@@ -0,0 +1,14 @@
+import type { TVars } from './types';
+/** Substitute `{name}` tokens from `vars`. Unknown tokens are kept verbatim.
+ *
+ *  One pass, deliberately: a substituted value that itself looks like a token
+ *  is never rescanned, so a variable carrying user text cannot reach back into
+ *  the catalog. The `kroma-i18n` crate pins the same guarantee. Reuse between
+ *  messages is a catalog concern, handled once at build by {@link expandRefs}. */
+export declare function interpolate(template: string, vars?: TVars): string;
+/** Whether `text` still names a `{token}`. After {@link interpolate} that means
+ *  a variable the caller never passed, since an unknown token is kept
+ *  verbatim. */
+export declare function hasToken(text: string): boolean;
+/** The `{token}` names `text` still carries. */
+export declare function tokensIn(text: string): string[];

package/types/i18n/src/layout.d.ts

@@ -0,0 +1,18 @@
+import type { Catalog } from './types';
+/** Where a catalog file sits in a folder-per-locale layout:
+ *  `./<locale>/<namespace>.json`. */
+export interface CatalogPath {
+    readonly locale: string;
+    readonly namespace: string;
+}
+export declare function parseCatalogPath(path: string): CatalogPath | null;
+/** Merge the files of a glob into one catalog per locale, as `defineI18n`
+ *  takes them. Keys are the glob's paths, values the parsed files. */
+export declare function catalogsByLocale(files: Readonly<Record<string, Catalog>>): Record<string, Catalog>;
+type Loader = () => Promise<Catalog>;
+/** The loaders of a glob regrouped by namespace, then by locale, as
+ *  `defineI18n` takes its `lazy` namespaces: each locale is fetched on its own. */
+export declare function sourcesByNamespace(loaders: Readonly<Record<string, Loader>>): Record<string, Record<string, Loader>>;
+/** The namespace a key belongs to: everything before its first dot. */
+export declare function namespaceOf(key: string): string;
+export {};

package/types/i18n/src/locales.d.ts

@@ -0,0 +1,12 @@
+import type { LocaleSet } from './types';
+/** The namespace holding each locale's name for itself, the one catalog an app
+ *  needs before anything renders. */
+export declare const LABEL_NAMESPACE = "lang";
+/** Where a locale's name for itself lives in its own catalog. One spelling,
+ *  because both the locale set and `defineI18n` read it. */
+export declare function labelKey<L extends string>(code: L): `lang.${L}`;
+/** The locales a product ships, knowable without loading a single message:
+ *  `createLocales({ fr: 'Français', en: 'English' }, 'fr')`. The value of each
+ *  entry is the endonym `normalizeLocale` accepts next to a BCP 47 tag, because
+ *  that is how the server stores an account's language. */
+export declare function createLocales<const N extends Record<string, string>, const D extends keyof N & string>(names: N, defaultLocale: D): LocaleSet<keyof N & string, D>;

package/types/i18n/src/namespaces.d.ts

@@ -0,0 +1,37 @@
+import type { NamespaceCatalogs } from './announce';
+import type { Catalog } from './types';
+/** Where a landed catalog goes, and how a view hears that a locale is whole. */
+export interface CatalogSink {
+    extend(locale: string, catalog: Catalog): void;
+    changed(): void;
+}
+/**
+ * Which namespaces exist, where each locale's catalog comes from, and which of
+ * them have landed. A namespace a chunk announced is `needed`: its catalog for
+ * every warmed locale is fetched at once. One only the folder glob offered is
+ * fetched when a key of it misses. A view is told once per locale, when the
+ * last fetch in flight for it lands, rather than once per namespace.
+ */
+export declare class Namespaces {
+    private readonly sink;
+    private readonly entries;
+    private readonly warmed;
+    private readonly inFlight;
+    private readonly pendingByLocale;
+    constructor(sink: CatalogSink, shipped: Readonly<Record<string, Catalog>>);
+    announce(namespace: string, catalogs: NamespaceCatalogs, needed: boolean): void;
+    /** From now on, fetch every needed namespace's catalog for `locale`. */
+    warm(locale: string): void;
+    /** Everything in flight for `locale`, as one promise a component can suspend
+     *  on, or `null` when nothing is. The same promise is handed back until it
+     *  settles, which is what `use()` needs to resume. */
+    pending(locale: string): Promise<void> | null;
+    /** A key nothing answered in `locale`: fetch its namespace for that locale,
+     *  unless a fetch already failed. */
+    missed(key: string, locale: string): void;
+    private ensure;
+    private landed;
+    private flying;
+    private settle;
+    private entry;
+}

package/types/i18n/src/nest.d.ts

@@ -0,0 +1,17 @@
+import type { Catalog } from './types';
+/** Whether a template still names a key, i.e. {@link expandRefs} could not
+ *  resolve it. A catalog that ships one of these has a typo or a cycle. */
+export declare function hasUnresolvedRef(template: string): boolean;
+/** Expand `$t(other.key)` references inside catalog values, once, so a term
+ *  written in one place reads the same everywhere it is quoted.
+ *
+ *  A reference resolves against its own locale first, then the default locale,
+ *  then the same two in `against`: the catalogs already built, for a part that
+ *  arrives later. One that names a missing key, or that closes a cycle, is left
+ *  standing as `$t(...)` rather than throwing: a catalog is data, and a bad
+ *  entry must not take the app down at import. Guard the shipped catalogs with
+ *  {@link hasUnresolvedRef} in a test instead.
+ *
+ *  Runs at construction, never per translation, which is what lets
+ *  interpolation stay a single pass. */
+export declare function expandRefs<C extends Record<string, Record<string, string>>>(catalogs: C, defaultLocale: keyof C & string, against?: Readonly<Record<string, Catalog | undefined>>): C;

package/types/i18n/src/plural.d.ts

@@ -0,0 +1,20 @@
+import type { Catalog, PluralCategory, PluralRule, TVars } from './types';
+/** The CLDR plural category `count` falls in for `locale`. Falls back to a
+ *  one/other split where `Intl.PluralRules` is missing, which is the older
+ *  television engines. Note that French puts 0 in `one` and English does not,
+ *  so a server rendering the same catalog has to agree with this. */
+export declare function selectCategory(locale: string, count: number, rule?: PluralRule): PluralCategory;
+/** The key `catalog` should be read at once the message's numeric variables
+ *  have chosen a plural variant, or `key` itself when it declares none.
+ *
+ *  Resolution is per catalog rather than across a fallback chain, so a locale
+ *  can never borrow another language's singular purely because that language
+ *  happens to declare one; the caller moves on to the next catalog only when
+ *  this one has no template at all.
+ *
+ *  `count` selects `key_one` / `key_other` / `key_zero`. Any other numeric
+ *  variable selects `key_<name>_one` and so on, which is how a message whose
+ *  quantity is not called "count" pluralises. Only one variable can select,
+ *  since one key names one template: `count` is tried first, then the rest in
+ *  declaration order. */
+export declare function resolvePluralKey(catalog: Catalog, locale: string, key: string, vars: TVars, rule?: PluralRule): string;

package/types/i18n/src/react/context.d.ts

@@ -0,0 +1,37 @@
+import type { I18n, ScopedTranslate } from '../i18n';
+import type { Locale, MessageKey, Translate } from '../registry';
+import type { Catalog } from '../types';
+/** What a provider hands down. `version` changes when a scope is added or a
+ *  dev switch moves; it is carried rather than derived because it is what
+ *  rebuilds `translator` beside it, and a memoiser that cannot see a value
+ *  being read will prune the dependency and serve a stale translator. The
+ *  provider watches the store once, on behalf of every consumer, rather than
+ *  each of them opening its own subscription. */
+export interface I18nValue {
+    i18n: I18n<string, Catalog>;
+    locale: Locale;
+    version: number;
+    translator: (scope?: string) => ScopedTranslate<MessageKey>;
+    setLocale: (locale: Locale) => void;
+}
+export declare const I18nContext: import("react").Context<I18nValue | null>;
+/**
+ * A translator for the active locale. Waits, behind the nearest Suspense
+ * boundary, for the catalogs the screen's chunk announced to land in that
+ * locale, so no key is painted.
+ *
+ * Pass a scope to read a runtime-added catalog first, which is how a module
+ * reads its own messages while still falling back to the app's. A catalog that
+ * arrives after first paint re-renders through the provider, so it does not
+ * leave its keys showing.
+ */
+export declare function useT(scope: string): ScopedTranslate<MessageKey>;
+export declare function useT(): Translate;
+/** A factory for scoped translators, for a view that renders rows belonging to
+ *  several scopes at once and so cannot call {@link useT} once per row. */
+export declare function useScopedT(): (scope: string) => ScopedTranslate<MessageKey>;
+export declare function useLocale(): Locale;
+/** A no-op unless the provider was given an `onLocaleChange`. */
+export declare function useSetLocale(): (locale: Locale) => void;
+/** The instance itself, for the caller that needs `add` when a module loads. */
+export declare function useI18n(): I18n<string, Catalog>;

package/types/i18n/src/react/index.d.ts

@@ -0,0 +1,2 @@
+export { I18nContext, type I18nValue, useI18n, useLocale, useScopedT, useSetLocale, useT, } from './context';
+export { I18nProvider, type I18nProviderProps } from './provider';

package/types/i18n/src/react/provider.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+import type { I18n } from '../i18n';
+import type { Locale } from '../registry';
+import type { Catalog } from '../types';
+export interface I18nProviderProps {
+    /** The instance built by `createI18n`. */
+    i18n: I18n<string, Catalog>;
+    /** Controlled: the app owns the resolved locale and `useSetLocale` asks for a
+     *  change through `onLocaleChange` rather than setting it here. */
+    locale: Locale;
+    onLocaleChange?: (locale: Locale) => void;
+    children: ReactNode;
+}
+export declare function I18nProvider({ i18n, locale, onLocaleChange, children, }: Readonly<I18nProviderProps>): import("react").JSX.Element;

package/types/i18n/src/registry.d.ts

@@ -0,0 +1,36 @@
+import type { TVars } from './types';
+/**
+ * The seam that makes this package typed without a generic at every call site.
+ *
+ * The `@kroma/i18n/vite` plugin augments it from the catalog folder, with the
+ * locales it found and every namespace's messages folded into one map:
+ *
+ * ```ts
+ * declare module '@kroma/i18n' {
+ *   interface Register {
+ *     locale: 'en' | 'fr';
+ *     messages: typeof navMessages & typeof playerMessages;
+ *   }
+ * }
+ * ```
+ *
+ * From then on {@link Locale}, {@link MessageKey} and {@link Translate} are the
+ * app's own everywhere they are imported. Left alone it stays empty and the
+ * types widen to `string`, so the package is usable before it is configured
+ * and a consumer that never augments it still compiles.
+ */
+export interface Register {
+}
+/** The locales the project registered, or `string` before it registers any. */
+export type Locale = Register extends {
+    locale: infer L extends string;
+} ? L : string;
+/** The message map the project registered, keyed by message key. */
+export type Messages = Register extends {
+    messages: infer M extends Record<string, string>;
+} ? M : Record<string, string>;
+/** Every key the default catalog declares, which is the catalog that has to be
+ *  complete because it is the one every other locale falls back to. */
+export type MessageKey = keyof Messages & string;
+/** A translation function bound to one locale. */
+export type Translate = (key: MessageKey, vars?: TVars) => string;

package/types/i18n/src/store.d.ts

@@ -0,0 +1,46 @@
+import type { Chain } from './chain';
+import type { CatalogSource, Catalogs } from './types';
+/** `$schema` points an editor at the catalog schema; it is not a message. */
+export declare const SCHEMA_KEY: '$schema';
+/** The catalogs an instance can currently reach: the ones it was built with,
+ *  plus whatever has been added since.
+ *
+ *  Added catalogs are scoped and layered rather than merged, because a module
+ *  loaded at runtime cannot be trusted not to reuse a key the app already
+ *  spells differently. A scope's own messages win for that scope and are
+ *  invisible everywhere else. */
+export declare class CatalogStore<L extends string> {
+    readonly defaultLocale: L;
+    private readonly base;
+    private readonly scopes;
+    private readonly chains;
+    private readonly origins;
+    private readonly listeners;
+    private revision;
+    constructor(catalogs: Catalogs<L>, defaultLocale: L);
+    /** The catalogs a lookup walks, most specific first.
+     *
+     *  Cached, because this is asked once per rendered string: the answer only
+     *  changes when a scope is added or removed, and building a fresh array per
+     *  translation is a measurable share of the cheapest path. */
+    chain(locale: string, scope?: string): Chain;
+    /** Where each catalog of {@link chain} came from, at the same indices. Kept
+     *  beside the chain rather than in it so that rendering a message never
+     *  walks provenance it does not read. */
+    sources(locale: string, scope?: string): readonly CatalogSource[];
+    private build;
+    /** Add a scope's catalogs, returning a disposer that removes them again.
+     *  Adding the same scope twice replaces it, so a module that reloads does not
+     *  leave its previous messages behind. */
+    add(scope: string, catalogs: Catalogs<string>): () => void;
+    /** Merge catalogs into the base ones, as a namespace loaded on demand does:
+     *  visible to every translator, scoped or not, and never removed. Quiet on
+     *  purpose: the caller says when a view should re-read, so a locale whose
+     *  namespaces land one by one is announced once. */
+    extend(catalogs: Catalogs<string>): void;
+    /** Bumped whenever a scope is added or removed or a locale's fetches have
+     *  all landed, so a UI can hold it as a snapshot and re-render then. */
+    version(): number;
+    subscribe(listener: () => void): () => void;
+    changed(): void;
+}

package/types/i18n/src/types.d.ts

@@ -0,0 +1,30 @@
+/** The variables a message interpolates. A numeric one can also select a
+ *  plural variant; see {@link PluralCategory}. */
+export type TVars = Record<string, string | number>;
+/** One locale's messages, key to template. */
+export type Catalog = Readonly<Record<string, string>>;
+/** Every locale's messages. A locale may be absent, in which case lookups for
+ *  it fall through to the default locale. */
+export type Catalogs<L extends string = string> = Readonly<Partial<Record<L, Catalog>>>;
+/** Where a catalog in a lookup came from: the scope that added it, or `null` for
+ *  the base catalogs the app was built with, and the locale it speaks. */
+export interface CatalogSource {
+    readonly scope: string | null;
+    readonly locale: string;
+}
+/** A CLDR plural category. Catalogs carry it as a key suffix (`key_one`). */
+export type PluralCategory = Intl.LDMLPluralRule;
+/** Picks the category a count falls in. Supply one only where
+ *  `Intl.PluralRules` is absent or wrong for a language you ship. */
+export type PluralRule = (locale: string, count: number) => PluralCategory;
+export interface LocaleSet<L extends string, D extends L = L> {
+    readonly detectLocale: (preferred?: string | null) => L;
+    readonly isLocale: (value: unknown) => value is L;
+    readonly normalizeLocale: (tag?: string | null) => L | null;
+    readonly DEFAULT_LOCALE: D;
+    readonly SUPPORTED_LOCALES: ReadonlySet<L>;
+    readonly LOCALES: ReadonlyArray<{
+        readonly code: L;
+        readonly labelKey: `lang.${L}`;
+    }>;
+}

package/types/module-sdk/src/admin/context.d.ts

@@ -0,0 +1,20 @@
+import type { KromaClient } from '@kroma/client';
+import type { User } from '@kroma/client/accounts';
+import { type ReactNode } from 'react';
+export interface AdminHostValue {
+    client: KromaClient;
+    user: User | null;
+    apiBase: string;
+    /** Open the host's "media details" dialog for a catalog item. A service the
+     *  shell owns and a module borrows: the dialog reads the core catalog, which
+     *  is not a module's to know, but a module page listing files has every
+     *  reason to offer it. Absent on a shell that has no such dialog. */
+    openMediaInfo?: (itemId: string, title: string) => void;
+}
+export declare function AdminHostProvider({ value, children, }: Readonly<{
+    value: AdminHostValue;
+    children: ReactNode;
+}>): import("react").JSX.Element;
+/** The host-provided client / user / apiBase. Throws if used outside the
+ *  provider (which the admin shell always mounts). */
+export declare function useAdminHost(): AdminHostValue;

package/types/module-sdk/src/admin/denied.d.ts

@@ -0,0 +1 @@
+export declare function Denied(): import("react").JSX.Element;

package/types/module-sdk/src/admin/engines.d.ts

@@ -0,0 +1,35 @@
+import type { EngineContribution, EngineField } from '@kroma/client/modules';
+/** A contribution the add-picker can offer: it names the instance an added row
+ * stores, and it has either a field form or a custom flow. */
+export type EngineChoice = EngineContribution & {
+    id: string;
+};
+/** The enabled contributors to `point` that expose an add-flow. A disabled
+ * module contributes nothing, so its add-flow disappears from the page. */
+export declare function useEnabledEngines(point: string): EngineChoice[];
+/** Whether each module is enabled, as a predicate. For a caller checking a
+ * VARIABLE number of modules, where one `useModuleEnabled` per id would be a
+ * hook in a loop. Unknown ids answer true, matching {@link useModuleEnabled}. */
+export declare function useModuleEnabledCheck(): (id: string) => boolean;
+/** Whether module `id` is enabled. Defaults to true while loading / when unknown,
+ * so nothing flickers off before the module list resolves. */
+export declare function useModuleEnabled(id: string): boolean;
+/** A controlled form over an engine's declared fields. Every label resolves
+ * through `t()`, so a field key like `field.url` localizes while a proper-noun
+ * engine label (`Transmission`) passes through unchanged. */
+export declare function FieldForm({ fields, values, onChange, }: Readonly<{
+    fields: EngineField[];
+    values: Record<string, string>;
+    onChange: (key: string, value: string) => void;
+}>): import("react").JSX.Element;
+export interface AddEngineOptions {
+    engines: EngineChoice[];
+    title: string;
+    onSubmit: (engineId: string, values: Record<string, string>) => Promise<void>;
+}
+/** Open the generic "add an engine" dialog: pick an engine, name it, fill its
+ * declared fields, submit. Resolves `true` on submit, `false` on dismiss - and
+ * immediately `false` when no <AddEngineHost/> is mounted. */
+export declare function addEngine(options: Readonly<AddEngineOptions>): Promise<boolean>;
+/** Mount once, near the admin root. Draws whatever `addEngine()` asks. */
+export declare function AddEngineHost(): import("react").JSX.Element | null;