@stapel/categories-react 0.1.0

package/src/api/types.ts

@@ -0,0 +1,99 @@
+/**
+ * The wire shapes of `stapel-categories`, taken from the generated schema
+ * wherever the generated schema is TRUE, and hand-mirrored — with the reason
+ * written down — in the one place it is not.
+ *
+ * ── The one place the generated types are wrong: `config.type` ─────────────
+ *
+ * `FeatureCompact.config` is `{"allOf": [{"$ref": "FeatureConfig"}]}`, and
+ * `FeatureConfig` is a `oneOf` over ten config schemas carrying
+ * `discriminator: {propertyName: "type", mapping: {"null": ConvertibleUnitConfig}}`
+ * (stapel-categories `docs/schema.json`). That mapping is malformed — it has
+ * ONE entry, keyed `"null"`, instead of the ten type slugs — so
+ * openapi-typescript does two things to the generated surface:
+ *
+ *   1. it strips the discriminator from every use site, emitting
+ *      `Omit<components["schemas"]["FeatureConfig"], "type">`; and
+ *   2. it re-adds a SYNTHETIC discriminant on each member, so the generated
+ *      `IntConfig` declares `type: "IntConfig"` where the wire sends
+ *      `type: "int"` (see `generated/schema.ts`, "discriminator enum property
+ *      added by openapi-typescript").
+ *
+ * A pair that typed features off the generated union would therefore hand
+ * `@stapel/attributes-react` a `config` with no `type` at all, and any
+ * narrowing written against it would compare the value to a string the server
+ * never sends. So the features surface is typed through attributes-react's
+ * hand-mirrored `FeatureDef` / `FeatureConfig` (`attributes-react/src/types.ts`,
+ * itself checked against the engine's generated golden corpus) — the same
+ * shapes the value editors, the mirror and the formatter already switch on.
+ * Everything else here comes from the generated schema untouched.
+ *
+ * The upstream ask is recorded rather than worked around twice: emit the ten
+ * `type` slugs in `discriminator.mapping`, and both of the above disappear.
+ */
+import type { FeatureConfig, FeatureDef } from "@stapel/attributes-react";
+import type { components } from "./generated/schema.js";
+
+export type Schemas = components["schemas"];
+
+/**
+ * One category row, exactly as the list / children / carousel endpoints send
+ * it (`CategorySerializer`).
+ *
+ * Three fields decide what a storefront may do with it, and each is a trap if
+ * read casually:
+ *
+ * - `name` is a **translation key**, not a label, whenever `translatable` is
+ *   true — see `catalog/labels.ts`. Nothing on this endpoint resolves it.
+ * - `tn_ancestors_pks` / `tn_children_pks` are django-treenode's
+ *   COMMA-JOINED PK STRINGS (`treenode/utils.py: PKS_SEPARATOR = ","`), typed
+ *   `string` here because that is what arrives — `""` for a root. Parse them
+ *   with `parseTreenodePks`, never with `JSON.parse` and never by assuming an
+ *   array.
+ * - `deleted` is a TOMBSTONE flag, not an absence: a soft-deleted row is still
+ *   served (the list endpoint's `include_deleted` defaults to **true**), which
+ *   is exactly what makes the delta protocol work and exactly what shows a
+ *   deleted category in a menu if nobody filters.
+ */
+export type Category = Schemas["Category"];
+
+/** The `{pagination, revisions, results}` envelope of `RevisionPagination`. */
+export type CategoryPage = Schemas["PaginatedCategoryList"];
+
+/** `revisions` — the delta-sync bookkeeping half of the envelope. */
+export type CategoryRevisions = CategoryPage["revisions"];
+
+/** `GET /categories/revision/` — `{revision}`, the table's current maximum. */
+export type MaxRevision = Schemas["MaxRevision"];
+
+/**
+ * One resolved feature of a category (own + inherited, deduplicated by slug,
+ * in the category's own order first).
+ *
+ * Structurally `FeatureCompact`, but typed as attributes-react's `FeatureDef`
+ * for the discriminator reason at the top of this file. The two agree field
+ * for field; only `config` differs, and only in the direction of the truth.
+ *
+ * `config` arrives **verbatim**, NOT through `get_config_with_defaults()`
+ * (`FeatureCompactSerializer.get_config`) — an absent key means "the type's
+ * default", never "off". attributes-react owns those defaults; this pair does
+ * not re-state them.
+ */
+export type CategoryFeature = FeatureDef;
+
+export type { FeatureConfig };
+
+/** Query parameters of `GET /categories/api/v1/categories/`. */
+export interface CategoryListParams {
+  /** Exclusive lower bound: rows with `revision > minRevision`. Omit for a
+   * full sync. `0` is NOT the same as omitting it — it skips unsynced legacy
+   * rows whose revision is still 0. */
+  readonly minRevision?: number;
+  /** Inclusive upper bound. The pair pins it across a multi-page walk so a
+   * write landing mid-walk cannot shift page boundaries under the reader. */
+  readonly maxRevision?: number;
+  /** Default on the server is **true**. */
+  readonly includeDeleted?: boolean;
+  readonly page?: number;
+  readonly pageSize?: number;
+}

