@elabs-ai/components-editor 4.0.0 → 4.1.0

package/src/lib/monaco-theme-bridge.test.ts

@@ -0,0 +1,307 @@
+/**
+ * monaco-theme-bridge.test.ts — locks #88: Monaco composites a translucent
+ * `editor.lineHighlightBackground` UNDER every token's text on the cursor's
+ * line, so the REAL, on-screen ground a syntax color renders against on that
+ * line is `flattenOver(lineHighlight, background)`, not the bare
+ * `--background`. `buildBrandThemeData()` used to AA-clamp every rule's
+ * foreground against the bare background alone, so a rule could pass its own
+ * nominal check and still fail WCAG AA once Monaco actually painted it.
+ *
+ * This derives REAL numbers from the shipped theme tokens (parsed straight out
+ * of `packages/tokens/src/themes/{light,dark}.css`, the same technique
+ * `packages/tokens/src/themes-contrast.test.ts` uses) rather than asserting on
+ * a hand-picked ratio — before the fix this fails at `token: "string"` in the
+ * `light` theme (measured ~4.16:1 against the composited ground, short of the
+ * 4.5:1 AA bar); after the fix every rule clears its bar in both themes.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { TokenTheme } from "monaco-editor/esm/vs/editor/common/languages/supports/tokenization.js";
+import { vs, vs_dark } from "monaco-editor/esm/vs/editor/standalone/common/themes.js";
+
+import {
+  buildBrandThemeData,
+  contrast,
+  flattenOver,
+  IGNORED_BASE_SCOPES,
+  LINE_HIGHLIGHT_ALPHA,
+  withAlpha,
+} from "./monaco-theme-bridge";
+
+type ThemeSlug = "light" | "dark";
+
+/**
+ * Resolve `packages/tokens/src/themes/<theme>.css` regardless of whether the
+ * test runner's cwd is this package (`pnpm --filter … test`) or the repo root
+ * (`pnpm test` via Turborepo) — same multi-candidate approach as
+ * `packages/ai/src/dark-theme-variant.test.ts`.
+ */
+function themeCssPath(theme: ThemeSlug): string {
+  const candidates = [
+    resolve(process.cwd(), `../tokens/src/themes/${theme}.css`), // cwd = packages/editor
+    resolve(process.cwd(), `packages/tokens/src/themes/${theme}.css`), // cwd = repo root
+    resolve(process.cwd(), `../../packages/tokens/src/themes/${theme}.css`),
+  ].find((candidate) => existsSync(candidate));
+  if (!candidates) {
+    throw new Error(`themes/${theme}.css not found from cwd ${process.cwd()}`);
+  }
+  return candidates;
+}
+
+/**
+ * All `--token: oklch(...)` declarations in a `[data-theme="name"]` block,
+ * with single-level `var(--other)` aliases resolved (`--chart-1`/`--ring` both
+ * alias `--primary` in the shipped themes) — same technique as
+ * `themes-contrast.test.ts`'s `tokenMap`.
+ */
+function tokenMap(theme: ThemeSlug): Record<string, string> {
+  const css = readFileSync(themeCssPath(theme), "utf8");
+  const block = css.match(new RegExp(`\\[data-theme="${theme}"\\]\\s*\\{([\\s\\S]*?)\\n\\}`))?.[1];
+  if (block == null) {
+    throw new Error(`[data-theme="${theme}"] block not found in ${theme}.css`);
+  }
+  const literals: Record<string, string> = {};
+  const aliases: Record<string, string> = {};
+  for (const m of block.matchAll(/(--[\w-]+):\s*(oklch\([^;]+\)|var\(\s*--[\w-]+\s*\))\s*;/g)) {
+    const name = m[1];
+    const value = m[2]?.trim();
+    if (name == null || value == null) continue;
+    if (value.startsWith("var(")) {
+      const target = value.match(/var\(\s*(--[\w-]+)\s*\)/)?.[1];
+      if (target != null) aliases[name] = target;
+    } else {
+      literals[name] = value;
+    }
+  }
+  const map: Record<string, string> = { ...literals };
+  for (const [name, firstTarget] of Object.entries(aliases)) {
+    let target: string | undefined = firstTarget;
+    const seen = new Set<string>([name]);
+    while (target != null && !seen.has(target)) {
+      seen.add(target);
+      const literal = literals[target];
+      if (literal != null) {
+        map[name] = literal;
+        break;
+      }
+      target = aliases[target];
+    }
+  }
+  return map;
+}
+
+// Every semantic token `buildBrandThemeData` reads (see monaco-theme-bridge.ts).
+const TOKEN_NAMES = [
+  "--background",
+  "--foreground",
+  "--muted",
+  "--muted-foreground",
+  "--border",
+  "--primary",
+  "--ring",
+  "--ring-contour",
+  "--popover",
+  "--popover-foreground",
+  "--input",
+  "--chart-1",
+  "--chart-2",
+  "--chart-3",
+  "--chart-4",
+  "--success",
+  "--destructive",
+  "--calc-result",
+  "--warning",
+] as const;
+
+afterEach(() => {
+  document.documentElement.removeAttribute("style");
+});
+
+/** Build real Monaco theme data from the shipped `theme`'s actual tokens, on a
+ * DETACHED element (never appended to `document`) so this is pure token → theme
+ * math with no dependency on any particular DOM/render state. */
+function buildThemeDataFor(theme: ThemeSlug) {
+  const tokens = tokenMap(theme);
+  const el = document.createElement("div");
+  for (const name of TOKEN_NAMES) {
+    const value = tokens[name];
+    if (value != null) el.style.setProperty(name, value);
+  }
+  return buildBrandThemeData(el);
+}
+
+// `comment`/`delimiter` are intentionally softer (3.2:1, "muted but legible");
+// every other rule with a foreground targets full AA (4.5:1).
+const SOFT_RATIO_TOKENS = new Set(["comment", "delimiter"]);
+
+describe.each<ThemeSlug>(["light", "dark"])("buildBrandThemeData (%s)", (theme) => {
+  const data = buildThemeDataFor(theme);
+  const colors = data.colors;
+  const background = colors["editor.background"]!;
+  const foreground = colors["editor.foreground"]!;
+  const lineHighlight = colors["editor.lineHighlightBackground"]!;
+
+  it("derives editor.lineHighlightBackground from the exported LINE_HIGHLIGHT_ALPHA expression (no drift)", () => {
+    // If the overlay Monaco actually paints (`colors["editor.lineHighlightBackground"]`)
+    // is ever computed from a DIFFERENT alpha/expression than the one used to
+    // derive the ground syntax colors are clamped against, this catches it —
+    // both must be `withAlpha(foreground, LINE_HIGHLIGHT_ALPHA)`.
+    expect(lineHighlight).toBe(withAlpha(foreground, LINE_HIGHLIGHT_ALPHA));
+  });
+
+  it("AA-clamps every syntax rule's foreground against the COMPOSITED line-highlight ground, not the bare background (#88)", () => {
+    // The real, on-screen ground for text painted on the cursor's line: Monaco
+    // renders `editor.lineHighlightBackground` UNDER the token text there.
+    const tokenGround = flattenOver(lineHighlight, background);
+
+    const failures: string[] = [];
+    for (const rule of data.rules ?? []) {
+      if (!rule.foreground) continue;
+      const minRatio = SOFT_RATIO_TOKENS.has(rule.token) ? 3.2 : 4.5;
+      const ratio = contrast(`#${rule.foreground}`, tokenGround);
+      if (ratio < minRatio) {
+        failures.push(
+          `token "${rule.token || "(base)"}" measures ${ratio.toFixed(2)}:1 against the ` +
+            `composited line-highlight ground, needs >= ${minRatio}:1`,
+        );
+      }
+    }
+    expect(failures).toEqual([]);
+  });
+
+  it("gives Monaco's focusBorder a layer of the compound indicator that clears 1.4.11 (#67)", () => {
+    // Monaco's `focusBorder` is a SINGLE colour key, so it cannot carry the DOM's
+    // two-layer `focus-ring` (ring + `--ring-contour` outline). It must therefore be
+    // whichever layer actually clears the non-text 3:1 bar against the editor ground.
+    // Before the fix this was hard-wired to `--ring`, which on `light` IS `--primary`
+    // and measures ~1.36:1 — a focus indicator nobody can see.
+    const focusBorder = colors.focusBorder!;
+    expect(contrast(focusBorder, background)).toBeGreaterThanOrEqual(3);
+  });
+
+  it("still clamps the calc-result inlay color against the composited ground", () => {
+    const tokenGround = flattenOver(lineHighlight, background);
+    const calcResult = colors["editorInlayHint.foreground"]!;
+    expect(contrast(calcResult, tokenGround)).toBeGreaterThanOrEqual(4.5);
+  });
+});
+
+/**
+ * Locks #90: Monaco's `vs`/`vs-dark` base themes (inherited at
+ * `buildBrandThemeData`'s `inherit: true`) ship LANGUAGE-SUFFIXED rules —
+ * `string.key.json`, `string.value.json`, `keyword.json`, … — that the
+ * bridge's shorter, unsuffixed rules (`string.key`, `string.value`,
+ * `keyword`) can never beat: Monaco's token-theme trie resolves the DEEPEST
+ * matching scope, and rules are sorted lexicographically before insertion, so
+ * `string.key` is always inserted before `string.key.json` regardless of
+ * which array it came from — the base's `.json` child then overwrites the
+ * clone it inherited from our shorter rule.
+ *
+ * This asserts against Monaco's REAL resolution — `TokenTheme` built from
+ * `base.rules.concat(data.rules)`, exactly mirroring
+ * `standaloneThemeService.js`'s `tokenTheme` getter — rather than against the
+ * bridge's returned `rules` array, since the array has ALWAYS looked correct
+ * (the `// JSON keys` comment on `key`/`string.key` records exactly that
+ * mistaken belief). Before the fix this fails on `string.key.json`,
+ * `string.value.json` and `keyword.json` in BOTH bases (`number.json` and
+ * `delimiter.bracket.json` were already branded — `vs`/`vs-dark` don't
+ * specialise those two scopes, so they fall through to the bridge's
+ * unsuffixed `number`/`delimiter` rules even pre-fix); after the fix every
+ * scope below resolves to a brand colour in both bases.
+ */
+describe.each<[ThemeSlug, typeof vs]>([
+  ["light", vs],
+  ["dark", vs_dark],
+])("Monaco real trie resolution (%s base) — #90", (theme, base) => {
+  const data = buildThemeDataFor(theme);
+  // Mirror `standaloneThemeService.js`: `rules = baseData.rules.concat(this.themeData.rules)`.
+  const merged = [...base.rules, ...(data.rules ?? [])];
+  const tokenTheme = TokenTheme.createFromRawTokenTheme(merged, []);
+  const colorMap = tokenTheme.getColorMap();
+
+  const toHexByte = (n: number) => Math.round(n).toString(16).padStart(2, "0").toUpperCase();
+  const resolvedForegroundHex = (scope: string): string | undefined => {
+    const rule = tokenTheme._match(scope);
+    const color = colorMap[rule._foreground];
+    if (!color) return undefined;
+    return `${toHexByte(color.rgba.r)}${toHexByte(color.rgba.g)}${toHexByte(color.rgba.b)}`;
+  };
+
+  // Every foreground the bridge itself declares (uppercased 6-hex, no `#`) —
+  // a scope resolving to one of these IS branded, whatever its numeric colour id.
+  const brandForegrounds = new Set(
+    (data.rules ?? [])
+      .map((rule) => rule.foreground)
+      .filter((fg): fg is string => typeof fg === "string" && fg.length > 0)
+      .map((fg) => fg.toUpperCase()),
+  );
+
+  it.each([
+    "string.key.json",
+    "string.value.json",
+    "keyword.json",
+    "number.json",
+    "delimiter.bracket.json",
+  ])(
+    "scope %s resolves through the real trie to a brand colour, not a stock base colour",
+    (scope) => {
+      const hex = resolvedForegroundHex(scope);
+      expect(hex).toBeDefined();
+      expect(brandForegrounds.has(hex!)).toBe(true);
+    },
+  );
+
+  // PR #119 review thread 2 (chatgpt-codex-connector): `CodeEditorProps.language`
+  // is a plain, unrestricted `string` passed straight to
+  // `monaco.editor.setModelLanguage` (`code-editor.tsx`) — it is NOT limited
+  // to `EDITOR_LANGUAGES`, so a consumer passing `language="pug"` (or
+  // `"handlebars"`) really does reach these scopes. `IGNORED_BASE_SCOPES`'s
+  // old "nothing in this package can ever render them" premise was false for
+  // these three; only `metatag.php` (no `foreground` in the base themes —
+  // nothing to un-brand) is legitimately left out.
+  it.each(["tag.id.pug", "tag.class.pug", "variable.parameter"])(
+    "scope %s (reachable via an unrestricted CodeEditor `language` prop) resolves to a brand colour",
+    (scope) => {
+      const hex = resolvedForegroundHex(scope);
+      expect(hex).toBeDefined();
+      expect(brandForegrounds.has(hex!)).toBe(true);
+    },
+  );
+});
+
+/**
+ * Drift guard (#90): every DOTTED scope Monaco's `vs`/`vs-dark` base themes
+ * specialise must be either (a) re-declared by the bridge's own `rules`, or
+ * (b) named in `IGNORED_BASE_SCOPES` with a reason it can never reach this
+ * package's editors. This is what survives a `monaco-editor` UPGRADE: today's
+ * fix hand-lists the scopes evidenced against 0.55.1 — if a future version
+ * specialises a new one (or changes what `EDITOR_LANGUAGES` can reach), this
+ * test reds instead of silently shipping another un-branded scope.
+ */
+describe("drift guard against monaco-editor's base themes — #90", () => {
+  const light = buildThemeDataFor("light");
+  const dark = buildThemeDataFor("dark");
+  const bridgeTokens = new Set(
+    [...(light.rules ?? []), ...(dark.rules ?? [])].map((rule) => rule.token),
+  );
+
+  const dottedBaseTokens = new Set(
+    [...vs.rules, ...vs_dark.rules]
+      .map((rule) => rule.token)
+      .filter((token) => token.includes(".")),
+  );
+
+  it("has at least one dotted scope to guard (sanity — a stale extraction would vacuously pass)", () => {
+    expect(dottedBaseTokens.size).toBeGreaterThan(0);
+  });
+
+  it.each([...dottedBaseTokens].sort())(
+    "base scope %s is either overridden by the bridge or explicitly ignored",
+    (token) => {
+      const covered = bridgeTokens.has(token) || IGNORED_BASE_SCOPES.has(token);
+      expect(covered).toBe(true);
+    },
+  );
+});

