@graph8/sdk 0.358.0 → 0.362.0

package/templates/next-app/components/app-shell.tsx.tmpl

@@ -2,33 +2,248 @@
 
 import Link from "next/link";
 import { usePathname } from "next/navigation";
-import type { ReactNode } from "react";
+import { useEffect, useMemo, useState, type ReactNode } from "react";
+import { ChevronsLeft, ChevronsRight, Menu, Search } from "lucide-react";
+import { Kbd, Sheet, SheetContent, SheetDescription, SheetTitle, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, cn } from "@graph8/sdk/ui";
 import { nav } from "@/lib/nav";
+import { ConnectionStatus } from "./shell/connection-status";
+import { currentNavEntry, groupNav, isActivePath, isEditableTarget, type NavEntry } from "./shell/nav-model";
+import { QuickJump } from "./shell/quick-jump";
+import { ThemeToggle } from "./shell/theme-toggle";
 
-/** Sidebar + content area. Edit freely: add a logo, group the links, add your own auth. */
-export function AppShell({ children }: { children: ReactNode }) {
+/**
+ * The app frame: a grouped sidebar (icons, active state, collapsible, remembered), a workspace header
+ * (title, current screen, quick jump, connection status, theme), a mobile drawer, and the content.
+ * Edit freely: add your logo, a user menu (`userMenu`), more header tools (`headerSlot`).
+ *
+ * Keyboard: Cmd/Ctrl+K jumps to a screen, Cmd/Ctrl+B collapses the sidebar.
+ */
+export interface AppShellProps {
+  children: ReactNode;
+  /** Right side of the header, before the theme toggle (a user menu, a help link). */
+  headerSlot?: ReactNode;
+  /** Replaces the connection status pill (your own session UI). `null` hides it. */
+  status?: ReactNode | null;
+  /** Bottom of the sidebar (workspace switcher, version). */
+  sidebarFooter?: ReactNode;
+  /** Pad the content area. Off by default: screens built with ScreenLayout bring their own padding. */
+  contentPadding?: boolean;
+}
+
+const items: readonly NavEntry[] = nav;
+const COLLAPSED_KEY = "g8.sidebar.collapsed";
+
+function isMod(e: KeyboardEvent): boolean {
+  return e.metaKey || e.ctrlKey;
+}
+
+function NavLink({ item, active, collapsed, onNavigate }: { item: NavEntry; active: boolean; collapsed: boolean; onNavigate?: () => void }) {
+  const Icon = item.icon;
+  const link = (
+    <Link
+      href={item.path}
+      aria-current={active ? "page" : undefined}
+      onClick={onNavigate}
+      title={collapsed ? undefined : item.description}
+      className={cn(
+        "group flex h-8 items-center gap-2.5 rounded-md text-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        collapsed ? "w-8 justify-center" : "px-2",
+        active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "text-text-color-muted hover:bg-surface-hover hover:text-foreground",
+      )}
+    >
+      <span className={cn("flex size-5 shrink-0 items-center justify-center", active ? "text-foreground" : "text-text-color-muted group-hover:text-foreground")}>
+        {Icon ? (
+          <Icon className="size-4" strokeWidth={1.5} aria-hidden />
+        ) : (
+          <span aria-hidden className={cn("flex size-4 items-center justify-center rounded-sm text-[10px] font-medium uppercase", active ? "bg-foreground text-background" : "bg-muted")}>
+            {item.label.charAt(0)}
+          </span>
+        )}
+      </span>
+      {collapsed ? <span className="sr-only">{item.label}</span> : <span className="truncate">{item.label}</span>}
+    </Link>
+  );
+  if (!collapsed) return link;
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{link}</TooltipTrigger>
+      <TooltipContent side="right" className="text-xs">
+        {item.label}
+        {item.description ? <span className="ml-1.5 opacity-70">{item.description}</span> : null}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+function SidebarNav({ pathname, collapsed, onNavigate }: { pathname: string | null; collapsed: boolean; onNavigate?: () => void }) {
+  const groups = useMemo(() => groupNav(items), []);
+  return (
+    <nav aria-label="Main" className="flex flex-1 flex-col gap-1 overflow-y-auto overflow-x-hidden px-2 py-2">
+      {groups.map((group, gi) => (
+        <div key={group.label ?? "_top"} className={cn("flex flex-col gap-0.5", gi > 0 && "mt-2")}>
+          {group.label ? (
+            collapsed ? (
+              <div aria-hidden className="mx-2 my-1 border-t border-sidebar-border" />
+            ) : (
+              <div className="truncate px-2 pb-1 pt-1 text-[11px] font-medium uppercase tracking-wide text-text-color-muted">{group.label}</div>
+            )
+          ) : null}
+          {group.items.map((item) => (
+            <NavLink key={item.path} item={item} active={isActivePath(item.path, pathname)} collapsed={collapsed} onNavigate={onNavigate} />
+          ))}
+        </div>
+      ))}
+    </nav>
+  );
+}
+
+export function AppShell({ children, headerSlot, status, sidebarFooter, contentPadding = false }: AppShellProps) {
   const pathname = usePathname();
+  const [collapsed, setCollapsed] = useState(false);
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const [jumpOpen, setJumpOpen] = useState(false);
+  const current = currentNavEntry(items, pathname);
+
+  // Remember the sidebar width per browser.
+  useEffect(() => {
+    try {
+      setCollapsed(localStorage.getItem(COLLAPSED_KEY) === "1");
+    } catch {
+      // storage unavailable: start expanded
+    }
+  }, []);
+  const toggleCollapsed = () => {
+    setCollapsed((c) => {
+      try {
+        localStorage.setItem(COLLAPSED_KEY, c ? "0" : "1");
+      } catch {
+        // ignore
+      }
+      return !c;
+    });
+  };
+
+  useEffect(() => {
+    setMobileOpen(false);
+  }, [pathname]);
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (!isMod(e)) return;
+      if (e.key.toLowerCase() === "k") {
+        e.preventDefault();
+        setJumpOpen((o) => !o);
+      } else if (e.key.toLowerCase() === "b") {
+        // Cmd/Ctrl+B means bold in a text field: leave it to the field.
+        if (isEditableTarget(e.target)) return;
+        e.preventDefault();
+        toggleCollapsed();
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  const brand = (
+    <div className={cn("flex h-14 shrink-0 items-center gap-2.5 border-b border-sidebar-border", collapsed ? "justify-center px-0" : "px-4")}>
+      <span aria-hidden className="flex size-7 shrink-0 items-center justify-center rounded-md bg-foreground text-[11px] font-medium uppercase text-background">
+        {String({{titleJson}}).charAt(0)}
+      </span>
+      <div className={cn("min-w-0 truncate text-sm font-medium text-foreground", collapsed && "sr-only")}>{{{titleJson}}}</div>
+    </div>
+  );
+
   return (
-    <div className="flex min-h-screen">
-      <aside className="w-56 shrink-0 border-r border-border p-4">
-        <div className="mb-4 text-sm font-semibold">{{{titleJson}}}</div>
-        <nav className="flex flex-col gap-1" aria-label="Main">
-          {nav.map((item) => {
-            const active = item.path === "/" ? pathname === "/" : pathname === item.path || pathname.startsWith(`${item.path}/`);
-            return (
-              <Link
-                key={item.path}
-                href={item.path}
-                aria-current={active ? "page" : undefined}
-                className={`rounded-md px-3 py-1.5 text-sm ${active ? "bg-muted font-medium" : "text-muted-foreground hover:bg-muted"}`}
+    <TooltipProvider delayDuration={100}>
+      <div className="flex h-dvh w-full overflow-hidden bg-background text-foreground">
+        <aside
+          aria-label="Sidebar"
+          data-collapsed={collapsed ? "true" : "false"}
+          className={cn("hidden h-full shrink-0 flex-col border-r border-sidebar-border bg-sidebar transition-[width] duration-150 md:flex", collapsed ? "w-14" : "w-60")}
+        >
+          {brand}
+          <SidebarNav pathname={pathname} collapsed={collapsed} />
+          <div className={cn("flex shrink-0 items-center gap-1 border-t border-sidebar-border p-2", collapsed ? "flex-col" : "")}>
+            {sidebarFooter ? <div className={cn("min-w-0 flex-1", collapsed && "hidden")}>{sidebarFooter}</div> : null}
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  onClick={toggleCollapsed}
+                  aria-label={collapsed ? "Expand sidebar" : "Collapse sidebar"}
+                  aria-expanded={!collapsed}
+                  className={cn("inline-flex size-8 shrink-0 items-center justify-center rounded-md text-text-color-muted transition-colors hover:bg-surface-hover hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", !collapsed && !sidebarFooter && "ml-auto")}
+                >
+                  {collapsed ? <ChevronsRight className="size-4" strokeWidth={1.5} aria-hidden /> : <ChevronsLeft className="size-4" strokeWidth={1.5} aria-hidden />}
+                </button>
+              </TooltipTrigger>
+              <TooltipContent side="right" className="text-xs">
+                {collapsed ? "Expand" : "Collapse"} <Kbd className="ml-1">⌘B</Kbd>
+              </TooltipContent>
+            </Tooltip>
+          </div>
+        </aside>
+
+        <Sheet open={mobileOpen} onOpenChange={setMobileOpen}>
+          <SheetContent side="left" hideCloseButton className="w-72 gap-0 bg-sidebar p-0 sm:max-w-72">
+            <SheetTitle className="sr-only">Navigation</SheetTitle>
+            <SheetDescription className="sr-only">Screens of this app</SheetDescription>
+            <div className="flex h-full flex-col">
+              {brand}
+              <SidebarNav pathname={pathname} collapsed={false} onNavigate={() => setMobileOpen(false)} />
+              {sidebarFooter ? <div className="border-t border-sidebar-border p-2">{sidebarFooter}</div> : null}
+            </div>
+          </SheetContent>
+        </Sheet>
+
+        <div className="flex min-w-0 flex-1 flex-col">
+          <header className="flex h-14 shrink-0 items-center gap-2 border-b border-border bg-background px-3 sm:px-4">
+            <button
+              type="button"
+              onClick={() => setMobileOpen(true)}
+              aria-label="Open navigation"
+              className="inline-flex size-8 items-center justify-center rounded-md text-text-color-muted hover:bg-surface-hover hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring md:hidden"
+            >
+              <Menu className="size-4" strokeWidth={1.5} aria-hidden />
+            </button>
+            <nav aria-label="Breadcrumb" className="flex min-w-0 items-center gap-1.5 text-sm">
+              <span className="hidden truncate font-medium text-foreground sm:inline">{{{titleJson}}}</span>
+              {current ? (
+                <>
+                  <span aria-hidden className="hidden text-text-color-muted/60 sm:inline">/</span>
+                  {current.group ? (
+                    <>
+                      <span className="hidden truncate text-text-color-muted lg:inline">{current.group}</span>
+                      <span aria-hidden className="hidden text-text-color-muted/60 lg:inline">/</span>
+                    </>
+                  ) : null}
+                  <span aria-current="page" className="truncate font-medium text-foreground sm:font-normal sm:text-text-color-muted">{current.label}</span>
+                </>
+              ) : null}
+            </nav>
+            <div className="ml-auto flex shrink-0 items-center gap-1.5">
+              <button
+                type="button"
+                onClick={() => setJumpOpen(true)}
+                aria-label="Jump to a screen"
+                aria-keyshortcuts="Meta+K Control+K"
+                className="inline-flex h-8 items-center gap-2 rounded-md border border-border bg-background px-2.5 text-sm text-text-color-muted transition-colors hover:bg-surface-hover hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
-                {item.label}
-              </Link>
-            );
-          })}
-        </nav>
-      </aside>
-      <main className="min-w-0 flex-1 p-6">{children}</main>
-    </div>
+                <Search className="size-4" strokeWidth={1.5} aria-hidden />
+                <span className="hidden md:inline">Jump to</span>
+                <Kbd className="hidden md:inline-flex">⌘K</Kbd>
+              </button>
+              {status === undefined ? <ConnectionStatus /> : status}
+              {headerSlot}
+              <ThemeToggle />
+            </div>
+          </header>
+          <main id="main" className={cn("min-h-0 min-w-0 flex-1 overflow-y-auto", contentPadding && "p-6")}>
+            {children}
+          </main>
+        </div>
+      </div>
+      <QuickJump items={items} open={jumpOpen} onOpenChange={setJumpOpen} />
+    </TooltipProvider>
   );
 }

package/templates/next-app/components/shell/connection-status.tsx.tmpl

@@ -0,0 +1,109 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { KeyRound } from "lucide-react";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, cn } from "@graph8/sdk/ui";
+
+export type State =
+  | { kind: "checking" }
+  | { kind: "ok"; who: string }
+  | { kind: "setup"; message: string }
+  | { kind: "hidden"; message: string }
+  | { kind: "down"; message: string };
+
+const PATH = "/api/g8/me";
+
+function describe(data: unknown): string {
+  const d = (data ?? {}) as Record<string, unknown>;
+  const org = (d.organization as Record<string, unknown> | undefined)?.name ?? d.org_name ?? d.organization_name;
+  const name = d.name ?? d.key_name ?? d.label;
+  return [name, org].filter((x): x is string => typeof x === "string" && x.length > 0).join(" at ") || "graph8";
+}
+
+function messageOf(body: Record<string, unknown>, status: number): string {
+  const raw = body.message ?? body.detail ?? body.error;
+  if (typeof raw === "string" && raw) return raw;
+  if (raw && typeof raw === "object") {
+    const nested = (raw as Record<string, unknown>).message;
+    if (typeof nested === "string" && nested) return nested;
+  }
+  return `HTTP ${status}`;
+}
+
+/**
+ * Map the `/api/g8/me` answer to a state. Only the proxy's own refusals (identified by their `error`
+ * code, not the status, because graph8's 401/403/500 pass through unchanged) are setup hints.
+ */
+export function connectionStateFor(status: number, body: Record<string, unknown>): Exclude<State, { kind: "checking" }> {
+  if (status >= 200 && status < 300) return { kind: "ok", who: describe(body.data ?? body) };
+  const message = messageOf(body, status);
+  if (body.error === "g8_proxy_misconfigured") return { kind: "setup", message };
+  if (body.error === "path_not_allowed") {
+    return { kind: "hidden", message: 'The proxy runs, but "me" is not in allowedPrefixes (app/api/g8/[...path]/route.ts): add it to show the connected key here.' };
+  }
+  if (status === 401 || status === 403) {
+    return { kind: "down", message: `${message} (HTTP ${status}: graph8 or your authorize hook refused it; check the server's graph8 API key and your session.)` };
+  }
+  return { kind: "down", message };
+}
+
+/**
+ * Shows whether this app reaches graph8 through its own proxy route (`/api/g8/me`), without ever
+ * holding the key in the browser. The proxy passes graph8's status codes straight through, so only the
+ * proxy's OWN refusals (tagged by their `error` code) count as setup steps:
+ *   - setup (warning): the proxy refuses to run (`g8_proxy_misconfigured`: no G8_API_KEY, no `authorize`,
+ *     no `allowedPrefixes`): fix route.ts
+ *   - hidden (warning): the proxy runs but "me" is not an allowed prefix (`path_not_allowed`): add it to
+ *     show who the key belongs to. Unknown is a warning, never green.
+ *   - ok (green): connected, the tooltip names the key and the workspace
+ *   - down (red): anything else (graph8 401/403/5xx, your `authorize` hook refusing, unreachable), with
+ *     the message, so the developer sees the real cause
+ * Replace or remove it from app-shell.tsx once your own session UI is in place.
+ */
+export function ConnectionStatus({ className }: { className?: string }) {
+  const [state, setState] = useState<State>({ kind: "checking" });
+
+  const check = useCallback(async () => {
+    setState({ kind: "checking" });
+    try {
+      const res = await fetch(PATH, { headers: { accept: "application/json" }, cache: "no-store" });
+      const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+      setState(connectionStateFor(res.status, body));
+    } catch {
+      setState({ kind: "down", message: "Could not reach this app's /api/g8 route." });
+    }
+  }, []);
+
+  useEffect(() => {
+    void check();
+  }, [check]);
+
+  const label = state.kind === "ok" ? "Connected" : state.kind === "checking" ? "Checking" : state.kind === "hidden" ? "Proxy ready" : state.kind === "setup" ? "Set up the proxy" : "Not connected";
+  const dot = state.kind === "ok" ? "bg-positive-foreground" : state.kind === "checking" ? "bg-text-color-muted" : state.kind === "setup" || state.kind === "hidden" ? "bg-warning-foreground" : "bg-error-foreground";
+  const detail = state.kind === "ok" ? state.who : state.kind === "checking" ? "Asking graph8 who this key belongs to." : state.message;
+
+  return (
+    <TooltipProvider delayDuration={150}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <button
+            type="button"
+            onClick={() => void check()}
+            aria-label={`graph8: ${label}. ${detail}`}
+            className={cn(
+              "inline-flex h-8 items-center gap-2 rounded-md border border-border bg-background px-2.5 text-xs text-foreground transition-colors hover:bg-surface-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              className,
+            )}
+          >
+            <KeyRound className="size-3.5 text-text-color-muted" strokeWidth={1.5} aria-hidden />
+            <span aria-hidden className={cn("size-1.5 rounded-full", dot)} />
+            <span className="hidden sm:inline">{label}</span>
+          </button>
+        </TooltipTrigger>
+        <TooltipContent side="bottom" align="end" className="max-w-xs text-xs">
+          {detail}
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}

package/templates/next-app/components/shell/nav-model.ts.tmpl

@@ -0,0 +1,65 @@
+import type { LucideIcon } from "lucide-react";
+
+/**
+ * The sidebar's view of `lib/nav.ts`. `icon`, `group` and `description` are optional: a nav generated
+ * without them still renders (letter glyphs, one unlabelled section). Edit freely.
+ */
+export interface NavEntry {
+  label: string;
+  path: string;
+  icon?: LucideIcon;
+  group?: string;
+  description?: string;
+}
+
+export interface NavGroup {
+  /** null for the unlabelled top section (entries without a group). */
+  label: string | null;
+  items: NavEntry[];
+}
+
+/** Groups in first-seen order; ungrouped entries come first, in one unlabelled section. */
+export function groupNav(items: readonly NavEntry[]): NavGroup[] {
+  const groups: NavGroup[] = [];
+  for (const item of items) {
+    const label = item.group?.trim() || null;
+    let group = groups.find((g) => g.label === label);
+    if (!group) {
+      group = { label, items: [] };
+      groups.push(group);
+    }
+    group.items.push(item);
+  }
+  return [...groups.filter((g) => g.label === null), ...groups.filter((g) => g.label !== null)];
+}
+
+/** `/contacts` is active on `/contacts` and `/contacts/42`; `/` only on `/`. */
+export function isActivePath(itemPath: string, pathname: string | null): boolean {
+  if (!pathname) return false;
+  if (itemPath === "/") return pathname === "/";
+  return pathname === itemPath || pathname.startsWith(`${itemPath}/`);
+}
+
+/** The nav entry for the current URL (the longest matching path wins). */
+export function currentNavEntry(items: readonly NavEntry[], pathname: string | null): NavEntry | undefined {
+  return [...items].filter((i) => isActivePath(i.path, pathname)).sort((a, b) => b.path.length - a.path.length)[0];
+}
+
+/** Case-insensitive match on label, group and description, for the quick-jump palette. */
+export function matchesNav(item: NavEntry, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (!q) return true;
+  return [item.label, item.group ?? "", item.description ?? "", item.path].some((s) => s.toLowerCase().includes(q));
+}
+
+/** True when a key event comes from a text field, so app shortcuts (Cmd/Ctrl+B is bold there) leave it alone. */
+export function isEditableTarget(target: EventTarget | null): boolean {
+  const el = target as (HTMLElement & { isContentEditable?: boolean }) | null;
+  if (!el || typeof el.tagName !== "string") return false;
+  if (el.isContentEditable || el.closest?.("[contenteditable=''],[contenteditable='true'],[contenteditable='plaintext-only']")) return true;
+  const tag = el.tagName.toLowerCase();
+  if (tag === "textarea" || tag === "select") return true;
+  if (tag !== "input") return false;
+  const type = ((el as HTMLInputElement).type || "text").toLowerCase();
+  return !["button", "checkbox", "radio", "range", "color", "file", "image", "reset", "submit"].includes(type);
+}

package/templates/next-app/components/shell/quick-jump.tsx.tmpl

@@ -0,0 +1,131 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useRouter } from "next/navigation";
+import { ArrowRight, Search } from "lucide-react";
+import { Dialog, DialogContent, DialogDescription, DialogTitle, Kbd, cn } from "@graph8/sdk/ui";
+import { groupNav, matchesNav, type NavEntry } from "./nav-model";
+
+/**
+ * Quick jump (Cmd/Ctrl+K): type to filter the screens, arrows to move, Enter to go. No extra
+ * dependency: a Dialog, an input and a list. Add your own entries (records, actions) to `extra`.
+ */
+export function QuickJump({ items, open, onOpenChange, extra = [] }: { items: readonly NavEntry[]; open: boolean; onOpenChange: (open: boolean) => void; extra?: readonly NavEntry[] }) {
+  const router = useRouter();
+  const [query, setQuery] = useState("");
+  const [cursor, setCursor] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLUListElement>(null);
+
+  const results = useMemo(() => {
+    const all = [...items, ...extra].filter((i) => matchesNav(i, query));
+    return groupNav(all).flatMap((g) => g.items.map((item) => ({ item, group: g.label })));
+  }, [items, extra, query]);
+
+  useEffect(() => {
+    if (open) {
+      setQuery("");
+      setCursor(0);
+    }
+  }, [open]);
+
+  useEffect(() => {
+    setCursor((c) => Math.min(c, Math.max(results.length - 1, 0)));
+  }, [results.length]);
+
+  useEffect(() => {
+    const el = listRef.current?.querySelector<HTMLElement>(`[data-index="${cursor}"]`);
+    el?.scrollIntoView({ block: "nearest" });
+  }, [cursor]);
+
+  const go = (item: NavEntry | undefined) => {
+    if (!item) return;
+    onOpenChange(false);
+    router.push(item.path);
+  };
+
+  const listboxId = "g8-quick-jump-results";
+  const activeId = results[cursor] ? `g8-quick-jump-${cursor}` : undefined;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        showCloseButton={false}
+        className="top-[18%] max-w-lg translate-y-0 gap-0 overflow-hidden rounded-xl border border-border bg-popover p-0 shadow-xl sm:max-w-lg"
+        onOpenAutoFocus={(e) => {
+          e.preventDefault();
+          inputRef.current?.focus();
+        }}
+      >
+        <DialogTitle className="sr-only">Jump to a screen</DialogTitle>
+        <DialogDescription className="sr-only">Type to filter, use the arrow keys, press Enter to open.</DialogDescription>
+        <div className="flex items-center gap-2 border-b border-border px-3">
+          <Search className="size-4 shrink-0 text-text-color-muted" strokeWidth={1.5} aria-hidden />
+          <input
+            ref={inputRef}
+            role="combobox"
+            aria-expanded="true"
+            aria-controls={listboxId}
+            aria-activedescendant={activeId}
+            aria-label="Jump to a screen"
+            autoComplete="off"
+            spellCheck={false}
+            value={query}
+            placeholder="Jump to a screen"
+            onChange={(e) => {
+              setQuery(e.target.value);
+              setCursor(0);
+            }}
+            onKeyDown={(e) => {
+              if (e.key === "ArrowDown") {
+                e.preventDefault();
+                setCursor((c) => (results.length ? (c + 1) % results.length : 0));
+              } else if (e.key === "ArrowUp") {
+                e.preventDefault();
+                setCursor((c) => (results.length ? (c - 1 + results.length) % results.length : 0));
+              } else if (e.key === "Enter") {
+                e.preventDefault();
+                go(results[cursor]?.item);
+              }
+            }}
+            className="h-12 w-full min-w-0 bg-transparent text-sm text-foreground outline-none placeholder:text-text-color-muted"
+          />
+          <Kbd>esc</Kbd>
+        </div>
+        <ul ref={listRef} id={listboxId} role="listbox" aria-label="Screens" className="max-h-80 overflow-y-auto p-1.5">
+          {results.length === 0 ? (
+            <li className="px-3 py-8 text-center text-sm text-text-color-muted">No screen matches "{query}".</li>
+          ) : (
+            results.map(({ item, group }, index) => {
+              const Icon = item.icon;
+              const active = index === cursor;
+              return (
+                <li
+                  key={`${index}:${item.path}`}
+                  id={`g8-quick-jump-${index}`}
+                  data-index={index}
+                  role="option"
+                  aria-selected={active}
+                  onMouseEnter={() => setCursor(index)}
+                  onMouseDown={(e) => e.preventDefault()}
+                  onClick={() => go(item)}
+                  className={cn("flex h-9 cursor-pointer items-center gap-2.5 rounded-md px-2.5 text-sm", active ? "bg-surface-selected text-foreground" : "text-foreground")}
+                >
+                  <span className="flex size-5 shrink-0 items-center justify-center text-text-color-muted">
+                    {Icon ? <Icon className="size-4" strokeWidth={1.5} aria-hidden /> : <span className="text-[10px] font-medium uppercase">{item.label.charAt(0)}</span>}
+                  </span>
+                  <span className="min-w-0 flex-1 truncate">
+                    {item.label}
+                    {item.description ? <span className="ml-2 text-xs text-text-color-muted">{item.description}</span> : null}
+                  </span>
+                  {group ? <span className="shrink-0 text-xs text-text-color-muted">{group}</span> : null}
+                  {active ? <ArrowRight className="size-3.5 shrink-0 text-text-color-muted" strokeWidth={1.5} aria-hidden /> : null}
+                </li>
+              );
+            })
+          )}
+        </ul>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/templates/next-app/components/shell/theme-toggle.tsx.tmpl

@@ -0,0 +1,40 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Moon, Sun } from "lucide-react";
+import { cn } from "@graph8/sdk/ui";
+
+const KEY = "g8.theme";
+
+/** Light or dark, remembered in localStorage and applied as the `dark` class on <html> (see app/layout.tsx). */
+export function ThemeToggle({ className }: { className?: string }) {
+  const [dark, setDark] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    setDark(document.documentElement.classList.contains("dark"));
+  }, []);
+
+  const toggle = () => {
+    const next = !document.documentElement.classList.contains("dark");
+    document.documentElement.classList.toggle("dark", next);
+    try {
+      localStorage.setItem(KEY, next ? "dark" : "light");
+    } catch {
+      // Private mode: the choice lasts for this page only.
+    }
+    setDark(next);
+  };
+
+  const Icon = dark ? Sun : Moon;
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      aria-label={dark ? "Switch to light mode" : "Switch to dark mode"}
+      aria-pressed={dark ?? false}
+      className={cn("inline-flex size-8 items-center justify-center rounded-md text-text-color-muted transition-colors hover:bg-surface-hover hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", className)}
+    >
+      <Icon className="size-4" strokeWidth={1.5} aria-hidden />
+    </button>
+  );
+}

package/templates/next-app/lib/nav.ts.tmpl

@@ -1,2 +1,2 @@
 // Generated by `graph8-sdk create {{stackId}}`. One entry per screen; edit freely.
-export const nav: { label: string; path: string }[] = {{navJson}};
+{{navImports}}export const nav: {{navType}} = {{navJson}};