@veluai/velu 0.2.25 → 0.2.27

package/src/navigation.js

@@ -1,459 +1,459 @@
-import GithubSlugger from 'github-slugger';
-import ISO6391 from 'iso-639-1';
-
-/**
- * navigation.js — the PURE, framework-agnostic navigation model. No
- * `fs`, no React, no Node-only imports: this file is imported by BOTH
- * the Node-side Vite plugin (to normalize + walk) AND the browser
- * runtime (to resolve the active page → sidebar/header). Sharing the
- * exact same code on both sides is what keeps SSR and client render
- * in lockstep (no hydration drift).
- *
- * Model: `velu.json`'s `navigation` is normalized into a canonical
- * tree whose containment order is FIXED, regardless of how the author
- * nested things, and identical to the URL-prefix order:
- *
- *   AXIS_ORDER:  product → version → language → tabs → groups → pages
- *   URL:         /<product?>/<version?>/<language?>/<page-path>
- *
- * Default axis values contribute no URL segment. Dropdowns are out of
- * scope by design.
- */
-
-export const AXIS_ORDER = ['product', 'version', 'language'];
-
-// `language` in velu.json is stored as an ISO 639-1 code (e.g. "en");
-// the switcher shows the code + its native name. iso-639-1 covers the
-// full set of codes; unknown/invalid codes fall back to the code.
-function languageName(code) {
-  const c = String(code).toLowerCase();
-  return ISO6391.getNativeName(c) || code;
-}
-
-/** Fresh slugger per call → pure (no cross-call dedup state). */
-export function slugify(s) {
-  return new GithubSlugger().slug(String(s ?? ''));
-}
-
-/**
- * Map a content page path to its in-context URL leaf:
- *   "index"        → "/"
- *   "sync/index"   → "/sync"
- *   "sync/github"  → "/sync/github"
- * Defined ONCE so collect + resolve never disagree.
- */
-export function urlForPath(pagePath) {
-  const segs = String(pagePath)
-    .replace(/^\/+|\/+$/g, '')
-    .split('/')
-    .filter(Boolean);
-  if (segs[segs.length - 1] === 'index') segs.pop();
-  return '/' + segs.join('/');
-}
-
-/** Normalize a request/location path: drop query+hash, collapse a
- *  trailing slash (except root), ensure a leading slash. Used on both
- *  sides so the active-page lookup matches identically. */
-export function normalizeUrl(url) {
-  let u = String(url).split('#')[0].split('?')[0];
-  // Decode percent-encoding so non-ASCII slugs (e.g. an "Español"
-  // language → "/español") match whether the browser sends the path
-  // encoded ("/espa%C3%B1ol") or decoded.
-  try {
-    u = decodeURI(u);
-  } catch {
-    /* malformed escape — leave as-is */
-  }
-  if (!u.startsWith('/')) u = '/' + u;
-  if (u.length > 1) u = u.replace(/\/+$/, '');
-  return u || '/';
-}
-
-const titleCase = (s) =>
-  String(s)
-    .replace(/[-_]+/g, ' ')
-    .replace(/\b\w/g, (c) => c.toUpperCase());
-
-const lastSeg = (url) => {
-  const segs = String(url).split('/').filter(Boolean);
-  return segs[segs.length - 1] ?? '';
-};
-
-// ── Normalization ──────────────────────────────────────────────────
-
-/**
- * Build the canonical tree from a raw `navigation` object. At each
- * level we honor a fixed precedence (products > versions > languages >
- * tabs > leaf), so canonically-authored configs (axes nested in
- * AXIS_ORDER, or only one axis) collapse to the intended tree. A leaf
- * level mixes anchors + groups + pages as siblings.
- */
-export function normalizeNavigation(raw) {
-  const root = { kind: 'root', children: normalizeChildren(raw ?? {}) };
-  applyDefaults(root.children);
-  return root;
-}
-
-function normalizeChildren(obj) {
-  // Anchors are pinned links that may sit alongside ANY level (incl.
-  // next to tabs as "global" anchors), so collect them regardless of
-  // which grouping branch this container uses.
-  const anchors = Array.isArray(obj.anchors)
-    ? obj.anchors.map(normalizeAnchor)
-    : [];
-  if (Array.isArray(obj.products))
-    return [...anchors, ...obj.products.map(normalizeProduct)];
-  if (Array.isArray(obj.versions))
-    return [...anchors, ...obj.versions.map(normalizeVersion)];
-  if (Array.isArray(obj.languages))
-    return [...anchors, ...obj.languages.map(normalizeLanguage)];
-  if (Array.isArray(obj.tabs))
-    return [...anchors, ...obj.tabs.map(normalizeTab)];
-  const out = [...anchors];
-  if (Array.isArray(obj.groups)) out.push(...obj.groups.map(normalizeGroup));
-  if (Array.isArray(obj.pages)) out.push(...obj.pages.map(normalizePageEntry));
-  return out;
-}
-
-function normalizeProduct(p) {
-  return {
-    kind: 'product',
-    label: p.name ?? p.product,
-    slug: slugify(p.product),
-    icon: p.icon,
-    color: p.color,
-    default: Boolean(p.default),
-    children: normalizeChildren(p),
-  };
-}
-
-function normalizeVersion(v) {
-  return {
-    kind: 'version',
-    label: v.version,
-    slug: slugify(v.version),
-    default: Boolean(v.default),
-    children: normalizeChildren(v),
-  };
-}
-
-function normalizeLanguage(l) {
-  const code = String(l.language);
-  return {
-    kind: 'language',
-    code,
-    label: languageName(code),
-    slug: slugify(code),
-    default: Boolean(l.default),
-    children: normalizeChildren(l),
-  };
-}
-
-function normalizeTab(t) {
-  return {
-    kind: 'tab',
-    label: t.tab,
-    slug: slugify(t.tab),
-    icon: t.icon,
-    href: t.href,
-    children: normalizeChildren(t),
-  };
-}
-
-function normalizeAnchor(a) {
-  return {
-    kind: 'anchor',
-    label: a.anchor,
-    icon: a.icon,
-    href: a.href,
-    color: a.color,
-  };
-}
-
-function normalizeGroup(g) {
-  const pages = (g.pages ?? []).map(normalizePageEntry);
-  // A group `root` is its landing page. velu-ui's Sidebar section
-  // heading isn't a link, so surface root as the group's FIRST item
-  // (its label comes from the root page's frontmatter, like any page).
-  if (g.root) pages.unshift({ kind: 'page', pagePath: g.root });
-  return {
-    kind: 'group',
-    label: g.group,
-    icon: g.icon,
-    expanded: Boolean(g.expanded),
-    root: g.root,
-    children: pages,
-  };
-}
-
-/** A `pages[]` entry is a string (page path), a generated OpenAPI page
- *  ({ apiPage, label, method }), or a nested group. */
-function normalizePageEntry(entry) {
-  if (typeof entry === 'string') return { kind: 'page', pagePath: entry };
-  if (entry && entry.apiPage) {
-    return { kind: 'page', pagePath: entry.apiPage, label: entry.label, method: entry.method, api: true };
-  }
-  return normalizeGroup(entry);
-}
-
-/**
- * Ensure each axis sibling-set has exactly one default: if the author
- * marked none, the first declared becomes default (so an axis never
- * prefixes every URL). Recurses through the whole tree.
- */
-function applyDefaults(children) {
-  for (const kind of AXIS_ORDER) {
-    const sibs = children.filter((c) => c.kind === kind);
-    if (sibs.length && !sibs.some((s) => s.default)) sibs[0].default = true;
-  }
-  for (const c of children) if (c.children) applyDefaults(c.children);
-}
-
-// ── Walking ────────────────────────────────────────────────────────
-
-/**
- * Walk the tree to every page leaf, computing its full URL (with the
- * accumulated NON-default axis prefix) and its ancestor chain. Pure —
- * the Node side adds fs existence on top (see navigation-node.js); the
- * runtime uses it directly for resolution. Returns:
- *   [{ pagePath, url, ctx, ancestors:Node[] }]
- */
-export function walkPages(tree) {
-  const out = [];
-  const visit = (node, ctx, ancestors) => {
-    if (node.kind === 'page') {
-      out.push({
-        pagePath: node.pagePath,
-        url: urlInCtx(node.pagePath, ctx),
-        ctx: { ...ctx },
-        ancestors,
-        node,
-      });
-      return;
-    }
-    let next = ctx;
-    if (node.kind === 'product')
-      next = { ...ctx, product: node.default ? null : node.slug };
-    else if (node.kind === 'version')
-      next = { ...ctx, version: node.default ? null : node.slug };
-    else if (node.kind === 'language')
-      next = { ...ctx, language: node.default ? null : node.slug };
-    const nextAncestors =
-      node.kind === 'root' ? ancestors : [...ancestors, node];
-    for (const c of node.children ?? []) visit(c, next, nextAncestors);
-  };
-  visit(tree, { product: null, version: null, language: null }, []);
-  return out;
-}
-
-/** Compose a page URL from a page path + an axis context. */
-function urlInCtx(pagePath, ctx) {
-  const prefix = [ctx.product, ctx.version, ctx.language].filter(Boolean);
-  const leaf = urlForPath(pagePath).split('/').filter(Boolean);
-  return '/' + [...prefix, ...leaf].join('/');
-}
-
-// ── Resolution (runtime) ───────────────────────────────────────────
-
-/**
- * Resolve the active page for a URL into everything the chrome needs.
- * `pagesMap` is url → { frontmatter, ... } (from the virtual module),
- * used to source sidebar labels from page frontmatter titles.
- *
- * Returns null when no page matches (404). Otherwise:
- *   {
- *     url, frontmatter,
- *     sidebarSections, anchors,
- *     tabs, activeTab,
- *     products, activeProduct,
- *     versions, activeVersion,
- *     languages, activeLanguage,
- *     breadcrumb,
- *   }
- */
-export function resolve(url, tree, pagesMap = {}) {
-  const norm = normalizeUrl(url);
-  const entries = walkPages(tree);
-  const match = entries.find((e) => e.url === norm);
-  if (!match) return null;
-
-  const { ctx, ancestors } = match;
-  const ancOf = (kind) => ancestors.filter((a) => a.kind === kind).pop();
-  const tabAnc = ancOf('tab');
-  const axisAnc = ancestors
-    .filter((a) => AXIS_ORDER.includes(a.kind))
-    .pop();
-  const productAnc = ancOf('product');
-  const versionAnc = ancOf('version');
-  const languageAnc = ancOf('language');
-
-  // Sidebar/anchor container = nearest tab, else nearest axis node,
-  // else the root. Its group/page children form the sidebar; its
-  // anchor children form the context-zone anchors.
-  const container = tabAnc || axisAnc || tree;
-  const containerKids = container.children ?? [];
-  const sidebarSections = buildSidebar(
-    containerKids.filter((n) => n.kind === 'group' || n.kind === 'page'),
-    pagesMap,
-    ctx,
-  );
-  // Whether THIS tab's sidebar holds any API page. The chrome uses it to
-  // pick ONE sidebar style for the whole tab (flat API list vs nested docs
-  // list) rather than flipping per selected page — so a tab that mixes an
-  // intro page with generated API operations reads as a single, stable
-  // sidebar. Derived from the sidebar items (the API ones carry `method`).
-  const sidebarHasApi = sidebarSectionsHaveApi(sidebarSections);
-  // Anchors are gathered from every container along the active path —
-  // root (global), the active product/version/language, and the active
-  // tab — so global anchors show on every page while tab-scoped ones
-  // show only within their tab.
-  const anchors = [tree, productAnc, versionAnc, languageAnc, tabAnc]
-    .filter(Boolean)
-    .flatMap((c) => (c.children ?? []).filter((n) => n.kind === 'anchor'))
-    .map((a) => ({ label: a.label, icon: a.icon, href: a.href, external: true }));
-
-  // Tabs live directly under the innermost axis node (or root).
-  const tabParent = axisAnc || tree;
-  const tabNodes = (tabParent.children ?? []).filter((n) => n.kind === 'tab');
-  const firstUrlUnder = (node) => {
-    const e = entries.find((en) => en.ancestors.includes(node));
-    return e ? e.url : node.href ?? '#';
-  };
-  const tabs = tabNodes.map((t) => ({
-    label: t.label,
-    icon: t.icon,
-    href: firstUrlUnder(t),
-  }));
-  const activeTab = tabAnc ? firstUrlUnder(tabAnc) : undefined;
-
-  // Switchers: sibling axis options + the URL to land on when chosen
-  // (first page of that option's subtree). Each option set is scoped
-  // to the active outer axis (versions within the active product, etc).
-  const axisOptions = (kind, parent) =>
-    (parent?.children ?? tree.children ?? [])
-      .filter((n) => n.kind === kind)
-      .map((n) => ({
-        label: n.label,
-        code: n.code, // language code (undefined for product/version)
-        slug: n.slug,
-        icon: n.icon,
-        default: n.default,
-        href: firstUrlUnder(n),
-        active: n === ancOf(kind),
-      }));
-  const products = axisOptions('product', tree);
-  const versions = axisOptions('version', productAnc ?? tree);
-  const languages = axisOptions('language', versionAnc ?? productAnc ?? tree);
-
-  // Breadcrumb: tab → group ancestors → page title.
-  const groupAncestors = ancestors.filter((a) => a.kind === 'group');
-  const pageTitle = pagesMap[norm]?.frontmatter?.title ?? titleCase(lastSeg(norm));
-  const breadcrumb = [
-    ...(tabAnc ? [{ label: tabAnc.label }] : []),
-    ...groupAncestors.map((g) => ({ label: g.label })),
-    { label: pageTitle },
-  ];
-
-  // Prev / next = neighbors in the sidebar's reading order (the
-  // flattened page sequence of the active section).
-  const ordered = flattenSidebar(sidebarSections);
-  const idx = ordered.findIndex((p) => p.href === norm);
-  const prev = idx > 0 ? ordered[idx - 1] : undefined;
-  const next = idx >= 0 && idx < ordered.length - 1 ? ordered[idx + 1] : undefined;
-
-  return {
-    url: norm,
-    frontmatter: pagesMap[norm]?.frontmatter ?? {},
-    sidebarSections,
-    sidebarHasApi,
-    anchors,
-    tabs,
-    activeTab,
-    products,
-    activeProduct: productAnc?.label,
-    versions,
-    activeVersion: versionAnc?.label,
-    languages,
-    activeLanguage: languageAnc?.label,
-    activeLanguageCode: languageAnc?.code,
-    breadcrumb,
-    prev,
-    next,
-  };
-}
-
-/** True when any item in the sidebar (at any nesting depth) is an API page —
- *  i.e. carries an HTTP `method`. Lets the chrome render the whole tab with
- *  the API sidebar style instead of switching per selected page. */
-function sidebarSectionsHaveApi(sections) {
-  const walk = (items) =>
-    (items ?? []).some((it) => it.method || (it.items && walk(it.items)));
-  return sections.some((s) => walk(s.items));
-}
-
-/** Flatten sidebar sections (incl. nested groups) to an ordered list of
- *  page links {label, href} — the page reading order for prev/next. */
-function flattenSidebar(sections) {
-  const out = [];
-  const walk = (items) => {
-    for (const it of items) {
-      if (it.items) walk(it.items);
-      else out.push({ label: it.label, href: it.href });
-    }
-  };
-  for (const s of sections) walk(s.items);
-  return out;
-}
-
-/**
- * Map a list of (group|page) nodes to the velu-ui Sidebar `sections`
- * shape: [{ title, icon, items:[{ label, href, icon, items }] }].
- * Loose top-level pages (not inside a group) collect into a leading
- * untitled section. Page labels come from frontmatter title, falling
- * back to a title-cased URL segment (the SAME fallback on both render
- * sides). Sidebar derives open/active state from `activeHref`, so we
- * don't compute it here.
- */
-export function buildSidebar(nodes, pagesMap, ctx) {
-  const sections = [];
-  let loose = null;
-  for (const n of nodes) {
-    if (n.kind === 'group') {
-      sections.push({
-        title: n.label,
-        icon: n.icon,
-        items: itemsFor(n.children, pagesMap, ctx),
-      });
-    } else if (n.kind === 'page') {
-      if (!loose) {
-        loose = { title: '', items: [] };
-        sections.push(loose);
-      }
-      loose.items.push(itemFor(n, pagesMap, ctx));
-    }
-  }
-  return sections;
-}
-
-function itemsFor(nodes, pagesMap, ctx) {
-  return (nodes ?? []).map((n) =>
-    n.kind === 'group'
-      ? {
-          label: n.label,
-          icon: n.icon,
-          items: itemsFor(n.children, pagesMap, ctx),
-        }
-      : itemFor(n, pagesMap, ctx),
-  );
-}
-
-function itemFor(pageNode, pagesMap, ctx) {
-  const href = urlInCtx(pageNode.pagePath, ctx);
-  const fm = pagesMap[href]?.frontmatter;
-  // Generated API pages carry their own label + HTTP method (for the sidebar
-  // method badge); normal pages source their label from frontmatter.
-  const label = pageNode.label ?? fm?.title ?? titleCase(lastSeg(href));
-  const item = { label, href };
-  if (pageNode.method) item.method = pageNode.method;
-  return item;
-}
+import GithubSlugger from 'github-slugger';
+import ISO6391 from 'iso-639-1';
+
+/**
+ * navigation.js — the PURE, framework-agnostic navigation model. No
+ * `fs`, no React, no Node-only imports: this file is imported by BOTH
+ * the Node-side Vite plugin (to normalize + walk) AND the browser
+ * runtime (to resolve the active page → sidebar/header). Sharing the
+ * exact same code on both sides is what keeps SSR and client render
+ * in lockstep (no hydration drift).
+ *
+ * Model: `velu.json`'s `navigation` is normalized into a canonical
+ * tree whose containment order is FIXED, regardless of how the author
+ * nested things, and identical to the URL-prefix order:
+ *
+ *   AXIS_ORDER:  product → version → language → tabs → groups → pages
+ *   URL:         /<product?>/<version?>/<language?>/<page-path>
+ *
+ * Default axis values contribute no URL segment. Dropdowns are out of
+ * scope by design.
+ */
+
+export const AXIS_ORDER = ['product', 'version', 'language'];
+
+// `language` in velu.json is stored as an ISO 639-1 code (e.g. "en");
+// the switcher shows the code + its native name. iso-639-1 covers the
+// full set of codes; unknown/invalid codes fall back to the code.
+function languageName(code) {
+  const c = String(code).toLowerCase();
+  return ISO6391.getNativeName(c) || code;
+}
+
+/** Fresh slugger per call → pure (no cross-call dedup state). */
+export function slugify(s) {
+  return new GithubSlugger().slug(String(s ?? ''));
+}
+
+/**
+ * Map a content page path to its in-context URL leaf:
+ *   "index"        → "/"
+ *   "sync/index"   → "/sync"
+ *   "sync/github"  → "/sync/github"
+ * Defined ONCE so collect + resolve never disagree.
+ */
+export function urlForPath(pagePath) {
+  const segs = String(pagePath)
+    .replace(/^\/+|\/+$/g, '')
+    .split('/')
+    .filter(Boolean);
+  if (segs[segs.length - 1] === 'index') segs.pop();
+  return '/' + segs.join('/');
+}
+
+/** Normalize a request/location path: drop query+hash, collapse a
+ *  trailing slash (except root), ensure a leading slash. Used on both
+ *  sides so the active-page lookup matches identically. */
+export function normalizeUrl(url) {
+  let u = String(url).split('#')[0].split('?')[0];
+  // Decode percent-encoding so non-ASCII slugs (e.g. an "Español"
+  // language → "/español") match whether the browser sends the path
+  // encoded ("/espa%C3%B1ol") or decoded.
+  try {
+    u = decodeURI(u);
+  } catch {
+    /* malformed escape — leave as-is */
+  }
+  if (!u.startsWith('/')) u = '/' + u;
+  if (u.length > 1) u = u.replace(/\/+$/, '');
+  return u || '/';
+}
+
+const titleCase = (s) =>
+  String(s)
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+
+const lastSeg = (url) => {
+  const segs = String(url).split('/').filter(Boolean);
+  return segs[segs.length - 1] ?? '';
+};
+
+// ── Normalization ──────────────────────────────────────────────────
+
+/**
+ * Build the canonical tree from a raw `navigation` object. At each
+ * level we honor a fixed precedence (products > versions > languages >
+ * tabs > leaf), so canonically-authored configs (axes nested in
+ * AXIS_ORDER, or only one axis) collapse to the intended tree. A leaf
+ * level mixes anchors + groups + pages as siblings.
+ */
+export function normalizeNavigation(raw) {
+  const root = { kind: 'root', children: normalizeChildren(raw ?? {}) };
+  applyDefaults(root.children);
+  return root;
+}
+
+function normalizeChildren(obj) {
+  // Anchors are pinned links that may sit alongside ANY level (incl.
+  // next to tabs as "global" anchors), so collect them regardless of
+  // which grouping branch this container uses.
+  const anchors = Array.isArray(obj.anchors)
+    ? obj.anchors.map(normalizeAnchor)
+    : [];
+  if (Array.isArray(obj.products))
+    return [...anchors, ...obj.products.map(normalizeProduct)];
+  if (Array.isArray(obj.versions))
+    return [...anchors, ...obj.versions.map(normalizeVersion)];
+  if (Array.isArray(obj.languages))
+    return [...anchors, ...obj.languages.map(normalizeLanguage)];
+  if (Array.isArray(obj.tabs))
+    return [...anchors, ...obj.tabs.map(normalizeTab)];
+  const out = [...anchors];
+  if (Array.isArray(obj.groups)) out.push(...obj.groups.map(normalizeGroup));
+  if (Array.isArray(obj.pages)) out.push(...obj.pages.map(normalizePageEntry));
+  return out;
+}
+
+function normalizeProduct(p) {
+  return {
+    kind: 'product',
+    label: p.name ?? p.product,
+    slug: slugify(p.product),
+    icon: p.icon,
+    color: p.color,
+    default: Boolean(p.default),
+    children: normalizeChildren(p),
+  };
+}
+
+function normalizeVersion(v) {
+  return {
+    kind: 'version',
+    label: v.version,
+    slug: slugify(v.version),
+    default: Boolean(v.default),
+    children: normalizeChildren(v),
+  };
+}
+
+function normalizeLanguage(l) {
+  const code = String(l.language);
+  return {
+    kind: 'language',
+    code,
+    label: languageName(code),
+    slug: slugify(code),
+    default: Boolean(l.default),
+    children: normalizeChildren(l),
+  };
+}
+
+function normalizeTab(t) {
+  return {
+    kind: 'tab',
+    label: t.tab,
+    slug: slugify(t.tab),
+    icon: t.icon,
+    href: t.href,
+    children: normalizeChildren(t),
+  };
+}
+
+function normalizeAnchor(a) {
+  return {
+    kind: 'anchor',
+    label: a.anchor,
+    icon: a.icon,
+    href: a.href,
+    color: a.color,
+  };
+}
+
+function normalizeGroup(g) {
+  const pages = (g.pages ?? []).map(normalizePageEntry);
+  // A group `root` is its landing page. velu-ui's Sidebar section
+  // heading isn't a link, so surface root as the group's FIRST item
+  // (its label comes from the root page's frontmatter, like any page).
+  if (g.root) pages.unshift({ kind: 'page', pagePath: g.root });
+  return {
+    kind: 'group',
+    label: g.group,
+    icon: g.icon,
+    expanded: Boolean(g.expanded),
+    root: g.root,
+    children: pages,
+  };
+}
+
+/** A `pages[]` entry is a string (page path), a generated OpenAPI page
+ *  ({ apiPage, label, method }), or a nested group. */
+function normalizePageEntry(entry) {
+  if (typeof entry === 'string') return { kind: 'page', pagePath: entry };
+  if (entry && entry.apiPage) {
+    return { kind: 'page', pagePath: entry.apiPage, label: entry.label, method: entry.method, api: true };
+  }
+  return normalizeGroup(entry);
+}
+
+/**
+ * Ensure each axis sibling-set has exactly one default: if the author
+ * marked none, the first declared becomes default (so an axis never
+ * prefixes every URL). Recurses through the whole tree.
+ */
+function applyDefaults(children) {
+  for (const kind of AXIS_ORDER) {
+    const sibs = children.filter((c) => c.kind === kind);
+    if (sibs.length && !sibs.some((s) => s.default)) sibs[0].default = true;
+  }
+  for (const c of children) if (c.children) applyDefaults(c.children);
+}
+
+// ── Walking ────────────────────────────────────────────────────────
+
+/**
+ * Walk the tree to every page leaf, computing its full URL (with the
+ * accumulated NON-default axis prefix) and its ancestor chain. Pure —
+ * the Node side adds fs existence on top (see navigation-node.js); the
+ * runtime uses it directly for resolution. Returns:
+ *   [{ pagePath, url, ctx, ancestors:Node[] }]
+ */
+export function walkPages(tree) {
+  const out = [];
+  const visit = (node, ctx, ancestors) => {
+    if (node.kind === 'page') {
+      out.push({
+        pagePath: node.pagePath,
+        url: urlInCtx(node.pagePath, ctx),
+        ctx: { ...ctx },
+        ancestors,
+        node,
+      });
+      return;
+    }
+    let next = ctx;
+    if (node.kind === 'product')
+      next = { ...ctx, product: node.default ? null : node.slug };
+    else if (node.kind === 'version')
+      next = { ...ctx, version: node.default ? null : node.slug };
+    else if (node.kind === 'language')
+      next = { ...ctx, language: node.default ? null : node.slug };
+    const nextAncestors =
+      node.kind === 'root' ? ancestors : [...ancestors, node];
+    for (const c of node.children ?? []) visit(c, next, nextAncestors);
+  };
+  visit(tree, { product: null, version: null, language: null }, []);
+  return out;
+}
+
+/** Compose a page URL from a page path + an axis context. */
+function urlInCtx(pagePath, ctx) {
+  const prefix = [ctx.product, ctx.version, ctx.language].filter(Boolean);
+  const leaf = urlForPath(pagePath).split('/').filter(Boolean);
+  return '/' + [...prefix, ...leaf].join('/');
+}
+
+// ── Resolution (runtime) ───────────────────────────────────────────
+
+/**
+ * Resolve the active page for a URL into everything the chrome needs.
+ * `pagesMap` is url → { frontmatter, ... } (from the virtual module),
+ * used to source sidebar labels from page frontmatter titles.
+ *
+ * Returns null when no page matches (404). Otherwise:
+ *   {
+ *     url, frontmatter,
+ *     sidebarSections, anchors,
+ *     tabs, activeTab,
+ *     products, activeProduct,
+ *     versions, activeVersion,
+ *     languages, activeLanguage,
+ *     breadcrumb,
+ *   }
+ */
+export function resolve(url, tree, pagesMap = {}) {
+  const norm = normalizeUrl(url);
+  const entries = walkPages(tree);
+  const match = entries.find((e) => e.url === norm);
+  if (!match) return null;
+
+  const { ctx, ancestors } = match;
+  const ancOf = (kind) => ancestors.filter((a) => a.kind === kind).pop();
+  const tabAnc = ancOf('tab');
+  const axisAnc = ancestors
+    .filter((a) => AXIS_ORDER.includes(a.kind))
+    .pop();
+  const productAnc = ancOf('product');
+  const versionAnc = ancOf('version');
+  const languageAnc = ancOf('language');
+
+  // Sidebar/anchor container = nearest tab, else nearest axis node,
+  // else the root. Its group/page children form the sidebar; its
+  // anchor children form the context-zone anchors.
+  const container = tabAnc || axisAnc || tree;
+  const containerKids = container.children ?? [];
+  const sidebarSections = buildSidebar(
+    containerKids.filter((n) => n.kind === 'group' || n.kind === 'page'),
+    pagesMap,
+    ctx,
+  );
+  // Whether THIS tab's sidebar holds any API page. The chrome uses it to
+  // pick ONE sidebar style for the whole tab (flat API list vs nested docs
+  // list) rather than flipping per selected page — so a tab that mixes an
+  // intro page with generated API operations reads as a single, stable
+  // sidebar. Derived from the sidebar items (the API ones carry `method`).
+  const sidebarHasApi = sidebarSectionsHaveApi(sidebarSections);
+  // Anchors are gathered from every container along the active path —
+  // root (global), the active product/version/language, and the active
+  // tab — so global anchors show on every page while tab-scoped ones
+  // show only within their tab.
+  const anchors = [tree, productAnc, versionAnc, languageAnc, tabAnc]
+    .filter(Boolean)
+    .flatMap((c) => (c.children ?? []).filter((n) => n.kind === 'anchor'))
+    .map((a) => ({ label: a.label, icon: a.icon, href: a.href, external: true }));
+
+  // Tabs live directly under the innermost axis node (or root).
+  const tabParent = axisAnc || tree;
+  const tabNodes = (tabParent.children ?? []).filter((n) => n.kind === 'tab');
+  const firstUrlUnder = (node) => {
+    const e = entries.find((en) => en.ancestors.includes(node));
+    return e ? e.url : node.href ?? '#';
+  };
+  const tabs = tabNodes.map((t) => ({
+    label: t.label,
+    icon: t.icon,
+    href: firstUrlUnder(t),
+  }));
+  const activeTab = tabAnc ? firstUrlUnder(tabAnc) : undefined;
+
+  // Switchers: sibling axis options + the URL to land on when chosen
+  // (first page of that option's subtree). Each option set is scoped
+  // to the active outer axis (versions within the active product, etc).
+  const axisOptions = (kind, parent) =>
+    (parent?.children ?? tree.children ?? [])
+      .filter((n) => n.kind === kind)
+      .map((n) => ({
+        label: n.label,
+        code: n.code, // language code (undefined for product/version)
+        slug: n.slug,
+        icon: n.icon,
+        default: n.default,
+        href: firstUrlUnder(n),
+        active: n === ancOf(kind),
+      }));
+  const products = axisOptions('product', tree);
+  const versions = axisOptions('version', productAnc ?? tree);
+  const languages = axisOptions('language', versionAnc ?? productAnc ?? tree);
+
+  // Breadcrumb: tab → group ancestors → page title.
+  const groupAncestors = ancestors.filter((a) => a.kind === 'group');
+  const pageTitle = pagesMap[norm]?.frontmatter?.title ?? titleCase(lastSeg(norm));
+  const breadcrumb = [
+    ...(tabAnc ? [{ label: tabAnc.label }] : []),
+    ...groupAncestors.map((g) => ({ label: g.label })),
+    { label: pageTitle },
+  ];
+
+  // Prev / next = neighbors in the sidebar's reading order (the
+  // flattened page sequence of the active section).
+  const ordered = flattenSidebar(sidebarSections);
+  const idx = ordered.findIndex((p) => p.href === norm);
+  const prev = idx > 0 ? ordered[idx - 1] : undefined;
+  const next = idx >= 0 && idx < ordered.length - 1 ? ordered[idx + 1] : undefined;
+
+  return {
+    url: norm,
+    frontmatter: pagesMap[norm]?.frontmatter ?? {},
+    sidebarSections,
+    sidebarHasApi,
+    anchors,
+    tabs,
+    activeTab,
+    products,
+    activeProduct: productAnc?.label,
+    versions,
+    activeVersion: versionAnc?.label,
+    languages,
+    activeLanguage: languageAnc?.label,
+    activeLanguageCode: languageAnc?.code,
+    breadcrumb,
+    prev,
+    next,
+  };
+}
+
+/** True when any item in the sidebar (at any nesting depth) is an API page —
+ *  i.e. carries an HTTP `method`. Lets the chrome render the whole tab with
+ *  the API sidebar style instead of switching per selected page. */
+function sidebarSectionsHaveApi(sections) {
+  const walk = (items) =>
+    (items ?? []).some((it) => it.method || (it.items && walk(it.items)));
+  return sections.some((s) => walk(s.items));
+}
+
+/** Flatten sidebar sections (incl. nested groups) to an ordered list of
+ *  page links {label, href} — the page reading order for prev/next. */
+function flattenSidebar(sections) {
+  const out = [];
+  const walk = (items) => {
+    for (const it of items) {
+      if (it.items) walk(it.items);
+      else out.push({ label: it.label, href: it.href });
+    }
+  };
+  for (const s of sections) walk(s.items);
+  return out;
+}
+
+/**
+ * Map a list of (group|page) nodes to the velu-ui Sidebar `sections`
+ * shape: [{ title, icon, items:[{ label, href, icon, items }] }].
+ * Loose top-level pages (not inside a group) collect into a leading
+ * untitled section. Page labels come from frontmatter title, falling
+ * back to a title-cased URL segment (the SAME fallback on both render
+ * sides). Sidebar derives open/active state from `activeHref`, so we
+ * don't compute it here.
+ */
+export function buildSidebar(nodes, pagesMap, ctx) {
+  const sections = [];
+  let loose = null;
+  for (const n of nodes) {
+    if (n.kind === 'group') {
+      sections.push({
+        title: n.label,
+        icon: n.icon,
+        items: itemsFor(n.children, pagesMap, ctx),
+      });
+    } else if (n.kind === 'page') {
+      if (!loose) {
+        loose = { title: '', items: [] };
+        sections.push(loose);
+      }
+      loose.items.push(itemFor(n, pagesMap, ctx));
+    }
+  }
+  return sections;
+}
+
+function itemsFor(nodes, pagesMap, ctx) {
+  return (nodes ?? []).map((n) =>
+    n.kind === 'group'
+      ? {
+          label: n.label,
+          icon: n.icon,
+          items: itemsFor(n.children, pagesMap, ctx),
+        }
+      : itemFor(n, pagesMap, ctx),
+  );
+}
+
+function itemFor(pageNode, pagesMap, ctx) {
+  const href = urlInCtx(pageNode.pagePath, ctx);
+  const fm = pagesMap[href]?.frontmatter;
+  // Generated API pages carry their own label + HTTP method (for the sidebar
+  // method badge); normal pages source their label from frontmatter.
+  const label = pageNode.label ?? fm?.title ?? titleCase(lastSeg(href));
+  const item = { label, href };
+  if (pageNode.method) item.method = pageNode.method;
+  return item;
+}