langsys-js-react 0.6.7 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+## 0.7.0 - 2026-11-14
+
+> Requires the base SDK `langsys-js-typescript@^0.7.4`, which carries write gating (ticket 838), the move (`previousCategory`), the previous messages category (`messagesPreviousCategory`), `<plaintext>` among the elements that are never translated, numbers formatted for the locale inside a translation's plural or gender form, and the VAR-3 marker reader this release's transform emits for.
+
+### Added
+
+- **Moving content to another category (spec MOVE-1 to MOVE-5).** `<Translate>` and `<Phrase>` take `previousCategory`, and `inCategory`, `isCategoryRef`, `CategoryRef` and `CategoryMoveOptions` are re-exported for `t('Buy now', inCategory('Checkout', { previousCategory: 'Header' }))`. The binding only forwards it: the base SDK sends `previous_category` on the registration a miss triggers, keeps it out of `custom_id`, renders the previous category's translation until the new one is in the catalog, and stamps the host so hydration agrees. Verified against a local API: the four moved items came back with their own translations (`memory_translated: false`) and were not registered again after the refresh. Needs base SDK `^0.7.3`.
+- **A nested `<Phrase>` or `<Translate>` that names no category takes its block's category and previous category (spec MOVE-4).** A block that holds a component renders through the core's DOM class, and a unit inside it now registers and renders under the block's `category` and `previousCategory` (a React context the block provides), on the client, in a request scope and on hydration, where it was registered with no category. A unit that names its own `category` (`''` included) takes neither and moves only with its own `previousCategory`. `category` is now absent rather than `''` when a unit names none; a unit outside any block still has none. `inCategory`, `isCategoryRef`, `CategoryRef` and `CategoryMoveOptions` are also exported from `langsys-js-react/server`, the same references as the main entry's.
+- **Write gating (ticket 838).** Public keys are read-only; the server decides per session whether it may register content, and read-only sessions report the page URL only (never phrase content) so Langsys can visit and register from an allow-listed address.
+  - **`useWriteEnabled()`** → `boolean | undefined`. Tri-state, and the states are distinct: `undefined` means authorization hasn't landed (and is the value throughout SSR), `false` means read-only, `true` means this session registers directly. Don't collapse it to a boolean or default `undefined` to `false`.
+  - **`setWriteGrant(grant)`** → `Promise<void>`, also on `LangsysApp`. For login-walled apps: supply a short-lived JWT after `init()` and the session is re-authorized with an `X-Write-Grant` header. It re-authorizes rather than only storing the token.
+  - **`writeGrant`** init option, inherited from the base config type. Prefer the function form — grants are short-lived and a static string expires while the app is still mounted.
+  - **`WriteGrant`** type re-exported. The raw **`writeEnabled`** signal is deliberately *not* re-exported: it is the one signal that needs adapting, since it is `undefined` for the whole of a server render, and re-exporting it alongside `useWriteEnabled()` would offer a supported-looking way to defeat the hydration guard. Advanced consumers can import it from `langsys-js-typescript` directly.
+- **`useNotifyNavigation(location)`** and **`notifyNavigation()`** (re-exported by reference). Content that stays mounted across a route change — a persistent layout, a header — is not re-rendered by React when only the route changes, so the SDK never learns its phrases now appear on the new page. Pass the router's location to the hook (React Router's `useLocation().key`, Next's `usePathname()`), and every mounted translated node looks itself up again at the new URL.
+- **Server messages.** `resolveServerMessages(body, { key | resolver, pieces? })` and `renderServerMessage(entry, category?)` re-exported by reference, with `DEFAULT_SERVER_MESSAGE_CATEGORY` and the `ServerMessage` / `ResolveServerMessagesOptions` / `ServerMessagePieces` types; `messagesCategory` and `messagesPreviousCategory` init options inherited from the base config. Entries are read only from where the server attached them — a configured `key` or an app `resolver` — beside the framework's own error body, which is never searched or changed; `field` and `code` are the framework's own, passed through. **`useRenderServerMessage()`** renders entries in components and re-renders them when the locale changes: the translation of the entry's `template` when the catalog has one, its `message` otherwise. Works unchanged for the entries an Inertia server hands to the page after a failed form.
+- **Legacy-key migration.** The core's `legacyKeys` init option (inherited from the base config) lets an app keep calling `t()` / `useT()` with its i18next, vue-i18n or plain JSON keys: a key the files hold registers and renders as its converted value, never as the key. `LegacyFormatError` and the `LegacyKeyFile` type are re-exported; `LangsysApp.Translations.setLegacyKeys` turns the mode on or off later.
+- **Catalog snapshots.** `LangsysApp.loadSnapshot(snapshot, locale?)` (the core's, by reference) loads an exported catalog synchronously before the first render; the fetched catalog still replaces it. `SnapshotError` and the `CatalogSnapshot` type are re-exported.
+- **Server rendering per request — `langsys-js-react/server`.** A Node-only entry over the core's request scope: `renderInRequestScope({ locale, catalog?, url?, credentials? }, render)` renders one request inside a scope of its own and returns the HTML, the seed the client hydrates from (`LangsysApp.seedCatalog`), and `close()` for after the response; `installRequestScopeStorage()` plus the core's `createRequestScope` / `scope.enter()` serve a host that cannot wrap its render. The entry loads no React and also exports `LangsysApp` and `createLocaleStore`, the same ones as the main entry, so a server process, a Next Server Component included, calls `init()` through it; a scope fetches and registers with the project and key `init()` supplies, or with its own `credentials: { projectid, key }`, so two requests for two projects in one process never share a credential. Inside a scope every hook reads that request's locale and catalog, so concurrent requests in different locales never see each other's. `RegistrationResult` and `RegistrationReason` are re-exported.
+- **`<Translate>` and `<Phrase>` render through the core's block tree.** Content made of markup and text is translated as data (`renderBlock`) and rendered by React: on a server it arrives translated with its block id on the element, it hydrates without a mismatch, a locale change re-renders it, and a translation that reorders a phrase's inline elements moves your elements with their handlers; a portal stays under the element that holds it, so its events bubble there. A new `tag` moves the unit to the element it makes, on either path. Registration goes through `registerBlock`, with no DOM walk over nodes React owns; a block is registered once however blocks nest, and a block nested in one that falls back to the DOM translation stays its own, rendered and registered with its own params. `<DontTranslate>` is the host element it renders, like any other markup. Content holding any other component, `lazy`, `Suspense` or `dangerouslySetInnerHTML` renders as written and is translated after mount, with an explicit `custom_id` on the element from the first render. Such a block is keyed and registered once its content has stopped changing for 500 ms, so a `Suspense` fallback that resolves within that time never becomes a block; a fallback still showing then is registered, and when it later resolves the SDK says so in a debug notice naming both block ids.
+- **Variables become placeholders at build time (`langsys-js-react/vite`, `/babel`, `/next`).** Inside `<Translate>`, `<Phrase>` and `t()` calls, an interpolated value — `{user.firstName}`, `` `${items.length}` `` — becomes a named placeholder with its value as the param, so the sentence registers once for every user and can take plural forms. Only the `t` a `useT()` call returns is rewritten, and its values join the params where `t()` reads them, in `t(text, params)` and `t(text, category, params)` alike (a second argument the build cannot see into is read when the call runs); `+` joins as JavaScript joins it; a key built in the call (its own text has no space: `errors.${code}`, `status_${status}`) is left for legacy-key mode to look up. Names come from the expression in snake_case (`first_name`, `items_count`), derived by the SDK so they match every other Langsys SDK, and never take a name the developer wrote; an expression no name can be derived from is named `value`, a second one `value_2` even when it repeats the first, and the build warns. String, number and plain template literals stay text, a fragment's content joins the text around it, and each run of text reaches React as one string, as JSX renders the source. An expression holding JSX is left as it is, and so is `{children}` that is all the text between two elements of translated text; beside text, or in a part that is not translated, it is a value. A value that is text, a number, a boolean or a date is the param (a boolean stays a boolean, which a select can branch on), a bigint is passed as its digits, `null` or `undefined` renders nothing, on React 19 a promise or a context is read as React reads one, and anything else, such as an element, a list or a function, renders in its place as React renders it. In a `<Translate>`, a value in an attribute the SDK translates (`alt`, `title`, `placeholder`, `aria-label` and the rest, a button's `value`) is a placeholder too, written into the attribute's text as JavaScript writes it, unless it also appears in the text or as a whole attribute; a value that is the whole attribute fills it as a value fills text (`null` or `undefined` with nothing), and one on an element whose opt-out or input type is an expression is left as written, and that block registers nothing. A value right after a `%` and a word (`%s{x}`) gets its placeholder in the stored form, `{x}`, so the `%s` stays text. A `<Phrase>` holding a value marker of its own has its other values marked too (one in its translated text where no marker can stand is left as written, and that phrase registers nothing), and a name such a marker carries is never given to another value. A value inside `<DontTranslate>`, an element with `translate="no"` / `data-notrans` (in a `<Translate>`, an expression value included, since it is known only at runtime; in a `<Phrase>` a value under one is a placeholder, filled either way) or code such as `<template>` is shown as written, so it stays where it is and is marked as a value (`<span data-ls-param="name">`); Langsys never stores a marked value: a block's content holds its placeholder, and a `<Phrase>` keys the whole part as one empty piece of markup. A value inside `<script>`, `<style>` or `<plaintext>` is left as written, and so is one in a part that is not translated where no marker can stand: inside `<math>` or an excluded `<svg>`, where a `<span>` draws nothing, or in `<textarea>`, `<title>` or `<option>`, which hold text only. A `<Translate>` holding one registers nothing. One line enables it: the Vite plugin, the Babel plugin, or `withLangsys(nextConfig)`, which adds it to Turbopack and webpack with Next's compiler left on. The Vite plugin and the Next loader read TypeScript's and the standard decorators, and Flow in a `.js` file, and leave a file they cannot read as written, with a build warning, so they never fail a build your compiler passes. Adds `@babel/core` as a dependency, loaded only by these build entries.
+- **A value that can't be named is not registered.** Without the build transform, a value interpolated in `<Translate>` or `<Phrase>` markup splits the text around it, and the component registers nothing for that unit rather than one phrase per value — on its own render path and when it falls back to the SDK's DOM translation — and the SDK notes it once as a debug notice. Translations already in the catalog still render. In a `<Phrase>`, a value inside a part that is not translated, or inside notation such as `<math>`, doesn't count, since the phrase's key leaves that part out, so the phrase still registers. A value that is an element's only text can't be told from literal text at runtime, so that block registers the text it renders; enable the transform for those. The transform leaves a conditional as written, so a conditional inside other text registers nothing either.
+- **`localeHeaders()`** re-exported: the `Accept-Language` header for the user's chosen locale, for an app's calls to its own API.
+- **`<LangsysProvider seed>` for Next.js's App Router.** The root layout opens the request's scope and passes `scope.seed()` to the provider; `useT()`, `useCurrentLocale()`, `useTranslations()`, `<Translate>` and `<Phrase>` then render the request's locale on the server, and the browser hydrates from the same catalog with no mismatch. Requires the core's `scopeFromSeed`.
+- **Running without credentials.** `init()` without a project id, API key or locale store leaves the client unconfigured rather than throwing: `t()` and `<Translate>` / `<Phrase>` render source text, nothing is requested or registered (a registration resolves skipped with `RegistrationReason` `'not-configured'`), and `LangsysApp.isConfigured()` reports it. The `requireCredentials` init option, inherited from the base config, fails loudly instead: `t()` throws, so a component calling it reaches its error boundary, and a block's registration rejects, left unhandled so it surfaces; a block holding a value the transform did not name only reads and never rejects. `LangsysConfigurationError` is re-exported by reference from `langsys-js-react` and `langsys-js-react/server`.
+- **`interpolate` re-exported.** `interpolate(text, params, locale)` fills a string's placeholders, ICU included, where the hooks cannot run. `langsys-js-typescript` is a plain dependency of this package rather than a peer, so importing it from there resolves under npm's hoisting and fails under pnpm, Yarn PnP or `--no-hoist`.
+- **E2E testbed** (`example/Testbed.tsx` + `example/e2e/write-gating.mjs`, `npm run test:e2e`) — drives a real browser against a live API and asserts on captured request payloads *and* response status.
+
+### Fixed
+
+- **`useWriteEnabled()` hydration safety.** It pins `getServerSnapshot` to `undefined` rather than reusing the live signal getter. React uses that snapshot for the hydration render as well as the server render, so reading the live value there makes a session whose authorization resolved before hydration render markup disagreeing with the server HTML, and React discards the subtree.
+
+### Docs
+
+- **Plurals and gender: write the sentence flat.** The README showed `t('{count, plural, one {# item} other {# items}}', …)` as where `t()` calls were headed. It now says never to write ICU: write the sentence with the count or the name as a `{placeholder}`, Langsys makes each language's plural and gender forms, the base language included, and `t()` renders them with the CLDR plural rules of the loaded catalog's locale. Pass `name_gender` beside `name` to choose a gender form. Numbers and dates format for the locale inside those forms as everywhere else.
+- **`translationsLoadingPromise` settles when the fetch ends, on failure as well as on success, and never rejects.** On success `t()` already returns the new locale's text when it settles, and `useCurrentLocale()` follows about 100 ms later. On failure the page renders the source text, or the catalog stored for that locale, and `useCurrentLocale()` keeps naming the last locale that loaded. The README says to treat a settled promise with a matching locale as the only sign a switch worked, and that an error state needs the app's own timeout.
 
 ## 0.6.7 - 2026-08-21
 

