@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/theme/built-in-themes.ts

@@ -0,0 +1,342 @@
+/**
+ * SCREEN-2002 — the four built-in themes, as data.
+ *
+ * `dark` is today's colour, gathered from the four places that used to decide it: `PALETTE`/`MOTION`
+ * (Ink), `ANSI` (the markdown diff rows), `marked-terminal`'s own chalk defaults and `cli-highlight`'s
+ * `DEFAULT_THEME`. Making those defaults explicit is what lets a theme change them at all; it is also
+ * why a user who sets nothing sees the same colours as before.
+ *
+ * Over the 300-line file ceiling, deliberately. The file is ONE concern — four colour tables of the
+ * same shape — and the ceiling exists to break up files that do several things. Splitting per theme
+ * would put the dark and light values that must correspond in different files, which is the drift
+ * the token model was built to stop.
+ *
+ * The daltonized pair is specified in hex rather than colour names on purpose: a name is whatever the
+ * terminal says it is, so a colour-vision-deficiency simulation cannot compute it, and the guard
+ * REFUSES what it cannot simulate. Their status and diff pairs avoid red/green entirely — blue for
+ * "good", orange for "bad" — the distinction protanopes and deuteranopes retain.
+ *
+ * This module is the only file in the package allowed to hold a colour VALUE; the consistency test
+ * ratchets on both that import and on direct `chalk.<colour>(` calls elsewhere.
+ */
+import type { ITuiTheme } from './theme-contracts.js';
+
+/** Today's values, name for name. */
+export const DARK_THEME: ITuiTheme = {
+  id: 'dark',
+  name: 'Dark',
+  appearance: 'dark',
+  source: 'built-in',
+  colors: {
+    text: {
+      accent: 'cyan',
+      emphasis: 'white',
+      success: 'green',
+      warning: 'yellow',
+      error: 'red',
+      session: 'magenta',
+      muted: 'gray',
+      onAccent: 'black',
+    },
+    border: {
+      attention: 'yellow',
+      focused: 'cyan',
+      active: 'green',
+      muted: 'gray',
+      error: 'red',
+    },
+    status: {
+      running: 'yellow',
+      success: 'green',
+      error: 'red',
+      denied: 'yellowBright',
+      waiting: 'yellow',
+      cancelled: 'yellow',
+      idle: 'gray',
+    },
+  },
+  // marked-terminal's own defaults, written down so a theme can change them.
+  markdown: {
+    heading: 'green',
+    firstHeading: 'magenta',
+    code: 'yellow',
+    codespan: 'yellow',
+    link: 'blue',
+    href: 'blue',
+    blockquote: 'gray',
+    del: 'gray',
+    html: 'gray',
+    // The former `ANSI.lightGreen` / `lightRed` / `darkGreenBackground` / `darkRedBackground`.
+    diffAdded: 'ansi256(120)',
+    diffRemoved: 'ansi256(210)',
+    diffAddedBackground: 'ansi256(22)',
+    diffRemovedBackground: 'ansi256(52)',
+    diffHunk: 'cyan',
+  },
+  // cli-highlight's DEFAULT_THEME, written down for the same reason.
+  syntax: {
+    keyword: 'blue',
+    built_in: 'cyan',
+    type: 'cyan',
+    literal: 'blue',
+    number: 'green',
+    regexp: 'red',
+    string: 'red',
+    class: 'blue',
+    function: 'yellow',
+    comment: 'green',
+    doctag: 'green',
+    meta: 'gray',
+    tag: 'gray',
+    name: 'blue',
+    attr: 'cyan',
+    addition: 'green',
+    deletion: 'red',
+  },
+  motion: { wave: ['#555555', '#777777', '#999999', '#bbbbbb'] },
+};
+
+/** The same roles against a light background: darker foregrounds, light diff backgrounds. */
+export const LIGHT_THEME: ITuiTheme = {
+  id: 'light',
+  name: 'Light',
+  appearance: 'light',
+  source: 'built-in',
+  colors: {
+    text: {
+      accent: 'ansi256(24)',
+      emphasis: 'black',
+      success: 'ansi256(28)',
+      warning: 'ansi256(130)',
+      error: 'ansi256(124)',
+      session: 'ansi256(90)',
+      muted: 'ansi256(243)',
+      onAccent: 'white',
+    },
+    border: {
+      attention: 'ansi256(130)',
+      focused: 'ansi256(24)',
+      active: 'ansi256(28)',
+      muted: 'ansi256(249)',
+      error: 'ansi256(124)',
+    },
+    status: {
+      running: 'ansi256(130)',
+      success: 'ansi256(28)',
+      error: 'ansi256(124)',
+      denied: 'ansi256(166)',
+      waiting: 'ansi256(130)',
+      cancelled: 'ansi256(130)',
+      idle: 'ansi256(243)',
+    },
+  },
+  markdown: {
+    heading: 'ansi256(28)',
+    firstHeading: 'ansi256(90)',
+    code: 'ansi256(94)',
+    codespan: 'ansi256(94)',
+    link: 'ansi256(26)',
+    href: 'ansi256(26)',
+    blockquote: 'ansi256(243)',
+    del: 'ansi256(243)',
+    html: 'ansi256(243)',
+    diffAdded: 'ansi256(22)',
+    diffRemoved: 'ansi256(52)',
+    diffAddedBackground: 'ansi256(194)',
+    diffRemovedBackground: 'ansi256(224)',
+    diffHunk: 'ansi256(24)',
+  },
+  syntax: {
+    keyword: 'ansi256(26)',
+    built_in: 'ansi256(24)',
+    type: 'ansi256(24)',
+    literal: 'ansi256(26)',
+    number: 'ansi256(28)',
+    regexp: 'ansi256(124)',
+    string: 'ansi256(124)',
+    class: 'ansi256(26)',
+    function: 'ansi256(94)',
+    comment: 'ansi256(28)',
+    doctag: 'ansi256(28)',
+    meta: 'ansi256(243)',
+    tag: 'ansi256(243)',
+    name: 'ansi256(26)',
+    attr: 'ansi256(24)',
+    addition: 'ansi256(22)',
+    deletion: 'ansi256(52)',
+  },
+  motion: { wave: ['#bbbbbb', '#999999', '#777777', '#555555'] },
+};
+
+/** Blue "good" / orange "bad": the pair protanopes and deuteranopes keep apart. */
+export const DARK_DALTONIZED_THEME: ITuiTheme = {
+  id: 'dark-daltonized',
+  name: 'Dark (daltonized)',
+  appearance: 'dark',
+  source: 'built-in',
+  colors: {
+    text: {
+      accent: '#56b4e9',
+      emphasis: '#ffffff',
+      success: '#56b4e9',
+      warning: '#e69f00',
+      error: '#d55e00',
+      session: '#cc79a7',
+      muted: '#999999',
+      onAccent: '#000000',
+    },
+    border: {
+      attention: '#e69f00',
+      focused: '#56b4e9',
+      active: '#56b4e9',
+      muted: '#999999',
+      error: '#d55e00',
+    },
+    status: {
+      running: '#e69f00',
+      success: '#56b4e9',
+      error: '#d55e00',
+      denied: '#f0e442',
+      waiting: '#e69f00',
+      cancelled: '#cc79a7',
+      idle: '#999999',
+    },
+  },
+  markdown: {
+    heading: '#56b4e9',
+    firstHeading: '#cc79a7',
+    code: '#e69f00',
+    codespan: '#e69f00',
+    link: '#56b4e9',
+    href: '#56b4e9',
+    blockquote: '#999999',
+    del: '#999999',
+    html: '#999999',
+    diffAdded: '#8ecdf5',
+    diffRemoved: '#ffb066',
+    diffAddedBackground: '#00335c',
+    diffRemovedBackground: '#5c3000',
+    diffHunk: '#56b4e9',
+  },
+  syntax: {
+    keyword: '#56b4e9',
+    built_in: '#8ecdf5',
+    type: '#8ecdf5',
+    literal: '#56b4e9',
+    number: '#e69f00',
+    regexp: '#d55e00',
+    string: '#d55e00',
+    class: '#56b4e9',
+    function: '#f0e442',
+    comment: '#999999',
+    doctag: '#999999',
+    meta: '#999999',
+    tag: '#999999',
+    name: '#56b4e9',
+    attr: '#8ecdf5',
+    addition: '#8ecdf5',
+    deletion: '#ffb066',
+  },
+  motion: { wave: ['#3d3d3d', '#5c5c5c', '#7a7a7a', '#999999'] },
+};
+
+export const LIGHT_DALTONIZED_THEME: ITuiTheme = {
+  id: 'light-daltonized',
+  name: 'Light (daltonized)',
+  appearance: 'light',
+  source: 'built-in',
+  colors: {
+    text: {
+      accent: '#0072b2',
+      emphasis: '#000000',
+      success: '#0072b2',
+      warning: '#b35900',
+      error: '#8c3d00',
+      session: '#a8477f',
+      muted: '#5c5c5c',
+      onAccent: '#ffffff',
+    },
+    border: {
+      attention: '#b35900',
+      focused: '#0072b2',
+      active: '#0072b2',
+      muted: '#a3a3a3',
+      error: '#8c3d00',
+    },
+    status: {
+      running: '#b35900',
+      success: '#0072b2',
+      error: '#8c3d00',
+      denied: '#8a7500',
+      waiting: '#b35900',
+      cancelled: '#a8477f',
+      idle: '#5c5c5c',
+    },
+  },
+  markdown: {
+    heading: '#0072b2',
+    firstHeading: '#a8477f',
+    code: '#8a5a00',
+    codespan: '#8a5a00',
+    link: '#0072b2',
+    href: '#0072b2',
+    blockquote: '#5c5c5c',
+    del: '#5c5c5c',
+    html: '#5c5c5c',
+    diffAdded: '#004c77',
+    diffRemoved: '#7a3300',
+    diffAddedBackground: '#d6ecf9',
+    diffRemovedBackground: '#fbe5cd',
+    diffHunk: '#0072b2',
+  },
+  syntax: {
+    keyword: '#0072b2',
+    built_in: '#004c77',
+    type: '#004c77',
+    literal: '#0072b2',
+    number: '#b35900',
+    regexp: '#8c3d00',
+    string: '#8c3d00',
+    class: '#0072b2',
+    function: '#8a7500',
+    comment: '#5c5c5c',
+    doctag: '#5c5c5c',
+    meta: '#5c5c5c',
+    tag: '#5c5c5c',
+    name: '#0072b2',
+    attr: '#004c77',
+    addition: '#004c77',
+    deletion: '#7a3300',
+  },
+  motion: { wave: ['#c7c7c7', '#a3a3a3', '#7a7a7a', '#5c5c5c'] },
+};
+
+export const BUILT_IN_THEMES: readonly ITuiTheme[] = [
+  DARK_THEME,
+  LIGHT_THEME,
+  DARK_DALTONIZED_THEME,
+  LIGHT_DALTONIZED_THEME,
+];
+
+/** The theme a run uses when nothing is configured: today's colours. */
+export const DEFAULT_THEME_ID = DARK_THEME.id;
+
+/**
+ * The catalogue, as a function rather than the array itself. A caller outside `src/theme/` — the
+ * theme registry a picker reads — needs to ENUMERATE the built-ins, which is a different act from
+ * reaching into one of them for a colour; the floor refuses the second by refusing the DATA's names,
+ * so the first gets an accessor of its own instead of an exemption.
+ */
+export function listBuiltInThemes(): readonly ITuiTheme[] {
+  return BUILT_IN_THEMES;
+}
+
+/**
+ * The one place "no theme was resolved" is answered. A caller outside `src/theme/` asks this instead
+ * of importing the built-in data, so the anti-drift floor can keep the colour DATA inside this
+ * module and still let a non-React entry point — `renderMarkdown`, which is called with a theme or
+ * without one — render at all.
+ */
+export function resolveTheme(theme: ITuiTheme | undefined): ITuiTheme {
+  return theme ?? DARK_THEME;
+}

