handoff-app 1.2.2-7 → 2.0.0-0

package/src/config/normalizers/page.ts

@@ -0,0 +1,45 @@
+import { PageListObject } from '../../transformers/preview/types';
+
+type RawPageFrontmatter = Record<string, any>;
+
+type NormalizePageOptions = {
+  /** The page id — its slug path (e.g. `guides/setup`), derived from the file location. */
+  id: string;
+  /** Logical route the page is served at (e.g. `/guides/setup`). */
+  routePath: string;
+  /** Absolute filesystem path of the source `.md` (workspace-only, stripped on publish). */
+  sourcePath: string;
+};
+
+/** Humanize a slug segment (`getting-started` → `Getting Started`) for a default title. */
+const humanize = (segment: string): string =>
+  segment
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim();
+
+/**
+ * Normalize a page's parsed markdown frontmatter into a {@link PageListObject}. Pages have no
+ * required authored fields (a bare `.md` is valid); the title falls back to a humanized last slug
+ * segment. The id is always the slug path (a page is addressed by its URL, so id ≡ route): the file
+ * location is the single source of identity for both filesystem and registry serving.
+ */
+export const normalizePageDeclaration = (raw: RawPageFrontmatter, options: NormalizePageOptions): PageListObject => {
+  const lastSegment = options.id.split('/').pop() ?? options.id;
+
+  return {
+    id: options.id,
+    path: options.routePath,
+    sourcePath: options.sourcePath,
+    title: typeof raw.title === 'string' && raw.title.trim() ? raw.title : humanize(lastSegment),
+    description: typeof raw.description === 'string' ? raw.description : undefined,
+    group: typeof raw.group === 'string' ? raw.group : undefined,
+    weight: typeof raw.weight === 'number' ? raw.weight : undefined,
+    menuTitle: typeof raw.menuTitle === 'string' ? raw.menuTitle : undefined,
+    metaTitle: typeof raw.metaTitle === 'string' ? raw.metaTitle : undefined,
+    metaDescription: typeof raw.metaDescription === 'string' ? raw.metaDescription : undefined,
+    enabled: typeof raw.enabled === 'boolean' ? raw.enabled : undefined,
+    external: typeof raw.external === 'string' || typeof raw.external === 'boolean' ? raw.external : undefined,
+    menu: raw.menu && typeof raw.menu === 'object' ? raw.menu : undefined,
+  };
+};

package/src/config/normalizers/pattern.ts

@@ -1,3 +1,4 @@
+import path from 'path';
 import { PatternListObject } from '../../transformers/preview/types';
 
 type RawPatternDeclaration = Record<string, any>;
@@ -51,6 +52,8 @@ export const normalizePatternDeclaration = (
     group: typeof raw.group === 'string' ? raw.group : undefined,
     tags: Array.isArray(raw.tags) ? raw.tags.filter((t: any) => typeof t === 'string') : undefined,
     components,
-    path: '',
+    // Source location of the pattern (declaration directory), retained so the store can expose a
+    // stable source reference for checkout/publish.
+    path: path.dirname(options.declarationPath),
   };
 };

package/src/config/runtime.ts

@@ -1,5 +1,6 @@
 import esbuild from 'esbuild';
 import fs from 'fs-extra';
+import matter from 'gray-matter';
 import { createRequire } from 'module';
 import path from 'path';
 import { ComponentListObject, PatternListObject } from '../transformers/preview/types';
@@ -9,6 +10,7 @@ import { Config, ConfigFileEntry, RuntimeConfig } from '../types/config';
 import { Logger } from '../utils/logger';
 import { normalizePathForCompare } from '../utils/path';
 import { normalizeComponentDeclaration } from './normalizers/declaration';
