@dogsbay/ui 0.2.0-beta.13 → 0.2.0-beta.131

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,
@@ -32,6 +33,10 @@ interface Props {
   lang?: string;
   /** Optional title/filename displayed in the header bar */
   title?: string;
+  /*
+   * A `caption` slot makes the block a figure: the header bar is its
+   * <figcaption>, showing the caption with the language beside it.
+   */
   /** Show copy button (default: true) */
   copy?: boolean;
   /** Show line numbers (default: false) */
@@ -44,6 +49,31 @@ 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;
+  /**
+   * Lines to fold behind a toggle, e.g. "3-8,20-25" (Expressive Code's `collapse`), numbered from the
+   * block's first line (not `startLine`). Each run shows as "N collapsed lines"; a click or Space
+   * shows or hides it. No script: a checkbox in the label, and
+   * code-rich.css (render-html's code blocks use the same markup).
+   */
+  collapse?: string;
+  /** The toggle's text; `{n}` is the number of lines it hides. `collapsedLabelOne` for a single line. */
+  collapsedLabel?: string;
+  collapsedLabelOne?: string;
   class?: string;
   [key: string]: unknown;
 }
@@ -58,10 +88,32 @@ const {
   highlights,
   wordHighlights,
   theme = "github-dark-default",
+  copyText: copyTextOverride,
+  diffAdd,
+  diffRemove,
+  collapse,
+  collapsedLabel = "{n} collapsed lines",
+  collapsedLabelOne = "1 collapsed line",
   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;
+    // Capped as render-html's parseLineRanges: `1-999999999` would fill the Set and stall the build
+    for (let n = start; n <= Math.min(end, start + 5000); n++) out.add(n);
+  }
+  return out;
+};
+const addLines = parseLineSpec(diffAdd);
+const removeLines = parseLineSpec(diffRemove);
+
 // Build transformers list
 const transformers: ShikiTransformer[] = [
   transformerNotationDiff(),
@@ -71,6 +123,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());
@@ -131,19 +196,72 @@ transformers.push({
   },
 });
 
+// Collapsed runs: after the gutter, so each folded line keeps its number. Lines are the
+// `.line` spans of <code>, separated by "\n" text nodes (render-html's collapseLines does the same).
+const collapseRuns: Array<[number, number]> = [];
+for (const n of [...parseLineSpec(collapse)].sort((a, b) => a - b)) {
+  const last = collapseRuns[collapseRuns.length - 1];
+  if (last && n === last[1] + 1) last[1] = n;
+  else collapseRuns.push([n, n]);
+}
+if (collapseRuns.length) {
+  transformers.push({
+    name: "collapse",
+    code(node) {
+      const kids = node.children as any[];
+      const linePos = kids.flatMap((c, i) => (c.type === "element" && c.tagName === "span" ? [i] : []));
+      for (const [a, b] of [...collapseRuns].reverse()) {
+        if (a > linePos.length) continue;
+        const end = Math.min(b, linePos.length);
+        const from = linePos[a - 1];
+        const to = linePos[end - 1];
+        const label = (end === a ? collapsedLabelOne : collapsedLabel).replace("{n}", String(end - a + 1));
+        kids.splice(from, to - from + 1, {
+          type: "element",
+          tagName: "span",
+          properties: { class: "code-collapse" },
+          children: [
+            {
+              type: "element",
+              tagName: "label",
+              properties: { class: "code-collapse-label", "data-pagefind-ignore": "" },
+              children: [
+                { type: "element", tagName: "input", properties: { type: "checkbox", class: "code-collapse-toggle" }, children: [] },
+                { type: "text", value: label },
+              ],
+            },
+            { type: "element", tagName: "span", properties: { class: "code-collapse-lines" }, children: kids.slice(from, to + 1) },
+          ],
+        });
+      }
+    },
+  });
+}
+
 // Build meta string
 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);
 