package/src/theme/color-vision.ts

@@ -0,0 +1,171 @@
+/**
+ * SCREEN-2002 — colour-vision-deficiency simulation, for the guard over the daltonized built-ins.
+ *
+ * A daltonized theme's claim is that two colours a viewer must tell apart still differ AFTER their
+ * protan or deutan confusion. That is measurable, so it is measured: simulate both deficiencies
+ * (Viénot–Brettel–Mollon, the linear-RGB projection published for dichromats), convert to CIE Lab,
+ * and take the pairwise distance.
+ *
+ * The guard REFUSES what it cannot simulate. A colour NAME is whatever the terminal says it is, so a
+ * named value in a daltonized theme is an error rather than a pass — the one direction a guard may
+ * never take silently.
+ */
+import type { TThemeColor } from './theme-contracts.js';
+
+export type TColorVision = 'protanopia' | 'deuteranopia';
+
+interface IRgb {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+}
+
+const HEX_LONG = /^#([0-9a-f]{6})$/iu;
+const HEX_SHORT = /^#([0-9a-f]{3})$/iu;
+const ANSI256 = /^ansi256\((\d{1,3})\)$/iu;
+const RGB = /^rgb\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})\)$/iu;
+const BYTE_MAX = 255;
+const HEX_BASE = 16;
+const HEX_PAIR = /[0-9a-f]{2}/giu;
+const ANSI_CUBE_START = 16;
+const ANSI_GRAY_START = 232;
+const ANSI_CUBE_SIDE = 6;
+/**
+ * Published numeric tables are kept as DATA — parsed from their published text rather than spelled
+ * as literals in expressions, so the values stay verbatim and reviewable against their source.
+ */
+function coefficients(published: string): number[] {
+  return published.split(/\s+/u).map(Number);
+}
+
+/** The xterm 6×6×6 cube's channel levels. */
+const ANSI_CUBE_STEPS = coefficients('0 95 135 175 215 255');
+const GRAY_STEP = 10;
+const GRAY_BASE = 8;
+
+/** An Ink-grammar colour as 0–255 sRGB, or `undefined` when it cannot be simulated. */
+export function toRgb(color: TThemeColor): IRgb | undefined {
+  const long = HEX_LONG.exec(color);
+  if (long?.[1]) {
+    const [r, g, b] = (long[1].match(HEX_PAIR) ?? []).map((pair) =>
+      Number.parseInt(pair, HEX_BASE),
+    ) as [number, number, number];
+    return { r, g, b };
+  }
+  const short = HEX_SHORT.exec(color);
+  if (short?.[1]) {
+    const [r, g, b] = [...short[1]].map((digit) => Number.parseInt(`${digit}${digit}`, HEX_BASE));
+    return r === undefined || g === undefined || b === undefined ? undefined : { r, g, b };
+  }
+  const rgb = RGB.exec(color);
+  if (rgb) return { r: Number(rgb[1]), g: Number(rgb[2]), b: Number(rgb[3]) };
+  const ansi = ANSI256.exec(color);
+  if (ansi) return fromAnsi256(Number(ansi[1]));
+  // A colour NAME resolves in the terminal, not here.
+  return undefined;
+}
+
+function fromAnsi256(index: number): IRgb | undefined {
+  if (index >= ANSI_GRAY_START) {
+    const level = GRAY_BASE + (index - ANSI_GRAY_START) * GRAY_STEP;
+    return { r: level, g: level, b: level };
+  }
+  if (index < ANSI_CUBE_START) return undefined; // the 16 system colours are terminal-defined
+  const offset = index - ANSI_CUBE_START;
+  const r = ANSI_CUBE_STEPS[Math.floor(offset / (ANSI_CUBE_SIDE * ANSI_CUBE_SIDE))];
+  const g = ANSI_CUBE_STEPS[Math.floor(offset / ANSI_CUBE_SIDE) % ANSI_CUBE_SIDE];
+  const b = ANSI_CUBE_STEPS[offset % ANSI_CUBE_SIDE];
+  return r === undefined || g === undefined || b === undefined ? undefined : { r, g, b };
+}
+
+const GAMMA_THRESHOLD = 0.04045;
+const GAMMA_OFFSET = 0.055;
+const GAMMA_SCALE = 1.055;
+const GAMMA_EXPONENT = 2.4;
+const GAMMA_LINEAR_DIVISOR = 12.92;
+
+function toLinear(channel: number): number {
+  const value = channel / BYTE_MAX;
+  return value <= GAMMA_THRESHOLD
+    ? value / GAMMA_LINEAR_DIVISOR
+    : ((value + GAMMA_OFFSET) / GAMMA_SCALE) ** GAMMA_EXPONENT;
+}
+
+/** Viénot–Brettel–Mollon dichromat projections, applied in linear RGB. */
+const PROJECTION: Record<TColorVision, readonly number[][]> = {
+  protanopia: [
+    coefficients('0.1121 0.8853 -0.0005'),
+    coefficients('0.1127 0.8897 -0.0001'),
+    coefficients('0.0045 0.0 1.0019'),
+  ],
+  deuteranopia: [
+    coefficients('0.292 0.7054 -0.0003'),
+    coefficients('0.2934 0.7089 0.0'),
+    coefficients('-0.0209 0.4614 0.5677'),
+  ],
+};
+
+/** sRGB → CIE XYZ (D65), the standard matrix. */
+const SRGB_TO_XYZ = [
+  coefficients('0.4124 0.3576 0.1805'),
+  coefficients('0.2126 0.7152 0.0722'),
+  coefficients('0.0193 0.1192 0.9505'),
+];
+
+function project(matrix: readonly number[][], vector: readonly number[]): number[] {
+  return matrix.map((row) =>
+    row.reduce((sum, factor, index) => sum + factor * (vector[index] ?? 0), 0),
+  );
+}
+
+interface ILab {
+  readonly l: number;
+  readonly a: number;
+  readonly b: number;
+}
+
+const D65 = coefficients('0.95047 1 1.08883');
+const LAB_EPSILON_NUMERATOR = 216;
+const LAB_EPSILON_DENOMINATOR = 24389;
+const LAB_KAPPA_DIVISOR = 27;
+const LAB_EPSILON = LAB_EPSILON_NUMERATOR / LAB_EPSILON_DENOMINATOR;
+const LAB_KAPPA = LAB_EPSILON_DENOMINATOR / LAB_KAPPA_DIVISOR;
+const LAB_L_SCALE = 116;
+const LAB_L_OFFSET = 16;
+const LAB_A_SCALE = 500;
+const LAB_B_SCALE = 200;
+const THREE = 3;
+const CUBE_ROOT = 1 / THREE;
+
+function toLab(linear: readonly number[]): ILab {
+  const xyz = project(SRGB_TO_XYZ, linear).map((value, index) => value / (D65[index] ?? 1));
+  const f = (value: number): number =>
+    value > LAB_EPSILON ? value ** CUBE_ROOT : (LAB_KAPPA * value + LAB_L_OFFSET) / LAB_L_SCALE;
+  const [fx, fy, fz] = xyz.map(f) as [number, number, number];
+  return {
+    l: LAB_L_SCALE * fy - LAB_L_OFFSET,
+    a: LAB_A_SCALE * (fx - fy),
+    b: LAB_B_SCALE * (fy - fz),
+  };
+}
+
+/** One colour as a dichromat sees it, in Lab. `undefined` ⇒ the value cannot be simulated. */
+export function simulate(color: TThemeColor, vision: TColorVision): ILab | undefined {
+  const rgb = toRgb(color);
+  if (rgb === undefined) return undefined;
+  const linear = [toLinear(rgb.r), toLinear(rgb.g), toLinear(rgb.b)];
+  return toLab(project(PROJECTION[vision], linear));
+}
+
+/** CIE76 distance between two simulated colours; `undefined` when either cannot be simulated. */
+export function simulatedDistance(
+  first: TThemeColor,
+  second: TThemeColor,
+  vision: TColorVision,
+): number | undefined {
+  const a = simulate(first, vision);
+  const b = simulate(second, vision);
+  if (a === undefined || b === undefined) return undefined;
+  const SQUARE = 2;
+  return Math.sqrt((a.l - b.l) ** SQUARE + (a.a - b.a) ** SQUARE + (a.b - b.b) ** SQUARE);
+}

