@stapel/categories-react 0.1.0

package/src/i18n/keys.ts

@@ -0,0 +1,156 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { categoriesErrorBundleEn } from "./generated/errors.gen.js";
+
+/**
+ * categories-react's own translation KEYS (frontend-standard §4.2): headless
+ * components never render literal strings — hosts resolve these via core's
+ * i18n engine (`useT`). Backend error codes flow through the SAME contour: a
+ * `StapelApiError.code` is already a key, so the default bundle below ships
+ * English fallbacks for the 62 backend error codes (generated) plus the pair's
+ * own UI keys. All UI keys live under the `categories.` namespace.
+ *
+ * ── WHAT IS DELIBERATELY NOT IN THIS FILE ──────────────────────────────────
+ *
+ * **A category name.** `category.electronics` is a key, and it is a key this
+ * library must never carry a text for: the catalogue is a deployment's
+ * content, not a library's chrome, and no two marketplaces have the same tree.
+ * `catalog/labels.ts` explains the mechanism in full — names arrive as keys
+ * because no serializer runs the module's `DISPLAY_TRANSLATOR` seam — and the
+ * pair's answer is to hand the key to the HOST's engine, whose bundle is where
+ * a deployment's catalogue copy belongs. When the key does not resolve the key
+ * is shown, on purpose: a visible `category.electronics` gets fixed, while a
+ * prettified "Electronics" ships for a year in the wrong language.
+ *
+ * The same goes for a feature's name and its option labels.
+ *
+ * **The twelve `error.400.feature_*` / `description_too_*` keys.** They are
+ * owned by `stapel_attributes` and translated by `@stapel/attributes-react`
+ * (`/i18n/ru`, `/i18n/es`) — the package that also draws and validates those
+ * values. Restating them here would give one refusal two sentences, which is
+ * the exact thing §13.2's note 3 closed. A host registers both bundles; the
+ * suite proves the union covers the whole registry.
+ */
+export const CATEGORIES_I18N_KEYS = {
+  unknownError: "categories.error.unknown",
+
+  // ── catalog / tree ───────────────────────────────────────────────────────
+  catalogTitle: "categories.catalog.title",
+  catalogLoading: "categories.catalog.loading",
+  catalogLoadFailed: "categories.catalog.load_failed",
+  catalogEmpty: "categories.catalog.empty",
+  catalogRetry: "categories.catalog.retry",
+  /** The sync walk hit its page budget — the tree on screen is incomplete. */
+  catalogTruncated: "categories.catalog.truncated",
+  catalogRefreshing: "categories.catalog.refreshing",
+  catalogAsOf: "categories.catalog.as_of",
+
+  // ── one category ─────────────────────────────────────────────────────────
+  categoryTitle: "categories.category.title",
+  categoryUnknownSlug: "categories.category.unknown_slug",
+  categorySubcategories: "categories.category.subcategories",
+  /** A leaf: no sub-categories, and that is not an error. */
+  categoryNoSubcategories: "categories.category.no_subcategories",
+  categoryOpen: "categories.category.open",
+
+  // ── breadcrumbs ──────────────────────────────────────────────────────────
+  breadcrumbsRoot: "categories.breadcrumbs.root",
+  breadcrumbsLabel: "categories.breadcrumbs.label",
+
+  // ── carousel ─────────────────────────────────────────────────────────────
+  carouselTitle: "categories.carousel.title",
+  carouselLoading: "categories.carousel.loading",
+  carouselLoadFailed: "categories.carousel.load_failed",
+  carouselEmpty: "categories.carousel.empty",
+
+  // ── picker (the compose form's chooser) ──────────────────────────────────
+  pickerTitle: "categories.picker.title",
+  pickerSearch: "categories.picker.search",
+  pickerLoading: "categories.picker.loading",
+  pickerLoadFailed: "categories.picker.load_failed",
+  pickerNoMatches: "categories.picker.no_matches",
+  pickerUp: "categories.picker.up",
+  pickerSelected: "categories.picker.selected",
+  pickerBlockedNothingSelected: "categories.picker.blocked.nothing_selected",
+  pickerBlockedNotALeaf: "categories.picker.blocked.not_a_leaf",
+
+  // ── feature schema ───────────────────────────────────────────────────────
+  featuresTitle: "categories.features.title",
+  featuresLoading: "categories.features.loading",
+  featuresLoadFailed: "categories.features.load_failed",
+  featuresEmpty: "categories.features.empty",
+  featuresMandatory: "categories.features.mandatory",
+  featuresType: "categories.features.type",
+  /** A feature whose `config` carries no `type` at all. */
+  featuresUntyped: "categories.features.untyped",
+} as const;
+
+export type CategoriesI18nKey =
+  (typeof CATEGORIES_I18N_KEYS)[keyof typeof CATEGORIES_I18N_KEYS];
+
+/**
+ * English fallback bundle for categories-react UI keys + backend error codes.
+ * The generated backend texts are spread FIRST so coverage of the error
+ * registry is by construction; the pair's own copy follows.
+ */
+export const categoriesI18nBundleEn: Record<string, string> = {
+  ...categoriesErrorBundleEn,
+
+  "categories.error.unknown": "Something went wrong with the catalogue",
+
+  "categories.catalog.title": "Catalogue",
+  "categories.catalog.loading": "Loading the catalogue…",
+  "categories.catalog.load_failed": "We could not load the catalogue",
+  "categories.catalog.empty": "This catalogue has no categories yet",
+  "categories.catalog.retry": "Try again",
+  "categories.catalog.truncated":
+    "Only part of the catalogue was loaded. A category missing here has not been read yet — it has not been removed.",
+  "categories.catalog.refreshing": "Checking for catalogue changes…",
+  "categories.catalog.as_of": "Catalogue as of revision {revision}",
+
+  "categories.category.title": "Category",
+  "categories.category.unknown_slug":
+    "There is no category at this address",
+  "categories.category.subcategories": "Subcategories",
+  "categories.category.no_subcategories": "This category has no subcategories",
+  "categories.category.open": "Open",
+
+  "categories.breadcrumbs.root": "All categories",
+  "categories.breadcrumbs.label": "You are here",
+
+  "categories.carousel.title": "Browse by category",
+  "categories.carousel.loading": "Loading categories…",
+  "categories.carousel.load_failed": "We could not load the categories",
+  "categories.carousel.empty": "No categories are featured right now",
+
+  "categories.picker.title": "Category",
+  "categories.picker.search": "Search categories",
+  "categories.picker.loading": "Loading categories…",
+  "categories.picker.load_failed": "We could not load the categories",
+  "categories.picker.no_matches": "No category matches that",
+  "categories.picker.up": "Up one level",
+  "categories.picker.selected": "Selected: {category}",
+  "categories.picker.blocked.nothing_selected": "Choose a category first",
+  "categories.picker.blocked.not_a_leaf":
+    "Choose a more specific category — this one has subcategories, and the details asked for depend on which",
+
+  "categories.features.title": "Details in this category",
+  "categories.features.loading": "Loading the details…",
+  "categories.features.load_failed": "We could not load the details",
+  "categories.features.empty": "This category asks for no extra details",
+  "categories.features.mandatory": "Required",
+  "categories.features.type": "{type}",
+  "categories.features.untyped": "This detail has no type and cannot be shown",
+};
+
+/**
+ * Register the English bundle into a core i18n engine. Locale bundles ship as
+ * opt-in subpaths (`@stapel/categories-react/i18n/ru`, `…/es`) so a host that
+ * needs only English never carries them.
+ *
+ * A host that renders a category's feature schema also registers
+ * `@stapel/attributes-react`'s bundles — that package owns the twelve
+ * `stapel_attributes` error keys in every locale.
+ */
+export function registerCategoriesI18n(i18n: I18nEngine): void {
+  i18n.registerBundle("en", categoriesI18nBundleEn as I18nDictionary);
+}

