@elabs-ai/components-ai 4.0.0

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@elabs-ai/components-ai",
+  "version": "4.0.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mreimitz/elabs-components.git",
+    "directory": "packages/ai"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@radix-ui/react-use-controllable-state": "^1.2.2",
+    "@rive-app/react-webgl2": "^4.26.1",
+    "@streamdown/cjk": "^1.0.2",
+    "@streamdown/code": "^1.1.0",
+    "@streamdown/math": "^1.0.2",
+    "@streamdown/mermaid": "^1.0.2",
+    "mermaid": "^11.12.2",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "ansi-to-react": "^6.2.6",
+    "class-variance-authority": "^0.7.1",
+    "lucide-react": "^0.577.0",
+    "media-chrome": "^4.17.2",
+    "motion": "^12.26.2",
+    "nanoid": "^5.1.6",
+    "react-jsx-parser": "^2.2.0",
+    "shiki": "^3.22.0",
+    "streamdown": "^2.4.0",
+    "tokenlens": "^1.3.1",
+    "use-stick-to-bottom": "^1.1.3",
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "@xyflow/react": "^12.11.1",
+    "ai": "^6.0.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0",
+    "@elabs-ai/components-tokens": "4.0.0",
+    "@elabs-ai/components-ui": "4.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/react": "^19.0.2",
+    "@types/react-dom": "^19.0.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "@xyflow/react": "^12.11.1",
+    "ai": "^6.0.0",
+    "eslint": "^9.17.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.2",
+    "@elabs-ai/components-charts": "4.0.0",
+    "@elabs-ai/components-eslint-config": "0.1.0",
+    "@elabs-ai/components-icons": "4.0.0",
+    "@elabs-ai/components-typescript-config": "0.1.0",
+    "@elabs-ai/components-tokens": "4.0.0",
+    "@elabs-ai/components-ui": "4.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo coverage"
+  }
+}

package/src/_audio-player-media-chrome.tsx

