@secundus-studio/stift-generator 0.0.0-stage → 0.4.31

package/dist/index.d.ts

@@ -0,0 +1,1149 @@
+import { LocaleTag, UnitCategory, RegisteredLocale, LoadingStrategy, NamespaceId, UrlDetectionConfig, CookiePersistenceConfig, StateConfig, MessageKey, PackSecurityTier as PackSecurityTier$1, PackEncoding as PackEncoding$1, PackCompression as PackCompression$1, PackCatalog, LocaleShard } from '@secundus-studio/stift-core';
+export { IcuNode, IcuOption, ParseResult, collectFunctions, parseMessage } from '@secundus-studio/stift-core';
+import { z } from 'zod';
+
+/**
+ * Project config types (docs/05-config.md + docs/02-schemas.ts §9).
+ *
+ * Moved into `@secundus-studio/stift-generator` rather than `@secundus-studio/stift-core/config` (the
+ * path doc 05 shows): the config file is loaded by build tooling and never
+ * touches the runtime, and keeping it out of core avoids pulling the build
+ * surface / a Zod dep into the headless runtime. `LocaleTag` is re-exported
+ * from core so config authoring shares the branded type.
+ */
+
+/** `'any'` = accept any engine-supported value; a list narrows the generated `Register` union. */
+type NumberingSystemConfig = 'any' | readonly string[];
+/** `'any'` = accept any engine-supported value; a list narrows the generated `Register` union. */
+type CurrencyConfig = 'any' | readonly string[];
+/**
+ * Per-category unit declaration (docs/17-units.md). `supportedValues` sets the
+ * category's allowed units (omitted or `'all'` = the full canonical catalog);
+ * `defaults` carries the per-locale default units in the same shape as context
+ * params (docs/16): the required `all` key is the catch-all, and locale keys
+ * are overrides that outrank it via the locale hierarchy (exact tag → stripped
+ * subtags → `all`). An unsupported locale key is a *runtime* error via
+ * `unitsSchema`. A global override via `stift.setUnit` outranks everything.
+ *
+ * Nesting per-locale defaults (never top-level keys) is what lets the
+ * `supportedValues` reserved key coexist with a `Partial<Record<RegisteredLocale, string>>`
+ * — under an unaugmented `Register.locale` (no generated `stift.gen.d.ts`)
+ * that mapped type collapses to a broad index signature whose `string` value
+ * conflicts with the `readonly string[]` of `supportedValues`.
+ */
+type UnitCategoryConfig = {
+    /** The category's allowed units. */
+    supportedValues: 'all' | readonly string[];
+    /** Per-locale default units. `all` is the required catch-all; remaining
+     *  keys are per-locale overrides, restricted to the generated
+     *  `Register.locale` union so an unsupported locale is a type error at the
+     *  config file. */
+    defaults: {
+        all: string;
+    } & Partial<Record<RegisteredLocale, string>>;
+    /** Persist a `setUnit` override to the state backend (default `true`).
+     *  `false` keeps the override in memory only — use it for session-scoped
+     *  or backend-authoritative values. */
+    persist?: boolean;
+};
+/** Units config. `'all'` opens every category with its canonical default;
+ *  a partial object leaves the omitted categories open the same way. */
+type UnitsConfig = 'all' | Partial<Record<UnitCategory, UnitCategoryConfig>>;
+/**
+ * Pack serialization encoding.
+ *
+ * - `'msgpack'` — MessagePack binary (default). Compact, fast, not
+ *   human-readable. Emitted as `.dat`.
+ * - `'cbor'` — CBOR binary. Same role, different size/speed tradeoff.
+ *   Emitted as `.dat`.
+ * - `'json'` — Plain readable JSON bytes. Emitted as `.json`, fetched and
+ *   parsed as JSON at runtime — no codec, decompression, or key. Only valid
+ *   with `tier: 'none'` + `compression: 'none'`.
+ */
+type PackEncoding = 'msgpack' | 'cbor' | 'json';
+/**
+ * Pack compression (applied after serialization, before encryption).
+ *
+ * - `'none'` — Skip compression. Required with `encoding: 'json'`.
+ * - `'gzip'` — Default. `node:zlib` at build time, platform
+ *   `DecompressionStream` in the browser.
+ * - `'brotli'` — Smaller than gzip; browser decodes via `brotli-wasm`
+ *   (lazy import, so gzip users never ship it).
+ */
+type PackCompression = 'none' | 'gzip' | 'brotli';
+/**
+ * Pack security tier (docs/03-architecture.md §4).
+ *
+ * - `'none'` — No obfuscation or encryption. Pair with `encoding: 'json'` +
+ *   `compression: 'none'` for plain `.json` packs; with a binary encoding it
+ *   still emits a `.dat` container, just with tier byte `0`.
+ * - `'obfuscated'` — Default for prod. Binary codec + compression: defeats
+ *   casual network-tab scraping, naive JSON scrapers, accidental leakage of
+ *   unreleased strings — not a motivated attacker (public spec).
+ * - `'encrypted-static'` — + AES-GCM with a build-time key (`staticKey` /
+ *   `STIFT_STATIC_KEY`, also baked into the client bundle — weak by design).
+ * - `'encrypted-session'` — + AES-GCM with a per-session key from the app's
+ *   authenticated endpoint (`getSessionKey`). Real access control for
+ *   entitlement-gated locales.
+ */
+type PackSecurityTier = 'none' | 'obfuscated' | 'encrypted-static' | 'encrypted-session';
+/**
+ * Per-locale defaults for a declared context param (docs/16). Always the
+ * object form: the reserved `all` key is the guaranteed catch-all fallback
+ * (required — a value can never be undefined), and locale keys are restricted
+ * to the generated `Register.locale` union, so an unsupported locale is a
+ * type error at the config file. Resolution walks the locale hierarchy
+ * (exact tag → stripped subtags → `all`).
+ */
+type ParamDefaults = {
+    all: string;
+} & Partial<Record<RegisteredLocale, string>>;
+interface ContextParamConfig {
+    /**
+     * Declared context param name (e.g. `gender`, `politeness`). Declared params
+     * are context-supplied and *optional* at call sites (docs/16 §Design).
+     */
+    name: string;
+    /** Canonical category set — the type union emitted for this param
+     *  everywhere it is used, and the set `defaults`/`setParam` values validate
+     *  against. */
+    values: readonly string[];
+    /** Per-locale defaults. Every value must be a member of `values`; the `all`
+     *  key is required and serves as the fallback when no locale-specific entry
+     *  (or a parent locale's entry) matches. */
+    defaults: ParamDefaults;
+    /** Persist a `setParam` override to the state backend (default `true`).
+     *  `false` keeps the override in memory only — use it for session-scoped
+     *  or backend-authoritative values (e.g. a plan/tenant the backend owns). */
+    persist?: boolean;
+}
+interface ParamsConfig {
+    /** Declared context params (grammatical agreement, docs/16). */
+    context?: readonly ContextParamConfig[];
+}
+interface DetectionConfig {
+    /**
+     * Detector priority order (min 1 entry), most-trusted first — e.g.
+     * `['explicit', 'custom', 'navigator']`. `'custom'` is a reserved slot: the
+     * function itself is registered at runtime via
+     * `createStift({ detectors: { custom: [...] } })`, never here.
+     */
+    order: string[];
+    /**
+     * Per-detector timeout: local/sync detectors get a short leash, a DB-backed
+     * custom detector gets network slack. A flat number (e.g. `1500`) works when
+     * no split is needed; a function gets full dynamic control
+     * (e.g. skip the custom allowance when offline).
+     */
+    timeout?: number | (Partial<Record<string, number>> & {
+        default: number;
+    }) | ((detectorId: string) => number);
+    /** Locale-in-the-URL strategy for the built-in `url` detector
+     *  (docs/07-detection-and-middleware.md §4). */
+    url?: UrlDetectionConfig;
+    /**
+     * Opt-in client-side cookie persistence of the active locale
+     * (docs/07-detection-and-middleware.md §2): a discovery win
+     * (header/navigator/custom) or an explicit `setLocale` writes the locale to
+     * a `document.cookie`, and the `cookie` detector reads it back on later
+     * visits so the user's saved choice prevails over the first-visit guess.
+     */
+    cookie?: CookiePersistenceConfig;
+    /** Last-resort locale when every detector has no opinion. Usually the default locale. */
+    fallback?: LocaleTag;
+}
+interface NamespacesConfig {
+    /** Translation-files directory, relative to the project root (e.g. `'locales'`). */
+    dir: string;
+    /**
+     * How namespaces are discovered: `'convention'` walks
+     * `<dir>/<locale>/<namespace>.json` (nested dirs supported:
+     * `locales/en/common/systemStatus/notifications.json` → namespace
+     * `"common/systemStatus/notifications"`); `'manifest'` reads an explicit list.
+     */
+    discovery: 'convention' | 'manifest';
+    /** Namespaces seeded into `memory.preload` (pinned, LRU-exempt at runtime). */
+    default: readonly string[];
+}
+/**
+ * Pack compile pipeline config (docs/03-architecture.md §4).
+ * Absent entirely = `{ tier: 'obfuscated', encoding: 'msgpack', compression: 'gzip' }`.
+ */
+interface SecurityConfig {
+    /** What the tier buys is documented per value — default `'obfuscated'`. */
+    tier: PackSecurityTier;
+    /** Serializer — default `'msgpack'`. `'json'` emits plain `.json` packs (only with `tier: 'none'` + `compression: 'none'`). */
+    encoding: PackEncoding;
+    /** Post-serialization compression — default `'gzip'`. `'none'` is required with `encoding: 'json'`. */
+    compression: PackCompression;
+    /**
+     * AES-GCM key string for encrypted tiers (docs/03-architecture.md §4).
+     * `encrypted-static`: also baked into the client bundle by the generated
+     * runtime (weak by design). `encrypted-session`: used at build time only;
+     * the runtime gets the per-session key from the app's auth endpoint via
+     * `getSessionKey`. Prefer an env var (`STIFT_STATIC_KEY`) over a literal.
+     */
+    staticKey?: string;
+}
+interface MemoryConfig {
+    /** Max in-memory cached namespaces before eviction. Pinned + live-subscriber entries are exempt. */
+    maxCachedNamespaces?: number;
+    /** Eviction policy: `'lru'` (recency, default) or `'ttl'` (age via `ttlMs`). */
+    evictionPolicy?: 'lru' | 'ttl';
+    /** `'ttl'` only: entry lifetime in ms. */
+    ttlMs?: number;
+}
+interface StiftConfig {
+    /** Locales: `default` (schema locale, must be in `supported`) + every supported tag incl. registered dialects (e.g. `['en', 'ar', 'ar-SY-x-lattakia']`). Narrows `Register.locale` in typegen. */
+    locales: {
+        /** BCP 47 tag of the schema locale (e.g. `'en'`). New keys propagate from here to every locale. */
+        default: LocaleTag;
+        /** Every tag with translations + registered dialects. Each scaffolds/completes a `locales/<tag>/` dir. */
+        supported: readonly LocaleTag[];
+    };
+    /** `'any'` or an explicit list (validated via `Intl.supportedValuesOf`).
+     *  Narrows `Register.numberingSystems` for the format call-sites.
+     *  Optional — absent behaves exactly like `'any'`. */
+    numberingSystems?: NumberingSystemConfig;
+    /** Default 'any'. A literal list drives the generated `Register.currencies`
+     *  union used by `@secundus-studio/stift-format`'s typed currency formatting. */
+    currencies?: CurrencyConfig;
+    /** Units config (docs/17-units.md). A per-category declaration restricts
+     *  the category's allowed units + per-locale defaults; `'all'` (or omitting
+     *  a category) opens it with the canonical default. Drives the generated
+     *  `Register.units` unions and the runtime's unit defaults. */
+    units?: UnitsConfig;
+    /** Which files get watched/compiled — feeds the compiler and the dev-mode loader. */
+    namespaces: NamespacesConfig;
+    /** ICU message format flavor the packs compile with. Only `'icu-mf1'` is
+     *  supported — `'icu-mf2'` names a future formatter engine and is rejected
+     *  at config load, so selecting it fails fast instead of silently building
+     *  MF1 packs. Selects the runtime `FormatterEngine`. */
+    messageFormat: 'icu-mf1';
+    /** Grammatical-agreement declarations (docs/16). Declared params are optional at call sites; undeclared params are always required. */
+    params?: ParamsConfig;
+    /** Pack encoding/compression/encryption. Absent = `{ tier: 'obfuscated', encoding: 'msgpack', compression: 'gzip' }`. */
+    security?: SecurityConfig;
+    /** In-memory cache bounds + eviction policy for `PackManager`. */
+    memory?: MemoryConfig;
+    /** Namespace fetch policy (docs/01-feature-spec.md §4.16). Default:
+     *  'lazy-per-namespace'. SPA/PWA projects should generally set
+     *  'critical-then-full-background' or 'boot-all'. */
+    loadingStrategy?: LoadingStrategy;
+    /** 'boot-all' only: namespaces excluded from the boot load. Excluded
+     *  namespaces fall back to 'critical-then-full-background' individually. */
+    bootExclude?: readonly NamespaceId[];
+    /** Default detector order/timeouts/URL strategy/cookie persistence. Custom detector *functions* still come from `createStift`. */
+    detection?: DetectionConfig;
+    /**
+     * Persisted user state (docs/05-config.md): key prefix + storage backend for
+     * the active locale, context-param overrides, and unit overrides. Entirely
+     * optional — the defaults are `{ prefix: '__stift_', storage: 'webStorage' }`
+     * (e.g. `__stift_locale`, `__stift_gender`). `createStift({ state })` can
+     * override at runtime.
+     */
+    state?: StateConfig;
+}
+/** Identity helper for editor autocomplete while authoring the config. */
+declare function defineConfig(config: StiftConfig): StiftConfig;
+
+/** One discovered namespace file with its home locale + namespace id. */
+interface DiscoveredNamespace {
+    locale: string;
+    namespace: string;
+    /** Absolute path to `<locale>/<namespace>.json`. */
+    file: string;
+}
+interface DiscoveryResult {
+    /** `locale -> discovered namespaces` for every locale that has any. */
+    byLocale: Map<string, DiscoveredNamespace[]>;
+    /** Every namespace, flat, sorted for stable output. */
+    all: DiscoveredNamespace[];
+}
+/**
+ * Walk a `locales/` tree under `root`. Locale directories are the direct
+ * children of `locales/`; anything below a locale directory (recursively)
+ * that ends in `.json` becomes a namespace with the `/`-joined relative
+ * path, extension stripped.
+ */
+declare function discoverConvention(root: string, localesDir?: string): Promise<DiscoveryResult>;
+
+/**
+ * Type extraction (docs/08-grammatical-agreement.md:138-150).
+ *
+ * For each message key, parse every locale variant's ICU source and derive
+ * its param shape:
+ *   - `plural` / `selectordinal` argument → `number`
+ *   - `select` argument → the literal union of its case labels, collected
+ *     across every nesting depth
+ * Then union the resulting param shape across all locales' variants of that
+ * key, per docs/01-feature-spec.md §4.3's union-across-locales rule — a
+ * param required by any locale is required at every call site (declared
+ * context params are the exception: the message uses them but the app
+ * supplies them, so they're optional — docs/16).
+ *
+ * `params.context` (docs/02-schemas.ts §8) supplies canonical category sets
+ * for recurring params like `gender`: when a `select` argument's name is
+ * configured, its categories are reconciled against the canonical set and a
+ * warning is emitted on mismatch. This does not change the emitted type —
+ * it is a lint/consistency check.
+ */
+
+/** Fully-qualified context for one message source. */
+interface MessageSourceInput {
+    locale: string;
+    namespace: string;
+    key: MessageKey;
+    value: string;
+}
+type ParamType = {
+    kind: 'number';
+} | {
+    kind: 'select';
+    categories: string[];
+} | {
+    kind: 'primitive';
+};
+/**
+ * Raw per-locale derived shape for one key. `params` maps param name → the
+ * type derived from THIS locale's source only.
+ */
+interface KeyLocaleShape {
+    params: Record<string, ParamType>;
+}
+interface KeyShape {
+    /** Union across locales. Values are sorted for stable output. */
+    params: Record<string, ParamType>;
+    /** Which locales actually use each param (devtools data). */
+    paramLocales: Record<string, string[]>;
+}
+interface ExtractResult {
+    /** namespace → key → shape, for every key seen across any locale. */
+    byNamespace: Map<string, Map<MessageKey, KeyShape>>;
+    /** Consistency warnings from params.context reconciliation. */
+    warnings: string[];
+}
+/**
+ * Derive the param shape of a single message source by walking its full ICU
+ * AST (nested select/plural included).
+ */
+declare function deriveLocaleShape(source: string): Record<string, ParamType>;
+/**
+ * Union the per-key shapes across every locale that defines the key, and
+ * reconcile `params.context` canonical sets. Param requiredness is reflected
+ * in the emitted type (handled upstream in typegen).
+ */
+declare function extractShapes(sources: MessageSourceInput[], paramsConfig?: ParamsConfig): ExtractResult;
+
+/**
+ * Locale diffing (docs/06-build-plugin.md §3, docs/04-execution-plan.md
+ * Phase 2): which keys exist in a reference (default) locale but are missing
+ * in other locales. Reported so CI / `stift generate` can fail or warn on
+ * an untranslated namespace.
+ *
+ * Presence is computed from the raw per-locale sources (not the unioned
+ * `extract`, which spans every locale and would hide per-locale gaps).
+ */
+
+interface MissingDiffIssue {
+    namespace: string;
+    key: MessageKey;
+    /** The locale whose source file is missing this key. */
+    locale: string;
+}
+interface DiffResult {
+    /** Missing keys, one per (namespace, key, locale). */
+    missing: MissingDiffIssue[];
+}
+/**
+ * Diff the default locale against every base (non-dialect) locale. A key is
+ * "missing" for a base locale when the default defines it but that locale's
+ * own source has no value for it.
+ *
+ * Dialect/variant locales (e.g. `ar-SY`, `ar-SY-x-lattakia`) are intentionally
+ * excluded: they partially override their parent, and the runtime resolves
+ * gaps through the fallback chain (docs/07-detection / docs/02-schemas §9).
+ * Flagging them would turn legitimate partial overrides into false positives.
+ *
+ * `locales` is the full set of discovered on-disk locales; `defaultLocale` is
+ * the reference. Only locales with no parent in `locales` are treated as base
+ * anchors and compared. Missing = key present in default, absent in the base
+ * locale's own sources.
+ */
+declare function diffLocales(sources: MessageSourceInput[], locales: string[], defaultLocale: string): DiffResult;
+
+interface ScaffoldResult {
+    /** Directories that did not exist and were created. */
+    createdDirs: string[];
+}
+
+interface OrphanKeyIssue {
+    namespace: string;
+    key: string;
+    locale: string;
+}
+interface CompletionResult {
+    /** Completed flat sources — feed these to extract/diff/compile. */
+    sources: MessageSourceInput[];
+    /** Absolute paths rewritten this run. */
+    writtenFiles: string[];
+    /** Absolute paths created this run (subset of `writtenFiles`). */
+    createdFiles: string[];
+    orphanKeys: OrphanKeyIssue[];
+    /** Keys that inherited a value from an ancestor or the default this run. */
+    filledKeys: number;
+    /**
+     * Per-locale translation coverage (0-1): keys authored in the locale itself
+     * or inherited from a non-default registered ancestor, over the default
+     * locale's schema keys. Values inherited from the default (i.e. still shown
+     * in the default language at runtime) count as untranslated — this is the
+     * "78% translated" signal the catalog ships as `coverage`. The default
+     * locale itself reads 1.
+     */
+    authoredCoverage: Record<string, number>;
+    warnings: string[];
+}
+
+/** Security config consumed by the compiler (subset of StiftConfig). */
+interface CompileSecurityConfig {
+    tier: PackSecurityTier$1;
+    encoding: PackEncoding$1;
+    compression: PackCompression$1;
+    /** Required for both encrypted tiers — see docs/03-architecture.md §4. */
+    staticKey?: string;
+}
+/**
+ * Resolve the effective compiler security from a loaded config: `security`
+ * or the module defaults, with `STIFT_STATIC_KEY` as the static-key
+ * fallback for the encrypted tiers. Shared by `Generator.compileAsync` and
+ * the Vite plugin's incremental dev compile so both stay in lockstep.
+ */
+declare function resolveCompileSecurity(config: Pick<StiftConfig, 'security'>): CompileSecurityConfig;
+interface CompileNamespaceOptions {
+    security: CompileSecurityConfig;
+}
+/** One compiled namespace ready for emission. */
+interface CompiledNamespaceOutput {
+    locale: LocaleTag;
+    namespace: NamespaceId;
+    /** `/`-joined: `${locale}/${namespace}` — matches PersisterAdapter keys. */
+    persistKey: string;
+    bytes: Uint8Array;
+    byteLength: number;
+    contentHash: string;
+}
+/**
+ * One cached compiled namespace, for incremental dev compilation (the Vite
+ * plugin's serve loop reuses prior `.dat` bytes when a namespace's source
+ * hasn't changed — docs/06-build-plugin.md). `sourceHash` is a cheap hash of
+ * the normalized source (UTF-8 JSON bytes), distinct from `contentHash`
+ * (over the compiled bytes).
+ */
+interface CompiledNamespaceCacheEntry {
+    /** Hash over the namespace's normalized source JSON bytes. */
+    sourceHash: string;
+    bytes: Uint8Array;
+    byteLength: number;
+    contentHash: string;
+}
+/** `persistKey -> compiled entry`, the incremental dev compile cache. */
+type CompiledCache = Map<string, CompiledNamespaceCacheEntry>;
+/** One compiled locale shard ready for emission. */
+interface LocaleShardOutput {
+    locale: LocaleTag;
+    /** Parsed shard (mirrors `bytes` — kept so callers needn't re-parse). */
+    shard: LocaleShard;
+    /** Serialized shard bytes (minified JSON) — what gets emitted + hashed. */
+    bytes: Uint8Array;
+    byteLength: number;
+    /** sha256 over the shard bytes — the index's two-tier invalidation key. */
+    namespacesHash: string;
+}
+/** What compileAll returns: every compiled namespace + the catalog index + shards. */
+interface CompileAllResult {
+    outputs: CompiledNamespaceOutput[];
+    /** Tiny index: one row per locale, no per-namespace hashes/URLs. */
+    catalog: PackCatalog;
+    /** One shard per locale with the full namespace metadata. */
+    shards: LocaleShardOutput[];
+    /** Fresh cache for the caller to hold between incremental runs. */
+    cache: CompiledCache;
+    /** Namespaces compiled this run (not reused from `cache`). */
+    compiledCount: number;
+    /** Namespaces whose prior compiled bytes were reused unchanged. */
+    reusedCount: number;
+}
+interface CompileAllOptions {
+    /** locales/<locale>/<namespace>.json files already read (extract shape). */
+    sources: MessageSourceInput[];
+    /** Every locale that has files on disk, for catalog coverage. */
+    locales: readonly LocaleTag[];
+    defaultLocale: LocaleTag;
+    security: CompileSecurityConfig;
+    /**
+     * Prior compiled bytes by persistKey. Entries whose `sourceHash` still
+     * matches are reused verbatim (bytes + contentHash), so a dev edit
+     * recompiles only the namespaces that actually changed.
+     */
+    cache?: CompiledCache;
+    /**
+     * Resolve the fetch URL for one (locale, namespace) — lets the Vite plugin
+     * route `.dat` files through the app's asset pipeline (opaque/hashed names,
+     * docs/02-schemas.ts §3b + docs/14-obfuscation-compatibility.md), while the
+     * CLI uses a simple conventional path. The third argument is the compiled
+     * bytes' content hash, available for content-addressed URLs
+     * (`<ns>.<hash>.dat`) — optional so existing callers keep compiling.
+     */
+    urlFor(locale: LocaleTag, namespace: NamespaceId, contentHash?: string): string;
+    /**
+     * Resolve the fetch URL for one locale's shard — content-addressed
+     * (`catalog/<locale>.<namespacesHash>.json`), immutable per content, so
+     * browsers cache shards forever and the index always points at fresh ones.
+     * Optional so existing callers keep compiling (falls back to a conventional
+     * `catalog/<locale>.<hash>.json` path — same shape, caller-supplied base).
+     */
+    shardUrlFor?(locale: LocaleTag, namespacesHash: string): string;
+    /**
+     * Per-locale translation coverage override (0-1), preferred over the
+     * key-presence fallback below. The real pipeline feeds this from
+     * completion (`authoredCoverage` — authored/inherited keys vs filled-from-
+     * default). Direct `compileAll` consumers without it get coverage from the
+     * sources as given: keys present vs the default locale's keys.
+     */
+    coverageByLocale?: Partial<Record<LocaleTag, number>>;
+}
+/**
+ * Compile one namespace's message map into pack bytes. Binary encodings
+ * produce a `.dat` container; `encoding: 'json'` produces raw UTF-8 JSON
+ * bytes (no header, compression, or encryption — enforced here as well as
+ * in the config schema, so direct `compileAll` callers can't slip through).
+ * Exported for direct/unit use; `compileAll` drives the whole tree.
+ */
+declare function compileNamespace(messages: Record<MessageKey, string>, options: CompileNamespaceOptions): Promise<Uint8Array>;
+/**
+ * Compile every (locale, namespace) present in `sources` and build the
+ * catalog index + one shard per locale. `baseLocale` is the direct parent in
+ * the fallback chain when it's a registered locale; `packVersion` is a short
+ * content-derived hash (display only — contentHash is the real invalidation
+ * key, docs/13-cache-invalidation.md).
+ */
+declare function compileAll(options: CompileAllOptions): Promise<CompileAllResult>;
+
+interface GenerateOptions {
+    root?: string;
+    configFile?: string;
+    /** Output path for the generated `.d.ts`. Default `<root>/src/stift.gen.d.ts`. */
+    outputFile?: string;
+}
+interface GenerateResult {
+    config: StiftConfig;
+    discovery: DiscoveryResult;
+    extract: ExtractResult;
+    diff: DiffResult;
+    sources: MessageSourceInput[];
+    /** Scaffold + completion stats (default-locale-as-schema authoring). */
+    scaffold: ScaffoldResult;
+    completion: CompletionResult;
+    /** Absolute path the `.d.ts` was written to. */
+    outputFile: string;
+    warnings: string[];
+}
+/** Default relative output path for the generated module. */
+declare const DEFAULT_OUTPUT_REL: string;
+/** Options for the Phase 5 compiled-pack pipeline. */
+interface CompileOptions {
+    root?: string;
+    configFile?: string;
+    /** Write `.dat` files + `catalog.json` here (CLI/vanilla path). */
+    outDir?: string;
+    /** Override the security config (defaults to config.security). */
+    security?: CompileSecurityConfig;
+    /** Resolve each namespace's fetch URL (defaults to `${locale}/${ns}.dat`);
+     *  receives the compiled bytes' content hash for content-addressed names. */
+    urlFor?(locale: string, namespace: string, contentHash?: string): string;
+    /** Resolve each locale shard's URL (defaults to
+     *  `catalog/${locale}.${namespacesHash}.json`). */
+    shardUrlFor?(locale: string, namespacesHash: string): string;
+}
+interface CompileResult {
+    config: StiftConfig;
+    result: CompileAllResult;
+    /** Absolute paths written, when `outDir` was provided. */
+    writtenFiles: string[];
+}
+/** Defaults when `security` is absent from the config (docs/03 §4). */
+declare class Generator {
+    constructor(options?: {
+        root?: string;
+    });
+    private root;
+    /**
+     * Full one-shot pipeline. Returns everything the caller may need to print
+     * a report; also writes the generated `.d.ts`.
+     */
+    generateAsync(options?: GenerateOptions): Promise<GenerateResult>;
+    /**
+     * Build a predicate telling the CLI/Vite watcher whether a changed file
+     * should trigger regeneration (a `.json` under `<root>/locales/`).
+     */
+    makeWatchFilter(root: string, localesDir: string): (file: string) => boolean;
+    /**
+     * Phase 5: compile every (locale, namespace) into pack files (`.dat`
+     * containers, or raw `.json` when `security.encoding` is `'json'`) + the
+     * catalog index + one shard per locale. When `outDir` is given, writes
+     * `<outDir>/<locale>/<namespace>.dat` (or `.json`), `<outDir>/catalog.json`
+     * (the index), and `<outDir>/catalog/<locale>.<hash>.json` (shards);
+     * otherwise returns in-memory bytes for the Vite plugin to emit through
+     * the asset pipeline.
+     */
+    compileAsync(options?: CompileOptions): Promise<CompileResult>;
+}
+
+interface LoadConfigOptions {
+    root?: string;
+    configFile?: string;
+}
+interface LoadedConfig {
+    config: StiftConfig;
+    /** Absolute path to the resolved config file. */
+    file: string;
+}
+declare function findConfigFile(root: string): string | undefined;
+/**
+ * Resolve + validate the config. Throws a descriptive error if missing or
+ * failing schema validation.
+ */
+declare function loadConfig(options?: LoadConfigOptions): Promise<LoadedConfig>;
+
+/**
+ * Register typegen (docs/06-build-plugin.md §3, docs/02-schemas.ts §8).
+ *
+ * Emits an `stift.gen.d.ts` containing:
+ *   declare module "@secundus-studio/stift-core" {
+ *     interface Register {
+ *       locale: "en" | "ar" | ...
+ *       numberingSystems: ...
+ *       numberingSystems: ...
+ *       messages: {
+ *         checkout: {
+ *           proceed: { gender: "male" | "female" | "other" }
+ *           total: { amount: number }
+ *           save: {}
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * - Namespaces are keyed by their `/`-joined id; each maps `MessageKey` →
+ *   its union-across-locales param object (`{}` when it takes no params).
+ * - Keys are quoted (dot-paths are common and must not collide with dot
+ *   accessor syntax in a literal union).
+ * - `context` (declared `params.context`) emits each param's canonical
+ *   `values` union. A declared param a message uses is *optional* at the call
+ *   site (R1 — context-supplied, docs/16); every other param the message
+ *   text references is *required*, so the type system guarantees the message
+ *   always receives its data params.
+ * - `numberingSystems` / `currencies`: a literal
+ *   list emits a literal union; `'any'` (or an absent key) emits the engine's
+ *   supported set (`Intl.supportedValuesOf`) as a literal union too — pinned
+ *   to the ICU / tzdata of the machine that regenerates the file
+ *   (docs/06-build-plugin.md §Typegen), falling back to `string` only if the
+ *   engine has no list.
+ */
+
+interface GenerateTypegenOptions {
+    config: StiftConfig;
+    extract: ExtractResult;
+}
+declare function generateTypegen(options: GenerateTypegenOptions): string;
+
+/**
+ * Zod schema validating an `StiftConfig` (docs/05-config.md:123-127 —
+ * "the loaded config is validated against a schema before anything reads
+ * it"). Lane per: a malformed BCP 47 tag or invalid security tier fails fast
+ * with a clear message instead of surfacing as a confusing runtime bug.
+ */
+
+declare const configSchema: z.ZodEffects<z.ZodObject<{
+    locales: z.ZodObject<{
+        default: z.ZodEffects<z.ZodString, string, string>;
+        supported: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        default: string;
+        supported: string[];
+    }, {
+        default: string;
+        supported: string[];
+    }>;
+    numberingSystems: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"any">, z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">]>>;
+    currencies: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"any">, z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">]>>;
+    namespaces: z.ZodObject<{
+        dir: z.ZodString;
+        discovery: z.ZodEnum<["convention", "manifest"]>;
+        default: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        default: string[];
+        dir: string;
+        discovery: "convention" | "manifest";
+    }, {
+        default: string[];
+        dir: string;
+        discovery: "convention" | "manifest";
+    }>;
+    messageFormat: z.ZodEffects<z.ZodEnum<["icu-mf1", "icu-mf2"]>, "icu-mf1" | "icu-mf2", "icu-mf1" | "icu-mf2">;
+    params: z.ZodOptional<z.ZodObject<{
+        context: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            values: z.ZodArray<z.ZodString, "many">;
+            defaults: z.ZodRecord<z.ZodString, z.ZodString>;
+            persist: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            values: string[];
+            name: string;
+            defaults: Record<string, string>;
+            persist?: boolean | undefined;
+        }, {
+            values: string[];
+            name: string;
+            defaults: Record<string, string>;
+            persist?: boolean | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        context?: {
+            values: string[];
+            name: string;
+            defaults: Record<string, string>;
+            persist?: boolean | undefined;
+        }[] | undefined;
+    }, {
+        context?: {
+            values: string[];
+            name: string;
+            defaults: Record<string, string>;
+            persist?: boolean | undefined;
+        }[] | undefined;
+    }>>;
+    units: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"all">, z.ZodRecord<z.ZodEnum<["length", "mass", "area", "temperature", "digital"]>, z.ZodObject<{
+        supportedValues: z.ZodUnion<[z.ZodLiteral<"all">, z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">]>;
+        defaults: z.ZodObject<{
+            all: z.ZodEffects<z.ZodString, string, string>;
+        }, "strip", z.ZodEffects<z.ZodString, string, string>, z.objectOutputType<{
+            all: z.ZodEffects<z.ZodString, string, string>;
+        }, z.ZodEffects<z.ZodString, string, string>, "strip">, z.objectInputType<{
+            all: z.ZodEffects<z.ZodString, string, string>;
+        }, z.ZodEffects<z.ZodString, string, string>, "strip">>;
+        persist: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        defaults: {
+            all: string;
+        } & {
+            [k: string]: string;
+        };
+        supportedValues: "all" | string[];
+        persist?: boolean | undefined;
+    }, {
+        defaults: {
+            all: string;
+        } & {
+            [k: string]: string;
+        };
+        supportedValues: "all" | string[];
+        persist?: boolean | undefined;
+    }>>]>>;
+    security: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        tier: z.ZodEnum<["none", "obfuscated", "encrypted-static", "encrypted-session"]>;
+        encoding: z.ZodEnum<["msgpack", "cbor", "json"]>;
+        compression: z.ZodEnum<["none", "gzip", "brotli"]>;
+        staticKey: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tier: "none" | "obfuscated" | "encrypted-static" | "encrypted-session";
+        encoding: "msgpack" | "cbor" | "json";
+        compression: "none" | "gzip" | "brotli";
+        staticKey?: string | undefined;
+    }, {
+        tier: "none" | "obfuscated" | "encrypted-static" | "encrypted-session";
+        encoding: "msgpack" | "cbor" | "json";
+        compression: "none" | "gzip" | "brotli";
+        staticKey?: string | undefined;
+    }>, {
+        tier: "none" | "obfuscated" | "encrypted-static" | "encrypted-session";
+        encoding: "msgpack" | "cbor" | "json";
+        compression: "none" | "gzip" | "brotli";
+        staticKey?: string | undefined;
+    }, {
+        tier: "none" | "obfuscated" | "encrypted-static" | "encrypted-session";
+        encoding: "msgpack" | "cbor" | "json";
+        compression: "none" | "gzip" | "brotli";
+        staticKey?: string | undefined;
+    }>>;
+    memory: z.ZodOptional<z.ZodObject<{
+        maxCachedNamespaces: z.ZodOptional<z.ZodNumber>;
+        evictionPolicy: z.ZodOptional<z.ZodEnum<["lru", "ttl"]>>;
+        ttlMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxCachedNamespaces?: number | undefined;
+        evictionPolicy?: "lru" | "ttl" | undefined;
+        ttlMs?: number | undefined;
+    }, {
+        maxCachedNamespaces?: number | undefined;
+        evictionPolicy?: "lru" | "ttl" | undefined;
+        ttlMs?: number | undefined;
+    }>>;
+    loadingStrategy: z.ZodOptional<z.ZodEnum<["lazy-per-namespace", "critical-then-full-background", "boot-all"]>>;
+    bootExclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    detection: z.ZodOptional<z.ZodObject<{
+        order: z.ZodArray<z.ZodString, "many">;
+        timeout: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodIntersection<z.ZodRecord<z.ZodString, z.ZodNumber>, z.ZodObject<{
+            default: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            default: number;
+        }, {
+            default: number;
+        }>>, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;
+        url: z.ZodOptional<z.ZodObject<{
+            strategy: z.ZodEnum<["path-prefix", "subdomain", "domain", "query-param"]>;
+            paramName: z.ZodOptional<z.ZodString>;
+            domainMap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodString, string, string>>>;
+        }, "strip", z.ZodTypeAny, {
+            strategy: "path-prefix" | "subdomain" | "domain" | "query-param";
+            paramName?: string | undefined;
+            domainMap?: Record<string, string> | undefined;
+        }, {
+            strategy: "path-prefix" | "subdomain" | "domain" | "query-param";
+            paramName?: string | undefined;
+            domainMap?: Record<string, string> | undefined;
+        }>>;
+        cookie: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            maxAge: z.ZodOptional<z.ZodNumber>;
+            path: z.ZodOptional<z.ZodString>;
+            sameSite: z.ZodOptional<z.ZodEnum<["strict", "lax", "none"]>>;
+            secure: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            path?: string | undefined;
+            name?: string | undefined;
+            maxAge?: number | undefined;
+            sameSite?: "none" | "strict" | "lax" | undefined;
+            secure?: boolean | undefined;
+        }, {
+            path?: string | undefined;
+            name?: string | undefined;
+            maxAge?: number | undefined;
+            sameSite?: "none" | "strict" | "lax" | undefined;
+            secure?: boolean | undefined;
+        }>>;
+        fallback: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        order: string[];
+        url?: {
+            strategy: "path-prefix" | "subdomain" | "domain" | "query-param";
+            paramName?: string | undefined;
+            domainMap?: Record<string, string> | undefined;
+        } | undefined;
+        timeout?: number | (Record<string, number> & {
+            default: number;
+        }) | ((...args: unknown[]) => unknown) | undefined;
+        cookie?: {
+            path?: string | undefined;
+            name?: string | undefined;
+            maxAge?: number | undefined;
+            sameSite?: "none" | "strict" | "lax" | undefined;
+            secure?: boolean | undefined;
+        } | undefined;
+        fallback?: string | undefined;
+    }, {
+        order: string[];
+        url?: {
+            strategy: "path-prefix" | "subdomain" | "domain" | "query-param";
+            paramName?: string | undefined;
+            domainMap?: Record<string, string> | undefined;
+        } | undefined;
+        timeout?: number | (Record<string, number> & {
+            default: number;
+        }) | ((...args: unknown[]) => unknown) | undefined;
+        cookie?: {
+            path?: string | undefined;
+            name?: string | undefined;
+            maxAge?: number | undefined;
+            sameSite?: "none" | "strict" | "lax" | undefined;
+            secure?: boolean | undefined;
+        } | undefined;
+        fallback?: string | undefined;
+    }>>;
+    state: z.ZodOptional<z.ZodObject<{
+        prefix: z.ZodOptional<z.ZodString>;
+        storage: z.ZodOptional<z.ZodEnum<["webStorage", "cookie", "none"]>>;
+    }, "strip", z.ZodTypeAny, {
+        prefix?: string | undefined;
+        storage?: "none" | "cookie" | "webStorage" | undefined;
+    }, {
+        prefix?: string | undefined;
+        storage?: "none" | "cookie" | "webStorage" | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    locales: {
+        default: string;
+        supported: string[];
+    };
+    namespaces: {
+        default: string[];
+        dir: string;
+        discovery: "convention" | "manifest";
+    };
+    messageFormat: "icu-mf1" | "icu-mf2";
+    params?: {
+        context?: {
+            values: string[];
+            name: string;
+            defaults: Record<string, string>;
+            persist?: boolean | undefined;
+        }[] | undefined;
+    } | undefined;
+    numberingSystems?: "any" | string[] | undefined;
+    currencies?: "any" | string[] | undefined;
+    units?: "all" | Partial<Record<"length" | "mass" | "area" | "temperature" | "digital", {
+        defaults: {
+            all: string;
+        } & {
+            [k: string]: string;
+        };
+        supportedValues: "all" | string[];
+        persist?: boolean | undefined;
+    }>> | undefined;
+    security?: {
+        tier: "none" | "obfuscated" | "encrypted-static" | "encrypted-session";
+        encoding: "msgpack" | "cbor" | "json";
+        compression: "none" | "gzip" | "brotli";
+        staticKey?: string | undefined;
+    } | undefined;
+    memory?: {
+        maxCachedNamespaces?: number | undefined;
+        evictionPolicy?: "lru" | "ttl" | undefined;
+        ttlMs?: number | undefined;
+    } | undefined;
+    loadingStrategy?: "lazy-per-namespace" | "critical-then-full-background" | "boot-all" | undefined;
+    bootExclude?: string[] | undefined;
+    detection?: {
+        order: string[];
+        url?: {
+            strategy: "path-prefix" | "subdomain" | "domain" | "query-param";
+            paramName?: string | undefined;
+            domainMap?: Record<string, string> | undefined;
+        } | undefined;
+        timeout?: number | (Record<string, number> & {
+            default: number;
+        }) | ((...args: unknown[]) => unknown) | undefined;
+        cookie?: {
+            path?: string | undefined;
+            name?: string | undefined;
+            maxAge?: number | undefined;
+            sameSite?: "none" | "strict" | "lax" | undefined;
+            secure?: boolean | undefined;
+        } | undefined;
+        fallback?: string | undefined;
+    } | undefined;
+    state?: {
+        prefix?: string | undefined;
+        storage?: "none" | "cookie" | "webStorage" | undefined;
+    } | undefined;
+}, {
+    locales: {
+        default: string;
+        supported: string[];
+    };
+    namespaces: {
+        default: string[];
+        dir: string;
+        discovery: "convention" | "manifest";
+    };
+    messageFormat: "icu-mf1" | "icu-mf2";
+    params?: {
+        context?: {
+            values: string[];
+            name: string;
+            defaults: Record<string, string>;
+            persist?: boolean | undefined;
+        }[] | undefined;
+    } | undefined;
+    numberingSystems?: "any" | string[] | undefined;
+    currencies?: "any" | string[] | undefined;
+    units?: "all" | Partial<Record<"length" | "mass" | "area" | "temperature" | "digital", {
+        defaults: {
+            all: string;
+        } & {
+            [k: string]: string;
+        };
+        supportedValues: "all" | string[];
+        persist?: boolean | undefined;
+    }>> | undefined;
+    security?: {
+        tier: "none" | "obfuscated" | "encrypted-static" | "encrypted-session";
+        encoding: "msgpack" | "cbor" | "json";
+        compression: "none" | "gzip" | "brotli";
+        staticKey?: string | undefined;
+    } | undefined;
+    memory?: {
+        maxCachedNamespaces?: number | undefined;
+        evictionPolicy?: "lru" | "ttl" | undefined;
+        ttlMs?: number | undefined;
+    } | undefined;
+    loadingStrategy?: "lazy-per-namespace" | "critical-then-full-background" | "boot-all" | undefined;
+    bootExclude?: string[] | undefined;
+    detection?: {
+        order: string[];
+        url?: {
+            strategy: "path-prefix" | "subdomain" | "domain" | "query-param";
+            paramName?: string | undefined;
+            domainMap?: Record<string, string> | undefined;
+        } | undefined;
+        timeout?: number | (Record<string, number> & {
+            default: number;
+        }) | ((...args: unknown[]) => unknown) | undefined;
+        cookie?: {
+            path?: string | undefined;
+            name?: string | undefined;
+            maxAge?: number | undefined;
+            sameSite?: "none" | "strict" | "lax" | undefined;
+            secure?: boolean | undefined;
+        } | undefined;
+        fallback?: string | undefined;
+    } | undefined;
+    state?: {
+        prefix?: string | undefined;
+        storage?: "none" | "cookie" | "webStorage" | undefined;
+    } | undefined;
+}>, {
+    locales: {
+        default: string;
+        supported: string[];
+    };
+    namespaces: {
+        default: string[];
+        dir: string;
+        discovery: "convention" | "manifest";
+    };
+    messageFormat: "icu-mf1" | "icu-mf2";
+    params?: {
+        context?: {
+            values: string[];
+            name: string;
+            defaults: Record<string, string>;
+            persist?: boolean | undefined;
+        }[] | undefined;
+    } | undefined;
+    numberingSystems?: "any" | string[] | undefined;
+    currencies?: "any" | string[] | undefined;
+    units?: "all" | Partial<Record<"length" | "mass" | "area" | "temperature" | "digital", {
+        defaults: {
+            all: string;
+        } & {
+            [k: string]: string;
+        };
+        supportedValues: "all" | string[];
+        persist?: boolean | undefined;
+    }>> | undefined;
+    security?: {
+        tier: "none" | "obfuscated" | "encrypted-static" | "encrypted-session";
+        encoding: "msgpack" | "cbor" | "json";
+        compression: "none" | "gzip" | "brotli";
+        staticKey?: string | undefined;
+    } | undefined;
+    memory?: {
+        maxCachedNamespaces?: number | undefined;
+        evictionPolicy?: "lru" | "ttl" | undefined;
+        ttlMs?: number | undefined;
+    } | undefined;
+    loadingStrategy?: "lazy-per-namespace" | "critical-then-full-background" | "boot-all" | undefined;
+    bootExclude?: string[] | undefined;
+    detection?: {
+        order: string[];
+        url?: {
+            strategy: "path-prefix" | "subdomain" | "domain" | "query-param";
+            paramName?: string | undefined;
+            domainMap?: Record<string, string> | undefined;
+        } | undefined;
+        timeout?: number | (Record<string, number> & {
+            default: number;
+        }) | ((...args: unknown[]) => unknown) | undefined;
+        cookie?: {
+            path?: string | undefined;
+            name?: string | undefined;
+            maxAge?: number | undefined;
+            sameSite?: "none" | "strict" | "lax" | undefined;
+            secure?: boolean | undefined;
+        } | undefined;
+        fallback?: string | undefined;
+    } | undefined;
+    state?: {
+        prefix?: string | undefined;
+        storage?: "none" | "cookie" | "webStorage" | undefined;
+    } | undefined;
+}, {
+    locales: {
+        default: string;
+        supported: string[];
+    };
+    namespaces: {
+        default: string[];
+        dir: string;
+        discovery: "convention" | "manifest";
+    };
+    messageFormat: "icu-mf1" | "icu-mf2";
+    params?: {
+        context?: {
+            values: string[];
+            name: string;
+            defaults: Record<string, string>;
+            persist?: boolean | undefined;
+        }[] | undefined;
+    } | undefined;
+    numberingSystems?: "any" | string[] | undefined;
+    currencies?: "any" | string[] | undefined;
+    units?: "all" | Partial<Record<"length" | "mass" | "area" | "temperature" | "digital", {
+        defaults: {
+            all: string;
+        } & {
+            [k: string]: string;
+        };
+        supportedValues: "all" | string[];
+        persist?: boolean | undefined;
+    }>> | undefined;
+    security?: {
+        tier: "none" | "obfuscated" | "encrypted-static" | "encrypted-session";
+        encoding: "msgpack" | "cbor" | "json";
+        compression: "none" | "gzip" | "brotli";
+        staticKey?: string | undefined;
+    } | undefined;
+    memory?: {
+        maxCachedNamespaces?: number | undefined;
+        evictionPolicy?: "lru" | "ttl" | undefined;
+        ttlMs?: number | undefined;
+    } | undefined;
+    loadingStrategy?: "lazy-per-namespace" | "critical-then-full-background" | "boot-all" | undefined;
+    bootExclude?: string[] | undefined;
+    detection?: {
+        order: string[];
+        url?: {
+            strategy: "path-prefix" | "subdomain" | "domain" | "query-param";
+            paramName?: string | undefined;
+            domainMap?: Record<string, string> | undefined;
+        } | undefined;
+        timeout?: number | (Record<string, number> & {
+            default: number;
+        }) | ((...args: unknown[]) => unknown) | undefined;
+        cookie?: {
+            path?: string | undefined;
+            name?: string | undefined;
+            maxAge?: number | undefined;
+            sameSite?: "none" | "strict" | "lax" | undefined;
+            secure?: boolean | undefined;
+        } | undefined;
+        fallback?: string | undefined;
+    } | undefined;
+    state?: {
+        prefix?: string | undefined;
+        storage?: "none" | "cookie" | "webStorage" | undefined;
+    } | undefined;
+}>;
+
+export { type CompileAllOptions, type CompileAllResult, type CompileNamespaceOptions, type CompileOptions, type CompileResult, type CompileSecurityConfig, type CompiledCache, type CompiledNamespaceCacheEntry, type CompiledNamespaceOutput, type ContextParamConfig, DEFAULT_OUTPUT_REL, type DetectionConfig, type DiffResult, type DiscoveredNamespace, type DiscoveryResult, type ExtractResult, type GenerateOptions, type GenerateResult, type GenerateTypegenOptions, Generator, type KeyLocaleShape, type KeyShape, type LoadConfigOptions, type LoadedConfig, type LocaleShardOutput, type MessageSourceInput, type MissingDiffIssue, type NamespacesConfig, type ParamType, type ParamsConfig, type StiftConfig, compileAll, compileNamespace, configSchema, defineConfig, deriveLocaleShape, diffLocales, discoverConvention, extractShapes, findConfigFile, generateTypegen, loadConfig, resolveCompileSecurity };