-const html = await codeToHtml(code, {
-  lang: lang.toLowerCase() as BundledLanguage,
+// 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(highlightCode, {
+  lang: shikiLang as BundledLanguage,
   themes: {
     light: "github-light-default" as BundledTheme,
     dark: (theme || "github-dark-default") as BundledTheme,
@@ -154,21 +272,36 @@ const html = await codeToHtml(code, {
 });
 
 // Show header bar only when there's a title or a declared language
-const hasLabel = !!title || (lang !== "plaintext");
+const hasCaption = Astro.slots.has("caption");
+const Wrapper = hasCaption ? "figure" : "div";
+const Header = hasCaption ? "figcaption" : "div";
+const hasLabel = hasCaption || !!title || (lang !== "plaintext");
 const showHeader = hasLabel;
 // When no header, copy button floats inside the code body
 const floatingCopy = copy && !showHeader;
 ---
 
-<div
-  class={codeRichWrapper({ class: className })}
+<Wrapper
+  class={codeRichWrapper({ class: [hasCaption && "m-0", className] })}
   data-component="code-rich"
   data-line-numbers={lineNumbers || undefined}
   {...rest}
 >
   {showHeader && (
-    <div class={codeRichHeader()}>
-      <span class="select-none">{title || lang}</span>
+    <Header class={codeRichHeader()}>
+      {/*
+        Left: what the code is (caption or filename title), or the language when that is
+        all there is. Right: the language beside the copy button, as secondary detail
+      */}
+      {hasCaption ? (
+        <span class="min-w-0 font-medium text-code-fg" data-part="caption"><slot name="caption" /></span>
+      ) : title ? (
+        <span class="min-w-0 font-medium text-code-fg" data-part="title">{title}</span>
+      ) : (
+        <span class="select-none">{lang}</span>
+      )}
+      <span class="flex shrink-0 items-center gap-2">
+      {(hasCaption || title) && lang !== "plaintext" && <span class="select-none" data-part="language">{lang}</span>}
       {copy && (
         <button
           class={codeRichCopy()}
@@ -211,7 +344,8 @@ const floatingCopy = copy && !showHeader;
           </svg>
         </button>
       )}
-    </div>
+      </span>
+    </Header>
   )}
   <div class="code-rich-body relative overflow-x-auto [&_pre]:!m-0 [&_pre]:!rounded-none [&_pre]:!border-0 [&_pre]:!bg-transparent [&_pre]:px-4 [&_pre]:py-3">
     <Fragment set:html={html} />
@@ -233,7 +367,7 @@ const floatingCopy = copy && !showHeader;
       </button>
     )}
   </div>
-</div>
+</Wrapper>
 
 <script>
   function setupCodeRichCopy() {

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

@@ -2,7 +2,9 @@
 
 /* ── All lines ────────────────────────────────────────── */
 .code-rich-body .line {
-  display: inline-flex;
+  /* inline-block, not inline-flex: a flex line makes each token span a flex item, and
+     browsers then copy a hand-made selection with a line break between tokens. */
+  display: inline-block;
   width: 100%;
 }
 
@@ -12,7 +14,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 +30,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);
@@ -66,3 +85,36 @@
   padding: 1px 4px;
   margin: 0 -1px;
 }
+
+/* ── `collapse` fence option: line runs folded behind a toggle ──
+   No script: a checkbox inside the label. Lines hide only where :has() works,
+   so a browser without it shows every line rather than losing them. */
+.code-rich-body .code-collapse-label {
+  display: inline-block;
+  width: 100%;
+  cursor: pointer;
+  user-select: none;
+  /* The code's own colour: a muted label fell under 4.5:1 on the code background */
+  border-block: 1px dashed color-mix(in oklab, currentColor 35%, transparent);
+  font-style: italic;
+}
+.code-rich-body .code-collapse-toggle {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  opacity: 0;
+}
+.code-rich-body .code-collapse-label:has(.code-collapse-toggle:focus-visible) {
+  outline: 2px solid var(--ring);
+  outline-offset: -2px;
+}
+/* The label stays when open, so focus stays on the checkbox and it folds again */
+.code-rich-body .code-collapse-label::before {
+  content: "▸ ";
+}
+.code-rich-body .code-collapse-label:has(.code-collapse-toggle:checked)::before {
+  content: "▾ ";
+}
+.code-rich-body .code-collapse:has(.code-collapse-toggle:not(:checked)) > .code-collapse-lines {
+  display: none;
+}

