@dogsbay/docs-layout 0.2.0-beta.14 → 0.2.0-beta.140

package/src/DocsLayout.astro

@@ -31,9 +31,12 @@ import SidebarMenuItem from "@dogsbay/ui/sidebar/SidebarMenuItem.astro";
 import SidebarMenuButton from "@dogsbay/ui/sidebar/SidebarMenuButton.astro";
 import SidebarSeparator from "@dogsbay/ui/sidebar/SidebarSeparator.astro";
 import SidebarNavTree from "@dogsbay/ui/sidebar/SidebarNavTree.astro";
+import DocsNavClient from "./DocsNavClient.astro";
 import Separator from "@dogsbay/ui/separator/Separator.astro";
 import ThemeToggle from "@dogsbay/ui/theme-toggle/ThemeToggle.astro";
 import DocsToc from "./DocsToc.astro";
+import { resolveTocPlacement, hasDisplayableToc, type TocMode } from "./toc-placement.js";
+import { linkIconAttrs } from "./link-icons.js";
 import DocsFooter from "./DocsFooter.astro";
 import SearchDialog from "./SearchDialog.astro";
 import TagList from "./TagList.astro";
@@ -42,9 +45,9 @@ import TypeBadge from "./TypeBadge.astro";
 import PageActions from "./PageActions.astro";
 import VersionSwitcher from "./VersionSwitcher.astro";
 import LocaleSwitcher from "./LocaleSwitcher.astro";
-import { filterNavByAxis } from "./nav-filter.js";
+import { filterNavByAxis, rootVersionFilter } from "./nav-filter.js";
 import type { LlmProviderName } from "./llm-actions.js";