package/README-SSR.md

@@ -1,156 +1,156 @@
-# SSR Usage Guide (Next.js / Remix)
+# SSR Usage Guide
 
-This guide shows how to use `langsys-js-react` with Server-Side Rendering (SSR) to eliminate duplicate API calls and improve performance.
+This guide covers rendering `langsys-js-react` on a server: serving each request its own locale's translations, handing the client the catalog the server rendered with, and collecting what the server render missed.
 
-## The problem
+## How it works
 
-In a traditional SSR flow:
-1. The server fetches translations during render.
-2. The client re-fetches the same translations after hydration.
-3. Duplicate API calls, slower initial render, possible flash of untranslated content.
+A server process renders for many visitors at once. The SDK keeps its catalog and locale in module state, which is right for a browser page and wrong for a server, so each request renders inside a **request scope** of its own — the core's, from `langsys-js-typescript`. A scope has its own locale, its own view of the catalog, its own misses and its own hydration seed, and nothing one request's scope does reaches another's.
 
-## The solution
+This package's server entry, `langsys-js-react/server`, opens a scope around one request's render. It is Node-only (it hands the core an `AsyncLocalStorage`, so the scope stays current across every `await` in the render) and is never part of the main bundle.
 
-Pass pre-fetched translations from server to client using the `initialTranslations` config option. The client SDK uses them as-is and skips the initial fetch. Because the hooks are built on `useSyncExternalStore` with a server snapshot, the first paint already reflects the seeded translations.
-
-## Next.js — App Router
-
-### Step 1: Fetch translations on the server
+## Rendering one request
 
 ```tsx
-// app/layout.tsx (Server Component)
-import type { iCategories } from 'langsys-js-react';
-import { LangsysClient } from './LangsysClient';
-
-async function getTranslations(locale: string): Promise<iCategories> {
-    const res = await fetch(
-        `https://api.langsys.dev/api/projects/${process.env.LANGSYS_PROJECT_ID}/translations?locale=${locale}`,
-        { headers: { 'x-Authorization': process.env.LANGSYS_API_KEY!, 'Content-Type': 'application/json' } }
+// server.tsx
+import { renderToString } from 'react-dom/server';
+import { LangsysApp, createLocaleStore, renderInRequestScope } from 'langsys-js-react/server';
+
+// Once per process: request scopes fetch catalogs, and close() sends misses, with this project and key.
+const ready = LangsysApp.init({
+    projectid: PROJECT_ID,
+    key: SERVER_KEY,
+    UserLocaleStore: createLocaleStore('en'),
+    baseLocale: 'en',
+});
+
+app.get('*', async (req, res) => {
+    await ready;
+    const locale = resolveLocale(req); // your framework's or app's resolved locale
+
+    const { result: html, seed, close } = await renderInRequestScope(
+        { locale, url: req.url },
+        () => renderToString(<App />),
     );
-    const result = await res.json();
-    return result.data as iCategories;
-}
 
-export default async function RootLayout({ children }: { children: React.ReactNode }) {
-    const locale = 'en'; // from cookie / Accept-Language / route segment
-    const translations = await getTranslations(locale);
+    res.send(`<!doctype html>
+<div id="root">${html}</div>
+<script>window.__LANGSYS_SEED__ = ${JSON.stringify(seed)}</script>
+<script type="module" src="/client.js"></script>`);
 
-    return (
-        <html lang={locale}>
-            <body>
-                <LangsysClient
-                    locale={locale}
-                    translations={translations}
-                    projectId={process.env.LANGSYS_PROJECT_ID!}
-                    apiKey={process.env.NEXT_PUBLIC_LANGSYS_API_KEY!} // read-only key for the client
-                >
-                    {children}
-                </LangsysClient>
-            </body>
-        </html>
-    );
-}
+    await close(); // after the response: hands this request's misses to the core
+});
 ```
 
-### Step 2: Initialize on the client
+- `LangsysApp.init()` in the server process supplies the project and key a scope fetches its catalog with and sends its misses under. A scope given `credentials: { projectid, key }` uses those instead, so one process can render for several projects: two scopes never share a credential, however their requests interleave. Without either, a scope not given `catalog` renders source text.
+- `renderInRequestScope({ locale, catalog?, url?, credentials? }, render)` opens a scope, runs `render` inside it and resolves once it has finished. The scope fetches the locale's catalog at most once per request, shared read-only with other requests rendering the same locale under the same credentials; pass `catalog` when you already have it (from a snapshot or your own fetch).
+- Inside the render, `useT()` and `LangsysApp.t` read this request's catalog.
+- `seed` is `{ locale, catalog, blocks, phrases }`: the catalog this request rendered with, the content blocks it served, and the misses it collected.
+- `close()` runs after the response has been sent. What it does with the misses is set by `ssrTokenStrategy` (below). It never throws, and calling it again returns the first result.
 
-```tsx
-// app/LangsysClient.tsx
-'use client';
+Where your framework cannot wrap its render in a function, open the scope and enter it instead, in the request's own async function, before anything renders:
 
