@dogsbay/ui 0.2.0-beta.1 → 0.2.0-beta.100

package/package.json

@@ -1,25 +1,28 @@
 {
   "name": "@dogsbay/ui",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.100",
   "description": "Accessible UI components for Astro, inspired by Base UI and shadcn",
   "type": "module",
   "exports": {
     "./*": "./src/*"
   },
   "dependencies": {
-    "tailwind-variants": "^0.3.0"
+    "tailwind-variants": "^0.3.1"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "astro": "^5.0.0 || ^6.0.0",
-    "@dogsbay/elements": "0.2.0-beta.1",
-    "@dogsbay/primitives": "0.2.0-beta.1",
-    "@dogsbay/icons": "0.2.0-beta.1"
+    "astro": "^5.0.0 || ^6.0.0 || ^7.0.0",
+    "@dogsbay/elements": "0.2.0-beta.100",
+    "@dogsbay/icons": "0.2.0-beta.100",
+    "@dogsbay/primitives": "0.2.0-beta.100"
   },
   "optionalDependencies": {
-    "shiki": "^4.0.0",
-    "@shikijs/transformers": "^4.0.0",
-    "maplibre-gl": "^5.0.0",
-    "katex": "^0.16.0"
+    "@shikijs/transformers": "^4.3.1",
+    "katex": "^0.16.47",
+    "maplibre-gl": "^5.24.0",
+    "shiki": "^4.3.1"
   },
   "files": [
     "src",
@@ -34,5 +37,8 @@
   "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/ui",
   "bugs": {
     "url": "https://github.com/dogsbay/dogsbay/issues"
+  },
+  "scripts": {
+    "test": "vitest run"
   }
 }

package/src/alert/CollapsibleAlert.astro

@@ -18,6 +18,11 @@ const wrapper = tv({
   variants: {
     variant: {
       default: "border-border",
+      // `plain` = a disclosure that is CHROME, not an alert: no tint, no
+      // icon, no ARIA role. Used for collapsed context (e.g. the
+      // comparison view's unchanged-section folds), where announcing a
+      // "note" or a live-region "status" would be a lie.
+      plain: "border-border",
       destructive: "border-destructive/50",
       note: "border-note/50",
       abstract: "border-abstract/50",
@@ -41,6 +46,7 @@ type Variant = VariantProps<typeof wrapper>["variant"];
 /** Title bar: stronger tint (~10%) */
 const titleBg: Record<string, string> = {
   default: "bg-muted",
+  plain: "bg-transparent",
   destructive: "bg-destructive/10 text-destructive",
   note: "bg-note/10", abstract: "bg-abstract/10", info: "bg-info/10",
   tip: "bg-tip/10", success: "bg-success/10", question: "bg-question/10",
@@ -51,6 +57,7 @@ const titleBg: Record<string, string> = {
 /** Body: subtle tint (~3%) */
 const bodyBg: Record<string, string> = {
   default: "bg-background",
+  plain: "bg-transparent",
   destructive: "bg-destructive/3",
   note: "bg-note/3", abstract: "bg-abstract/3", info: "bg-info/3",
   tip: "bg-tip/3", success: "bg-success/3", question: "bg-question/3",
@@ -79,14 +86,23 @@ interface Props {
 const { variant = "note", title, open = false, class: className } = Astro.props;
 const v = variant || "note";
 
-const role = contentVariants.has(v) ? "note" : "status";
+// `plain` is chrome — a disclosure, nothing more. No role at all:
+// role="note"/"status" on collapsed context misinforms assistive tech
+// (and "status" would make it a live region).
+const role = v === "plain" ? undefined : contentVariants.has(v) ? "note" : "status";
 const icon = contentVariants.has(v) ? icons[v] : null;
 ---
 
+{/*
+  The role belongs on the CONTENT, not on <details>. A <details> element
+  has an implicit `group` role, and ARIA does not permit overriding it
+  with `note`/`status` — axe flags it (aria-allowed-role), which is
+  exactly what an accessibility pass found on the comparison site's
+  collapsed sections. Moving it to the body keeps the semantics legal.
+*/}
 <details
   class:list={[wrapper({ variant, class: className }), "group/collapsible"]}
   data-variant={variant}
-  role={role}
   open={open}
 >
   <summary class:list={[
@@ -97,7 +113,7 @@ const icon = contentVariants.has(v) ? icons[v] : null;
     <span class="flex-1 text-foreground" data-part="title">{title || v.charAt(0).toUpperCase() + v.slice(1)}</span>
     <span class="shrink-0 text-muted-foreground group-open/collapsible:rotate-180 transition-transform duration-200" set:html={chevronSvg} />
   </summary>
-  <div class:list={["px-4 py-3 text-sm [&_p]:leading-relaxed", bodyBg[v]]}>
+  <div class:list={["px-4 py-3 text-sm [&_p]:leading-relaxed", bodyBg[v]]} role={role}>
     <slot />
   </div>
 </details>

package/src/api-layout/ApiLayout.astro

@@ -12,17 +12,41 @@
  */
 interface Props {
   class?: string;
+  /**
+   * "page" (default): a dedicated API operation page — full-viewport
+   * min-height, sticky code rail.
+   * "embedded": the layout sits inline among prose (imported MDX docs
+   * with several endpoints per page) — natural height, no sticky.
+   */
+  variant?: "page" | "embedded";
 }
 
-const { class: className } = Astro.props;
+const { class: className, variant = "page" } = Astro.props;
+const isPage = variant === "page";
 ---
 
-<div class:list={["grid grid-cols-1 lg:grid-cols-2 lg:min-h-[calc(100vh-3rem)]", className]}>
-  <div class="px-6 py-10 lg:border-r">
+{/* dba-api marks an API-reference region: the generated .docs-prose
+    typography rules skip everything inside it via :not(.dba-api *), so
+    endpoint cards keep their own utility-class typography even when the
+    page body is wrapped in the prose article. */}
+<div
+  class:list={[
+    "dba-api grid grid-cols-1 lg:grid-cols-2",
+    isPage ? "lg:min-h-[calc(100vh-3rem)]" : "my-6 rounded-lg border overflow-hidden",
+    className,
+  ]}
+>
+  <div class:list={[isPage ? "px-6 py-10" : "p-6", "lg:border-r"]}>
     <slot name="description" />
   </div>
   <div class="bg-[var(--api-panel-bg)] text-[var(--api-panel-fg)]">
-    <div class="px-6 py-10 lg:sticky lg:top-12 lg:max-h-[calc(100vh-3rem)] lg:overflow-y-auto">
+    <div
+      class:list={[
+        isPage
+          ? "px-6 py-10 lg:sticky lg:top-12 lg:max-h-[calc(100vh-3rem)] lg:overflow-y-auto"
+          : "p-6",
+      ]}
+    >
       <slot name="code" />
     </div>
   </div>

package/src/code-block/CodeBlock.astro

@@ -42,6 +42,15 @@ const {
   ...rest
 } = Astro.props;
 
+// AsciiDoc/docs language tokens that are not Shiki grammars → the nearest real
+// one, so the block actually highlights (and data-language is meaningful)
+// instead of silently falling back to plaintext. The header still shows the
+// original label (`lang` below), only the highlighter input is aliased. #009.
+const LANG_ALIASES: Record<string, string> = {
+  terminal: "bash",
+};
+const shikiLang = LANG_ALIASES[lang.toLowerCase()] ?? lang.toLowerCase();
+
 // Show header bar based on showTitle prop:
 // - true: show when there's a title or a declared language (default, original behavior)
 // - false: never show
@@ -107,7 +116,7 @@ const floatingCopy = copy && !showHeader;
     </div>
   )}
   <div class="relative overflow-x-auto [&_pre]:!m-0 [&_pre]:!rounded-none [&_pre]:!border-0 [&_pre]:px-4 [&_pre]:py-3">
-    <Code code={code} lang={lang.toLowerCase()} themes={{ light: "github-light-default", dark: theme }} defaultColor={false} />
+    <Code code={code} lang={shikiLang} themes={{ light: "github-light-default", dark: theme }} defaultColor={false} />
     {floatingCopy && (
       <button
         class:list={[codeBlockCopy(), "absolute right-2 top-2 opacity-0 group-hover:opacity-100 transition-opacity"]}

package/src/code-rich/CodeRich.astro

@@ -1,6 +1,7 @@
 ---
 import "./code-rich.css";
-import { codeToHtml, type BundledLanguage, type BundledTheme } from "shiki";
+import { stripMarkersForCopy, stripUnprocessableMarkers } from "./markers";
+import { codeToHtml, bundledLanguages, type BundledLanguage, type BundledTheme } from "shiki";
 import {
   transformerNotationDiff,
   transformerNotationHighlight,
@@ -44,6 +45,21 @@ interface Props {
   wordHighlights?: string;
   /** Shiki theme */
   theme?: string;
+  /**
+   * Override the copy-button text. Diff-annotated blocks copy the
+   * post-change code only — the default (all lines minus annotation
+   * comments) would paste removed lines into the reader's editor.
+   */
+  copyText?: string;
+  /**
+   * Diff lines by NUMBER (1-based, e.g. "2,5-6") instead of `[!code]`
+   * comment markers. Markers only work in languages whose grammar has
+   * comments — in `plaintext` (or any unknown language) Shiki cannot
+   * recognize them and they render as literal text. Line numbers are
+   * language-independent, so a generated diff never leaks markers.
+   */
+  diffAdd?: string;
+  diffRemove?: string;
   class?: string;
   [key: string]: unknown;
 }
@@ -58,10 +74,28 @@ const {
   highlights,
   wordHighlights,
   theme = "github-dark-default",
+  copyText: copyTextOverride,
+  diffAdd,
+  diffRemove,
   class: className,
   ...rest
 } = Astro.props;
 
+// "2,5-6" → Set{2,5,6}
+const parseLineSpec = (spec?: string): Set<number> => {
+  const out = new Set<number>();
+  for (const part of (spec ?? "").split(",")) {
+    const range = part.trim().match(/^(\d+)(?:-(\d+))?$/);
+    if (!range) continue;
+    const start = Number(range[1]);
+    const end = range[2] ? Number(range[2]) : start;
+    for (let n = start; n <= end; n++) out.add(n);
+  }
+  return out;
+};
+const addLines = parseLineSpec(diffAdd);
+const removeLines = parseLineSpec(diffRemove);
+
 // Build transformers list
 const transformers: ShikiTransformer[] = [
   transformerNotationDiff(),
@@ -71,6 +105,19 @@ const transformers: ShikiTransformer[] = [
   transformerNotationWordHighlight(),
 ];
 
+// Line-number diffs (language-independent — see the prop docs)
+if (addLines.size || removeLines.size) {
+  transformers.push({
+    name: "line-diff",
+    line(node, line) {
+      const kind = addLines.has(line) ? "add" : removeLines.has(line) ? "remove" : null;
+      if (!kind) return;
+      const cls = node.properties.class;
+      node.properties.class = `${Array.isArray(cls) ? cls.join(" ") : (cls ?? "")} diff ${kind}`.trim();
+    },
+  });
+}
+
 // Meta-based highlights: ```ts {1,3-5}
 if (highlights) {
   transformers.push(transformerMetaHighlight());
@@ -136,14 +183,25 @@ let metaStr = "";
 if (highlights) metaStr += `{${highlights}} `;
 if (wordHighlights) metaStr += `/${wordHighlights}/ `;
 
-// Strip annotation comments from the copy text
-const copyText = code
-  .replace(/\s*\/\/\s*\[!code\s[^\]]*\]\s*$/gm, "")
-  .replace(/\s*\/\/\s*![a-z]+.*$/gm, "")
-  .trim();
+// Copy text: explicit override (diff blocks pass the post-change code)
+// or the block's own code — either way every annotation form is
+// stripped (see ./markers.ts).
+const copyText = stripMarkersForCopy(copyTextOverride ?? code);
+
+// Unknown languages (package-install, mdx-ish doc tokens) fall back
+// to plaintext instead of throwing — same behavior as CodeBlock's
+// <Code>. The header still shows the declared language label.
+const requestedLang = lang.toLowerCase();
+const isPlainGrammar =
+  !(requestedLang in bundledLanguages) || ["plaintext", "text", "txt", "ansi"].includes(requestedLang);
+const shikiLang = isPlainGrammar ? "plaintext" : requestedLang;
+
+// Markers Shiki cannot process would render as literal text — strip
+// exactly those, leave the rest for the notation transformers.
+const highlightCode = stripUnprocessableMarkers(code, isPlainGrammar);
 
-const html = await codeToHtml(code, {
-  lang: lang.toLowerCase() as BundledLanguage,
+const html = await codeToHtml(highlightCode, {
+  lang: shikiLang as BundledLanguage,
   themes: {
     light: "github-light-default" as BundledTheme,
     dark: (theme || "github-dark-default") as BundledTheme,

package/src/code-rich/code-rich.css

@@ -12,7 +12,12 @@
   min-width: 4ch;
   margin-right: 1.5ch;
   text-align: right;
-  color: oklch(0.35 0 0 / 0.7);
+  /* Theme-aware, and NO alpha. This was a fixed dark grey at 70%
+     opacity: fine on a light code background, 1.3:1 against the dark
+     one — line numbers were effectively invisible in dark mode.
+     Opacity compounds it, since it blends toward whatever is behind.
+     --muted-foreground already flips per theme (L 0.45 / 0.708). */
+  color: var(--muted-foreground);
   user-select: none;
   flex-shrink: 0;
 }
@@ -23,6 +28,18 @@
   color: oklch(0.55 0.2 25);
 }
 
+/* Dark mode: the diff gutters sit on TINTED line backgrounds, not on
+   the plain code background, and at L0.55 they measure 2.89:1 (add)
+   and 2.63:1 (remove) there — both well under AA. Light mode is
+   unaffected, so these are overrides rather than a changed base.
+   Raised to L0.72 for headroom over the 4.5:1 floor. */
+.dark .code-rich-body .gutter.add {
+  color: oklch(0.72 0.2 145);
+}
+.dark .code-rich-body .gutter.remove {
+  color: oklch(0.72 0.14 25);
+}
+
 /* ── Diff line backgrounds ────────────────────────────── */
 .code-rich-body .line.diff.add {
   background-color: oklch(0.75 0.18 145 / 0.15);

package/src/code-rich/markers.ts

@@ -0,0 +1,64 @@
+/**
+ * `[!code …]` annotation hygiene.
+ *
+ * Shiki's notation transformers consume these markers — but only the
+ * ones they can SEE: a marker is recognized when the grammar tokenizes
+ * its comment AND the marker ends the line. Anything else reaches the
+ * reader as literal text in the code block. Two real cases from the
+ * better-auth corpus:
+ *
+ *   - `package-install` (and every unknown language) falls back to
+ *     `plaintext`, which has no comment tokens at all;
+ *   - upstream authors mid-line markers — `// [!code highlight] // check
+ *     if the user is allowed` — where the marker is not the last thing
+ *     on the line.
+ *
+ * These helpers strip exactly what Shiki cannot process, and strip
+ * everything from copy text (a marker pasted into an editor is always
+ * wrong).
+ */
+
+/** A `[!code …]` annotation carrying its own comment leader. */
+const MARKER = /[ \t]*(?:\/\/|#|--|<!--|\/\*|;)[ \t]*\[!code[^\]]*\](?:[ \t]*(?:-->|\*\/))?/g;
+
+/**
+ * A bare annotation — upstream also appends one INSIDE an existing
+ * comment (`// e.g. "us-east-1" [!code highlight]`), with no leader of
+ * its own.
+ */
+const BARE_MARKER = /[ \t]*\[!code[^\]]*\]/g;
+
+/**
+ * Remove the markers Shiki cannot process, leaving the ones it can for
+ * the notation transformers to consume.
+ *
+ * @param code           the block's source
+ * @param isPlainGrammar true when highlighting falls back to plaintext
+ */
+export function stripUnprocessableMarkers(code: string, isPlainGrammar: boolean): string {
+  return code
+    .split("\n")
+    .map((line) => {
+      // No grammar → no comment tokens → Shiki sees nothing to strip.
+      if (isPlainGrammar) return line.replace(MARKER, "").replace(BARE_MARKER, "");
+      let out = "";
+      let last = 0;
+      for (const m of line.matchAll(MARKER)) {
+        const end = m.index + m[0].length;
+        if (line.slice(end).trim() === "") break; // ends the line — Shiki handles it
+        out += line.slice(last, m.index);
+        last = end;
+      }
+      return out + line.slice(last);
+    })
+    .join("\n");
+}
+
+/** Strip EVERY annotation form — markers must never reach the clipboard. */
+export function stripMarkersForCopy(code: string): string {
+  return code
+    .replace(MARKER, "")
+    .replace(BARE_MARKER, "")
+    .replace(/\s*\/\/\s*![a-z]+.*$/gm, "")
+    .trim();
+}

package/src/content-renderer/ContentRenderer.astro

@@ -126,7 +126,7 @@ function inlineToHtml(nodes: InlineNode[]): string {
       case "code": return `<code>${n.text || ""}</code>`;
       case "highlight": return `<mark>${inlineToHtml((n.children || []) as InlineNode[])}</mark>`;
       case "link": return `<a href="${n.href || ""}">${inlineToHtml((n.children || []) as InlineNode[])}</a>`;
-      case "image": return `<img src="${n.src || ""}" alt="${n.alt || ""}">`;
+      case "image": return `<img src="${withBaseUrl(n.src as string | undefined)}" alt="${n.alt || ""}">`;
       case "kbd": return (n.keys as string[] || []).map((k: string) => `<kbd>${k}</kbd>`).join("+");
       case "html-inline": return String(n.html || "");
       case "break": return "<br>";
@@ -142,6 +142,26 @@ function resolveImage(src: string): ImageMetadata | undefined {
   const clean = normalized.replace(/#.*$/, "");
   return images[clean];
 }
+
+/**
+ * Prefix Astro's `base` config (= urlBase from site.url's path)
+ * onto absolute image paths so they resolve on subpath-mounted
+ * deploys. Skip for external / data: / already-prefixed URLs.
+ * See plans/content-assets-folder.md.
+ */
+function withBaseUrl(src: string | undefined): string {
+  if (!src) return "";
+  const baseUrl = import.meta.env.BASE_URL.replace(/\/$/, "");
+  if (
+    !baseUrl ||
+    !src.startsWith("/") ||
+    src.startsWith(`${baseUrl}/`) ||
+    /^(?:[a-z]+:|\/\/)/i.test(src)
+  ) {
+    return src;
+  }
+  return `${baseUrl}${src}`;
+}
 ---
 
 {/* ── Prose ──────────────────────────────────────────────── */}
@@ -157,7 +177,7 @@ function resolveImage(src: string): ImageMetadata | undefined {
   <Fragment set:html={
     `<h${node.props!.level} id="${node.props!.slug || ''}" class="group scroll-mt-20">` +
     `${node.inline ? inlineToHtml(node.inline) : (node.html?.replace(/<h\d[^>]*>|<\/h\d>/g, '') || node.props!.text || '')}` +
-    `<a href="#${node.props!.slug || ''}" class="no-underline ml-2 opacity-0 group-hover:opacity-50 transition-opacity text-muted-foreground" aria-label="Link to this heading">¶</a>` +
+    `<a href="#${node.props!.slug || ''}" class="heading-anchor no-underline ml-2 opacity-0 group-hover:opacity-50 transition-opacity text-muted-foreground" aria-label="Link to this heading">¶</a>` +
     `</h${node.props!.level}>`
   } />
 )}
@@ -275,7 +295,18 @@ function resolveImage(src: string): ImageMetadata | undefined {
 {/* ── Table ──────────────────────────────────────────────── */}
 {node.type === "table" && (
   <Table class="my-4">
-    {children.map(child => <Astro.self node={child} images={images} icons={icons} />)}
+    {(node.props?.headerRows as string[][] | undefined)?.length ? (
+      <TableHeader>
+        {(node.props!.headerRows as string[][]).map((row) => (
+          <TableRow>{row.map((cell) => <TableHead set:html={cell} />)}</TableRow>
+        ))}
+      </TableHeader>
+    ) : null}
+    <TableBody>
+      {((node.props?.bodyRows as string[][] | undefined) ?? []).map((row) => (
+        <TableRow>{row.map((cell) => <TableCell set:html={cell} />)}</TableRow>
+      ))}
+    </TableBody>
   </Table>
 )}
 {node.type === "thead" && <TableHeader>{children.map(child => <Astro.self node={child} images={images} icons={icons} />)}</TableHeader>}
@@ -296,11 +327,14 @@ function resolveImage(src: string): ImageMetadata | undefined {
 {node.type === "hr" && <hr class="my-8 border-border" />}
 {node.type === "html" && (() => {
   let html = node.html || "";
-  if (html.includes("<img") && Object.keys(images).length > 0) {
+  if (html.includes("<img")) {
     html = html.replace(/src="([^"]+)"/g, (_match: string, src: string) => {
       const resolved = resolveImage(src);
       if (resolved) return `src="${resolved.src}" width="${resolved.width}" height="${resolved.height}"`;
-      return _match;
+      // Not in the glob (SVG / PDF / build-without-optimization) —
+      // prefix BASE_URL so absolute paths resolve on subpath deploys.
+      const prefixed = withBaseUrl(src);
+      return prefixed === src ? _match : `src="${prefixed}"`;
     });
   }
   return <Fragment set:html={html} />;

package/src/content-renderer/InlineRenderer.astro

@@ -47,6 +47,24 @@ function resolveImage(src: string): ImageMetadata | undefined {
 
 const resolvedImg = node.type === "image" ? resolveImage(node.src as string || "") : undefined;
 
+// When the image isn't in the glob map (SVG, PDF, or built with
+// imageOptimization: false), the `<img src={node.src}>` fallback
+// fires below. Prefix Astro's `base` for absolute paths so they
+// resolve on subpath-mounted deploys. See plans/content-assets-folder.md.
+function withBaseUrl(src: string | undefined): string {
+  if (!src) return "";
+  const baseUrl = import.meta.env.BASE_URL.replace(/\/$/, "");
+  if (
+    !baseUrl ||
+    !src.startsWith("/") ||
+    src.startsWith(`${baseUrl}/`) ||
+    /^(?:[a-z]+:|\/\/)/i.test(src)
+  ) {
+    return src;
+  }
+  return `${baseUrl}${src}`;
+}
+
 // Icon resolution
 const iconSvg = node.type === "icon" && icons
   ? icons.resolve(node.library || "emoji", node.name, node.variant, node.size) as string | null
@@ -90,7 +108,7 @@ const isEmojiIcon = node.type === "icon" && (node.library === "emoji" || (iconSv
 )}
 {node.type === "image" && !resolvedImg && (
   <img
-    src={node.src}
+    src={withBaseUrl(node.src as string | undefined)}
     alt={node.alt || ""}
     title={node.title}
     width={node.width}

package/src/docs-layout/DocsLayout.astro

@@ -99,10 +99,33 @@ const currentPath = Astro.url.pathname.replace(/\/$/, "") || "/";
     <title>{title} — {siteTitle}</title>
     <ClientRouter />
     <script is:inline>
-      if (localStorage.getItem("theme") === "dark") {
-        document.documentElement.classList.add("dark");
-      }
+      // Explicit choice wins in BOTH directions; only its absence
+      // falls through to the OS. Kept in sync with
+      // packages/docs-layout/src/DocsLayout.astro — a test asserts no
+      // copy regresses to the localStorage-only form.
+      (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>
+    <style is:global>
+      /*
+        The sticky-chrome contract. The docs header is exactly this tall,
+        and anything else that sticks (the comparison toolbar) offsets by
+        it — one variable, so a header change can never leave another bar
+        overlapping or floating.
+      */
+      :root {
+        --db-header-height: 3.25rem;
+      }
+    </style>
     <slot name="head" />
   </head>
   <body class="min-h-screen bg-background text-foreground antialiased">
@@ -131,7 +154,16 @@ const currentPath = Astro.url.pathname.replace(/\/$/, "") || "/";
         <SidebarRail />
       </Sidebar>
       <SidebarInset>
-        <header class="sticky top-0 z-40 flex items-center gap-3 border-b border-border bg-background/95 px-4 py-3 backdrop-blur-sm">
+        {/*
+          The header's height comes from `--db-header-height` (declared on
+          :root below) — the CONTRACT that any other sticky chrome sticks
+          below, e.g. the comparison toolbar. Both read the same variable,
+          so they cannot drift; a magic offset copied into another
+          stylesheet would break the moment this padding changed.
+        */}
+        <header
+          class="sticky top-0 z-40 flex h-[var(--db-header-height)] items-center gap-3 border-b border-border bg-background/95 px-4 backdrop-blur-sm"
+        >
           <SidebarTrigger />
           <Separator orientation="vertical" class="h-5" />
           <span class="text-sm font-medium" data-page-title>{title}</span>

package/src/icon/Icon.astro

@@ -0,0 +1,84 @@
+---
+/**
+ * Icon — render an icon by name from any Iconify pack (defaults
+ * to Lucide).
+ *
+ * Resolves at BUILD time via `@dogsbay/icons`'s registry — the
+ * SVG is inlined into the static HTML, so there's no client-side
+ * fetch and no FOUC. Tree-shakeable: only icons actually used in
+ * pages get inlined, since Astro statically evaluates the
+ * resolution per template instance.
+ *
+ * Usage:
+ *
+ *   <Icon name="rocket" />              // bare → Lucide rocket
+ *   <Icon name="lucide:book-open" />    // explicit pack
+ *   <Icon name="mdi:home" />            // Material Design Icons
+ *   <Icon name="simple-icons:github" /> // brand icons
+ *   <Icon name="rocket" class="size-5 text-primary" />
+ *
+ * Bare names check the emoji map first (so `rocket` → 🚀
+ * matches existing inline-icon behaviour), then fall through to
+ * Lucide. When the icon doesn't exist anywhere, the component
+ * renders nothing — silent fallback rather than a broken-image
+ * box, since icons are decorative and consistent typography is
+ * preferable to a placeholder.
+ *
+ * Accessibility: when `alt` is supplied, the icon is announced
+ * to screen readers as a labelled image. Without `alt` (the
+ * default), the SVG is `aria-hidden` because most icons in this
+ * codebase are paired with adjacent text that already conveys
+ * the meaning. Pass `alt=""` explicitly to force the
+ * decorative-only state when needed by external tooling.
+ */
+import { resolveIcon } from "@dogsbay/icons";
+
+interface Props {
+  /**
+   * Icon shorthand. Either bare (`rocket`, `book-open`) or
+   * namespaced (`pack:name`). See file header for examples.
+   */
+  name: string;
+  /** Tailwind class string. Defaults to `size-4` for inline-text sizing. */
+  class?: string;
+  /**
+   * Accessible label. Set to a non-empty string for icons that
+   * convey information without surrounding text. Leave undefined
+   * (or pass empty string) for decorative icons paired with a
+   * text label.
+   */
+  alt?: string;
+}
+
+const { name, class: className = "size-4", alt } = Astro.props;
+const svg = resolveIcon(name);
+const labelled = typeof alt === "string" && alt.length > 0;
+---
+
+{
+  svg ? (
+    svg.startsWith("<") ? (
+      <span
+        class:list={["inline-flex shrink-0", className]}
+        role={labelled ? "img" : undefined}
+        aria-label={labelled ? alt : undefined}
+        aria-hidden={labelled ? undefined : "true"}
+        set:html={svg}
+        data-icon={name}
+      />
+    ) : (
+      // Emoji fallback — `svg` is actually a Unicode character
+      // when the name resolved against the emoji map (e.g.
+      // `rocket` → 🚀). Render it as text so font emoji shows.
+      <span
+        class:list={["inline-flex shrink-0", className]}
+        role={labelled ? "img" : undefined}
+        aria-label={labelled ? alt : undefined}
+        aria-hidden={labelled ? undefined : "true"}
+        data-icon={name}
+      >
+        {svg}
+      </span>
+    )
+  ) : null
+}

package/src/icon/index.ts

@@ -0,0 +1 @@
+export { default as Icon } from "./Icon.astro";

package/src/image/Image.astro

@@ -47,6 +47,27 @@ const captionText = caption || title;
 const w = width || (imageData ? imageData.width : undefined);
 const h = height || (imageData ? imageData.height : undefined);
 
+// When `imageData` is unavailable (image not in import.meta.glob —
+// e.g. SVG, PDF, or build-time `imageOptimization: false`), the
+// `<img src={src}>` fallback fires with the raw markdown src. For
+// absolute paths like `/_assets/foo.png`, we need to prefix with
+// Astro's `base` so the URL resolves on subpath-mounted deploys
+// (GH Pages project pages, multi-mount Cloudflare).
+//
+// `<AstroImage>` does this automatically; raw `<img>` does not.
+//
+// Skip prefixing for: external URLs (http/https), data: URIs,
+// and paths that already start with `import.meta.env.BASE_URL`
+// (defensive; shouldn't normally happen).
+const baseUrl = import.meta.env.BASE_URL.replace(/\/$/, "");
+const resolvedSrc =
+  baseUrl &&
+  src.startsWith("/") &&
+  !src.startsWith(`${baseUrl}/`) &&
+  !/^(?:[a-z]+:|\/\/)/i.test(src)
+    ? `${baseUrl}${src}`
+    : src;
+
 const alignClass = align === "left"
   ? "float-left mr-4 mb-2"
   : align === "right"
@@ -71,7 +92,7 @@ const alignClass = align === "left"
       />
     ) : (
       <img
-        src={src}
+        src={resolvedSrc}
         alt={alt}
         title={title}
         width={w}
@@ -102,7 +123,7 @@ const alignClass = align === "left"
   />
 ) : (
   <img
-    src={src}
+    src={resolvedSrc}
     alt={alt}
     title={title}
     width={w}

package/src/sidebar/SidebarNavMark.astro

@@ -0,0 +1,85 @@
+---
+/**
+ * A nav state marker (changed / new / removed / moved).
+ *
+ * Accessibility contract — the reason this is a component and not a
+ * coloured dot inlined three times:
+ *
+ *  - **Never colour alone** (WCAG 1.4.1): each kind gets a distinct
+ *    GLYPH (+ • − →), so it is readable in greyscale and by anyone who
+ *    does not perceive the hue difference. Colour only reinforces.
+ *  - **Survives forced-colors** (Windows High Contrast strips
+ *    background-color): the glyph is real text, so it always renders;
+ *    `currentColor` keeps it visible when the palette is overridden.
+ *  - **Announced, not implied**: a visually-hidden word rides along, so
+ *    the row reads "MySQL, changed". `title` alone is not enough — it is
+ *    unreliable in screen readers and invisible to touch users.
+ *  - **aria-hidden on the glyph** so it is not announced twice.
+ */
+interface Props {
+  kind: "added" | "changed" | "removed" | "moved";
+  /** Announced text; defaults to the kind (or "contains X" for a subtree). */
+  label?: string;
+  /** True when this summarizes DESCENDANTS (a collapsed group). */
+  subtree?: boolean;
+  class?: string;
+}
+
+const { kind, label, subtree = false, class: className } = Astro.props;
+
+const GLYPH: Record<Props["kind"], string> = {
+  added: "+",
+  changed: "•",
+  removed: "−",
+  moved: "→",
+};
+
+const text = label ?? (subtree ? `contains ${kind}` : kind);
+---
+
+<span
+  class:list={["db-nav-mark", className]}
+  data-nav-mark={kind}
+  data-nav-mark-subtree={subtree ? "" : undefined}
+  title={text}
+>
+  <span aria-hidden="true">{GLYPH[kind]}</span>
+  <span class="sr-only">{text}</span>
+</span>
+
+<style is:global>
+  .db-nav-mark {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    width: 1rem;
+    height: 1rem;
+    margin-left: auto; /* right-aligned: labels stay flush-left and scannable */
+    border-radius: 99px;
+    font-size: 0.75rem;
+    line-height: 1;
+    font-weight: 700;
+    /* colour REINFORCES the glyph; it never carries the meaning alone */
+    color: var(--color-muted-foreground, currentColor);
+  }
+  .db-nav-mark[data-nav-mark="added"] { color: var(--color-success, oklch(0.72 0.19 150)); }
+  .db-nav-mark[data-nav-mark="changed"] { color: var(--color-warning, oklch(0.8 0.16 85)); }
+  .db-nav-mark[data-nav-mark="removed"] { color: var(--color-destructive, oklch(0.64 0.21 25)); }
+  .db-nav-mark[data-nav-mark="moved"] { color: var(--color-info, oklch(0.7 0.14 240)); }
+  /* A subtree marker is a hint, not a claim about this row — mute it. */
+  .db-nav-mark[data-nav-mark-subtree] { opacity: 0.55; }
+
+  /* Removed pages get a second non-colour signal — but ONLY a page that
+     is itself removed. A subtree aggregate is a claim about descendants;
+     striking through a surviving group would tell the reader the whole
+     section was deleted. */
+  [data-nav-mark-row="removed"]:not([data-nav-mark-subtree]) {
+    text-decoration: line-through;
+    opacity: 0.7;
+  }
+
+  @media (forced-colors: active) {
+    .db-nav-mark { color: CanvasText; }
+  }
+</style>

package/src/sidebar/SidebarNavTree.astro

@@ -1,4 +1,5 @@
 ---
+import SidebarNavMark from "./SidebarNavMark.astro";
 /**
  * Recursive sidebar navigation tree.
  * Renders a data-driven tree with native <details>/<summary> for zero-JS expand/collapse.
@@ -8,11 +9,18 @@
  *   <SidebarNavTree items={navItems} currentPath={Astro.url.pathname} />
  */
 
+interface NavMark {
+  kind: "added" | "changed" | "removed" | "moved";
+  label?: string;
+  subtree?: boolean;
+}
+
 interface NavItem {
   label: string;
   href?: string;
   icon?: string;         // Raw SVG string (rendered via set:html)
   children?: NavItem[];
+  mark?: NavMark;
 }
 
 interface Props {
@@ -24,6 +32,13 @@ interface Props {
 
 const { items, currentPath, level = 0, class: className } = Astro.props;
 
+/**
+ * Markers are rendered by SidebarNavMark, which owns the accessibility
+ * contract (distinct glyph so colour is never the sole channel,
+ * visually-hidden text so the row announces "MySQL, changed",
+ * forced-colors survival). See that component.
+ */
+
 const normalizedPath = currentPath.replace(/\/$/, "") || "/";
 
 function isActive(href: string) {
@@ -54,24 +69,78 @@ const paddingLeft = `${8 + level * 12}px`;
     const active = item.href ? isActive(item.href) : false;
     const hasChildren = item.children && item.children.length > 0;
     const shouldOpen = hasChildren && hasActiveDescendant(item);
+    const open = shouldOpen || active;
+    // A branch that is ALSO a page (has an href) is a section landing
+    // page; it uses the button-driven disclosure below and needs a
+    // stable id linking its toggle button to its submenu.
+    const submenuId = item.href
+      ? `nav-sub-${item.href.replace(/[^a-z0-9]+/gi, "-")}-${level}`
+      : undefined;
 
     return (
       <li data-sidebar="nav-tree-item">
-        {hasChildren ? (
+        {hasChildren && item.href ? (
+          /*
+            Section landing page: APG "disclosure navigation" pattern — a
+            real link (navigates) + a SEPARATE toggle <button> (expands),
+            as siblings. Nesting a focusable <a> inside the interactive
+            <summary> is an axe `nested-interactive` violation, and native
+            <details> can't show a header link when collapsed without that
+            nesting. Progressive enhancement: the submenu's server state
+            (hidden unless open) is correct with no JS — the link still
+            works and the active section is expanded — and the inline
+            script wires the toggle button when JS is available.
+          */
+          <Fragment>
+            <div
+              class:list={[
+                "flex w-full min-w-0 items-center gap-2 rounded-md text-sm text-sidebar-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+                level === 0 ? "h-8" : "h-7",
+                active && "bg-sidebar-accent font-medium text-sidebar-accent-foreground",
+              ]}
+              style={`padding-left: ${paddingLeft};`}
+            >
+              <button
+                type="button"
+                data-nav-toggle
+                aria-controls={submenuId}
+                aria-expanded={open ? "true" : "false"}
+                aria-label={`Toggle ${item.label} section`}
+                class="shrink-0 rounded outline-none ring-sidebar-ring focus-visible:ring-2"
+              >
+                <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 transition-transform duration-200" data-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6" /></svg>
+              </button>
+              {item.icon && <span class="shrink-0 [&>svg]:size-4" set:html={item.icon} />}
+              <a
+                href={item.href}
+                class="min-w-0 flex-1 truncate text-inherit no-underline outline-none ring-sidebar-ring focus-visible:ring-2"
+                data-nav-href={item.href}
+                data-active={active || undefined}
+                data-nav-mark-row={item.mark?.subtree ? undefined : item.mark?.kind}
+              >{item.label}</a>
+              {item.mark && (
+                <SidebarNavMark kind={item.mark.kind} label={item.mark.label} subtree={item.mark.subtree} />
+              )}
+            </div>
+            <div id={submenuId} data-nav-submenu hidden={!open}>
+              <Astro.self items={item.children!} currentPath={currentPath} level={level + 1} />
+            </div>
+          </Fragment>
+        ) : hasChildren ? (
           <details open={shouldOpen || active}>
             <summary
               class:list={[
                 "flex w-full min-w-0 cursor-pointer items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none [list-style:none] ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&::-webkit-details-marker]:hidden",
                 level === 0 ? "h-8" : "h-7",
-                active && "bg-sidebar-accent font-medium text-sidebar-accent-foreground",
               ]}
               style={`padding-left: ${paddingLeft};`}
-              data-nav-href={item.href || undefined}
-              data-active={active || undefined}
             >
               <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 transition-transform duration-200" data-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6" /></svg>
               {item.icon && <span class="shrink-0 [&>svg]:size-4" set:html={item.icon} />}
-              <span class="truncate">{item.label}</span>
+              <span class="min-w-0 flex-1 truncate">{item.label}</span>
+              {item.mark && (
+                <SidebarNavMark kind={item.mark.kind} label={item.mark.label} subtree={item.mark.subtree} />
+              )}
             </summary>
             <Astro.self items={item.children!} currentPath={currentPath} level={level + 1} />
           </details>
@@ -86,12 +155,22 @@ const paddingLeft = `${8 + level * 12}px`;
             style={`padding-left: ${paddingLeft};`}
             data-active={active || undefined}
             data-nav-href={item.href}
+            {/*
+              A SUBTREE mark is a claim about descendants, never about
+              this row — striking through a surviving group because one
+              child was deleted tells the reader the whole section is
+              gone (code review, 2026-07-13).
+            */}
+            data-nav-mark-row={item.mark?.subtree ? undefined : item.mark?.kind}
           >
             {/* Spacer to align with chevron in branch items */}
             <span class="size-4 shrink-0" />
             {/* Icon (level 0 only) */}
             {item.icon && <span class="shrink-0 [&>svg]:size-4" set:html={item.icon} />}
-            <span class="truncate">{item.label}</span>
+            <span class="min-w-0 flex-1 truncate">{item.label}</span>
+            {item.mark && (
+              <SidebarNavMark kind={item.mark.kind} label={item.mark.label} subtree={item.mark.subtree} />
+            )}
           </a>
         )}
       </li>
@@ -100,7 +179,32 @@ const paddingLeft = `${8 + level * 12}px`;
 </ul>
 
 <style is:global>
-  details[open] > summary [data-chevron] {
+  details[open] > summary [data-chevron],
+  [data-nav-toggle][aria-expanded="true"] [data-chevron] {
     transform: rotate(90deg);
   }
 </style>
+
+<script>
+  // Wire the section-landing disclosure toggles (APG disclosure-nav).
+  // The link navigates on its own; this button just expands/collapses
+  // the sibling submenu. Server-rendered state is already correct, so
+  // with no JS the link still works and the active section is open.
+  // Idempotent + re-run after view transitions.
+  function wireNavToggles() {
+    document
+      .querySelectorAll<HTMLButtonElement>("[data-nav-toggle]:not([data-wired])")
+      .forEach((btn) => {
+        btn.dataset.wired = "1";
+        const id = btn.getAttribute("aria-controls");
+        const submenu = id ? document.getElementById(id) : null;
+        btn.addEventListener("click", () => {
+          const isOpen = btn.getAttribute("aria-expanded") === "true";
+          btn.setAttribute("aria-expanded", String(!isOpen));
+          if (submenu) submenu.hidden = isOpen;
+        });
+      });
+  }
+  wireNavToggles();
+  document.addEventListener("astro:page-load", wireNavToggles);
+</script>

package/src/table/Table.astro

@@ -11,14 +11,17 @@ const table = tv({
 
 interface Props {
   class?: string;
+  /** Optional table caption, rendered as a `<caption>` (bottom-aligned). */
+  caption?: string;
   [key: string]: unknown;
 }
 
-const { class: className, ...rest } = Astro.props;
+const { class: className, caption, ...rest } = Astro.props;
 ---
 
 <div class={tableContainer()}>
   <table class={table({ class: className })} {...rest}>
+    {caption && <caption class="text-sm text-muted-foreground mt-2">{caption}</caption>}
     <slot />
   </table>
 </div>

package/src/table/TableCell.astro

@@ -2,7 +2,7 @@
 import { tv } from "tailwind-variants";
 
 const tableCell = tv({
-  base: "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0",
+  base: "p-2 align-top [&:has([role=checkbox])]:pr-0",
 });
 
 interface Props {

package/src/table/TableHead.astro

@@ -2,7 +2,7 @@
 import { tv } from "tailwind-variants";
 
 const tableHead = tv({
-  base: "h-10 px-2 text-left align-middle font-semibold text-muted-foreground whitespace-nowrap [&:has([role=checkbox])]:pr-0",
+  base: "px-2 py-2 text-left align-bottom font-semibold text-muted-foreground [&:has([role=checkbox])]:pr-0",
 });
 
 interface Props {