package/src/catalog/labels.ts

@@ -0,0 +1,129 @@
+/**
+ * NAMES ARE TRANSLATION KEYS. NOTHING ON THE WIRE RESOLVES THEM.
+ *
+ * This is the fact a storefront most needs stated plainly, so it is stated
+ * here and mirrored honestly rather than papered over.
+ *
+ * `stapel-categories` stores keys, never a catalogue: "This module stores
+ * translation **keys** (e.g. `category.electronics`); it never owns a
+ * translation catalog" (`translation.py`). Rendering runs through a
+ * `DISPLAY_TRANSLATOR` seam whose default is the identity function, and — this
+ * is the part that decides the client's behaviour — **no serializer calls it**.
+ * `translate()` has exactly two call sites in the module, `Category.__str__`
+ * and the admin's memoized feature label (`models.py`, `translation.py`); the
+ * REST layer serializes `name` straight off the model. So:
+ *
+ *   GET /categories/api/v1/categories/  →  { "name": "category.electronics" }
+ *
+ * even on a deployment that has configured a real translator. There is no
+ * `?lang=`, no `Accept-Language` handling, and no second endpoint that returns
+ * resolved labels: `GET /categories/translation-keys/` is `IsServiceRequest`
+ * and returns the KEYS with admin refs — it is the extraction feed for
+ * translators, the opposite direction.
+ *
+ * ── Which strings are keys ─────────────────────────────────────────────────
+ *
+ * The wire says so per row, and the pair reads the flag instead of guessing:
+ *
+ *  - a category's `name` is a key **iff `translatable` is true** (default
+ *    `true`; the field's own help text is "If True, category name is a
+ *    translation key").
+ *  - a feature's `name` is a key iff its `translate` mode is `"all"` or
+ *    `"title"`; `"none"` means the stored string IS the label.
+ *  - a feature's option labels and its `placeholder`/`prefix`/`postfix`
+ *    config strings are keys only under `translate: "all"`, and only while
+ *    `config.translatable_options` is not false
+ *    (`translation_keys.py: _extract_option_keys_as_list`).
+ *
+ * ── What this pair does about it ───────────────────────────────────────────
+ *
+ * It resolves through the HOST's i18n engine — the same `useT` every other key
+ * in the fleet goes through — and it does NOT ship a catalogue: category names
+ * are a deployment's content, not a library's chrome, so `category.electronics`
+ * belongs in the host's bundle beside its own copy, not in
+ * `@stapel/categories-react/i18n/ru`.
+ *
+ * And when the key does not resolve, the key is shown. That is deliberate.
+ * The alternative — falling back to the slug, or to a prettified
+ * `"category.electronics" → "Electronics"` — invents a label the operator
+ * never approved and hides a missing translation behind something that looks
+ * finished. A visible `category.electronics` gets fixed; a plausible-looking
+ * "Electronics" ships for a year in the wrong language.
+ */
+import type { Category, CategoryFeature } from "../api/types.js";
+
+/**
+ * How a display string reached the screen — the honest answer, carried instead
+ * of being flattened into a string.
+ *
+ * `"key"`      the value is a translation key; run it through i18n.
+ * `"literal"`  the row opted out of translation; the value is the label.
+ */
+export type CategoryLabelKind = "key" | "literal";
+
+export interface CategoryLabel {
+  readonly kind: CategoryLabelKind;
+  /** The key to translate, or the literal to print. */
+  readonly value: string;
+}
+
+/**
+ * A category's display string and what to do with it.
+ *
+ * `translatable` is optional in the schema and defaults to `true` on the model,
+ * so an absent flag means KEY. Guessing "literal" for an absent flag is the
+ * wrong-way-round failure: it prints `category.electronics` at a visitor on a
+ * fully translated deployment.
+ */
+export function categoryLabel(category: Category): CategoryLabel {
+  return {
+    kind: category.translatable === false ? "literal" : "key",
+    value: category.name,
+  };
+}
+
+/**
+ * A feature's display string and what to do with it.
+ *
+ * `translate: "none"` is the only mode that makes the name a literal;
+ * `"title"` and `"all"` both translate it, and the difference between them is
+ * about the feature's OPTIONS, which are attributes-react's business, not
+ * this function's. An absent mode means `"all"` (the model default).
+ */
+export function featureLabel(feature: CategoryFeature): CategoryLabel {
+  return {
+    kind: feature.translate === "none" ? "literal" : "key",
+    // `name` falls back to `slug` server-side (`FeatureDef.__post_init__`);
+    // mirror that rather than rendering an empty label.
+    value: feature.name ?? feature.slug,
+  };
+}
+
+/**
+ * Are this feature's option labels translation keys?
+ *
+ * Only under `translate: "all"`, and only while the config has not opted out
+ * with `translatable_options: false`. A consumer that labels facet values (the
+ * search pair does) needs both halves of that: translating an opted-out option
+ * shows the raw key, and NOT translating an opted-in one shows the raw key
+ * too — same symptom, opposite fix.
+ */
+export function featureOptionsAreKeys(feature: CategoryFeature): boolean {
+  if ((feature.translate ?? "all") !== "all") return false;
+  const config = feature.config;
+  return config?.["translatable_options"] !== false;
+}
+
+/**
+ * Resolve a label with a translator, without pretending about misses.
+ *
+ * `translate` is the host's `t` (core's `useT()`); i18n engines return the key
+ * itself for a miss, which is exactly the behaviour this pair wants and
+ * documents above.
+ */
+export function renderCategoryLabel(
+  label: CategoryLabel,
+  translate: (key: string) => string
+): string {
+  return label.kind === "key" ? translate(label.value) : label.value;
+}