-import { useEffect, useState, type ReactNode } from 'react';
-import { LangsysApp, useLocaleStore, type iCategories } from 'langsys-js-react';
-
-export function LangsysClient({
-    locale,
-    translations,
-    projectId,
-    apiKey,
-    children,
-}: {
-    locale: string;
-    translations: iCategories;
-    projectId: string;
-    apiKey: string;
-    children: ReactNode;
-}) {
-    const [, , localeStore] = useLocaleStore(locale);
-
-    useEffect(() => {
-        LangsysApp.init({
-            projectid: projectId,
-            key: apiKey,
-            UserLocaleStore: localeStore,
-            baseLocale: 'en',
-            initialTranslations: translations,
-            initialTranslationsLocale: locale,
-            ssrTokenStrategy: 'client',
-        });
-    }, [localeStore, projectId, apiKey, translations, locale]);
-
-    return <>{children}</>;
-}
+```ts
+import { createRequestScope, installRequestScopeStorage } from 'langsys-js-react/server';
+
+installRequestScopeStorage(); // once, at startup, beside LangsysApp.init() as above
+
+// in the request handler, before rendering:
+const scope = await createRequestScope({ locale, url });
+scope.enter(); // current for the rest of this request's async context
+// ...render, send scope.seed() with the page, then after the response:
+await scope.close();
 ```
 