+import { normalizePageDeclaration } from './normalizers/page';
 import { normalizePatternDeclaration } from './normalizers/pattern';
 
 /**
@@ -56,7 +58,7 @@ const findPreferredModernDeclaration = (componentDir: string, componentBaseName:
   return modernFiles[0];
 };
 
-const resolveComponentDeclaration = (componentDir: string, componentBaseName: string): DeclarationResolution | null => {
+export const resolveComponentDeclaration = (componentDir: string, componentBaseName: string): DeclarationResolution | null => {
   const modernMatch = findPreferredModernDeclaration(componentDir, componentBaseName);
   const legacyFiles = getLegacyDeclarationFiles(componentBaseName);
   const legacyMatch = legacyFiles.find((candidate) => fs.existsSync(path.resolve(componentDir, candidate)));
@@ -171,6 +173,7 @@ export const initRuntimeConfig = (handoff: HandoffContext): [runtimeConfig: Runt
       js: undefined,
       components: {},
       patterns: {},
+      pages: {},
     },
   };
 
@@ -284,7 +287,12 @@ export const initRuntimeConfig = (handoff: HandoffContext): [runtimeConfig: Runt
           fallbackId: patternBaseName,
         });
       } catch (err) {
-        Logger.error(`Failed to read or parse pattern config: ${resolvedPatternConfigPath}`, err);
+        // Treat as a warning rather than an error: the file may be empty or
+        // mid-edit. It is already tracked in configFiles above, so
+        // watchRuntimeConfiguration will pick it up once the file is saved
+        // with valid content.
+        Logger.warn(`Pattern config skipped (incomplete or invalid) — will retry on next save: ${resolvedPatternConfigPath}`);
+        Logger.debug(`Pattern parse detail:`, err);
         continue;
       }
 
@@ -293,6 +301,26 @@ export const initRuntimeConfig = (handoff: HandoffContext): [runtimeConfig: Runt
     }
   }
 
+  // -------------------------------------------------------------------------
+  // Discover markdown pages
+  // -------------------------------------------------------------------------
+  // Working pages under `<workingPath>/pages/` are first-class registry entities (publish/checkout).
+  // Discovery mirrors the catch-all/static-path walk: every `.md` except `index.md` becomes a page
+  // keyed by its slug path. Package `config/docs` defaults are NOT entities (they ship with the tool).
+  const pagesRoot = path.resolve(handoff.workingPath, 'pages');
+  for (const segments of collectPageMarkdownPaths(pagesRoot)) {
+    const slug = segments.join('/');
+    const sourcePath = path.resolve(pagesRoot, `${slug}.md`);
+    try {
+      const { data: frontmatter } = matter(fs.readFileSync(sourcePath, 'utf-8'));
+      const page = normalizePageDeclaration(frontmatter, { id: slug, routePath: `/${slug}`, sourcePath });
+      result.entries.pages[page.id] = page;
+    } catch (err) {
+      Logger.warn(`Page skipped (unreadable or invalid frontmatter): ${sourcePath}`);
+      Logger.debug(`Page parse detail:`, err);
+    }
+  }
+
   // -------------------------------------------------------------------------
   // Inject synthetic previews from patterns onto components
   // -------------------------------------------------------------------------
@@ -301,6 +329,24 @@ export const initRuntimeConfig = (handoff: HandoffContext): [runtimeConfig: Runt
   return [result, Array.from(configFiles), configFileIndex];
 };
 
+/**
+ * Recursively collect `.md` files under a root, returning slug segments (relative path without the
+ * `.md`). `index.md` is excluded — section index content is served by dedicated/home routes.
+ */
+const collectPageMarkdownPaths = (rootDir: string, relativeParts: string[] = []): string[][] => {
+  if (!fs.existsSync(rootDir)) return [];
+  const results: string[][] = [];
+  for (const entry of fs.readdirSync(rootDir)) {
+    const fullPath = path.join(rootDir, entry);
+    if (fs.lstatSync(fullPath).isDirectory()) {
+      results.push(...collectPageMarkdownPaths(fullPath, [...relativeParts, entry]));
+    } else if (entry.endsWith('.md') && entry !== 'index.md') {
+      results.push([...relativeParts, entry.replace(/\.md$/, '')]);
+    }
+  }
+  return results;
+};
+
 /**
  * Returns a list of component directories for a given path.
  *

package/src/index.ts

@@ -2,11 +2,12 @@ import 'dotenv/config';
 import fs from 'fs-extra';
 import { Types as CoreTypes, Handoff as HandoffRunner, Providers } from 'handoff-core';
 import path from 'path';
-import buildApp, { devApp, watchApp } from './app-builder';
+import buildApp, { devApp, watchApp, type BuildPackage, type BuildTarget } from './app-builder';
 import { ejectConfig, ejectPages, ejectTheme } from './cli/eject';
 import { makeComponent, makePage, makeTemplate } from './cli/make';
 import { initConfigWithMetadata, initRuntimeConfig, validateConfig } from './config';
 import pipeline, { buildComponents, buildPatterns } from './pipeline';
+import { createFilesystemStore, type HandoffStore } from './store';
 import processComponents, { ComponentSegment } from './transformers/preview/component/builder';
 import { Config, ConfigFileEntry, RuntimeConfig } from './types/config';
 import { Logger } from './utils/logger';
@@ -28,6 +29,19 @@ class Handoff {
     typography: {};
   };
 
+  private _store?: HandoffStore;
+
+  /**
+   * Normalized store over the current workspace runtime for components, patterns, pages, tokens,
+   * and assets. It is created lazily and reads live from `runtimeConfig`.
+   */
+  get store(): HandoffStore {
+    if (!this._store) {
+      this._store = createFilesystemStore(this);
+    }
+    return this._store;
+  }
+
   private _initialArgs: { debug?: boolean; force?: boolean; config?: Partial<Config> } = {};
   private _configFilePaths: string[] = [];
   private _configFileIndex: Map<string, ConfigFileEntry> = new Map();