package/src/theme/index.ts

@@ -0,0 +1,45 @@
+/** SCREEN-2002 — the theme module's internal surface (the package exports nothing from here yet). */
+/**
+ * The colour DATA is deliberately NOT re-exported — neither the individual themes nor the array that
+ * holds them. The anti-drift floor forbids naming them outside `src/theme/`, and a barrel re-export
+ * would be the way around that. The two legitimate needs get accessors instead: a caller that must
+ * render without a resolved theme asks {@link resolveTheme}, and one that must ENUMERATE the
+ * built-ins asks {@link listBuiltInThemes}.
+ */
+export { DEFAULT_THEME_ID, listBuiltInThemes, resolveTheme } from './built-in-themes.js';
+export {
+  ThemeProvider,
+  useMotion,
+  useMotionTokens,
+  usePalette,
+  useSyntaxHighlighting,
+  useTheme,
+} from './theme-context.js';
+export {
+  background,
+  diffRowStyles,
+  foreground,
+  isThemeColor,
+  markdownRendererOptions,
+  syntaxHighlightTheme,
+} from './theme-styles.js';
+export { THEME_SYNTAX_KEYS } from './theme-contracts.js';
+export { simulate, simulatedDistance, toRgb } from './color-vision.js';
+export {
+  escapeThemeText,
+  parseThemeDocument,
+  quoteThemeText,
+  sanitizeThemeProse,
+} from './theme-document.js';
+export type { IThemeDocumentInput, TThemeDocumentResult } from './theme-document.js';
+export type { IDiffRowStyles } from './theme-styles.js';
+export type {
+  IThemeColors,
+  IThemeMarkdown,
+  IThemeMotion,
+  IThemeSyntax,
+  ITuiTheme,
+  TThemeAppearance,
+  TThemeColor,
+  TThemeSource,
+} from './theme-contracts.js';