-### Step 3: Use translations in any client component
+Prefer `renderInRequestScope` (or `scope.run()`) wherever you can wrap the render. `scope.enter()` binds the scope to the async continuation it is called in, so it holds only when that same function goes on to render. Any function your host awaits and returns from before rendering — a middleware, a route handler that returns before the render, a helper that opens the scope — loses it on return, even when `enter()` comes after that function's own `await`, and the render then reads another request's state.
 
-```tsx
-'use client';
-import { useT } from 'langsys-js-react';
+## Hydrating on the client
 
-export function Hero() {
-    const t = useT();
-    return (
-        <>
-            <h1>{t('Welcome', 'HomePage')}</h1>
-            <p>{t('Hello, {name}!', 'HomePage', { name: 'Sarah' })}</p>
-        </>
-    );
-}
+Seed the client with the server's catalog **before** hydrating, so the first client render matches the server's HTML:
+
+```tsx
+// client.tsx
+import { hydrateRoot } from 'react-dom/client';
+import { LangsysApp, createLocaleStore } from 'langsys-js-react';
+
+const seed = window.__LANGSYS_SEED__;
+LangsysApp.seedCatalog(seed.catalog, seed.locale, seed); // synchronous
+
+const localeStore = createLocaleStore(seed.locale);
+hydrateRoot(document.getElementById('root')!, <App localeStore={localeStore} />);
+
+LangsysApp.init({
+    projectid: PROJECT_ID,
+    key: PUBLIC_KEY, // a read-only key in the browser
+    UserLocaleStore: localeStore,
+    baseLocale: 'en',
+});
 ```
 
-## Next.js — Pages Router
+`seedCatalog` is synchronous and marks the locale as loaded, so `init()` does not fetch it again. Passing the seed itself as the third argument hands over the content blocks the server rendered and the misses it collected, so the client never registers again what the server already collects. `<Translate>` and `<Phrase>` register themselves as they render, so nothing else is needed.
 
-```tsx
-// pages/_app.tsx
-import type { AppProps } from 'next/app';
-import { useEffect } from 'react';
-import { LangsysApp, useLocaleStore } from 'langsys-js-react';
+## Next.js
 
