handoff-app 1.2.2-7 → 2.0.0-1

package/drizzle/meta/_journal.json

@@ -0,0 +1,41 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1781979217509,
+      "tag": "0000_init_registry_storage",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1782045350977,
+      "tag": "0001_add_review_metadata",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1782713759115,
+      "tag": "0002_add_pages",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1783354008332,
+      "tag": "0003_add_tokens",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1783442253186,
+      "tag": "0004_add_assets",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'drizzle-kit';
+
+/**
+ * Drizzle Kit config for generating the registry's package-owned migrations.
+ *
+ * Migrations are generated into `./drizzle` and shipped with the `handoff-app` package; the
+ * bundled runner (`handoff-app db:migrate`) applies them at install/deploy time. Both built-in
+ * adapters (`pg`, `neon`) target the Postgres dialect, so a single migration set serves both.
+ *
+ * Generate after schema changes with: `npx drizzle-kit generate`
+ */
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './src/registry/db/schema.ts',
+  out: './drizzle',
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "1.2.2-7",
+  "version": "2.0.0-1",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",
@@ -53,6 +53,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
+    "@neondatabase/serverless": "^1.1.0",
     "@radix-ui/react-accordion": "^1.2.8",
     "@radix-ui/react-collapsible": "^1.1.2",
     "@radix-ui/react-dialog": "^1.1.4",
@@ -78,6 +79,7 @@
     "@types/react-syntax-highlighter": "^15.5.7",
     "@types/refractor": "^3.0.2",
     "@types/ws": "^8.18.1",
+    "@vercel/blob": "^1.1.1",
     "@vitejs/plugin-react": "^4.5.2",
     "archiver": "^5.3.1",
     "chalk": "^4.1.2",
@@ -86,6 +88,7 @@
     "clsx": "^2.1.1",
     "cross-spawn": "^7.0.3",
     "dotenv": "^16.0.3",
+    "drizzle-orm": "^0.45.2",
     "esbuild": "^0.25.0",
     "eslint": "^8.23.1",
     "eslint-config-next": "^15.3.4",
@@ -101,6 +104,7 @@
     "next": "^15.3.4",
     "next-themes": "^0.4.4",
     "node-html-parser": "^6.1.4",
+    "pg": "^8.22.0",
     "postcss": "^8.4.16",
     "prettier": "^3.4.2",
     "react": "^19.1.0",
@@ -121,13 +125,18 @@
     "ws": "^8.18.3",
     "yargs": "^17.7.2"
   },