package/src/catalog/pks.ts

@@ -0,0 +1,35 @@
+/**
+ * django-treenode's ancestry columns, parsed.
+ *
+ * `tn_ancestors_pks`, `tn_children_pks`, `tn_descendants_pks` and
+ * `tn_siblings_pks` are `TextField`s holding a COMMA-JOINED list of primary
+ * keys (`treenode/utils.py`: `PKS_SEPARATOR = ","`, `join_pks`, `split_pks`),
+ * and drf-spectacular therefore types them `string` in the schema. The spec
+ * (§4.3) describes them as if they were arrays; on the wire they are `"1,7,12"`
+ * and `""`.
+ *
+ * Root-first ordering is a property of how treenode writes the column
+ * (`update_tree` walks down from the root), and the whole breadcrumb depends
+ * on it — so it is asserted in `test/tree.test.ts` against a real fixture
+ * rather than assumed here.
+ */
+
+/**
+ * Parse a treenode pks column into numeric ids, root-first.
+ *
+ * Empty string → `[]` (a root has no ancestors; a leaf has no children).
+ * Non-numeric fragments are dropped rather than turned into `NaN`: a `NaN`
+ * silently fails every `===` against a real id, which reads as "the parent is
+ * missing" — the same wrong answer, two hours later.
+ */
+export function parseTreenodePks(column: string | null | undefined): readonly number[] {
+  if (column === null || column === undefined || column === "") return [];
+  const out: number[] = [];
+  for (const part of column.split(",")) {
+    const trimmed = part.trim();
+    if (trimmed === "") continue;
+    const value = Number(trimmed);
+    if (Number.isInteger(value)) out.push(value);
+  }
+  return out;
+}

package/src/catalog/sync.ts