-export default function App({ Component, pageProps }: AppProps) {
-    const locale = pageProps.locale ?? 'en';
-    const [, , localeStore] = useLocaleStore(locale);
-
-    useEffect(() => {
-        LangsysApp.init({
-            projectid: process.env.NEXT_PUBLIC_LANGSYS_PROJECT_ID!,
-            key: process.env.NEXT_PUBLIC_LANGSYS_API_KEY!,
-            UserLocaleStore: localeStore,
-            baseLocale: 'en',
-            initialTranslations: pageProps.translations,
-            initialTranslationsLocale: locale,
-        });
-    }, [localeStore, pageProps.translations, locale]);
-
-    return <Component {...pageProps} />;
-}
+In the App Router, server components and client components are built against separate copies of the SDK, so a scope opened in a server component is not visible to the client components rendering the same request. The request's **seed** crosses that boundary instead: the root layout opens the scope and passes its seed to `<LangsysProvider>`, which rebuilds the scope on the client-component side.
+
+```js
+// next.config.mjs — the placeholder transform, in Turbopack and webpack
+import { withLangsys } from 'langsys-js-react/next';
+export default withLangsys({ /* your config */ });
+```
+
+```tsx
+// app/langsys-client.tsx — this package ships no 'use client' directive, so re-export the provider through one
+'use client';
+export { LangsysProvider } from 'langsys-js-react';
 ```
 
 ```tsx
-// pages/index.tsx — fetch translations in getServerSideProps
-import type { iCategories } from 'langsys-js-react';
-
-export async function getServerSideProps() {
-    const locale = 'en';
-    const res = await fetch(
-        `https://api.langsys.dev/api/projects/${process.env.LANGSYS_PROJECT_ID}/translations?locale=${locale}`,
-        { headers: { 'x-Authorization': process.env.LANGSYS_API_KEY!, 'Content-Type': 'application/json' } }
+// app/layout.tsx — a server component
+import { LangsysApp, createLocaleStore, createRequestScope } from 'langsys-js-react/server';
+import { LangsysProvider } from './langsys-client';
+
+// The server's own SDK, initialized once per process: scopes fetch catalogs with this project and key.
+let ready: Promise<unknown> | undefined;
+const initServer = () =>
+    (ready ??= LangsysApp.init({
+        projectid: process.env.LANGSYS_PROJECT_ID!,
+        key: process.env.LANGSYS_SERVER_KEY!,
+        UserLocaleStore: createLocaleStore('en'),
+        baseLocale: 'en',
+    }));
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+    await initServer();
+    const locale = await resolveLocale(); // your app's own resolution: route segment, cookie, header
+    const scope = await createRequestScope({ locale });
+    return (
+        <html lang={locale}>
+            <body>
+                <LangsysProvider seed={scope.seed()}>{children}</LangsysProvider>
+            </body>
+        </html>
     );