+  "peerDependencies": {
+    "typescript": ">=5.6 <7"
+  },
   "devDependencies": {
     "@types/archiver": "^5.3.1",
     "@types/cross-spawn": "^6.0.2",
     "@types/fs-extra": "^11.0.4",
     "@types/handlebars": "^4.1.0",
     "@types/node": "^20.11.18",
+    "@types/pg": "^8.20.0",
     "@types/yargs": "^17.0.33",
+    "drizzle-kit": "^0.31.10",
     "np": "^10.2.0",
     "prettier-plugin-tailwindcss": "^0.7.0",
     "sass-embedded": "^1.89.0",

package/src/app/components/Component/Preview.tsx

@@ -1,3 +1,4 @@
+import { buildArtifactUrl } from '@handoff/artifacts/url';
 import { SlotMetadata } from '@handoff/transformers/preview/component';
 import { PageSlice } from '@handoff/transformers/preview/types';
 import { PreviewObject } from '@handoff/types/preview';
@@ -314,7 +315,7 @@ export const ComponentDisplay: React.FC<{
                         className="h-7 px-3 hover:bg-gray-300 [&_svg]:size-3"
                         onClick={() => {
                           // open in new tab
-                          window.open(`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${previewUrl}`, '_blank');
+                          window.open(buildArtifactUrl(`component/${previewUrl}`, process.env.HANDOFF_APP_BASE_PATH ?? ''), '_blank');
                         }}
                         variant="ghost"
                       >
@@ -344,7 +345,7 @@ export const ComponentDisplay: React.FC<{
                       display: 'block',
                       margin: '0 auto',
                     }}
-                    src={`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${previewUrl}`}
+                    src={buildArtifactUrl(`component/${previewUrl}`, process.env.HANDOFF_APP_BASE_PATH ?? '')}
                   />
                 </div>
               ) : (

package/src/app/components/Component/RegistryActions.tsx

@@ -0,0 +1,150 @@
+'use client';
+import { CheckIcon, CopyIcon, Download } from 'lucide-react';
+import React from 'react';
+
+import type { RuntimeMode } from '@handoff/types/config';
+import { cn } from '../../lib/utils';
+import { Button } from '../ui/button';
+import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover';
+
+type RegistryEntityType = 'component' | 'pattern';
+
+interface RegistryActionsProps {
+  /** Resolved runtime mode projected to the client. */
+  mode: RuntimeMode;
+  /** Whether this is a connected workspace (workspace mode + resolvable registry URL). */
+  connected: boolean;
+  /** The kind of entity the page documents. */
+  entityType: RegistryEntityType;
+  /** Stable id of the component/pattern, used in the copyable command. */
+  id: string;
+}
+
+type RegistryAction = {
+  label: string;
+  title: string;
+  description: React.ReactNode;
+  command: string;
+};
+
+/**
+ * Registry transfer affordance for the single component/pattern page. Surfaces a context-appropriate
+ * helper based on the runtime:
+ * - registry mode -> "Checkout" instructions (pull the entity into a connected workspace);
+ * - connected workspace (workspace mode + registry URL) -> "Publish" instructions.
+ *
+ * A static export is never a live runtime, so the publish affordance is suppressed there using the
+ * same `HANDOFF_BUILD_TARGET` gate the runtime-mode badge uses. Renders nothing when no action
+ * applies (e.g. a plain, unconnected workspace).
+ */
+export const RegistryActions: React.FC<RegistryActionsProps> = ({ mode, connected, entityType, id }) => {
+  // The static export is a frozen snapshot, not a live workspace, so the publish hint carries no
+  // meaning there and is omitted (mirrors the runtime-mode badge in the header).
+  const isStaticSnapshot = process.env.HANDOFF_BUILD_TARGET === 'static';
+
+  const action = resolveAction({ mode, connected, entityType, id, isStaticSnapshot });
+  if (!action) {
+    return null;
+  }
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="outline" size="sm" className="font-normal [&_svg]:size-3!">
+          <Download aria-hidden="true" />
+          {action.label}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent align="start" className="w-[360px] p-4">
+        <div className="flex flex-col gap-3">
+          <div className="flex items-center gap-2">
+            <Download className="size-4 text-gray-700 dark:text-gray-200" aria-hidden="true" />
+            <p className="text-sm font-semibold text-gray-900 dark:text-gray-100">{action.title}</p>
+          </div>
+          <p className="text-sm text-muted-foreground">{action.description}</p>
+          <div className="border-t" />
+          <div className="flex items-stretch overflow-hidden rounded-md border">
+            <code className="flex flex-1 items-center truncate px-3 py-2 font-mono text-xs text-gray-700 dark:text-gray-300">
+              {action.command}
+            </code>
+            <CopyCommandButton command={action.command} />
+          </div>
+          <p className="text-xs text-muted-foreground">Requires a workspace configured with registry access.</p>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+};
+
+/** Copy-to-clipboard control for the command box. No tooltip — just a copy/checkmark toggle. */
+const CopyCommandButton: React.FC<{ command: string }> = ({ command }) => {
+  const [copied, setCopied] = React.useState(false);
+
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(command);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch (err) {
+      console.error('Failed to copy command: ', err);
+    }
+  };
+
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="icon"
+      onClick={handleCopy}
+      aria-label={copied ? 'Copied' : 'Copy command'}
+      className="relative h-auto w-9 self-stretch rounded-none border-0 border-l shadow-none"
+    >
+      <span className={cn('transition-all', copied ? 'scale-100 opacity-100' : 'scale-0 opacity-0')}>
+        <CheckIcon className="stroke-gray-600" size={16} aria-hidden="true" />
+      </span>
+      <span className={cn('absolute transition-all', copied ? 'scale-0 opacity-0' : 'scale-100 opacity-100')}>
+        <CopyIcon size={16} aria-hidden="true" />
+      </span>
+    </Button>
+  );
+};
+
+const resolveAction = ({
+  mode,
+  connected,
+  entityType,
+  id,
+  isStaticSnapshot,
+}: RegistryActionsProps & { isStaticSnapshot: boolean }): RegistryAction | null => {
+  if (mode === 'registry') {
+    return {
+      label: 'Checkout',
+      title: `Checkout ${entityType}`,
+      description: (
+        <>
+          Run this in a connected workspace to pull <strong className="font-medium text-foreground">{id}</strong> from the
+          registry.
+        </>
+      ),
+      command: `npm run checkout -- ${entityType} ${id}`,
+    };
+  }
+
+  if (mode === 'workspace' && connected && !isStaticSnapshot) {
+    return {
+      label: 'Publish',
+      title: `Publish ${entityType}`,
+      description: (
+        <>
+          Run this in your connected workspace to publish <strong className="font-medium text-foreground">{id}</strong> to
+          the registry.
+        </>
+      ),
+      command: `npm run publish -- ${entityType} ${id}`,
+    };
+  }
+
+  return null;
+};
+
+export default RegistryActions;

