From df57b54bdece6183b4c2244fc1a5921eb011cbce Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Sat, 12 Sep 2026 21:04:02 -0700
Subject: [PATCH] Breadcrumbs on every page, and a sidebar that unfolds to
 where you are (#170)

Anthony: "this needs a cookie crumb navbar, all pages need this with the
new IA" and "broad and drill down, I'm not seeing that in the sidebar".

lib/crumbs.ts derives the trail from the path and the spec registry, so
no page declares it: /openthreat is Home > Specs > Catalogs a site serves
about itself > OpenThreat, /opencpu adds OpenServer before OpenCPU,
/docs/openthreat ends in Specification, /docs/cli is Home > Docs > CLI,
a blog post passes its title as the leaf. components/breadcrumbs.tsx
renders it (server-rendered, with a BreadcrumbList JSON-LD) at the top
of every SiteShell page; the SPA routes rendered by page-markup.ts get
the same trail as a string.

components/side-nav.tsx replaces the flat sidebar: the four groups stay,
and under Specs the family the current page belongs to unfolds to its
specs, and the spec to its blocks, marked active. The home page string
marks the active entry for the SPA routes too.


Claude-Session: https://claude.ai/code/session_014cmNRtR2vL1p89dbVQ7FZJ

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../logicsrc-web/src/app/[[...slug]]/page.tsx |  2 +-
 .../logicsrc-web/src/app/blog/[slug]/page.tsx |  2 +-
 .../logicsrc-web/src/app/docs/[slug]/page.tsx |  2 +-
 .../src/components/breadcrumbs.tsx            | 46 +++++++++
 apps/logicsrc-web/src/components/side-nav.tsx | 89 +++++++++++++++++
 .../src/components/site-shell.tsx             | 39 +++-----
 apps/logicsrc-web/src/lib/crumbs.ts           | 99 +++++++++++++++++++
 apps/logicsrc-web/src/lib/page-markup.ts      |  6 +-
 apps/logicsrc-web/src/styles.css              | 57 +++++++++++
 9 files changed, 310 insertions(+), 32 deletions(-)
 create mode 100644 apps/logicsrc-web/src/components/breadcrumbs.tsx
 create mode 100644 apps/logicsrc-web/src/components/side-nav.tsx
 create mode 100644 apps/logicsrc-web/src/lib/crumbs.ts

diff --git a/apps/logicsrc-web/src/app/[[...slug]]/page.tsx b/apps/logicsrc-web/src/app/[[...slug]]/page.tsx
index 21161e3..4797bd4 100644
--- a/apps/logicsrc-web/src/app/[[...slug]]/page.tsx
+++ b/apps/logicsrc-web/src/app/[[...slug]]/page.tsx
@@ -70,7 +70,7 @@ export default async function Page({
 
   return (
     <>
-      <div id="app" dangerouslySetInnerHTML={{ __html: renderPageMarkup() }} />
+      <div id="app" dangerouslySetInnerHTML={{ __html: renderPageMarkup(slug?.[0] ? `/${slug[0]}` : "/") }} />
       <HomeInteractivity />
     </>
   );
diff --git a/apps/logicsrc-web/src/app/blog/[slug]/page.tsx b/apps/logicsrc-web/src/app/blog/[slug]/page.tsx
index 16e2858..8284fc6 100644
--- a/apps/logicsrc-web/src/app/blog/[slug]/page.tsx
+++ b/apps/logicsrc-web/src/app/blog/[slug]/page.tsx
@@ -117,7 +117,7 @@ export default async function BlogPostPage({
   const html = sanitizeRenderedHtml(post.html);
 
   return (
-    <SiteShell active="Blog">
+    <SiteShell active="Blog" crumbTitle={post.title}>
       <script
         type="application/ld+json"
         dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
diff --git a/apps/logicsrc-web/src/app/docs/[slug]/page.tsx b/apps/logicsrc-web/src/app/docs/[slug]/page.tsx
index 42f1d05..6b0d76a 100644
--- a/apps/logicsrc-web/src/app/docs/[slug]/page.tsx
+++ b/apps/logicsrc-web/src/app/docs/[slug]/page.tsx
@@ -42,7 +42,7 @@ export default async function DocPage({
   const html = sanitizeRenderedHtml(rawHtml);
 
   return (
-    <SiteShell active="Docs">
+    <SiteShell active="Docs" crumbTitle={docTitle(md, slug)}>
       <article className="band" style={{ maxWidth: "48rem" }}>
         <p style={{ marginBottom: "1.5rem" }}>
           <Link href="/docs" style={{ color: "#5b6b7a", textDecoration: "none" }}>
diff --git a/apps/logicsrc-web/src/components/breadcrumbs.tsx b/apps/logicsrc-web/src/components/breadcrumbs.tsx
new file mode 100644
index 0000000..c3b8356
--- /dev/null
+++ b/apps/logicsrc-web/src/components/breadcrumbs.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import type { ReactNode } from "react";
+import { crumbsFor } from "@/lib/crumbs";
+
+/**
+ * The trail at the top of every page, derived from the path and the spec
+ * registry. Rendered on the server too (usePathname works during SSR), so the
+ * HTML carries it, plus a BreadcrumbList for search engines.
+ */
+export function Breadcrumbs({ leaf }: { leaf?: string }): ReactNode {
+  const pathname = usePathname() ?? "/";
+  const crumbs = crumbsFor(pathname, leaf);
+  if (crumbs.length === 0) return null;
+  const site = "https://logicsrc.com";
+  const jsonLd = {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: crumbs.map((c, i) => ({
+      "@type": "ListItem",
+      position: i + 1,
+      name: c.label,
+      item: `${site}${c.href}`
+    }))
+  };
+  return (
+    <nav className="crumbs" aria-label="Breadcrumb">
+      <ol>
+        {crumbs.map((c, i) => {
+          const last = i === crumbs.length - 1;
+          return (
+            <li key={c.href + c.label}>
+              {last ? (
+                <span aria-current="page">{c.label}</span>
+              ) : (
+                <a href={c.href}>{c.label}</a>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+    </nav>
+  );
+}
diff --git a/apps/logicsrc-web/src/components/side-nav.tsx b/apps/logicsrc-web/src/components/side-nav.tsx
new file mode 100644
index 0000000..a528dde
--- /dev/null
+++ b/apps/logicsrc-web/src/components/side-nav.tsx
@@ -0,0 +1,89 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import type { ReactNode } from "react";
+import { NAV_GROUPS } from "@/lib/nav";
+import { FAMILIES, allSpecs, familyOfSpec, familyTree, type Family } from "@/lib/specs";
+
+/**
+ * The sidebar, broad first, drilling down in place. The four groups are
+ * always shown. Under Specs, the family the current page belongs to unfolds
+ * to its specs, and the spec the page belongs to unfolds to its blocks, so
+ * the sidebar shows where you are and what is beside you without leaving the
+ * page. Rendered on the server too, so the unfolded state is in the HTML.
+ */
+function currentFamily(pathname: string): { family?: Family; specSlug?: string } {
+  const parts = pathname.split("/").filter(Boolean);
+  if (parts[0] === "specs" && parts[1]) return { family: FAMILIES.find((f) => f.slug === parts[1]) };
+  const slug =
+    parts[0] === "docs" && parts[1]
+      ? allSpecs().find((x) => x.doc === `/docs/${parts[1]}`)?.slug
+      : allSpecs().find((x) => x.landing === `/${parts[0]}`)?.slug;
+  if (!slug) return {};
+  return { family: familyOfSpec(slug), specSlug: slug };
+}
+
+export function SideNav(): ReactNode {
+  const pathname = usePathname() ?? "/";
+  const { family: open, specSlug } = currentFamily(pathname);
+  const openParent = specSlug ? allSpecs().find((x) => x.slug === specSlug)?.parent ?? specSlug : undefined;
+
+  const isCurrent = (href: string): boolean => href === pathname;
+
+  return (
+    <nav aria-label="LogicSRC sections">
+      {NAV_GROUPS.map((group) => (
+        <div key={group.label} className="nav-group-block">
+          <span className="nav-group">{group.label}</span>
+          {group.items.map((item) => {
+            const family = group.label === "Specs" ? FAMILIES.find((f) => `/specs/${f.slug}` === item.href) : undefined;
+            const unfolded = family && open && family.slug === open.slug;
+            const active = isCurrent(item.href) || (family && open?.slug === family.slug && pathname.startsWith("/specs/"));
+            return (
+              <div key={item.href} className={unfolded ? "nav-branch open" : "nav-branch"}>
+                <a
+                  href={item.href}
+                  className={active ? "active" : undefined}
+                  aria-current={isCurrent(item.href) ? "page" : undefined}
+                  target={item.external ? "_blank" : undefined}
+                  rel={item.external ? "noreferrer" : undefined}
+                >
+                  {item.label}
+                </a>
+                {unfolded ? (
+                  <div className="nav-children">
+                    {familyTree(family).map(({ spec, children }) => {
+                      const href = spec.landing ?? spec.doc ?? "/specs";
+                      const here = spec.slug === specSlug || children.some((c) => c.slug === specSlug);
+                      return (
+                        <div key={spec.slug}>
+                          <a href={href} className={spec.slug === specSlug ? "active" : undefined} aria-current={spec.slug === specSlug ? "page" : undefined}>
+                            {spec.name}
+                          </a>
+                          {children.length > 0 && (here || openParent === spec.slug) ? (
+                            <div className="nav-children">
+                              {children.map((c) => (
+                                <a
+                                  key={c.slug}
+                                  href={c.landing ?? c.doc ?? href}
+                                  className={c.slug === specSlug ? "active" : undefined}
+                                  aria-current={c.slug === specSlug ? "page" : undefined}
+                                >
+                                  {c.name}
+                                </a>
+                              ))}
+                            </div>
+                          ) : null}
+                        </div>
+                      );
+                    })}
+                  </div>
+                ) : null}
+              </div>
+            );
+          })}
+        </div>
+      ))}
+    </nav>
+  );
+}
diff --git a/apps/logicsrc-web/src/components/site-shell.tsx b/apps/logicsrc-web/src/components/site-shell.tsx
index 4c14a24..d1aafdf 100644
--- a/apps/logicsrc-web/src/components/site-shell.tsx
+++ b/apps/logicsrc-web/src/components/site-shell.tsx
@@ -1,18 +1,23 @@
 import type { ReactNode } from "react";
 import { renderInstallCommand } from "@/lib/install-command";
-import { NAV_GROUPS } from "@/lib/nav";
+import { Breadcrumbs } from "@/components/breadcrumbs";
+import { SideNav } from "@/components/side-nav";
 
 /**
- * The site chrome for every standalone route. The sidebar comes from
- * lib/nav.ts, the same array the home page renders, so the two cannot drift.
- * `active` is a label or an href; either marks the current entry.
+ * The site chrome for every standalone route: the sidebar that unfolds to
+ * where you are (components/side-nav.tsx), and the breadcrumb trail at the
+ * top of the page (components/breadcrumbs.tsx), both derived from the spec
+ * registry and the path. `crumbTitle` names the last crumb when the
+ * registry cannot, such as a blog post's title. `active` is kept for
+ * callers that still pass it and is no longer needed.
  */
 export function SiteShell({
   children,
-  active,
+  crumbTitle,
 }: {
   children: ReactNode;
   active?: string;
+  crumbTitle?: string;
 }): ReactNode {
   return (
     <main className="shell">
@@ -27,30 +32,10 @@ export function SiteShell({
         {/* Same markup the homepage uses, so the two can never drift apart.
             Static content from a module constant -- nothing user-supplied. */}
         <div dangerouslySetInnerHTML={{ __html: renderInstallCommand("rail") }} />
-        <nav aria-label="LogicSRC sections">
-          {NAV_GROUPS.map((group) => (
-            <div key={group.label} className="nav-group-block">
-              <span className="nav-group">{group.label}</span>
-              {group.items.map((item) => {
-                const isActive = item.label === active || item.href === active;
-                return (
-                  <a
-                    key={item.href}
-                    href={item.href}
-                    className={isActive ? "active" : undefined}
-                    aria-current={isActive ? "page" : undefined}
-                    target={item.external ? "_blank" : undefined}
-                    rel={item.external ? "noreferrer" : undefined}
-                  >
-                    {item.label}
-                  </a>
-                );
-              })}
-            </div>
-          ))}
-        </nav>
+        <SideNav />
       </aside>
       <section className="workspace">
+        <Breadcrumbs leaf={crumbTitle} />
         {children}
         <footer
           style={{
diff --git a/apps/logicsrc-web/src/lib/crumbs.ts b/apps/logicsrc-web/src/lib/crumbs.ts
new file mode 100644
index 0000000..2b4aa4b
--- /dev/null
+++ b/apps/logicsrc-web/src/lib/crumbs.ts
@@ -0,0 +1,99 @@
+import { NAV_GROUPS } from "./nav";
+import { FAMILIES, GUIDES, allSpecs, familyOfSpec, type Spec } from "./specs";
+
+/**
+ * Breadcrumbs for any path, derived from the registry so no page declares
+ * them by hand. The trail follows the site's architecture, broad to narrow:
+ *
+ *   /specs/catalogs      Home › Specs › Catalogs a site serves about itself
+ *   /openthreat          Home › Specs › Catalogs … › OpenThreat
+ *   /opencpu             Home › Specs › Catalogs … › OpenServer › OpenCPU
+ *   /docs/openthreat     Home › Specs › Catalogs … › OpenThreat › Specification
+ *   /docs/cli            Home › Docs › CLI
+ *   /blog/<slug>         Home › Blog › <leaf, supplied by the page>
+ *
+ * `leaf` lets a page name the last crumb when the registry cannot (a blog
+ * post's title). The home page has no trail.
+ */
+export type Crumb = { href: string; label: string };
+
+const HOME: Crumb = { href: "/", label: "Home" };
+
+function specTrail(spec: Spec): Crumb[] {
+  const family = familyOfSpec(spec.slug);
+  const trail: Crumb[] = [HOME, { href: "/specs", label: "Specs" }];
+  if (family) trail.push({ href: `/specs/${family.slug}`, label: family.name });
+  if (spec.parent) {
+    const parent = allSpecs().find((x) => x.slug === spec.parent);
+    if (parent) trail.push({ href: parent.landing ?? parent.doc ?? "/specs", label: parent.name });
+  }
+  trail.push({ href: spec.landing ?? spec.doc ?? "/specs", label: spec.name });
+  return trail;
+}
+
+function navLabel(path: string): string | null {
+  for (const g of NAV_GROUPS) for (const i of g.items) if (i.href === path) return i.label;
+  return null;
+}
+
+function pretty(segment: string): string {
+  return segment.replace(/[-_]+/g, " ").replace(/^\w/, (c) => c.toUpperCase());
+}
+
+export function crumbsFor(pathname: string, leaf?: string): Crumb[] {
+  const path = pathname.replace(/\/+$/, "") || "/";
+  if (path === "/") return [];
+  const parts = path.split("/").filter(Boolean);
+
+  // /specs and /specs/<family>
+  if (parts[0] === "specs") {
+    const trail: Crumb[] = [HOME, { href: "/specs", label: "Specs" }];
+    const family = parts[1] ? FAMILIES.find((f) => f.slug === parts[1]) : undefined;
+    if (family) trail.push({ href: `/specs/${family.slug}`, label: family.name });
+    return trail;
+  }
+
+  // /docs and /docs/<slug>
+  if (parts[0] === "docs") {
+    if (!parts[1]) return [HOME, { href: "/docs", label: "Docs" }];
+    const spec = allSpecs().find((x) => x.doc === `/docs/${parts[1]}`);
+    if (spec) {
+      const trail = specTrail(spec);
+      // A spec with no landing page: its doc IS the spec crumb already.
+      if (spec.landing) trail.push({ href: `/docs/${parts[1]}`, label: "Specification" });
+      return trail;
+    }
+    const guide = GUIDES.find((g) => g.slug === parts[1]);
+    return [HOME, { href: "/docs", label: "Docs" }, { href: path, label: leaf ?? guide?.name ?? pretty(parts[1]) }];
+  }
+
+  // /<slug> for a spec landing page (one segment), including /openontology/explore under it.
+  const spec = allSpecs().find((x) => x.landing === `/${parts[0]}`);
+  if (spec) {
+    const trail = specTrail(spec);
+    if (parts[1]) trail.push({ href: path, label: leaf ?? pretty(parts[1]) });
+    return trail;
+  }
+
+  // Everything else: Home › <section> [› leaf]
+  const trail: Crumb[] = [HOME];
+  const first = `/${parts[0]}`;
+  trail.push({ href: first, label: navLabel(first) ?? pretty(parts[0]) });
+  if (parts.length > 1) trail.push({ href: path, label: leaf ?? pretty(parts[parts.length - 1]) });
+  else if (leaf && leaf !== trail[trail.length - 1].label) trail[trail.length - 1] = { href: path, label: leaf };
+  return trail;
+}
+
+/** The trail as HTML, for the server-string home template's non-root routes. */
+export function renderCrumbsHtml(pathname: string): string {
+  const crumbs = crumbsFor(pathname);
+  if (crumbs.length === 0) return "";
+  const items = crumbs
+    .map((c, i) =>
+      i === crumbs.length - 1
+        ? `<li><span aria-current="page">${c.label}</span></li>`
+        : `<li><a href="${c.href}">${c.label}</a></li>`
+    )
+    .join("");
+  return `<nav class="crumbs" aria-label="Breadcrumb"><ol>${items}</ol></nav>`;
+}
diff --git a/apps/logicsrc-web/src/lib/page-markup.ts b/apps/logicsrc-web/src/lib/page-markup.ts
index b36fba9..6272463 100644
--- a/apps/logicsrc-web/src/lib/page-markup.ts
+++ b/apps/logicsrc-web/src/lib/page-markup.ts
@@ -5,6 +5,7 @@
 // the `home-interactivity` client component.
 import { renderInstallCommand } from "./install-command";
 import { renderNavHtml } from "./nav";
+import { renderCrumbsHtml } from "./crumbs";
 import { FAMILIES, familyTree } from "./specs";
 
 const schemas = [
@@ -110,7 +111,7 @@ const comparisonRows = [
   }
 ];
 
-export function renderPageMarkup(): string {
+export function renderPageMarkup(path = "/"): string {
   return `
   <main class="shell">
     <aside class="rail">
@@ -122,9 +123,10 @@ export function renderPageMarkup(): string {
         </div>
       </div>
       ${renderInstallCommand("rail")}
-      <nav aria-label="LogicSRC sections">${renderNavHtml("/")}</nav>
+      <nav aria-label="LogicSRC sections">${renderNavHtml(path)}</nav>
     </aside>
     <section class="workspace">
+      ${renderCrumbsHtml(path)}
       <header id="overview" class="hero">
         <div>
           <p class="eyebrow">Profullstack open spec project</p>
diff --git a/apps/logicsrc-web/src/styles.css b/apps/logicsrc-web/src/styles.css
index 59dcf2f..9d62ab5 100644
--- a/apps/logicsrc-web/src/styles.css
+++ b/apps/logicsrc-web/src/styles.css
@@ -926,3 +926,60 @@ pre {
   margin: 1rem 0 0;
   font-size: 0.95rem;
 }
+
+/* Sidebar drill-down: the current family unfolds to its specs, a spec to its blocks. */
+.rail nav .nav-branch {
+  display: contents;
+}
+.rail nav .nav-children {
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  margin: 0.2rem 0 0.35rem 0.6rem;
+  padding-left: 0.6rem;
+  border-left: 1px solid #263039;
+}
+.rail nav .nav-children a {
+  min-height: 1.9rem;
+  padding: 0.3rem 0.6rem;
+  font-size: 0.85rem;
+  border-color: transparent;
+}
+.rail nav .nav-children a.active,
+.rail nav .nav-children a:hover {
+  border-color: #3f5049;
+}
+
+/* Breadcrumb trail at the top of every page but the home page. */
+.crumbs {
+  width: 100%;
+  max-width: 72rem;
+  margin: 0 auto 0.75rem;
+  font-size: 0.88rem;
+  color: #5b6b7a;
+}
+.crumbs ol {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+  list-style: none;
+  margin: 0;
+  padding: 0.35rem 0 0.75rem;
+  border-bottom: 1px solid #e3e6e0;
+}
+.crumbs li + li::before {
+  content: "›";
+  margin-right: 0.35rem;
+  color: #9aa6b1;
+}
+.crumbs a {
+  color: inherit;
+  text-decoration: none;
+}
+.crumbs a:hover {
+  text-decoration: underline;
+}
+.crumbs [aria-current="page"] {
+  color: #101418;
+  font-weight: 600;
+}