package/src/i18n/ru.ts

@@ -0,0 +1,110 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { categoriesErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+export { categoriesErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+/**
+ * Russian bundle for categories-react — the `@stapel/categories-react/i18n/ru`
+ * subpath (i18n-shipping.md §2) so the locale is opt-in: hosts that do not
+ * register it never carry these strings (the main entry does not import this
+ * module — gated by size-limit + the bundle-purity test).
+ *
+ * This is the storefront's DEFAULT language (storefront spec verdict F1:
+ * ru-first).
+ *
+ * ── What comes from where ──────────────────────────────────────────────────
+ *
+ * `stapel-categories` ships **no `translations/` directory at all**, so 20 of
+ * the 62 registry codes can never come from an upstream catalogue. They split
+ * by owner, and the split is the whole point:
+ *
+ *  - the 42 cross-cutting `stapel_core` codes are GENERATED, merged in from
+ *    stapel-core's own catalogue by `pnpm gen:errors` (spread first below);
+ *  - the **8 `stapel_categories` codes** are authored here — and when upstream
+ *    ships a catalogue, eight lines are deleted and no key or text moves;
+ *  - the **12 `stapel_attributes` codes** are NOT here. They belong to
+ *    `@stapel/attributes-react`, which already translates them and which is a
+ *    peer of this pair anyway. Two pairs must not give one refusal two
+ *    sentences (§13.2 note 3). A host registers both bundles;
+ *    `test/i18n.test.ts` proves the union covers the registry.
+ *
+ * PROVENANCE, stated rather than implied: the core catalogue ships
+ * `origin=seed:authored` and is UNREVIEWED; the pair-authored strings below
+ * are the same grade. Neither is a claim of review.
+ *
+ * And once more, because it is the fact this pair exists to be honest about:
+ * **no category name is translated here.** Category and feature names arrive
+ * as translation KEYS (`catalog/labels.ts`) and belong in the deployment's own
+ * bundle, not in a library's.
+ */
+export const categoriesI18nBundleRu: I18nDictionary = {
+  ...categoriesErrorBundleRu,
+
+  // ── the 8 stapel_categories-owned codes, pair-authored ───────────────────
+  "error.400.categories_config_required": "Требуется объект config.",
+  "error.400.categories_database_error":
+    "Ошибка базы данных при сохранении изменений.",
+  "error.400.categories_duplicate_slug":
+    "Характеристика со слагом «{slug}» уже существует.",
+  "error.400.categories_expected_list": "Ожидался список объектов.",
+  "error.400.categories_feature_editor_invalid":
+    "Некорректный запрос редактора характеристик: {reason}",
+  "error.400.categories_invalid_conversion":
+    "Недопустимое преобразование типа (поддерживается только select ↔ string).",
+  "error.400.categories_not_deleted": "Категория не удалена.",
+  "error.409.categories_feature_editor_conflict":
+    "Категорию изменил другой редактор (ожидалась ревизия {expected}, сейчас {actual}); перезагрузите страницу и повторите.",
+
+  "categories.error.unknown": "Что-то пошло не так с каталогом.",
+
+  "categories.catalog.title": "Каталог",
+  "categories.catalog.loading": "Загружаем каталог…",
+  "categories.catalog.load_failed": "Не удалось загрузить каталог.",
+  "categories.catalog.empty": "В каталоге пока нет категорий.",
+  "categories.catalog.retry": "Повторить",
+  "categories.catalog.truncated":
+    "Каталог загружен не полностью. Категории, которой здесь нет, ещё не прочитали — её не удаляли.",
+  "categories.catalog.refreshing": "Проверяем изменения в каталоге…",
+  "categories.catalog.as_of": "Каталог на ревизию {revision}",
+
+  "categories.category.title": "Категория",
+  "categories.category.unknown_slug": "По этому адресу нет категории.",
+  "categories.category.subcategories": "Подкатегории",
+  "categories.category.no_subcategories": "У этой категории нет подкатегорий.",
+  "categories.category.open": "Открыть",
+
+  "categories.breadcrumbs.root": "Все категории",
+  "categories.breadcrumbs.label": "Вы здесь",
+
+  "categories.carousel.title": "Категории",
+  "categories.carousel.loading": "Загружаем категории…",
+  "categories.carousel.load_failed": "Не удалось загрузить категории.",
+  "categories.carousel.empty": "Сейчас ни одна категория не вынесена на витрину.",
+
+  "categories.picker.title": "Категория",
+  "categories.picker.search": "Поиск по категориям",
+  "categories.picker.loading": "Загружаем категории…",
+  "categories.picker.load_failed": "Не удалось загрузить категории.",
+  "categories.picker.no_matches": "Ни одна категория не подходит.",
+  "categories.picker.up": "На уровень выше",
+  "categories.picker.selected": "Выбрано: {category}",
+  "categories.picker.blocked.nothing_selected": "Сначала выберите категорию.",
+  "categories.picker.blocked.not_a_leaf":
+    "Выберите категорию точнее — у этой есть подкатегории, а от них зависит, какие характеристики спросят.",
+
+  "categories.features.title": "Характеристики в этой категории",
+  "categories.features.loading": "Загружаем характеристики…",
+  "categories.features.load_failed": "Не удалось загрузить характеристики.",
+  "categories.features.empty":
+    "В этой категории не нужно заполнять дополнительные характеристики.",
+  "categories.features.mandatory": "Обязательно",
+  "categories.features.type": "{type}",
+  "categories.features.untyped":
+    "У этой характеристики нет типа, показать её нельзя.",
+};
+
+/** Register the `ru` bundle. Call AFTER `registerCategoriesI18n` so it
+ * overrides the English floor. */
+export function registerCategoriesI18nRu(engine: I18nEngine, locale = "ru"): void {
+  engine.registerBundle(locale, categoriesI18nBundleRu);
+}

package/src/index.ts

@@ -0,0 +1,191 @@
+/**
+ * `@stapel/categories-react` — the headless React pair for stapel-categories
+ * (frontend-standard §2). Business + state only, zero visual opinion; the antd
+ * skin lives behind the `./default` subpath, so a host that renders its own
+ * catalogue chrome never carries it.
+ *
+ * ── The one-liner ──────────────────────────────────────────────────────────
+ *
+ * ```tsx
+ * const runtime = createCategoriesRuntime({ baseUrl: "/categories/api/v1/" });
+ * <CategoriesProvider runtime={runtime}>
+ *   <CatalogPage />          // or <CategoryPage slug={slug} renderListings={…} />
+ * </CategoriesProvider>
+ * ```
+ *
+ * No session, no workspace id, no auth client: every endpoint this pair calls
+ * is a SAFE method under `ReadOnlyOrStaff`, so a catalogue renders for a
+ * visitor who will never sign in.
+ *
+ * ── The four properties this pair exists to guarantee ──────────────────────
+ *
+ * 1. **The client builds the tree, because the server has none.**
+ *    `GET /categories/` returns FLAT rows ordered by `revision`, with treenode
+ *    ancestry as COMMA-JOINED pk strings (`"1,7,12"`, `""` for a root).
+ *    `catalog/tree.ts` parses and assembles; `catalog/pks.ts` is the parser,
+ *    and it exists because the spec described those columns as arrays.
+ * 2. **The catalogue is synced by delta, not refetched.** A stored snapshot
+ *    (`createRepository`, `scope: "app"`) plus `?min_revision=` is the module's
+ *    own documented protocol; without it every storefront page pulls the whole
+ *    catalogue. Two things the documentation does not say are implemented
+ *    anyway and explained where they live: `revisions.deleted_ids` is the
+ *    complete tombstone channel (the `deleted: true` rows are paginated and a
+ *    short walk misses them), and a multi-page walk must pin `max_revision` or
+ *    a concurrent write shifts its page boundaries.
+ * 3. **A slug is resolved by the client, because the server cannot.**
+ *    `lookup_field` is never overridden and the list endpoint has no slug
+ *    filter, so `/c/:slug` resolves against the synced tree. That is a second,
+ *    independent reason the tree is cached.
+ * 4. **Names are translation KEYS, and this pair says so.** No serializer runs
+ *    the module's `DISPLAY_TRANSLATOR` seam, so `name` arrives as
+ *    `category.electronics` even on a deployment with a real translator
+ *    configured, and `translatable` / `translate` say per row whether a string
+ *    is a key at all. `catalog/labels.ts` carries the whole answer, and the
+ *    pair ships no catalogue of category names — those belong to the host.
+ *
+ * Layers: api → catalog (pure) → model → headless → i18n. Generated surfaces
+ * (the typed schema, the error map, the manifest, the nav manifest, llms.txt)
+ * are produced by the monorepo `gen:*` drivers from stapel-categories' own
+ * `docs/` artifacts and stand under drift gates.
+ */
+
+// ── api ──────────────────────────────────────────────────────────────────────
+export { categoryListParams, createCategoriesApi } from "./api/categoriesApi.js";
+export type { CategoriesApi } from "./api/categoriesApi.js";
+export type {
+  Category,
+  CategoryFeature,
+  CategoryListParams,
+  CategoryPage as CategoryListPage,
+  CategoryRevisions,
+  FeatureConfig,
+  MaxRevision,
+  Schemas,
+} from "./api/types.js";
+
+// ── catalog (pure: no React, no fetch, no storage) ───────────────────────────
+export { parseTreenodePks } from "./catalog/pks.js";
+export {
+  buildCategoryTree,
+  categoryAncestorIds,
+  categoryBreadcrumbs,
+  categoryChildIds,
+  flattenCategoryNodes,
+  resolveCategorySlug,
+} from "./catalog/tree.js";
+export type {
+  BuildCategoryTreeOptions,
+  CategoryIndex,
+  CategoryNode,
+} from "./catalog/tree.js";
+
+export {
+  EMPTY_SNAPSHOT,
+  applyCategoryPage,
+  firstPageRequest,
+  isEmptySnapshot,
+  nextPageRequest,
+  parseSnapshot,
+} from "./catalog/sync.js";
+export type { CategorySnapshot } from "./catalog/sync.js";
+
+export {
+  categoryLabel,
+  featureLabel,
+  featureOptionsAreKeys,
+  renderCategoryLabel,
+} from "./catalog/labels.js";
+export type { CategoryLabel, CategoryLabelKind } from "./catalog/labels.js";
+
+// ── model (runtime wiring, persistence, sync driver, hooks) ──────────────────
+export { createCategoriesRuntime } from "./model/runtime.js";
+export type {
+  CategoriesRuntime,
+  CreateCategoriesRuntimeOptions,
+} from "./model/runtime.js";
+export {
+  CategoriesRuntimeContext,
+  useCategoriesAnalytics,
+  useCategoriesApi,
+  useCategoriesRuntime,
+} from "./model/context.js";
+export {
+  CATALOG_KEY,
+  CATALOG_NAMESPACE,
+  createCatalogStore,
+  memoryCatalogStore,
+} from "./model/catalogStore.js";
+export type {
+  CatalogStore,
+  CreateCatalogStoreOptions,
+} from "./model/catalogStore.js";
+export { MAX_SYNC_PAGES, syncCatalog } from "./model/catalogSync.js";
+export type { SyncCatalogOptions, SyncCatalogResult } from "./model/catalogSync.js";
+export { catalogKeyOptions, categoriesQueryKeys } from "./model/queryKeys.js";
+export type { CatalogKeyOptions } from "./model/queryKeys.js";
+export {
+  useCategoriesRevision,
+  useCategoryCarousel,
+  useCategoryCatalog,
+  useCategoryChildren,
+  useCategoryFeatures,
+} from "./model/queries.js";
+export type {
+  CategoryCatalog,
+  UseCategoryCatalogOptions,
+} from "./model/queries.js";
+
+// ── headless (renderless components) ─────────────────────────────────────────
+export { CategoriesProvider } from "./headless/CategoriesProvider.js";
+export { CategoryTree } from "./headless/CategoryTree.js";
+export type { CategoryTreeBag, CategoryTreeProps } from "./headless/CategoryTree.js";
+export { CategoryBreadcrumbs } from "./headless/CategoryBreadcrumbs.js";
+export type {
+  CategoryBreadcrumbsBag,
+  CategoryBreadcrumbsProps,
+  CategoryCrumb,
+} from "./headless/CategoryBreadcrumbs.js";
+export { CategoryCarousel } from "./headless/CategoryCarousel.js";
+export type {
+  CarouselEntry,
+  CategoryCarouselBag,
+  CategoryCarouselProps,
+} from "./headless/CategoryCarousel.js";
+export { CategoryPicker } from "./headless/CategoryPicker.js";
+export type {
+  CategoryOption,
+  CategoryPickerBag,
+  CategoryPickerBlockedReason,
+  CategoryPickerProps,
+} from "./headless/CategoryPicker.js";
+export { CategoryFeatures } from "./headless/CategoryFeatures.js";
+export type {
+  CategoryFeatureEntry,
+  CategoryFeaturesBag,
+  CategoryFeaturesProps,
+} from "./headless/CategoryFeatures.js";
+
+// ── nav manifest (the pair's public surface declaration) ─────────────────────
+export { navEntries } from "./nav/manifest.js";
+
+// ── i18n ─────────────────────────────────────────────────────────────────────
+export {
+  CATEGORIES_I18N_KEYS,
+  categoriesI18nBundleEn,
+  registerCategoriesI18n,
+} from "./i18n/keys.js";
+export type { CategoriesI18nKey } from "./i18n/keys.js";
+
+// ── errors map (code → status/params/remediation/en; generated) ──────────────
+export {
+  CATEGORIES_ERRORS,
+  CATEGORIES_ERROR_CODES,
+  CATEGORIES_FEATURE_EDITOR_CONFLICT,
+  categoriesErrorBundleEn,
+  explainCategoriesError,
+} from "./i18n/errorsMap.js";
+export type {
+  CategoriesErrorCode,
+  CategoriesErrorSpec,
+  Remediation,
+} from "./i18n/errorsMap.js";

package/src/model/catalogStore.ts

@@ -0,0 +1,102 @@
+/**
+ * Where the catalogue lives between page loads.
+ *
+ * `createRepository` is the ONE sanctioned client-side persistence primitive
+ * (`@stapel/core` `repository.ts`; direct `localStorage` outside it is a lint
+ * error, `stapel/no-raw-storage`), and the spec's verdict (§4.3) puts the tree
+ * in it with `scope: "app"`.
+ *
+ * **`scope: "app"` is a correctness choice, not a size one.** A user-scoped
+ * repository is encrypted with the per-session key and wiped on logout, with
+ * no opt-out — both of which are wrong here twice over: the category tree is
+ * a deployment's PUBLIC content, identical for every visitor and for a visitor
+ * with no session at all, and wiping it at logout would re-download the whole
+ * catalogue for somebody who just signed out of a storefront they are still
+ * browsing. App scope also means `createRepository` never asks for a
+ * `SessionManager`, so the store works on a page with no auth wired at all.
+ *
+ * A repository read can fail or return junk (a private window, cleared site
+ * data, a snapshot written by an older shape). Every read here degrades to
+ * "no snapshot" — a cold sync costs one request; a cache that throws costs
+ * the page.
+ */
+import { createRepository } from "@stapel/core";
+import type { Repository } from "@stapel/core";
+import { EMPTY_SNAPSHOT, parseSnapshot } from "../catalog/sync.js";
+import type { CategorySnapshot } from "../catalog/sync.js";
+
+/** The repository namespace. Changing it orphans every stored snapshot, which
+ * is the intended migration for a shape change too large for `version`. */
+export const CATALOG_NAMESPACE = "categories.catalog";
+
+/** The single key inside that namespace. */
+export const CATALOG_KEY = "snapshot";
+
+/** Read / write the catalogue snapshot, with every failure mode absorbed. */
+export interface CatalogStore {
+  load(): Promise<CategorySnapshot>;
+  save(snapshot: CategorySnapshot): Promise<void>;
+  clear(): Promise<void>;
+}
+
+export interface CreateCatalogStoreOptions {
+  /** Inject a repository (tests, SSR, a host with its own backend). Default:
+   * an app-scoped repository under {@link CATALOG_NAMESPACE}. */
+  readonly repository?: Repository<unknown>;
+}
+
+/** A store that remembers nothing — the honest fallback when persistence is
+ * unavailable, and what a caller passes to opt out of caching entirely. */
+export function memoryCatalogStore(): CatalogStore {
+  let held: CategorySnapshot = EMPTY_SNAPSHOT;
+  return {
+    load: () => Promise.resolve(held),
+    save: (snapshot) => {
+      held = snapshot;
+      return Promise.resolve();
+    },
+    clear: () => {
+      held = EMPTY_SNAPSHOT;
+      return Promise.resolve();
+    },
+  };
+}
+
+export function createCatalogStore(
+  options: CreateCatalogStoreOptions = {}
+): CatalogStore {
+  let repository: Repository<unknown>;
+  try {
+    repository =
+      options.repository ??
+      createRepository<unknown>(CATALOG_NAMESPACE, { scope: "app" });
+  } catch {
+    // No storage backend at all (an exotic runtime, a locked-down origin).
+    return memoryCatalogStore();
+  }
+
+  return {
+    async load() {
+      try {
+        return parseSnapshot(await repository.get(CATALOG_KEY)) ?? EMPTY_SNAPSHOT;
+      } catch {
+        return EMPTY_SNAPSHOT;
+      }
+    },
+    async save(snapshot) {
+      try {
+        await repository.set(CATALOG_KEY, snapshot);
+      } catch {
+        // A full quota or a blocked origin must not fail the render that
+        // triggered the sync: the catalogue is already in memory and correct.
+      }
+    },
+    async clear() {
+      try {
+        await repository.del(CATALOG_KEY);
+      } catch {
+        /* nothing to undo */
+      }
+    },
+  };
+}

package/src/model/catalogSync.ts

@@ -0,0 +1,115 @@
+/**
+ * The sync walk: stored snapshot → one request or several → a fresh snapshot.
+ *
+ * Pure of React, so the same routine serves the hook, an SSR prefetch and a
+ * test. The rules it enforces are all in `catalog/sync.ts`; this is the loop
+ * that applies them, plus the two guards a loop over a paginated endpoint
+ * needs:
+ *
+ *  - a **page budget**, because `has_next` is server-reported and a bug there
+ *    (or a catalogue growing faster than the walk reads it) is an infinite
+ *    request loop against someone's production API, not a slow render; and
+ *  - **publish-on-completion**, so a walk that dies on page 3 leaves the
+ *    previous catalogue intact instead of replacing it with two thirds of one.
+ */
+import type { CategoriesApi } from "../api/categoriesApi.js";
+import type { CategoryListParams } from "../api/types.js";
+import {
+  EMPTY_SNAPSHOT,
+  applyCategoryPage,
+  firstPageRequest,
+  isEmptySnapshot,
+  nextPageRequest,
+} from "../catalog/sync.js";
+import type { CategorySnapshot } from "../catalog/sync.js";
+
+/**
+ * Hard ceiling on pages per sync. At the server's max `page_size` of 1000 this
+ * is a million categories — far beyond any real catalogue, and small enough
+ * that a runaway loop stops in seconds instead of hammering a backend.
+ */
+export const MAX_SYNC_PAGES = 1000;
+
+export interface SyncCatalogOptions {
+  readonly signal?: AbortSignal;
+  /** Rows per request. Server default 100, maximum 1000. */
+  readonly pageSize?: number;
+  readonly maxPages?: number;
+}
+
+export interface SyncCatalogResult {
+  readonly snapshot: CategorySnapshot;
+  /** `true` when the walk started from nothing (a cold catalogue). */
+  readonly wasFullSync: boolean;
+  /** How many requests the walk actually made. `0` is impossible — the
+   * freshness probe is the caller's job, not this function's. */
+  readonly pages: number;
+  /** The page budget stopped the walk before `has_next` did. The snapshot is
+   * a truncated catalogue and the caller must NOT treat it as complete. */
+  readonly truncated: boolean;
+}
+
+/**
+ * Bring `stored` up to date.
+ *
+ * A cold start walks the whole catalogue into a fresh accumulator; a warm
+ * start folds the delta into the stored rows. Which one happens is decided by
+ * `firstPageRequest` and by what the accumulator starts as — there is no flag
+ * that a caller could set the wrong way (see `catalog/sync.ts`).
+ */
+export async function syncCatalog(
+  api: CategoriesApi,
+  stored: CategorySnapshot,
+  options: SyncCatalogOptions = {}
+): Promise<SyncCatalogResult> {
+  const wasFullSync = isEmptySnapshot(stored);
+  const budget = options.maxPages ?? MAX_SYNC_PAGES;
+
+  let request: CategoryListParams | undefined = {
+    ...firstPageRequest(stored),
+    ...(options.pageSize !== undefined ? { pageSize: options.pageSize } : {}),
+  };
+  // A full sync must not inherit rows the server is no longer listing, so it
+  // accumulates from empty. A delta folds into what is already known.
+  let accumulator: CategorySnapshot = wasFullSync
+    ? EMPTY_SNAPSHOT
+    : { ...stored };
+  let pages = 0;
+  let truncated = false;
+
+  while (request !== undefined) {
+    if (pages >= budget) {
+      truncated = true;
+      break;
+    }
+    const current: CategoryListParams = request;
+    const page = await api.list(current, {
+      ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    });
+    pages += 1;
+    accumulator = applyCategoryPage(accumulator, page, {
+      // The walk pinned its window with `max_revision`; the cursor may not
+      // claim to have read past it.
+      ...(current.maxRevision !== undefined
+        ? { cursorLimit: current.maxRevision }
+        : {}),
+    });
+    request = nextPageRequest(current, page);
+  }
+
+  if (truncated) {
+    // The rows gathered so far are still worth showing — a partial catalogue
+    // beats a blank menu — but the CURSOR must not advance, or the next sync
+    // asks for a delta on top of a catalogue that was never fully read and the
+    // gap becomes permanent. Rewinding it here means the worst case is one
+    // repeated full walk, not a silently incomplete tree forever.
+    return {
+      snapshot: { ...accumulator, cursor: stored.cursor },
+      wasFullSync,
+      pages,
+      truncated,
+    };
+  }
+
+  return { snapshot: accumulator, wasFullSync, pages, truncated };
+}