langsys-js-typescript 0.6.5 → 0.7.0

package/dist/index.d.mts

@@ -1,3 +1,6 @@
+import { q as ParamPrimitive, j as LegacyKeyFile, K as TFunction, c as CatalogSnapshot, y as ServerMessage, a7 as iContentBlock } from './pure-DkFXdgVa.mjs';
+export { C as CONTENT_BLOCK_MARKER_ATTR, a as CONTENT_BLOCK_MARKER_ATTRS, b as CONTENT_BLOCK_MARKER_ATTR_LEGACY, D as DEFAULT_SERVER_MESSAGE_CATEGORY, d as ExpressionShape, e as ExtractParamKeys, I as InterpolateOptions, L as LEGACY_FORMATS, f as LegacyConversion, g as LegacyEntryPoint, h as LegacyFormat, i as LegacyFormatError, k as LegacyKeyHit, l as LegacyKeyProblem, m as LegacyKeys, n as NamedExpression, P as PHRASE_MARKER_ATTR, o as PHRASE_MARKER_ATTRS, p as PHRASE_MARKER_ATTR_LEGACY, r as ParamsFor, R as RESOLVED_MARKER_ATTR, s as RESOLVED_MARKER_ATTRS, t as RESOLVED_MARKER_ATTR_LEGACY, u as ResolveServerMessagesOptions, S as SNAPSHOT_FORMAT, w as SNAPSHOT_VERSION, x as SUPPORTED_LEGACY_FORMATS, z as ServerMessagePieces, B as SnapshotCatalog, F as SnapshotCategory, G as SnapshotError, H as SnapshotPayload, J as SnapshotRefusal, T as TArgs, O as TranslationParams, V as VAR_PARAM_ATTR, Q as buildSnapshot, W as canonicalSnapshotJson, X as canonicalizeLocale, Y as convertLegacyCall, Z as convertLegacyPluralForms, _ as convertLegacyValue, $ as createLegacyKeys, a0 as defaultedArguments, a1 as derivePlaceholderNames, a3 as fillTemplate, a4 as findUnusedParamKeys, a5 as generateCustomId, a6 as generateLegacyCustomId, a8 as interpolate, a9 as isEmpty, aa as isICU, ab as isTranslationExcluded, ad as md5, ae as md5Legacy, af as normalizeMarkupPlaceholders, ah as parseSnapshot, ai as resolveServerMessages, aj as snakeCase, ak as snapshotChecksum, am as templateMarkers, an as toServerMessage } from './pure-DkFXdgVa.mjs';
+
 /**
  * Tiny framework-agnostic reactive value holder — our replacement for a
  * Svelte `Writable<T>`. The shape is deliberately similar so the mental
@@ -60,6 +63,289 @@ type iCategories = {
     __uncategorized__: iTranslations;
 };
 
+/**
+ * Content blocks without a DOM (spec SRV-1, MARK-1, TOK-6): identify, translate
+ * and register a `<Translate>` block from a tree, so a framework rendering on a
+ * server, or rendering on the client before mount, emits the translated block
+ * and its stamped id instead of source text.
+ *
+ * A tree is the block's content, the children of the host element, as plain
+ * nodes. It is walked by the same code as the DOM (`tokenizeNodes`,
+ * `findSingleTextNode`, `isExcisedFromUnit`) through a DOM-shaped view of it, so
+ * a tree and the DOM it mirrors yield the same tokens, shape and id.
+ *
+ * `renderBlock` is synchronous and pure over the active catalog: it registers
+ * nothing and its output is the same on a server and in the browser for the
+ * same catalog, so a client's first render matches what the server sent. A
+ * binding registers with `registerBlock`, which touches no DOM.
+ */
+/**
+ * A node of a block's content. Attribute values are strings; `true` is an attribute with no value.
+ *
+ * `params` on a nested host's element (a phrase host or a content-block declaration) are
+ * that unit's own: it renders with them in place of the block's, so a binding names each
+ * unit's values on their own (VAR-2) and a nested phrase keys as it does standing alone.
+ * A nested host without them renders with the block's.
+ */
+type BlockNode = {
+    text: string;
+} | {
+    comment: string;
+} | {
+    tag: string;
+    attrs?: Readonly<Record<string, string | true>>;
+    children?: readonly BlockNode[];
+    params?: Readonly<Record<string, ParamPrimitive>>;
+};
+/**
+ * A node of a rendered block. Every element names, as `source`, the pre-order
+ * index of the input element it renders (elements only, counted across the
+ * whole input from 0), so a binding can re-attach what the tree cannot carry —
+ * handlers, refs, keys — even where a translation reorders inline markup.
+ */
+type RenderedNode = {
+    text: string;
+} | {
+    comment: string;
+} | {
+    tag: string;
+    attrs: Record<string, string | true>;
+    children: RenderedNode[];
+    source: number;
+};
+type BlockShape = 'phrase' | 'block' | 'empty';
+interface BlockOptions {
+    category?: string;
+    params?: Record<string, ParamPrimitive>;
+    /** A label for the block in the Translation Manager, as `Translate`'s option. */
+    label?: string;
+    /**
+     * The app's own `custom_id` for the block: rendered under it, and registered
+     * under it with its content when the catalog does not hold it, as
+     * `Translate`'s `custom_id` option does.
+     */
+    id?: string;
+    /**
+     * A `custom_id` to ADOPT: a renderer already rendered this block from the
+     * catalog under it (a stamp carried with the resolved marker, MARK-3). Rendered
+     * under it, never registered.
+     */
+    customId?: string;
+    /**
+     * `registerBlock` only: the host element on the client, whose ancestors decide
+     * GATE-10. The walk starts at its parent, since the host itself carries the
+     * resolved marker when it was rendered from the catalog.
+     */
+    host?: Element;
+    /** `false` registers nothing, nested hosts included (VAR-7); `renderBlock` ignores it. Default `true`. */
+    register?: boolean;
+}
+interface RenderedBlock {
+    shape: BlockShape;
+    /** The id the block renders under: derived, a historical id the catalog holds (CID-3), or adopted. Null when empty. */
+    customId: string | null;
+    nodes: RenderedNode[];
+    /**
+     * The attributes to set on the host: the block's id (MARK-1), and, when the
+     * rendered text is a translation (a locale other than the base), the resolved
+     * marker with that locale (GATE-10), so a DOM reader on the client never files
+     * the served translation as source. Empty for an empty block.
+     */
+    hostAttrs: Record<string, string>;
+}
+/**
+ * A block as a request scope's seed carries it (SRV-4), for a client that cannot
+ * recover the block's source from its DOM: `registerBlock` accepts it in place
+ * of the source nodes.
+ */
+interface SeededBlock {
+    customId: string;
+    category: string;
+    tokens: string[];
+    shape: 'phrase' | 'block';
+    /**
+     * The block's content as `registerBlock` over its nodes would send it, for a
+     * client that registers it from the seed. Absent wherever no client does: a
+     * phrase-shaped entry, a block the scope's catalog holds, a `collected` one and
+     * one marked `register: false`. A seeded block without it registers nothing.
+     */
+    content?: string;
+    /**
+     * The server's scope sends this block itself at `close()` (the `server`
+     * strategy, or `auto` for a short list), so a client never registers it:
+     * not from the seed, and not from the `Translate` over its host.
+     */
+    collected?: boolean;
+    /**
+     * `false` when a registration over the block's nodes sends nothing, so
+     * `registerBlock(seededBlock)` never registers it: a block rendered with
+     * `register: false` (VAR-7), at any depth, whose tokens hold values from
+     * variables, carried only so a client can re-render the served text; one under
+     * an adopted id; one inside a resolved scope, and the blocks nested in either;
+     * and a unit of value markers only.
+     */
+    register?: false;
+}
+/**
+ * A phrase a request scope's render missed, as its seed carries it: `t()`, a
+ * `<Phrase>` host or a single-token block. `collected` as on `SeededBlock`: the
+ * scope sends it itself at `close()`, and the client never records it again.
+ */
+interface SeededPhrase {
+    category: string;
+    phrase: string;
+    collected?: boolean;
+}
+/** A request scope's hydration seed (SRV-4): `LangsysApp.seedCatalog(seed.catalog, seed.locale, seed)` on the client. */
+interface RequestSeed {
+    locale: string;
+    catalog: iCategories;
+    blocks: Record<string, SeededBlock>;
+    phrases: SeededPhrase[];
+}
+/** The tokens and shape of a block's content, exactly as `tokenizeElement` and `Translate` decide them for the same markup. */
+declare function tokenizeTree(nodes: readonly BlockNode[]): {
+    tokens: string[];
+    shape: BlockShape;
+};
+/**
+ * Render a block from its content: the translated tree, the id it renders
+ * under and the marker to stamp. Synchronous, registers nothing, and reads only
+ * the active catalog (a request scope's, or the page's), so the same input and
+ * catalog render the same bytes on a server and in the browser.
+ *
+ * Nested marked hosts are units of their own (MARK-4), rendered in place: a
+ * phrase host as its rich phrase, a declared block as its own block (stamped
+ * with its id), a stamped one under its id. `translate="no"`, `data-notrans`
+ * and code elements are returned as given.
+ */
+declare function renderBlock(nodes: readonly BlockNode[], options?: BlockOptions): RenderedBlock;
+/** The notices already given, one per reason. */
+/**
+ * Report, as a debug notice once per process per reason, that a binding could
+ * not render a block through `renderBlock`. What happens next depends on the
+ * reason, and the notice says which:
+ *
+ * - a framework component in its subtree, a raw-HTML prop, a raw-text element,
+ *   a suspense placeholder: SRV-1's one sanctioned fallback, not a fault. The
+ *   block is served as source with no resolved marker and its app-supplied id
+ *   stamped where it has one, and the client renders and registers it after
+ *   hydration.
+ * - `variable`: the block holds a value from a variable the binding cannot name
+ *   without its build-time transform, so it renders from the catalog and
+ *   registers nothing, on the server or the client (VAR-7).
+ *
+ * The notice is the core's (bindings write no console output of their own). One
+ * raised before `init()` is held until debug is known (see `debugNotice`).
+ */
+declare function warnUnrenderedBlock(reason: string): void;
+/**
+ * Register a block for discovery, with no DOM: what `Translate` registers when
+ * it mounts, for a framework that owns the host's text nodes and renders
+ * through `renderBlock`. A single-token unit records its phrase miss as `t()`
+ * does; a block the catalog lacks, under no historical id, registers with its
+ * content; an adopted id (`customId`) registers nothing; nested phrase hosts and
+ * declared or unresolved-stamped blocks register as their own units. Inside a
+ * request scope it is held for `close()`. Fire-and-forget, and never throws
+ * synchronously: the returned promise settles once the registration has run.
+ *
+ * On a server outside every request scope it resolves at once and registers
+ * nothing: there is no scope to hold the block for `close()`, and no `init()` to
+ * wait for when the client is the one that initialises, so waiting would keep the
+ * tree alive for the life of the process. A debug notice says so, once.
+ *
+ * Under `requireCredentials` an unconfigured client fails loudly here as on the
+ * DOM classes (WIRE-4): on the page the promise rejects with
+ * `LangsysConfigurationError`, checked again once `init()` has answered, so a
+ * block registered before `init()` refuses rejects too. A `register: false` block
+ * is a read and never rejects. A binding that leaves the
+ * promise unhandled surfaces it. On a server it never rejects, since an unhandled
+ * rejection would end a Node process rather than one request, and the request's
+ * `t()` throws already.
+ *
+ * With `host`, the host is the binding's from this call on: an enclosing
+ * `Translate` leaves it alone rather than taking it over as an unmanaged marked host.
+ *
+ * One-shot: it records what the block is now. A binding calls it again on each
+ * change `t` goes through — a locale switch, a new catalog, a navigation — as
+ * `Translate` re-enters its lookup (HINT-13).
+ *
+ * The flows it serves: on a server the outermost host renders and registers,
+ * and nested declared hosts are covered through its tree. On the client after
+ * hydration, the blocks a scope rendered are registered from its seed, one
+ * `registerBlock(seededBlock)` per `seed().blocks` entry after `init()`, since
+ * the DOM already holds translated text. That loop is for bindings that mount
+ * the DOM classes; a binding that renders trees registers each block from its
+ * nodes as it renders. Either way a block or phrase the seed marks `collected`
+ * is never registered, since the server's scope sends it itself, and neither is a
+ * block the seed marks `register: false`, whose tokens hold per-user values.
+ */
+declare function registerBlock(input: readonly BlockNode[] | SeededBlock, options?: BlockOptions): Promise<void>;
+/**
+ * A host element's content as a tree: its child nodes as `BlockNode`s, a
+ * `<template>`'s content included. For a binding that holds a DOM, on a server
+ * or on the client, so no binding walks a DOM of its own to tokenize.
+ */
+declare function blockNodesOf(element: {
+    childNodes: ArrayLike<Node>;
+}): BlockNode[];
+/**
+ * Write a rendered block into the host's EXISTING nodes: each text node's value,
+ * each translatable attribute and each nested host's unit markers (its id and
+ * resolved marker, MARK-1, GATE-10), in place, never replacing a node, so a
+ * framework's references to them stay live; and, given a whole `RenderedBlock`,
+ * its `hostAttrs` on the host. Only when the DOM has the rendered tree's
+ * structure: the same nodes in the same places, each element where its `source`
+ * says. Otherwise nothing is touched and it returns
+ * `{ applied: false, reason: 'structure' }`: a translation that reorders inline
+ * markup cannot be applied to nodes a framework owns.
+ *
+ * With `self`, `element` is the tree's root rather than its parent: the tree was
+ * rendered from `[{ tag, attrs, children: blockNodesOf(element) }]`, as a
+ * standalone phrase host is (`data-ls-phrase` on the root, at `source` 0), and
+ * `element` is matched against its one root node.
+ */
+declare function applyRendered(element: Element, rendered: RenderedBlock | readonly RenderedNode[], options?: {
+    self?: boolean;
+}): {
+    applied: boolean;
+    reason?: 'structure';
+};
+/** Serialise a block's content as HTML, for the content snapshot a block registers with. Not identity. */
+declare function serializeTree(nodes: readonly BlockNode[]): string;
+
+interface HttpResponse {
+    status: number;
+    statusText: string;
+    url: string;
+    data: string;
+}
+interface ResponseObject {
+    status: boolean;
+    page?: number;
+    page_count?: number;
+    records_per_page?: number;
+    data?: object[] | object;
+    errors?: string[];
+    http?: HttpResponse;
+    /**
+     * Server-computed write capability for this session, returned by
+     * `authorize-project` and by every catalog fetch. Envelope-level on
+     * `/translations`: the `data` member there IS the category map, so a stray
+     * non-category key inside it would be read as a category.
+     */
+    write_enabled?: boolean;
+    /**
+     * Project setting: record a miss only while the loaded locale is the base locale.
+     * A top-level sibling of `data` on both catalog routes, and inside `data` on
+     * `authorize-project`. Absent means off.
+     */
+    discovery_base_locale_only?: boolean;
+    /** Catalog size counters returned alongside `data` on `/translations`. */
+    words?: number;
+    untranslated_words?: number;
+}
+
 /**
  * Minimum interface for a user-locale source.
  *
@@ -80,6 +366,33 @@ interface LocaleSource {
     /** Register a callback for locale changes. Returns an unsubscribe function. */
     subscribe(run: (locale: string) => void): () => void;
 }
