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

package/src/theme/__tests__/theme-document.test.ts

@@ -0,0 +1,222 @@
+/**
+ * SCREEN-2002 TC-11 — the theme file boundary.
+ *
+ * Everything a user or a plugin can put in a theme file arrives here as text. The contract is
+ * whole-file refusal with a path-named diagnostic: a file is either applied entirely or skipped
+ * entirely, because a partially-applied theme is the state where a reader cannot tell which colours
+ * are theirs and which are the base's.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { DARK_THEME, LIGHT_THEME } from '../built-in-themes.js';
+import { parseThemeDocument } from '../theme-document.js';
+
+import type { TThemeDocumentResult } from '../theme-document.js';
+
+function parse(text: string, id = 'custom:mine'): TThemeDocumentResult {
+  return parseThemeDocument({ id, fileName: 'mine.json', source: 'user', text });
+}
+
+function expectRefusal(text: string): string {
+  const result = parse(text);
+  expect(result.ok).toBe(false);
+  if (result.ok) throw new Error('expected a refusal');
+  return result.error;
+}
+
+describe('parseThemeDocument', () => {
+  it('applies a sparse override over its base and leaves every other token alone', () => {
+    const result = parse(
+      JSON.stringify({
+        name: 'Mine',
+        base: 'light',
+        overrides: { colors: { text: { accent: '#56b4e9' } } },
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error('expected a theme');
+    expect(result.theme.id).toBe('custom:mine');
+    expect(result.theme.name).toBe('Mine');
+    expect(result.theme.source).toBe('user');
+    expect(result.theme.appearance).toBe(LIGHT_THEME.appearance);
+    expect(result.theme.colors.text.accent).toBe('#56b4e9');
+    expect(result.theme.colors.text.muted).toBe(LIGHT_THEME.colors.text.muted);
+    expect(result.theme.syntax).toEqual(LIGHT_THEME.syntax);
+    expect(result.theme.motion).toEqual(LIGHT_THEME.motion);
+  });
+
+  it('defaults to the dark base and to the id as a name', () => {
+    const result = parse('{}');
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error('expected a theme');
+    expect(result.theme.name).toBe('custom:mine');
+    expect(result.theme.colors).toEqual(DARK_THEME.colors);
+  });
+
+  it('refuses an unknown token path, naming it', () => {
+    const error = expectRefusal(
+      JSON.stringify({ overrides: { colors: { text: { accnt: 'red' } } } }),
+    );
+    expect(error).toBe('$.overrides.colors.text.accnt is not a theme token');
+  });
+
+  it('refuses an invalid colour value, naming its path and the value', () => {
+    const error = expectRefusal(
+      JSON.stringify({ overrides: { colors: { text: { accent: 'not-a-colour' } } } }),
+    );
+    expect(error).toMatch(/^\$\.overrides\.colors\.text\.accent: "not-a-colour" is not a colour/u);
+  });
+
+  const ESCAPE = String.fromCharCode(27);
+
+  it('refuses a raw SGR string — the grammar is the injection floor', () => {
+    const error = expectRefusal(
+      JSON.stringify({ overrides: { markdown: { code: `${ESCAPE}[31m` } } }),
+    );
+    expect(error).toMatch(/^\$\.overrides\.markdown\.code: /u);
+  });
+
+  it('keeps the refusal itself off the terminal — the message quotes what it rejected', () => {
+    // The diagnostic is the one part of a refused file that reaches a terminal, and it quotes the
+    // value. Interpolating it raw defeats the grammar's injection floor with the very message that
+    // reports a violation of it — and a plugin's theme file is third-party content.
+    const errors = [
+      expectRefusal(JSON.stringify({ overrides: { markdown: { code: `${ESCAPE}[2J` } } })),
+      expectRefusal(JSON.stringify({ overrides: { [`${ESCAPE}[2Jx`]: {} } })),
+      expectRefusal(JSON.stringify({ [`${ESCAPE}[2Jx`]: 1 })),
+      expectRefusal(`{ ${ESCAPE}[2J not json`),
+      expectRefusal(JSON.stringify({ base: `${ESCAPE}[2J` })),
+    ];
+    for (const error of errors) expect(error).not.toContain(ESCAPE);
+    // Escaped, not dropped: an author has to be able to SEE what their file holds.
+    expect(errors[0]).toContain('\\u001b[2J');
+  });
+
+  it('escapes the 8-BIT spelling too, which JSON.stringify leaves standing', () => {
+    // A terminal accepts `ESC [` and the single byte U+009B as the same CSI, and `JSON.stringify`
+    // escapes only U+0000-U+001F — so quoting the 7-bit spelling alone leaves the other one's
+    // parameters as a live sequence. `sanitize-terminal-text.ts` states the same rule.
+    const csi = String.fromCharCode(0x9b);
+    const osc = String.fromCharCode(0x9d);
+    const del = String.fromCharCode(0x7f);
+    const errors = [
+      expectRefusal(JSON.stringify({ overrides: { markdown: { code: `${csi}2J` } } })),
+      expectRefusal(JSON.stringify({ base: `${osc}0;x` })),
+      expectRefusal(JSON.stringify({ [`${del}x`]: 1 })),
+    ];
+    for (const error of errors) {
+      expect(error).not.toContain(csi);
+      expect(error).not.toContain(osc);
+      expect(error).not.toContain(del);
+    }
+    expect(errors[0]).toContain('\\u009b2J');
+  });
+
+  it('holds the MINTED id to the LENGTH bound too, not only the control-character one', () => {
+    // The id becomes the rendered name when a document supplies none, so a bound on one and not the
+    // other leaves the row it is drawn in exactly as broken.
+    const tooLong = parseThemeDocument({
+      id: `custom:${'x'.repeat(60)}`,
+      fileName: 'mine.json',
+      source: 'user',
+      text: '{}',
+    });
+    expect(tooLong.ok).toBe(false);
+    if (tooLong.ok) throw new Error('expected a refusal');
+    expect(tooLong.error).toMatch(/^\$\.name: the minted id must be at most 60 characters$/u);
+
+    // A 60-character id is accepted, which is the bound itself rather than a value near it. The
+    // RELATION to what `agent-cli` can mint is not asserted here — this package does not depend on
+    // that one — but in `theme-sources.test.ts`, where the longest mintable id is loaded end to end
+    // with its fixture derived from `MAX_ID_SEGMENT`, so widening that bound turns it red.
+    const composite = parseThemeDocument({
+      id: `custom:${'p'.repeat(53)}`,
+      fileName: 'mine.json',
+      source: 'plugin',
+      text: '{}',
+    });
+    expect(composite.ok).toBe(true);
+  });
+
+  it('checks the MINTED id on the same terms as a name the file supplied', () => {
+    const result = parseThemeDocument({
+      id: `custom:${String.fromCharCode(0x9b)}2J`,
+      fileName: 'mine.json',
+      source: 'user',
+      text: '{}',
+    });
+    expect(result.ok).toBe(false);
+  });
+
+  it('refuses a name it would then render for the whole session', () => {
+    // Unlike a diagnostic, a name is APPLIED: it is drawn on every `/theme list` row and every
+    // picker row until the setting changes.
+    expect(expectRefusal(JSON.stringify({ name: `${ESCAPE}[2JPWNED` }))).toBe(
+      '$.name: must not contain control characters',
+    );
+    expect(expectRefusal(JSON.stringify({ name: 'two\nlines' }))).toBe(
+      '$.name: must not contain control characters',
+    );
+    expect(expectRefusal(JSON.stringify({ name: 'x'.repeat(61) }))).toMatch(
+      /^\$\.name: must be at most 60 characters$/u,
+    );
+  });
+
+  it('refuses an explicit null rather than reading it as "unset"', () => {
+    expect(expectRefusal(JSON.stringify({ base: null }))).toBe(
+      '$.base: expected a built-in theme id',
+    );
+    expect(expectRefusal(JSON.stringify({ overrides: null }))).toMatch(
+      /^\$\.overrides: expected an object of tokens$/u,
+    );
+  });
+
+  it('refuses a background chalk name as a foreground token value', () => {
+    const error = expectRefusal(
+      JSON.stringify({ overrides: { colors: { border: { focused: 'bgRed' } } } }),
+    );
+    expect(error).toMatch(/^\$\.overrides\.colors\.border\.focused: "bgRed" is not a colour/u);
+  });
+
+  it('refuses a malformed file WHOLE, naming the file root', () => {
+    expect(expectRefusal('{ not json')).toMatch(/^\$: /u);
+  });
+
+  it('refuses an unknown base', () => {
+    expect(expectRefusal(JSON.stringify({ base: 'solarized' }))).toBe(
+      '$.base: "solarized" is not a built-in theme',
+    );
+  });
+
+  it('refuses an unknown top-level key', () => {
+    expect(expectRefusal(JSON.stringify({ colors: {} }))).toBe('$.colors is not a theme token');
+  });
+
+  it('refuses a token group replaced by a scalar, and a colour replaced by an object', () => {
+    expect(expectRefusal(JSON.stringify({ overrides: { colors: 'red' } }))).toMatch(
+      /^\$\.overrides\.colors: /u,
+    );
+    expect(
+      expectRefusal(JSON.stringify({ overrides: { colors: { text: { accent: {} } } } })),
+    ).toMatch(/^\$\.overrides\.colors\.text\.accent: /u);
+  });
+
+  it('refuses a motion ramp that is not exactly four colours', () => {
+    expect(
+      expectRefusal(JSON.stringify({ overrides: { motion: { wave: ['red', 'blue'] } } })),
+    ).toMatch(/^\$\.overrides\.motion\.wave: /u);
+    const ok = parse(
+      JSON.stringify({ overrides: { motion: { wave: ['red', 'blue', 'green', 'cyan'] } } }),
+    );
+    expect(ok.ok).toBe(true);
+  });
+
+  it('refuses a name that is not a non-empty string', () => {
+    expect(expectRefusal(JSON.stringify({ name: '' }))).toBe('$.name: expected a non-empty string');
+  });
+
+  it('never lets a document reach the prototype', () => {
+    const error = expectRefusal('{"overrides":{"colors":{"text":{"__proto__":{"a":true}}}}}');
+    expect(error).toBe('$.overrides.colors.text.__proto__ is not a theme token');
+  });
+});

package/src/theme/__tests__/theme-registry.test.ts

@@ -0,0 +1,138 @@
+/**
+ * SCREEN-2002 TC-09/TC-10 — the registry and the catalogue port.
+ *
+ * The property worth guarding is that an unknown id NAMES itself. Resolving silently would make a
+ * removed plugin theme look like a theme that stopped working, and the id is the only thing that
+ * can point at the cause.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { DARK_THEME, LIGHT_THEME, listBuiltInThemes } from '../built-in-themes.js';
+import {
+  createThemeCataloguePort,
+  createThemeRegistry,
+  formatUnknownThemeNotice,
+} from '../theme-registry.js';
+
+import type { IAppearanceSettings } from '@robota-sdk/agent-interface-command';
+
+const APPEARANCE: IAppearanceSettings = {
+  theme: 'dark',
+  syntaxHighlighting: true,
+  reducedMotion: false,
+};
+
+describe('the theme registry (SCREEN-2002 TC-09)', () => {
+  it('lists the built-ins and finds one by id', () => {
+    const registry = createThemeRegistry();
+
+    expect(registry.list().map((theme) => theme.id)).toEqual([
+      'dark',
+      'light',
+      'dark-daltonized',
+      'light-daltonized',
+    ]);
+    expect(registry.get('light')?.name).toBe(LIGHT_THEME.name);
+    expect(registry.get('nope')).toBeUndefined();
+  });
+
+  it('resolves a known id without naming a miss', () => {
+    const resolution = createThemeRegistry().resolve('light');
+
+    expect(resolution.theme.id).toBe('light');
+    expect(resolution.unknownId).toBeUndefined();
+  });
+
+  it('falls back to the default AND names the id it could not find', () => {
+    const resolution = createThemeRegistry().resolve('solarized');
+
+    expect(resolution.theme.id).toBe(DARK_THEME.id);
+    // The whole point: the caller can say WHICH theme is missing.
+    expect(resolution.unknownId).toBe('solarized');
+    expect(formatUnknownThemeNotice('solarized')).toContain('solarized');
+  });
+
+  it('treats an absent id as no request at all, not as a miss', () => {
+    const resolution = createThemeRegistry().resolve(undefined);
+
+    expect(resolution.theme.id).toBe(DARK_THEME.id);
+    expect(resolution.unknownId).toBeUndefined();
+  });
+
+  it('carries a caller-supplied catalogue, which is how work unit 3 adds user themes', () => {
+    const registry = createThemeRegistry([LIGHT_THEME]);
+
+    expect(registry.list()).toEqual([LIGHT_THEME]);
+    expect(registry.get('dark')).toBeUndefined();
+  });
+});
+
+describe('the catalogue port (SCREEN-2002 TC-09)', () => {
+  it('projects identity and source, never a colour', () => {
+    const port = createThemeCataloguePort({
+      registry: createThemeRegistry(),
+      readAppearance: () => APPEARANCE,
+    });
+
+    const entry = port.getTheme('dark');
+
+    expect(entry).toEqual({
+      id: 'dark',
+      name: DARK_THEME.name,
+      appearance: DARK_THEME.appearance,
+      source: DARK_THEME.source,
+    });
+    // A command asks about ids; colours belong to whatever is rendering.
+    expect(Object.keys(entry ?? {})).not.toContain('colors');
+  });
+
+  it('RE-READS the appearance on every call, so a just-applied patch is visible', () => {
+    let stored: IAppearanceSettings = { ...APPEARANCE };
+    const port = createThemeCataloguePort({
+      registry: createThemeRegistry(),
+      readAppearance: () => stored,
+    });
+
+    expect(port.getAppearance().settings.theme).toBe('dark');
+    // The host wrote the settings document between the two calls.
+    stored = { ...stored, theme: 'light' };
+    expect(port.getAppearance().settings.theme).toBe('light');
+  });
+
+  it('omits the override entirely when nothing pinned this run', () => {
+    const port = createThemeCataloguePort({
+      registry: createThemeRegistry(),
+      readAppearance: () => APPEARANCE,
+    });
+
+    expect('reducedMotionPin' in port.getAppearance()).toBe(false);
+  });
+
+  it('reports the tier that pinned reduced motion AND what it pinned', () => {
+    // One pair, not two optional fields: a tier alone cannot say which way a run went, because
+    // `--no-reduced-motion` is an override too. The shape makes the half-supplied case unwritable.
+    const port = createThemeCataloguePort({
+      registry: createThemeRegistry(),
+      readAppearance: () => APPEARANCE,
+      reducedMotionPin: { tier: 'flag', reducedMotion: false },
+    });
+
+    expect(port.getAppearance().reducedMotionPin).toEqual({ tier: 'flag', reducedMotion: false });
+  });
+});
+
+describe('a registry that also carries what it could not load (SCREEN-2002 TC-11)', () => {
+  const skip = { id: 'custom:broken', fileName: 'broken.json', reason: '$.overrides: boom' };
+
+  it('keeps skipped files out of the themes it can resolve', () => {
+    const registry = createThemeRegistry(listBuiltInThemes(), [skip]);
+    expect(registry.get('custom:broken')).toBeUndefined();
+    expect(registry.list().some((theme) => theme.id === 'custom:broken')).toBe(false);
+    expect(registry.resolve('custom:broken').unknownId).toBe('custom:broken');
+  });
+
+  it('reports them separately, so a surface can SHOW a file it will not apply', () => {
+    expect(createThemeRegistry(listBuiltInThemes(), [skip]).skipped()).toEqual([skip]);
+    expect(createThemeRegistry().skipped()).toEqual([]);
+  });
+});

package/src/theme/__tests__/theme-styles.test.ts

@@ -0,0 +1,233 @@
+/**
+ * SCREEN-2002 TC-01/TC-02 — the token model and the style builder.
+ *
+ * The load-bearing assertion is the `dark` theme against the values the package shipped before the
+ * theme existed: the whole unit is only safe if a user who sets nothing sees the same colours. The
+ * four recorded byte exceptions (chalk's paired closers, the builder's SGR chain order, `type` keeping
+ * `dim`, and `strong`/`em`/`listitem` not being theme tokens) are asserted by name here rather than
+ * discovered later.
+ */
+import chalk from 'chalk';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { BUILT_IN_THEMES, DARK_THEME } from '../built-in-themes.js';
+import { THEME_SYNTAX_KEYS } from '../theme-contracts.js';
+import {
+  background,
+  diffRowStyles,
+  foreground,
+  isThemeColor,
+  markdownRendererOptions,
+  syntaxHighlightTheme,
+} from '../theme-styles.js';
+
+/** cli-highlight's own coloured keys, read from the dependency when this test was written. */
+const CLI_HIGHLIGHT_COLOURED_KEYS = [
+  'keyword',
+  'built_in',
+  'type',
+  'literal',
+  'number',
+  'regexp',
+  'string',
+  'class',
+  'function',
+  'comment',
+  'doctag',
+  'meta',
+  'tag',
+  'name',
+  'attr',
+  'addition',
+  'deletion',
+];
+
+const SGR = '\u001b[';
+const TRUECOLOR = 3;
+
+// chalk emits nothing when the test process has no TTY; these assertions are ABOUT the bytes, so the
+// level is forced for the file and restored afterwards.
+const originalLevel = chalk.level;
+beforeAll(() => {
+  chalk.level = TRUECOLOR;
+});
+afterAll(() => {
+  chalk.level = originalLevel;
+});
+
+describe('theme colour grammar (SCREEN-2002 TC-01)', () => {
+  it('accepts Inks grammar and nothing else', () => {
+    for (const value of [
+      'cyan',
+      'yellowBright',
+      'gray',
+      '#abc',
+      '#123456',
+      'ansi256(22)',
+      'rgb(1, 2, 3)',
+    ]) {
+      expect(isThemeColor(value)).toBe(true);
+    }
+    for (const value of [
+      '',
+      'nosuchcolour',
+      '#12345',
+      'ansi256(256)',
+      'rgb(1,2)',
+      `${SGR}31m`,
+      'cyan bold',
+      // A chalk BACKGROUND name is a real chalk style but never a token value: every token in the
+      // model is a foreground, and `background()` derives the `bg…` name from it.
+      'bgRed',
+      'bgCyan',
+    ]) {
+      expect(isThemeColor(value)).toBe(false);
+    }
+  });
+
+  it('builds a complete cli-highlight theme so no key falls back to its red/green default', () => {
+    expect([...THEME_SYNTAX_KEYS]).toEqual(CLI_HIGHLIGHT_COLOURED_KEYS);
+    for (const theme of BUILT_IN_THEMES) {
+      const built = syntaxHighlightTheme(theme.syntax);
+      expect(Object.keys(built).sort()).toEqual([...CLI_HIGHLIGHT_COLOURED_KEYS].sort());
+    }
+  });
+});
+
+describe('the dark theme reproduces todays rendering (SCREEN-2002 TC-02)', () => {
+  it('keeps every Ink colour value the package shipped', () => {
+    expect(DARK_THEME.colors).toEqual({
+      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',
+      },
+    });
+    expect(DARK_THEME.motion.wave).toEqual(['#555555', '#777777', '#999999', '#bbbbbb']);
+  });
+
+  it('renders each markdown token in marked-terminals own colour, with its structure fixed', () => {
+    const options = markdownRendererOptions(DARK_THEME.markdown);
+    // Byte equality against marked-terminal's own defaults: the builder reproduces each chain in the
+    // dependency's order, so the `dark` theme leaves markdown rendering untouched.
+    expect(options.heading?.('H')).toBe(chalk.green.bold('H'));
+    expect(options.code?.('C')).toBe(chalk.yellow('C'));
+    expect(options.codespan?.('C')).toBe(chalk.yellow('C'));
+    expect(options.link?.('L')).toBe(chalk.blue('L'));
+    expect(options.html?.('X')).toBe(chalk.gray('X'));
+    expect(options.firstHeading?.('F')).toBe(chalk.magenta.underline.bold('F'));
+    expect(options.blockquote?.('B')).toBe(chalk.gray.italic('B'));
+    expect(options.del?.('D')).toBe(chalk.dim.gray.strikethrough('D'));
+    expect(options.href?.('A')).toBe(chalk.blue.underline('A'));
+    // `strong`, `em`, `listitem` and `hr` are NOT theme tokens: the builder never supplies them, so
+    // marked-terminal keeps `chalk.bold` / `chalk.italic` / `chalk.reset` under every theme.
+    expect(options.strong).toBeUndefined();
+    expect(options.em).toBeUndefined();
+    expect(options.listitem).toBeUndefined();
+    expect(options.hr).toBeUndefined();
+  });
+
+  it('keeps cli-highlights `type` dim while taking its colour from the theme', () => {
+    const syntax = syntaxHighlightTheme(DARK_THEME.syntax);
+    expect(syntax.type?.('T')).toBe(chalk.cyan.dim('T'));
+    expect(syntax.keyword?.('K')).toBe(chalk.blue('K'));
+    expect(syntax.string?.('S')).toBe(chalk.red('S'));
+  });
+
+  it('paints diff rows with the former ANSI background/foreground pair', () => {
+    const styles = diffRowStyles(DARK_THEME);
+    const added = styles.added('+row');
+    // The former literal escapes: 48;5;22 background, 38;5;120 foreground.
+    expect(added).toContain(`${SGR}48;5;22m`);
+    expect(added).toContain(`${SGR}38;5;120m`);
+    const removed = styles.removed('-row');
+    expect(removed).toContain(`${SGR}48;5;52m`);
+    expect(removed).toContain(`${SGR}38;5;210m`);
+    // The hunk header takes the theme's colour; the `diff `/`index ` metadata rows take dim over the
+    // INHERITED foreground, exactly as this renderer always wrote them — no colour, no exception.
+    expect(styles.hunk('@@ -1 +1 @@')).toBe(chalk.cyan('@@ -1 +1 @@'));
+    expect(styles.meta('diff --git a/x b/x')).toBe(chalk.dim('diff --git a/x b/x'));
+    // Recorded exception: chalk closes with the paired resets, not the blanket reset.
+    expect(added.endsWith(`${SGR}0m`)).toBe(false);
+    expect(added).toContain(`${SGR}39m`);
+    expect(added).toContain(`${SGR}49m`);
+  });
+
+  it('refuses a background name where a foreground was asked for', () => {
+    // `isThemeColor` refuses `bgRed` as a token value; the builder must agree rather than hand back
+    // a background style. The style table holds the `bg…` entries for `background()`'s use.
+    expect(() => foreground('bgRed')).toThrow(/bgRed/u);
+    expect(background('red')('x')).toBe(chalk.bgRed('x'));
+  });
+
+  it('THROWS on a value outside the grammar rather than answering with a default style', () => {
+    // SCREEN-2002 work unit 3. These two answered the same question differently and silently —
+    // `foreground` with its base, `background` with `chalk.reset` — so a value neither could encode
+    // rendered as unstyled text in one place and as a reset in another. Unreachable while every
+    // value came from a validated built-in; reachable the moment a parsed file reaches the builder,
+    // which is why `parseThemeDocument` refuses a file WHOLE and this refuses what gets past it.
+    expect(() => foreground('not-a-colour')).toThrow(/not-a-colour/u);
+    expect(() => background('not-a-colour')).toThrow(/not-a-colour/u);
+    // The refusal names the grammar, because the value came from a file someone has to fix — and
+    // it names it COMPLETELY. `HEX` has always accepted the three-digit form, so a grammar string
+    // that lists only `#rrggbb` tells an author a value the builder accepts is invalid, in the one
+    // message they will read about it.
+    expect(() => foreground('not-a-colour')).toThrow(/#rgb \| #rrggbb/u);
+  });
+
+  it('accepts the three-digit hex form the grammar advertises', () => {
+    expect(isThemeColor('#0f0')).toBe(true);
+    expect(foreground('#0f0')('x')).toBe(chalk.hex('#0f0')('x'));
+    expect(background('#0f0')('x')).toBe(chalk.bgHex('#0f0')('x'));
+  });
+
+  it('keeps the terminals own colour DEPTH for diff rows when there is one', () => {
+    const daltonized = BUILT_IN_THEMES.find((theme) => theme.id === 'dark-daltonized');
+    expect(daltonized).toBeDefined();
+    const ANSI256 = 2;
+    const previous = chalk.level;
+    try {
+      // A 256-colour terminal: the row must downsample with the rest of the frame, not emit
+      // truecolor on its own because the diff renderer forced a level.
+      chalk.level = ANSI256;
+      const row = diffRowStyles(daltonized ?? DARK_THEME).added('+row');
+      expect(row).toContain(`${SGR}38;5;`);
+      expect(row).not.toContain(`${SGR}38;2;`);
+      // Colour OFF is the one case that IS overridden — the caller asked for colour.
+      chalk.level = 0;
+      const forced = diffRowStyles(daltonized ?? DARK_THEME).added('+row');
+      expect(forced).toContain(`${SGR}38;2;`);
+    } finally {
+      chalk.level = previous;
+    }
+  });
+
+  it('renders a light theme in different bytes from the dark one', () => {
+    const light = BUILT_IN_THEMES.find((theme) => theme.id === 'light');
+    expect(light).toBeDefined();
+    expect(foreground(light?.colors.text.accent ?? 'cyan')('x')).not.toBe(
+      foreground(DARK_THEME.colors.text.accent)('x'),
+    );
+  });
+});