@dogsbay/ui 0.2.0-beta.17 → 0.2.0-beta.171

package/package.json

@@ -1,25 +1,30 @@
 {
   "name": "@dogsbay/ui",
-  "version": "0.2.0-beta.17",
+  "version": "0.2.0-beta.171",
   "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"
   },
-  "peerDependencies": {
-    "astro": "^5.0.0 || ^6.0.0",
-    "@dogsbay/icons": "0.2.0-beta.17",
-    "@dogsbay/elements": "0.2.0-beta.17",
-    "@dogsbay/primitives": "0.2.0-beta.17"
+  "devDependencies": {
+    "vitest": "^4.1.10",
+    "@shikijs/transformers": "^4.3.1",
+    "katex": "^0.16.47",
+    "maplibre-gl": "^5.24.0",
+    "shiki": "^4.3.1"
   },
-  "optionalDependencies": {
-    "shiki": "^4.0.0",
-    "@shikijs/transformers": "^4.0.0",
-    "maplibre-gl": "^5.0.0",
-    "katex": "^0.16.0"
+  "peerDependencies": {
+    "astro": "^5.0.0 || ^6.0.0 || ^7.0.0",
+    "@shikijs/transformers": "^4.3.1",
+    "katex": "^0.16.47",
+    "maplibre-gl": "^5.24.0",
+    "shiki": "^4.3.1",
+    "@dogsbay/elements": "0.2.0-beta.171",
+    "@dogsbay/icons": "0.2.0-beta.171",
+    "@dogsbay/primitives": "0.2.0-beta.171"
   },
   "files": [
     "src",
@@ -34,5 +39,25 @@
   "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/ui",
   "bugs": {
     "url": "https://github.com/dogsbay/dogsbay/issues"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    },
+    "@shikijs/transformers": {
+      "optional": true
+    },
+    "katex": {
+      "optional": true
+    },
+    "maplibre-gl": {
+      "optional": true
+    },
+    "shiki": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "vitest run"
   }
 }

package/src/alert/CollapsibleAlert.astro

@@ -6,18 +6,26 @@
  * Composes with the same variant tokens as Alert.
  *
  * Usage:
- *   <CollapsibleAlert variant="warning" title="Warning" open>
+ *   <CollapsibleAlert variant="warning" title="Warning" icon="lucide:rocket" open>
  *     <p>Body content here.</p>
  *   </CollapsibleAlert>
+ *
+ * A title with markup goes in the `title` slot: `<Fragment slot="title">Run <code>init</code></Fragment>`.
  */
 import { tv, type VariantProps } from "tailwind-variants";
 import { contentVariants, icons, chevronSvg } from "./variants.js";
+import { resolveIcon } from "./icon.js";
 
 const wrapper = tv({
   base: "relative w-full rounded-lg border overflow-hidden [&>summary]:list-none [&>summary::-webkit-details-marker]:hidden",
   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 +49,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 +60,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",
@@ -73,31 +83,47 @@ interface Props {
   title?: string;
   /** Whether the details starts open */
   open?: boolean;
+  /** An icon name in place of the variant's (`lucide:rocket`, `compass`, an emoji shortcode); unknown names keep the variant's. */
+  icon?: string;
   class?: string;
+  /** id, data-*, aria-*: passed to the <details> (an `id` is a link target) */
+  [key: string]: unknown;
 }
 
-const { variant = "note", title, open = false, class: className } = Astro.props;
+const { variant = "note", title, open = false, class: className, icon: iconName, ...rest } = Astro.props;
 const v = variant || "note";
 
-const role = contentVariants.has(v) ? "note" : "status";
-const icon = contentVariants.has(v) ? icons[v] : null;
+// `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";
+// The author's icon, as Alert draws it; else the variant's (`plain` has none)
+const icon = (iconName ? resolveIcon(iconName) : null) ?? (contentVariants.has(v) ? icons[v] : null);
+const fallbackTitle = title || v.charAt(0).toUpperCase() + v.slice(1);
 ---
 
+{/*
+  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}
+  {...rest}
 >
   <summary class:list={[
     "flex cursor-pointer items-center gap-2 px-4 py-3 text-sm font-semibold select-none",
     titleBg[v],
   ]}>
     {icon && <span class:list={["shrink-0 [&>svg]:size-4", iconColor[v]]} set:html={icon} />}
-    <span class="flex-1 text-foreground" data-part="title">{title || v.charAt(0).toUpperCase() + v.slice(1)}</span>
+    <span class="flex-1 text-foreground" data-part="title"><slot name="title">{fallbackTitle}</slot></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/alert/icon.ts

@@ -1,30 +1,23 @@
 /**
- * Resolve an icon shortcode for the Alert component.
+ * Resolve an icon name for Alert and CollapsibleAlert.
  *
- * Accepts two formats:
- *   - `library:name` — e.g. "lucide:rocket", "material:check-circle", "simple:github"
- *   - bare shortcode — treated as emoji (e.g. "rocket" → 🚀)
+ * The same names as Icon.astro and dogsbay-ssg (`@dogsbay/icons` resolveIcon):
+ *   - `pack:name` — e.g. "lucide:rocket", "material:check-circle", "simple:github"
+ *   - a bare name — an emoji shortcode first ("rocket" → 🚀), then a Lucide icon ("compass")
  *
  * Returns an inline SVG string or a span with the emoji character. Returns
- * null when the shortcode can't be resolved (caller should fall back to the
+ * null when the name can't be resolved (caller should fall back to the
  * variant's default icon).
  */
-import { createIconRegistry } from "@dogsbay/icons";
-
-const registry = createIconRegistry();
+import { resolveIcon as resolveName } from "@dogsbay/icons";
 
 export function resolveIcon(shortcode: string): string | null {
-  const colonIdx = shortcode.indexOf(":");
-  const [library, name] = colonIdx >= 0
-    ? [shortcode.slice(0, colonIdx), shortcode.slice(colonIdx + 1)]
-    : ["emoji", shortcode];
-
-  const resolved = registry.resolve(library, name);
+  const resolved = resolveName(shortcode);
   if (!resolved) return null;
 
   // Emoji resolve to Unicode characters; wrap for consistent sizing/positioning
   // with the SVG icons in the Alert layout.
-  if (library === "emoji") {
+  if (!resolved.startsWith("<")) {
     return `<span aria-hidden="true" style="font-size:1em;line-height:1;display:inline-block;width:1em;text-align:center;">${resolved}</span>`;
   }
 

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/api-layout/ExampleBlock.astro

@@ -55,9 +55,10 @@ const content = code || (json !== undefined && json !== null ? JSON.stringify(js
 
 {content && (
   <div class={className}>
-    <h3 class="mb-3 text-xs font-semibold uppercase tracking-wider text-white/60">
+    {/* A label, not a heading: on an operation page it followed the h1 (axe heading-order). */}
+    <p class="mb-3 text-xs font-semibold uppercase tracking-wider text-white/60">
       {title}
-    </h3>
+    </p>
     <CodeBlock code={content} lang={resolvedLang} copy={true} />
   </div>
 )}

package/src/api-params/ApiParams.astro

@@ -57,7 +57,7 @@ function splitCodeBlocks(html: string): Segment[] {
 }
 ---
 
-<table class="api-params w-full text-sm border-collapse not-prose">
+<table class="api-params w-full text-sm border-collapse">
   <thead>
     <tr class="border-b border-border">
       <th class="py-3 px-4 text-left font-semibold text-muted-foreground uppercase tracking-wider text-xs w-[140px]">Parameter</th>

package/src/api-symbol/ApiSymbol.astro

@@ -18,7 +18,7 @@ const slug = name.toLowerCase().replace(/[^\w]/g, "-").replace(/-+/g, "-");
 const HeadingTag = `h${level}` as any;
 ---
 
-<div class="api-symbol not-prose" data-kind={kind}>
+<div class="api-symbol" data-kind={kind}>
   <div class="api-symbol-heading">
     <span class={`api-badge api-badge-${badgeKind}`}>{badgeKind}</span>
     <HeadingTag id={slug} class="!mt-0 !mb-0 !border-0">

package/src/api-symbol/api-symbol.css

@@ -1,4 +1,7 @@
-/* API Symbol badges — colored by kind */
+/* API Symbol badges, coloured by kind. Text on its own 20% tint must reach
+   WCAG AA (4.5:1) on the page background: the light colours were L 0.5–0.6
+   (3.2–4.0:1) and are L 0.44 (5.0:1 or more); render-html's
+   tests/contrast.test.ts measures every kind in both modes. */
 .api-badge {
   display: inline-flex;
   align-items: center;
@@ -13,8 +16,8 @@
 }
 
 .api-badge-class {
-  background-color: oklch(0.55 0.18 265 / 0.2);
-  color: oklch(0.55 0.18 265);
+  background-color: oklch(0.44 0.18 265 / 0.2);
+  color: oklch(0.44 0.18 265);
 }
 .dark .api-badge-class {
   background-color: oklch(0.7 0.15 265 / 0.2);
@@ -22,8 +25,8 @@
 }
 
 .api-badge-meth {
-  background-color: oklch(0.55 0.15 155 / 0.2);
-  color: oklch(0.55 0.15 155);
+  background-color: oklch(0.44 0.15 155 / 0.2);
+  color: oklch(0.44 0.15 155);
 }
 .dark .api-badge-meth {
   background-color: oklch(0.7 0.15 155 / 0.2);
@@ -31,8 +34,8 @@
 }
 
 .api-badge-attr {
-  background-color: oklch(0.6 0.15 55 / 0.2);
-  color: oklch(0.6 0.15 55);
+  background-color: oklch(0.44 0.15 55 / 0.2);
+  color: oklch(0.44 0.15 55);
 }
 .dark .api-badge-attr {
   background-color: oklch(0.75 0.15 55 / 0.2);
@@ -40,8 +43,8 @@
 }
 
 .api-badge-func {
-  background-color: oklch(0.55 0.18 330 / 0.2);
-  color: oklch(0.55 0.18 330);
+  background-color: oklch(0.44 0.18 330 / 0.2);
+  color: oklch(0.44 0.18 330);
 }
 .dark .api-badge-func {
   background-color: oklch(0.7 0.15 330 / 0.2);
@@ -49,8 +52,8 @@
 }
 
 .api-badge-module {
-  background-color: oklch(0.5 0.12 200 / 0.2);
-  color: oklch(0.5 0.12 200);
+  background-color: oklch(0.44 0.12 200 / 0.2);
+  color: oklch(0.44 0.12 200);
 }
 .dark .api-badge-module {
   background-color: oklch(0.65 0.12 200 / 0.2);

package/src/avatar/Avatar.astro

@@ -30,16 +30,20 @@ const initials =
     .join("")
     .slice(0, 2)
     .toUpperCase();
+// The name is on the avatar itself, so it is read whether the image loads, fails or was never given:
+// the initials stand in visually only, and a failed image is hidden with its alt.
+// An author's own aria-label wins (an empty one does not); the role is ours, as in render-html.
+const label = alt ? { role: "img", "aria-label": (rest["aria-label"] as string | undefined) || alt } : {};
 ---
 
-<span class={avatar({ class: className })} {...rest}>
+<span class={avatar({ class: className })} {...rest} {...label}>
   {
     src ? (
       <>
         <img
           class={avatarImage()}
           src={src}
-          alt={alt}
+          alt=""
           width="40"
           height="40"
           onerror="this.hidden=true;this.nextElementSibling.hidden=false"

package/src/badge/Badge.astro

@@ -1,17 +1,10 @@
 ---
 import { tv, type VariantProps } from "tailwind-variants";
+import { BADGE_BASE, BADGE_VARIANTS } from "./variants.js";
 
 const badge = tv({
-  base: "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors",
-  variants: {
-    variant: {
-      default: "border-transparent bg-primary text-primary-foreground",
-      secondary: "border-transparent bg-secondary text-secondary-foreground",
-      destructive:
-        "border-transparent bg-destructive text-destructive-foreground",
-      outline: "text-foreground",
-    },
-  },
+  base: BADGE_BASE,
+  variants: { variant: BADGE_VARIANTS },
   defaultVariants: {
     variant: "default",
   },

package/src/badge/variants.ts

@@ -0,0 +1,39 @@
+/**
+ * Badge classes, shared by Badge.astro, ContentRenderer and @dogsbay/render-html
+ * (which copies this file with scripts/sync-sources.mjs), so a badge
+ * looks the same however a page is produced.
+ */
+export const BADGE_BASE =
+  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors";
+
+export const BADGE_VARIANTS = {
+  default: "border-transparent bg-primary text-primary-foreground",
+  secondary: "border-transparent bg-secondary text-secondary-foreground",
+  destructive: "border-transparent bg-destructive text-destructive-foreground",
+  outline: "text-foreground",
+  // Status colours, from the callout palette (`:badge[Beta]{variant="warning"}`).
+  // The TEXT is the accent mixed 60% toward --foreground; the tint keeps the
+  // accent at full strength. The accent used raw measured 1.85-2.6:1 in light
+  // mode (danger 3.3-3.9:1 in dark too), from painted pixels. --foreground is
+  // near-black in light and near-white in dark, so one rule serves both themes
+  // (worst case 4.95:1); a fixed dark colour would fail dark mode. The same
+  // rule as the in-cell admonitions in format-astro's theme-css.ts.
+  // The `color:` hint is required: tailwind-merge 2.x (Badge.astro's tv())
+  // reads a bare text-[... 60% ...] as a FONT SIZE and drops text-xs.
+  // Checked per preset by @dogsbay/render-html tests/contrast.test.ts, and
+  // through tv() by ui tests/badge.test.ts.
+  info: "border-transparent bg-info/15 text-[color:color-mix(in_oklab,var(--info)_60%,var(--foreground))]",
+  success: "border-transparent bg-success/15 text-[color:color-mix(in_oklab,var(--success)_60%,var(--foreground))]",
+  warning: "border-transparent bg-warning/15 text-[color:color-mix(in_oklab,var(--warning)_60%,var(--foreground))]",
+  danger: "border-transparent bg-danger/15 text-[color:color-mix(in_oklab,var(--danger)_60%,var(--foreground))]",
+} as const;
+
+export type BadgeVariant = keyof typeof BADGE_VARIANTS;
+
+/** The class list for a variant; an unknown variant gets the base classes only. */
+export function badgeClass(variant: string | undefined): string {
+  // Own keys only: `toString` or `__proto__` must not read Object.prototype
+  const key = variant ?? "default";
+  const v = Object.prototype.hasOwnProperty.call(BADGE_VARIANTS, key) ? BADGE_VARIANTS[key as BadgeVariant] : undefined;
+  return v ? `${BADGE_BASE} ${v}` : BADGE_BASE;
+}

package/src/code-block/CodeBlock.astro

@@ -1,5 +1,6 @@
 ---
 import { Code } from "astro/components";
+import { ansiColoursOnly, stripAnsi } from "./ansi";
 import { tv } from "tailwind-variants";
 
 const codeBlockWrapper = tv({
@@ -21,6 +22,10 @@ interface Props {
   lang?: string;
   /** Optional title 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 the header title bar. true = always, false = never, "auto" = only when title prop is set (default: true) */
@@ -42,31 +47,66 @@ 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();
+
+// Tags that mean "no language": no label, as render-html (its PLAIN set, @dogsbay/render-html/lines).
+// Only `plaintext` was hidden, so `txt` and `output` blocks showed "txt" and "output".
+const PLAIN = new Set(["", "text", "txt", "plain", "plaintext", "none", "output", "log", "code", "codeblock"]);
+const plain = PLAIN.has(lang.toLowerCase().trim());
+// An `ansi` block shows its colours, not its escape codes: copy the text as shown
+const isAnsi = shikiLang === "ansi";
+const copyText = isAnsi ? stripAnsi(code) : code;
+// Shiki draws colours only; any other sequence would garble the text (./ansi.ts)
+const shownCode = isAnsi ? ansiColoursOnly(code) : code;
+
 // Show header bar based on showTitle prop:
 // - true: show when there's a title or a declared language (default, original behavior)
 // - false: never show
 // - "auto": only show when an explicit title is provided (not lang-only)
+const hasCaption = Astro.slots.has("caption");
+const Wrapper = hasCaption ? "figure" : "div";
+const Header = hasCaption ? "figcaption" : "div";
 const showHeader =
-  showTitle === false ? false
+  hasCaption ? true
+  : showTitle === false ? false
   : showTitle === "auto" ? !!title
-  : !!title || lang !== "plaintext";
+  : !!title || !plain;
 // When no header, copy button floats inside the code body
 const floatingCopy = copy && !showHeader;
 ---
 
-<div
-  class={codeBlockWrapper({ class: className })}
+<Wrapper
+  class={codeBlockWrapper({ class: [hasCaption && "m-0", className] })}
   data-component="code-block"
   {...rest}
 >
   {showHeader && (
-    <div class={codeBlockHeader()}>
-      <span class="select-none">{title || lang}</span>
+    <Header class={codeBlockHeader()}>
+      {/*
+        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) && !plain && <span class="select-none" data-part="language">{lang}</span>}
       {copy && (
         <button
           class={codeBlockCopy()}
           data-part="copy"
-          data-copy-text={code}
+          data-copy-text={copyText}
           type="button"
           aria-label="Copy code"
         >
@@ -104,15 +144,16 @@ const floatingCopy = copy && !showHeader;
           </svg>
         </button>
       )}
-    </div>
+      </span>
+    </Header>
   )}
   <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={shownCode} 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"]}
         data-part="copy"
-        data-copy-text={code}
+        data-copy-text={copyText}
         type="button"
         aria-label="Copy code"
       >
@@ -126,7 +167,7 @@ const floatingCopy = copy && !showHeader;
       </button>
     )}
   </div>
-</div>
+</Wrapper>
 
 <script>
   function setupCodeBlockCopy() {

package/src/code-block/ansi.ts

@@ -0,0 +1,31 @@
+/**
+ * A terminal's escape sequences in an `ansi` code block (dogsbay-ssg, 2026-11-04). Shared with
+ * @dogsbay/render-html (copied by its sync-sources as `code-ansi.ts`), so both pipelines show and
+ * copy the same text.
+ *
+ * One pattern, linear (each alternative is a run of one character class with a fixed end):
+ *  - CSI: `ESC [` or the 8-bit `\x9b`, parameters, intermediates, a final byte — or cut off at the
+ *    end of the text;
+ *  - OSC (titles, `ESC ] 8` hyperlinks): to BEL or `ESC \`, or the end of the text;
+ *  - `ESC` + intermediates + a final byte (`ESC ( B`, which `tput sgr0` writes), and any other
+ *    two-byte escape.
+ */
+const SEQUENCE = /(?:\x1b\[|\x9b)[0-?]*[ -/]*(?:[@-~]|$)|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\|$)|\x1b[ -/]*[0-~]?/g;
+
+/** Is this sequence a colour or style (SGR, `ESC [ … m`), the only kind a highlighter draws? */
+const SGR = /^(?:\x1b\[|\x9b)[0-9;:]*m$/;
+
+/** The text as a terminal shows it, every escape sequence left out (plain rendering, copy). */
+export function stripAnsi(s: string): string {
+  return s.replace(SEQUENCE, "");
+}
+
+/**
+ * Only the colour and style sequences kept, for Shiki's `ansi`: it reads `ESC [` as running to the
+ * next `m`, so `ESC [2K` (erase line) ate the next letters (`Compiling` → `piling`), and it shows
+ * an OSC hyperlink's bytes as text. What is left is what it draws correctly. 8-bit CSI is written
+ * in its 7-bit form.
+ */
+export function ansiColoursOnly(s: string): string {
+  return s.replace(SEQUENCE, (m) => (SGR.test(m) ? m.replace(/^\x9b/, "\x1b[") : ""));
+}