package/src/lib/monaco-theme-bridge.ts

@@ -61,11 +61,19 @@ const clamp01 = (n: number) => (Number.isFinite(n) ? Math.min(1, Math.max(0, n))
 const byte = (n: number) => n.toString(16).padStart(2, "0");
 
 /** Mix `alpha` (0..1) into a `#rrggbb` color, returning `#rrggbbaa`. */
-function withAlpha(hex: string, alpha: number): string {
+export function withAlpha(hex: string, alpha: number): string {
   const base = hex.slice(0, 7);
   return `${base}${byte(Math.round(clamp01(alpha) * 255))}`;
 }
 
+/**
+ * Alpha of the translucent cursor-line highlight Monaco paints UNDER every
+ * token's text on the active line (`editor.lineHighlightBackground`). Named
+ * and shared so the visual overlay and the AA-contrast ground it composites
+ * into (`flattenOver`, below) can never drift apart (#88).
+ */
+export const LINE_HIGHLIGHT_ALPHA = 0.05;
+
 /** Strip `#` and any alpha — Monaco token rules want a bare 6-char hex. */
 function bare(hex: string): string {
   return hex.replace("#", "").slice(0, 6).padEnd(6, "0");
@@ -84,11 +92,31 @@ function luminance(hex: string): number {
     0.0722 * toLinear(channel(hex, 2))
   );
 }
-function contrast(a: string, b: string): number {
+export function contrast(a: string, b: string): number {
   const la = luminance(a);
   const lb = luminance(b);
   return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
 }
+
+/**
+ * Composite a translucent `#rrggbbaa` overlay (an alpha-suffixed hex, as
+ * `withAlpha` produces) over an opaque `#rrggbb` ground — the same straight,
+ * source-over blend a browser/Monaco applies when it paints a translucent
+ * decoration on top of the editor surface. Returns the resulting opaque
+ * `#rrggbb`.
+ *
+ * Exists so contrast clamps (and tests) can target the REAL, on-screen ground
+ * a syntax color renders against, not the bare, uncomposited surface color —
+ * see #88.
+ */
+export function flattenOver(overlayHexWithAlpha: string, groundHex: string): string {
+  const overlayBase = overlayHexWithAlpha.slice(0, 7);
+  const alphaHex = overlayHexWithAlpha.length >= 9 ? overlayHexWithAlpha.slice(7, 9) : "ff";
+  const alpha = clamp01((parseInt(alphaHex, 16) || 0) / 255);
+  const blend = (i: number) =>
+    Math.round(channel(overlayBase, i) * alpha + channel(groundHex, i) * (1 - alpha));
+  return `#${byte(blend(0))}${byte(blend(1))}${byte(blend(2))}`;
+}
 function mixHex(hex: string, target: string, t: number): string {
   const lerp = (i: number) =>
     Math.round(channel(hex, i) + (channel(target, i) - channel(hex, i)) * t);
@@ -143,6 +171,17 @@ export function buildBrandThemeData(
   const border = read("--border", muted);
   const primary = read("--primary", foreground);
   const ring = read("--ring", primary);
+  const ringContour = read("--ring-contour", ring);
+  // Monaco's `focusBorder` is a SINGLE colour key — a theme cannot hand it the
+  // two-layer compound indicator the DOM gets from the `focus-ring` utility (#67),
+  // so it gets whichever layer actually clears the 1.4.11 bar against this editor's
+  // own ground. That is exactly the `max(ring, contour)` rule
+  // `themes-contrast.test.ts` asserts on the tokens, evaluated here at runtime so it
+  // also holds for a consumer theme this package has never heard of: on `light` the
+  // ring IS `--primary` (1.36:1) and the contour wins; on `dark` the contour
+  // deliberately collapses into the background and the ring wins.
+  const focusBorder =
+    contrast(ringContour, background) > contrast(ring, background) ? ringContour : ring;
   const popover = read("--popover", background);
   const popoverFg = read("--popover-foreground", foreground);
   const input = read("--input", border);
@@ -152,10 +191,21 @@ export function buildBrandThemeData(
   const chart4 = read("--chart-4", primary);
   const success = read("--success", chart2);
   const destructive = read("--destructive", "#ff0000");
+
+  // Monaco paints `editor.lineHighlightBackground` — a translucent overlay —
+  // UNDER every token's text on the CURSOR'S line, so the real, on-screen
+  // ground a syntax color renders against there is this COMPOSITE, not the
+  // bare `background` alone (#88). Computed once and reused for both the
+  // `colors` entry below and the AA-clamp ground, so the two can't drift apart.
+  const lineHighlight = withAlpha(foreground, LINE_HIGHLIGHT_ALPHA);
+  const tokenGround = flattenOver(lineHighlight, background);
+
   // Calc result-inlay color (#220): the computed answer shown after each ```calc
   // line. Themed here (not hardcoded) so it re-applies on theme change with the
-  // rest of the editor; AA-clamped against the editor background like syntax tokens.
-  const calcResult = ensureReadable(read("--calc-result", primary), background, 4.5);
+  // rest of the editor; AA-clamped against the composited line-highlight ground
+  // like syntax tokens (#88) — an inlay on the cursor's line is painted over the
+  // same overlay.
+  const calcResult = ensureReadable(read("--calc-result", primary), tokenGround, 4.5);
 
   const colors: Monaco.editor.IColors = {
     "editor.background": background,
@@ -167,7 +217,7 @@ export function buildBrandThemeData(
     "editor.selectionBackground": withAlpha(primary, 0.28),
     "editor.inactiveSelectionBackground": withAlpha(primary, 0.14),
     "editor.selectionHighlightBackground": withAlpha(primary, 0.14),
-    "editor.lineHighlightBackground": withAlpha(foreground, 0.05),
+    "editor.lineHighlightBackground": lineHighlight,
     "editor.lineHighlightBorder": "#00000000",
     "editorIndentGuide.background1": withAlpha(border, 0.6),
     "editorIndentGuide.activeBackground1": mutedFg,
@@ -193,7 +243,7 @@ export function buildBrandThemeData(
     "input.background": input,
     "input.foreground": foreground,
     "input.border": border,
-    focusBorder: ring,
+    focusBorder,
     "dropdown.background": popover,
     "dropdown.foreground": popoverFg,
     "dropdown.border": border,
@@ -235,10 +285,23 @@ export function buildBrandThemeData(
     "diffEditor.border": border,
   };
 
-  // Syntax tokens: enforce AA (4.5:1) against the editor background; comments
-  // get a softer 3.2:1 so they stay intentionally muted but legible. Keyword/
-  // operator/tag stay on the brand primary (identity), readability-clamped too.
-  const ink = (hex: string, ratio = 4.5) => bare(ensureReadable(hex, background, ratio));
+  // Syntax tokens: enforce AA (4.5:1) against the composited line-highlight
+  // ground (#88 — Monaco paints that translucent overlay UNDER every token on
+  // the cursor's line, so clamping against the bare `background` targets a
+  // ground that is never actually rendered); comments get a softer 3.2:1 so
+  // they stay intentionally muted but legible. Keyword/operator/tag stay on
+  // the brand primary (identity), readability-clamped too.
+  //
+  // `AA_MARGIN` adds headroom on top of the nominal ratio: `ensureReadable`
+  // stops at the FIRST 10% mix step that clears the bar, so a zero-margin
+  // clamp can land a hair below it once axe's own rounding is applied — #88
+  // measured `string` short by 0.34:1 for exactly this reason. Modeling the
+  // OTHER transient overlays (selection, bracket-match, diff bands) is
+  // explicitly out of scope for #88; the margin is the accepted headroom for
+  // those too, not a claim they're individually composited in.
+  const AA_MARGIN = 0.15;
+  const ink = (hex: string, ratio = 4.5) =>
+    bare(ensureReadable(hex, tokenGround, ratio + AA_MARGIN));
   const rules: Monaco.editor.ITokenThemeRule[] = [
     { token: "", foreground: bare(foreground), background: bare(background) },
     { token: "comment", foreground: ink(mutedFg, 3.2), fontStyle: "italic" },
@@ -263,12 +326,93 @@ export function buildBrandThemeData(
     { token: "string.value", foreground: ink(chart2) },
     { token: "invalid", foreground: ink(destructive) },
     { token: "namespace", foreground: ink(success) },
+    // Monaco's built-in `vs`/`vs-dark` bases (inherited at `inherit: true`,
+    // below) ship LANGUAGE-SUFFIXED rules — `string.key.json`,
+    // `string.value.json`, `keyword.json`, `string.yaml`, `delimiter.html`, …
+    // — and Monaco's token-theme trie resolves the DEEPEST matching scope
+    // (`ThemeTrieElement.match`), with rules sorted lexicographically before
+    // insertion. A shorter brand scope (e.g. `string.key`, above) can
+    // therefore NEVER override a longer base scope: every scope a base theme
+    // specialises must be re-declared here, or that language renders in
+    // stock VS colours (#90). Keep this list in sync with the base themes —
+    // `IGNORED_BASE_SCOPES` + the drift guard in `monaco-theme-bridge.test.ts`
+    // fail CI if a future `monaco-editor` upgrade adds a new one.
+    { token: "string.key.json", foreground: ink(chart1) }, // pairs with `key`
+    { token: "string.value.json", foreground: ink(chart2) }, // pairs with `string`
+    { token: "keyword.json", foreground: ink(primary) }, // pairs with `keyword`
+    // Closes the class, not just JSON — the same base-specialisation gap
+    // reaches YAML/HTML/SQL/XML/CSS/SCSS (#90 evidence #7).
+    { token: "string.html", foreground: ink(chart2) },
+    { token: "string.sql", foreground: ink(chart2) },
+    { token: "string.yaml", foreground: ink(chart2) },
+    { token: "delimiter.html", foreground: ink(mutedFg, 3.2) },
+    { token: "delimiter.xml", foreground: ink(mutedFg, 3.2) },
+    { token: "attribute.value.html", foreground: ink(chart2) },
+    { token: "attribute.value.xml", foreground: ink(chart2) },
+    { token: "attribute.value.number", foreground: ink(chart4) },
+    { token: "attribute.value.unit", foreground: ink(chart4) },
+    { token: "attribute.value.number.css", foreground: ink(chart4) },
+    { token: "attribute.value.unit.css", foreground: ink(chart4) },
+    { token: "attribute.value.hex.css", foreground: ink(chart4) },
+    { token: "number.hex", foreground: ink(chart4) },
+    { token: "keyword.flow", foreground: ink(primary) },
+    { token: "keyword.flow.scss", foreground: ink(primary) },
+    { token: "operator.scss", foreground: ink(primary) },
+    { token: "operator.sql", foreground: ink(primary) },
+    { token: "operator.swift", foreground: ink(primary) },
+    { token: "predefined.sql", foreground: ink(chart3) },
+    { token: "metatag", foreground: ink(chart3) },
+    { token: "metatag.html", foreground: ink(chart3) },
+    { token: "metatag.xml", foreground: ink(chart3) },
+    { token: "metatag.content.html", foreground: ink(chart3) },
+    { token: "meta.scss", foreground: ink(chart1) },
+    { token: "meta.tag", foreground: ink(chart1) },
+    // `CodeEditorProps.language` is a plain, unrestricted `string` passed
+    // straight to `monaco.editor.setModelLanguage` (`code-editor.tsx`) — NOT
+    // limited to `EDITOR_LANGUAGES` — so a consumer really can reach these
+    // pug/handlebars scopes (PR #119 review thread 2). See
+    // `IGNORED_BASE_SCOPES` below for the one scope that stays un-overridden.
+    { token: "tag.id.pug", foreground: ink(primary) }, // pairs with `tag`
+    { token: "tag.class.pug", foreground: ink(primary) },
+    { token: "variable.parameter", foreground: bare(foreground) }, // pairs with `variable`
   ];
 
   // `base` is a placeholder; `applyBrandTheme` overrides it per theme.
   return { base: "vs", inherit: true, colors, rules };
 }
 
+/**
+ * Base-specialised dotted scopes (`vs`/`vs_dark`,
+ * `monaco-editor/esm/vs/editor/standalone/common/themes.js`) deliberately left
+ * un-overridden by `buildBrandThemeData`'s `rules`. Read by the drift-guard
+ * test (`monaco-theme-bridge.test.ts`, #90) so a future `monaco-editor`
+ * upgrade that adds a genuinely new specialised scope fails CI instead of
+ * silently un-branding it.
+ *
+ * PR #119 review thread 2 (fix-round-2): this set used to also carry
+ * `tag.id.pug` / `tag.class.pug` / `variable.parameter` on the premise that
+ * "the language that emits them is NOT in `EDITOR_LANGUAGES`, so nothing in
+ * this package can ever render them" — that premise is FALSE.
+ * `CodeEditorProps.language` (`code-editor.tsx`) is a plain, unrestricted
+ * `string` forwarded straight to `monaco.editor.setModelLanguage`; the
+ * toolbar's `EDITOR_LANGUAGES` list is a curated picker UI, not an
+ * enforcement boundary. A consumer passing `language="pug"` or
+ * `language="handlebars"` genuinely reaches those scopes and would have
+ * inherited stock Monaco colours instead of the token-derived brand theme.
+ * They are now branded in `rules` above instead of ignored here.
+ *
+ * - `metatag.php` — the one scope legitimately still ignored: verified
+ *   against `monaco-editor/esm/vs/editor/standalone/common/themes.js`, the
+ *   base themes give it only a `fontStyle` (`bold`), no `foreground` at all
+ *   — there is no colour to override, so branding it would be a no-op rule
+ *   with nothing to test.
+ *
+ * If a future scope needs the same "unreachable" reasoning, verify it
+ * against `CodeEditorProps.language`'s actual (unrestricted) type before
+ * adding it here — not against `EDITOR_LANGUAGES`.
+ */
+export const IGNORED_BASE_SCOPES = new Set(["metatag.php"]);
+
 /** The Monaco theme id used for a given brand theme. */
 export function brandThemeId(theme: ThemeName): string {
   return `brand-${theme}`;

package/src/markdown-academic/citations.tsx

@@ -262,7 +262,7 @@ function CiteLink({ entry, label }: { entry: ResolvedCitation; label: string })
       // (4.5:1), which `--primary` missed at 4.29-4.31:1 in light. The
       // resting `underline` is the separate 1.4.1 non-colour cue (#317's
       // link-in-text-block half) — keep both.
-      className="text-primary-text underline hover:underline focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      className="text-primary-text underline hover:underline focus-visible:rounded-sm focus-ring"
     >
       {label}
     </a>
@@ -427,7 +427,7 @@ export const Bibliography = forwardRef<HTMLElement, BibliographyProps>(function
                     rel="noopener noreferrer"
                     // #317/#399 — bibliography DOI/URL is body text: `-text` rung
                     // + resting underline (the non-colour cue).
-                    className="break-words text-primary-text underline underline-offset-2 hover:underline focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                    className="break-words text-primary-text underline underline-offset-2 hover:underline focus-visible:rounded-sm focus-ring"
                   >
                     {data.url ?? `doi:${data.doi}`}
                   </a>

package/src/markdown-academic/footnotes.tsx

@@ -165,7 +165,7 @@ export function FootnoteRef({ node: _n, children: _c, ...rest }: TagProps) {
         data-footnote-ref=""
         aria-label={`Footnote ${n}`}
         // #399 — a footnote marker is superscript body text: `-text` rung.
-        className="px-0.5 font-medium text-primary-text underline tabular-nums hover:underline focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        className="px-0.5 font-medium text-primary-text underline tabular-nums hover:underline focus-visible:rounded-sm focus-ring"
       >
         {n}
       </a>
@@ -196,7 +196,7 @@ export function FootnoteItem({ node: _n, children, ...rest }: TagProps) {
               ? `Back to reference ${n}, mention ${i + 1}`
               : `Back to reference ${n}`
           }
-          className="ms-0.5 inline-flex items-center text-muted-foreground no-underline hover:text-foreground focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          className="ms-0.5 inline-flex items-center text-muted-foreground no-underline hover:text-foreground focus-visible:rounded-sm focus-ring"
         >
           <span aria-hidden="true">↩</span>
           {refList.length > 1 ? (

package/src/markdown-academic/toc.tsx

@@ -75,7 +75,7 @@ export const TableOfContents = forwardRef<HTMLElement, TableOfContentsProps>(
             <li key={it.id} className={INDENT[Math.min(it.level - minLevel, INDENT.length - 1)]}>
               <a
                 href={`#${it.id}`}
-                className="text-muted-foreground underline hover:text-foreground hover:underline focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                className="text-muted-foreground underline hover:text-foreground hover:underline focus-visible:rounded-sm focus-ring"
               >
                 {it.text}
               </a>

package/src/markdown-editor/directive-views.tsx

@@ -170,10 +170,7 @@ function InlineEdit({ value, onCommit, ariaLabel, placeholder, className }: Inli
       spellCheck={false}
       onBlur={commit}
       onKeyDown={onKeyDown}
-      className={cn(
-        "brand-inline-edit rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ring",
-        className,
-      )}
+      className={cn("brand-inline-edit rounded-sm focus-ring", className)}
     />
   );
 }
@@ -644,7 +641,7 @@ function IterationDirectiveView() {
               data-directive-chrome=""
               aria-label="Iteration actions"
               title="Iteration actions…"
-              className="ms-auto inline-flex size-5 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              className="ms-auto inline-flex size-5 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground focus-ring"
             >
               <MoreHorizontal className="size-4" aria-hidden="true" />
             </button>

package/src/markdown-editor/markdown-editor.css

@@ -3,12 +3,18 @@
  *
  * Milkdown core ships ZERO styles (headless), so this is where brand-ui owns the
  * look. Every value is a semantic design token (var(--foreground), --border,
- * --radius, …) — NO raw colors — so the editor matches all three themes
+ * --radius, …) — NO raw colors — so the editor matches every theme
  * (light/dark) for free. Every rule
  * is scoped under `.milkdown-host` so nothing leaks globally.
  */
 
 .milkdown-host .ProseMirror {
+  /* Suppresses the platform default outline — NOT a bare removal: the
+     `:focus-visible` rule below is the replacement, drawn on this same
+     element (#309). It owns the indicator unconditionally, so it can't be
+     clipped by an ancestor and can't be deleted by a consumer `className`
+     reaching `cn()` on the wrapper (`markdown-editor.tsx`'s root `div`
+     intentionally carries no focus-ring utility of its own — see #67/#309). */
   outline: none;
   padding: 1rem 1.1rem;
   min-height: 9rem;
@@ -23,8 +29,25 @@
   margin-inline: auto;
 }
 
-.milkdown-host .ProseMirror:focus {
-  outline: none;
+/* Focus indicator (#309) — a compound two-layer shape mirroring the
+   `focus-ring-inset` Tailwind utility (`packages/tokens/src/themes.css`,
+   ADR 0027), hand-written because this stylesheet is a plain side-effect CSS
+   import resolved by the CONSUMER's bundler — not guaranteed to run through
+   Tailwind, so `@apply`/utility classes aren't reachable here (verified:
+   `@apply` appears zero times in any .css file in this repo). Drawn INSIDE
+   the editable's own box (`outline-offset: -3px`, an inset `box-shadow`), so
+   it can't be clipped by an ancestor and survives a consumer `className`
+   deleting the wrapper's classes (`MarkdownWorkspace` already does this via
+   `className="border-0"`). Two layers of opposite value so at least one edge
+   clears 3:1 against the ground whatever `--ring` resolves to in a given
+   theme (`--ring-contour` is the dedicated contour token — `themes-contrast.
+   test.ts`'s `INDICATOR_SURFACES` locks `max(ring, contour) >= 3:1` at the
+   token level; `markdown-editor.stories.tsx`'s `FocusIndicator` play
+   re-measures it on this rendered surface, both themes). */
+.milkdown-host .ProseMirror:focus-visible {
+  outline: 1px solid var(--ring-contour);
+  outline-offset: -3px;
+  box-shadow: inset 0 0 0 2px var(--ring);
 }
 
 /* ----------------------------------------------------------------------------