@dogsbay/ui 0.2.0-beta.12 → 0.2.0-beta.121

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/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/endpoint-card/EndpointCard.astro

@@ -51,10 +51,68 @@ const { method, path, baseUrl, summary, description, deprecated = false, class:
 
   {summary && <p class="text-sm text-muted-foreground">{summary}</p>}
   {description && description !== summary && (
-    <div class="text-sm text-muted-foreground" set:html={description} />
+    <div class="api-description text-sm text-muted-foreground" set:html={description} />
   )}
 
   <div class="space-y-3">
     <slot />
   </div>
 </div>
+
+<style is:global>
+  /* An operation's description is Markdown rendered to HTML (lists, code,
+     paragraphs), placed where the page's prose styles do not reach: without
+     these a bulleted field list reads as loose lines. */
+  .api-description > * + * {
+    margin-top: 0.5rem;
+  }
+  .api-description ul {
+    list-style: disc;
+    padding-left: 1.25rem;
+  }
+  .api-description ol {
+    list-style: decimal;
+    padding-left: 1.25rem;
+  }
+  .api-description li + li,
+  .api-description li > ul,
+  .api-description li > ol {
+    margin-top: 0.125rem;
+  }
+  .api-description ul ul {
+    list-style: circle;
+  }
+  /* Field names (`id`, `scm_type`) stand out in the JSON key colour,
+     on a faint tint of it. Override --api-field in the theme to change it; a site
+     scaffolded before the token existed gets --api-post, the same blue. */
+  .api-description code {
+    font-family: var(--font-mono, ui-monospace, monospace);
+    font-size: 0.85em;
+    font-weight: 600;
+    color: var(--api-field, var(--api-post, var(--foreground)));
+    background-color: color-mix(in oklab, var(--api-field, var(--api-post, var(--foreground))) 8%, transparent);
+    border-radius: 0.25rem;
+    padding: 0.0625rem 0.3rem;
+  }
+  /* A code block in a description (a JSON shape, `?order_by=`) is one
+     full-width block, as Swagger UI shows it: the chip styling above,
+     applied per line, read as a stack of separate highlights. */
+  .api-description pre {
+    overflow-x: auto;
+    border-radius: 0.375rem;
+    padding: 0.5rem 0.75rem;
+    background-color: var(--code-background, color-mix(in oklab, var(--foreground) 6%, transparent));
+  }
+  .api-description pre code {
+    display: block;
+    padding: 0;
+    border-radius: 0;
+    background: none;
+    white-space: pre;
+  }
+  .api-description a {
+    color: var(--primary);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+</style>

package/src/files/FileTree.astro

@@ -0,0 +1,16 @@
+---
+/**
+ * FileTree — the `:::files` directive: a nested list shown as folders and files.
+ * The markup is fileTreeHtml (markup.ts), shared with dogsbay-ssg.
+ */
+import { fileTreeHtml, type FileTreeItem } from "./markup.js";
+
+interface Props {
+  items: FileTreeItem[];
+  class?: string;
+}
+
+const { items, class: className } = Astro.props;
+---
+
+<Fragment set:html={fileTreeHtml(items, className ?? "")} />

package/src/files/index.ts

@@ -0,0 +1,2 @@
+export { default as FileTree } from "./FileTree.astro";
+export { fileTreeHtml, type FileTreeItem } from "./markup.js";

package/src/files/markup.ts

@@ -0,0 +1,34 @@
+/**
+ * The `:::files` tree, written once for both pipelines: FileTree.astro renders it,
+ * and dogsbay-ssg copies this file (scripts/sync-astro-styles.mjs) and calls it.
+ * Each pipeline turns an entry's inline Markdown into `label` HTML itself.
+ */
+
+export interface FileTreeItem {
+  /** The entry's label as HTML (already escaped). */
+  label: string;
+  /** A folder: it has entries, or its name ends in "/". */
+  folder: boolean;
+  children: FileTreeItem[];
+}
+
+const svg = (body: string) =>
+  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 text-muted-foreground" aria-hidden="true" focusable="false">${body}</svg>`;
+// Lucide folder and file (ISC licence).
+const FOLDER = svg('<path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z"/>');
+const FILE = svg('<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>');
+
+function list(items: FileTreeItem[], nested: boolean): string {
+  const cls = nested ? "m-0 ml-2 list-none border-l border-border pl-4" : "m-0 list-none p-0";
+  return `<ul class="${cls}">${items
+    .map(
+      (it) =>
+        `<li class="my-0.5" data-kind="${it.folder ? "folder" : "file"}"><span class="inline-flex items-center gap-1.5">${it.folder ? FOLDER : FILE}<span>${it.label}</span></span>${it.children.length ? list(it.children, true) : ""}</li>`,
+    )
+    .join("")}</ul>`;
+}
+
+/** The whole tree, in a bordered, monospaced box. */
+export function fileTreeHtml(items: FileTreeItem[], extraClass = ""): string {
+  return `<div class="not-prose my-4 overflow-x-auto rounded-lg border bg-card p-3 font-mono text-sm${extraClass ? ` ${extraClass}` : ""}" data-component="files">${list(items, false)}</div>`;
+}

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/kbd/Kbd.astro

@@ -1,9 +1,8 @@
 ---
 import { tv } from "tailwind-variants";
+import { KBD_CLASS } from "./variants.js";
 
-const kbd = tv({
-  base: "pointer-events-none inline-flex h-5 items-center justify-center gap-1 rounded border bg-muted px-1.5 font-mono text-xs font-medium text-muted-foreground shadow-[0_1px_0_1px] shadow-muted",
-});
+const kbd = tv({ base: KBD_CLASS });
 
 interface Props {
   class?: string;

package/src/kbd/variants.ts

@@ -0,0 +1,3 @@
+/** Kbd.astro's classes, shared with dogsbay-ssg (copied by scripts/sync-astro-styles.mjs). */
+export const KBD_CLASS =
+  "pointer-events-none inline-flex h-5 items-center justify-center gap-1 rounded border bg-muted px-1.5 font-mono text-xs font-medium text-muted-foreground shadow-[0_1px_0_1px] shadow-muted";

package/src/link-card/LinkCard.astro

@@ -1,5 +1,6 @@
 ---
 import { tv } from "tailwind-variants";
+import Icon from "../icon/Icon.astro";
 
 const linkCard = tv({
   base: "group flex flex-col gap-1 rounded-lg border bg-card p-4 text-card-foreground shadow-sm transition-colors hover:bg-accent/50",
@@ -17,16 +18,21 @@ interface Props {
   title: string;
   description?: string;
   href: string;
+  /** An icon before the title: a name (`rocket`, `mdi:home`) as the Icon component takes. */
+  icon?: string;
   class?: string;
   [key: string]: unknown;
 }
 
-const { title, description, href, class: className, ...rest } = Astro.props;
+const { title, description, href, icon, class: className, ...rest } = Astro.props;
 ---
 
 <a href={href} class={linkCard({ class: className })} {...rest}>
   <div class="flex items-center justify-between">
-    <span class={linkCardTitle()}>{title}</span>
+    <span class="flex min-w-0 items-center gap-2">
+      {icon && <Icon name={icon} class="size-4 shrink-0 text-muted-foreground" />}
+      <span class={linkCardTitle()}>{title}</span>
+    </span>
     <svg
       xmlns="http://www.w3.org/2000/svg"
       width="16"

package/src/property-list/PropertyList.astro

@@ -47,9 +47,10 @@ const groups = locationOrder
 <div class={className}>
   {groups.map((group) => (
     <div class="mb-4 last:mb-0">
-      <h4 class="mb-1 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+      {/* A label, not a heading: under an embed's tag h2 an h4 skipped a level (axe heading-order). */}
+      <p class="mb-1 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
         {group.label}
-      </h4>
+      </p>
       <div class="rounded-lg border bg-card">
         {group.params.map((param) => (
           <PropertyItem

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>