najm-kit 2.8.2 → 2.10.0

package/README.md

@@ -123,7 +123,7 @@ Changing the state updates the complete theme immediately. Use
 `stringifyNajmThemeConfig(theme)` when persisting it, and parse settings loaded
 from an API or local storage with `parseNajmThemeConfig` before applying them.
 
-## Components
+## Components
 
 Import from `najm-kit`:
 
@@ -145,44 +145,172 @@ import { Form, FormInput, useNForm } from 'najm-kit';
 | Feedback | Alert, Badge, Progress, Spinner, Toast |
 | Layout | Card, Sheet, Dialog, Popover, DropdownMenu, Tabs |
 | Data | Table (NTable), StatCard, DetailList |
-| Overlays | Command palette, Tooltip, Toast |
-
-## Global form development tools
-
-Enable schema-driven test values once on the full application provider. Every
-`NForm` and `WizardForm` below it then fills from its Zod schema when F8 is
-pressed; applications do not need a second provider or a form-fill helper.
-
-```tsx
-import { NajmAppProvider } from "najm-kit/app";
-
-<NajmAppProvider formDevTools>
-  <App />
-</NajmAppProvider>;
-```
-
-Pass a boolean to control it from application settings:
-
-```tsx
-<NajmAppProvider formDevTools={formFillEnabled}>
-  <App />
-</NajmAppProvider>
-```
-
-Forms with live relation options can override only those fields. The provider
-still owns enablement and Najm Kit still owns schema traversal and generation.
-
-```tsx
-<NForm
-  schema={orderSchema}
-  devTools={{ overrides: { customerId: customerOptions } }}
-  onSubmit={saveOrder}
->
-  {/* fields */}
-</NForm>
-```
-
-## ImageInput and AvatarInput
+| Overlays | Command palette, Tooltip, Toast |
+
+## Images and avatars
+
+Three components, one fallback rule. Each tries its sources in order, tries a
+source at most once, and discards what it knows about a failure the moment the
+sources change.
+
+### `NImage` — plain `<img>`
+
+For a logo or an icon whose box the caller's CSS already owns. No layout is
+invented, and `onError` is forwarded rather than swallowed.
+
+```tsx
+import { NImage } from 'najm-kit';
+
+<NImage src={logo} fallback="/brand/logo.svg" alt="Acme" className="h-8 w-auto" />
+```
+
+### `NAvatar` — person or record
+
+The image is a native `<img>` loaded directly by the browser, so a same-origin
+protected route works with the session the page already has, and the package
+needs no knowledge of which routes are protected.
+
+```tsx
+import { NAvatar } from 'najm-kit';
+
+<NAvatar
+  src={member.image}
+  fallbackSrc={stockPortrait}
+  version={member.imageRevision}
+  title={member.name}
+  subtitle={member.role}
+  size="lg"
+/>
+```
+
+- The primary source is tried first, then `fallbackSrc`, then the initials.
+- `version` (or `srcVersion`) is appended as `?v=…` to every remote source, so a
+  re-upload is not served from cache. `data:` and `blob:` sources are left alone.
+- Initials stay visible until an image paints and come back if every source
+  fails — a transparent PNG never shows letters through itself.
+- `imageProps` reaches the element for `loading`, `sizes`, `crossOrigin`,
+  `referrerPolicy`, and the load/error handlers. It defaults to `loading="lazy"`,
+  and supplied handlers are composed with the fallback chain rather than
+  replacing it.
+
+### `NNextImage` — optimized, from `najm-kit/next`
+
+Same fallback contract with Next's optimizer, layout reservation, `fill`, and
+`sizes`. It lives only in the `najm-kit/next` entry, because the root package
+stays installable without Next.
+
+```tsx
+import { NNextImage } from 'najm-kit/next';
+
+// A public asset: let the optimizer resize and re-encode it.
+<NNextImage src="/covers/spring.png" alt="Spring" width={64} height={64} />
+```
+
+For an asset the browser must fetch directly — one behind an authenticated route,
+typically — the *application* says so:
+
+```tsx
+<NNextImage
+  src={record.image}
+  alt={record.name}
+  fill
+  sizes="64px"
+  unoptimized
+/>
+```
+
+`unoptimized` is passed at the call site rather than inferred from the URL:
+which routes are protected is the application's fact, not something a package
+can read off a path. It changes delivery mechanics only — session validation,
+permissions, privacy projection, and what bytes come back all remain the
+backend's.
+
+## Status badges
+
+`<NBadge status="…" />` already maps a broad lifecycle vocabulary onto the
+semantic colors, so it is correct without configuration:
+
+```tsx
+import { NBadge } from 'najm-kit';
+
+<NBadge status="out_for_delivery" />   // warning, "Out For Delivery"
+<NBadge status="nebulous" />           // neutral, "Nebulous"
+```
+
+What an application usually adds on top is the same three things at every call
+site: its look, its shape, and its own translated label. Declare them once:
+
+```tsx
+<NajmAppProvider
+  badgeDefaults={{
+    look: 'soft',
+    shape: 'pill',
+    statusLabelKeys: {
+      active: 'status.active',
+      out_for_delivery: 'status.outForDelivery',
+    },
+  }}
+>
+```
+
+`badgeDefaults` lives on `NajmUIProvider` and is inherited by
+`NajmNextUIProvider` and `NajmAppProvider`, so there is one place to set it.
+The keys are the application's catalog keys, resolved through the same `t` the
+provider already has — this package ships no status catalog. A language change
+recomputes every label without a remount.
+
+Resolution, most specific first:
+
+1. An explicit prop beats every provider default.
+2. `label` beats string children; string children beat the provider's label.
+3. A `statusLabels` literal beats a `statusLabelKeys` catalog lookup.
+4. An unmapped status is humanized (`pending_review` → `Pending Review`).
+5. A per-instance `statusMap`/`iconMap` merges over the provider's, so
+   overriding one status costs one status.
+6. Provider status defaults apply **only** when `status` is set —
+   `<NBadge>Beta</NBadge>` keeps the ordinary content-badge look.
+
+Statuses are matched through one rule, exported as `normalizeStatusToken`, so
+`Out-For-Delivery `, `out for delivery`, and `out_for_delivery` are the same
+key for colors, icons, and labels alike. Badge text is presentation: it renames
+nothing in the backend and validates no lifecycle transition.
+
+## Global form development tools
+
+Enable schema-driven test values once on the full application provider. Every
+`NForm` and `WizardForm` below it then fills from its Zod schema when F8 is
+pressed; applications do not need a second provider or a form-fill helper.
+
+```tsx
+import { NajmAppProvider } from "najm-kit/app";
+
+<NajmAppProvider formDevTools>
+  <App />
+</NajmAppProvider>;
+```
+
+Pass a boolean to control it from application settings:
+
+```tsx
+<NajmAppProvider formDevTools={formFillEnabled}>
+  <App />
+</NajmAppProvider>
+```
+
+Forms with live relation options can override only those fields. The provider
+still owns enablement and Najm Kit still owns schema traversal and generation.
+
+```tsx
+<NForm
+  schema={orderSchema}
+  devTools={{ overrides: { customerId: customerOptions } }}
+  onSubmit={saveOrder}
+>
+  {/* fields */}
+</NForm>
+```
+
+## ImageInput and AvatarInput
 
 `ImageInput` and `AvatarInput` ship with a resilient preview contract so
 consumers do not need to wrap them with application-specific preview