-    const { data } = await res.json();
-    return { props: { locale, translations: data as iCategories } };
 }
 ```
 
+The layout imports `LangsysApp` and `createLocaleStore` from `langsys-js-react/server`, which loads no React, so a server component can call `init()`. It runs when a request first renders the layout, not when the module loads.
+
+Use the hooks, `<Translate>`, `<Phrase>` and `<DontTranslate>` in Client Components (files that start with `'use client'`), imported from `langsys-js-react` itself, as `example-next/app/Client.tsx` does; a Server Component renders them through a Client Component of yours. The build transform makes values placeholders only in units imported from the package, so a unit taken through a re-export of your own is left as written ([Variables in translated text](./README.md#variables-in-translated-text)).
+
+Under the provider, `useT()`, `useCurrentLocale()`, `useTranslations()`, `<Translate>` and `<Phrase>` render the request's locale and catalog on the server, and the browser hydrates from the same catalog, so the first client render matches the served HTML. Initialize the SDK in the browser as usual (`LangsysApp.init()` in a Client Component's `useEffect`); the provider has already seeded it with the request's catalog.
+
+Content a client component misses during the server render is registered by the browser after hydration. Under the `server` SSR strategy those misses are not sent from the server, because the provider's side of the render has no after-response hook.
+
+## What a server render translates and discovers
+
+| What renders the text | Translated on the server | Discovered |
+| --- | --- | --- |
+| `t()` / `useT()` inside a scope | Yes, in the request's locale; `useCurrentLocale()` and `useTranslations()` read the request's too | Yes: the miss is recorded in the scope and handed on by `close()` |
+| `<Translate>`, `<Phrase>` with markup and text | Yes, with the block's id on its element | Yes: registered through the scope, handed on by `close()` |
+| `<Translate>` / `<Phrase>` holding a component, `lazy`, `Suspense` or `dangerouslySetInnerHTML` | No — source text, with an explicit `custom_id` on the element; the SDK warns once | On the client, when it mounts |
+
+A block of markup and text renders through the core on the server and again in the browser, with the same result, so the page arrives translated and hydrates without a mismatch. A block whose content is only known once React renders it is served as written and translated in the browser.
+
 ## Locale switching
 
 Update the store from the same `useLocaleStore` call; the SDK reacts and fetches the new locale's translations:
@@ -164,7 +164,7 @@ export function LocaleSwitcher() {
 
     function changeLocale(next: string) {
         setLocale(next); // subscribers in the SDK trigger a fetch
-        return LangsysApp.translationsLoadingPromise; // optional: await the in-flight fetch
+        return LangsysApp.translationsLoadingPromise; // optional: settles when the fetch ends (success OR failure)
     }
 
     return (
@@ -177,24 +177,9 @@ export function LocaleSwitcher() {
 }
 ```
 