@@ -0,0 +1,146 @@
+"use client";
+
+/**
+ * The media-chrome half of `AudioPlayer`, split out so it can be `lazy()`-loaded.
+ *
+ * `media-chrome` declares no `sideEffects`, so a static import from
+ * `audio-player.tsx` put the whole custom-element library (and the
+ * `media-chrome/react` wrappers that register it) into the entry chunk of every
+ * `@elabs-ai/components-ai` consumer — including the vast majority that
+ * never render an `AudioPlayer`. Keeping every media-chrome *value* import in
+ * this module, reached only through
+ * `lazy(() => import("./_audio-player-media-chrome"))`, confines it to its own
+ * chunk. `audio-player.tsx` still owns the public prop types and imports the
+ * media-chrome element types with `import type` (types erase).
+ *
+ * See ADR 0019 and `pnpm heavy-deps:check`.
+ *
+ * @lazy-boundary This module must only ever be reached via `import()`. The gate
+ * fails if anything imports it statically, which would put media-chrome back in
+ * the entry chunk and make the `lazy()` pointless.
+ */
+import { Button, ButtonGroup, ButtonGroupText } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import {
+  MediaControlBar,
+  MediaController,
+  MediaDurationDisplay,
+  MediaMuteButton,
+  MediaPlayButton,
+  MediaSeekBackwardButton,
+  MediaSeekForwardButton,
+  MediaTimeDisplay,
+  MediaTimeRange,
+  MediaVolumeRange,
+} from "media-chrome/react";
+import type { CSSProperties } from "react";
+
+import type {
+  AudioPlayerControlBarProps,
+  AudioPlayerDurationDisplayProps,
+  AudioPlayerMuteButtonProps,
+  AudioPlayerPlayButtonProps,
+  AudioPlayerProps,
+  AudioPlayerSeekBackwardButtonProps,
+  AudioPlayerSeekForwardButtonProps,
+  AudioPlayerTimeDisplayProps,
+  AudioPlayerTimeRangeProps,
+  AudioPlayerVolumeRangeProps,
+} from "./audio-player";
+
+export const AudioPlayer = ({ children, style, ...props }: AudioPlayerProps) => (
+  <MediaController
+    audio
+    style={
+      {
+        "--media-background-color": "transparent",
+        "--media-button-icon-height": "1rem",
+        "--media-button-icon-width": "1rem",
+        "--media-control-background": "transparent",
+        "--media-control-hover-background": "var(--color-accent)",
+        "--media-control-padding": "0",
+        "--media-font": "var(--font-sans)",
+        "--media-font-size": "10px",
+        "--media-icon-color": "currentColor",
+        "--media-preview-time-background": "var(--color-background)",
+        "--media-preview-time-border-radius": "var(--radius-md)",
+        "--media-preview-time-text-shadow": "none",
+        "--media-primary-color": "var(--color-primary)",
+        "--media-range-bar-color": "var(--color-primary)",
+        "--media-range-track-background": "var(--color-secondary)",
+        "--media-secondary-color": "var(--color-secondary)",
+        "--media-text-color": "var(--color-foreground)",
+        "--media-tooltip-arrow-display": "none",
+        "--media-tooltip-background": "var(--color-background)",
+        "--media-tooltip-border-radius": "var(--radius-md)",
+        ...style,
+      } as CSSProperties
+    }
+    {...props}
+  >
+    {children}
+  </MediaController>
+);
+
+export const AudioPlayerControlBar = ({ children, ...props }: AudioPlayerControlBarProps) => (
+  <MediaControlBar {...props}>
+    <ButtonGroup orientation="horizontal">{children}</ButtonGroup>
+  </MediaControlBar>
+);
+
+export const AudioPlayerPlayButton = ({ className, ...props }: AudioPlayerPlayButtonProps) => (
+  <Button asChild size="icon-sm" variant="outline">
+    <MediaPlayButton className={cn("bg-transparent", className)} {...props} />
+  </Button>
+);
+
+export const AudioPlayerSeekBackwardButton = ({
+  seekOffset = 10,
+  ...props
+}: AudioPlayerSeekBackwardButtonProps) => (
+  <Button asChild size="icon-sm" variant="outline">
+    <MediaSeekBackwardButton seekOffset={seekOffset} {...props} />
+  </Button>
+);
+
+export const AudioPlayerSeekForwardButton = ({
+  seekOffset = 10,
+  ...props
+}: AudioPlayerSeekForwardButtonProps) => (
+  <Button asChild size="icon-sm" variant="outline">
+    <MediaSeekForwardButton seekOffset={seekOffset} {...props} />
+  </Button>
+);
+
+export const AudioPlayerTimeDisplay = ({ className, ...props }: AudioPlayerTimeDisplayProps) => (
+  <ButtonGroupText asChild className="bg-transparent">
+    <MediaTimeDisplay className={cn("tabular-nums", className)} {...props} />
+  </ButtonGroupText>
+);
+
+export const AudioPlayerTimeRange = ({ className, ...props }: AudioPlayerTimeRangeProps) => (
+  <ButtonGroupText asChild className="bg-transparent">
+    <MediaTimeRange className={cn("", className)} {...props} />
+  </ButtonGroupText>
+);
+
+export const AudioPlayerDurationDisplay = ({
+  className,
+  ...props
+}: AudioPlayerDurationDisplayProps) => (
+  <ButtonGroupText asChild className="bg-transparent">
+    <MediaDurationDisplay className={cn("tabular-nums", className)} {...props} />
+  </ButtonGroupText>
+);
+
+export const AudioPlayerMuteButton = ({ className, ...props }: AudioPlayerMuteButtonProps) => (
+  <ButtonGroupText asChild className="bg-transparent">
+    <MediaMuteButton className={cn("", className)} {...props} />
+  </ButtonGroupText>
+);
+
+export const AudioPlayerVolumeRange = ({ className, ...props }: AudioPlayerVolumeRangeProps) => (
+  <ButtonGroupText asChild className="bg-transparent">
+    <MediaVolumeRange className={cn("", className)} {...props} />
+  </ButtonGroupText>
+);

package/src/_chat-shell-rail.tsx