@@ -103,9 +117,101 @@ class Handoff {
     return this;
   }
 
-  async build(skipComponents?: boolean): Promise<Handoff> {
+  async build(target: BuildTarget = 'static', skipComponents?: boolean, buildPackage?: BuildPackage): Promise<Handoff> {
+    this.preRunner();
+    await buildApp(this, target, skipComponents, buildPackage);
+    return this;
+  }
+
+  /**
+   * Runs the package-owned registry database migrations against the configured PostgreSQL/Neon
+   * database. Independent of {@link build} — it only reads config + DB env vars and applies the
+   * bundled migration set.
+   */
+  async dbMigrate(): Promise<Handoff> {
+    if (!this.config) {
+      throw Error('Handoff not initialized');
+    }
+    const { runRegistryMigrations } = await import('./registry/db/migrate');
+    await runRegistryMigrations(this);
+    return this;
+  }
+
+  /**
+   * Publish a single component, pattern, or page from this connected workspace to the configured
+   * remote registry. Components and patterns receive a fresh targeted build before upload. Pages
+   * upload their record and markdown source because they render at runtime. The publish module is
+   * loaded lazily so the registry client and build code never enter the docs app bundle.
+   */
+  async publish(kind: 'component' | 'pattern' | 'page', id: string): Promise<Handoff> {
+    this.preRunner();
+    const { publishEntity } = await import('./registry/publish');
+    await publishEntity(this, kind, id);
+    return this;
+  }
+
+  /**
+   * Checkout a single component, pattern, or page from the connected remote registry. The checkout
+   * module is loaded lazily so the registry client never enters the docs app bundle.
+   */
+  async checkout(kind: 'component' | 'pattern' | 'page', id: string): Promise<Handoff> {
     this.preRunner();
-    await buildApp(this, skipComponents);
+    const { checkoutEntity } = await import('./registry/checkout');
+    await checkoutEntity(this, kind, id);
+    return this;
+  }
+
+  /**
+   * Publish design token sets from this connected workspace to the configured remote registry. Runs a
+   * fresh token build (Figma extract + style transformers), discovers the logical sets, and uploads
+   * each changed set (its extracted record + generated artifacts). Publishes every set when `setId` is
+   * omitted, or only the named set (`foundation/colors`, `component/<id>`). Loaded lazily so the
+   * registry client/build code never enters the docs app bundle.
+   */
+  async publishTokens(setId?: string): Promise<Handoff> {
+    this.preRunner();
+    const { publishTokens } = await import('./registry/publish/tokens');
+    await publishTokens(this, setId);
+    return this;
+  }
+
+  /**
+   * Checkout design token sets from the connected remote registry into this workspace: reconstruct
+   * the canonical local `tokens.json` and restore the generated token files to their configured output
+   * paths. Checks out every published set when `setId` is omitted, or only the named set. Loaded lazily
+   * so the registry client never enters the docs app bundle.
+   */
+  async checkoutTokens(setId?: string): Promise<Handoff> {
+    this.preRunner();
+    const { checkoutTokens } = await import('./registry/checkout/tokens');
+    await checkoutTokens(this, setId);
+    return this;
+  }
+
+  /**
+   * Publish asset collections (icons/logos/fonts) from this connected workspace to the configured
+   * remote registry. Runs a fresh build (Figma extract + asset generation), discovers the collections,
+   * uploads only content hashes the registry lacks, and finalizes each collection manifest atomically.
+   * Publishes every collection when `collection` is omitted, or only the named one. Loaded lazily so
+   * the registry client/build code never enters the docs app bundle.
+   */
+  async publishAssets(collection?: string): Promise<Handoff> {
+    this.preRunner();
+    const { publishAssets } = await import('./registry/publish/assets');
+    await publishAssets(this, collection);
+    return this;
+  }
+
+  /**
+   * Checkout asset collections from the connected remote registry into this workspace: recreate the
+   * standard workspace asset files, collection JSON, icon sprite/manifest, and downloadable archives.
+   * Checks out every published collection when `collection` is omitted, or only the named one. Loaded
+   * lazily so the registry client never enters the docs app bundle.
+   */
+  async checkoutAssets(collection?: string): Promise<Handoff> {
+    this.preRunner();
+    const { checkoutAssets } = await import('./registry/checkout/assets');
+    await checkoutAssets(this, collection);
     return this;
   }
 
@@ -261,6 +367,15 @@ class Handoff {
     return path.join(this.getOutputPath(), 'tokens');
   }
 
+  /**
+   * Gets the generated docs API root (`<workingPath>/public/api`) — the tree holding the asset
+   * collection JSON, per-asset icon/logo bodies, and the icon sprite + manifest.
+   * @returns {string} The absolute path to the public docs API directory
+   */
+  getAssetsApiPath(): string {
+    return path.resolve(this.workingPath, 'public', 'api');
+  }
+
   /**
    * Gets the path to the icons.zip file
    * @returns {string} The absolute path to the icons.zip file
@@ -329,6 +444,14 @@ export {
   definePattern,
   defineReactComponent,
 } from './declarations';
+export { defineAssetStorage } from './registry/asset-storage/define';
+export type {
+  AssetStorage,
+  AssetStorageContext,
+  AssetStorageFactory,
+  AssetStorageInput,
+  AssetStorageReadResult,
+} from './registry/asset-storage/types';
 export type {
   CsfDeclarationConfig,
   DeclarationPreview,

package/src/nav/index.ts

@@ -0,0 +1,94 @@
+/** A mode-aware placeholder retained in the serialized navigation shell. */
+export interface NavDynamicSlot {
+  kind: 'components' | 'patterns' | 'token-components';
+  type?: string;
+}
+
+/** A link nested within a navigation subsection. */
+export interface NavMenuItem {
+  title: string;
+  path?: string;
+  image?: string;
+  menu?: NavMenuItem[];
+}
+
+/** A group or direct link beneath a top-level navigation section. */
+export interface NavSubSection {
+  title: string;
+  path?: string;
+  image?: string;
+  menu?: NavMenuItem[];
+  dynamic?: NavDynamicSlot;
+}
+
+/** The canonical top-level navigation section shared by the build pipeline and docs app. */
+export interface SectionLink {
+  title: string;
+  weight: number;
+  external?: string | boolean;
+  path: string;
+  subSections: NavSubSection[];
+}
+
+/** Minimal navigation entity served by the docs navigation endpoint. */
+export interface NavEntity {
+  id: string;
+  title?: string;
+  group?: string;
+  type?: string;
+}
+
+/** A navigation token-set record. Only component sets are rendered in the component-token slot. */
+export interface NavTokenSet extends NavEntity {
+  kind: 'foundation' | 'component';
+}
+
+/** A declarative submenu entry carried by a page record. */
+export interface NavPageMenuDeclaration {
+  title?: string;
+  enabled?: boolean;
+  components?: boolean | string;
+  patterns?: boolean;
+  tokens?: boolean;
+  path?: string;
+  image?: string;
+  menu?: NavMenuItem[];
+}
+
+/** The page fields needed to compose page-authored navigation sections. */
+export interface NavPageRecord {
+  id: string;
+  path?: string;
+  title?: string;
+  menuTitle?: string;
+  weight?: number;
+  enabled?: boolean;
+  external?: string | boolean;
+  menu?: Record<string, NavPageMenuDeclaration> | NavPageMenuDeclaration[];
+}
+
+/** Eager, already-resolved inputs to the pure navigation resolver. */
+export interface NavSources {
+  shell: SectionLink[];
+  components: NavEntity[];
+  patterns: NavEntity[];
+  pages: NavPageRecord[];
+  tokenSets: NavTokenSet[];
+  tokenFoundations: NavMenuItem[];
+  basePath?: string;
+}
+
+export type NavMode = 'workspace' | 'registry';
+export type NavLoad = 'initial' | 'refresh';
+
+/** The render-ready navigation payload. */
+export interface NavData {
+  shell: SectionLink[];
+}
+
+export { getNavData } from './resolver';
+export type { GetNavDataInput } from './resolver';
+export { getWorkspaceNavData } from './workspace';
+export type { WorkspaceNavAdapterOptions, WorkspaceNavLoaders } from './workspace';
+export { getRegistryNavData } from './registry';
+export type { RegistryNavAdapterOptions, RegistryNavRecords } from './registry';

package/src/nav/registry.ts

@@ -0,0 +1,54 @@
+import { buildTokensFoundationsMenu } from '../utils/menu-shell';
+import type { NavData, NavEntity, NavLoad, NavPageRecord, NavTokenSet, SectionLink } from '.';
+import { getNavData } from './resolver';
+
+export interface RegistryNavRecords {
+  components: NavEntity[];
+  patterns: NavEntity[];
+  pages: NavPageRecord[];
+  tokenSets: NavTokenSet[];
+}
+
+export interface RegistryNavAdapterOptions {
+  shell: SectionLink[];
+  load: NavLoad;
+  basePath?: string;
+  fetchRecords: () => Promise<RegistryNavRecords>;
+}
+
+const emptyRecords = (): RegistryNavRecords => ({ components: [], patterns: [], pages: [], tokenSets: [] });
+
+/** Registry adapter: shell-only initial load, or one best-effort runtime-record fetch on refresh. */
+export const getRegistryNavData = async (options: RegistryNavAdapterOptions): Promise<NavData> => {
+  let records = emptyRecords();
+  if (options.load === 'refresh') {
+    try {
+      records = (await options.fetchRecords()) ?? records;
+    } catch {
+      // Fall back to the baked navigation shell when the registry backend is unavailable.
+    }
+  }
+  const componentById = new Map(records.components.map((component) => [component.id, component]));
+  const tokenSets = records.tokenSets.map((set) => {
+    const id = set.id.startsWith('component/') ? set.id.slice('component/'.length) : set.id;
+    const component = componentById.get(id);
+    return {
+      ...set,
+      title: set.title || component?.title,
+      group: set.group ?? component?.group,
+    };
+  });
+  const normalizedBasePath = options.basePath ? `${options.basePath.replace(/^\/+|\/+$/g, '')}/` : '';
+
+  return getNavData({
+    mode: 'registry',
+    load: options.load,
+    sources: {
+      shell: options.shell,
+      ...records,
+      tokenSets,
+      tokenFoundations: buildTokensFoundationsMenu(normalizedBasePath),
+      basePath: options.basePath,
+    },
+  });
+};

package/src/nav/resolver.ts

@@ -0,0 +1,217 @@
+import { startCase } from 'lodash';
+import type {
+  NavData,
+  NavEntity,
+  NavLoad,
+  NavMenuItem,
+  NavMode,
+  NavPageMenuDeclaration,
+  NavPageRecord,
+  NavSources,
+  NavSubSection,
+  SectionLink,
+} from '.';
+
+export interface GetNavDataInput {
+  mode: NavMode;
+  load: NavLoad;
+  sources: NavSources;
+}
+
+const normalizeBasePath = (basePath?: string): string => {
+  if (!basePath) return '';
+  return `${basePath.replace(/^\/+|\/+$/g, '')}/`;
+};
+
+const cloneMenu = (menu: NavMenuItem[] = []): NavMenuItem[] =>
+  menu.map((item) => ({ ...item, ...(item.menu ? { menu: cloneMenu(item.menu) } : {}) }));
+
+const cloneSubSection = (section: NavSubSection): NavSubSection => ({
+  ...section,
+  ...(section.dynamic ? { dynamic: { ...section.dynamic } } : {}),
+  ...(section.menu ? { menu: cloneMenu(section.menu) } : {}),
+});
+
+const cloneSection = (section: SectionLink): SectionLink => ({
+  ...section,
+  subSections: section.subSections.map(cloneSubSection),
+});
+
+const entityTitle = (entity: NavEntity): string => entity.title || startCase(entity.id);
+
+const buildEntityMenu = (entities: NavEntity[], segment: 'component' | 'pattern', basePath: string): NavMenuItem[] => {
+  const grouped = new Map<string, NavEntity[]>();
+  for (const entity of entities) {
+    const group = entity.group ?? '';
+    grouped.set(group, [...(grouped.get(group) ?? []), entity]);
+  }
+
+  return Array.from(grouped.entries())
+    .map(([group, records]) => ({
+      title: group || 'Uncategorized',
+      path: '',
+      menu: records
+        .map((record) => ({
+          title: entityTitle(record),
+          path: `${basePath}system/${segment}/${record.id}`,
+        }))
+        .sort((a, b) => a.title.localeCompare(b.title)),
+    }))
+    .map(({ path: _path, ...group }) => group)
+    .sort((a, b) => a.title.localeCompare(b.title));
+};
+
+const buildTokensMenu = (sources: NavSources, basePath: string): NavMenuItem[] => {
+  const foundations = cloneMenu(sources.tokenFoundations);
+  const componentSets = sources.tokenSets
+    .filter((set) => set.kind === 'component')
+    .map((set) => {
+      const id = set.id.startsWith('component/') ? set.id.slice('component/'.length) : set.id;
+      return {
+        title: set.title || startCase(id),
+        path: `${basePath}system/tokens/components/${id}`,
+      };
+    })
+    .sort((a, b) => a.title.localeCompare(b.title));
+
+  if (componentSets.length > 0) {
+    foundations.push({
+      title: 'Components',
+      path: `${basePath}system/tokens/components`,
+      menu: componentSets,
+    });
+  }
+  return foundations;
+};
+
+const fillSubSections = (subSections: NavSubSection[], sources: NavSources, keepEmpty: boolean): NavSubSection[] => {
+  const basePath = normalizeBasePath(sources.basePath);
+  const resolved: NavSubSection[] = [];
+
+  for (const original of subSections) {
+    const section = cloneSubSection(original);
+    if (section.dynamic?.kind === 'components') {
+      const entities = section.dynamic.type
+        ? sources.components.filter((component) => component.type === section.dynamic?.type)
+        : sources.components;
+      section.menu = buildEntityMenu(entities, 'component', basePath);
+    } else if (section.dynamic?.kind === 'patterns') {
+      section.menu = buildEntityMenu(sources.patterns, 'pattern', basePath);
+    } else if (section.dynamic?.kind === 'token-components') {
+      section.menu = buildTokensMenu(sources, basePath);
+    }
+
+    if (!section.dynamic || keepEmpty || (section.menu?.length ?? 0) > 0) {
+      resolved.push(section);
+    }
+  }
+  return resolved;
+};
+
+const pageMenuEntries = (menu: NavPageRecord['menu']): NavPageMenuDeclaration[] => (Array.isArray(menu) ? menu : Object.values(menu ?? {}));
+
+const declarationToSubSection = (declaration: NavPageMenuDeclaration, sources: NavSources): NavSubSection | undefined => {
+  if (declaration.components) {
+    return {
+      title: declaration.title ?? 'Components',
+      menu: [],
+      dynamic: typeof declaration.components === 'string' ? { kind: 'components', type: declaration.components } : { kind: 'components' },
+    };
+  }
+  if (declaration.patterns) {
+    return { title: declaration.title ?? 'Patterns', menu: [], dynamic: { kind: 'patterns' } };
+  }
+  if (declaration.tokens) {
+    return {
+      title: 'Tokens',
+      menu: cloneMenu(sources.tokenFoundations),
+      dynamic: { kind: 'token-components' },
+    };
+  }
+  if (declaration.enabled === false) return undefined;
+  return {
+    title: declaration.title ?? '',
+    ...(declaration.path !== undefined ? { path: declaration.path } : {}),
+    ...(declaration.image !== undefined ? { image: declaration.image } : {}),
+    ...(declaration.menu !== undefined ? { menu: cloneMenu(declaration.menu) } : {}),
+  };
+};
+
+const buildChildPageItems = (parentId: string, pages: NavPageRecord[]): NavMenuItem[] => {
+  const prefix = `${parentId}/`;
+  const segments = Array.from(
+    new Set(pages.filter((page) => page.id.startsWith(prefix)).map((page) => page.id.slice(prefix.length).split('/')[0]))
+  );
+
+  return segments
+    .map((segment) => {
+      const id = `${parentId}/${segment}`;
+      const record = pages.find((page) => page.id === id);
+      const nested = buildChildPageItems(id, pages);
+      const item: NavMenuItem & { weight: number } = {
+        title: record?.menuTitle || record?.title || startCase(segment),
+        path: record?.path ?? `/${id}`,
+        weight: record?.weight ?? 0,
+      };
+      if (nested.length > 0) item.menu = nested;
+      return item;
+    })
+    .sort((a, b) => a.weight - b.weight || a.title.localeCompare(b.title))
+    .map(({ weight: _weight, ...item }) => item);
+};
+
+const buildPageSections = (sources: NavSources, keepEmpty: boolean): SectionLink[] => {
+  const pages = sources.pages.filter((page) => page.enabled !== false);
+  return pages
+    .filter((page) => !page.id.includes('/'))
+    .map((page) => {
+      const declared = page.menu
+        ? pageMenuEntries(page.menu)
+            .map((entry) => declarationToSubSection(entry, sources))
+            .filter((entry): entry is NavSubSection => entry !== undefined)
+        : [];
+      const children = page.menu ? [] : buildChildPageItems(page.id, pages);
+      const subSections = page.menu
+        ? fillSubSections(declared, sources, keepEmpty)
+        : children.length > 0
+          ? [{ title: page.menuTitle || page.title || startCase(page.id), menu: children }]
+          : [];
+      const external =
+        typeof page.external === 'string' &&
+        (page.external.startsWith('http://') || page.external.startsWith('https://') || page.external.startsWith('/'))
+          ? page.external
+          : false;
+      return {
+        title: page.menuTitle || page.title || startCase(page.id),
+        external,
+        weight: page.weight ?? 0,
+        path: page.path ?? `/${page.id}`,
+        subSections,
+      };
+    });
+};
+
+const resolveCompleteTree = (sources: NavSources, keepEmpty: boolean): SectionLink[] => {
+  const byPath = new Map(
+    sources.shell.map((section) => [
+      section.path,
+      { ...cloneSection(section), subSections: fillSubSections(section.subSections, sources, keepEmpty) },
+    ])
+  );
+  for (const section of buildPageSections(sources, keepEmpty)) {
+    byPath.set(section.path, section);
+  }
+  return Array.from(byPath.values()).sort((a, b) => a.weight - b.weight);
+};
+
+/** Resolve an eager navigation snapshot without fetching, mutation, or asynchronous work. */
+export const getNavData = ({ mode, load, sources }: GetNavDataInput): NavData => {
+  if (mode === 'workspace') {
+    return { shell: resolveCompleteTree(sources, false) };
+  }
+
+  if (load === 'initial') {
+    return { shell: sources.shell.map(cloneSection) };
+  }
+  return { shell: resolveCompleteTree(sources, true) };
+};