package/src/theme/theme-context.tsx

@@ -0,0 +1,81 @@
+/**
+ * SCREEN-2002 — the resolved theme, published to the tree.
+ *
+ * The `screen-reader-context` shape: one resolved value in a React context, defaulting to the `dark`
+ * built-in outside a provider so a component rendered in a test behaves exactly as it did before the
+ * theme existed. Components read `usePalette()` where they used to import `PALETTE`; nothing takes the
+ * theme as a prop, so a missed prop cannot leave one component on another theme.
+ */
+import React, { createContext, useContext } from 'react';
+
+import { DARK_THEME, resolveTheme } from './built-in-themes.js';
+import { useScreenReader } from '../screen-reader-context.js';
+import { isInteractiveColorTerminal } from '../terminal-capabilities.js';
+
+import type { IThemeColors, IThemeMotion, ITuiTheme } from './theme-contracts.js';
+
+const ThemeContext = createContext<ITuiTheme>(DARK_THEME);
+const ReducedMotionContext = createContext<boolean>(false);
+const SyntaxHighlightingContext = createContext<boolean>(true);
+
+export function ThemeProvider({
+  theme,
+  reducedMotion = false,
+  syntaxHighlighting = true,
+  children,
+}: {
+  theme?: ITuiTheme;
+  reducedMotion?: boolean;
+  syntaxHighlighting?: boolean;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return (
+    <ThemeContext.Provider value={resolveTheme(theme)}>
+      <ReducedMotionContext.Provider value={reducedMotion}>
+        <SyntaxHighlightingContext.Provider value={syntaxHighlighting}>
+          {children}
+        </SyntaxHighlightingContext.Provider>
+      </ReducedMotionContext.Provider>
+    </ThemeContext.Provider>
+  );
+}
+
+/** The whole resolved theme. Most components want {@link usePalette} instead. */
+export function useTheme(): ITuiTheme {
+  return useContext(ThemeContext);
+}
+
+/** The colour tokens — the direct replacement for the former `PALETTE` import. */
+export function usePalette(): IThemeColors {
+  return useTheme().colors;
+}
+
+/** The animation ramp — the direct replacement for the former `MOTION` import. */
+export function useMotionTokens(): IThemeMotion {
+  return useTheme().motion;
+}
+
+/**
+ * May this process ANIMATE? One owner for a three-input rule, with exactly one consumer (`WaveText`,
+ * the package's only animation). Deliberately NOT gating the background countdown (a once-a-second
+ * number is content — freezing it would show a stale `in 59s`) or the streaming indicator's
+ * screen-reader collapse (that drops content, which a sighted reduced-motion user still wants).
+ */
+export function useMotion(): boolean {
+  const screenReader = useScreenReader();
+  const reducedMotion = useContext(ReducedMotionContext);
+  // No `useMemo`: the value is a boolean, so memoizing it buys nothing — and a dependency array
+  // would have to omit `isInteractiveColorTerminal()`, which reads process state rather than React
+  // state. Hiding a non-reactive read inside a memo is how a stale gate gets written later.
+  return isInteractiveColorTerminal() && !screenReader && !reducedMotion;
+}
+
+/**
+ * SCREEN-2002: whether a fenced code block is highlighted. It travels with the theme rather than as
+ * a prop because every markdown render site already reads the theme from here, and a setting that
+ * reaches only some of them is worse than one that reaches none — `/theme syntax off` would report
+ * success while a block somewhere kept its colours.
+ */
+export function useSyntaxHighlighting(): boolean {
+  return useContext(SyntaxHighlightingContext);
+}