-import { jsonLdTypeFor, normalizeCustomJsonLd } from "./json-ld.js";
+import { jsonLdTypeFor, normalizeCustomJsonLd, buildArticleJsonLd, buildWebSiteJsonLd } from "./json-ld.js";
 import { resolveTagKeywords } from "./tag-list-data.js";
 
 interface NavItem {
@@ -86,6 +89,8 @@ type TagPaletteName =
 interface Props {
   /** Site name shown in header and sidebar logo */
   siteName: string;
+  /** The line under the site name in the sidebar header (`site.tagline`). Default "Documentation". */
+  siteTagline?: string;
   /** Page title for <title> tag */
   title: string;
   /** Home URL — also used as the base for the canonical link if absolute */
@@ -112,7 +117,13 @@ interface Props {
   siteDescription?: string;
   /** Copyright text (HTML allowed) */
   copyright?: string;
-  /** Favicon path (default: "/favicon.ico"). Set to false to disable. */
+  /**
+   * Favicon path. No host-root default — that 404s on subpath
+   * deploys. The format-astro emitter passes a combined-prefix
+   * path (e.g. `/<repo>/favicon.ico`) computed from site.url +
+   * basePath. Pass an empty string or `false` to disable. When
+   * undefined, no `<link rel="icon">` is emitted.
+   */
   favicon?: string | false;
   /** Per-page OG image URL. Overrides defaultOgImage. */
   ogImage?: string;
@@ -122,21 +133,34 @@ interface Props {
   ogType?: "article" | "website";
   /** Canonical URL for this page. Auto-computed from siteUrl + pathname when absolute siteUrl is provided. */
   canonicalUrl?: string;
+  /** `hreflang` alternates for this page's copies in other languages (absolute URLs), written after the canonical link. */
+  alternates?: { hreflang: string; href: string }[];
+  /** JSON-LD `BreadcrumbList` for this page, written after its own JSON-LD block. */
+  breadcrumbJsonLd?: Record<string, unknown>;
   /** Twitter / X handle including the leading "@" */
   twitterHandle?: string;
   /** Theme color hint for browsers (hex string) */
   themeColor?: string;
   /**
-   * Emit `<meta name="robots" content="noindex, nofollow">` when
+   * Emit `noindex` in the `<meta name="robots">` directive when
    * true. Tells external search engines (Google, Bing) to skip
-   * this page. Has NO effect on in-site Pagefind search — for
-   * that, use `excludeFromSearch`. The two are independent: a
-   * page can be excluded from external SEs but still appear in
-   * Pagefind (e.g. duplicate / old content readers might still
-   * want to find when they're already on the site), or vice
-   * versa.
+   * indexing this page. Independent of `nofollow` — common pattern
+   * for tag / index pages is noindex + follow (don't list this
+   * page in results, but do crawl through to the real content).
+   *
+   * Has NO effect on in-site Pagefind search — for that, use
+   * `excludeFromSearch`. The two are independent: a page can be
+   * excluded from external SEs but still appear in Pagefind (e.g.
+   * duplicate / old content readers might still want to find when
+   * they're already on the site), or vice versa.
    */
   noindex?: boolean;
+  /**
+   * Emit `nofollow` in the `<meta name="robots">` directive when
+   * true. Tells crawlers not to follow outbound links from this
+   * page. Independent of `noindex`. Default false.
+   */
+  nofollow?: boolean;
   /**
    * Exclude this page from in-site Pagefind search results.
    *
@@ -179,6 +203,12 @@ interface Props {
    * a non-root base path (e.g. "/docs/pagefind/").
    */
   pagefindUrl?: string;
+  /**
+   * Base Pagefind prefixes result URLs with. Forwarded to SearchDialog;
+   * format-astro passes the right value for the deploy layout. See
+   * `pagefind-base-url.ts` for why no constant works.
+   */
+  pagefindBaseUrl?: string;
   /**
    * Whether the site emits per-page `.md` mirror endpoints. When true,
    * the page advertises `<link rel="alternate" type="text/markdown">`
@@ -213,6 +243,12 @@ interface Props {
    * `taxonomies.tags.labels`.
    */
   tagLabels?: Record<string, string>;
+  /**
+   * Color chips whose prefix has no color automatically (a stable
+   * palette color per first segment). Sourced from
+   * `taxonomies.tags.autoColor`.
+   */
+  tagAutoColor?: boolean;
   /**
    * Page lifecycle status. Renders a StatusBadge for non-stable
    * states. Drafts/deprecated get strong colors.
@@ -333,7 +369,7 @@ interface Props {
    * `@/data/switcherMap.json`.
    */
   switcherMap?: {
-    versions: Array<{ id: string; label?: string; eol?: boolean; default?: boolean }>;
+    versions: Array<{ id: string; label?: string; eol?: boolean; default?: boolean; root?: boolean }>;
     byLogicalKey: Record<string, Record<string, string>>;
   };
   /**
@@ -341,6 +377,19 @@ interface Props {
    * (`<basePath>/<version>/`). Defaults to "/docs".
    */
   basePath?: string;
+  /**
+   * Sidebar navigation render mode.
+   *
+   * - `"client"` (default): emit the small `<DocsNavClient />` placeholder;
+   *   the tree is hydrated from `/_dogsbay/nav.json` once per session.
+   *   Page HTML shrinks dramatically at scale (~50 KB vs ~1.2 MB on a
+   *   2k-page site). No-JS users see a sitemap fallback link.
+   * - `"ssr-full"`: render the full nav tree into every page's HTML.
+   *   Best for very small sites or strict no-JS / SEO contexts.
+   *
+   * See plans/client-rendered-nav.md.
+   */
+  navMode?: "client" | "ssr-full";
   /**
    * Per-page LLM action UI. When set and `enabled !== false`, renders
    * the PageActions cluster (Copy markdown + Open in Claude/ChatGPT/
@@ -375,16 +424,74 @@ interface Props {
    * in per-page.
    */
   wideLayout?: boolean;
+
+  /**
+   * Which chrome this page wears.
+   *
+   * `"docs"` (default) is the full documentation shell. `"blog"` drops
+   * the sidebar and its nav fetch, and turns on the byline row — the
+   * blog is the same SITE, not a second design system, so the header,
+   * footer, search, page actions, TOC and every theme token stay
+   * identical. See plans/blog-capability.md Phase 3.
+   */
+  chrome?: "docs" | "blog";
+
+  /** Post authors. No byline is rendered when absent — never a placeholder. */
+  author?: string[];
+  /** ISO publish date for the byline. */
+  publishedDate?: string;
+  /** ISO updated date; shown only when it differs from publishedDate. */
+  updatedDate?: string;
+  /**
+   * Reading estimate in whole minutes. Computed at EMIT time from the
+   * TreeNode word count — a browser-side count would re-walk the DOM on
+   * every load for a number that cannot change.
+   */
+  readingMinutes?: number;
+  /** Optional hero image URL, rendered above the prose. */
+  heroImage?: string;
+  /**
+   * Table-of-contents placement. Default `"top"`.
+   * - `"top"` — expandable "On this page" disclosure at the top of the
+   *   article, identical on desktop and mobile; frees the right rail for the
+   *   `right-rail` named slot (e.g. an Ask AI panel).
+   * - `"popover"` — an "On this page" dropdown in the header.
+   * - `"rail"` — the classic right-hand TOC sidebar (pre-`toc` behaviour).
+   * - `"off"` — no table of contents.
+   * See plans/ask-branch1-placement-toc.md.
+   */
+  toc?: TocMode;
+  /**
+   * Internal/external link-icon glyphs. When set, a small trailing icon
+   * marks links in the prose — external (absolute / protocol-relative
+   * href) vs internal (root / relative) — classified purely by href
+   * shape in CSS. Either side may be absent to mark only that link kind.
+   * Sourced from `content.linkIcons` in `dogsbay.config.yml`.
+   * See plans/link-resolution-and-icons.md.
+   */
+  linkIcons?: {
+    external?: string;
+    internal?: string;
+  };
+  /**
+   * "Powered by DogsBay" footer attribution. Generated sites pass
+   * `siteConfig.poweredBy`, which defaults to true and is turned off with
+   * `poweredBy: false` in dogsbay.config.yml. See docs/powered-by.md.
+   */
+  poweredBy?: boolean;
   class?: string;
 }
 
 const {
+  poweredBy = false,
   siteName,
+  siteTagline,
   title,
   siteUrl = "/",
   nav,
   navGroups,
   headings = [],
+  toc = "top",
   prev,
   next,
   repoUrl,
@@ -393,24 +500,35 @@ const {
   editUrl,
   lastUpdated,
   copyright,
-  favicon = "/favicon.ico",
+  favicon,
   ogImage,
   defaultOgImage,
   ogType = "article",
   canonicalUrl,
+  alternates = [],
+  breadcrumbJsonLd,
   twitterHandle,
   themeColor,
   noindex,
+  nofollow,
   excludeFromSearch,
   plausibleDomain,
   plausibleScriptUrl,
   hideSearch = false,
-  pagefindUrl = "/pagefind/",
+  // No default for pagefindUrl — host-root absolute paths break on
+  // subpath-mounted deploys (GH Pages project pages, multi-mount
+  // Cloudflare). format-astro's emitter always passes the
+  // combined-prefix-aware URL; manual instantiation must too.
+  // Undefined here propagates to SearchDialog where the JS loader
+  // throws on first open instead of silently 404'ing the bundle.
+  pagefindUrl,
+  pagefindBaseUrl,
   mdMirror = false,
   tags,
   tagsIndexPath = "/tags",
   tagPrefixes,
   tagLabels,
+  tagAutoColor = false,
   status,
   pageType,
   audience,
@@ -425,10 +543,28 @@ const {
   multiSource,
   switcherMap,
   basePath,
+  navMode = "client",
   wideLayout = false,
+  chrome = "docs",
+  author,
+  publishedDate,
+  updatedDate,
+  readingMinutes,
+  heroImage,
+  linkIcons,
   class: className,
 } = Astro.props;
 
+// The version served at the site root (`path: ""`), if any: the sidebar
+// keeps its pages by leaving out the other versions' folders.
+const navRootVersion = rootVersionFilter(switcherMap?.versions);
+
+// Link icons — classified in CSS by href shape. `data-link-icons`
+// lists which kinds are active; the glyphs ride in CSS custom props
+// (single-quoted so they're valid `content:` string values).
+const { tokens: _linkIconTokens, style: _linkIconStyle } =
+  linkIconAttrs(linkIcons);
+
 // Resolve LLM action visibility + placement once. The component
 // guards against missing markdownBody / mdUrl internally, but we
 // also gate at the layout level so the slots stay empty when
@@ -475,20 +611,108 @@ const hasMetaStrip = (
   (typeof pageType === "string" && pageType.length > 0)
 );
 
+// TOC placement: which container(s) + the right-rail plugin region render.
+// Logic lives in toc-placement.ts so it's unit-tested; this file just consumes.
+const tocPlacement = resolveTocPlacement(toc, {
+  // Only show a TOC when the page has 2+ displayable headings (depth 2–3);
+  // the H1 doesn't count and a one-item TOC is noise. Keeps "On this page"
+  // off landing/welcome pages that are just an H1 + prose.
+  hasHeadings: hasDisplayableToc(headings),
+  wideLayout: !!wideLayout,
+});
+
 const currentPath = Astro.url.pathname.replace(/\/$/, "") || "/";
 
 // SEO computation
 const metaDescription = description ?? siteDescription;
 const metaOgImage = ogImage ?? defaultOgImage;
 const isAbsoluteSiteUrl = /^https?:\/\//.test(siteUrl);
+// Compose canonical from ORIGIN + pathname. siteUrl may carry a
+// path component (the urlBase that drives Astro's `base` — see
+// plans/astro-base-from-site-url.md), and Astro.url.pathname
+// already includes that prefix. Naively concatenating siteUrl +
+// pathname double-counts the urlBase (e.g. .../repo/repo/page).
+// Strip path off siteUrl by reparsing as a URL.
+let canonicalOrigin: string | undefined;
+if (isAbsoluteSiteUrl) {
+  try {
+    const u = new URL(siteUrl);
+    canonicalOrigin = `${u.protocol}//${u.host}`;
+  } catch {
+    // Malformed siteUrl — fall back to the original (no path) behavior.
+    canonicalOrigin = siteUrl.replace(/\/$/, "");
+  }
+}
 const computedCanonical = canonicalUrl
-  ?? (isAbsoluteSiteUrl
-    ? siteUrl.replace(/\/$/, "") + Astro.url.pathname
+  ?? (canonicalOrigin
+    ? canonicalOrigin + Astro.url.pathname
     : undefined);
 
-// Markdown mirror — append `.md` to the current path for the alternate link
+/**
+ * Format an ISO date for a byline.
+ *
+ * Runs at BUILD time, so the output is baked into the HTML and every
+ * reader sees the same string — no hydration flash, and no dependence on
+ * the visitor's locale for a date the author wrote. Falls back to the
+ * raw value if it will not parse, so a typo shows up as itself rather
+ * than as "Invalid Date".
+ */
+/**
+ * A value as a machine-readable ISO 8601 datetime, or "" when it is
+ * not a date at all.
+ *
+ * Unlike `_formatPostDate`, an unparseable value must NOT pass
+ * through: this feeds `article:published_time` / `modified_time`,
+ * where a malformed datetime is worse than an absent one — a consumer
+ * either ignores the whole article object or shows garbage.
+ * `lastUpdated` is documented as also accepting a version/tag string
+ * ("v2.1"), which must never reach these tags.
+ */
+function isoDate(value: string | undefined): string {
+  if (!value) return "";
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? "" : d.toISOString();
+}
+
+function _formatPostDate(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  // timeZone: "UTC" is load-bearing. parseMeta normalizes `created:
+  // 2026-01-01` to "2026-01-01T00:00:00.000Z", so a build host in any
+  // negative-offset zone (the default on many CI runners) would render
+  // "31 December 2025". DocsFooter already carries this fix; these
+  // copies dropped it.
+  return d.toLocaleDateString("en-GB", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC",
+  });
+}
+
+// Markdown mirror for the alternate link.
+//
+// Leaf pages append `.md` to the trimmed path (`/getting-started/` →
+// `/getting-started.md`), matching the emitted `<slug>.md.ts` endpoint.
+// The SITE INDEX is the exception: it is emitted as `index.md.ts`, so
+// its mirror is `<base>/index.md`. Appending `.md` there produced
+// `/.md` (root-served) or `/blog.md` (mounted) — neither exists, and on
+// a mounted site `/blog.md` also falls outside the `/blog/*` route.
+// Both leaf and index URLs carry a trailing slash under Astro's
+// directory build format, so only "is this the site root" distinguishes
+// them. Kept in step with `shouldRewriteToMarkdown`, which is handed the
+// same combined prefix.
+// Use the `basePath` PROP, not import.meta.env.BASE_URL. Astro's `base`
+// carries only site.url's path (urlBase); the prop carries the COMBINED
+// urlBase + site.basePath prefix — the same value the middleware gets —
+// so on a `site.basePath: /docs` deploy the two would otherwise disagree
+// about which page is the index.
+const mdMirrorBase = (basePath ?? "").replace(/\/+$/, "");
+const mdMirrorPath = Astro.url.pathname.replace(/\/$/, "");
 const mdMirrorHref = mdMirror
-  ? (Astro.url.pathname.replace(/\/$/, "") || "") + ".md"
+  ? mdMirrorPath === mdMirrorBase
+    ? `${mdMirrorBase}/index.md`
+    : `${mdMirrorPath}.md`
   : undefined;
 
 // Tag keywords for HTML meta + JSON-LD. Slug-based identifiers
@@ -509,17 +733,30 @@ const tagKeywords = resolveTagKeywords(tags, tagLabels);
 // Course; everything else → Article. Matches the conventions
 // search engines key off for educational / tutorial / reference
 // SERP rendering. See `json-ld.ts` for the full mapping table.
-const articleJsonLd = (ogType === "article" && tagKeywords.length > 0)
-  ? {
-      "@context": "https://schema.org",
-      "@type": jsonLdTypeFor(pageType),
-      headline: title,
-      keywords: tagKeywords.join(", "),
-      ...(metaDescription ? { description: metaDescription } : {}),
-      ...(metaOgImage ? { image: metaOgImage } : {}),
-      ...(computedCanonical ? { url: computedCanonical } : {}),
-    }
-  : undefined;
+// Structured data is emitted for EVERY page, not only tagged articles.
+// This used to also require `tagKeywords.length > 0`, so an untagged
+// page — a homepage, a landing page, a section index — emitted none at
+// all. An external agent audit reported "No JSON-LD structured data
+// found on homepage" and it was right: the page most likely to be an
+// agent's entry point was the one describing itself the least.
+// Keywords are enrichment, not a precondition for identity.
+const articleJsonLd = ogType === "article"
+  ? buildArticleJsonLd({
+      type: jsonLdTypeFor(pageType),
+      title,
+      siteName,
+      keywords: tagKeywords,
+      description: metaDescription,
+      image: metaOgImage,
+      url: computedCanonical,
+      headings,
+    })
+  : buildWebSiteJsonLd({
+      siteName,
+      title,
+      description: metaDescription,
+      url: computedCanonical,
+    });
 
 // `customJsonLd` accepts either a single object or an array.
 // Normalize to an array so we can iterate uniformly. Empty array
@@ -537,12 +774,126 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{title} | {siteName}</title>
 
+    <style is:global>
+      /*
+        The sticky-chrome contract. This header is exactly this tall, and
+        anything else that sticks (the release-comparison toolbar) offsets
+        by the same variable — so they cannot drift apart.
+      */
+      :root {
+        --db-header-height: 3rem;
+      }
+
+      /*
+        Diagrams drawn by Pele (`content.diagrams: pele`, plans/pele-diagrams.md).
+        Pele colours its SVGs from these variables, so a diagram takes the theme
+        and .dark switches them. Here rather than in Diagram.astro or global.css:
+        those are copied into a site once, this package is re-pinned on every
+        build. Borders are thin, so the theme's --border alone is too faint for
+        node outlines. The base mapping is the same as dogsbay-ssg's ssg.css.
+      */
+      .pele {
+        --pele-bg: var(--background);
+        --pele-fg: var(--foreground);
+        --pele-muted: var(--muted-foreground);
+        --pele-line: var(--foreground);
+        --pele-surface: var(--muted);
+        --pele-surface-alt: color-mix(in oklab, var(--muted), var(--foreground) 7%);
+        --pele-border: color-mix(in oklab, var(--border), var(--muted-foreground) 45%);
+        --pele-accent: var(--primary);
+        --pele-font: var(--font-sans);
+        --pele-font-mono: var(--font-code, monospace);
+        --pele-radius: calc(var(--radius) - 4px);
+        /*
+          Series colours (pie, xy, git, timeline, treemap, …; gantt's critical
+          tasks). Pele writes labels in --pele-bg on these fills, so they are
+          darker in light mode and lighter in dark mode. Its own palette is
+          fixed, and put white text on yellow (1.6:1). Same hues, in Pele's
+          order. dogsbay-ssg's ssg.css does not map these yet.
+        */
+        --pele-series-1: oklch(0.5 0.13 250);
+        --pele-series-2: oklch(0.5 0.15 55);
+        --pele-series-3: oklch(0.5 0.13 145);
+        --pele-series-4: oklch(0.5 0.16 25);
+        --pele-series-5: oklch(0.5 0.09 195);
+        --pele-series-6: oklch(0.5 0.12 95);
+        --pele-series-7: oklch(0.5 0.12 320);
+        --pele-series-8: oklch(0.5 0.06 60);
+        --pele-critical: var(--pele-series-4);
+        --pele-error: var(--pele-series-4);
+      }
+      .dark .pele {
+        --pele-series-1: oklch(0.78 0.13 250);
+        --pele-series-2: oklch(0.78 0.15 55);
+        --pele-series-3: oklch(0.78 0.13 145);
+        --pele-series-4: oklch(0.78 0.16 25);
+        --pele-series-5: oklch(0.78 0.09 195);
+        --pele-series-6: oklch(0.78 0.12 95);
+        --pele-series-7: oklch(0.78 0.12 320);
+        --pele-series-8: oklch(0.78 0.06 60);
+      }
+      /*
+        Diagram.astro inverts diagrams in dark mode, for Mermaid's fixed colours;
+        Pele's are already dark. Unlayered, so this wins over the dark:invert and
+        dark:hue-rotate utilities.
+      */
+      .diagram-content:has(> svg.pele),
+      .diagram-content > svg.pele {
+        filter: none;
+      }
+
+      /*
+        Internal/external link icons. Opt-in via `content.linkIcons`,
+        which sets `data-link-icons` (which kinds are active) and the
+        `--db-link-icon-*` custom props (the glyphs) on <body>. Links are
+        classified purely by href shape, so it covers both structured
+        links and raw-HTML anchors from imported content. Scoped to
+        `.docs-prose` so nav/header/footer links are untouched; buttons
+        (`<a data-variant>`, from Button.astro) carry no icon.
+      */
+      body[data-link-icons~="external"] .docs-prose a[href^="http://" i]:not([data-variant])::after,
+      body[data-link-icons~="external"] .docs-prose a[href^="https://" i]:not([data-variant])::after,
+      body[data-link-icons~="external"] .docs-prose a[href^="//"]:not([data-variant])::after {
+        content: var(--db-link-icon-external, "");
+        display: inline-block;
+        margin-inline-start: 0.15em;
+        font-size: 0.85em;
+        line-height: 1;
+        vertical-align: baseline;
+        opacity: 0.7;
+      }
+      body[data-link-icons~="internal"]
+        .docs-prose
+        a[href^="/"]:not([href^="//"]):not([data-variant])::after,
+      body[data-link-icons~="internal"] .docs-prose a[href^="./"]:not([data-variant])::after,
+      body[data-link-icons~="internal"] .docs-prose a[href^="../"]:not([data-variant])::after {
+        content: var(--db-link-icon-internal, "");
+        display: inline-block;
+        margin-inline-start: 0.15em;
+        font-size: 0.85em;
+        line-height: 1;
+        vertical-align: baseline;
+        opacity: 0.7;
+      }
+    </style>
+
     {metaDescription && <meta name="description" content={metaDescription} />}
-    {favicon !== false && <link rel="icon" href={favicon} />}
+    {favicon && <link rel="icon" href={favicon} />}
     {themeColor && <meta name="theme-color" content={themeColor} />}
     {/* External search engine directive — orthogonal to in-site
-       Pagefind exclusion. */}
-    {noindex && <meta name="robots" content="noindex, nofollow" />}
+       Pagefind exclusion. `noindex` + `nofollow` are independent
+       bits per the meta-robots spec; emit only the directives that
+       are set. Combining them when both are set keeps the tag
+       compact (`<meta name="robots" content="noindex, nofollow">`)
+       instead of emitting two tags. */}
+    {(noindex || nofollow) && (
+      <meta
+        name="robots"
+        content={[noindex && "noindex", nofollow && "nofollow"]
+          .filter(Boolean)
+          .join(", ")}
+      />
+    )}
 
     {/* In-site Pagefind exclusion is wired via two coordinated
        attributes on <body> and <main> below — see the prop docs
@@ -556,7 +907,14 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
        sidebar / header / TOC text from per-page excerpts. See main. */}
 
     {computedCanonical && <link rel="canonical" href={computedCanonical} />}
+    {alternates.map((a) => <link rel="alternate" hreflang={a.hreflang} href={a.href} />)}
     {mdMirrorHref && <link rel="alternate" type="text/markdown" href={mdMirrorHref} />}
+    {/* Programmatic llms.txt discovery — agents that follow head
+       link rels get the per-mount llms.txt without parsing HTML.
+       Mirrors the existing _headers Link rel="describedby" used by
+       Cloudflare Pages / Workers. */}
+    <link rel="alternate" type="text/plain" title="llms.txt" href={llmsLinkHrefResolved} />
+    <link rel="describedby" type="text/plain" href={llmsLinkHrefResolved} />
 
     {/* Open Graph */}
     <meta property="og:type" content={ogType} />
@@ -571,13 +929,36 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
     {ogType === "article" && tagKeywords.map((keyword) => (
       <meta property="article:tag" content={keyword} />
     ))}
+    {/* Article dates. `og:type="article"` was declared with no times
+       at all, which is an incomplete article object — crawlers and
+       social cards had no publish date to show even though the page
+       renders one visibly.
+
+       `article:modified_time` falls back to `lastUpdated`, the prop
+       the docs chrome already uses for "Last updated", so a docs page
+       gets a modified time without the blog-only `updatedDate` being
+       set. Only emitted when the value parses as a date: a
+       frontmatter `lastUpdated: v2.1` is a version string, and a
+       malformed datetime is worse than an absent one. */}
+    {ogType === "article" && isoDate(publishedDate) && (
+      <meta property="article:published_time" content={isoDate(publishedDate)} />
+    )}
+    {ogType === "article" && isoDate(updatedDate ?? lastUpdated) && (
+      <meta
+        property="article:modified_time"
+        content={isoDate(updatedDate ?? lastUpdated)}
+      />
+    )}
 
     {/* JSON-LD primary block — Article / HowTo / TechArticle /
        Course depending on `pageType`. Emits keywords as a
        Schema.org keywords string; Google reads this for topical
        categorization in rich results. */}
     {articleJsonLd && (
-      <script type="application/ld+json" set:html={JSON.stringify(articleJsonLd)} />
+      <script type="application/ld+json" set:html={JSON.stringify(articleJsonLd).replace(/</g, "\\u003c")} />
+    )}
+    {breadcrumbJsonLd && (
+      <script type="application/ld+json" set:html={JSON.stringify(breadcrumbJsonLd).replace(/</g, "\\u003c")} />
     )}
 
     {/* Per-page / per-site custom structured data. Layered on
@@ -604,29 +985,69 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
       ></script>
     )}
 
+    {/*
+      Theme bootstrap. Inline and BLOCKING on purpose — it must run
+      before first paint or the page flashes light before going dark.
+
+      An explicit choice wins in BOTH directions. Someone on a
+      dark-mode OS who deliberately picked light must stay light, so
+      "light" is checked rather than treated as "not dark". Only the
+      absence of a stored value falls through to the OS preference.
+
+      That fallback is the point of this block. Previously the only
+      condition was `=== "dark"`, so a visitor whose OS is in dark mode
+      got a light page until they found the toggle — and nothing else
+      in the CSS consulted prefers-color-scheme either. It also made
+      dark mode untestable by any tool that emulates the media query
+      (DevTools' Rendering panel, Playwright's colorScheme), because
+      the page did not read it.
+
+      localStorage access throws in some privacy modes; a throw here
+      would skip the class entirely, so it is guarded and degrades to
+      the OS preference.
+    */}
     <script is:inline>
-      if (localStorage.getItem("theme") === "dark") {
-        document.documentElement.classList.add("dark");
-      }
+      (function () {
+        var stored = null;
+        try {
+          stored = localStorage.getItem("theme");
+        } catch (e) {}
+        var dark =
+          stored === "dark" ||
+          (stored !== "light" &&
+            window.matchMedia("(prefers-color-scheme: dark)").matches);
+        if (dark) document.documentElement.classList.add("dark");
+      })();
     </script>
     <slot name="head" />
   </head>
   <body
     class="bg-background text-foreground antialiased"
     data-pagefind-ignore={excludeFromSearch ? "" : undefined}
+    data-link-icons={_linkIconTokens || undefined}
+    style={_linkIconStyle || undefined}
   >
     <SidebarProvider>
+      {/*
+        chrome="blog" drops the sidebar COLUMN only. SidebarProvider and
+        SidebarInset stay, so the content column, header offset and
+        sticky contract are byte-identical to a docs page — which is what
+        makes the blog read as the same site rather than a lookalike.
+        With no <Sidebar> sibling the inset's peer-* selectors simply do
+        not match and it fills the width.
+      */}
+      {chrome === "docs" && (
       <Sidebar collapsible="icon">
         <SidebarHeader>
           <SidebarMenu>
             <SidebarMenuItem>
-              <SidebarMenuButton size="lg" href={siteUrl} isActive={currentPath === siteUrl || currentPath === "/"}>
+              <SidebarMenuButton size="lg" href={basePath || "/"} isActive={currentPath === basePath || currentPath === "/"}>
                 <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
                   <Fragment set:html={siteIcon} />
                 </div>
                 <div class="grid flex-1 text-left text-sm leading-tight">
                   <span class="truncate font-semibold">{siteName}</span>
-                  <span class="truncate text-xs text-sidebar-foreground/70">Documentation</span>
+                  <span class="truncate text-xs text-sidebar-foreground/70">{siteTagline || "Documentation"}</span>
                 </div>
               </SidebarMenuButton>
             </SidebarMenuItem>
@@ -636,7 +1057,27 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
         <SidebarSeparator />
 
         <SidebarContent>
-          {navGroups ? (
+          {navMode === "client" ? (
+            // Client-render mode: emit one DocsNavClient placeholder
+            // inside a single SidebarGroup, regardless of navGroups.
+            // The group-label shape doesn't apply when the tree is
+            // hydrated by JS — multi-group nav is reconstructed
+            // client-side from the same /_dogsbay/nav.json shape.
+            // See plans/client-rendered-nav.md.
+            <SidebarGroup>
+              <SidebarGroupContent>
+                <DocsNavClient
+                  currentPath={currentPath}
+                  basePath={basePath ?? ""}
+                  namespace={multiSource?.namespace}
+                  version={multiSource?.version}
+                  locale={multiSource?.locale}
+                  rootVersion={navRootVersion.rootVersion}
+                  versionSegments={navRootVersion.versionSegments}
+                />
+              </SidebarGroupContent>
+            </SidebarGroup>
+          ) : navGroups ? (
             navGroups.map(group => (
               <SidebarGroup>
                 <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
@@ -644,8 +1085,10 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                   <SidebarNavTree
                     items={filterNavByAxis(group.items, {
                       basePath: basePath ?? "/docs",
+                      namespace: multiSource?.namespace,
                       version: multiSource?.version,
                       locale: multiSource?.locale,
+                      ...navRootVersion,
                     })}
                     currentPath={currentPath}
                   />
@@ -658,8 +1101,10 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 <SidebarNavTree
                   items={filterNavByAxis(nav, {
                     basePath: basePath ?? "/docs",
+                    namespace: multiSource?.namespace,
                     version: multiSource?.version,
                     locale: multiSource?.locale,
+                    ...navRootVersion,
                   })}
                   currentPath={currentPath}
                 />
@@ -670,14 +1115,31 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
 
         <SidebarRail />
       </Sidebar>
+      )}
 
       <SidebarInset>
-        <header class="sticky top-0 z-40 flex h-12 shrink-0 items-center gap-2 border-b bg-background/95 px-4 backdrop-blur-sm supports-[backdrop-filter]:bg-background/60">
-          <SidebarTrigger class="-ml-1" />
+        {/*
+          Height comes from `--db-header-height` (declared on :root in
+          <head>) — the CONTRACT any other sticky chrome offsets by, e.g.
+          the release-comparison toolbar. One variable, so a change here
+          can never leave another sticky bar overlapping or floating.
+        */}
+        <header class="sticky top-0 z-40 flex h-[var(--db-header-height)] shrink-0 items-center gap-2 border-b bg-background/95 px-4 backdrop-blur-sm supports-[backdrop-filter]:bg-background/60">
+          {chrome === "docs" && <SidebarTrigger class="-ml-1" />}
           <Separator orientation="vertical" class="mr-2 h-4" />
           <span class="text-sm text-muted-foreground" data-page-title>{title}</span>
           <div class="ml-auto flex items-center gap-2">
             <slot name="header" />
+            {tocPlacement.popoverToc && (
+              <details class="dba-toc-popover relative" data-toc-popover>
+                <summary class="cursor-pointer list-none rounded-md px-2 py-1.5 text-sm text-muted-foreground hover:bg-accent hover:text-foreground">
+                  On this page
+                </summary>
+                <div class="absolute right-0 z-50 mt-1 max-h-[70vh] w-64 overflow-y-auto rounded-md border bg-background p-3 shadow-md">
+                  <DocsToc headings={headings} title="" />
+                </div>
+              </details>
+            )}
             {switcherMap && multiSource && (
               <LocaleSwitcher
                 switcherMap={switcherMap}
@@ -704,7 +1166,11 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
             {!hideSearch && (
               <SearchDialog
                 pagefindUrl={pagefindUrl}
+                pagefindBaseUrl={pagefindBaseUrl}
+                navUrl={basePath ? `${basePath}/_dogsbay/nav.json` : "/_dogsbay/nav.json"}
                 taxonomyDisplay={taxonomyDisplay}
+                scopeProduct={multiSource?.namespace}
+                scopeVersion={multiSource?.version}
               />
             )}
             {repoUrl && (
@@ -737,9 +1203,30 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
               the actual page content. Filter elements live in here
               now to stay inside that scope.
             */}
-            {Array.isArray(tags) && tags.map((tag) => (
-              <div hidden data-pagefind-filter={`tag:${tag}`}></div>
-            ))}
+            {/*
+              Slash-nested tags whose prefix is declared in
+              `taxonomies.tags.prefixes` emit as per-prefix filter
+              divs so each prefix becomes its own Pagefind facet
+              column (Difficulty, Topic, Persona, …) instead of
+              pooling under a single "Tag" column.
+
+              Plain tags and tags whose prefix isn't declared fall
+              back to the pooled `tag:` filter — backward-compatible
+              for sites that haven't declared prefixes.
+
+              See plans/per-prefix-search-facets.md.
+            */}
+            {Array.isArray(tags) && tags.map((tag) => {
+              const slash = tag.indexOf("/");
+              if (slash > 0) {
+                const prefix = tag.slice(0, slash);
+                const leaf = tag.slice(slash + 1);
+                if (tagPrefixes && tagPrefixes[prefix]) {
+                  return <div hidden data-pagefind-filter={`${prefix}:${leaf}`}></div>;
+                }
+              }
+              return <div hidden data-pagefind-filter={`tag:${tag}`}></div>;
+            })}
             {Array.isArray(audience) && audience.map((value) => (
               <div hidden data-pagefind-filter={`audience:${value}`}></div>
             ))}
@@ -748,6 +1235,18 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
             ))}
             {status && <div hidden data-pagefind-filter={`status:${status}`}></div>}
             {pageType && <div hidden data-pagefind-filter={`type:${pageType}`}></div>}
+            {/*
+              Multi-source axis filters — so search on a versioned/multi-
+              product site can be scoped to (or faceted by) the current
+              product and version. `product` = namespace, `version` = the
+              version segment. Only emitted when the axis is active.
+            */}
+            {multiSource?.namespace && (
+              <div hidden data-pagefind-filter={`product:${multiSource.namespace}`}></div>
+            )}
+            {multiSource?.version && (
+              <div hidden data-pagefind-filter={`version:${multiSource.version}`}></div>
+            )}
             {/*
               Custom-taxonomy filters. Any taxonomy declared in
               `dogsbay.config.yml` that isn't one of the five built-ins
@@ -801,12 +1300,62 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                   {title}
                 </h1>
               )}
+              {/*
+                Byline — blog chrome only, and only when there is
+                something to say. An absent author means NO byline row,
+                never "Unknown": a placeholder byline is worse than none,
+                because it reads as data rather than as a gap.
+
+                Sits between the H1 and the lede so the reader gets
+                attribution before the summary, which is the order a
+                post is scanned in.
+              */}
+              {chrome === "blog" && (author?.length || publishedDate || readingMinutes) && (
+                <div
+                  class="not-prose mb-6 flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground"
+                  data-post-byline
+                  data-pagefind-ignore
+                >
+                  {author && author.length > 0 && (
+                    <span class="font-medium text-foreground">{author.join(", ")}</span>
+                  )}
+                  {author && author.length > 0 && publishedDate && (
+                    <span aria-hidden="true">&middot;</span>
+                  )}
+                  {publishedDate && (
+                    <time datetime={publishedDate}>{_formatPostDate(publishedDate)}</time>
+                  )}
+                  {publishedDate && readingMinutes && <span aria-hidden="true">&middot;</span>}
+                  {readingMinutes && <span>{readingMinutes} min read</span>}
+                  {updatedDate && updatedDate !== publishedDate && (
+                    <span>
+                      &middot; Updated <time datetime={updatedDate}>{_formatPostDate(updatedDate)}</time>
+                    </span>
+                  )}
+                </div>
+              )}
+
               {autoLede && description && (
                 <p class="text-lg text-muted-foreground mb-6">
                   {description}
                 </p>
               )}
 
+              {/*
+                Hero image. aspect-boxed on purpose — an unsized image
+                above the fold is the classic layout-shift source, and it
+                would shove the prose down after paint.
+              */}
+              {chrome === "blog" && heroImage && (
+                <img
+                  src={heroImage}
+                  alt=""
+                  class="not-prose mb-8 w-full rounded-lg border border-border object-cover aspect-[2/1]"
+                  loading="eager"
+                  decoding="async"
+                />
+              )}
+
               {hasMetaStrip && (
                 <div
                   class="not-prose mb-6 flex flex-wrap items-center gap-2"
@@ -830,11 +1379,23 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                       indexPath={tagsIndexPath}
                       prefixes={tagPrefixes}
                       labels={tagLabels}
+                      autoColor={tagAutoColor}
                     />
                   )}
                 </div>
               )}
 
+              {tocPlacement.topToc && (
+                <details class="dba-toc-top not-prose mb-6 rounded-md border" data-toc-top>
+                  <summary class="cursor-pointer list-none px-3 py-2 text-sm font-medium text-muted-foreground">
+                    On this page
+                  </summary>
+                  <div class="border-t px-3 py-2">
+                    <DocsToc headings={headings} title="" />
+                  </div>
+                </details>
+              )}
+
               <slot />
 
               <DocsFooter
@@ -842,24 +1403,57 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 lastUpdated={lastUpdated}
                 prev={prev}
                 next={next}
+                {/*
+                  Blog adjacency is chronological, so "Previous/Next"
+                  describes the wrong axis. Left is older, right is newer —
+                  a timeline runs that way, and so does a series: the
+                  right-hand link is the next part.
+                */}
+                prevLabel={chrome === "blog" ? "Older" : undefined}
+                nextLabel={chrome === "blog" ? "Newer" : undefined}
                 copyright={copyright}
                 llmsLink={llmFooterLink}
                 llmsLinkHref={llmsLinkHrefResolved}
+                poweredBy={poweredBy}
               />
             </div>
           </main>
 
-          {headings.length > 0 && !wideLayout && (
+          {/* Classic right-hand TOC — only in `toc: rail` mode. */}
+          {tocPlacement.railToc && (
             <aside class="sticky top-12 hidden h-[calc(100vh-3rem)] w-56 shrink-0 overflow-y-auto border-l p-4 lg:block">
               <DocsToc headings={headings} />
             </aside>
           )}
+          {/* Right-rail plugin region — host for the `right-rail` named slot
+              (e.g. an Ask AI panel). Rendered in every non-rail mode and not
+              gated on headings, so a plugin can dock on heading-less pages.
+              Hidden when nothing fills it (see the empty-rail style below). */}
+          {tocPlacement.regionRail && (
+            <aside
+              class="dba-right-rail sticky top-12 hidden h-[calc(100vh-3rem)] w-80 shrink-0 overflow-y-auto border-l p-4 lg:block xl:w-96"
+              data-right-rail
+            >
+              <slot name="right-rail" />
+            </aside>
+          )}
         </div>
       </SidebarInset>
     </SidebarProvider>
   </body>
 </html>
 
+<style>
+  /* The right-rail plugin region renders unconditionally in non-rail TOC
+     modes so plugins (e.g. Ask AI) can dock into it. Until something fills
+     the `right-rail` slot it has no element children — hide it so an empty
+     bordered column doesn't show. (:has matches element children only; an
+     unfilled Astro named slot renders none.) */
+  aside[data-right-rail]:not(:has(*)) {
+    display: none;
+  }
+</style>
+
 <script>
   import "@dogsbay/ui/sidebar/sidebar.ts";