-> Keep one locale store for the app (created where you call `init`) and thread `setLocale` down via context or props, rather than calling `useLocaleStore` with a fresh initial value in unrelated trees.
-
-## Benefits
-
-### Performance
-- No duplicate API calls (server + client).
-- Translations ready immediately on hydration.
-- Faster Time to Interactive (TTI).
-- Reduced API usage and costs.
-
-### User experience
-- No flash of untranslated content.
-- Instant translation display.
-- Better SEO with server-rendered translations.
+> `translationsLoadingPromise` settles when the fetch ends, on failure as well as on success, so it does not mean the new language is showing. [Waiting for translations to load](./README.md#waiting-for-translations-to-load) covers how to tell the two apart.
 
-### Developer experience
-- Simple configuration.
-- Full TypeScript support, including compile-time-checked interpolation params on `t()`.
+> Keep one locale store for the app (created where you call `init`) and thread `setLocale` down via context or props, rather than calling `useLocaleStore` with a fresh initial value in unrelated trees.
 
 ## Configuration options
 
@@ -204,45 +189,34 @@ export function LocaleSwitcher() {
 { ssrTokenStrategy: 'client' | 'server' | 'auto' }
 ```
 
-- `'client'` (default) — queue tokens, send from client after hydration.
-- `'server'` — send tokens immediately from server.
-- `'auto'` — small batches (≤5) from server, larger batches from client.
+This decides what `close()` does with the phrases a scoped server render missed. It acts on an SDK initialized in the rendering process (`LangsysApp.init()` on the server):
 
-### Debug mode
+- `'client'` (default) — nothing is sent from the server. Content that also renders on the client is caught there, when `t()` runs in the browser.
+- `'server'` — `close()` sends the misses from the server, when the server's key may write. Note that this originates from your server's IP rather than a browser's.
+- `'auto'` — `close()` sends a short list (fewer than 5) from the server and leaves a longer one to the client.
 
-```typescript
-{ debug: true, initialTranslations: translations, initialTranslationsLocale: locale }
-```
+`close()` never throws; its result says whether it sent or why it skipped.
 
-Look for:
-- `SSR initial translations config:` on init — confirms pre-fetched data is detected.
-- `Using pre-fetched translations for locale` — confirms the initial fetch was skipped.
-- `Locale change detected!` — fires on a subsequent locale switch.
+### Debug mode
+
+Pass `debug: true` to `init()` to log the SDK's lifecycle to the console, including `Locale change detected!` on a locale switch.
 
 ## Important notes
 
-1. **One-time use.** `initialTranslations` is consumed only at init. Locale changes after init go through the normal fetch path.
-2. **Matching locales.** Always provide `initialTranslationsLocale` with `initialTranslations` so the SDK knows what locale the data represents.
-3. **Data format.** The translations payload must match the `iCategories` shape returned by `LangsysAppAPI.getTranslations()`.
-4. **Cache.** The 60-second locale cache still applies. Pre-fetched translations count as cached.
-5. **Token creation.** Use a read-only API key for the client in production — missing tokens won't be sent. Keep the write key on the server (and ideally pre-populate tokens via your local dev environment).
-6. **`'use client'`.** `useT`, `useLocaleStore`, `<Translate>`, and `LangsysApp.init` run on the client — keep them in Client Components.
+1. **Seed before hydrating.** Call `LangsysApp.seedCatalog(seed.catalog, seed.locale, seed)` before `hydrateRoot`, with the seed from the same request. Seeding after hydration, or from another request, renders different text from the server's HTML.
+2. **One scope per request.** Open a scope for every request and close it after that request's response. Never share one across requests: sharing one is exactly the cross-visitor leak the scope exists to prevent.
+3. **Data format.** A `catalog` passed to a scope must match the `iCategories` shape returned by `LangsysAppAPI.getTranslations()`.
+4. **Keys.** Use a read-only API key in the browser — anything shipped in public JS is extractable. A write key belongs on the server, where `close()` can send a scope's misses with it under the `'server'` or `'auto'` strategy.
+5. **Server-only entry.** Import `langsys-js-react/server` only from server code; it imports `node:async_hooks`. The main entry imports React hooks, so in a React Server Component environment put its hooks and components behind a Client Component boundary of your own (this package ships no `'use client'` directive). The server entry loads no React and exports the same `LangsysApp` and `createLocaleStore`, so a server component initializes the SDK through it.
 
 ## Troubleshooting
 
-### Translations not appearing
-- Check that `initialTranslationsLocale` matches the `UserLocaleStore` value at init.
-- Verify the translations payload matches the `iCategories` shape.
-- Enable `debug: true` and look for the messages above.
-
-### Still seeing duplicate API calls
-- Confirm both `initialTranslations` *and* `initialTranslationsLocale` are passed.
-- Confirm init runs before any rendering that calls `t(...)`.
-- Confirm the locale hasn't drifted between server and client.
+### Another visitor's language appears in a page
+- Every render must run inside its own request's scope: `renderInRequestScope`, or `scope.enter()` called in the function that itself renders — never in a middleware, handler or helper that returns before the render.
 
 ### Hydration mismatch warnings
-- Make sure the `locale` you seed on the server matches the initial value you pass to `useLocaleStore` on the client.
-- Keep `LangsysApp.init` inside `useEffect` (client-only) so the server render and the first client render agree.
+- Seed the client with the seed of the request that rendered the page, before `hydrateRoot`.
+- Make sure the locale store's initial value on the client is the seed's locale.
 
 ### TypeScript errors on `t()`
 - Placeholders are compile-time-checked: `t('Hello, {name}!', 'Cat')` *requires* a params object with `name`. Either add the key or remove the placeholder.