+/**
+ * A short-lived write grant (HS256 JWT) minted by the host app's own backend,
+ * sent as `X-Write-Grant`. A valid grant makes the session write-enabled
+ * server-side, so `write_enabled` comes back true and phrase discovery
+ * registers normally — used by login-walled apps our discovery renderer
+ * cannot reach.
+ *
+ * If the token only exists after login, still configure a PROVIDER at `init`
+ * that returns `null` until then, rather than leaving `writeGrant` unset and
+ * calling `setWriteGrant()` later. An unset grant tells the SDK that no grant
+ * can ever arrive, so when authorization comes back read-only it releases the
+ * queued misses — which for a login-walled app means they are only reported to
+ * a renderer that cannot log in, which is the situation grants exist to solve.
+ * A provider returning `null` keeps the queue held until the grant appears.
+ *
+ * Prefer the FUNCTION form. Grants have a ~5 minute TTL while `init()` runs
+ * once and an app session can last hours, so a bare string is expired minutes
+ * in and every later write silently degrades the session to read-only. The
+ * provider is called immediately before each request, so the host app refreshes
+ * by simply returning a fresh token. `null`/`undefined` means "no grant yet"
+ * (e.g. before login) and is sent as no header at all.
+ *
+ * The resolved token is never cached — not on the config singleton, not on the
+ * API client — which is what keeps it safe in a long-lived SSR process shared
+ * across users.
+ */
+type WriteGrant = string | (() => string | null | undefined | Promise<string | null | undefined>);
 interface iLangsysInitConfig {
     /** The ID (UUID) of the project created in Langsys */
     projectid: string;
@@ -96,6 +409,31 @@ interface iLangsysInitConfig {
      * @default 'en'
      */
     baseLocale?: string;
+    /**
+     * Point the SDK at a different API host — a local instance, a staging
+     * host, or a stateful test double.
+     *
+     * Prefer this over `LangsysAppAPI.setBaseUrl()`. The setter has to run
+     * BEFORE `init()`, and running it after leaves the SDK permanently inert:
+     * `init()` has already authorized against the default host and failed, and
+     * the locale subscription is installed closed over that failed result, so
+     * it no-ops for the life of the app. Nothing throws, and no later locale
+     * change or URL fix recovers it. This option is applied inside `init()`
+     * before authorization, in the same call that consumes it, so there is no
+     * ordering left to get wrong.
+     *
+     * @default 'https://api.langsys.dev/api'
+     */
+    apiUrl?: string;
+    /**
+     * Fail loudly when credentials are missing (WIRE-4). Off by default: `init()` without a
+     * project id, API key or locale store leaves the client unconfigured, and `t()` renders
+     * source text with its params filled. On, `t()` throws `LangsysConfigurationError`
+     * instead, so a build or test run with missing credentials stops at the first render.
+     *
+     * @default false
+     */
+    requireCredentials?: boolean;
     /**
      * Enable debug console messages.
      * @default false
@@ -111,6 +449,21 @@ interface iLangsysInitConfig {
      * @default 'client'
      */
     ssrTokenStrategy?: 'client' | 'server' | 'auto';
+    /**
+     * Turn on the legacy-key mode (spec MIG): the app's kept source-language
+     * files, each parsed, as `{ name, format?, namespace?, data }`. `t()` then
+     * resolves its argument as a key first; a key's value is the phrase, never
+     * the key. Formats are `i18next`, `vue-i18n` and `plain` (the default); any
+     * other makes `init` throw, naming the file. Unset, `t()` does no key lookup.
+     */
+    legacyKeys?: LegacyKeyFile[];
+    /**
+     * The category server messages are registered and rendered under (spec
+     * MSG-6). It must be the same category the server registers templates
+     * under, or every lookup misses and falls back to the entry's `message`.
+     * @default 'Errors'
+     */
+    messagesCategory?: string;
     /**
      * Pre-fetched translation data to bypass the initial API call.
      * Useful for SSR scenarios to avoid duplicate fetches.
@@ -118,6 +471,17 @@ interface iLangsysInitConfig {
     initialTranslations?: iCategories;
     /** Locale that `initialTranslations` corresponds to. */
     initialTranslationsLocale?: string;
+    /**
+     * Short-lived write grant for login-walled apps. See `WriteGrant` — prefer
+     * the function form; the bare string is quickstart-only. Can also be
+     * supplied after `init()` via `LangsysApp.setWriteGrant()`.
+     *
+     * Note: configuring a grant makes write capability per-user, so a
+     * process-level SSR write decision would be unsound. `ssrTokenStrategy`
+     * therefore degrades to `'client'` while a grant is configured (logged at
+     * init when `debug` is on).
+     */
+    writeGrant?: WriteGrant;
 }
 interface iLangsysConfig {
     projectid: string;
@@ -125,8 +489,22 @@ interface iLangsysConfig {
     sUserLocale: LocaleSource;
     baseLocale: string;
     debug?: boolean;
-    /** Permission level of the API key, set automatically after successful authorization. */
-    key_type?: 'read' | 'write';
+    /**
+     * Permission level of the API key, set automatically after successful
+     * authorization. Display/debug only — NEVER branch on this.
+     *
+     * A public key shipped in browser JS is extractable, so write capability
+     * is decided per-session by the server, not by the key alone: `ip_write`
+     * keys are read-only everywhere except from allow-listed IPs. Use the
+     * server-computed `writeEnabled` signal for every write decision. The
+     * `(string & {})` arm keeps unknown future key types from breaking
+     * downstream typechecks.
+     */
+    key_type?: 'read' | 'write' | 'ip_write' | (string & {});
+    /** Short-lived write grant sent as `X-Write-Grant`. See `WriteGrant`. */
+    writeGrant?: WriteGrant;
+    /** The category server messages render under (MSG-6). */
+    messagesCategory?: string;
     /**
      * Token creation behavior during SSR.
      * - 'client': queue tokens for client-side sending (default)
@@ -138,71 +516,156 @@ interface iLangsysConfig {
 }
 
 /**
- * Translation function type machinery.
- *
- * The big trick here is `ExtractParamKeys` — a recursive template-literal
- * type that pulls placeholder names out of a phrase at compile time, so
- * `t('Hello, {name}!', { name: 'Sarah' })` is type-checked: passing
- * an object without `name`, or with a key not in the phrase, is a TS error.
- */
-/** Allowed value types for interpolation. Mirrors what ICU MessageFormat will accept. */
-type ParamPrimitive = string | number | Date | boolean;
-/**
- * Pull placeholder names out of a phrase.
- * @example
- *   ExtractParamKeys<"Hello, {name}!">        // "name"
- *   ExtractParamKeys<"{first} and {last}">    // "first" | "last"
- *   ExtractParamKeys<"no placeholders here">  // never
- */
-type ExtractParamKeys<S extends string> = S extends `${string}{${infer K}}${infer Rest}` ? K | ExtractParamKeys<Rest> : never;
-/** Build the params object type required for a given phrase. */
-type ParamsFor<S extends string> = {
-    [K in ExtractParamKeys<S>]: ParamPrimitive;
-};
-/**
- * Rest-tuple for the optional params argument.
- * Empty when the phrase has no placeholders → 3rd arg is forbidden.
- * Required tuple when the phrase has placeholders → 3rd arg must be passed.
+ * The client has no credentials (WIRE-4): `init()` was refused for a missing project id,
+ * API key or locale store, or was never called. An explicit write throws this rather than
+ * sending, and so does `t()` under `requireCredentials`. A read renders source text instead,
+ * and a call whose result reports a skipped write resolves skipped with reason
+ * `not-configured`, since a component reaches it and a component path never throws.
  */
-type TArgs<P extends string> = [ExtractParamKeys<P>] extends [never] ? [] : [params: ParamsFor<P>];
-/** Loose params type — used inside generic stores where the phrase isn't a known literal. */
-type TranslationParams = Record<string, ParamPrimitive>;
+declare class LangsysConfigurationError extends Error {
+    constructor(message: string);
+}
 /**
- * The translation function signature.
- *
- *   t('Save')                                     // no category, no params
- *   t('Save', 'UI')                               // categorized
- *   t('Hello, {name}!', { name: 'X' })            // no category, with params
- *   t('Hello, {name}!', 'Greetings', { name: 'X' }) // category + params
- *
- * Two overloads discriminate on the type at position 2 (string → category,
- * object → params). `category` is required for the second overload —
- * pass any non-empty string. There is no "null category" wire concept:
- * absent category means absent.
+ * What a request sends under (SRV-2): a project id and API key, with the write grant that
+ * goes with them. The module-wide ones are what `init()` set; a request scope may carry
+ * its own.
  */
-interface TFunction {
-    <P extends string>(phrase: P, ...args: TArgs<P>): string;
-    <P extends string>(phrase: P, category: string, ...args: TArgs<P>): string;
+interface ApiCredentials {
+    readonly projectid: string;
+    readonly key: string;
+    readonly writeGrant?: WriteGrant;
+}
+interface SendOptions {
+    /**
+     * Let the request outlive the page that started it (`fetch` keepalive).
+     * Used for the teardown flush, where the document is being torn down and a
+     * normal request would be cancelled with it.
+     *
+     * NOT `navigator.sendBeacon`, which is the usual answer to this problem but
+     * cannot carry custom headers — our authorization is `x-Authorization`, so
+     * a beacon would be rejected. `keepalive` supports headers and survives
+     * teardown; the trade is a ~64KB body cap across in-flight keepalive
+     * requests, which is why the teardown path chunks conservatively.
+     */
+    keepalive?: boolean;
+    /**
+     * Send under these credentials. Without them a request sends under those of the
+     * request scope the calling code runs in, and outside every scope under the
+     * module-wide ones (SRV-2). The page's own lanes pass the module-wide ones, so a page
+     * request that starts inside a scope's async context still goes out under the page's key.
+     */
+    credentials?: ApiCredentials;
+}
+declare class LangsysAppAPIClass {
+    private apiurl;
+    config: iLangsysConfig;
+    constructor();
+    setup(config: iLangsysConfig): void;
+    /** Forget the credentials: `init()` was refused for missing ones, so nothing may send under old ones. */
+    clearCredentials(): void;
+    /** True when the module-wide credentials carry a write grant (in either form). */
+    hasWriteGrant(): boolean;
+    /** The module-wide credentials `init()` set: the page's, and a scope's that was given none. */
+    moduleCredentials(): ApiCredentials;
+    /** What a request made now sends under, unless it names its own (SRV-2): the active scope's, else the module-wide ones. */
+    currentCredentials(): ApiCredentials;
+    /**
+     * Resolve the write grant a request sends with, calling the consumer's provider
+     * if that is the configured form.
+     *
+     * The result is deliberately NOT cached — not here, not on the config
+     * singleton. Grants are ~5 minute JWTs and per-user, while this client is
+     * a process-wide singleton; in a long-lived SSR server one cached token
+     * would be attached to every later user's requests. Resolving per request
+     * is also what lets the host app refresh by simply returning a new token.
+     */
+    private resolveWriteGrant;
+    /** Build request headers fresh per call. Never memoized — see `resolveWriteGrant`. */
+    private buildHeaders;
+    /** Optional hook to point the client at a different API host. */
+    setBaseUrl(url: string): void;
+    validate(config: iLangsysConfig): Promise<ResponseObject>;
+    getTranslations(locale: string, opts?: SendOptions): Promise<ResponseObject>;
+    /**
+     * Register phrases and/or content blocks via the current unified endpoint.
+     * Each item carries `type: 'phrase' | 'content_block'`. Replaces the
+     * deprecated `projects/{id}/tokens` and `projects/{id}/content-blocks` routes.
+     */
+    createTranslatableItems(items: Array<Record<string, unknown>>, opts?: SendOptions): Promise<ResponseObject>;
+    /**
+     * Report that a page appears to contain unregistered content, so the
+     * discovery renderer can visit it from an allow-listed IP and register
+     * what it finds.
+     *
+     * URL only — never a phrase payload. This is the read-only lane: anonymous
+     * callers can say "look here", never "store this". Answers 204 whether or
+     * not the hint is acted on, deliberately so it can't be used as an oracle
+     * for key validity or registration state. No `project_id`: the key already
+     * resolves to exactly one project server-side.
+     */
+    postDiscoveryHint(pageUrl: string, opts?: SendOptions): Promise<ResponseObject>;
+    post(path: string, data?: Record<string, unknown>, opts?: SendOptions): Promise<ResponseObject>;
+    get(path: string, data?: Record<string, unknown>, opts?: SendOptions): Promise<ResponseObject>;
+    delete(path: string, data?: Record<string, unknown>, opts?: SendOptions): Promise<ResponseObject>;
+    patch(path: string, data?: Record<string, unknown>, opts?: SendOptions): Promise<ResponseObject>;
+    put(path: string, data?: Record<string, unknown>, opts?: SendOptions): Promise<ResponseObject>;
+    private send;
 }
+declare const LangsysAppAPI: LangsysAppAPIClass;
 
-/**
- * Lifecycle for app translations:
- *  - on-miss: any `t(cat, phrase)` whose phrase isn't in the catalog is
- *    queued as a "missing token" and (with write keys) flushed to the API.
- *  - locale changes trigger `change()` which fetches and replaces.
- *  - consumers can `subscribe(fn)` to react to translation snapshots.
- *  - frameworks subscribe to `tSignal` (which re-emits a fresh `TFunction`
- *    every time translations or the loaded locale change) so reactive
- *    templates re-render automatically.
- */
+/** Where `t()` reads and records: the page's state, or a request scope's (SRV-7). */
+interface CatalogView {
+    catalog(): iCategories;
+    locale(): string;
+    miss(category: string, key: string, onlyForRegistration: boolean): void;
+    fromSnapshot(): boolean;
+}
 declare class Translations {
     private config;
     private locale;
     private lastLoaded;
     private missingTokens;
+    /** Phrases already reported under REG-11, so the warning fires once each. */
+    private warnedEllipsis;
+    /** The legacy-key mode (MIG-1): null unless configured, and then `t()` does no key lookup at all. */
+    private legacyKeys;
+    private warnedLegacy;
     private timer;
+    /**
+     * Catalog fetches still in flight. While any is, queued tokens are held: the flush
+     * deduplicates against the catalog, and the catalog being fetched is not there yet.
+     */
+    private catalogFetchesInFlight;
+    /**
+     * The published catalog is a snapshot, not the live catalog (SNAP-2). Lookups
+     * read it, but registration is decided only against the live catalog
+     * (REG-13), so until one arrives every phrase is queued and the queue is held.
+     */
+    private catalogFromSnapshot;
+    /**
+     * CACHE-2: a failed catalog fetch, remembered per project and locale. Until `retryAt` a
+     * lookup for that pair renders source text and nothing is fetched. The window follows
+     * REG-8's clock on the read side: 3s, doubling on each consecutive failure to 5 minutes,
+     * cleared by the first success. Held on this instance, so it lasts the page session in a
+     * browser and the life of the server object on a server, and is never written anywhere.
+     */
+    private catalogFailures;
+    /** CACHE-2: a catalog request in flight per project and locale, shared by concurrent fetches. */
+    private catalogRequests;
     private flushScheduled;
+    private updateInFlight;
+    private debounceTimer;
+    private consecutiveFailures;
+    /** Epoch ms before which no send may be attempted. See RETRY_BACKOFF_*. */
+    private retryNotBefore;
+    private teardownInstalled;
+    /** Unregisters this instance from an injected teardown signal (`setTeardownSignal`). */
+    private releaseTeardownFlush;
     private isFirstClientRun;
+    /** Process-level write decision for the SSR lane. See `canWrite`. */
+    private ssrWriteEnabled;
+    /** Thrown by `t()` when `init()` was refused for missing credentials under `requireCredentials`. */
+    private credentialsError;
     private readyResolve;
     private readyPromise;
     debug: Logger;
@@ -217,6 +680,54 @@ declare class Translations {
      * to avoid acting on an empty cache during the cold-start race.
      */
     ready(): Promise<void>;
+    /**
+     * Resolve `ready()` without a catalog, for the paths where none is coming:
+     * `init` refused the config, or authorization failed.
+     *
+     * `Phrase` and `Translate` both await this gate before rendering, so
+     * leaving it pending on those paths is not a degraded mode — it is a
+     * permanent blank render, with no error, on the commonest misconfigurations
+     * there are. Settling makes them fall back to their source text, which is
+     * what an SDK that cannot reach its backend should show.
+     *
+     * Idempotent. A later successful load still updates the stores and
+     * re-renders every subscriber.
+     */
+    settle(): void;
+    /**
+     * WIRE-4: `init()` was refused for missing credentials. Reads render source through the
+     * catalog-failed path, so no miss is recorded and nothing is sent; and the capability
+     * settles as not writable, so nothing waits on it, and the read-only release drops what
+     * an earlier render queued, since it can never be sent. With `requireCredentials`, `t()`
+     * throws `error`.
+     */
+    markUnconfigured(error: LangsysConfigurationError, requireCredentials: boolean): void;
+    /**
+     * Under `requireCredentials`, throw the configuration error while the client is
+     * unconfigured (WIRE-4). `t()` calls it, and so does `Translate`'s render, whose
+     * multi-phrase blocks never reach `t()`.
+     */
+    assertConfigured(): void;
+    /** `init()` accepted credentials: undo an earlier refusal, so the first catalog decides afresh. */
+    markConfigured(): void;
+    /**
+     * The capability is known to be "no": the client has no credentials, or authorization was
+     * refused. Without this a block registration waiting for the capability would wait forever.
+     */
+    settleNotWritable(): void;
+    /**
+     * A route change re-enters the SDK (HINT-13). Call it from the router's after-navigation
+     * hook. It publishes a fresh `t` through `tSignal` — the same dependency a locale change
+     * advances — so a component bound to `t` re-renders its mounted nodes, and each miss is
+     * recorded at the URL the page is now on. The core's own `Translate` and `Phrase` re-enter
+     * too, but only while their host is attached to the document, so an instance left
+     * undestroyed on a removed node records nothing.
+     *
+     * It sends nothing itself. What follows is the ordinary miss path: one report per URL,
+     * the jitter, the decline rules, GATE-9 and GATE-10 all apply, and a phrase already queued
+     * or registered is not queued again. Calling it twice for the same URL reports nothing more.
+     */
+    notifyNavigation(): void;
     /** Current translation function. Reads fresh state on every call. */
     get t(): TFunction;
     /** Subscribe to translation snapshot changes. Fires immediately with the current value. */
@@ -236,8 +747,148 @@ declare class Translations {
      */
     lookup(phrase: string, category: string): string | null;
     private buildTFn;
+    /** The page's catalog, locale and miss queue: what `t()` uses outside every request scope. */
+    private readonly pageView;
+    /**
+     * The body of `t()` over a catalog view: the page's, or a request scope's
+     * (SRV-7). One implementation, so a scope looks up, converts legacy keys,
+     * strips C0 controls and interpolates exactly as the page does, and differs
+     * only in whose catalog it reads and whose misses it records.
+     */
+    renderWith(view: CatalogView, phrase: string, rest: unknown[]): string;
+    /**
+     * Turn on the legacy-key mode with the app's kept source-language files, or
+     * turn it off with null (MIG-1). Throws `LegacyFormatError` for a file this
+     * core does not read (MIG-7), before anything resolves through it.
+     */
+    setLegacyKeys(files: LegacyKeyFile[] | null | undefined): void;
+    /**
+     * A key hit is the key's converted value, and the key's namespace is the
+     * category unless the call passed one (MIG-3, MIG-5). A miss is the argument
+     * as literal source text, which Langsys `t()` does not convert (MIG-2), and
+     * is noted at debug so a mistyped or removed key is visible (MIG-6). A value
+     * the conversion does not recognise registers as written and warns at every
+     * log level, naming the file and the key (MIG-4).
+     */
+    private resolveLegacyKey;
+    private warnOnce;
+    /**
+     * Record a miss on the page's lanes, as `t()` outside every scope does: for a
+     * request scope rebuilt from a seed on the client (`scopeFromSeed`), whose
+     * render's misses belong to the page.
+     */
+    recordPageMiss(category: string, token: string): void;
     private missingToken;
+    /**
+     * Whether this session may write. The single decision point for the write
+     * lane — never infer capability from `key_type`.
+     *
+     * In the browser the server-computed signal is authoritative, and `undefined`
+     * (not yet authorized) correctly holds rather than writing or hinting.
+     *
+     * Under SSR the signal is deliberately never written (it is a process-wide
+     * singleton and write capability is per-session), so we fall back to the
+     * value the last catalog fetch reported for THIS process. That is only sound
+     * while capability depends on the server's IP alone, which is constant for
+     * the process. A configured write grant makes it per-user instead, so the
+     * server lane is unsafe and we degrade to flushing after hydration — where
+     * the decision is per-user and correct.
+     */
+    /** Whether this session may write now, by the same decision the flush makes (see `canWrite`). */
+    mayWrite(): boolean;
+    private canWrite;
+    /**
+     * Record the server's write decision from an `authorize-project` or catalog
+     * response. Browser: updates the shared signal. Server: keeps a
+     * process-level copy used only when no grant is configured (see `canWrite`).
+     *
+     * `keyType` is the key type the same response describes. The authorization path
+     * passes it, because it runs before `init()` hands this instance the new config:
+     * reading `this.config` there would describe the PREVIOUS init's key on a re-init.
+     */
+    applyWriteEnabled(value: boolean | undefined, keyType?: string | undefined): void;
+    /**
+     * Whether a miss is worth holding in the REGISTRATION queue. Distinct from
+     * `canWrite()`, which decides whether to send: this decides whether keeping
+     * it could ever lead to a send.
+     *
+     * What happens to a declined miss differs by arm, and the difference is
+     * load-bearing rather than incidental:
+     *
+     *  - In the BROWSER the discovery lane has already recorded it, so the page
+     *    is still reported and nothing is lost.
+     *  - Under SSR it is recorded NOWHERE — `recordMissForDiscovery` bails
+     *    without a `window`. The safety net there is that the client re-runs
+     *    `t()` after hydration and re-collects, which covers content rendered
+     *    on both sides and does NOT cover content that only ever executes
+     *    server-side. That gap is real and documented rather than closed.
+     *
+     * Two ways a queue becomes undrainable:
+     *
+     * SSR under `'client'` — the queue is meant to be flushed after hydration
+     * by `setup()`, but that reads the BROWSER's instance of this module. The
+     * push happened in the Node process's instance. Under real SSR (Next,
+     * Remix, Astro) those are different objects in different processes, and no
+     * channel carries tokens client-ward — `initialTranslations` goes the other
+     * way. So the tokens are silently dropped AND retained forever, since the
+     * 3s drain timer only exists in the browser branch of `setup()`. In a
+     * long-lived server that plateaus at "every phrase the app has ever
+     * server-rendered", held live and never sent. Declining to collect makes
+     * the limitation explicit instead of silent: server-side discovery requires
+     * `ssrTokenStrategy: 'server'`.
+     *
+     * Browser, definitively read-only — `writeEnabled` is `false` and no grant
+     * is configured, so no path exists by which this session becomes writable.
+     * (`undefined` still queues: capability isn't known yet and those misses
+     * must be held, not dropped. A configured grant also queues, since one
+     * arriving flips the session write-enabled.)
+     */
+    private shouldQueueForWrite;
     private scheduleTokenFlush;
+    /**
+     * Start the backstop interval if it isn't already running.
+     *
+     * Demand-driven deliberately. It used to start in `setup()` and run for the
+     * life of the page whether or not anything was ever queued — a wakeup every
+     * three seconds forever, for a queue that is empty almost all of the time.
+     * That is a battery and background-work cost on mobile, and React Native
+     * takes this same branch because it defines `window`.
+     *
+     * The tick disarms itself once the queue drains; the next miss re-arms it
+     * through `scheduleTokenFlush`. While sends keep failing the queue stays
+     * non-empty and the interval keeps running, which is the case a backstop
+     * exists for.
+     */
+    private ensureBackstop;
+    private stopBackstop;
+    /**
+     * Stop background work. Queued tokens stay queued, and further discovery
+     * re-arms the backstop — this releases the timer, it does not discard work.
+     */
+    destroy(): void;
+    /**
+     * Send whatever is still queued while the page is going away.
+     *
+     * Even with the debounce there is always a window where a miss is queued
+     * and the document is torn down — a tab closing, a client-side navigation,
+     * or the discovery renderer finishing its grace period. A normal request is
+     * cancelled with the document; `keepalive` survives it.
+     *
+     * Deliberately NOT `navigator.sendBeacon`, the usual answer here: it cannot
+     * set custom headers, and our authorization is `x-Authorization`, so every
+     * beacon would be rejected.
+     *
+     * Fire-and-forget with no local bookkeeping — the page is leaving, so there
+     * is no "after" in which a cache write or queue mutation could matter, and
+     * skipping them keeps this off the critical path of teardown.
+     */
+    private flushOnTeardown;
+    /**
+     * `visibilitychange → hidden` is the reliable teardown signal; `pagehide`
+     * backs it up. `unload`/`beforeunload` are deliberately not used — they are
+     * unreliable on mobile and block bfcache.
+     */
+    private installTeardownFlush;
     setup(config: iLangsysConfig): void;
     /**
      * Record that a locale's catalog is already present without fetching —
@@ -247,42 +898,66 @@ declare class Translations {
      * later switch *to* it still flows through `change()` normally.
      */
     markLoaded(locale: string): void;
+    /**
+     * A catalog is present for rendering, but it is not the catalog of record:
+     * a snapshot (SNAP-3). Unlike `markLoaded` nothing is recorded as fetched,
+     * so the next settle for the locale still fetches the catalog and replaces
+     * it. What waits on `ready()` renders from it now.
+     */
+    markSeeded(): void;
     /**
      * React to a user-locale change. Fetches translations if we haven't
      * loaded this locale within the last 60s (or if forced).
      */
     change(locale: string, force?: boolean, skipFetch?: boolean): Promise<boolean>;
+    /** The project and locale a catalog belongs to: its cache key, request key and CACHE-2 pair. */
+    private catalogScope;
+    /** One catalog request for a project and locale, recording the outcome for CACHE-2's window. */
+    private fetchCatalog;
+    /**
+     * Record a failed send and push the next attempt out exponentially:
+     * 3s, 6s, 12s … capped at 5 minutes. Reset on the first success.
+     */
+    private noteSendFailure;
     private updateTokens;
+    /**
+     * WIRE-4: the catalog fetch failed. Settle `ready()` so consumers render their
+     * source text, and mark the catalog unusable for deciding what is missing.
+     *
+     * The second half is the one that needs saying. Measured before it existed, with
+     * write capability already granted: a network-failed fetch let `t()` misses queue
+     * and POST phrases that were already registered, and a failed locale switch did
+     * the same, because the new scope had just reset the catalog to empty.
+     */
+    private markCatalogUnavailable;
+    /**
+     * Fetch and publish the catalog for `this.locale`. Resolves false when it could not.
+     *
+     * The response publishes only while the locale and cache scope it was requested for are
+     * still current. A locale change while it is in flight supersedes it, and it is dropped
+     * when it lands: published, it would show the previous locale's catalog under the new
+     * one, persist it under the new locale's cache key, and stamp the new locale as loaded,
+     * so `change()` would not fetch that locale for another 60s. A superseded response still
+     * resolves true or false, which `fetchCatalog` records against its own pair (CACHE-2).
+     */
     private getTranslations;
 }
 
-interface HttpResponse {
-    status: number;
-    statusText: string;
-    url: string;
-    data: string;
-}
-interface ResponseObject {
-    status: boolean;
-    page?: number;
-    page_count?: number;
-    records_per_page?: number;
-    data?: object[] | object;
-    errors?: string[];
-    http?: HttpResponse;
-}
-
 interface iCountry {
+    /** Country name in the requested locale */
     label: string;
+    /** ISO 3166-1 alpha-2 country code (e.g., "ES") */
     code: string;
+    /** In the EU: VAT applies, and a business VAT ID makes it a reverse charge */
+    eu?: boolean;
 }
 type iCountryList = iCountry[];
 interface iCountryDialCode {
     /** ISO 3166-1 alpha-2 country code (e.g., "US", "CA", "GB") */
     country_code: string;
-    /** International dialing code with + prefix (e.g., "+1", "+44", "+33") */
+    /** International dialing code, digits only (e.g., "1", "44", "506") */
     dial_code: string;
-    /** Localized country name in the requested locale */
+    /** Country name in the requested locale with its dialing code (e.g., "Costa Rica (+506)") */
     name: string;
 }
 
@@ -317,34 +992,192 @@ declare class LangsysAppClass {
     private config;
     Translations: Translations;
     translationsLoadingPromise: Promise<unknown>;
-    private locales;
-    private countries;
-    private countriesLocale;
-    private dialCodes;
-    private dialCodesLocale;
-    private currencies;
-    private currenciesLocale;
+    /**
+     * The reference lists read so far (REF-1), keyed by list and display locale: a list the API
+     * answered is held for the core's lifetime, a read in flight is shared, and a failed read is
+     * remembered for CACHE-2's window under the credentials it was sent with. Memory only: on a server the core is the long-lived
+     * module, so the hold already outlives the request, and nothing goes to a cache another
+     * host reads (CACHE-1).
+     */
+    private referenceLists;
     debug: Logger;
     constructor();
     /** Current translation function. Reads fresh state on every call. */
     get t(): TFunction;
+    /**
+     * Supply (or replace) the write grant after `init()` has run.
+     *
+     * This is for apps whose token only exists once the user logs in — i.e.
+     * after the SDK has already booted. It is NOT the refresh path: the token
+     * is resolved fresh before every request and never cached, so refresh is a
+     * pull. Pass a provider function and let your auth layer decide when to
+     * mint; that also makes this safe to call while a request is in flight,
+     * since an in-flight request has already resolved its own token.
+     *
+     * Pass `undefined` to drop the grant (e.g. on logout).
+     */
+    setWriteGrant(grant: WriteGrant | undefined): Promise<void>;
+    /**
+     * Apply an `authorize-project` payload. Shared by `init` and the
+     * re-authorization in `setWriteGrant`, so a policy or capability change is
+     * picked up identically by both — previously the re-auth path silently
+     * ignored `auto_discovery` even though the response carries it.
+     */
+    private applyAuthorization;
+    /** A route change re-enters the SDK (HINT-13). See `Translations.notifyNavigation`. */
+    notifyNavigation(): void;
+    /**
+     * Put a catalog in place SYNCHRONOUSLY, with no network and no await.
+     *
+     * The hydration hand-off primitive: a framework's client entry calls this
+     * with the catalog the server already rendered from, before mount, so the
+     * first paint has translations instead of source text. `t()` returns the
+     * translation on the very next line — there is nothing to await, which is
+     * the whole point. `init()` can run afterwards, at its own pace, to
+     * authorize and take over refreshes.
+     *
+     * Does exactly what the `initialTranslations` hand-off inside `init()` does
+     * — injects `__uncategorized__`, stamps every `__category__`, publishes the
+     * catalog and the locale — because it IS that code now. Two
+     * implementations of "seed a catalog" would be two sets of rules about what
+     * a seeded catalog looks like.
+     *
+     * Safe to call before `init()`, after it, or both: `init()` will not
+     * re-seed a locale that is already seeded, so an SSR payload passed through
+     * config cannot clobber a catalog a client entry put there first.
+     *
+     * `served`, a request scope's `seed()`, hands over what the server rendered
+     * before any DOM class mounts: each block's source tokens, which a served
+     * translation re-renders from, and which blocks and phrases the server sends
+     * itself (`collected`), which the client then never registers. Nothing is
+     * registered here; `registerBlock(seededBlock)` after `init()` does that.
+     */
+    /**
+     * The request header that asks the app's own API for the user's language
+     * (FRM-6): `{ 'Accept-Language': 'es-es' }` for the locale the user chose,
+     * inside a request scope the scope's, else the loaded catalog's. Empty before
+     * any locale is known. Spread it into the headers of the app's API calls, so an
+     * API that answers per the negotiated language (FRM-5) answers in the user's,
+     * not the browser's default.
+     */
+    localeHeaders(): Record<string, string>;
+    seedCatalog(catalog: iCategories, locale: string, served?: {
+        blocks?: Record<string, SeededBlock>;
+        phrases?: readonly SeededPhrase[];
+    }): void;
+    /**
+     * Load a catalog snapshot (spec SNAP-2) SYNCHRONOUSLY as the preloaded
+     * catalog for `locale` — the current user locale by default, else the
+     * snapshot's base locale. A first render or an offline session then has
+     * its translations with no network call.
+     *
+     * The snapshot is a cache, never the catalog of record (SNAP-3): once
+     * `init()` runs, the catalog is fetched as usual and replaces it, and a
+     * phrase the snapshot lacks is found there. With no network the snapshot
+     * keeps rendering, and anything it lacks shows its source text.
+     *
+     * Throws `SnapshotError`, naming the reason, for a file that is not a
+     * snapshot, an unsupported version, a missing member, or a checksum the
+     * contents no longer match — an edited snapshot is refused, not served.
+     * Returns false when the snapshot holds no catalog for the locale.
+     */
+    loadSnapshot(snapshot: string | CatalogSnapshot, locale?: string): boolean;
+    /** Publish a catalog and its locale — the one set of rules for what a seeded catalog looks like. */
+    private publishSeed;
+    /**
+     * Render a server message entry (spec MSG-5): its `template` through `t()`
+     * under the messages category, filled from its `params`. When the catalog
+     * holds no translation for the template, the entry's own `message` is shown
+     * instead, which is the text the server filled and possibly localised; an
+     * entry with no `message` shows its template filled. An entry with no
+     * `template` is not looked up and shows its `message`. `message` is never
+     * used as a lookup key.
+     *
+     * The lookup goes through `t()` on a miss too, so the template is recorded
+     * like any other missing phrase. A plural in the translation renders from a
+     * numeric param through the catalog's ICU, with no ICU written by the caller.
+     */
+    renderServerMessage(entry: ServerMessage, category?: string): string;
+    /** Whether a catalog is already published for this locale. */
+    private isAlreadySeeded;
+    /** Read the current locale's catalog again, and the locale data `getLocaleName` reads, on its next load. */
     refresh(): Promise<boolean>;
     /**
      * Initialize Langsys. Configuration must include at least `projectid`,
      * `key`, and `UserLocaleStore` (anything satisfying `LocaleSource` — see
      * its docstring for framework-specific adapters).
      */
+    /**
+     * Whether `init()` accepted a project id, an API key and a locale store (WIRE-4). False
+     * before `init()` runs and after one refused for missing credentials. Authorization is a
+     * separate question: a configured client whose key the server refuses is still configured.
+     */
+    isConfigured(): boolean;
+    /**
+     * `init()` without credentials (WIRE-4). Nothing throws here: `t()` renders source text with
+     * its params filled, no miss is queued and no request is made, a component's block
+     * registration resolves skipped with reason `not-configured`, and an explicit write throws
+     * `LangsysConfigurationError`. With `requireCredentials`, `t()` throws it too.
+     */
+    private refuseUnconfigured;
     init(initConfig: iLangsysInitConfig): Promise<ResponseObject>;
+    /** The countries' dial codes, named in the display locale (REF-1). */
     getDialCodes(inLocale?: string): Promise<iCountryDialCode[]>;
+    /** The currencies, named in the display locale (REF-1). */
     getCurrencies(inLocale?: string): Promise<iCurrencyList>;
+    /** The countries, named in the display locale (REF-1). */
     getCountries(inLocale?: string): Promise<iCountryList>;
     getCountryName(forCountryCode: string, inLocale?: string): Promise<string>;
     getCurrencyName(forCurrencyCode: string, inLocale?: string): Promise<string>;
+    /** The locales in one of the API's three forms, named in the display locale (REF-1). */
     getLocalesFormat(format?: '' | 'flat' | 'data', inLocale?: string): Promise<iLocaleDefault | iLocaleFlat[] | iLocaleData[]>;
     getLocalesFlat(inLocale?: string): Promise<iLocaleFlat[]>;
+    /** `forceRefresh` is an explicit refresh: it reads the list again, held or inside a failure window, and holds what that read answers. */
     getLocalesData(inLocale?: string, forceRefresh?: boolean): Promise<iLocaleData[]>;
     getLocales(inLocale?: string): Promise<iLocaleDefault>;
+    /**
+     * Read one reference list in a display locale (REF-1), or answer the one held for it.
+     *
+     * The display locale is the one given, else the current one, canonical as the core serves
+     * it; one not shaped as a locale is refused before anything is sent, since it is written
+     * into the request. A locale form is asked for that locale alone and answers that locale's entry,
+     * whose key and codes are in the organisation's code format, so it is matched and recoded
+     * in WIRE-3's form; a locale the API does not hold answers `empty()`, held like any
+     * answer. Nothing here throws but `requireCredentials` (WIRE-4): a refused locale, a failed
+     * read and an answer not of the list's shape answer `empty()` with the cause logged, and
+     * a failed read is remembered for CACHE-2's window under its credentials, inside which a
+     * call under them sends nothing; a call under other credentials still reads, though one made
+     * while a read is in flight shares it, whoever sent it.
+     * An unconfigured core sends nothing and logs nothing, whatever the display locale,
+     * `init()`'s refusal being its one warning. Each caller gets its own copy of a held list,
+     * so what one caller does to it never reaches the next; `copy: false` is for the core's own
+     * lookups, which only read it.
+     */
+    private readReferenceList;
+    /**
+     * An explicit refresh of one list and display locale: the held list and every failure
+     * window go, so the next call reads. Each credentials' count of failures in a row stays, so
+     * a refresh that fails again widens CACHE-2's window as any failure in a row does.
+     */
+    private forgetReferenceList;
+    /**
+     * A reference list's display locale (REF-1): the one given, else the current one, each
+     * canonical, as the core normalises the locale it serves. The current locale is the one
+     * `t()` and the catalog serve, on both profiles: the request scope's, else the store's. So
+     * a given `iw-IL` and a store holding `iw-IL` both name their lists in `he-il`.
+     */
+    private displayLocale;
     getLocaleNameWithLookup(forLocale: string, shortName?: boolean, inLocale?: string): Promise<string>;
+    /**
+     * Synchronous locale-name lookup against the in-memory locales cache.
+     *
+     * The cache is only populated once `await getLocalesData(inLocale)` — or
+     * any `getLocaleNameWithLookup` call — has settled for that display locale.
+     * Called before then this returns `''`, the same value a genuinely unknown
+     * locale returns, so the two cases are told apart by the warning rather
+     * than by the return value. Use `getLocaleNameWithLookup` when you can
+     * await; it loads the data first.
+     */
     getLocaleName(forLocale: string, shortName?: boolean, inLocale?: string): string;
     /** @deprecated use `getLocaleNameWithLookup` or `getLocaleName` */
     getLanguageName(forLocale: string, shortName?: boolean, inLocale?: string): Promise<string>;
@@ -353,17 +1186,21 @@ declare class LangsysAppClass {
      *
      * - In browsers, uses `navigator.languages` with fallback to `navigator.language`.
      * - In SSR environments, parses the `Accept-Language` header.
+     *
+     * With `supportedLocales`, returns the best CLDR-aware match from that list
+     * or `false` when none of the user's preferences are supported — so the
+     * documented `detectPreferredLocale(header, supported) || 'en-us'` idiom
+     * actually reaches your default. Returning the user's own unsupported
+     * locale instead would send the app to fetch a catalog that does not
+     * exist, and the caller's `||` would never fire.
+     *
+     * Without `supportedLocales`, returns the user's first preference in
+     * canonical form, or `false` when no preference is detectable.
      */
     detectPreferredLocale(acceptLanguageHeader?: string | null, supportedLocales?: string[]): string | false;
     private getUserLanguagePreferences;
     private parseAcceptLanguageHeader;
     private findBestLocaleMatch;
-    /**
-     * Resolve the effective locale for a data-fetching helper: explicit
-     * argument, else the user's current locale, else the base locale —
-     * always in BCP 47 canonical form so cache keys and API routes agree.
-     */
-    private resolveLocale;
 }
 declare const LangsysApp: LangsysAppClass;
 
@@ -383,6 +1220,12 @@ interface TranslateOptions {
      * normalized back to `{name}` at capture.
      */
     params?: Record<string, ParamPrimitive>;
+    /**
+     * `false` renders from the catalog and registers nothing, on either lane (VAR-7):
+     * for a binding whose content holds values from variables it cannot name without
+     * its build-time transform. One debug notice says so. Default `true`.
+     */
+    register?: boolean;
 }
 /**
  * Wrap a DOM element and manage translation for its contents.
@@ -405,15 +1248,206 @@ declare class Translate {
     private isTokenizing;
     private lastTranslatedLocale;
     private custom_id;
-    private unsubscribeLocale;
+    private unsubscribers;
     /** Sorted params key-set already checked, so value-only updates don't re-warn. */
     private checkedParamKeys;
-    constructor(element: HTMLElement, options?: TranslateOptions);
+    /** The block this host registered as, kept so a navigation can re-record its miss. */
+    private contentBlock;
+    /**
+     * The id a renderer stamped on this host (MARK-3's identity), adopted rather
+     * than derived. Such a host renders from the catalog entry under that id, or
+     * its source text, and registers nothing.
+     */
+    private adoptedId;
+    /**
+     * Whether an adopted host's source tokens have been recovered: its DOM holds
+     * the text a server translated, never the source the catalog is keyed by.
+     */
+    private sourcesRecovered;
+    /** The locale an adopted host was served in; its served text is right for that locale. */
+    private servedLocale;
+    /** What the unit's value markers say (VAR-3): the runs among its tokens, and their values. */
+    private vars;
+    /** Each marked run's source, by its first node, where it was recovered rather than read. */
+    private runSources;
+    /** Each marked run's text nodes as first seen, before any render wrote them. */
+    private runOriginals;
+    /** Each marked value as first seen, for a render that emptied it. */
+    private markedValues;
+    /** Marked hosts inside this one that no instance managed, taken over by this walk. */
+    private takenOver;
+    /**
+     * SRV-5: the content captured at mount is provisional. A framework can mount a
+     * block showing a placeholder (a Suspense fallback, a lazy child's spinner)
+     * and swap in the real content a moment later. An observer watches the host's
+     * STRUCTURE (child lists, never text: a value update must not re-key a block);
+     * the first registration waits until it has been quiet for `SETTLE_MS`, and a
+     * later structural change re-derives the block and registers what it shows.
+     */
+    private observer;
+    private settleTimer;
+    /** Whether the subtree has been quiet for the settle window since mount. */
+    private settled;
+    private settleWaiters;
+    /** A structural change the tokens do not reflect yet. */
+    private dirty;
+    /** Whether the id is derived from the content, and so follows it when it changes. */
+    private derivedId;
+    /** The id this instance last registered under, so a re-key after the window can be reported. */
+    private registeredId;
+    /** The text this class last wrote into each text node (see `isUnitChange`). */
+    private written;
+    /** The whitespace at each end of a single-token unit's text as the page gave it (`writeKeepingEdges`). */
+    private edges;
+    /**
+     * @param byWalk Internal: set when an enclosing walk creates this instance for
+     *   a host nothing managed, so an instance the author constructs replaces it.
+     */
+    constructor(element: HTMLElement, options?: TranslateOptions, byWalk?: boolean);
+    /**
+     * HINT-13: after `notifyNavigation()`, re-enter the lookup as a re-render would, so a miss is
+     * recorded at the page's new URL — only while the host is attached to the document. An
+     * instance whose node was removed but never destroyed stays subscribed, and re-entering it
+     * would report the old page's content for the new one.
+     */
+    private reenterAfterNavigation;
     /** Update interpolation params (e.g. a changed count) and re-render. Mirrors `Phrase.setParams`. */
     setParams(params: Record<string, ParamPrimitive> | undefined): void;
-    /** Stop reacting to locale changes. Safe to call multiple times. */
+    /**
+     * Watch the host's structure (SRV-5). Not for an adopted host or one in a
+     * resolved scope: served content is already what it shows, and registers
+     * nothing. Where there is no `MutationObserver`, the content is settled at mount.
+     */
+    private observeStructure;
+    /**
+     * Whether a mutation changes what this unit shows. A changed child list always
+     * does. A changed text does only until the window first closes, and only when it
+     * is not the text this class wrote: a framework can swap a placeholder's text for
+     * its content in place, and what registers is what the block shows when the
+     * window closes. After that, a text change is a value update and never re-keys.
+     */
+    private isUnitChange;
+    /**
+     * Whether the unit changed since its tokens were read, counting changes the
+     * observer has not delivered yet: a framework's swap and a catalog arriving can
+     * fall in the same task, before the observer's callback runs.
+     */
+    private hasUnreadChange;
+    /** Write a text node, remembering the text, so the observer can tell this write from a framework's. */
+    private writeText;
+    /**
+     * Write a unit's one token with the text node's own whitespace kept at each end, as
+     * the block path keeps it: beside an excluded element (TOK-1) it is the space between
+     * two words. The ends are the page's, so a re-render never adds to them, and a text
+     * the framework has rewritten since gives its own.
+     */
+    private writeKeepingEdges;
+    /**
+     * Whether a changed child list belongs to this unit. An excised subtree, and
+     * each nested host, is another instance's. An `<option>`'s list is changed only
+     * by this class, writing its text.
+     */
+    private isUnitStructure;
+    private armSettle;
+    private markSettled;
+    private whenSettled;
+    /**
+     * The block's structure changed after it was read: read it again, under the id
+     * its content now derives (an app's or a stamped id stays), stamp it, render it,
+     * and register it if unknown. An id already sent for the earlier content stays
+     * registered; the core cannot take a registration back.
+     */
+    private rederive;
+    /** Stop reacting to locale and catalog changes. Safe to call multiple times. */
     destroy(): void;
+    /**
+     * Take over every marked host inside this one that no instance manages
+     * (MARK-2, MARK-3). The walk excises such a host from this unit (MARK-4), and
+     * without an instance of its own it would never register: a phrase host
+     * registers whole, as the one string its markup defines, and a block host
+     * registers as its own block or, when it carries a stamped id, renders under
+     * that id and registers nothing. Excluded subtrees are not entered, and a
+     * marked host's own inside is its instance's to walk.
+     */
+    private takeOverUnmanagedHosts;
     private translateUpdate;
+    /**
+     * An adopted host holds the text a renderer served, a translation when the
+     * page was served in another locale, and the catalog is keyed by source. Its
+     * source tokens come from the scope's seed, or the catalog entry the served text
+     * was rendered from, never from the DOM (SRV-4): each text node and attribute is
+     * given its source as the original it renders from. Until they are recovered the
+     * host is left as served, which is right for the locale it was served in; a
+     * later switch tries again, since a binding may hand the seed over after mount.
+     */
+    /**
+     * An adopted host re-rendered in another locale names that locale in its own
+     * resolved marker, so the marker keeps describing the text it holds. A marker
+     * with no locale (bare, `true`) is left as it is.
+     */
+    private restampResolvedLocale;
+    private recoverServedSources;
+    /**
+     * Render a single-token block.
+     *
+     * Prefers the content-block entry: the token may be stored as a block —
+     * registered under an explicit `custom_id`, by an older SDK, or seeded
+     * server-side — and flat `t()` cannot see inside block entries, so it would
+     * report a miss for content that is present. Falls back to `t()`, which
+     * also queues the miss for registration.
+     */
+    private renderSingleToken;
+    /**
+     * Whether the single-token fast path may claim this element.
+     *
+     * "One token" is NOT the same question as "one text node", and treating
+     * them as one was the defect. A translatable ATTRIBUTE is also a token, and
+     * an element carrying only an attribute token — `<img alt="…">`,
+     * `<input placeholder="…">` — has no text node anywhere in its subtree. The
+     * fast path would then write the translation as the element's text, and the
+     * element itself is gone.
+     *
+     * So the fast path requires an actual text node to write into. Everything
+     * else goes to the node-walking path, which already translates attributes
+     * in place and recurses, so a token on a nested element is reached too.
+     */
+    private usesSingleTextNodeFastPath;
+    /** A unit whose one token is a marked run is a phrase too (VAR-3, TOK-6): one sentence, with its values. */
+    private isSingleRun;
+    /** Whether this unit registers: not with `register: false`, and not when it is made only of markers (VAR-3, VAR-7). */
+    private registers;
+    /**
+     * The unique non-whitespace text node under `root`, or `null` when there is
+     * none or more than one — in which case the caller falls back to a flat
+     * text render, since there is no single place to put the result.
+     */
+    /**
+     * Publish the resolved `custom_id` on the host element.
+     *
+     * A server-rendered page is otherwise unreadable: the id is derivable only
+     * by re-running the tokenizer over the same subtree, which a reader holding
+     * just the HTML cannot do identically — and the tokenizer's own rules are
+     * what decide it. Stamping it makes the block self-describing, the same way
+     * a `Phrase` host already carries `PHRASE_MARKER_ATTR`.
+     *
+     * Written on every resolution, including when the migration fallback adopts
+     * a legacy id, so the attribute always names the id actually in use rather
+     * than the one first derived.
+     */
+    private stampContentBlockMarker;
+    /** The unit's first marked run, where its single-run token comes from. */
+    private findRun;
+    /** The node a run is known by: its first text node or marker. */
+    private runKey;
+    /** A run text node's text before any render wrote it. */
+    private runOriginal;
+    /** A marked value: the text the framework shows now, or, where a render emptied it, what it showed. */
+    private markedValue;
+    /** Write `template` into a marked run, around its values where it can (see `renderRun`). */
+    private writeRun;
+    /** A marked run inside a block: its translation under the block's id, else its source. */
+    private translateRun;
+    private findSingleTextNode;
     private tokenizeContent;
     private handleContentBlock;
     private translate;
@@ -427,15 +1461,185 @@ declare class Translate {
     /**
      * Interpolate `{name}`-style params into a resolved text, matching `t()`:
      * unknown keys fall through untouched, and the untranslated fallback is
-     * interpolated too. No-op when no params were supplied.
+     * interpolated too. Runs without params as well, since a text carrying ICU
+     * renders its `other` branch rather than its raw source (ICU-1). Plain text,
+     * braces included, comes back exactly as written.
      */
     private applyParams;
     private translateAttributes;
     private translateAttribute;
 }
 
-/** Attribute marker the `Translate` tokenizer uses to skip a `<Phrase>` subtree. */
-declare const PHRASE_MARKER_ATTR = "data-ls-phrase";
+/**
+ * Framework-agnostic content-block helpers.
+ *
+ * The DOM-mutating `Translate` class in `translate.ts` is one consumer of
+ * these — it walks a live element, tokenizes it, registers the content
+ * block, and mutates the same element in place. That model fits Svelte
+ * and vanilla JS, where the SDK genuinely owns the DOM node.
+ *
+ * For React/Vue/Angular wrappers, mutating the DOM directly is an anti-
+ * pattern — those frameworks own their rendered output. Wrappers should
+ * import the helpers below to handle the framework-agnostic parts (token
+ * discovery, content-block registration, dedup against the local cache)
+ * and render translated content through their framework's native means.
+ *
+ * Wrapper pattern:
+ *
+ *   1. After mount, grab the rendered DOM via the framework's ref/binding.
+ *   2. `const { tokens, content } = tokenizeElement(el);`
+ *   3. `const customId = generateCustomId(category, tokens);`
+ *   4. `if (!isContentBlockKnown(category, customId)) {`
+ *      `    await registerContentBlock({ custom_id: customId, category, content, tokens, label });`
+ *      `}`
+ *   5. Subscribe to `sTranslations` + `currentlyLoadedLocale`; on change,
+ *      look up each token via `Translations.lookupContent(category, customId, token)`
+ *      and render via your framework's templating.
+ */
+
+/**
+ * Attributes that mark a subtree as a self-managed "keep-together" phrase,
+ * which the block tokenizer must skip rather than split at tag boundaries.
+ *
+ * Two spellings, because two SDKs mark the same thing:
+ *  - `data-ls-phrase` — set by this SDK's framework `<Phrase>` components.
+ *  - `data-langsys-phrase` — `langsys-php`'s author-facing marker, which
+ *    survives into `translatePage()` output.
+ *
+ * The distinction is invisible in normal use, but on SSR handoff there is only
+ * ONE DOM: a page rendered by PHP and then hydrated by a JS SDK is walked by
+ * both implementations, so this tokenizer has to recognise PHP's marker or it
+ * re-tokenizes a subtree PHP deliberately kept whole. Recognising both is
+ * additive — `data-langsys-phrase` never appears in DOM our components emit.
+ */
+/**
+ * True when an element is marked as a self-managed phrase by either SDK.
+ *
+ * Presence alone means intent, like any boolean HTML attribute — but an
+ * explicit `="false"` or `="0"` opts OUT, compared after trimming. Mirrors
+ * `langsys-php`'s `isPhraseMarked()` exactly (same method name in both SDKs,
+ * so the correspondence is checkable at a glance). Without the opt-out we
+ * would skip a subtree the author had deliberately un-marked, and it would
+ * then be translated by neither SDK.
+ */
+declare function isPhraseMarked(element: Element): boolean;
+/**
+ * True iff the local translations cache already has the content block
+ * for the given `(category, customId)` — meaning the backend knows about
+ * it and there's no need to re-register.
+ *
+ * The cache is keyed under `'__uncategorized__'` for null/empty categories,
+ * matching the convention the server uses in its GET /translations response.
+ */
+declare function isContentBlockKnown(category: string, customId: string): boolean;
+/**
+ * Why a registration did not reach the server, or did not take (REG-10).
+ *
+ * - `not-configured`: the client has no credentials, so nothing can be sent
+ *   (WIRE-4);
+ * - `not-write-enabled`: the session may not write, so the block was handed to
+ *   the discovery lane instead;
+ * - `catalog-unavailable`: the catalog fetch failed, so an unknown block cannot
+ *   be told from a registered one (WIRE-4);
+ * - `base-locale-gate`: the project registers only at its base locale (GATE-9);
+ * - `deferred`: the block was found inside a request scope, which holds it for its
+ *   flush after the response (SRV-3, SRV-7);
+ * - `client-strategy`: the SSR token strategy leaves collection to the client
+ *   (SSR-1), or a write grant made capability per-user (SSR-2);
+ * - `refused`: the server answered the request with a failure;
+ * - `failed`: the request did not complete.
+ */
+type RegistrationReason = 'not-configured' | 'not-write-enabled' | 'catalog-unavailable' | 'base-locale-gate' | 'deferred' | 'client-strategy' | 'refused' | 'failed';
+/**
+ * What a registration did. Success only when the server stored the block. A
+ * write skipped on purpose is `{ status: false, skipped: true, reason }`, and one
+ * that failed is `{ status: false, reason, errors }`, so a caller can tell them
+ * apart and neither reads as success.
+ */
+type RegistrationResult = {
+    status: true;
+} | {
+    status: false;
+    skipped: true;
+    reason: 'not-configured' | 'not-write-enabled' | 'catalog-unavailable' | 'base-locale-gate' | 'deferred' | 'client-strategy';
+} | {
+    status: false;
+    skipped?: false;
+    reason: 'refused' | 'failed';
+    errors?: unknown[];
+};
+/**
+ * POST a content block to the backend, then stamp its custom_id into the local
+ * translations cache, so later mounts in this session, and later reloads since
+ * the cache is persisted, skip the POST.
+ *
+ * A block has one request in flight at a time under one set of credentials
+ * (REG-7). A call for a block whose request has not answered yet resolves with
+ * that request's result and sends nothing: a binding calls `registerBlock` on
+ * every change `t` goes through, and a page load makes several of those before
+ * the first request returns. Once it answers, the block is known, or, refused or
+ * failed, may be sent again. A request answers only for the project and key it
+ * went out under, so a call under others, after a re-init, sends its own.
+ *
+ * One behaviour on every path (REG-10): never throws, always logs, and never
+ * reports success for work that did not happen. A skipped write returns a
+ * non-success result naming its reason.
+ */
+declare function registerContentBlock(contentBlock: iContentBlock): Promise<RegistrationResult>;
+/**
+ * Walk an `HTMLElement`, collecting tokens for translation and producing a
+ * cloned-and-stylized snapshot of its content for the Translation Manager.
+ *
+ * Tokens harvested:
+ *  - text-node content (whitespace-normalized, trimmed)
+ *  - translatable attribute values (`placeholder`, `alt`, `title`, `aria-*`, etc.)
+ *  - button/input/select value text
+ *
+ * Skips subtrees marked with `translate="no"`.
+ *
+ * The returned `content` is a string snapshot of the element's children, as the
+ * tree path registers a block's nodes: the host is the unit, not part of its
+ * content. The live element is not mutated. Computed semantic styles (color,
+ * font, spacing, etc.) are inlined onto the clone so translators see content
+ * styled the way end-users do. It holds no value and no nested unit's content
+ * (`scrubContent`).
+ *
+ * Requires that `element` is mounted in the document so `getComputedStyle`
+ * can read its style. For SSR / pre-mount callers, the style capture step
+ * silently no-ops and the snapshot is plain (without inlined styles).
+ */
+declare function tokenizeElement(element: HTMLElement): {
+    tokens: string[];
+    content: string;
+    vars: UnitVars;
+};
+/**
+ * The token list this element would have produced before 0.6.3, when every
+ * `<option>`'s text was harvested twice — once by a `<select>` special case and
+ * again by the ordinary text-node walk.
+ *
+ * **Lookup only.** Content blocks registered by an older SDK are keyed by an id
+ * derived from this list, so `Translate` falls back to it when the corrected id
+ * misses; without that, every block containing a `<select>` would silently
+ * re-key and lose its translations on upgrade. Registration always uses the
+ * corrected list, so the legacy-keyed population can only shrink.
+ *
+ * Skips the computed-style capture that `tokenizeElement` performs — this is a
+ * cache-key computation, not a snapshot for translators.
+ *
+ * @deprecated Migration aid; will be removed once catalogs have been rebased.
+ */
+declare function legacyTokenizeElement(element: HTMLElement): string[];
+/** What the walk learns from value markers (VAR-3), alongside the tokens. */
+interface UnitVars {
+    /** Each marker's value, by name: the params the unit renders with, unless the caller names them. */
+    values: Record<string, string>;
+    /** The indices of tokens that are marked runs. */
+    runs: number[];
+    /** The indices of tokens made only of markers, with no text of their own. */
+    markerOnly: number[];
+}
+
 interface PhraseOptions {
     /** Category the phrase registers under (disambiguation for translators). */
     category?: string;
@@ -448,6 +1652,12 @@ interface PhraseOptions {
      * normalized back to `{n}` at capture.
      */
     params?: Record<string, ParamPrimitive>;
+    /**
+     * `false` renders from the catalog and registers nothing (VAR-7): for a binding
+     * whose phrase holds values from variables it cannot name without its build-time
+     * transform. One debug notice says so. Default `true`.
+     */
+    register?: boolean;
 }
 /**
  * DOM handler for a markup-bearing "rich" phrase (`<Phrase>`).
@@ -465,13 +1675,37 @@ declare class Phrase {
     private host;
     private category;
     private params;
+    private register;
+    /** Each marked value in the host (VAR-3), by name: params the caller's own override. */
+    private values;
     private phrase;
     private slots;
+    /** The key a phrase holding an opaque element was registered under before TOK-1: looked up on a miss, never registered. */
+    private earlier;
+    /**
+     * A phrase made only of value markers (VAR-3) or of opaque elements (TOK-1) has no
+     * text of its own, and registers nothing, on mount or on a navigation.
+     */
+    private textless;
+    /** The text of each opaque element that takes params, as the page gave it: where a caller's param can land (TOK-1). */
+    private opaqueTexts;
+    /**
+     * The markup slot each element in the host renders. An element's place is its
+     * slot only while the host shows the source's order; a translation that
+     * reorders its markup, served or rendered here, moves them.
+     */
+    private slotOf;
+    /** A served translation whose source phrase is not recovered yet (see `recoverServed`). */
+    private servedUnrecovered;
     private unsubscribers;
     private ready;
     /** Sorted params key-set already checked, so value-only updates don't re-warn. */
     private checkedParamKeys;
-    constructor(host: HTMLElement, options?: PhraseOptions);
+    /**
+     * @param byWalk Internal: set when an enclosing walk creates this instance for
+     *   a host nothing managed, so an instance the author constructs replaces it.
+     */
+    constructor(host: HTMLElement, options?: PhraseOptions, byWalk?: boolean);
     /** Update interpolation params (e.g. a changed count) and re-render. */
     setParams(params: Record<string, ParamPrimitive> | undefined): void;
     /** Stop reacting to locale/translation changes. Safe to call multiple times. */
@@ -483,6 +1717,15 @@ declare class Phrase {
      * re-warn on every render.
      */
     private _checkParams;
+    /**
+     * Inside a resolved scope the host holds a translation a server served, and the
+     * catalog is keyed by source: the source phrase is the one catalog entry that
+     * renders as the served text (`recoverPhraseSource`), never the DOM's text. Its
+     * elements are mapped to the source's slots by the order the served translation
+     * opened them. Until it is recovered the host renders from its served text,
+     * which is right for the locale it was served in.
+     */
+    private recoverServed;
     private _render;
 }
 
@@ -514,6 +1757,12 @@ declare class Phrase {
 interface RichSlot {
     /** Shallow clone of the original element — preserves tag, class, href, etc. */
     template: HTMLElement;
+    /**
+     * For an element opaque in the phrase (TOK-1), the element itself: it renders its
+     * own content as given, so reconstitution moves it rather than a copy, and what a
+     * framework renders inside it stays the framework's.
+     */
+    source?: HTMLElement;
 }
 interface EncodedRichText {
     /**
@@ -523,6 +1772,18 @@ interface EncodedRichText {
     phrase: string;
     /** Captured inline elements, indexed by markup-token slot number. */
     slots: RichSlot[];
+    /** Each marked value, by name (VAR-3): the params the phrase renders with, unless the caller names them. */
+    values: Record<string, string>;
+    /**
+     * For a phrase holding an opaque element, the key it was registered under before
+     * TOK-1 bound this path, with that key's slots and values: looked up on a miss for
+     * `phrase`, never registered.
+     */
+    earlier?: {
+        phrase: string;
+        slots: RichSlot[];
+        values: Record<string, string>;
+    };
 }
 /**
  * Walk an element's subtree and produce the encoded phrase + captured slots.
@@ -530,6 +1791,24 @@ interface EncodedRichText {
  * Text nodes contribute their (whitespace-collapsed) text. Each child element
  * becomes a markup-token pair wrapping its recursively-encoded contents, and a
  * shallow clone of the element is captured as a slot. Nesting is preserved.
+ *
+ * COALESCING ADJACENT TEXT NODES IS CORRECT HERE — do not "fix" it.
+ *
+ * `_encodeNodes` concatenates adjacent text nodes and this function collapses
+ * whitespace, producing ONE phrase string. That string is the lookup key:
+ * `Phrase` calls `Translations.t(phrase, category)` and never computes a
+ * `custom_id`. A sentence must survive the round trip whole — that is the
+ * entire reason `<Phrase>` exists, since splitting `Based on {n}
+ * <strong>reviews</strong>` into fragments makes correct agreement impossible
+ * in languages with more than two plural forms.
+ *
+ * The `_walkForTokens` contract in `content-block.ts` says the OPPOSITE, for
+ * the content-block path, where token-array arity is identity. Both are right
+ * for their own path. If you arrived here from that comment intending to make
+ * this consistent with it, the paths are not meant to agree.
+ *
+ * Pinned by `tests/content-block-identity.test.ts` ("Phrase path"), which
+ * fails if this coalescing is removed.
  */
 declare function encodeRichText(root: HTMLElement): EncodedRichText;
 /**
@@ -538,340 +1817,306 @@ declare function encodeRichText(root: HTMLElement): EncodedRichText;
  * carries machine-findable delimiters for reconstitution.
  */
 declare function markupTokenValues(slotCount: number): Record<string, string>;
-/**
- * Rebuild DOM nodes from a resolved string containing sentinel-delimited spans.
- *
- * The original (framework-owned) elements are reused as wrappers — so scoped
- * CSS classes / attributes survive — with the translated text placed inside.
- *
- * Robust to model mistakes: if sentinels are unbalanced (a tag dropped or a
- * stray close), we fall back to a single plain-text node (markers stripped) —
- * "lose the markup, keep the meaning" rather than throw.
- */
-declare function reconstitute(resolved: string, slots: RichSlot[], doc?: Document): Node[];
+declare function reconstitute(resolved: string, slots: RichSlot[], doc?: Document, onElement?: (element: HTMLElement, slot: number) => void): Node[];
 /** Remove any sentinel markers from a string, leaving the bare text. */
 declare function stripSentinels(value: string): string;
 
-declare class LangsysAppAPIClass {
-    private apiurl;
-    config: iLangsysConfig;
-    private headers;
-    constructor();
-    setup(config: iLangsysConfig): void;
-    /** Optional hook to point the client at a different API host. */
-    setBaseUrl(url: string): void;
-    validate(config: iLangsysConfig): Promise<ResponseObject>;
-    getTranslations(locale: string): Promise<ResponseObject>;
-    /**
-     * Register phrases and/or content blocks via the current unified endpoint.
-     * Each item carries `type: 'phrase' | 'content_block'`. Replaces the
-     * deprecated `projects/{id}/tokens` and `projects/{id}/content-blocks` routes.
-     */
-    createTranslatableItems(items: Array<Record<string, unknown>>): Promise<ResponseObject>;
-    post(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
-    get(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
-    delete(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
-    patch(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
-    put(path: string, data?: Record<string, unknown>): Promise<ResponseObject>;
-    private send;
-}
-declare const LangsysAppAPI: LangsysAppAPIClass;
-
-interface iContentBlock {
-    custom_id: string;
-    category: string;
-    content: string;
-    label?: string;
-    tokens: string[];
-}
-
 /**
- * Framework-agnostic content-block helpers.
+ * Minimal synchronous storage contract for `persist` — structurally a subset of
+ * the DOM `Storage` interface, so `localStorage` satisfies it as-is.
  *
- * The DOM-mutating `Translate` class in `translate.ts` is one consumer of
- * these — it walks a live element, tokenizes it, registers the content
- * block, and mutates the same element in place. That model fits Svelte
- * and vanilla JS, where the SDK genuinely owns the DOM node.
- *
- * For React/Vue/Angular wrappers, mutating the DOM directly is an anti-
- * pattern — those frameworks own their rendered output. Wrappers should
- * import the helpers below to handle the framework-agnostic parts (token
- * discovery, content-block registration, dedup against the local cache)
- * and render translated content through their framework's native means.
- *
- * Wrapper pattern:
- *
- *   1. After mount, grab the rendered DOM via the framework's ref/binding.
- *   2. `const { tokens, content } = tokenizeElement(el);`
- *   3. `const customId = generateCustomId(category, tokens);`
- *   4. `if (!isContentBlockKnown(category, customId)) {`
- *      `    await registerContentBlock({ custom_id: customId, category, content, tokens, label });`
- *      `}`
- *   5. Subscribe to `sTranslations` + `currentlyLoadedLocale`; on change,
- *      look up each token via `Translations.lookupContent(category, customId, token)`
- *      and render via your framework's templating.
+ * Synchronous on purpose: `persist` seeds its signal during module
+ * initialization, so an async backend could not be read in time. React Native
+ * apps inject a synchronous adapter (MMKV, or an in-memory mirror of
+ * AsyncStorage hydrated at startup) via `setPersistStorage`.
  */
-
+interface PersistStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    /** Optional. Used to drop superseded keys; absent on minimal adapters. */
+    removeItem?(key: string): void;
+}
 /**
- * Attributes that mark a subtree as a self-managed "keep-together" phrase,
- * which the block tokenizer must skip rather than split at tag boundaries.
+ * Inject the storage backend used by every `persist` signal — those created
+ * afterwards AND those that already exist.
  *
- * Two spellings, because two SDKs mark the same thing:
- *  - `data-ls-phrase` — set by this SDK's framework `<Phrase>` components.
- *  - `data-langsys-phrase` — `langsys-php`'s author-facing marker, which
- *    survives into `translatePage()` output.
+ * Re-hydrating the existing ones is the point, not a nicety: the catalog store
+ * is built at module load, long before a React Native app can hand us MMKV, so
+ * an injection that only applied going forward would apply to none of the
+ * signals anyone cares about.
  *
- * The distinction is invisible in normal use, but on SSR handoff there is only
- * ONE DOM: a page rendered by PHP and then hydrated by a JS SDK is walked by
- * both implementations, so this tokenizer has to recognise PHP's marker or it
- * re-tokenizes a subtree PHP deliberately kept whole. Recognising both is
- * additive — `data-langsys-phrase` never appears in DOM our components emit.
+ * Pass `null` to drop the injection and return to auto-detection.
  */
-declare const PHRASE_MARKER_ATTRS: readonly ["data-ls-phrase", "data-langsys-phrase"];
+declare function setPersistStorage(storage: PersistStorage | null): void;
 /**
- * True when an element opts out of translation entirely — it and its subtree
- * are skipped by the tokenizer.
+ * Create a Signal whose value is persisted to storage when one is available: an
+ * injected `PersistStorage` first, else `localStorage`. Falls back to in-memory
+ * behaviour during SSR, or when storage is unavailable or quota-exceeded.
+ * Stored value is JSON-encoded.
  *
- * Mirrors `langsys-php`'s `HtmlParser::isTranslationExcluded()` exactly:
- *  - `translate="no"` — the HTML standard attribute, matched case-insensitively.
- *  - `data-notrans` — PHP's author-facing alias, for hosts whose templating
- *    strips unknown bare attributes or where `translate` collides with another
- *    tool. Presence is intent; an explicit `"false"`/`"0"` opts out of the
- *    opt-out, compared after trimming.
+ * `legacyKey` is READ but never written, so a renamed key migrates its cache on
+ * first load instead of silently dropping it. A host app that downgrades the
+ * SDK still finds its old value where it left it.
  *
- * Honoring PHP's alias matters for the same reason as the phrase marker: on SSR
- * handoff there is ONE DOM, and content an author marked "do not translate"
- * must not be extracted and registered by whichever SDK happens to walk it.
+ * DO NOT persist `writeEnabled`, `autoDiscovery`, or any other session
+ * capability. "Cache it like translations for a faster warm start" is the
+ * obvious next optimization and it is wrong twice over:
  *
- * Both this and `isPhraseMarked` trim before comparing. They briefly differed
- * — PHP's phrase check predated the trim its exclusion check gained — and the
- * gap was resolved by asking rather than tidying: mirror exactly, flag the
- * wart, let the owner decide. Divergence-by-tidying is the same failure class
- * as divergence-by-oversight, just better intentioned.
- */
-declare function isTranslationExcluded(element: Element): boolean;
-/**
- * True when an element is marked as a self-managed phrase by either SDK.
+ *  1. A persisted value is restored SYNCHRONOUSLY at module init, so the client
+ *     would mount with a concrete capability while the server rendered from
+ *     `undefined` — a hydration mismatch on every consumer, not just the ones
+ *     that resolve auth before first render.
+ *  2. Write capability is per-session and IP-dependent: the same key answers
+ *     differently from different networks, and a grant makes it per-user.
+ *     Persisting it caches one session's answer across later sessions on a
+ *     shared device — the same unsoundness as caching it on an SSR singleton.
  *
- * Presence alone means intent, like any boolean HTML attribute — but an
- * explicit `="false"` or `="0"` opts OUT, compared after trimming. Mirrors
- * `langsys-php`'s `isPhraseMarked()` exactly (same method name in both SDKs,
- * so the correspondence is checkable at a glance). Without the opt-out we
- * would skip a subtree the author had deliberately un-marked, and it would
- * then be translated by neither SDK.
+ * Translations are safe to persist because they are project-scoped content, not
+ * a permission decision. Capability is re-derived from the server every time.
  */
-declare function isPhraseMarked(element: Element): boolean;
+declare function persist<T>(key: string, initial: T, legacyKey?: string): Signal<T>;
+
 /**
- * Compute the deterministic content-block id from a `(category, tokens)` pair.
+ * A host's own "the app is going away" signal, for runtimes with no `document` to listen to.
  *
- * JSON-stringifies the tuple so each token is unambiguously delimited
- * (the previous `tokens.join('-')` was collision-prone for tokens
- * containing a hyphen, e.g. `'e-mail'`).
+ * In a browser the core flushes queued registrations itself, on `visibilitychange → hidden` and
+ * `pagehide` (REG-3). React Native defines `window` but has no `document`, so those listeners
+ * cannot exist there, and anything still queued when the app is backgrounded or killed would be
+ * lost. `setTeardownSignal` lets the host supply the signal instead: the React Native binding
+ * adapts `AppState` leaving `active`, and the core keeps the send.
  *
- * Pure function — same inputs always produce the same id. Exported so
- * framework wrappers can compute the id themselves before deciding
- * whether to call `registerContentBlock`.
+ * Same shape as `setPersistStorage`: a module-level injection that reaches every `Translations`
+ * instance, those set up before it and after.
  */
-declare function generateCustomId(category: string, tokens: string[]): string;
 /**
- * The id this block would have had before the 0.6.0 MD5 fix.
- *
- * **Lookup only — never register under this.** Blocks registered by an older
- * SDK are keyed by it, so `Translate` falls back to it when the corrected id
- * misses, which keeps existing translations resolving instead of orphaning
- * them. Registering under it would keep minting ids from a hash that both
- * diverges across SDKs and can collide.
- *
- * Note the collision is a property of the FINAL hashed string, not the phrase:
- * `JSON.stringify` shifts every character's offset, so the same phrase pair can
- * collide standalone and not collide here — and changing `category` moves every
- * character into different lanes. Always reason at this level, not at `md5()`.
- *
- * @deprecated Migration aid; will be removed once catalogs have been rebased.
+ * Subscribe `fire` to the host's teardown signal and return a function that unsubscribes it.
+ * The core calls `fire` nothing else: firing it runs the ordinary teardown flush.
  */
-declare function generateLegacyCustomId(category: string, tokens: string[]): string;
+type TeardownSubscribe = (fire: () => void) => (() => void) | void;
 /**
- * True iff the local translations cache already has the content block
- * for the given `(category, customId)` — meaning the backend knows about
- * it and there's no need to re-register.
+ * Inject the host's teardown signal, replacing any previous one. The previous subscription is
+ * released first, so a re-injection — React Native's Fast Refresh, a test — never leaves two
+ * live subscriptions that would flush twice. `null` releases the current one and injects none.
  *
- * The cache is keyed under `'__uncategorized__'` for null/empty categories,
- * matching the convention the server uses in its GET /translations response.
+ * Fire it once per departure, edge-triggered, as the app leaves the foreground: the flush sends
+ * what is queued, and firing again while nothing is queued sends nothing.
  */
-declare function isContentBlockKnown(category: string, customId: string): boolean;
+declare function setTeardownSignal(subscribe: TeardownSubscribe | null): void;
+
 /**
- * POST a content block to the backend, then stamp its custom_id into the
- * local translations cache so subsequent mounts in this session — and
- * subsequent reloads, since the cache is persisted — skip the POST.
+ * Request scopes (spec SRV-7): rendering on a server without one visitor's
+ * state reaching the next.
  *
- * Mirrors the standalone-phrase path's cache writeback semantics. Respects
- * `key_type === 'write'`: read-only keys silently no-op (resolves with
- * `{ status: true }` so the caller can still render the cached translation).
+ * The core keeps one catalog, one locale and one miss queue in module state,
+ * which is right for a page and wrong for a server process rendering for many
+ * visitors at once. A scope holds its own: its locale, its view of the catalog,
+ * the misses its render records, and the seed its page hands the client. A
+ * binding opens one in its framework's request hook, renders inside `run()`,
+ * serialises `seed()` into the page, and calls `close()` after the response.
  *
- * Errors are logged via the SDK's logger and returned as `{ status: false }`
- * — never thrown. Callers can decide whether to surface to UI or swallow.
+ * A catalog is fetched at most once per request, and shared read-only (frozen)
+ * with scopes rendering the same locale under the same credentials within a
+ * minute, so a busy locale costs one fetch rather than one per visitor. Nothing a
+ * scope writes is visible to another scope or to the page.
+ *
+ * A scope may carry its own project id and API key (SRV-2), for a process that
+ * renders for more than one project: every request the scope makes goes out under
+ * them, and a scope given none sends under the module-wide ones `init()` set.
  */
-declare function registerContentBlock(contentBlock: iContentBlock): Promise<{
-    status: boolean;
-    errors?: unknown[];
-}>;
+interface RequestScopeOptions {
+    /** The request's locale, as the framework or SRV-6 resolved it. */
+    locale: string;
+    /** A catalog already in hand (a snapshot, an upstream fetch); otherwise it is fetched. */
+    catalog?: iCategories;
+    /** The page's URL, for the records this scope keeps. */
+    url?: string;
+    /**
+     * The project id and API key this scope's requests send under, with the write grant
+     * that goes with them (SRV-2): its catalog fetch, its `close()`, and every request a
+     * render inside it makes. Without them the scope sends under the module-wide ones.
+     * Never part of `seed()`.
+     *
+     * Its key's write capability is the one its catalog fetch reports, so a scope handed
+     * both a catalog and credentials of its own has no answer for its key and sends
+     * nothing at `close()`; the client registers what it missed.
+     */
+    credentials?: ApiCredentials;
+}
+/** A phrase a scope's render missed. */
+interface ScopeMiss {
+    category: string;
+    phrase: string;
+}
+interface RequestScope {
+    readonly locale: string;
+    /** `t()` over this scope's catalog; its misses are this scope's. */
+    readonly t: TFunction;
+    /**
+     * Run `fn` inside the scope: top-level `t()`, `LangsysApp.t`, `tSignal.get()`,
+     * and the lookups and registrations `Translate` and `Phrase` make, resolve to
+     * it. Across `await` only once `setRequestScopeStorage` has an
+     * `AsyncLocalStorage`; otherwise only code that finishes inside `fn`.
+     *
+     * The `t` that `tSignal.get()` returns reads the catalog when it is CALLED, not
+     * when it was taken: kept and called after `fn` returns, it reads the page's.
+     * A host wrapping `t` for its components returns `scope.t`, which is this
+     * scope's wherever it is called.
+     */
+    run<R>(fn: () => R): R;
+    /**
+     * Make the scope current for the rest of the current async context, where the
+     * render cannot be wrapped in `run()`. Requires `setRequestScopeStorage` to
+     * have been given an `AsyncLocalStorage`; throws otherwise.
+     *
+     * It holds only in the continuation that itself performs the render: called
+     * inside a function the host awaits and returns from (a Nuxt plugin, a Nitro
+     * request hook, an awaited helper), the scope is gone when that function
+     * returns, before or after its own `await` alike. So call `enter()` in the
+     * function that renders, `run()` everywhere else, and hand the scope to the
+     * app through the framework's own injection when the host awaits you.
+     */
+    enter(): void;
+    /**
+     * The hydration seed (SRV-4): on the client, `LangsysApp.seedCatalog(seed.catalog,
+     * seed.locale, seed)` before hydration. `blocks` names every block the scope
+     * rendered through `renderBlock`, by id, with its category, source tokens and
+     * shape, for a client that cannot recover a block's source from DOM already
+     * holding the translation; hand each to `registerBlock` after `init()`.
+     * `phrases` lists the phrases the render missed. A block or phrase the scope
+     * sends itself at `close()` is marked `collected`, and the client never
+     * registers it.
+     */
+    seed(): RequestSeed;
+    /** The phrases this scope's render missed. */
+    misses(): readonly ScopeMiss[];
+    /**
+     * After the response (SRV-3): send what the render missed, when the key the
+     * scope sends under may write and the SSR strategy collects on the server,
+     * then stop recording. Resolves what happened; never throws. Calling it
+     * again resolves the first result.
+     */
+    close(): Promise<RegistrationResult>;
+}
 /**
- * Walk an `HTMLElement`, collecting tokens for translation and producing a
- * cloned-and-stylized snapshot of its outerHTML for the Translation Manager.
- *
- * Tokens harvested:
- *  - text-node content (whitespace-normalized, trimmed)
- *  - translatable attribute values (`placeholder`, `alt`, `title`, `aria-*`, etc.)
- *  - button/input/select value text
- *
- * Skips subtrees marked with `translate="no"`.
- *
- * The returned `content` is a string snapshot — the live element is not
- * mutated. Computed semantic styles (color, font, spacing, etc.) are inlined
- * onto the clone so translators see content styled the way end-users do.
- *
- * Requires that `element` is mounted in the document so `getComputedStyle`
- * can read its style. For SSR / pre-mount callers, the style capture step
- * silently no-ops and the snapshot is plain (without inlined styles).
+ * Open a request scope. Resolves once its catalog is in hand: the one passed,
+ * one fetched within the last minute for the same credentials and locale, or a
+ * fresh fetch. A fetch that fails leaves the scope rendering source text and
+ * recording nothing, as the page does while its catalog is unavailable
+ * (WIRE-4). Credentials without both a project id and a key reject with
+ * `LangsysConfigurationError`, before anything is sent.
  */
-declare function tokenizeElement(element: HTMLElement): {
-    tokens: string[];
-    content: string;
-};
+declare function createRequestScope(options: RequestScopeOptions): Promise<RequestScope>;
 /**
- * The token list this element would have produced before 0.6.3, when every
- * `<option>`'s text was harvested twice — once by a `<select>` special case and
- * again by the ordinary text-node walk.
+ * The request scope a server rendered, rebuilt on the client from its seed, at
+ * once and synchronously: for a host whose client render must run inside the
+ * same scope as the server's (React's hydration render, which reads the server
+ * snapshot), and whose provider cannot await. Its `t` reads the seed's catalog
+ * in the seed's locale, so the hydration render produces the served text.
  *
- * **Lookup only.** Content blocks registered by an older SDK are keyed by an id
- * derived from this list, so `Translate` falls back to it when the corrected id
- * misses; without that, every block containing a `<select>` would silently
- * re-key and lose its translations on upgrade. Registration always uses the
- * corrected list, so the legacy-keyed population can only shrink.
- *
- * Skips the computed-style capture that `tokenizeElement` performs — this is a
- * cache-key computation, not a snapshot for translators.
+ * It sends nothing itself: the server's scope decided at its own `close()`. What
+ * its render misses, and the blocks it registers, go to the page's lanes as a
+ * render outside any scope would, which skip what the seed marks `collected`
+ * (the seed's blocks and phrases are remembered here, as `seedCatalog` remembers
+ * them), so under the `client` strategy the client still registers them.
  *
- * @deprecated Migration aid; will be removed once catalogs have been rebased.
- */
-declare function legacyTokenizeElement(element: HTMLElement): string[];
-
-/**
- * Create a Signal whose value is persisted to localStorage (when available).
- * Falls back to in-memory behavior during SSR or when storage is unavailable
- * or quota-exceeded. Stored value is JSON-encoded.
+ * A host that wraps `t` for its components returns `scope.t`, never a `t` taken
+ * from `tSignal.get()` inside `run()`: that one reads the catalog when it is
+ * called, and called later in the render, outside `run()`, it reads the page's.
  */
-declare function persist<T>(key: string, initial: T): Signal<T>;
+declare function scopeFromSeed(seed: RequestSeed): RequestScope;
+/** The request scope the current code runs in, if any. */
+declare function currentRequestScope(): RequestScope | undefined;
+/** Forget every shared catalog, so the next scope for each locale fetches afresh. */
+declare function clearSharedCatalogs(): void;
 
-declare const sTranslations: Signal<iCategories>;
-declare const currentlyLoadedLocale: Signal<string>;
-
-declare const isEmpty: (data: unknown) => boolean;
-/**
- * MD5 of a string, matching a standard UTF-8 MD5 for all input.
- *
- * Content-block `custom_id`s are derived from this, so it's a wire identity —
- * see `generateCustomId`. Before 0.6.0 this packed UTF-16 code units directly
- * into byte lanes, which agreed with a real MD5 only for ASCII: non-ASCII
- * input both diverged from every other Langsys SDK and could collide (a
- * character's high byte was OR-ed into the neighbouring lane, vanishing
- * whenever that lane already carried those bits — so `éa` and `ǩa` hashed
- * alike). `md5Legacy` preserves the old behavior for migration lookups only.
- */
-declare function md5(inputString: string): string;
+/** The ambient-context shape `AsyncLocalStorage` has, so the core never imports `node:async_hooks`. */
+interface ScopeStorage {
+    getStore(): unknown;
+    run<R>(store: unknown, fn: () => R): R;
+    /** Makes a store current for the rest of the async context; needed only by `scope.enter()`. */
+    enterWith?(store: unknown): void;
+}
 /**
- * The pre-0.6.0 MD5, retained ONLY so existing content blocks stay resolvable:
- * ids minted by an older SDK are keyed by this. Lookup-only — never register
- * new content under it, or the colliding-id population keeps growing.
+ * Hand the core an `AsyncLocalStorage` (or anything of its shape), so a scope
+ * entered with `scope.run()` stays current across `await` inside the render.
+ * Pass `null` to go back to synchronous nesting.
  *
- * @deprecated Migration aid; will be removed once catalogs have been rebased.
+ * The storage is opt-in, and what it guarantees depends on the host's async
+ * model: under zone.js, for one, promises do not carry it across concurrent
+ * renders. A binding may instead carry the scope through its own dependency
+ * injection, one scope per request, and read `scope.t` and the scope's values
+ * directly, with no storage at all.
  */
-declare function md5Legacy(inputString: string): string;
+declare function setRequestScopeStorage(value: ScopeStorage | null): void;
 
 /**
- * Detects ICU MessageFormat syntax in a translation string.
- *
- *   - Matches `{var, plural, …}`, `{var, select, …}`, `{var, selectordinal, …}`,
- *     `{var, number, …}`, `{var, date, …}`, `{var, time, …}`.
- *   - Also matches the style-less forms `{var, number}`, `{var, date}`,
- *     `{var, time}` — valid ICU with the locale-default style.
- *   - Doesn't match plain interpolation slots like `{name}` or `{count}`.
- *
- * Exported because the Translation Manager UI needs the same detection logic
- * to decide whether to render a plural-slot editor vs. a single text field.
+ * Report, as a debug notice once per process per reason, that a unit registers
+ * nothing because the text it holds came from a variable that cannot be named
+ * (VAR-7): `register: false` on a DOM class, or a binding without its build-time
+ * transform. Its catalogued translations still render. The reason names the cause,
+ * such as the transform to enable.
  */
-declare function isICU(template: string): boolean;
+declare function warnUnregistered(reason: string): void;
+
 /**
- * Normalize `%name%` markup placeholders to canonical `{name}`.
- *
- * Framework compilers consume bare `{name}` written in markup before the DOM
- * walker ever sees it (Svelte compiles it to an expression; JSX evaluates it),
- * so DOM content accepts `%name%` as a collision-free authoring escape.
- * Normalization runs at every markup capture boundary (content-block
- * tokenizer, `Translate` original-value snapshots, `Phrase` encoding), so the
- * catalog, the wire, and translators only ever see the canonical `{name}`
- * form — and plain `{name}` keeps working for vanilla-HTML authors.
- *
- * Keys must be identifiers (`[A-Za-z_][A-Za-z0-9_]*`), so literal `%` in
- * prose ("20% off", "50% to 60%") can't match. `t()` phrases are JS strings
- * with no compiler collision and stay `{name}`-only.
+ * The catalog. Inside a request scope `get()` answers with the scope's catalog,
+ * as `t()` does, so a binding that reads the catalog through this signal on a
+ * server renders the visitor's, never another request's. `set`, `update` and
+ * `subscribe` are the page's.
  */
-declare function normalizeMarkupPlaceholders(text: string): string;
+declare const sTranslations: Signal<iCategories>;
 /**
- * Params keys that have NO matching placeholder in `texts`.
- *
- * Texts are expected in canonical form (post-`normalizeMarkupPlaceholders`),
- * so a key counts as used when it appears as `{key}` or as the argument of an
- * ICU slot (`{key, plural, …}`). Surrounding whitespace is tolerated.
+ * The locale the catalog is for. Inside a request scope `get()` answers with the
+ * scope's locale (SRV-7), for the same reason as `sTranslations`.
  */
-declare function findUnusedParamKeys(texts: string[], params: Record<string, unknown> | undefined): string[];
+declare const currentlyLoadedLocale: Signal<string>;
 /**
- * Substitute placeholders in a translated string with values from `params`.
+ * Server-computed write capability for THIS session. The single source of
+ * truth for every write decision — never infer it from `key_type`, which
+ * cannot express `ip_write` (read-only everywhere except from allow-listed
+ * IPs, which is exactly how the discovery renderer registers content).
  *
- * Two paths:
- *   - ICU MessageFormat (target string contains `{var, plural|select|…, …}`):
- *     parsed and formatted via `intl-messageformat`, which knows every
- *     target locale's plural rules (Arabic's 6 categories, Russian's 4,
- *     etc.) and gender-select branches.
- *   - Simple `{name}` interpolation: cheap regex replacement. Unknown
- *     placeholders are left untouched so missing data is visible to the
- *     developer rather than silently rendering empty strings. Number and
- *     Date values are formatted per the target locale's CLDR rules
- *     (`Intl.NumberFormat` / `Intl.DateTimeFormat`) — pass numbers as
- *     strings to opt out (e.g. IDs and codes that must not get grouping
- *     separators).
+ * Tri-state, and the three states are genuinely distinct:
+ *   - `undefined` — not yet authorized. HOLD: neither register nor hint.
+ *     Collapsing this to `false` would drop every miss that lands before
+ *     `validate()` resolves and fire a spurious discovery hint for it.
+ *   - `true`  — register missing tokens (never hint).
+ *   - `false` — never attempt a write (no 403 churn); hint instead.
  *
- * Malformed ICU falls through to simple interpolation rather than throwing,
- * so the developer sees a broken-but-visible string instead of a runtime crash.
- * Backend-side validation in langsys-ai is supposed to prevent this — the
- * fall-through is defense in depth.
+ * Refreshed from `authorize-project` at init and from every catalog fetch.
  *
- * `locale` is required for ICU formatting (drives plural-rule selection).
- * Falls back to `'en'` if absent — simple-interpolation path ignores it.
+ * BROWSER-AUTHORITATIVE: only ever written when `window` exists. Write
+ * capability is per-session (it varies by requester IP and by write grant),
+ * while this module is a process-wide singleton — in a long-lived SSR server
+ * shared across every request and every user, caching one request's answer
+ * here would apply it to every later visitor. Under SSR it stays `undefined`,
+ * which is the honest answer rather than a leaked one.
  */
-declare function interpolate(template: string, params: Record<string, unknown>, locale?: string): string;
-
+declare const writeEnabled: Signal<boolean | undefined>;
 /**
- * Locale-identifier handling, CLDR/BCP 47 flavored. Everything here rides on
- * the platform's native `Intl` — no bundled locale data.
+ * Whether this API key is permitted to report page URLs for content discovery.
  *
- * The SDK's convention: canonicalize once at every input boundary (init
- * config, user-locale store emissions, detectPreferredLocale, API routes) and
- * treat the canonical string as the identity everywhere downstream — cache
- * keys, equality checks, and the wire format all use it.
- */
-/**
- * Canonicalize a locale identifier to BCP 47 canonical form (the form CLDR
- * data is keyed by): language lowercase, script Titlecase, region uppercase —
- * `en-us` → `en-US`, `zh-hant-tw` → `zh-Hant-TW`. Underscores are accepted
- * and converted (`en_US` → `en-US`). Legacy aliases are resolved (`iw` → `he`,
- * `in` → `id`).
+ * A POLICY, not a capability — deliberately independent of `writeEnabled`, and
+ * the two must not be collapsed. `writeEnabled` answers "can this session write
+ * from here"; this answers "may this key report at all". The canonical public
+ * website is `writeEnabled: false` **and** `autoDiscovery: true` — read-only,
+ * and permitted to report — which is exactly the case a single merged flag
+ * would break.
+ *
+ * It exists because the SDK cannot tell whether it is running on a public
+ * website. A mobile app holding a read key would otherwise report "page URLs"
+ * that are not pages, and no heuristic settles it — our own URL heuristic is
+ * already defeated by a routerless SPA. Beyond that, a customer may simply not
+ * want visitors' page paths leaving the browser, whatever the SDK infers.
  *
- * Structurally invalid tags fall back to best-effort manual casing rather
- * than throwing, so a bad config value degrades to a failed catalog lookup
- * instead of a crash.
+ * Plain boolean rather than the tri-state `writeEnabled` uses, and false until
+ * known. That is only safe because it is evaluated where the report is SENT
+ * rather than where the miss is recorded: by then authorization has long since
+ * resolved, and if it somehow hasn't, not reporting is the correct conservative
+ * default. Checked at collection time instead, false-until-known would silently
+ * drop early misses for keys that do permit reporting.
  */
-declare function canonicalizeLocale(locale: string): string;
+declare const autoDiscovery: Signal<boolean | undefined>;
 
 interface iProject {
     id: string;
@@ -892,5 +2137,29 @@ interface iProject {
 
 declare const t: TFunction;
 declare const tSignal: Signal<TFunction>;
+/**
+ * Tell the SDK the route changed (HINT-13). Call it from your router's after-navigation hook,
+ * so content that stays mounted across routes — a persistent layout — is looked up again and
+ * its misses are recorded for the new URL. Framework bindings wire this for you.
+ */
+declare const notifyNavigation: () => void;
+/**
+ * The header that asks your own API for the user's language (FRM-6):
+ * `fetch(url, { headers: { ...localeHeaders() } })`. See `LangsysApp.localeHeaders`.
+ */
+declare const localeHeaders: () => Record<string, string>;
+/**
+ * Render a server message entry (MSG-5): its template through `t()` under the
+ * messages category, or the entry's `message` when there is no translation.
+ * Standalone alias for `LangsysApp.renderServerMessage`.
+ */
+declare const renderServerMessage: (entry: ServerMessage, category?: string) => string;
+/**
+ * Standalone alias for `LangsysApp.setWriteGrant` — supply the write grant
+ * after `init()`, e.g. once the user logs in. Not the refresh path: the token
+ * is resolved fresh before every request and never cached, so pass a provider
+ * function and let your auth layer decide when to mint.
+ */
+declare const setWriteGrant: (grant: WriteGrant | undefined) => Promise<void>;
 
-export { type EncodedRichText, type ExtractParamKeys, LangsysApp, LangsysAppAPI, type LocaleSource, Logger, PHRASE_MARKER_ATTR, PHRASE_MARKER_ATTRS, type ParamPrimitive, type ParamsFor, Phrase, type PhraseOptions, type RichSlot, type Signal, type Subscriber, type TArgs, type TFunction, Translate, type TranslateOptions, type TranslationParams, Translations, type Unsubscriber, type Updater, canonicalizeLocale, createSignal, currentlyLoadedLocale, encodeRichText, findUnusedParamKeys, generateCustomId, generateLegacyCustomId, getValue, type iCategories, type iContentBlock, type iCountry, type iCountryDialCode, type iCountryList, type iCurrency, type iCurrencyList, type iLangsysConfig, type iLangsysInitConfig, type ResponseObject as iLangsysResponse, type iLanguageName, type iLocaleData, type iLocaleDefault, type iLocaleFlat, type iProject, type iTranslations, interpolate, isContentBlockKnown, isEmpty, isICU, isPhraseMarked, isTranslationExcluded, legacyTokenizeElement, logger, markupTokenValues, md5, md5Legacy, normalizeMarkupPlaceholders, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };
+export { type ApiCredentials, type BlockNode, type BlockOptions, type BlockShape, CatalogSnapshot, type EncodedRichText, LangsysApp, LangsysAppAPI, LangsysConfigurationError, LegacyKeyFile, type LocaleSource, Logger, ParamPrimitive, type PersistStorage, Phrase, type PhraseOptions, type RegistrationReason, type RegistrationResult, type RenderedBlock, type RenderedNode, type RequestScope, type RequestScopeOptions, type RequestSeed, type RichSlot, type ScopeMiss, type ScopeStorage, type SeededBlock, type SeededPhrase, type SendOptions, ServerMessage, type Signal, type Subscriber, TFunction, type TeardownSubscribe, Translate, type TranslateOptions, Translations, type Unsubscriber, type Updater, type WriteGrant, applyRendered, autoDiscovery, blockNodesOf, clearSharedCatalogs, createRequestScope, createSignal, currentRequestScope, currentlyLoadedLocale, encodeRichText, getValue, type iCategories, iContentBlock, type iCountry, type iCountryDialCode, type iCountryList, type iCurrency, type iCurrencyList, type iLangsysConfig, type iLangsysInitConfig, type ResponseObject as iLangsysResponse, type iLanguageName, type iLocaleData, type iLocaleDefault, type iLocaleFlat, type iProject, type iTranslations, isContentBlockKnown, isPhraseMarked, legacyTokenizeElement, localeHeaders, logger, markupTokenValues, notifyNavigation, persist, reconstitute, registerBlock, registerContentBlock, renderBlock, renderServerMessage, sTranslations, scopeFromSeed, serializeTree, setPersistStorage, setRequestScopeStorage, setTeardownSignal, setWriteGrant, stripSentinels, t, tSignal, tokenizeElement, tokenizeTree, warnUnregistered, warnUnrenderedBlock, writeEnabled };