@@ -0,0 +1,169 @@
+/**
+ * The delta protocol, as pure state transitions.
+ *
+ * `stapel-categories` documents the flow on the viewset itself (`views.py`,
+ * `CategoryViewSet` docstring): full `GET /categories/` → store
+ * `revisions.global_max` → later `GET /categories/?min_revision=<stored>` →
+ * drop the rows that come back `deleted: true`. The spec's verdict (§4.3) is
+ * that the result lives in `createRepository()` rather than being refetched
+ * per page, because without it every storefront page pulls the whole
+ * catalogue.
+ *
+ * Three things the documented flow does not say, all of which change the code:
+ *
+ * 1. **`revisions.deleted_ids` is the authoritative tombstone channel**, not
+ *    the `deleted: true` rows. The rows are PAGINATED — a tombstone can land
+ *    on page 3 of a walk that stopped at page 2 — while `deleted_ids` is
+ *    computed unpaginated over `deleted=True AND revision > min_revision`
+ *    (`stapel_core/django/api/revision.py`). It is also a snapshot of the
+ *    CURRENT flag, so a category deleted and then restored is simply absent
+ *    from it. Both channels are applied; the list is the one that is complete.
+ *    On a FULL sync `deleted_ids` is `[]` by construction (the server only
+ *    computes it when `min_revision` was sent), which is why dropping
+ *    `deleted: true` rows still matters.
+ *
+ * 2. **A multi-page walk must pin its upper bound.** Pages are ordered by
+ *    `revision` and filtered at request time; a write landing between page 1
+ *    and page 2 shifts every subsequent page boundary, and the walk silently
+ *    skips a row. `max_revision` exists for exactly this and the documented
+ *    flow never mentions it: `nextPageRequest` pins the window to the
+ *    `global_max` observed on the FIRST page and stores that as the new
+ *    cursor. Anything written during the walk is picked up by the next delta.
+ *
+ * 3. **`revisions.global_max` is a property of the TABLE, not of the page** —
+ *    it is `Max(revision)` over the whole model, so it is already the right
+ *    cursor even when the page came back empty.
+ */
+import type { Category, CategoryPage } from "../api/types.js";
+import type { CategoryListParams } from "../api/types.js";
+
+/** The persisted catalogue: rows plus the cursor they are current as of. */
+export interface CategorySnapshot {
+  /** Storage-format marker. A snapshot written by an older shape is discarded
+   * rather than migrated — it is a cache, and a full resync costs one request. */
+  readonly version: 1;
+  /** `revisions.global_max` as of the last completed sync. */
+  readonly cursor: number;
+  /** Live rows, tombstones already applied. Order is not meaningful. */
+  readonly rows: readonly Category[];
+}
+
+/** An empty snapshot — the state before the first sync. */
+export const EMPTY_SNAPSHOT: CategorySnapshot = {
+  version: 1,
+  cursor: 0,
+  rows: [],
+};
+
+/** A snapshot with no rows has never synced, whatever its cursor says. */
+export function isEmptySnapshot(snapshot: CategorySnapshot): boolean {
+  return snapshot.rows.length === 0;
+}
+
+/**
+ * Accept a value read back from persistence, or reject it.
+ *
+ * A repository read can hand back anything: a snapshot written by a previous
+ * version of this pair, a half-written value, `undefined` after a cleared
+ * origin. Every one of those must degrade to "no snapshot" — a cache that
+ * throws on read is worse than no cache.
+ */
+export function parseSnapshot(value: unknown): CategorySnapshot | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const candidate = value as Partial<CategorySnapshot>;
+  if (candidate.version !== 1) return undefined;
+  if (typeof candidate.cursor !== "number" || !Number.isFinite(candidate.cursor)) {
+    return undefined;
+  }
+  if (!Array.isArray(candidate.rows)) return undefined;
+  for (const row of candidate.rows) {
+    if (typeof row !== "object" || row === null) return undefined;
+    if (typeof (row as Category).id !== "number") return undefined;
+  }
+  return {
+    version: 1,
+    cursor: candidate.cursor,
+    rows: candidate.rows as readonly Category[],
+  };
+}
+
+/**
+ * The request that starts a sync from `snapshot`.
+ *
+ * A cold start asks for everything with `include_deleted: false` — nothing is
+ * cached, so a tombstone has nothing to evict and the payload is smaller. A
+ * warm start asks for the delta with `include_deleted: true`, because there
+ * the tombstones are the point.
+ */
+export function firstPageRequest(snapshot: CategorySnapshot): CategoryListParams {
+  if (isEmptySnapshot(snapshot)) {
+    return { includeDeleted: false, page: 1 };
+  }
+  return { minRevision: snapshot.cursor, includeDeleted: true, page: 1 };
+}
+
+/**
+ * The request for the next page of an in-flight walk, or `undefined` when the
+ * walk is done.
+ *
+ * `maxRevision` pins the window to what the first page reported, so the walk
+ * reads one consistent snapshot of the table instead of a moving one.
+ */
+export function nextPageRequest(
+  previous: CategoryListParams,
+  page: CategoryPage
+): CategoryListParams | undefined {
+  if (!page.pagination.has_next) return undefined;
+  return {
+    ...previous,
+    page: page.pagination.page + 1,
+    maxRevision: previous.maxRevision ?? page.revisions.global_max,
+  };
+}
+
+/**
+ * Fold one page into an accumulator.
+ *
+ * There is one merge rule, and the FULL/DELTA distinction lives in what the
+ * caller starts from, not in a flag here: a delta folds into the stored
+ * snapshot, a full sync folds into {@link EMPTY_SNAPSHOT}. That is the whole
+ * difference — a row the server no longer lists is gone from a full listing
+ * precisely because it was never folded in. Expressing it as a flag on the
+ * merge invites the two silent failures instead: a delta treated as full
+ * empties the catalogue, a full treated as delta resurrects rows deleted while
+ * the client was away.
+ *
+ * The new snapshot is not published until the walk COMPLETES (see
+ * `model/catalogSync.ts`), so a walk that fails halfway leaves the previous
+ * catalogue on screen rather than a truncated one.
+ *
+ * The cursor only ever moves FORWARD, and never past `cursorLimit`:
+ * `global_max` is the table's live maximum, which can already exceed the
+ * window a walk pinned with `max_revision`. Taking it verbatim would record
+ * having read rows the walk never asked for.
+ */
+export function applyCategoryPage(
+  accumulator: CategorySnapshot,
+  page: CategoryPage,
+  options: { readonly cursorLimit?: number } = {}
+): CategorySnapshot {
+  const byId = new Map<number, Category>();
+  for (const row of accumulator.rows) byId.set(row.id, row);
+
+  for (const row of page.results) {
+    if (row.deleted === true) byId.delete(row.id);
+    else byId.set(row.id, row);
+  }
+  for (const id of page.revisions.deleted_ids) byId.delete(id);
+
+  const observed =
+    options.cursorLimit !== undefined
+      ? Math.min(page.revisions.global_max, options.cursorLimit)
+      : page.revisions.global_max;
+
+  return {
+    version: 1,
+    cursor: Math.max(accumulator.cursor, observed),
+    rows: [...byId.values()],
+  };
+}