package/src/code-rich/markers.ts

@@ -0,0 +1,66 @@
+/**
+ * `[!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 {
+  // Every marker has "[!code"; without one there is nothing to strip, and MARKER's leading [ \t]* is quadratic on a long run of spaces.
+  if (!code.includes("[!code")) return code;
+  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

@@ -29,6 +29,10 @@
  *          api-params, api-symbol, api-doc, api-source, youtube, image, grid
  */
 import Alert from "../alert/Alert.astro";
+import { badgeClass } from "../badge/variants.js";
+
+/** Attribute-safe text (also safe as element text). */
+const escAttr = (s: string) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 import AlertTitle from "../alert/AlertTitle.astro";
 import AlertDescription from "../alert/AlertDescription.astro";
 import CollapsibleAlert from "../alert/CollapsibleAlert.astro";
@@ -126,8 +130,9 @@ 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 "badge": return `<span class="${badgeClass(n.variant as string | undefined)}" data-variant="${escAttr(String(n.variant || "default"))}">${escAttr(String(n.text ?? ""))}</span>`;
       case "html-inline": return String(n.html || "");
       case "break": return "<br>";
       default: return "";
@@ -142,6 +147,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 +182,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 +300,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 +332,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} />;
@@ -353,7 +392,9 @@ function resolveImage(src: string): ImageMetadata | undefined {
   <li id={(node.props?.id as string) || ""} class="text-sm text-muted-foreground">
     {node.inline
       ? <span>{node.inline.map(span => <InlineRenderer node={span} icons={icons} images={images} />)}</span>
-      : <Fragment set:html={node.html} />
+      : children.length > 0
+        ? children.map(child => <Astro.self node={child} images={images} icons={icons} />)
+        : <Fragment set:html={node.html} />
     }
     {" "}<a href={`#${node.props?.backrefId || ""}`} class="text-primary hover:underline" aria-label={`Back to reference ${node.props?.label}`}>↩</a>
   </li>

package/src/content-renderer/InlineRenderer.astro

@@ -3,6 +3,7 @@
  * InlineRenderer — renders structured InlineNode[] to HTML elements.
  */
 import MathKatex from "../math/MathKatex.astro";
+import Badge from "../badge/Badge.astro";
 
 interface InlineNode {
   type: string;
@@ -47,6 +48,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 +109,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}
@@ -117,6 +136,10 @@ const isEmojiIcon = node.type === "icon" && (node.library === "emoji" || (iconSv
   </a>
 )}
 
+{node.type === "badge" && (
+  <Badge variant={(node as { variant?: string }).variant ?? "default"}>{node.text}</Badge>
+)}
+
 {node.type === "kbd" && (
   <span class="inline-flex items-center gap-0.5">
     {(node.keys || []).map((key, i) => (

package/src/details-sheet/DetailsSheet.astro

@@ -0,0 +1,28 @@
+---
+/**
+ * DetailsSheet — wraps a CollapsibleAlert (a <details>) so it opens as a
+ * side sheet. The markup stays a working <details>: with no script the
+ * content is a normal collapsible block. `<db-details-sheet>` (from
+ * @dogsbay/elements) moves the body into a native modal <dialog> on the right
+ * while it is open.
+ *
+ * Usage:
+ *   <DetailsSheet>
+ *     <CollapsibleAlert title="Advanced options">…</CollapsibleAlert>
+ *   </DetailsSheet>
+ */
+interface Props {
+  /** The close button's accessible name */
+  closeLabel?: string;
+}
+
+const { closeLabel = "Close" } = Astro.props;
+---
+
+<db-details-sheet close-label={closeLabel}>
+  <slot />
+</db-details-sheet>
+
+<script>
+  import "@dogsbay/elements/db-details-sheet";
+</script>

package/src/details-sheet/index.ts

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

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>