handoff-app 1.2.2-7 → 2.0.0-0

package/dist/transformers/preview/types.d.ts

@@ -226,3 +226,41 @@ export type PatternListObject = {
     id: string;
     path: string;
 } & PatternObject;
+/**
+ * A documentation page authored as markdown. The frontmatter is parsed into these fields and the
+ * markdown body is the rendered content. Pages are workspace-authored under `<workingPath>/pages/`
+ * and are first-class registry entities (publish/checkout) alongside components and patterns. Unlike
+ * components/patterns there is no rendered-artifact pipeline: the raw markdown is stored and rendered
+ * at runtime.
+ */
+export type PageObject = {
+    title: string;
+    description?: string;
+    group?: string;
+    /** Sort weight within the nav section (lower first). */
+    weight?: number;
+    /** Alternative title used in navigation. */
+    menuTitle?: string;
+    /** SEO overrides. */
+    metaTitle?: string;
+    metaDescription?: string;
+    /** When `false`, the page is hidden from navigation. */
+    enabled?: boolean;
+    /** External link target — a URL/path string, or `true` to flag the section as external. */
+    external?: string | boolean;
+    /** Optional declarative submenu structure (mirrors the markdown frontmatter `menu`). */
+    menu?: {
+        [key: string]: any;
+    };
+};
+export type PageListObject = {
+    /** Stable page id — its slug path (e.g. `guides/setup`), derived from the file location (id ≡ route). */
+    id: string;
+    /** Logical route the page is served at (e.g. `/guides/setup`). */
+    path: string;
+    /**
+     * Absolute filesystem path of the source `.md` (workspace store only). Workspace-only and stripped
+     * from the published transfer item — never persisted to or served from the registry.
+     */
+    sourcePath?: string;
+} & PageObject;

package/dist/transformers/utils/handlebars.d.ts

@@ -1,5 +1,6 @@
 import { RegisterHandlebarsHelpersContext } from '../../types/config';
 import { SlotMetadata } from '../preview/component';