package/src/catalog/tree.ts

@@ -0,0 +1,242 @@
+/**
+ * The tree the server does not build.
+ *
+ * `stapel-categories` has no tree endpoint. `GET /categories/` returns FLAT
+ * rows ordered by `revision`, each carrying `tn_parent`, `tn_priority` and the
+ * treenode ancestry columns — the client assembles the hierarchy (spec §4.3).
+ * Everything in this file is pure: no React, no fetch, no storage, so the same
+ * functions serve a browser, an SSR render and a test.
+ *
+ * ── Three server facts this module encodes, each a bug if forgotten ────────
+ *
+ * 1. **`deleted` rows are served.** `include_deleted` defaults to `true`, and
+ *    the delta protocol NEEDS it that way. A tree built without filtering
+ *    shows soft-deleted categories in a menu.
+ * 2. **`active: false` rows are served too**, and nothing on the list endpoint
+ *    filters them — only `carousel` does. "Active" is the storefront's
+ *    visibility switch, so the public tree drops them by default and the
+ *    option to keep them is explicit.
+ * 3. **Order is `tn_priority` DESCENDING**, which is what both `children` and
+ *    `carousel` do server-side (`views.py: order_by("-tn_priority")`). Ties
+ *    are broken by `id` so a rebuild is deterministic — priority defaults to
+ *    `0`, so a catalogue that never set it is ALL ties, and an unstable order
+ *    there means the menu reshuffles between renders.
+ */
+import type { Category } from "../api/types.js";
+import { parseTreenodePks } from "./pks.js";
+
+/** One node of the assembled tree. */
+export interface CategoryNode {
+  readonly category: Category;
+  readonly id: number;
+  readonly depth: number;
+  readonly children: readonly CategoryNode[];
+}
+
+/**
+ * A built catalogue: the rows, plus the lookups a screen actually asks for.
+ *
+ * Built once per snapshot and shared, because every one of these questions is
+ * asked on every render of every category page.
+ */
+export interface CategoryIndex {
+  /** Roots, in display order. */
+  readonly roots: readonly CategoryNode[];
+  /** Every node by id, including ones filtered out of `roots`' subtrees? No —
+   * only the nodes that survived the filter. What is not in the tree is not
+   * addressable. */
+  readonly byId: ReadonlyMap<number, CategoryNode>;
+  /** Slug → node. See `resolveCategorySlug` for the collision rule. */
+  readonly bySlug: ReadonlyMap<string, CategoryNode>;
+  /** How many rows the source snapshot had before filtering. */
+  readonly totalRows: number;
+}
+
+export interface BuildCategoryTreeOptions {
+  /** Keep `deleted: true` rows. Default `false`. */
+  readonly includeDeleted?: boolean;
+  /** Keep `active: false` rows. Default `false` — the storefront's answer.
+   * A catalogue admin passes `true`. */
+  readonly includeInactive?: boolean;
+}
+
+function displayOrder(a: Category, b: Category): number {
+  const pa = a.tn_priority ?? 0;
+  const pb = b.tn_priority ?? 0;
+  if (pa !== pb) return pb - pa;
+  return a.id - b.id;
+}
+
+function keeps(row: Category, options: BuildCategoryTreeOptions): boolean {
+  if (row.deleted === true && options.includeDeleted !== true) return false;
+  // `active` is optional in the schema and defaults to true on the model, so
+  // the test is "not explicitly false" — an absent field is an active
+  // category, never a hidden one.
+  if (row.active === false && options.includeInactive !== true) return false;
+  return true;
+}
+
+/**
+ * Assemble flat rows into a tree.
+ *
+ * A row whose `tn_parent` is not in the surviving set becomes a ROOT rather
+ * than disappearing. That is not tidiness — it is the only safe answer to the
+ * two ways it legitimately happens: a delta page that brought a child before
+ * its parent, and a parent filtered out by `active: false` while the child was
+ * left active by a catalogue editor. Dropping the subtree would delete a live
+ * branch of the catalogue from the menu and give nobody a reason.
+ */
+export function buildCategoryTree(
+  rows: Iterable<Category>,
+  options: BuildCategoryTreeOptions = {}
+): CategoryIndex {
+  const all = [...rows];
+  const kept = all.filter((row) => keeps(row, options)).sort(displayOrder);
+
+  const childrenOf = new Map<number, Category[]>();
+  const present = new Set<number>(kept.map((row) => row.id));
+  const roots: Category[] = [];
+
+  for (const row of kept) {
+    const parent = row.tn_parent;
+    if (parent === null || parent === undefined || !present.has(parent)) {
+      roots.push(row);
+      continue;
+    }
+    const bucket = childrenOf.get(parent);
+    if (bucket === undefined) childrenOf.set(parent, [row]);
+    else bucket.push(row);
+  }
+
+  const byId = new Map<number, CategoryNode>();
+  const bySlug = new Map<string, CategoryNode>();
+
+  // Iterative build (not recursion): a catalogue is authored data, and a cycle
+  // introduced by a bad `tn_parent` would blow the stack instead of rendering.
+  // `seen` makes a cycle a finite, visible truncation.
+  function build(row: Category, depth: number, seen: ReadonlySet<number>): CategoryNode {
+    const kids = childrenOf.get(row.id) ?? [];
+    const nextSeen = new Set(seen).add(row.id);
+    const node: CategoryNode = {
+      category: row,
+      id: row.id,
+      depth,
+      children: kids
+        .filter((kid) => !nextSeen.has(kid.id))
+        .map((kid) => build(kid, depth + 1, nextSeen)),
+    };
+    byId.set(row.id, node);
+    if (row.slug !== "" && !bySlug.has(row.slug)) bySlug.set(row.slug, node);
+    return node;
+  }
+
+  const builtRoots = roots.map((row) => build(row, 0, new Set<number>()));
+
+  // A row that no root can reach is a row inside a PARENT CYCLE (`a.parent =
+  // b, b.parent = a` — authored data, so possible). The recursion above
+  // refuses to follow the cycle, which keeps the stack safe but would drop
+  // those rows entirely: they would vanish from the menu with no error
+  // anywhere. Promote whatever is left to roots instead, so a broken branch
+  // is VISIBLE and fixable rather than absent.
+  for (const row of kept) {
+    if (byId.has(row.id)) continue;
+    builtRoots.push(build(row, 0, new Set<number>()));
+  }
+
+  return { roots: builtRoots, byId, bySlug, totalRows: all.length };
+}
+
+/**
+ * Resolve a URL slug to a category — the lookup the SERVER does not offer.
+ *
+ * `CategoryViewSet` never overrides `lookup_field` and the list endpoint has
+ * no slug filter, so `GET /categories/<slug>/` is a 404 and `?slug=` is
+ * ignored. The storefront's `/c/:slug` therefore resolves against the synced
+ * tree (spec §4.3), which is one more reason the catalogue is cached rather
+ * than fetched per page.
+ *
+ * `Category.slug` is `unique=True` at the model level, so a collision cannot
+ * come from the database. It CAN come from the client's own snapshot — a
+ * delta that renamed a slug from A to B arrives as one row, and a stale row
+ * still holding B has not been evicted yet. First-in-display-order wins,
+ * deterministically, and the loser is reachable by id.
+ */
+export function resolveCategorySlug(
+  index: CategoryIndex,
+  slug: string
+): CategoryNode | undefined {
+  return index.bySlug.get(slug);
+}
+
+/**
+ * The path from the root down to `id`, inclusive — the breadcrumb.
+ *
+ * Walks `tn_parent` through the built index rather than trusting
+ * `tn_ancestors_pks`, because the index is what the screen is showing: if a
+ * filter removed an ancestor, the crumb must not name a category the visitor
+ * cannot open. `categoryAncestorIds` is the other answer — the server's — and
+ * the two are compared in `test/tree.test.ts` precisely so a divergence is a
+ * red test rather than a subtly wrong crumb.
+ *
+ * An unknown id gives `[]`, not a partial path: half a breadcrumb reads as a
+ * top-level category.
+ */
+export function categoryBreadcrumbs(
+  index: CategoryIndex,
+  id: number | null | undefined
+): readonly CategoryNode[] {
+  if (id === null || id === undefined) return [];
+  const start = index.byId.get(id);
+  if (start === undefined) return [];
+
+  const path: CategoryNode[] = [start];
+  const seen = new Set<number>([start.id]);
+  let cursor = start.category.tn_parent;
+  while (cursor !== null && cursor !== undefined && !seen.has(cursor)) {
+    const parent = index.byId.get(cursor);
+    if (parent === undefined) break;
+    path.push(parent);
+    seen.add(parent.id);
+    cursor = parent.category.tn_parent;
+  }
+  return path.reverse();
+}
+
+/**
+ * The server's own answer to "who are this row's ancestors", root-first, from
+ * `tn_ancestors_pks`.
+ *
+ * Useful without a built index (a single category fetched on its own), and the
+ * cross-check for {@link categoryBreadcrumbs}.
+ */
+export function categoryAncestorIds(category: Category): readonly number[] {
+  return parseTreenodePks(category.tn_ancestors_pks);
+}
+
+/**
+ * The server's own answer to "who are this row's children", from
+ * `tn_children_pks`.
+ *
+ * This is the FULL child set, including soft-deleted and inactive rows — the
+ * column is maintained by treenode, which knows nothing about either flag. Use
+ * it to detect "this category has sub-categories at all"; use the built node's
+ * `children` to render them.
+ */
+export function categoryChildIds(category: Category): readonly number[] {
+  return parseTreenodePks(category.tn_children_pks);
+}
+
+/** Depth-first walk of a subtree (or the whole forest), in display order. */
+export function flattenCategoryNodes(
+  nodes: readonly CategoryNode[]
+): readonly CategoryNode[] {
+  const out: CategoryNode[] = [];
+  const walk = (list: readonly CategoryNode[]): void => {
+    for (const node of list) {
+      out.push(node);
+      walk(node.children);
+    }
+  };
+  walk(nodes);
+  return out;
+}