@@ -0,0 +1,18 @@
+import { FileText, Sparkles } from "lucide-react";
+
+/** Sample context rail for the Chat Shell story. */
+export function ContextPanelRail() {
+  return (
+    <div className="flex h-full flex-col bg-surface">
+      <div className="flex h-12 items-center border-b px-4 text-sm font-semibold">Context</div>
+      <div className="space-y-2 p-3 text-sm">
+        <div className="flex items-center gap-2 rounded-md border bg-card p-2">
+          <FileText className="size-4 text-muted-foreground" /> Deploy log — wk 23
+        </div>
+        <div className="flex items-center gap-2 rounded-md border bg-card p-2">
+          <Sparkles className="size-4 text-muted-foreground" /> Billing runbook
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/_code-block-theme.test.ts

@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { buildCodeBlockTheme, codeBlockThemeId, getThemeScopeKey } from "./_code-block-theme";
+
+afterEach(() => {
+  document.documentElement.removeAttribute("data-theme");
+  document.documentElement.removeAttribute("style");
+});
+
+// #315 blocker fix — the highlight-cache scoping key must NOT collapse "no
+// data-theme attribute" and an explicit "data-theme=light" into the same value,
+// or the pre-ThemeProvider-mount render's `:root`-tokenized colors would poison
+// the cache under the key ThemeProvider later writes explicitly.
+describe("getThemeScopeKey", () => {
+  it("returns a distinct sentinel when no data-theme attribute is set", () => {
+    expect(getThemeScopeKey()).toBe("__root__");
+  });
+
+  it("returns the RAW attribute value when data-theme is set", () => {
+    document.documentElement.setAttribute("data-theme", "light");
+    expect(getThemeScopeKey()).toBe("light");
+  });
+
+  it("differs between unset and explicit light (the exact collision the fix closes)", () => {
+    const unset = getThemeScopeKey();
+    document.documentElement.setAttribute("data-theme", "light");
+    expect(unset).not.toBe(getThemeScopeKey());
+  });
+
+  // ADR 0029 — theme names are open, so an unrecognized name is a CONSUMER
+  // theme, not an error. It must get its own cache bucket (it has its own
+  // `--code-*` values); the pre-0029 code narrowed it away to the default,
+  // which would have served a consumer theme the light theme's tokens.
+  it("gives an unregistered (consumer) theme its own bucket", () => {
+    document.documentElement.setAttribute("data-theme", "midnight");
+    expect(getThemeScopeKey()).toBe("midnight");
+    expect(codeBlockThemeId(getThemeScopeKey())).toBe("brand-code-midnight");
+  });
+});
+
+describe("codeBlockThemeId", () => {
+  it("namespaces the theme name so it can't collide with a bundled Shiki theme", () => {
+    expect(codeBlockThemeId("light")).toBe("brand-code-light");
+    expect(codeBlockThemeId("dark")).toBe("brand-code-dark");
+  });
+});
+
+describe("buildCodeBlockTheme", () => {
+  it("derives colors from the active theme's --code-* custom properties, not a github-* literal", () => {
+    document.documentElement.setAttribute("data-theme", "light");
+    document.documentElement.style.setProperty("--code-background", "oklch(1 0 0)");
+    document.documentElement.style.setProperty("--code-foreground", "oklch(0.21 0.02 264)");
+    document.documentElement.style.setProperty("--code-keyword", "oklch(0.38 0.16 264)");
+    document.documentElement.style.setProperty("--code-string", "oklch(0.42 0.14 150)");
+
+    const theme = buildCodeBlockTheme();
+
+    expect(theme.name).toBe("brand-code-light");
+    expect(theme.bg).toBe("#ffffff");
+    expect(theme.fg).toMatch(/^#[0-9a-f]{6}$/);
+    // Never the hardcoded third-party palette (#315).
+    expect(JSON.stringify(theme)).not.toMatch(/github/i);
+
+    const keywordRule = theme.settings?.find((s) => {
+      const scope = s.scope;
+      return Array.isArray(scope) ? scope.includes("keyword") : scope === "keyword";
+    });
+    expect(keywordRule?.settings.foreground).toMatch(/^#[0-9a-f]{6}$/);
+    expect(keywordRule?.settings.foreground).not.toBe(theme.fg);
+  });
+
+  // #315 blocker fix — `theme.name` (the highlight-cache key) must differ
+  // between "no data-theme attribute" and an explicit "light", even
+  // though both resolve to the same light/dark flag.
+  it("gives the unset-attribute render a distinct theme name from explicit light", () => {
+    const unset = buildCodeBlockTheme();
+    expect(unset.name).toBe("brand-code-__root__");
+
+    document.documentElement.setAttribute("data-theme", "light");
+    const explicitBright = buildCodeBlockTheme();
+    expect(explicitBright.name).toBe("brand-code-light");
+    expect(explicitBright.name).not.toBe(unset.name);
+
+    // Both are still "light" — the collision was in the CACHE KEY, not the flag.
+    expect(unset.type).toBe("light");
+    expect(explicitBright.type).toBe("light");
+  });
+
+  it("marks dark as a dark Shiki theme (color-scheme-driven, not guessed)", () => {
+    document.documentElement.setAttribute("data-theme", "dark");
+    const theme = buildCodeBlockTheme();
+    expect(theme.type).toBe("dark");
+  });
+
+  it("marks light as a light Shiki theme", () => {
+    document.documentElement.setAttribute("data-theme", "light");
+    const theme = buildCodeBlockTheme();
+    expect(theme.type).toBe("light");
+  });
+
+  it("re-derives different colors when the active theme changes", () => {
+    document.documentElement.setAttribute("data-theme", "light");
+    document.documentElement.style.setProperty("--code-keyword", "oklch(0.38 0.16 264)");
+    const bright = buildCodeBlockTheme();
+
+    document.documentElement.setAttribute("data-theme", "dark");
+    document.documentElement.style.setProperty("--code-keyword", "oklch(0.7 0.16 264)");
+    const dark = buildCodeBlockTheme();
+
+    const keywordOf = (theme: typeof bright) =>
+      theme.settings?.find(
+        (s) => s.scope === "keyword" || (s.scope as string[])?.includes?.("keyword"),
+      )?.settings.foreground;
+
+    expect(keywordOf(bright)).not.toBe(keywordOf(dark));
+  });
+
+  // #315 follow-up — the theme id/type and the resolved colors must ALWAYS
+  // come from the SAME element, so a region-scoped `data-theme` (a supported
+  // ThemeProvider/decorator pattern, see @.claude/rules/theming.md) resolves
+  // ITS OWN theme, never the document root's, and the two can never disagree.
+  it("resolves a region-scoped data-theme (not the document root's) when passed that region's element", () => {
+    document.documentElement.setAttribute("data-theme", "light");
+    const region = document.createElement("div");
+    region.setAttribute("data-theme", "dark");
+    document.body.appendChild(region);
+
+    const theme = buildCodeBlockTheme(region);
+    expect(theme.name).toBe("brand-code-dark");
+    expect(theme.type).toBe("dark"); // the region's theme, not light's "light"
+
+    document.body.removeChild(region);
+  });
+});

package/src/_code-block-theme.ts

@@ -0,0 +1,184 @@
+/**
+ * _code-block-theme — derives a Shiki theme from brand-ui's `--code-*` tokens
+ * instead of a hardcoded `github-light`/`github-dark` literal (issue #315).
+ *
+ * Shiki can't read CSS custom properties at tokenize time, so — the same
+ * "wrap an engine, theme it from tokens" pattern as `@elabs-ai/components-editor`'s
+ * Monaco bridge (`monaco-theme-bridge.ts`), `@elabs-ai/components-maps`' `useTokenColor`,
+ * and this package's own `buildInteractiveTerminalTheme` — this module reads the
+ * ACTIVE theme's resolved token colors at call time via `resolveTokenColor`
+ * (`@elabs-ai/components-tokens`, ADR 0015: oklch → hex, no canvas needed since every
+ * `--code-*` token is authored as `oklch()`) and builds a single Shiki
+ * `ThemeRegistrationRaw` that matches whatever brand theme is currently active
+ * — including a low-chroma monochrome ink palette, never a recolored GitHub
+ * theme. Callers re-derive (and re-highlight) whenever `data-theme` changes;
+ * see `code-block.tsx`'s `data-theme` MutationObserver.
+ *
+ * `buildCodeBlockTheme` takes a single `el` (default `<html>`) and derives BOTH
+ * the theme id/type AND the resolved colors from that SAME element — never a
+ * separately-requested theme name. A CodeBlock nested inside a region-scoped
+ * `<div data-theme="dark">` (a supported `ThemeProvider`/decorator pattern,
+ * see @.claude/rules/theming.md) resolves ITS region's theme this way: pass a
+ * descendant of that region as `el` and the id/type/colors all agree by
+ * construction (there is no "themeName" parameter that could disagree with what
+ * `el` actually renders).
+ *
+ * The highlight-cache key (`codeBlockThemeId`, consumed by `code-block.tsx`'s
+ * `getTokensCacheKey`) is keyed on `getThemeScopeKey` — the RAW `data-theme`
+ * attribute — and must NOT be collapsed to a validated/normalized theme name.
+ * This matters: "no `data-theme` attribute yet" (the first render, before
+ * `ThemeProvider` mounts and writes the attribute) and an EXPLICIT
+ * `data-theme="light"` are DIFFERENT palettes, because `:root`'s fallback
+ * `--code-*` values are intentionally their OWN neutral placeholder theme, not
+ * a byte-identical copy of `[data-theme="light"]`'s (see `themes.css`'s
+ * "`:root` holds the DEFAULT (light) theme" header — a deliberately distinct
+ * palette, not an alias). If the cache key normalized "unset" to "light", a
+ * code block that first tokenizes before `ThemeProvider` mounts would cache
+ * `:root`'s colors under the SAME key `ThemeProvider` later writes explicitly
+ * — so the (correct) `light` colors would never take effect; the cache hit
+ * would return the stale `:root` colors forever (#315 follow-up). Keying on the
+ * raw attribute gives "no attribute" and "light" distinct cache entries, so the
+ * mutation from one to the other is a genuine cache miss and re-tokenizes.
+ *
+ * ADR 0029 removed the `getActiveThemeName` helper this file used to export.
+ * Theme names are open now, so "narrow the attribute to a known theme" is not a
+ * meaningful operation — a consumer theme is as real as a shipped one. The two
+ * things it was used for are both answered off the element directly:
+ * `resolveThemeIsDark(el)` for the light/dark `type`, and `resolveTokenColor`
+ * for the colors.
+ */
+
+import { resolveThemeIsDark, resolveTokenColor } from "@elabs-ai/components-tokens";
+import type { ThemeRegistrationRaw } from "shiki";
+
+const FALLBACK_BACKGROUND = "#ffffff";
+const FALLBACK_FOREGROUND = "#111111";
+/** Cache-key sentinel for "no `data-theme` attribute present" — see `getThemeScopeKey`. */
+const ROOT_SCOPE_KEY = "__root__";
+
+/**
+ * Reads the RAW `data-theme` attribute off `el` (default `<html>`) — or the
+ * `"__root__"` sentinel when the attribute is absent. It deliberately does NOT
+ * collapse "unset" and "explicit light" into one value (see the module comment),
+ * and it never validates the name against a registry: a consumer theme gets its
+ * own cache bucket, which is exactly right — it has its own `--code-*` values.
+ */
+export function getThemeScopeKey(el?: Element | null): string {
+  const root = el ?? (typeof document !== "undefined" ? document.documentElement : null);
+  return root?.getAttribute("data-theme") || ROOT_SCOPE_KEY;
+}
+
+/** Shiki theme `name` for a given theme-scope key — also the highlight-cache key. */
+export function codeBlockThemeId(scopeKey: string): string {
+  return `brand-code-${scopeKey}`;
+}
+
+/**
+ * Builds a Shiki `ThemeRegistrationRaw` from the resolved `--code-*` tokens of
+ * whichever brand theme is active on `el` (default `<html>`). The theme id, its
+ * light/dark `type` and its colors are ALL derived from THIS SAME element, so
+ * they can never disagree. `type` comes from `resolveThemeIsDark` (the theme's
+ * own `color-scheme`) rather than a registry lookup, so a consumer-authored
+ * theme gets the right Shiki type without registering here (ADR 0029). Scopes
+ * follow the common TextMate categories Shiki's bundled grammars emit across
+ * languages.
+ */
+export function buildCodeBlockTheme(el?: Element | null): ThemeRegistrationRaw {
+  const root = el ?? (typeof document !== "undefined" ? document.documentElement : null);
+  const read = (name: string, fallback: string) => resolveTokenColor(name, { el: root, fallback });
+
+  const background = read("--code-background", FALLBACK_BACKGROUND);
+  const foreground = read("--code-foreground", FALLBACK_FOREGROUND);
+  const comment = read("--code-comment", foreground);
+  const string_ = read("--code-string", foreground);
+  const number = read("--code-number", foreground);
+  const constant = read("--code-constant", foreground);
+  const keyword = read("--code-keyword", foreground);
+  const func = read("--code-function", foreground);
+  const type = read("--code-type", foreground);
+  const tag = read("--code-tag", foreground);
+  const property = read("--code-property", foreground);
+
+  return {
+    // Keyed on the RAW scope, not the validated name — see the module doc
+    // comment + `getThemeScopeKey` for why "unset" and "light" must get
+    // different cache buckets.
+    name: codeBlockThemeId(getThemeScopeKey(root)),
+    type: resolveThemeIsDark(root) ? "dark" : "light",
+    bg: background,
+    fg: foreground,
+    colors: {
+      "editor.background": background,
+      "editor.foreground": foreground,
+    },
+    settings: [
+      { settings: { foreground } },
+      {
+        scope: ["comment", "punctuation.definition.comment"],
+        settings: { foreground: comment, fontStyle: "italic" },
+      },
+      {
+        scope: ["string", "string.quoted", "string.template", "punctuation.definition.string"],
+        settings: { foreground: string_ },
+      },
+      {
+        scope: ["constant.numeric", "constant.character", "constant.character.escape"],
+        settings: { foreground: number },
+      },
+      {
+        scope: ["constant.language", "constant.other", "support.constant"],
+        settings: { foreground: constant },
+      },
+      {
+        scope: [
+          "keyword",
+          "keyword.control",
+          "keyword.operator",
+          "storage.type",
+          "storage.modifier",
+        ],
+        settings: { foreground: keyword },
+      },
+      {
+        scope: [
+          "entity.name.function",
+          "support.function",
+          "meta.function-call",
+          "variable.function",
+        ],
+        settings: { foreground: func },
+      },
+      {
+        scope: [
+          "entity.name.type",
+          "entity.name.class",
+          "support.type",
+          "support.class",
+          "entity.other.inherited-class",
+        ],
+        settings: { foreground: type },
+      },
+      {
+        scope: ["entity.name.tag", "punctuation.definition.tag"],
+        settings: { foreground: tag },
+      },
+      {
+        scope: [
+          "entity.other.attribute-name",
+          "variable.other.property",
+          "meta.object-literal.key",
+          "support.type.property-name",
+        ],
+        settings: { foreground: property },
+      },
+      // Deliberately NO `invalid`/`invalid.illegal` rule here (#315 follow-up):
+      // it used to alias to the SAME color as `tag`, so a perfectly valid
+      // <div>/JSX tag — the most common markup element in the languages this
+      // component renders — was indistinguishable from genuinely broken syntax.
+      // Leaving the scope unmapped falls through to the base `{ settings:
+      // { foreground } }` rule above (Shiki/TextMate cascade), same as most
+      // grammars' own default. If a dedicated "this token is invalid" highlight
+      // is ever wanted, it needs its OWN `--code-*` token, not a reuse of `tag`.
+    ],
+  };
+}