@@ -247,93 +375,93 @@ Key behaviors:
   a newer value, and object URLs created by the component are tracked so
   consumer-owned blob URLs are never revoked.
 
-`AvatarInput` forwards every preview and accessibility prop unchanged while
-preserving its circular, size, fill, and camera-icon defaults.
-
-## Formatting
-
-Pure formatters are available from the server-safe `najm-kit/format` entry.
-Money values are integer minor units and use the currency's own exponent (for
-example MAD has two decimals, JPY zero, and KWD three).
-
-```ts
-import { formatCurrency, formatDate, slugify } from 'najm-kit/format';
-
-formatCurrency(12_500, { locale: 'fr-MA', currency: 'MAD' });
-formatDate('2026-08-08T20:00:00Z', {
-  locale: 'fr-MA',
-  timeZone: 'Africa/Casablanca',
-});
-slugify('Najm Format & Pagination');
-```
-
-Client code can use the active locale, time zone, currency, and placeholder
-through `useNajmFormat`. `NajmAppProvider` mounts the format provider for you:
-
-```tsx
-import { NajmAppProvider } from 'najm-kit/app';
-import { useNajmFormat } from 'najm-kit';
-
-<NajmAppProvider
-  translations={translations}
-  currency="MAD"
-  locales={{ en: 'en-MA', fr: 'fr-MA' }}
->
-  <App />
-</NajmAppProvider>
-
-function Total({ value }: { value: number }) {
-  return <span>{useNajmFormat().money(value)}</span>;
-}
-```
-
-## Offset pagination and queries
-
-`najm-kit/pagination` is server-safe and framework-independent. It accepts
-endpoints that return either `{ rows, total }` or a bare row array. When no
-total exists it probes for one extra row; when a total exists continuation is
-calculated without another request.
-
-```ts
-import {
-  createOffsetPagination,
-  fetchOffsetPage,
-} from 'najm-kit/pagination';
-
-const pagination = createOffsetPagination(pageIndex, pageSize);
-const page = await fetchOffsetPage(
-  ({ limit, offset }) => api.orders.list({ limit, offset }),
-  pagination,
-);
-```
-
-React Query consumers install the optional `@tanstack/react-query` peer and use
-the isolated `najm-kit/query` entry. `useResponsiveOffsetList` resolves numbered
-desktop paging versus card continuation and exposes props that plug directly
-into `NTable` and `createCardPagination`.
-
-```tsx
-import { NTable, createCardPagination } from 'najm-kit';
-import { useResponsiveOffsetList } from 'najm-kit/query';
-
-const list = useResponsiveOffsetList({
-  queryKey: ['orders'],
-  fetchPage: ({ limit, offset }) => api.orders.list({ limit, offset }),
-  strategy: 'paged',
-});
-
-<NTable
-  data={list.data}
-  columns={columns}
-  manualPagination
-  pageCount={list.pageCount}
-  pagination={list.pagination}
-  onPaginationChange={list.onPaginationChange}
-  cardPagination={createCardPagination(list, labels)}
-/>
-```
-
-## Hooks
+`AvatarInput` forwards every preview and accessibility prop unchanged while
+preserving its circular, size, fill, and camera-icon defaults.
+
+## Formatting
+
+Pure formatters are available from the server-safe `najm-kit/format` entry.
+Money values are integer minor units and use the currency's own exponent (for
+example MAD has two decimals, JPY zero, and KWD three).
+
+```ts
+import { formatCurrency, formatDate, slugify } from 'najm-kit/format';
+
+formatCurrency(12_500, { locale: 'fr-MA', currency: 'MAD' });
+formatDate('2026-08-08T20:00:00Z', {
+  locale: 'fr-MA',
+  timeZone: 'Africa/Casablanca',
+});
+slugify('Najm Format & Pagination');
+```
+
+Client code can use the active locale, time zone, currency, and placeholder
+through `useNajmFormat`. `NajmAppProvider` mounts the format provider for you:
+
+```tsx
+import { NajmAppProvider } from 'najm-kit/app';
+import { useNajmFormat } from 'najm-kit';
+
+<NajmAppProvider
+  translations={translations}
+  currency="MAD"
+  locales={{ en: 'en-MA', fr: 'fr-MA' }}
+>
+  <App />
+</NajmAppProvider>
+
+function Total({ value }: { value: number }) {
+  return <span>{useNajmFormat().money(value)}</span>;
+}
+```
+
+## Offset pagination and queries
+
+`najm-kit/pagination` is server-safe and framework-independent. It accepts
+endpoints that return either `{ rows, total }` or a bare row array. When no
+total exists it probes for one extra row; when a total exists continuation is
+calculated without another request.
+
+```ts
+import {
+  createOffsetPagination,
+  fetchOffsetPage,
+} from 'najm-kit/pagination';
+
+const pagination = createOffsetPagination(pageIndex, pageSize);
+const page = await fetchOffsetPage(
+  ({ limit, offset }) => api.orders.list({ limit, offset }),
+  pagination,
+);
+```
+
+React Query consumers install the optional `@tanstack/react-query` peer and use
+the isolated `najm-kit/query` entry. `useResponsiveOffsetList` resolves numbered
+desktop paging versus card continuation and exposes props that plug directly
+into `NTable` and `createCardPagination`.
+
+```tsx
+import { NTable, createCardPagination } from 'najm-kit';
+import { useResponsiveOffsetList } from 'najm-kit/query';
+
+const list = useResponsiveOffsetList({
+  queryKey: ['orders'],
+  fetchPage: ({ limit, offset }) => api.orders.list({ limit, offset }),
+  strategy: 'paged',
+});
+
+<NTable
+  data={list.data}
+  columns={columns}
+  manualPagination
+  pageCount={list.pageCount}
+  pagination={list.pagination}
+  onPaginationChange={list.onPaginationChange}
+  cardPagination={createCardPagination(list, labels)}
+/>
+```
+
+## Hooks
 
 ```tsx
 import { useKeyboard } from 'najm-kit';
@@ -397,116 +525,116 @@ Notes:
 - The columns the TanStack table receives are already filtered, so the
   settings menu will not list `visible: false` columns.
 
-If you need to inspect or build your own effective column list, the same
-pure helper is exported as `filterResponsiveColumns`. The literal class
-map is also exported as `hiddenBelowClasses`, and
-`resolveHiddenBelowClass(breakpoint)` returns the class for a single
-breakpoint or `undefined` when no breakpoint is set.
-
-## NTable responsive cards, loading, and pagination
-
-Responsive row actions are visible by default on phone, tablet, and coarse or
-non-hover pointers. Fine-pointer desktop layouts may reveal them on hover, but
-keyboard focus always reveals the action. Applications still decide which menu
-items exist through `menu`, `onView`, `onEdit`, and `onDelete`; visibility does
-not grant an action or replace server authorization.
-
-When `dynamicHeight` is enabled, table and card loading skeletons measure the
-available body. Table rows use the same header/row geometry as dynamic page
-sizing, while cards measure the active grid columns, card height, and gap. The
-loading surface also follows the loaded `bordered`, design recipe, radius,
-border color, shadow, and `classNames.content`/`classNames.cards` contract.
-
-Use `cardPagination` to choose pagination presentation whenever the effective
-rendered mode is cards:
-
-- `{ mode: "paged" }` (the default) preserves existing pagination.
-- `{ mode: "all" }` renders every row already supplied and hides the footer.
-- `{ mode: "load-more", ... }` renders every supplied row and provides a
-  guarded, keyboard-operable Load more/Retry control with polite loading,
-  appended-result, and end-of-list announcements.
-
-`showPagination={false}` remains an absolute presentation override and hides
-both numbered controls and Load more. In table mode, existing controlled and
-manual server pagination remains unchanged.
-
-```tsx
-import { NTable, type NTableCardPagination } from "najm-kit";
-
-const cardPagination: NTableCardPagination = {
-  mode: "load-more",
-  hasNextPage: query.hasNextPage,
-  loadingMore: query.isFetchingNextPage,
-  loadMoreError: query.isFetchNextPageError
-    ? "The next page could not be loaded."
-    : undefined,
-  onLoadMore: () => query.fetchNextPage(),
-  loadMoreLabel: "Load more",
-  loadingMoreLabel: "Loading more...",
-  retryLabel: "Retry",
-  endLabel: "No more results.",
-};
-
-<NTable
-  data={query.data?.pages.flatMap((page) => page.rows) ?? []}
-  columns={columns}
-  getRowId={(row) => row.id}
-  renderCard={ResultCard}
-  cardPagination={cardPagination}
-/>
-```
-
-The application owns the query, cursor/offset, accumulated pages, cache
-invalidation, search/filter/sort semantics, authorization, and privacy
-projection. Najm Kit never imports React Query, calls an endpoint, invents a
-page size, or treats supplied rows as proof that every database row is loaded.
-Client sorting and filtering cover the rows currently supplied unless the
-application implements matching server-side behavior.
-
-For a responsive screen that uses current-page data in desktop table mode and
-accumulated pages in card mode, keep those two query shapes in the application
-and pass the appropriate `data`. Crossing the `<640px` responsive-card
-breakpoint does not overwrite the user's chosen view, pagination position,
-sorting, filters, expansion, or row selection.
-
-## Theme-backed charts
-
-`NBarChart`, `NLineChart`, `NPieChart`, and `NStatusBreakdown` accept generic
-caller-formatted data and use `--chart-1` through `--chart-5` by default.
-Colors repeat deterministically after the fifth series or item; set `color` on
-an exceptional series/item to override that one value. Each chart accepts
-`loading`/`loadingLabel` and renders an accessible shape-matched skeleton.
-`NPieChart` and `NDonutCard` accept `size="sm" | "md" | "lg"` or a numeric
-pixel diameter and shrink within narrow containers.
-
-```tsx
-import { NBarChart, NPieChart } from "najm-kit";
-
-const data = [
-  { id: "jan", label: "Jan", values: { received: 12, refunded: 2 } },
-  { id: "feb", label: "Feb", values: { received: 18, refunded: 1 } },
-];
-
-<NBarChart
-  title="Monthly activity"
-  data={data}
-  series={[
-    { id: "received", label: "Received" },
-    { id: "refunded", label: "Refunded" },
-  ]}
-  valueFormatter={(value) => `${value} MAD`}
-/>
-
-<NPieChart
-  title="Status"
-  size={132}
-  items={[
-    { id: "active", label: "Active", value: 8 },
-    { id: "pending", label: "Pending", value: 3 },
-  ]}
-/>
-```
-
+If you need to inspect or build your own effective column list, the same
+pure helper is exported as `filterResponsiveColumns`. The literal class
+map is also exported as `hiddenBelowClasses`, and
+`resolveHiddenBelowClass(breakpoint)` returns the class for a single
+breakpoint or `undefined` when no breakpoint is set.
+
+## NTable responsive cards, loading, and pagination
+
+Responsive row actions are visible by default on phone, tablet, and coarse or
+non-hover pointers. Fine-pointer desktop layouts may reveal them on hover, but
+keyboard focus always reveals the action. Applications still decide which menu
+items exist through `menu`, `onView`, `onEdit`, and `onDelete`; visibility does
+not grant an action or replace server authorization.
+
+When `dynamicHeight` is enabled, table and card loading skeletons measure the
+available body. Table rows use the same header/row geometry as dynamic page
+sizing, while cards measure the active grid columns, card height, and gap. The
+loading surface also follows the loaded `bordered`, design recipe, radius,
+border color, shadow, and `classNames.content`/`classNames.cards` contract.
+
+Use `cardPagination` to choose pagination presentation whenever the effective
+rendered mode is cards:
+
+- `{ mode: "paged" }` (the default) preserves existing pagination.
+- `{ mode: "all" }` renders every row already supplied and hides the footer.
+- `{ mode: "load-more", ... }` renders every supplied row and provides a
+  guarded, keyboard-operable Load more/Retry control with polite loading,
+  appended-result, and end-of-list announcements.
+
+`showPagination={false}` remains an absolute presentation override and hides
+both numbered controls and Load more. In table mode, existing controlled and
+manual server pagination remains unchanged.
+
+```tsx
+import { NTable, type NTableCardPagination } from "najm-kit";
+
+const cardPagination: NTableCardPagination = {
+  mode: "load-more",
+  hasNextPage: query.hasNextPage,
+  loadingMore: query.isFetchingNextPage,
+  loadMoreError: query.isFetchNextPageError
+    ? "The next page could not be loaded."
+    : undefined,
+  onLoadMore: () => query.fetchNextPage(),
+  loadMoreLabel: "Load more",
+  loadingMoreLabel: "Loading more...",
+  retryLabel: "Retry",
+  endLabel: "No more results.",
+};
+
+<NTable
+  data={query.data?.pages.flatMap((page) => page.rows) ?? []}
+  columns={columns}
+  getRowId={(row) => row.id}
+  renderCard={ResultCard}
+  cardPagination={cardPagination}
+/>
+```
+
+The application owns the query, cursor/offset, accumulated pages, cache
+invalidation, search/filter/sort semantics, authorization, and privacy
+projection. Najm Kit never imports React Query, calls an endpoint, invents a
+page size, or treats supplied rows as proof that every database row is loaded.
+Client sorting and filtering cover the rows currently supplied unless the
+application implements matching server-side behavior.
+
+For a responsive screen that uses current-page data in desktop table mode and
+accumulated pages in card mode, keep those two query shapes in the application
+and pass the appropriate `data`. Crossing the `<640px` responsive-card
+breakpoint does not overwrite the user's chosen view, pagination position,
+sorting, filters, expansion, or row selection.
+
+## Theme-backed charts
+
+`NBarChart`, `NLineChart`, `NPieChart`, and `NStatusBreakdown` accept generic
+caller-formatted data and use `--chart-1` through `--chart-5` by default.
+Colors repeat deterministically after the fifth series or item; set `color` on
+an exceptional series/item to override that one value. Each chart accepts
+`loading`/`loadingLabel` and renders an accessible shape-matched skeleton.
+`NPieChart` and `NDonutCard` accept `size="sm" | "md" | "lg"` or a numeric
+pixel diameter and shrink within narrow containers.
+
+```tsx
+import { NBarChart, NPieChart } from "najm-kit";
+
+const data = [
+  { id: "jan", label: "Jan", values: { received: 12, refunded: 2 } },
+  { id: "feb", label: "Feb", values: { received: 18, refunded: 1 } },
+];
+
+<NBarChart
+  title="Monthly activity"
+  data={data}
+  series={[
+    { id: "received", label: "Received" },
+    { id: "refunded", label: "Refunded" },
+  ]}
+  valueFormatter={(value) => `${value} MAD`}
+/>
+
+<NPieChart
+  title="Status"
+  size={132}
+  items={[
+    { id: "active", label: "Active", value: 8 },
+    { id: "pending", label: "Pending", value: 3 },
+  ]}
+/>
+```
+
 ### Server-backed combobox search
 
 `ComboboxInput` and `FormInput type="combobox"` can delegate filtering to a
@@ -600,4 +728,116 @@ only, after a real `image` and before the role's gender variant:
 ```ts
 getPersonImage({ image: child.image, role: "child", gender: child.gender, fallback: child.placeholder });
 ```
-
+
+
+## Server UI bootstrap (`najm-kit/server`, `najm-kit/server/react`)
+
+An application that renders its own theme and its own logos on the server ends
+up writing the same module every time: fetch the public endpoints, unwrap the
+`data` envelope, validate the payload, fall back to the built-in assets when
+any of that fails, and run the resources in parallel. These two entries own
+that mechanism. What stays with the application is what is genuinely
+application-specific — how a request reaches its own backend, which paths it
+serves, what a valid payload looks like, what the factory values are, and where
+a diagnostic goes.
+
+Neither entry is re-exported from `najm-kit`, `najm-kit/next`, or
+`najm-kit/app`. `najm-kit/server` imports no React at all, so a route handler
+or a plain script can use it.
+
+### The application's one server module
+
+```ts
+// src/lib/serverLoader.ts
+import "server-only";
+
+import { parseNajmDesignConfig } from "najm-kit/server";
+import { createReactServerUiBootstrap } from "najm-kit/server/react";
+
+export const serverUi = createReactServerUiBootstrap({
+  fetcher: async (path) => {
+    const { server } = await import("@app/server");
+    return server.fetch(new Request(`http://internal${path}`));
+  },
+  resources: {
+    appearance: {
+      path: "/api/appearance",
+      parse: parseAppearance,          // returns undefined or throws to reject
+      fallback: getFactoryAppearance,  // called per load
+    },
+    branding: {
+      path: "/api/branding",
+      parse: parseBranding,
+      fallback: getFactoryBranding,
+    },
+  },
+  onDiagnostic: (diagnostic) => {
+    console.warn(`[ui-bootstrap] ${diagnostic.resource} ${diagnostic.reason}`, diagnostic);
+  },
+});
+
+export const loadServerUiBootstrap = serverUi.load;
+export const { appearance: loadServerAppearance, branding: loadServerBranding } =
+  serverUi.loaders;
+```
+
+`load()` resolves every resource; `loaders.<name>()` and `loadResource(name)`
+read one off the same resolution. Resource names, payload types, and the number
+of resources are the application's — the snapshot type is inferred from the
+`resources` object, so `snapshot.branding` is your branding type and not a
+package interface.
+
+### Call the factory once, at module scope
+
+`createReactServerUiBootstrap()` builds one `React.cache()` entry. Calling it
+inside a layout, page, or component builds a fresh one per call and shares
+nothing. Every server boundary in a render must import the same module.
+
+The cache is React's, so it is request-scoped and nothing else: separate
+requests never see each other's snapshot or each other's failure, and a
+transient outage is retried on the next request rather than pinned into a
+process-global. That also rules out a module `Map`, a module promise,
+`unstable_cache`, `"use cache"`, or a durable cache here — every one of them
+would leak one visitor's render into another's.
+
+The snapshot is deliberately stable for the length of one render. A settings
+surface that saves appearance or branding updates the client provider and then
+refreshes or navigates into a new render to observe the persisted result.
+
+Outside a render — route handlers, server actions, scripts — use
+`createUiBootstrapLoader()` from `najm-kit/server` directly. There is no request
+cache for `cache()` to write to there, so the adapter would silently re-fetch
+per call.
+
+### Failure behaviour
+
+Resources fall back independently: a branding outage never discards a valid
+appearance. Each failure calls `onDiagnostic` once with a `reason` of
+`fetch-failed`, `response-not-ok`, `invalid-json`, `invalid-envelope`, or
+`invalid-payload`, plus the path and — for a non-success response — the status.
+Diagnostics never carry response bodies, headers, cookies, or raw thrown
+values; `error` is a normalized `"<name>: <message>"` for an `Error` and the
+value's type for anything else.
+
+A `fallback()` that throws is **not** caught. A missing factory theme is the
+application's configuration error, and a second fallback would only hide it.
+
+Falling back is right for *public* appearance and branding, where the worst case
+is a visitor seeing the built-in logo. It is not a general rule: do not route
+authenticated, financial, or privacy-sensitive reads through this, because a
+silent fallback there hides an outage behind plausible-looking data.
+
+### Envelopes
+
+`select` defaults to Najm's `{ data }` envelope. Applications behind a different
+envelope pass their own at the loader level or per resource; returning the
+payload unchanged is a valid selector, and throwing rejects the response as
+`invalid-envelope`.
+
+### Client Components
+
+`najm-kit/server/react` maps the `browser` export condition to a module that
+throws, so importing it from a Client Component fails the build with an
+explanation rather than shipping the application's fetcher and factory values
+into a browser bundle. Seed the client from the server snapshot through
+`NajmAppProvider` instead.