package/src/app/components/Foundations/DisplayLogo.tsx

@@ -1,10 +1,18 @@
-import { Types as CoreTypes } from 'handoff-core';
 import React from 'react';
+import type { DisplayableAsset } from '../util/useCollectionAssets';
 
-export const DisplayLogo: React.FC<{ logo: CoreTypes.IAssetObject; content?: string; correct?: boolean }> = ({ logo, content }) => {
+export const DisplayLogo: React.FC<{ logo: DisplayableAsset; content?: string; correct?: boolean }> = ({ logo, content }) => {
+  // Workspace/static ships the SVG body inline in tokens.json (`data`) — render it directly so the
+  // logo has no dependency on the fetch-only `/api/assets/logos/*` files (absent on a static host).
+  // Registry has no inline body; it falls back to the individual asset content URL (`src`).
+  const src = logo.src ?? `${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/assets/logos/${logo.path}`;
   return (
     <div className="flex flex-col gap-5">
-      <img src={`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/assets/logos/${logo.path}`} alt="Usage Cards" className="rounded-3xl" />
+      {logo.data ? (
+        <div className="rounded-3xl" dangerouslySetInnerHTML={{ __html: logo.data }} />
+      ) : (
+        <img src={src} alt={logo.name} className="rounded-3xl" />
+      )}
       <div className="flex flex-row gap-4">
         <img src={`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/assets/images/check-circle.svg`} alt="Do" className="h-6 w-6" />
         <p className="leading-normal text-gray-500">

package/src/app/components/Layout/Header.tsx

@@ -4,11 +4,22 @@ import { ModeToggle } from '../../components/ModeSwitcher';
 import { MainNav } from '../../components/Navigation/MainNav';
 import { MobileNav } from '../../components/Navigation/MobileNav';
 import { cn } from '../../lib/utils';
+import { Badge } from '../ui/badge';
 import { useConfigContext } from '../context/ConfigContext';
 
+const RUNTIME_MODE_LABEL: Record<'workspace' | 'registry', string> = {
+  workspace: 'Workspace',
+  registry: 'Registry',
+};
+
 export function Header() {
   const context = useConfigContext();
   const [isScrolled, setIsScrolled] = useState(false);
+  const runtimeMode = context.config?.runtime?.mode ?? 'workspace';
+  const runtimeModeLabel = RUNTIME_MODE_LABEL[runtimeMode];
+  // The static export is a self-contained snapshot of the workspace, not a live runtime, so the
+  // runtime-mode badge carries no meaning there and is omitted.
+  const isStaticSnapshot = process.env.HANDOFF_BUILD_TARGET === 'static';
 
   useEffect(() => {
     const handleScroll = () => {
@@ -28,9 +39,16 @@ export function Header() {
     >
       <header className="border-grid container mx-auto w-full max-w-[1500px] bg-transparent px-8">
         <div className="mx-auto flex items-center justify-between @container">
-          <Link href="/">
-            <img className="max-h-5" src={`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/logo.svg`} alt={context.config?.app?.title} />
-          </Link>
+          <div className="flex items-center gap-3">
+            <Link href="/">
+              <img className="max-h-5" src={`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/logo.svg`} alt={context.config?.app?.title} />
+            </Link>
+            {!isStaticSnapshot && (
+              <Badge variant={runtimeMode === 'registry' ? 'info' : 'default'} aria-label={`Runtime mode: ${runtimeModeLabel}`}>
+                {runtimeModeLabel}
+              </Badge>
+            )}
+          </div>
           <div className="hidden items-center gap-4 @2xl:flex">
             <MainNav />
             <ModeToggle />

package/src/app/components/Layout/Main.tsx

@@ -5,6 +5,7 @@ import { Header } from '../../components/Layout/Header';
 import { ThemeProvider } from '../../components/util/theme-provider';
 import SideNav from '../Navigation/SideNav';
 import { ConfigContextProvider } from '../context/ConfigContext';
+import { hasRenderableNav } from '../../lib/utils';
 import { SidebarInset, SidebarProvider } from '../ui/sidebar';
 import { SectionLink } from '../util';
 
@@ -21,6 +22,13 @@ interface LayoutComponentProps {
   fullWidthHero?: boolean;
 }
 export default function Layout<LayoutComponentProps>({ children, config, menu, metadata, current, fullWidthHero = false }) {
+  // In registry mode the per-page `current` is empty for lambda-rendered (fallback) pages, so mount
+  // the sidebar regardless and let SideNav resolve its section from the cached shell (and collapse
+  // itself to full width when that section has no renderable nav). Workspace/static know the section
+  // at render time, so drop the left column entirely for pages with no side-nav content (e.g. a
+  // standalone page with no children) and let the content go full width.
+  const isRegistry = config?.runtime?.mode === 'registry';
+  const showSidebar = isRegistry || hasRenderableNav(current as SectionLink);
   return (
     <div>
       <ConfigContextProvider defaultConfig={config} defaultMenu={menu}>
@@ -48,10 +56,10 @@ export default function Layout<LayoutComponentProps>({ children, config, menu, m
                   <div className="mx-auto w-full">{children}</div>
                 </div>
               </div>
-            ) : current ? (
+            ) : showSidebar ? (
               <SidebarProvider>
                 <div className="flex w-full">
-                  <SideNav menu={current} />
+                  <SideNav />
                   <SidebarInset className="relative bg-transparent py-8 pl-8 pr-8 md:pl-8 lg:gap-10 lg:py-16 lg:pl-16">
                     <div className="mx-auto w-full">{children}</div>
                   </SidebarInset>
@@ -59,7 +67,7 @@ export default function Layout<LayoutComponentProps>({ children, config, menu, m
               </SidebarProvider>
             ) : (
               <div className="flex w-full">
-                <div className="relative bg-transparent px-16 py-8 lg:gap-10 lg:py-16 xl:grid">
+                <div className="relative w-full bg-transparent px-16 py-8 lg:gap-10 lg:py-16">
                   <div className="mx-auto w-full">{children}</div>
                 </div>
               </div>

package/src/app/components/Navigation/MainNav.tsx

@@ -10,6 +10,7 @@ import {
 } from '../../components/ui/navigation-menu';
 import { cn } from '../../lib/utils';
 import { useConfigContext } from '../context/ConfigContext';
+import { useNav } from '../context/NavProvider';
 
 const trimSlashes = (input: string): string => {
   return input.replace(/^\/+|\/+$/g, '');
@@ -18,11 +19,12 @@ const trimSlashes = (input: string): string => {
 export function MainNav() {
   const context = useConfigContext();
   const router = useRouter();
+  const { menu } = useNav();
   return (
     <NavigationMenu>
       <NavigationMenuList>
-        {context.menu &&
-          context.menu.map((section) => {
+        {menu &&
+          menu.map((section) => {
             const isActive = trimSlashes(router.asPath).startsWith(trimSlashes(section.path));
             return (
               <NavigationMenuItem key={section.title}>

package/src/app/components/Navigation/MobileNav.tsx

@@ -7,6 +7,7 @@ import { Button } from '../../components/ui/button';
 import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger } from '../../components/ui/sheet';
 import { cn } from '../../lib/utils';
 import { useConfigContext } from '../context/ConfigContext';
+import { useNav } from '../context/NavProvider';
 
 const trimSlashes = (input: string): string => {
   return input.replace(/^\/+|\/+$/g, '');
@@ -16,6 +17,7 @@ export function MobileNav() {
   const context = useConfigContext();
   const router = useRouter();
   const { theme, setTheme } = useTheme();
+  const { menu } = useNav();
 
   const toggleTheme = () => {
     if (theme === 'light') {
@@ -48,8 +50,8 @@ export function MobileNav() {
           </SheetTrigger>
         </SheetHeader>
         <div className="mt-8 flex flex-col space-y-4">
-          {context.menu &&
-            context.menu.map((section) => {
+          {menu &&
+            menu.map((section) => {
               const isActive = trimSlashes(router.asPath).startsWith(trimSlashes(section.path));
               return (
                 <Link

package/src/app/components/Navigation/SideNav.tsx

@@ -16,8 +16,9 @@ import {
 } from 'lucide-react';
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '../../components/ui/collapsible';
 
+import Link from 'next/link';
 import { useRouter } from 'next/router';
-import React from 'react';
+import React, { useEffect, useState } from 'react';
 import {
   Sidebar,
   SidebarContent,
@@ -30,8 +31,22 @@ import {
   SidebarMenuSub,
   SidebarSeparator,
 } from '../../components/ui/sidebar';
-import { normalizePathForMatch, toAbsolutePath } from '../../lib/utils';
-import { SectionLink } from '../util';
+import { normalizePathForMatch } from '../../lib/utils';
+import { useNav } from '../context/NavProvider';
+
+/**
+ * `next/link` re-applies `basePath`, but the menu item paths already carry the base prefix (built by
+ * the server navigation resolver). Strip the leading base segment once so the link is not
+ * double-prefixed; with no base path this just returns a leading-slash route.
+ */
+const stripBasePath = (p: string): string => {
+  const base = (process.env.HANDOFF_APP_BASE_PATH ?? '').replace(/^\/+|\/+$/g, '');
+  let rel = p.replace(/^\/+/, '');
+  if (base && (rel === base || rel.startsWith(`${base}/`))) {
+    rel = rel.slice(base.length).replace(/^\/+/, '');
+  }
+  return `/${rel}`;
+};
 
 const NormalMenuItem = ({ title, icon, path }) => {
   const router = useRouter();
@@ -39,10 +54,13 @@ const NormalMenuItem = ({ title, icon, path }) => {
   return (
     <SidebarMenuItem>
       <SidebarMenuButton asChild isActive={isActive}>
-        <a href={toAbsolutePath(path)} className="gap-3">
+        {/* Soft (client-side) navigation so moving between entity pages reuses the already-loaded
+            cached nav with no reload/flash. Prefetch is off: each prefetch would invoke the
+            fallback:'blocking' lambda data route, so fetch the target's data on click instead. */}
+        <Link href={stripBasePath(path)} prefetch={false} className="gap-3">
           <MenuIcon icon={icon} isActive={isActive} />
           <span>{title}</span>
-        </a>
+        </Link>
       </SidebarMenuButton>
     </SidebarMenuItem>
   );
@@ -53,8 +71,15 @@ const CollapsibleMenuItem = ({ title, icon, path, menu }) => {
   const isActive = menu.some(
     (item) => normalizePathForMatch(router.asPath).startsWith(normalizePathForMatch(item.path))
   );
+  // Controlled so the active group auto-opens on soft navigation (an uncontrolled `defaultOpen` is
+  // only read on mount and would not re-open the active group when the route changes client-side),
+  // while still letting the user collapse/expand groups manually.
+  const [open, setOpen] = useState(isActive);
+  useEffect(() => {
+    if (isActive) setOpen(true);
+  }, [isActive]);
   return (
-    <Collapsible defaultOpen={isActive} className="group/collapsible">
+    <Collapsible open={open} onOpenChange={setOpen} className="group/collapsible">
       <SidebarMenuItem>
         <CollapsibleTrigger asChild>
           <SidebarMenuButton className="h-9 gap-3">
@@ -118,13 +143,23 @@ const MenuIcon = ({ icon, isActive = false }) => {
   }
 };
 
-const SideNav = ({ menu }: { menu: SectionLink }) => {
+const SideNav = () => {
+  const { current } = useNav();
+  const sections = current?.subSections ?? [];
+
+  // Collapse the sidebar entirely (render nothing, reserve no gutter) when the resolved section has
+  // no renderable content, so the page content goes full width. A `dynamic` slot counts as
+  // renderable even before its entities load, to avoid a full-width → gutter flash in registry mode.
+  const hasContent = sections.some((section) => (section.menu && section.menu.length > 0) || !!section.dynamic);
+  if (!hasContent) {
+    return null;
+  }
+
   return (
     <Sidebar className="sticky left-auto">
       <SidebarContent className="px-4 pt-5">
-        {menu.subSections &&
-          menu.subSections.length > 0 &&
-          menu.subSections.map((section, index) => (
+        {sections.length > 0 &&
+          sections.map((section, index) => (
             <React.Fragment key={index}>
               <SidebarGroup>
                 {!section.path && <SidebarGroupLabel>{section.title}</SidebarGroupLabel>}
@@ -138,7 +173,7 @@ const SideNav = ({ menu }: { menu: SectionLink }) => {
                   </SidebarGroupContent>
                 )}
               </SidebarGroup>
-              {index < menu.subSections.length && <SidebarSeparator className="mx-4" />}
+              {index < sections.length && <SidebarSeparator className="mx-4" />}
             </React.Fragment>
           ))}
       </SidebarContent>

package/src/app/components/NotFound.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+
+interface NotFoundProps {
+  title?: string;
+  description?: React.ReactNode;
+  linkHref?: string;
+  linkLabel?: string;
+}
+
+const NotFound: React.FC<NotFoundProps> = () => {
+  return (
+    <div className="flex flex-col items-center">
+      <div className="mb-2 text-7xl font-bold text-gray-800 dark:text-white">404</div>
+      <h1 className="mb-4 text-2xl font-semibold text-gray-700 dark:text-gray-300">Oops! Page not found.</h1>
+      <p className="mb-6 max-w-md text-center text-gray-500 dark:text-gray-400">
+        This page doesn&rsquo;t exist or has been moved.
+        <br />
+        Please check the URL or return to the homepage.
+      </p>
+    </div>
+  );
+};
+
+export default NotFound;

package/src/app/components/context/NavProvider.tsx

@@ -0,0 +1,71 @@
+'use client';
+
+import type { NavData, SectionLink } from '@handoff/nav';
+import React, { createContext, useContext, useEffect, useState } from 'react';
+
+export type { NavData, NavEntity } from '@handoff/nav';
+
+interface INavContext {
+  nav: NavData;
+  currentSectionId: string;
+}
+
+const EMPTY_NAV: NavData = { shell: [] };
+const NavContext = createContext<INavContext>({ nav: EMPTY_NAV, currentSectionId: '' });
+const isRegistryMode = process.env.HANDOFF_RUNTIME_MODE === 'registry';
+
+// A module-level fulfilled cache and in-flight guard make the registry refresh a single hard-load
+// operation, including StrictMode remounts. A browser hard reload resets both and observes publishes.
+let cachedNav: NavData | null = null;
+let inFlight: Promise<NavData | null> | null = null;
+
+const loadNav = (): Promise<NavData | null> => {
+  if (cachedNav) return Promise.resolve(cachedNav);
+  if (inFlight) return inFlight;
+  inFlight = fetch(`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/docs/nav.json`)
+    .then((res) => (res.ok ? res.json() : null))
+    .then((data: NavData | null) => {
+      if (data) cachedNav = data;
+      return cachedNav;
+    })
+    .catch(() => null)
+    .finally(() => {
+      inFlight = null;
+    });
+  return inFlight;
+};
+
+export const NavProvider: React.FC<{
+  children: React.ReactNode;
+  initialNav?: NavData;
+  currentSectionId?: string;
+}> = ({ children, initialNav = EMPTY_NAV, currentSectionId = '' }) => {
+  // Registry alone owns refresh state. Workspace renders the latest page prop directly, so soft
+  // navigation cannot briefly expose the preceding page's tree and triggers no provider effect.
+  const [registryNav, setRegistryNav] = useState<NavData>(() => cachedNav ?? initialNav);
+
+  useEffect(() => {
+    if (!isRegistryMode || cachedNav) return;
+    let active = true;
+    loadNav().then((data) => {
+      if (active && data) setRegistryNav(data);
+    });
+    return () => {
+      active = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const nav = isRegistryMode ? registryNav : initialNav;
+  return <NavContext.Provider value={{ nav, currentSectionId }}>{children}</NavContext.Provider>;
+};
+
+/** The sole view-facing navigation API: one active tree and an exact-match active section. */
+export const useNav = (): { nav: NavData; menu: SectionLink[]; current: SectionLink | null } => {
+  const { nav, currentSectionId } = useContext(NavContext);
+  return {
+    nav,
+    menu: nav.shell,
+    current: nav.shell.find((section) => section.path === currentSectionId) ?? null,
+  };
+};