+import { type ComponentArtifactPresence, type SharedArtifactPresence } from '../preview/component/shared-artifacts';
 import { HandlebarsContext } from '../types';
 /**
  * Registers common Handlebars helpers, then runs optional `hooks.registerHandlebarsHelpers`.
@@ -29,4 +30,6 @@ export declare const createHandlebarsContext: (data: {
     values?: any;
 }, options?: {
     includeSharedStyles?: boolean;
+    sharedArtifacts?: SharedArtifactPresence;
+    componentArtifacts?: ComponentArtifactPresence;
 }) => HandlebarsContext;

package/dist/transformers/utils/handlebars.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createHandlebarsContext = exports.registerHandlebarsHelpers = void 0;
 const handlebars_1 = __importDefault(require("handlebars"));
 const logger_1 = require("../../utils/logger");
+const shared_artifacts_1 = require("../preview/component/shared-artifacts");
 /**
  * Registers common Handlebars helpers, then runs optional `hooks.registerHandlebarsHelpers`.
  * @param data - Component data containing properties
@@ -66,14 +67,27 @@ exports.registerHandlebarsHelpers = registerHandlebarsHelpers;
  * @returns Handlebars context object
  */
 const createHandlebarsContext = (data, previewData, options) => {
-    var _a;
+    var _a, _b, _c;
     const basePath = (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : '';
-    const sharedStylesLink = (options === null || options === void 0 ? void 0 : options.includeSharedStyles) ? `<link rel="stylesheet" href="${basePath}/api/component/shared.css">` : '';
+    // Shared/global artifacts (`component/shared.css`, `component/main.css`, `component/main.js`) and
+    // the component's own css/js are referenced only when present, so a failed/absent build never
+    // produces a dangling reference. Absent presence info conservatively omits the artifacts.
+    const presence = (_b = options === null || options === void 0 ? void 0 : options.sharedArtifacts) !== null && _b !== void 0 ? _b : { mainJs: false, mainCss: false, sharedCss: false };
+    const componentPresence = (_c = options === null || options === void 0 ? void 0 : options.componentArtifacts) !== null && _c !== void 0 ? _c : { css: false, js: false };
+    const sharedStyleLinks = (0, shared_artifacts_1.renderSharedStyleLinks)(presence, basePath, {
+        includeSharedStyles: options === null || options === void 0 ? void 0 : options.includeSharedStyles,
+    });
+    const componentStyleLink = (0, shared_artifacts_1.renderComponentStyleLink)(componentPresence, data.id, basePath);
+    // The global script loads before the component-specific script so global side effects run first.
+    const globalScriptTag = (0, shared_artifacts_1.renderGlobalScriptTag)(presence, basePath);
+    const componentScriptTag = (0, shared_artifacts_1.renderComponentScriptTag)(componentPresence, data.id, basePath);
     return {
-        style: `${sharedStylesLink}<link rel="stylesheet" href="${basePath}/api/component/main.css">` +
-            `<link rel="stylesheet" href="${basePath}/api/component/${data.id}.css">\n` +
+        style: `${sharedStyleLinks ? `${sharedStyleLinks}\n` : ''}` +
+            `${componentStyleLink ? `${componentStyleLink}\n` : ''}` +
             `<link rel="stylesheet" href="${basePath}/assets/css/preview.css">`,
-        script: `<script src="${basePath}/api/component/${data.id}.js"></script>\n<script src="${basePath}/assets/js/preview.js"></script><script>var fields = ${JSON.stringify(data.properties)};</script>`,
+        script: `${globalScriptTag ? `${globalScriptTag}\n` : ''}` +
+            `${componentScriptTag ? `${componentScriptTag}\n` : ''}` +
+            `<script src="${basePath}/assets/js/preview.js"></script><script>var fields = ${JSON.stringify(data.properties)};</script>`,
         properties: previewData.values || {},
         fields: data.properties,
         title: data.title,

package/dist/types/config.d.ts

@@ -3,7 +3,7 @@ import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
 import { InlineConfig } from 'vite';
 import { SlotMetadata } from '../transformers/preview/component';
-import { ComponentListObject, PatternListObject, TransformComponentTokensResult } from '../transformers/preview/types';
+import { ComponentListObject, PageListObject, PatternListObject, TransformComponentTokensResult } from '../transformers/preview/types';
 import { ValidationResult } from './preview';
 export interface ImageStyle {
     name: string;
@@ -84,6 +84,98 @@ export interface NextAppConfig {
         websocket: number;
     };
 }
+/**
+ * Configuration for entry points to assets and components that will be built.
+ */
+export interface ConfigEntries {
+    /**
+     * Path to the main SCSS entry file
+     * @example "styles/main.scss"
+     */
+    scss?: string;
+    /**
+     * Path to the main JavaScript entry file
+     * @example "scripts/main.js"
+     */
+    js?: string;
+    /**
+     * Array of component paths to be included in the build
+     * @example ["components/button", "components/input"]
+     */
+    components?: string[];
+    /**
+     * Array of pattern paths to be included in the build.
+     * Patterns compose multiple component previews into single-page views.
+     * @example ["patterns/hero-section", "patterns"]
+     */
+    patterns?: string[];
+}
+/** Runtime mode. Resolved solely from `runtime.mode`; never inferred from env vars or connection settings. */
+export type RuntimeMode = 'workspace' | 'registry';
+/** Format used when synthesizing local workspace declarations. */
+export type DeclarationFormat = 'ts' | 'js' | 'cjs' | 'json';
+/**
+ * User-facing `runtime` configuration block. A single optional block that selects the runtime
+ * mode and carries mode-specific host/connection settings.
+ *
+ * Note: this is the authored shape. {@link RuntimeConfig} is the separate, resolved post-discovery
+ * shape used internally by the build/runtime.
+ */
+export interface HandoffRuntimeConfig {
+    /**
+     * The sole determinant of runtime mode. Defaults to `'workspace'` when omitted.
+     * Mode is never inferred from environment variables, database settings, or token presence.
+     */
+    mode?: RuntimeMode;
+    /** Workspace-mode settings. */
+    workspace?: {
+        entries?: ConfigEntries;
+        declarationFormat?: DeclarationFormat;
+    };
+    /** Registry-mode host settings. Env-var values are stored as names, never as secrets. */
+    registry?: {
+        /** Name of the env var holding the database URL. @default "DATABASE_URL" */
+        databaseUrlEnv?: string;
+        /** Name of the env var holding the registry API token. @default "HANDOFF_REGISTRY_API_TOKEN" */
+        apiTokenEnv?: string;
+        database?: {
+            /** @default "pg" */
+            adapter?: 'pg' | 'neon';
+        };
+        /**
+         * Where published asset blobs (icons/logos/fonts/sprites/archives) are stored. Defaults to the
+         * built-in PostgreSQL `bytea` store when omitted. Secrets are never persisted here - only the
+         * *names* of the env vars their values are read from at request time.
+         */
+        assetStorage?: {
+            /**
+             * Active storage provider for new uploads. `database` keeps bytes inline in Postgres; use the
+             * pre-packaged `vercel-blob` adapter or a `custom` module for object storage.
+             * @default "database"
+             */
+            adapter?: 'database' | 'vercel-blob' | 'custom';
+            /** For `adapter: "custom"` - server-only module path default-exporting a `defineAssetStorage` adapter. */
+            module?: string;
+            /** For `adapter: "vercel-blob"` - env var name holding the Blob read/write token. @default "BLOB_READ_WRITE_TOKEN" */
+            tokenEnv?: string;
+            /** Max bytes kept inline in the database `bytea` column (larger uploads are rejected). @default 4194304 */
+            maxInlineBytes?: number;
+            /** Non-secret adapter options (bucket env-var names, region, a custom `providerId`, …). */
+            options?: Record<string, unknown>;
+        };
+    };
+    /**
+     * Connected-workspace settings pointing at a remote registry. A connected workspace is
+     * `mode: 'workspace'` plus this block — it is not a third runtime mode.
+     */
+    registryConnection?: {
+        url?: string;
+        /** @default "HANDOFF_REGISTRY_URL" */
+        urlEnv?: string;
+        /** @default "HANDOFF_REGISTRY_ACCESS_TOKEN" */
+        accessTokenEnv?: string;
+    };
+}
 export interface Config {
     dev_access_token?: string | null | undefined;
     devAccessToken?: string | null | undefined;
@@ -112,32 +204,15 @@ export interface Config {
      * Configuration for the build pipeline
      */
     pipeline?: PipelineConfig;
+    /**
+     * Runtime configuration. `runtime.mode` is the sole determinant of runtime mode
+     * (`workspace` | `registry`), defaulting to `workspace` when omitted.
+     */
+    runtime?: HandoffRuntimeConfig;
     /**
      * Configuration for entry points to assets and components that will be built
      */
-    entries?: {
-        /**
-         * Path to the main SCSS entry file
-         * @example "styles/main.scss"
-         */
-        scss?: string;
-        /**
-         * Path to the main JavaScript entry file
-         * @example "scripts/main.js"
-         */
-        js?: string;
-        /**
-         * Array of component paths to be included in the build
-         * @example ["components/button", "components/input"]
-         */
-        components?: string[];
-        /**
-         * Array of pattern paths to be included in the build.
-         * Patterns compose multiple component previews into single-page views.
-         * @example ["patterns/hero-section", "patterns"]
-         */
-        patterns?: string[];
-    };
+    entries?: ConfigEntries;
     /**
      * Configuration for asset zip file download links
      * @default { icons: "/icons.zip", logos: "/logos.zip" }
@@ -283,7 +358,22 @@ export interface Config {
         registerHandlebarsHelpers?: (context: RegisterHandlebarsHelpersContext) => void;
     };
 }
-export type ClientConfig = Pick<Config, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'>;
+/**
+ * Non-secret runtime values projected to the browser. Only the resolved {@link RuntimeMode}
+ * crosses to the client; secrets and connection values never do.
+ */
+export interface ClientRuntimeConfig {
+    mode: RuntimeMode;
+    /**
+     * True when the runtime is a connected workspace (`mode: 'workspace'` plus a resolvable
+     * `registryConnection` URL). Non-secret: it never carries the URL or token value, only whether a
+     * connection is configured. Drives the workspace-only publish affordance in the docs UI.
+     */
+    connected: boolean;
+}
+export type ClientConfig = Pick<Config, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'> & {
+    runtime: ClientRuntimeConfig;
+};
 export interface RuntimeConfigComponentOptions {
     cssRootClass?: string;
     tokenNameSegments?: string[];
@@ -311,6 +401,9 @@ export interface RuntimeConfig {
         patterns: {
             [id: string]: PatternListObject;
         };
+        pages: {
+            [id: string]: PageListObject;
+        };
     };
     options: {
         [key: string]: RuntimeConfigComponentOptions;

package/dist/utils/menu-shell.d.ts

@@ -0,0 +1,60 @@
+import type { NavMenuItem, NavSubSection, SectionLink } from '../nav';
+/**
+ * Build-time menu *shell* builder.
+ *
+ * The docs navigation is two things: a SHELL (which sections exist, their order/titles, and which
+ * submenu slots are filled at runtime from the registry) and the runtime ENTITY lists
+ * (components/patterns/token sets) that the resolver splices into those slots. The shell is
+ * markdown-driven and therefore static per build; the entities are mutable at runtime and the
+ * resolved tree is served by `/api/docs/nav.json`.
+ *
+ * On Vercel the registry function cannot read `config/docs` markdown at request time — those reads
+ * use absolute build-machine paths (`HANDOFF_MODULE_PATH/...`) that do not exist on the deploy host
+ * and that nft cannot trace. So the shell is frozen here at build time (where the markdown is
+ * present) into `generated/nav-shell.json`, which the API route imports statically (bundled, path
+ * independent). The resolver combines it with runtime-variable records before the client renders it.
+ *
+ * This module is intentionally dependency-light and PURE (fs + gray-matter, no DB, no React, no
+ * `@handoff` aliases) so the compiled build pipeline (`dist/`) can import it — `src/app` is excluded
+ * from `tsc` and is not importable from the builder.
+ *
+ * It emits the canonical section structure with empty entity lists and `dynamic` splice markers.
+ * `src/nav/resolver.ts` is the sole place that fills those markers in every runtime mode.
+ */
+/** Back-compatible shell-builder names reconciled to the canonical navigation contract. */
+export type MenuShellSubItem = NavMenuItem;
+export type MenuShellSubSection = NavSubSection;
+export type MenuShellSection = SectionLink;
+export interface BuildMenuShellOptions {
+    /** Absolute path to the package docs root (`<modulePath>/config/docs`). */
+    docRoot: string;
+    /** Absolute path to the working-project page overrides (`<workingPath>/pages`), optional. */
+    workingPagesDir?: string;
+    /** Resolved app base path (e.g. `"foundations"` → no leading/trailing slash), optional. */
+    basePath?: string;
+}
+/**
+ * Paths that have dedicated route files and are therefore excluded from auto-scanned submenus.
+ * Single source of truth — the docs app imports this (re-exported there as `knownPaths`).
+ */
+export declare const KNOWN_PATHS: string[];
+/**
+ * The static Tokens submenu (Foundations only). Component token sets are mode-resolved runtime
+ * records, so the shell bakes only the deterministic Foundations entries. The resolver appends the
+ * component token-set records when it fills the dynamic slot. `basePath` must already be
+ * `"prefix/"`-normalized.
+ */
+export declare const buildTokensFoundationsMenu: (basePath: string) => MenuShellSubItem[];
+/**
+ * Recursively build menu entries from .md files in a directory (auto-scan for sections that do not
+ * declare a `menu` in frontmatter). Shared with the app — single source of truth for the auto-scan.
+ */
+export declare const buildMenuFromDirectory: (dirPath: string, urlPrefix: string) => MenuShellSubItem[];
+/**
+ * Build the full navigation shell from the docs markdown, with all registry entity slots
+ * (components/patterns/token sets) emitted empty and tagged `dynamic` for the resolver to fill.
+ *
+ * Returns the top-level `MenuShellSection[]` sorted by weight — the same shape the docs app's
+ * `SectionLink[]` uses, so it serializes directly into `generated/nav-shell.json`.
+ */
+export declare const buildMenuShell: (options: BuildMenuShellOptions) => MenuShellSection[];

package/dist/utils/menu-shell.js

@@ -0,0 +1,221 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMenuShell = exports.buildMenuFromDirectory = exports.buildTokensFoundationsMenu = exports.KNOWN_PATHS = void 0;
+const fs = __importStar(require("fs"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const lodash_1 = require("lodash");
+const path_1 = __importDefault(require("path"));
+/**
+ * Paths that have dedicated route files and are therefore excluded from auto-scanned submenus.
+ * Single source of truth — the docs app imports this (re-exported there as `knownPaths`).
+ */
+exports.KNOWN_PATHS = [
+    'assets',
+    'assets/fonts',
+    'assets/icons',
+    'assets/logos',
+    'foundations',
+    'foundations/colors',
+    'foundations/icons',
+    'foundations/effects',
+    'foundations/logos',
+    'foundations/logo',
+    'foundations/typography',
+    'system',
+    'system/component',
+    'system/tokens',
+    'system/tokens/foundations',
+    'system/tokens/foundations/colors',
+    'system/tokens/foundations/effects',
+    'system/tokens/foundations/typography',
+    'system/tokens/components',
+    'system/pattern',
+];
+/** Normalize the base path to the resolver's `"prefix/"` form (or `""`). */
+const normalizeBasePath = (basePath) => {
+    if (!basePath) {
+        return '';
+    }
+    return basePath.replace(/^\/+|\/+$/g, '') + '/';
+};
+/**
+ * The static Tokens submenu (Foundations only). Component token sets are mode-resolved runtime
+ * records, so the shell bakes only the deterministic Foundations entries. The resolver appends the
+ * component token-set records when it fills the dynamic slot. `basePath` must already be
+ * `"prefix/"`-normalized.
+ */
+const buildTokensFoundationsMenu = (basePath) => [
+    {
+        title: 'Foundations',
+        path: `${basePath}system/tokens/foundations`,
+        menu: [
+            { title: 'Colors', path: `${basePath}system/tokens/foundations/colors` },
+            { title: 'Effects', path: `${basePath}system/tokens/foundations/effects` },
+            { title: 'Typography', path: `${basePath}system/tokens/foundations/typography` },
+        ],
+    },
+];
+exports.buildTokensFoundationsMenu = buildTokensFoundationsMenu;
+/**
+ * Recursively build menu entries from .md files in a directory (auto-scan for sections that do not
+ * declare a `menu` in frontmatter). Shared with the app — single source of truth for the auto-scan.
+ */
+const buildMenuFromDirectory = (dirPath, urlPrefix) => {
+    var _a, _b, _c;
+    if (!fs.existsSync(dirPath))
+        return [];
+    const entries = fs.readdirSync(dirPath);
+    const items = [];
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dirPath, entry);
+        if (fs.lstatSync(fullPath).isDirectory()) {
+            const nestedItems = (0, exports.buildMenuFromDirectory)(fullPath, `${urlPrefix}/${entry}`);
+            if (nestedItems.length > 0) {
+                items.push({ title: (0, lodash_1.startCase)(entry), path: `${urlPrefix}/${entry}`, menu: nestedItems });
+            }
+        }
+        else if (entry.endsWith('.md') && entry !== 'index.md') {
+            const slug = entry.replace('.md', '');
+            const fullSlugPath = `${urlPrefix}/${slug}`.replace(/^\/+/, '');
+            if (exports.KNOWN_PATHS.indexOf(fullSlugPath) >= 0)
+                continue;
+            const contents = fs.readFileSync(fullPath, 'utf-8');
+            const { data: metadata } = (0, gray_matter_1.default)(contents);
+            if (metadata.enabled === false)
+                continue;
+            items.push({
+                title: (_b = (_a = metadata.menuTitle) !== null && _a !== void 0 ? _a : metadata.title) !== null && _b !== void 0 ? _b : (0, lodash_1.startCase)(slug),
+                path: `/${fullSlugPath}`,
+                weight: (_c = metadata.weight) !== null && _c !== void 0 ? _c : 0,
+            });
+        }
+    }
+    return items.sort((a, b) => { var _a, _b; return ((_a = a.weight) !== null && _a !== void 0 ? _a : 0) - ((_b = b.weight) !== null && _b !== void 0 ? _b : 0); });
+};
+exports.buildMenuFromDirectory = buildMenuFromDirectory;
+/**
+ * Build the full navigation shell from the docs markdown, with all registry entity slots
+ * (components/patterns/token sets) emitted empty and tagged `dynamic` for the resolver to fill.
+ *
+ * Returns the top-level `MenuShellSection[]` sorted by weight — the same shape the docs app's
+ * `SectionLink[]` uses, so it serializes directly into `generated/nav-shell.json`.
+ */
+const buildMenuShell = (options) => {
+    var _a, _b, _c;
+    const { docRoot, workingPagesDir } = options;
+    const basePath = normalizeBasePath(options.basePath);
+    if (!fs.existsSync(docRoot)) {
+        return [];
+    }
+    const docFiles = fs.readdirSync(docRoot);
+    let pageFiles = [];
+    if (workingPagesDir && fs.existsSync(workingPagesDir)) {
+        pageFiles = fs.readdirSync(workingPagesDir);
+    }
+    // De-duplicate; working-project pages win over package docs (same as the app).
+    const list = Array.from(new Set([...docFiles, ...pageFiles]));
+    const sections = [];
+    for (const fileName of list) {
+        const fromPages = pageFiles.includes(fileName);
+        const search = fromPages ? path_1.default.resolve(workingPagesDir, fileName) : path_1.default.resolve(docRoot, fileName);
+        if (fs.lstatSync(search).isDirectory() ||
+            search === path_1.default.resolve(docRoot, 'index.md') ||
+            (workingPagesDir && search === path_1.default.resolve(workingPagesDir, 'index.md')) ||
+            !fileName.endsWith('md')) {
+            continue;
+        }
+        const contents = fs.readFileSync(search, 'utf-8');
+        const { data: metadata } = (0, gray_matter_1.default)(contents);
+        if (metadata.enabled === false) {
+            continue;
+        }
+        const filepath = `/${fileName.replace('.md', '')}`;
+        const subSections = [];
+        if (metadata.menu) {
+            for (const key of Object.keys(metadata.menu)) {
+                const sub = metadata.menu[key];
+                if (sub.components) {
+                    // Omit `type` entirely when there is no filter (`undefined` is not JSON-serializable).
+                    const dynamic = typeof sub.components === 'string'
+                        ? { kind: 'components', type: sub.components }
+                        : { kind: 'components' };
+                    subSections.push({ title: sub.title, menu: [], dynamic });
+                }
+                else if (sub.tokens) {
+                    // Foundations are baked (deterministic); the resolver appends published component token
+                    // sets into this slot when it builds the refreshed registry tree.
+                    subSections.push({ title: 'Tokens', menu: (0, exports.buildTokensFoundationsMenu)(basePath), dynamic: { kind: 'token-components' } });
+                }
+                else if (sub.patterns) {
+                    // Always keep the empty patterns slot in the shell for the resolver to fill on refresh.
+                    subSections.push({ title: sub.title || 'Patterns', menu: [], dynamic: { kind: 'patterns' } });
+                }
+                else if (sub.enabled !== false) {
+                    subSections.push(sub);
+                }
+            }
+        }
+        else {
+            // No frontmatter menu: auto-scan the matching directory (working pages win over docs).
+            const dirName = fileName.replace('.md', '');
+            const nestedFromDocs = (0, exports.buildMenuFromDirectory)(path_1.default.resolve(docRoot, dirName), `/${dirName}`);
+            const nestedFromPages = workingPagesDir
+                ? (0, exports.buildMenuFromDirectory)(path_1.default.resolve(workingPagesDir, dirName), `/${dirName}`)
+                : [];
+            const seenPaths = new Set();
+            const children = [];
+            for (const item of [...nestedFromPages, ...nestedFromDocs]) {
+                if (item.path && !seenPaths.has(item.path)) {
+                    seenPaths.add(item.path);
+                    children.push(item);
+                }
+            }
+            // Wrap the scanned children under one labeled group (no `path`) so the side nav renders them as
+            // links — a flat subsection carrying a `path` but no `menu` renders nothing. This matches the
+            // record-backed nesting produced by the resolver so all modes remain structurally identical.
+            if (children.length > 0) {
+                subSections.push({ title: (_a = metadata.menuTitle) !== null && _a !== void 0 ? _a : metadata.title, menu: children });
+            }
+        }
+        let external = false;
+        if (typeof metadata.external === 'string' &&
+            (metadata.external.startsWith('http://') || metadata.external.startsWith('https://') || metadata.external.startsWith('/'))) {
+            external = metadata.external;
+        }
+        sections.push({
+            title: (_b = metadata.menuTitle) !== null && _b !== void 0 ? _b : metadata.title,
+            external,
+            weight: (_c = metadata.weight) !== null && _c !== void 0 ? _c : 0,
+            path: filepath,
+            subSections,
+        });
+    }
+    return sections.sort((a, b) => a.weight - b.weight);
+};
+exports.buildMenuShell = buildMenuShell;

package/dist/utils/stable-stringify.d.ts

@@ -0,0 +1,2 @@
+/** Serialize a value with object keys sorted at every nesting level. */
+export declare const stableStringify: (value: unknown) => string;

package/dist/utils/stable-stringify.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableStringify = void 0;
+/** Serialize a value with object keys sorted at every nesting level. */
+const stableStringify = (value) => JSON.stringify(value, (_, nestedValue) => nestedValue && typeof nestedValue === 'object' && !Array.isArray(nestedValue)
+    ? Object.fromEntries(Object.entries(nestedValue).sort(([left], [right]) => left.localeCompare(right)))
+    : nestedValue);
+exports.stableStringify = stableStringify;

package/docs/cli.md

@@ -51,11 +51,13 @@ Usage: handoff-app <cmd> <opts>
 Commands:
   fetch [opts] - Fetches the design tokens from the design system
 
-  build - Using the current tokens, build various outputs
-    build:app [opts] - Builds the design system static application
+  build [--target static|registry] [opts] - Builds the design system for the target (default: static export)
+    build:app [opts] - Builds the design system static application (alias of `build --target static`)
 
   start [opts] - Starts the design system in development mode
 
+  db:migrate [opts] - Runs registry database migrations (Drizzle / PostgreSQL). Reads the project config and database env vars, applies the package-owned migration set, and runs independently of `build`.
+
   make
     make:template <component> <state> [opts] - Creates a new template
     make:page <component> <state> [opts] - Creates a new page