@agi-fans/dsh-tui 0.21.0 → 0.22.0

package/lib/chrome/theme.js

@@ -3,6 +3,7 @@
  * glyphs used by terminal views.
  * @module @agi-fans/dsh-tui
  */
+import { contrastRatio, labDistance, nearestPaletteIndex, nearestXterm256, nearestXterm256Grey, relativeLuminance, toOklab, terminalColorsKey, } from "./terminal-colors.js";
 /** Rounded-box drawing characters (OMP unicode preset). */
 export const BOX = {
     topLeft: '╭',
@@ -55,35 +56,62 @@ const DARK_PALETTE = {
     border: '#3556b8',
     borderAccent: '#4d6bfe',
     borderMuted: '#3d424a',
+    // Every content colour sits near 67% lightness, which is what lets one ink
+    // stay readable across all three card fills. A 55% red reached 4.5:1 on a
+    // near-black card and only 3.4:1 once that card became a real grey.
     success: '#89d281',
-    error: '#fc4353',
+    error: '#ff8a8a',
     warning: '#e4c00f',
-    muted: '#858a94',
-    dim: '#666d7b',
+    muted: '#a3a8b2',
+    dim: '#858c99',
     text: '',
     userMessageText: '#e4e9f7',
     userMessageBg: '#141b30',
-    toolPendingBg: '#171e2e',
-    toolSuccessBg: '#141b26',
-    toolErrorBg: '#291d1d',
+    // The three states differ by hue and saturation at one lightness, the way pi's
+    // do. Three near-black fills a few units apart could only ever read as "dark";
+    // at 24% lightness a neutral pending, a green success, and a red failure name
+    // themselves without any status glyph.
+    toolPendingBg: '#34383a',
+    toolSuccessBg: '#254131',
+    toolAltBg: '#2b2f31',
+    toolErrorBg: '#5b282a',
     toolTitle: '#e0e0e0',
-    toolOutput: '#858a94',
+    toolOutput: '#a3a8b2',
     toolDiffAdded: '#89d281',
-    toolDiffRemoved: '#fc4353',
-    toolDiffContext: '#838a98',
-    mdHeading: '#7c93ff',
-    mdLink: '#7c93ff',
-    mdLinkUrl: '#7186bd',
-    mdCode: '#8a9099',
-    mdCodeBlock: '#9cdcfe',
+    toolDiffRemoved: '#ff8a8a',
+    toolDiffContext: '#a8aeb8',
+    // Content inks share one lightness and differ only in hue, the way pi's dark
+    // palette does. Two rules follow from that and neither held before:
+    //
+    // - A hue names a role, so no single hue may carry several. `mdHeading`,
+    //   `mdLink` and `mdListBullet` were all the accent blue, which made every
+    //   document look like one long link.
+    // - Nothing that is prose may be achromatic. Inline code was `#8a9099`
+    //   (chroma 0.015) and a prose-shaped codespan was `muted` — two greys the
+    //   reader cannot tell apart, for the one role that has to read as "this is
+    //   code".
+    //
+    // The syntax set used to be VSCode Dark+ values, which are drawn for a #1e1e1e
+    // editor and span 29 points of lightness here. These sit at 78% with chroma
+    // under 0.12, so a highlighted block varies in hue and not in weight.
+    mdHeading: '#ceb75b',
+    mdLink: '#83bdf8',
+    mdLinkUrl: '#7e95ad',
+    mdCode: '#d3a1ea',
+    mdCodeBlock: '#82cb9b',
     mdCodeBlockBorder: '#3d424a',
-    mdKeyword: '#569cd6',
-    syntaxString: '#ce9178',
-    syntaxNumber: '#b5cea8',
-    syntaxFunction: '#dcdcaa',
-    syntaxType: '#4ec9b0',
+    mdKeyword: '#83bdf8',
+    syntaxString: '#e7a875',
+    syntaxNumber: '#82cb9b',
+    syntaxFunction: '#cdb760',
+    syntaxType: '#d1a3e6',
     mdQuote: '#777d88',
-    mdListBullet: '#7c93ff',
+    mdQuoteBorder: '#3d424a',
+    mdHr: '#3d424a',
+    mdListBullet: '#a595c4',
+    // The composer's border while a `!` line is being typed. Green because that
+    // is the one signal that says "this leaves the model and runs on your machine".
+    shellMode: '#89d281',
     thinkingText: '#6b7280',
     customMessageLabel: '#b281d6',
 };
@@ -94,351 +122,51 @@ const LIGHT_PALETTE = {
     borderAccent: '#4d6bfe',
     borderMuted: '#b0b0b0',
     success: '#588458',
-    error: '#9f4f4f',
+    error: '#8f3a3a',
     warning: '#9a7326',
     muted: '#666666',
     dim: '#767676',
     text: '',
     userMessageText: '#1c2438',
     userMessageBg: '#e7ecf9',
-    toolPendingBg: '#eef1fa',
-    toolSuccessBg: '#e8f0e8',
-    toolErrorBg: '#f0e8e8',
+    // The same three states on paper: one lightness, three hues.
+    toolPendingBg: '#e7e8ea',
+    toolSuccessBg: '#dee9e1',
+    toolAltBg: '#eff0f2',
+    toolErrorBg: '#eee2e1',
     toolTitle: '#242424',
     toolOutput: '#666666',
     toolDiffAdded: '#4a6f4a',
-    toolDiffRemoved: '#9f4f4f',
+    toolDiffRemoved: '#93403f',
     toolDiffContext: '#666666',
-    mdHeading: '#3b57e0',
-    mdLink: '#3b57e0',
-    mdLinkUrl: '#5b6f9e',
-    mdCode: '#567b7b',
-    mdCodeBlock: '#567b7b',
+    // The same hue-per-role map as the dark palette, darkened for paper. Both
+    // palettes have to name a role with a hue, or switching themes would teach a
+    // reader a second visual language.
+    mdHeading: '#6d5900',
+    mdLink: '#1c62b3',
+    mdLinkUrl: '#465f7f',
+    mdCode: '#804797',
+    mdCodeBlock: '#247448',
     mdCodeBlockBorder: '#6c6c6c',
-    mdKeyword: '#0451a5',
-    syntaxString: '#a31515',
-    syntaxNumber: '#098558',
-    syntaxFunction: '#795e26',
-    syntaxType: '#267e97',
+    mdKeyword: '#1d5da7',
+    syntaxString: '#a24e10',
+    syntaxNumber: '#247448',
+    syntaxFunction: '#6d5900',
+    syntaxType: '#7e4a93',
     mdQuote: '#6c6c6c',
-    mdListBullet: '#3b57e0',
+    mdQuoteBorder: '#b8b8b8',
+    mdHr: '#b8b8b8',
+    mdListBullet: '#66508b',
+    shellMode: '#2f8f4e',
     thinkingText: '#6c6c6c',
     customMessageLabel: '#7e57c2',
 };
-const MIDNIGHT_PALETTE = {
-    ...DARK_PALETTE,
-    accent: '#7aa2f7',
-    border: '#3d59a1',
-    borderAccent: '#7dcfff',
-    borderMuted: '#3d424a',
-    success: '#9ece6a',
-    error: '#f7768e',
-    warning: '#e0af68',
-    muted: '#878d96',
-    dim: '#686f7e',
-    text: '',
-    userMessageBg: '#1a1b26',
-    toolPendingBg: '#16161e',
-    toolSuccessBg: '#1b2430',
-    toolErrorBg: '#2a1b26',
-    toolOutput: '#878d96',
-    toolDiffAdded: '#9ece6a',
-    toolDiffRemoved: '#f7768e',
-    toolDiffContext: '#858d9a',
-    mdHeading: '#bb9af7',
-    mdLink: '#7dcfff',
-    mdLinkUrl: '#626a77',
-    mdCode: '#7f8799',
-    mdCodeBlock: '#9aa5ce',
-    mdCodeBlockBorder: '#3d424a',
-    mdKeyword: '#bb9af7',
-    syntaxString: '#9ece6a',
-    syntaxNumber: '#ff9e64',
-    syntaxFunction: '#7aa2f7',
-    syntaxType: '#2ac3de',
-    mdQuote: '#777d88',
-    mdListBullet: '#7aa2f7',
-    thinkingText: '#6a7394',
-    customMessageLabel: '#bb9af7',
-    userMessageText: '#c0caf5',
-    toolTitle: '#c0caf5',
-};
-const SOLARIZED_PALETTE = {
-    ...DARK_PALETTE,
-    accent: '#c39400',
-    border: '#268bd2',
-    borderAccent: '#2aa198',
-    borderMuted: '#586e75',
-    success: '#859900',
-    error: '#e87b79',
-    warning: '#cb4b16',
-    muted: '#8e9e9f',
-    dim: '#668088',
-    text: '',
-    userMessageBg: '#073642',
-    toolPendingBg: '#002b36',
-    toolSuccessBg: '#073642',
-    toolErrorBg: '#3b2020',
-    toolOutput: '#8e9e9f',
-    toolDiffAdded: '#8fa500',
-    toolDiffRemoved: '#e87b79',
-    toolDiffContext: '#889fa6',
-    mdHeading: '#b58900',
-    mdLink: '#3496da',
-    mdLinkUrl: '#5e767d',
-    mdCode: '#93a1a1',
-    mdCodeBlock: '#2aa198',
-    mdCodeBlockBorder: '#073642',
-    mdKeyword: '#859900',
-    syntaxString: '#2aa198',
-    syntaxNumber: '#de66a0',
-    syntaxFunction: '#3496da',
-    syntaxType: '#b58900',
-    mdQuote: '#839496',
-    mdListBullet: '#b58900',
-    thinkingText: '#5e767d',
-    customMessageLabel: '#6c71c4',
-    userMessageText: '#93a1a1',
-    toolTitle: '#93a1a1',
-};
-const CATPPUCCIN_PALETTE = {
-    ...DARK_PALETTE,
-    accent: '#fab387',
-    border: '#89b4fa',
-    borderAccent: '#b4befe',
-    borderMuted: '#313244',
-    success: '#a6e3a1',
-    error: '#f38ba8',
-    warning: '#f9e2af',
-    muted: '#989db0',
-    dim: '#7a7d93',
-    text: '',
-    userMessageBg: '#181825',
-    toolPendingBg: '#313244',
-    toolSuccessBg: '#181825',
-    toolErrorBg: '#11111b',
-    toolTitle: '#b4befe',
-    toolOutput: '#989db0',
-    toolDiffAdded: '#a6e3a1',
-    toolDiffRemoved: '#f38ba8',
-    toolDiffContext: '#989db0',
-    mdHeading: '#fab387',
-    mdLink: '#89b4fa',
-    mdLinkUrl: '#6c7086',
-    mdCode: '#a6adc8',
-    mdCodeBlock: '#cdd6f4',
-    mdCodeBlockBorder: '#313244',
-    mdKeyword: '#cba6f7',
-    syntaxString: '#a6e3a1',
-    syntaxNumber: '#fab387',
-    syntaxFunction: '#89b4fa',
-    syntaxType: '#f9e2af',
-    mdQuote: '#7f849c',
-    mdListBullet: '#fab387',
-    thinkingText: '#6c7086',
-    customMessageLabel: '#cba6f7',
-    userMessageText: '#cdd6f4',
-};
-const DRACULA_PALETTE = {
-    ...DARK_PALETTE,
-    accent: '#bd93f9',
-    border: '#bd93f9',
-    borderAccent: '#ff79c6',
-    borderMuted: '#44475a',
-    success: '#50fa7b',
-    error: '#ff5a5a',
-    warning: '#f1fa8c',
-    muted: '#8693b9',
-    dim: '#6f7492',
-    text: '',
-    userMessageBg: '#1f2029',
-    toolPendingBg: '#21222c',
-    toolSuccessBg: '#1a1f1e',
-    toolErrorBg: '#2a2028',
-    toolTitle: '#8be9fd',
-    toolOutput: '#8693b9',
-    toolDiffAdded: '#50fa7b',
-    toolDiffRemoved: '#ff5a5a',
-    toolDiffContext: '#8693b9',
-    mdHeading: '#bd93f9',
-    mdLink: '#8be9fd',
-    mdLinkUrl: '#6474a5',
-    mdCode: '#9aa3c7',
-    mdCodeBlock: '#f8f8f2',
-    mdCodeBlockBorder: '#44475a',
-    mdKeyword: '#ff79c6',
-    syntaxString: '#f1fa8c',
-    syntaxNumber: '#bd93f9',
-    syntaxFunction: '#50fa7b',
-    syntaxType: '#8be9fd',
-    mdQuote: '#6474a5',
-    mdListBullet: '#ff79c6',
-    thinkingText: '#6474a5',
-    customMessageLabel: '#bd93f9',
-    userMessageText: '#f8f8f2',
-};
-const NORD_PALETTE = {
-    ...DARK_PALETTE,
-    accent: '#88c0d0',
-    border: '#5e81ac',
-    borderAccent: '#88c0d0',
-    borderMuted: '#434c5e',
-    success: '#a3be8c',
-    error: '#daa2a8',
-    warning: '#ebcb8b',
-    muted: '#a8b1c1',
-    dim: '#8490a7',
-    text: '',
-    userMessageBg: '#3b4252',
-    toolPendingBg: '#3b4252',
-    toolSuccessBg: '#2e3440',
-    toolErrorBg: '#3b2f31',
-    toolTitle: '#88c0d0',
-    toolOutput: '#a8b1c1',
-    toolDiffAdded: '#a3be8c',
-    toolDiffRemoved: '#daa2a8',
-    toolDiffContext: '#a8b1c1',
-    mdHeading: '#88c0d0',
-    mdLink: '#88c0d0',
-    mdLinkUrl: '#727f9a',
-    mdCode: '#82a2c1',
-    mdCodeBlock: '#d8dee9',
-    mdCodeBlockBorder: '#434c5e',
-    mdKeyword: '#82a2c1',
-    syntaxString: '#a3be8c',
-    syntaxNumber: '#b793b1',
-    syntaxFunction: '#88c0d0',
-    syntaxType: '#8fbcbb',
-    mdQuote: '#7b88a1',
-    mdListBullet: '#81a1c1',
-    thinkingText: '#747f95',
-    customMessageLabel: '#b48ead',
-    userMessageText: '#d8dee9',
-};
-const GRUVBOX_PALETTE = {
-    ...DARK_PALETTE,
-    accent: '#fe8019',
-    border: '#458588',
-    borderAccent: '#8ec07c',
-    borderMuted: '#504945',
-    success: '#b8bb26',
-    error: '#fc6c5c',
-    warning: '#fabd2f',
-    muted: '#a4988b',
-    dim: '#87796d',
-    text: '',
-    userMessageBg: '#1d2021',
-    toolPendingBg: '#32302f',
-    toolSuccessBg: '#1d2021',
-    toolErrorBg: '#3c2021',
-    toolTitle: '#ebdbb2',
-    toolOutput: '#a4988b',
-    toolDiffAdded: '#b8bb26',
-    toolDiffRemoved: '#fc6c5c',
-    toolDiffContext: '#a4988b',
-    mdHeading: '#fabd2f',
-    mdLink: '#8ec07c',
-    mdLinkUrl: '#7e7165',
-    mdCode: '#bdae93',
-    mdCodeBlock: '#ebdbb2',
-    mdCodeBlockBorder: '#504945',
-    mdKeyword: '#d3869b',
-    syntaxString: '#b8bb26',
-    syntaxNumber: '#d3869b',
-    syntaxFunction: '#fabd2f',
-    syntaxType: '#8ec07c',
-    mdQuote: '#928374',
-    mdListBullet: '#fe8019',
-    thinkingText: '#7e7165',
-    customMessageLabel: '#d3869b',
-    userMessageText: '#ebdbb2',
-};
-const ROSE_PINE_PALETTE = {
-    ...DARK_PALETTE,
-    accent: '#c4a7e7',
-    border: '#31748f',
-    borderAccent: '#9ccfd8',
-    borderMuted: '#403d52',
-    success: '#9ccfd8',
-    error: '#eb6f92',
-    warning: '#f6c177',
-    muted: '#8c89a2',
-    dim: '#6f6b8b',
-    text: '',
-    userMessageBg: '#21202e',
-    toolPendingBg: '#1f1d2e',
-    toolSuccessBg: '#21202e',
-    toolErrorBg: '#2d1f26',
-    toolTitle: '#9ccfd8',
-    toolOutput: '#8c89a2',
-    toolDiffAdded: '#9ccfd8',
-    toolDiffRemoved: '#eb6f92',
-    toolDiffContext: '#8c89a2',
-    mdHeading: '#c4a7e7',
-    mdLink: '#9ccfd8',
-    mdLinkUrl: '#908caa',
-    mdCode: '#a8a4c4',
-    mdCodeBlock: '#e0def4',
-    mdCodeBlockBorder: '#403d52',
-    mdKeyword: '#3b8cac',
-    syntaxString: '#f6c177',
-    syntaxNumber: '#ebbcba',
-    syntaxFunction: '#9ccfd8',
-    syntaxType: '#c4a7e7',
-    mdQuote: '#6e6a86',
-    mdListBullet: '#c4a7e7',
-    thinkingText: '#6e6a86',
-    customMessageLabel: '#c4a7e7',
-    userMessageText: '#e0def4',
-};
-const MONO_PALETTE = {
-    accent: '#e8e8e8',
-    border: '#888888',
-    borderAccent: '#b8b8b8',
-    borderMuted: '#444444',
-    success: '#c0c0c0',
-    error: '#f0f0f0',
-    warning: '#a8a8a8',
-    muted: '#939393',
-    dim: '#757575',
-    text: '',
-    userMessageText: '#e8e8e8',
-    userMessageBg: '#202020',
-    toolPendingBg: '#242424',
-    toolSuccessBg: '#1c1c1c',
-    toolErrorBg: '#2a2a2a',
-    toolTitle: '#e8e8e8',
-    toolOutput: '#939393',
-    toolDiffAdded: '#c0c0c0',
-    toolDiffRemoved: '#f0f0f0',
-    toolDiffContext: '#939393',
-    mdHeading: '#e8e8e8',
-    mdLink: '#b8b8b8',
-    mdLinkUrl: '#666666',
-    mdCode: '#a0a0a0',
-    mdCodeBlock: '#c0c0c0',
-    mdCodeBlockBorder: '#444444',
-    mdKeyword: '#b8b8b8',
-    syntaxString: '#c0c0c0',
-    syntaxNumber: '#a0a0a0',
-    syntaxFunction: '#e8e8e8',
-    syntaxType: '#b8b8b8',
-    mdQuote: '#888888',
-    mdListBullet: '#b8b8b8',
-    thinkingText: '#767676',
-    customMessageLabel: '#a8a8a8',
-};
 const PALETTES = {
     dark: DARK_PALETTE,
     light: LIGHT_PALETTE,
-    midnight: MIDNIGHT_PALETTE,
-    solarized: SOLARIZED_PALETTE,
-    catppuccin: CATPPUCCIN_PALETTE,
-    dracula: DRACULA_PALETTE,
-    nord: NORD_PALETTE,
-    gruvbox: GRUVBOX_PALETTE,
-    'rose-pine': ROSE_PINE_PALETTE,
-    mono: MONO_PALETTE,
+    // `system` starts from the neutral palette and is rebuilt from the reported
+    // terminal colors when a launch can probe them.
+    system: DARK_PALETTE,
 };
 /**
  * 16-color foreground fallbacks when the terminal is not truecolor. Entries
@@ -465,6 +193,7 @@ const DARK_ANSI16 = {
     // Neutral fills avoid same-index collisions with error and diff ink.
     toolPendingBg: '30',
     toolSuccessBg: '30',
+    toolAltBg: '30',
     toolErrorBg: '30',
     toolTitle: '37',
     toolOutput: '37',
@@ -479,7 +208,10 @@ const DARK_ANSI16 = {
     mdCodeBlockBorder: '90',
     mdKeyword: '36',
     mdQuote: '37',
+    mdQuoteBorder: '90',
+    mdHr: '90',
     mdListBullet: '94',
+    shellMode: '92',
     thinkingText: '90',
     customMessageLabel: '35',
 };
@@ -500,8 +232,12 @@ const LIGHT_ANSI16 = {
     text: '39',
     userMessageText: '30',
     userMessageBg: '37',
+    // This table holds *foreground* codes; `toBackgrounds` adds the 10 that turns
+    // them into fills, so `37` here is the white `\x1b[47m` card a light terminal
+    // needs under its dark ink.
     toolPendingBg: '37',
     toolSuccessBg: '37',
+    toolAltBg: '37',
     toolErrorBg: '37',
     toolTitle: '30',
     toolOutput: '30',
@@ -516,119 +252,17 @@ const LIGHT_ANSI16 = {
     mdCodeBlockBorder: '90',
     mdKeyword: '34',
     mdQuote: '30',
+    mdQuoteBorder: '90',
+    mdHr: '90',
     mdListBullet: '34',
+    shellMode: '32',
     thinkingText: '90',
     customMessageLabel: '35',
 };
-const MIDNIGHT_ANSI16 = {
-    ...DARK_ANSI16,
-    accent: '34',
-    border: '34',
-    borderAccent: '36',
-    mdHeading: '35',
-    mdLink: '36',
-    mdKeyword: '35',
-    mdListBullet: '34',
-    customMessageLabel: '35',
-};
-const SOLARIZED_ANSI16 = {
-    ...DARK_ANSI16,
-    accent: '33',
-    border: '34',
-    borderAccent: '36',
-    mdHeading: '33',
-    mdLink: '34',
-    mdKeyword: '32',
-    mdCodeBlock: '36',
-    mdListBullet: '33',
-    customMessageLabel: '35',
-};
-const CATPPUCCIN_ANSI16 = {
-    ...DARK_ANSI16,
-    accent: '33',
-    border: '34',
-    borderAccent: '35',
-    mdHeading: '33',
-    mdLink: '34',
-    mdKeyword: '35',
-    mdListBullet: '33',
-    customMessageLabel: '35',
-};
-const DRACULA_ANSI16 = {
-    ...DARK_ANSI16,
-    accent: '35',
-    border: '35',
-    borderAccent: '35',
-    mdHeading: '35',
-    mdLink: '36',
-    mdKeyword: '35',
-    mdListBullet: '35',
-    customMessageLabel: '35',
-};
-const NORD_ANSI16 = {
-    ...DARK_ANSI16,
-    accent: '36',
-    border: '34',
-    borderAccent: '36',
-    mdHeading: '36',
-    mdLink: '36',
-    mdKeyword: '34',
-    mdListBullet: '34',
-    customMessageLabel: '35',
-};
-const GRUVBOX_ANSI16 = {
-    ...DARK_ANSI16,
-    accent: '33',
-    border: '36',
-    borderAccent: '32',
-    mdHeading: '33',
-    mdLink: '32',
-    mdKeyword: '35',
-    mdListBullet: '33',
-    customMessageLabel: '35',
-};
-const ROSE_PINE_ANSI16 = {
-    ...DARK_ANSI16,
-    accent: '35',
-    border: '36',
-    borderAccent: '36',
-    mdHeading: '35',
-    mdLink: '36',
-    mdKeyword: '36',
-    mdListBullet: '35',
-    customMessageLabel: '35',
-};
-const MONO_ANSI16 = {
-    ...DARK_ANSI16,
-    syntaxString: '37',
-    syntaxNumber: '37',
-    syntaxFunction: '97',
-    syntaxType: '37',
-    accent: '97',
-    border: '37',
-    borderAccent: '97',
-    success: '37',
-    error: '97',
-    warning: '37',
-    muted: '37',
-    mdHeading: '97',
-    mdLink: '37',
-    mdCodeBlock: '37',
-    mdKeyword: '37',
-    mdListBullet: '37',
-    customMessageLabel: '37',
-};
 const ANSI16 = {
     dark: DARK_ANSI16,
     light: LIGHT_ANSI16,
-    midnight: MIDNIGHT_ANSI16,
-    solarized: SOLARIZED_ANSI16,
-    catppuccin: CATPPUCCIN_ANSI16,
-    dracula: DRACULA_ANSI16,
-    nord: NORD_ANSI16,
-    gruvbox: GRUVBOX_ANSI16,
-    'rose-pine': ROSE_PINE_ANSI16,
-    mono: MONO_ANSI16,
+    system: DARK_ANSI16,
 };
 /** Distance from a foreground SGR code to its background twin: 31 → 41, 39 → 49. */
 const BG_CODE_OFFSET = 10;
@@ -645,18 +279,164 @@ function toBackgrounds(foreground) {
     }
     return result;
 }
+/**
+ * Backgrounds for the three tool states, chosen so they stay distinct.
+ *
+ * This is the group form of the problem {@link nearestXterm256} solves for one
+ * colour: the states differ mostly in hue and only slightly in lightness, so
+ * quantising each swatch on its own collapses them. The assignment below picks a
+ * distinct entry per state and then orders the three by lightness, so pending,
+ * success, and error remain recognizable even on a terminal that offers only
+ * eight backgrounds.
+ *
+ * A 16-colour terminal simply has fewer backgrounds than the states that need
+ * one. Rather than paint three states the same black, the ones it cannot tint
+ * fall back to `toolSuccessBg` and the error state — the only one a reader must
+ * act on — is given the red it already has in `ansiBg` when the palette has a
+ * usable red background.
+ */
+function resolveToolFills(name, depth, terminal) {
+    const palette = name === 'system' ? systemPalette(terminal) : PALETTES[name];
+    const reported = depth === 'ansi16' && terminal?.palette !== undefined && terminal.palette.length === 16
+        ? terminal.palette
+        : undefined;
+    const states = ['toolPendingBg', 'toolSuccessBg', 'toolErrorBg'];
+    const swatches = states.map(state => {
+        const swatch = palette[state];
+        if (typeof swatch !== 'string' || swatch === '')
+            return undefined;
+        const [r, g, b] = hexToRgb(swatch);
+        return { r, g, b };
+    });
+    const filled = swatches.every((swatch) => swatch !== undefined);
+    if (!filled)
+        return undefined;
+    if (depth === 'ansi256') {
+        // The neutral ramp is where the three near-black surfaces actually live; the
+        // colour cube would round them all to the same corner.
+        const indices = swatches.map(swatch => nearestXterm256Grey(swatch));
+        return assignDistinct(states, indices, index => `\x1b[48;5;${index}m`);
+    }
+    if (reported !== undefined) {
+        // Sixteen colours are not enough for three surfaces, so each state claims a
+        // *different* entry from the ones its own hue actually reaches, rather than
+        // nudging a number that has no meaning in this palette.
+        return pickDistinctPaletteEntries(name, states, swatches, reported, index => ansiIndexSgr(index, true));
+    }
+    // The terminal never answered our colour query, so the standard xterm ANSI
+    // meanings are assumed: three different backgrounds that carry text. Guessing
+    // per swatch here is exactly what collapsed the three states into one. Red is
+    // deliberately not one of them — a red fill would share its palette slot with
+    // the red `error` and `toolDiffRemoved` ink drawn on top of it.
+    // A light card is white paper under dark ink, and the eight backgrounds an
+    // ANSI-16 terminal offers contain exactly one that carries it. Pending and
+    // success therefore share it, and the failing card — the state a reader has to
+    // act on — is the one that gets a fill of its own.
+    return name === 'light'
+        ? { toolPendingBg: '\x1b[47m', toolSuccessBg: '\x1b[47m', toolErrorBg: '\x1b[45m' }
+        : { toolPendingBg: '\x1b[44m', toolSuccessBg: '\x1b[40m', toolErrorBg: '\x1b[45m' };
+}
+/**
+ * Give each state the nearest palette entry no other state has taken.
+ *
+ * A 16-colour terminal cannot express a subtle tint, so the question stops being
+ * "which entry is nearest" and becomes "which entry can this state have". Each
+ * state is served in turn, by increasing distance, and only entries whose
+ * luminance is low enough to hold card text are considered — a bright palette
+ * entry would turn a tool card into a block of white.
+ */
+function pickDistinctPaletteEntries(name, states, swatches, palette, encode) {
+    // A palette slot already used as ink on a card is not available as a fill: a
+    // red background under red diff lines erases them. The check runs against the
+    // same fallback table the foreground codes come from, so the two can never
+    // disagree about which slot a colour occupies.
+    const takenByInk = new Set(CARD_INK_COLORS
+        .map(color => Number.parseInt(ANSI16[name][color], 10))
+        .filter(code => Number.isInteger(code) && code < 8));
+    const ceiling = SURFACE_MAX_LUMINANCE[name];
+    // A light card's ink is a black that owns slot 0, so its fills come from the
+    // bright end instead; the test is "far enough from the ink", not "dark".
+    const eligible = (entry, index) => entry !== undefined
+        && !takenByInk.has(index)
+        && (name === 'light' ? relativeLuminance(entry) >= ceiling : relativeLuminance(entry) < ceiling);
+    if (palette.filter(eligible).length < states.length)
+        return undefined;
+    const ranked = palette
+        .flatMap((entry, index) => entry === undefined ? [] : [{ index, entry: entry }])
+        .filter(({ entry, index }) => eligible(entry, index))
+        .map(({ index, entry }) => ({ index, lab: toOklab(entry) }));
+    if (ranked.length < states.length)
+        return undefined;
+    const used = new Set();
+    const result = {};
+    for (let at = 0; at < states.length; at += 1) {
+        const target = toOklab(swatches[at]);
+        let best;
+        for (const candidate of ranked) {
+            if (used.has(candidate.index))
+                continue;
+            const distance = labDistance(target, candidate.lab);
+            if (best === undefined || distance < best.distance)
+                best = { index: candidate.index, distance };
+        }
+        if (best === undefined)
+            return undefined;
+        used.add(best.index);
+        result[states[at]] = encode(best.index);
+    }
+    return result;
+}
+/** Ink drawn on a tool card, by theme token and ANSI-16 fallback code. */
+const CARD_INK_COLORS = [
+    'toolTitle', 'toolOutput', 'toolDiffAdded', 'toolDiffRemoved', 'toolDiffContext',
+    'mdKeyword', 'syntaxString', 'syntaxNumber', 'syntaxFunction', 'syntaxType',
+    'mdCodeBlock', 'mdLink', 'mdHeading', 'mdQuote', 'dim', 'muted', 'accent',
+    'success', 'error', 'warning', 'thinkingText', 'mdListBullet', 'mdHr',
+    'mdQuoteBorder', 'mdCodeBlockBorder', 'mdCode', 'mdLinkUrl',
+];
+/**
+ * How light a card fill may be, per palette.
+ *
+ * The constraint is not "dark" — it is "far from the ink". A dark theme draws
+ * light text on a dark fill and a light theme draws dark text on a light fill, so
+ * each palette states its own ceiling instead of sharing a dark one that would
+ * make every card on a light terminal a black block.
+ */
+const SURFACE_MAX_LUMINANCE = {
+    dark: 0.5, system: 0.5,
+    // A light card's fill comes from the bright end; the ceiling is its floor.
+    light: 0.98,
+};
+/**
+ * Give every state its own encoding, nudging the ones that collided.
+ *
+ * `preferred` is the honest per-state choice; when two states land on it, the
+ * one further from the light end is pushed to a neighbouring entry. A terminal
+ * whose palette has no room left keeps the collision rather than inventing a
+ * colour it cannot draw, which is why this returns `undefined` in that case.
+ */
+function assignDistinct(states, preferred, encode) {
+    const used = new Set();
+    const result = {};
+    for (let at = 0; at < states.length; at += 1) {
+        const state = states[at];
+        let index = preferred[at] ?? 0;
+        for (let step = 1; used.has(index) && step < 8; step += 1) {
+            // Alternate lighter and darker so a nudge stays close to the intent.
+            index = preferred[at] + (step % 2 === 1 ? -step : step);
+        }
+        if (used.has(index))
+            return undefined;
+        used.add(index);
+        result[state] = encode(index);
+    }
+    return result;
+}
 /** 16-color background fallbacks when the terminal is not truecolor. */
 const ANSI16_BG = {
     dark: toBackgrounds(DARK_ANSI16),
     light: toBackgrounds(LIGHT_ANSI16),
-    midnight: toBackgrounds(MIDNIGHT_ANSI16),
-    solarized: toBackgrounds(SOLARIZED_ANSI16),
-    catppuccin: toBackgrounds(CATPPUCCIN_ANSI16),
-    dracula: toBackgrounds(DRACULA_ANSI16),
-    nord: toBackgrounds(NORD_ANSI16),
-    gruvbox: toBackgrounds(GRUVBOX_ANSI16),
-    'rose-pine': toBackgrounds(ROSE_PINE_ANSI16),
-    mono: toBackgrounds(MONO_ANSI16),
+    system: toBackgrounds(DARK_ANSI16),
 };
 const FG_RESET = '\x1b[39m';
 const BG_RESET = '\x1b[49m';
@@ -666,11 +446,15 @@ const UNDERLINE_RESET = '\x1b[24m';
 const STRIKE_RESET = '\x1b[29m';
 const INVERSE_RESET = '\x1b[27m';
 /** Built-in palettes, including a few well-known oh-my-pi coding themes. */
-export const THEME_NAMES = [
-    'dark', 'light', 'midnight', 'solarized',
-    'catppuccin', 'dracula', 'nord', 'gruvbox', 'rose-pine',
-    'mono',
-];
+/**
+ * Shipped palettes: one dark, one light, and the one that follows the terminal.
+ *
+ * A theme is a contract the whole TUI is read through — every card, diff, and
+ * syntax token has to stay legible on it — so the set stays small enough to hold
+ * to that standard. `system` is not a third design: it derives its surfaces from
+ * the colours the terminal reports and then follows the same rules.
+ */
+export const THEME_NAMES = ['dark', 'light', 'system'];
 /** True when `value` is a shipped palette name. */
 export function isThemeName(value) {
     return THEME_NAMES.includes(value);
@@ -726,27 +510,282 @@ function hexToRgb(hex) {
         Number.parseInt(body.slice(4, 6), 16),
     ];
 }
-/** Foreground SGR for one swatch; `fallback` is a code from {@link ANSI16}. */
-function fgCode(swatch, trueColor, fallback) {
+/**
+ * SGR for one swatch at a color depth; `fallback` is a code from
+ * {@link ANSI16} or {@link ANSI16_BG}. `layer` is 38 for ink and 48 for fill.
+ */
+function swatchCode(swatch, depth, fallback, layer) {
     if (swatch === '')
-        return '\x1b[39m';
+        return layer === 38 ? '\x1b[39m' : '\x1b[49m';
     if (typeof swatch === 'number')
-        return `\x1b[38;5;${swatch}m`;
-    if (!trueColor)
+        return `\x1b[${layer};5;${swatch}m`;
+    if (depth === 'ansi16')
         return `\x1b[${fallback}m`;
     const [r, g, b] = hexToRgb(swatch);
-    return `\x1b[38;2;${r};${g};${b}m`;
+    if (depth === 'ansi256')
+        return `\x1b[${layer};5;${nearestXterm256({ r, g, b })}m`;
+    return `\x1b[${layer};2;${r};${g};${b}m`;
 }
-/** Background SGR for one swatch; `fallback` is a code from {@link ANSI16_BG}. */
-function bgCode(swatch, trueColor, fallback) {
-    if (swatch === '')
-        return '\x1b[49m';
-    if (typeof swatch === 'number')
-        return `\x1b[48;5;${swatch}m`;
-    if (!trueColor)
-        return `\x1b[${fallback}m`;
-    const [r, g, b] = hexToRgb(swatch);
-    return `\x1b[48;2;${r};${g};${b}m`;
+/** Mix two colors in linear light; `weight` is the share of `to`. */
+function mixRgb(from, to, weight) {
+    const linear = (value) => {
+        const channelValue = value / 255;
+        return channelValue <= 0.04045 ? channelValue / 12.92 : ((channelValue + 0.055) / 1.055) ** 2.4;
+    };
+    const encode = (value) => {
+        const clamped = Math.max(0, Math.min(1, value));
+        return Math.round(255 * (clamped <= 0.003_130_8 ? clamped * 12.92 : 1.055 * clamped ** (1 / 2.4) - 0.055));
+    };
+    const mix = (left, right) => linear(left) * (1 - weight) + linear(right) * weight;
+    return { r: encode(mix(from.r, to.r)), g: encode(mix(from.g, to.g)), b: encode(mix(from.b, to.b)) };
+}
+function toHex(color) {
+    const part = (value) => Math.round(value).toString(16).padStart(2, '0');
+    return `#${part(color.r)}${part(color.g)}${part(color.b)}`;
+}
+/** The fixed red a `system` error surface mixes toward when the palette has none. */
+const SYSTEM_ERROR_RED = { r: 0xff, g: 0x5f, b: 0x5f };
+/** The fixed green a `system` success surface mixes toward when the palette has none. */
+const SYSTEM_SUCCESS_GREEN = { r: 0x4a, g: 0xc8, b: 0x7a };
+/** The fixed blue a `system` notice surface mixes toward when the palette has none. */
+const SYSTEM_NOTICE_BLUE = { r: 0x6f, g: 0xa8, b: 0xff };
+/**
+ * Relative luminance each card state is held to on a `system` palette.
+ *
+ * These are the shipped dark palette's own fills measured as luminance, so a
+ * `system` card sits where a `dark` one does no matter what green the terminal
+ * reports. They are the one part of the card that must not follow the terminal:
+ * a terminal's green is chosen for *ink* on its background, and spending that
+ * green on a large fill is what pushed the shipped value from 4.4% to 11.7%
+ * luminance and flattened dimmed text on a successful card to 3.3:1.
+ */
+const SYSTEM_CARD_LUMINANCE = {
+    pending: 0.0386,
+    success: 0.0440,
+    error: 0.0391,
+};
+/**
+ * How far a card may move from the terminal background toward a state hue.
+ *
+ * A card is a step off the reader's own background, not a swatch of the terminal
+ * palette. Scaling a tint to the target luminance directly keeps the hue but not
+ * the calm: a saturated green has to be dimmed so far to reach 4.4% that the
+ * scaled channels clip, and a light terminal turns it neon. Interpolating from the
+ * background toward the hue instead bounds how much of the hue a card can ever
+ * contain, so the fill stays a surface whatever the terminal reports.
+ */
+const SYSTEM_CARD_TINT = 0.34;
+/**
+ * Where the alternate successful surface sits relative to the primary one.
+ *
+ * A slight step, not a second state: the pair exists so two adjacent successful
+ * calls do not merge into one block. Anything larger starts naming a difference
+ * that is not there.
+ */
+const SYSTEM_ALT_STEP = 1.065;
+/**
+ * The background-to-hue step that lands closest to a target relative luminance.
+ *
+ * A fixed weight cannot hold a card at one lightness — the same weight applied to
+ * a bright terminal green and to a dim one lands almost three stops apart — so the
+ * weight is solved for instead, by bisection. Hue still comes from the terminal,
+ * which is what makes the fill say "success"; how *much* of it a card spends is
+ * the theme's decision, and the tint cap is what keeps the result a surface.
+ */
+function tintAtLuminance(background, tint, target) {
+    const at = (weight) => mixRgb(background, tint, weight);
+    const luminanceAt = (weight) => relativeLuminance(at(weight));
+    // Interpolating between two luminance endpoints is monotonic only while one
+    // side sits below the target; a background already brighter than the target
+    // reverses which direction helps, so solve outward from the background.
+    const towardsBrighter = relativeLuminance(background) < target;
+    let low = 0;
+    let high = SYSTEM_CARD_TINT;
+    if (towardsBrighter ? luminanceAt(high) < target : luminanceAt(high) > target) {
+        // The capped step already overshoots or undershoots the target: the cap is
+        // the answer, and the card keeps the calm it was given.
+        return at(high);
+    }
+    for (let step = 0; step < 40; step += 1) {
+        const middle = (low + high) / 2;
+        if (towardsBrighter ? luminanceAt(middle) < target : luminanceAt(middle) > target)
+            low = middle;
+        else
+            high = middle;
+    }
+    return at((low + high) / 2);
+}
+/**
+ * The background lifted toward white until it reaches a target luminance.
+ *
+ * Neutral surfaces need a lightness step, not a hue: interpolating toward the
+ * foreground flattens whatever faint tint the terminal's background carries, so
+ * the step is taken toward white and the background's own channel ratios survive.
+ */
+function liftedToLuminance(background, target) {
+    // On paper the background is already brighter than a card wants to be, so the
+    // step goes toward black instead; either way it keeps the background's ratios.
+    const pole = relativeLuminance(background) < target ? { r: 255, g: 255, b: 255 } : { r: 0, g: 0, b: 0 };
+    const towardsBrighter = pole.r === 255;
+    const at = (weight) => mixRgb(background, pole, weight);
+    const luminanceAt = (weight) => relativeLuminance(at(weight));
+    let low = 0;
+    let high = 1;
+    for (let step = 0; step < 40; step += 1) {
+        const middle = (low + high) / 2;
+        if (towardsBrighter ? luminanceAt(middle) < target : luminanceAt(middle) > target)
+            low = middle;
+        else
+            high = middle;
+    }
+    return at((low + high) / 2);
+}
+/**
+ * The contrast a swatch keeps against the surfaces it is drawn on.
+ *
+ * Taken against the *weakest* card rather than against the page, because a
+ * secondary ink is spent on card fills — a hint on a successful card is the case
+ * that has to stay readable, not the same hint on bare background.
+ */
+function worstContrast(ink, cards) {
+    return Math.min(...cards.map(card => contrastRatio(ink, card)));
+}
+/**
+ * A secondary ink held at the contrast the shipped palette achieved.
+ *
+ * A fixed mix weight made the result depend on which side was bright: on a dark
+ * background the step lightened the ink and stayed safe, but against paper it
+ * moved it toward the page, so a light terminal's `dim` ended at 1.75:1 — nearly
+ * invisible. The weight is solved from the contrast actually achieved instead, so
+ * the live cards keep the hierarchy the palette was drawn with: this ink is as
+ * far from the text as the shipped one was from its own cards, no further.
+ */
+function quietInk(foreground, background, cards, target) {
+    const at = (weight) => mixRgb(foreground, background, weight);
+    /**
+     * Which way the weight moves contrast is the host's answer, not a constant.
+     *
+     * Toward a dark background the ink lightens as it is mixed, so weight raises
+     * contrast; toward paper it fades toward the page, so weight lowers it. Solving
+     * one direction silently returned the palette's cap on every light host, which
+     * is how `dim` came to sit at 1.75:1 while looking correct in the code.
+     */
+    const towardsBrighter = relativeLuminance(background) < relativeLuminance(foreground);
+    let low = 0;
+    let high = 1;
+    // A background that is itself close to the cards cannot reach the target at any
+    // weight; full foreground is the readable answer and the palette's floor.
+    if (worstContrast(at(0), cards) <= target)
+        return at(0);
+    for (let step = 0; step < 40; step += 1) {
+        const middle = (low + high) / 2;
+        const contrast = worstContrast(at(middle), cards);
+        if (towardsBrighter ? contrast > target : contrast >= target)
+            low = middle;
+        else
+            high = middle;
+    }
+    return at((low + high) / 2);
+}
+/**
+ * Rebuild the surface and ink swatches from what the terminal reported, so the
+ * cards sit on the user's own background instead of a guessed one. The two
+ * successful-call surfaces are separated by design: alternation only reads if
+ * the pair is perceptibly different.
+ */
+function systemPalette(terminal) {
+    const background = terminal?.background;
+    const light = terminal?.scheme === 'light';
+    const base = light ? LIGHT_PALETTE : DARK_PALETTE;
+    if (background === undefined)
+        return base;
+    const foreground = terminal?.foreground ?? (light ? { r: 0x24, g: 0x24, b: 0x24 } : { r: 0xe0, g: 0xe0, b: 0xe0 });
+    const accent = terminal?.palette?.[4] ?? SYSTEM_NOTICE_BLUE;
+    const error = terminal?.palette?.[1] ?? SYSTEM_ERROR_RED;
+    const successInk = terminal?.palette?.[2] ?? SYSTEM_SUCCESS_GREEN;
+    /**
+     * A state fill carries its own hue, the way the shipped palettes do.
+     *
+     * Mixing toward the terminal's *foreground* produced three greys: the states
+     * were separated only by lightness, which on a dark background is the one axis
+     * a reader cannot see. Mixing toward the state colour keeps the card on the
+     * user's own background and gives it the meaning at the same time — but the
+     * *amount* of that colour is fixed by the target luminance, not by a weight.
+     * A weight made the fill follow the terminal's swatch, and a bright terminal
+     * green turned every successful card into a pale one.
+     */
+    const stateCard = (tint, target) => toHex(tintAtLuminance(background, tint, target));
+    /** Relative luminance of a shipped swatch, keeping the light palette's own paper tone. */
+    const swatchLuminance = (color) => {
+        const [r, g, b] = hexToRgb(base[color]);
+        return relativeLuminance({ r, g, b });
+    };
+    // A light terminal wants the same three states as tinted paper, so its cards
+    // are held at the light palette's own lightness rather than inverted.
+    const target = (state) => light
+        ? swatchLuminance(`tool${state[0].toUpperCase()}${state.slice(1)}Bg`)
+        : SYSTEM_CARD_LUMINANCE[state];
+    // Pending is neutral, so it keeps the background's own hue and is only lifted in
+    // lightness: it must stay quieter than a settled card, and it must still read as
+    // belonging to this terminal rather than as a generic grey. Lifting the
+    // background keeps whatever faint tint it has; mixing toward the foreground
+    // instead traded that tint for the foreground's flat grey.
+    const pending = toHex(liftedToLuminance(background, target('pending')));
+    const successRgb = tintAtLuminance(background, successInk, target('success'));
+    const success = toHex(successRgb);
+    /**
+     * The alternating pair is a plain lightness step, and it has to stay one: two
+     * successive successful cards must be told apart, not two different states. It
+     * is derived from the success fill rather than from the background, because a
+     * success fill held at a fixed luminance no longer sits where the old background
+     * step assumed — measuring against the background made the pair collide and
+     * pushed the alternate surface to a brightness no card should reach.
+     */
+    const alt = toHex(tintAtLuminance(background, successInk, target('success') * SYSTEM_ALT_STEP));
+    const errorCard = stateCard(error, target('error'));
+    const cardFills = [pending, success, alt, errorCard].map(hexToRgb).map(([r, g, b]) => ({ r, g, b }));
+    /**
+     * The contrast the shipped `dim` reached against the shipped cards.
+     *
+     * That is the hierarchy to reproduce: the live cards are derived here, so a
+     * fixed weight cannot know how far it may weaken the ink before it disappears.
+     * `dim` is the only secondary ink that needs solving — it sits closest to the
+     * surface, so it is the first to become unreadable there.
+     */
+    const shippedDimContrast = () => {
+        const [r, g, b] = hexToRgb(base.dim);
+        const shippedCards = ['toolPendingBg', 'toolSuccessBg', 'toolAltBg', 'toolErrorBg']
+            .map(color => {
+            const [cr, cg, cb] = hexToRgb(base[color]);
+            return { r: cr, g: cg, b: cb };
+        });
+        return worstContrast({ r, g, b }, shippedCards);
+    };
+    return {
+        ...base,
+        text: toHex(foreground),
+        /**
+         * `muted` is not derived. Both shipped palettes set it to the same swatch as
+         * `toolOutput`, and that swatch already clears its cards on either host;
+         * deriving it separately only produced a second, near-identical grey that
+         * sometimes landed on the wrong side of the ink it was meant to match.
+         */
+        muted: base.muted,
+        dim: toHex(quietInk(foreground, background, cardFills, shippedDimContrast())),
+        userMessageBg: toHex(mixRgb(background, accent, 0.14)),
+        toolPendingBg: pending,
+        toolSuccessBg: success,
+        toolAltBg: alt,
+        toolErrorBg: errorCard,
+    };
+}
+/** 16-color SGR for one ANSI palette index, as ink or as a fill. */
+function ansiIndexSgr(index, asBackground) {
+    const base = asBackground ? 4 : 3;
+    if (index < 8)
+        return `\x1b[${base}${index}m`;
+    const bright = asBackground ? 10 : 9;
+    return `\x1b[${bright}${index - 8}m`;
 }
 /**
  * True when the environment asks for no color at all: a non-empty `NO_COLOR`
@@ -757,41 +796,99 @@ export function colorDisabledByEnv(env = process.env) {
     return (env.NO_COLOR !== undefined && env.NO_COLOR !== '') || env.FORCE_COLOR === '0';
 }
 /**
- * Detect 24-bit color. `NO_COLOR` (any non-empty value) and `FORCE_COLOR=0`
- * suppress 24-bit color and outrank every capability hint; `COLORTERM` and
- * Windows Terminal enable it, and only known 16-color hosts disqualify it.
+ * Detect the color depth. `NO_COLOR` (any non-empty value) and `FORCE_COLOR=0`
+ * outrank every capability hint and leave 16 colors; `COLORTERM` and Windows
+ * Terminal prove 24-bit color. Apple Terminal advertises `xterm-256color` but
+ * misdraws 24-bit sequences on the releases still in use, so it gets the
+ * 256-color cube. Known 16-color hosts stay at 16, and every other terminal is
+ * assumed to be a modern 24-bit one.
  */
-export function detectTrueColor(env = process.env) {
+export function detectColorDepth(env = process.env) {
     if (colorDisabledByEnv(env))
-        return false;
-    const colorterm = env.COLORTERM ?? '';
+        return 'ansi16';
+    const colorterm = (env.COLORTERM ?? '').toLowerCase();
     if (colorterm === 'truecolor' || colorterm === '24bit')
-        return true;
+        return 'truecolor';
     if (env.WT_SESSION)
-        return true;
+        return 'truecolor';
     const term = env.TERM ?? '';
     if (term === 'dumb' || term === '' || term === 'linux')
-        return false;
-    return true;
+        return 'ansi16';
+    if (env.TERM_PROGRAM === 'Apple_Terminal') {
+        const build = Number.parseInt((env.TERM_PROGRAM_VERSION ?? '').split('.')[0] ?? '', 10);
+        return Number.isInteger(build) && build >= FIRST_TRUECOLOR_APPLE_TERMINAL_BUILD ? 'truecolor' : 'ansi256';
+    }
+    return 'truecolor';
 }
+/** Terminal 2.15, macOS 26 Tahoe, is the first Apple Terminal with real 24-bit color. */
+const FIRST_TRUECOLOR_APPLE_TERMINAL_BUILD = 464;
 /**
  * Build a theme.
  * @param colors - emit SGR when true.
- * @param trueColor - 24-bit hex; ignored when colors is false.
+ * @param depth - color depth, or a boolean for 24-bit versus 16 colors; ignored when colors is false.
  * @param name - shipped palette (`dark` default).
+ * @param terminal - what the terminal reported about itself, when a probe answered.
  */
-export function createTheme(colors, trueColor = detectTrueColor(), name = 'dark') {
-    const tc = colors && trueColor;
-    const palette = PALETTES[name];
+export function createTheme(colors, depth = detectColorDepth(), name = 'dark', terminal) {
+    const resolvedDepth = depth === true ? 'truecolor' : depth === false ? 'ansi16' : depth;
+    const tc = colors && resolvedDepth === 'truecolor';
+    const palette = name === 'system' ? systemPalette(terminal) : PALETTES[name];
     const ansi = ANSI16[name];
     const ansiBg = ANSI16_BG[name];
-    const getFgAnsi = (color) => colors ? fgCode(palette[color], tc, ansi[color]) : '';
-    const getBgAnsi = (color) => colors ? bgCode(palette[color], tc, ansiBg[color]) : '';
+    // The reported sixteen colors decide the encoding only on a 16-color
+    // terminal; 256- and 24-bit terminals encode the exact swatch themselves.
+    const reported = resolvedDepth === 'ansi16' && terminal?.palette !== undefined && terminal.palette.length === 16 ? terminal.palette : undefined;
+    /**
+     * Without 24-bit color a hex swatch is quantized to the entry the terminal
+     * actually has, which is perceptual nearest rather than a fixed code shift.
+     */
+    const quantized = (swatch, asBackground) => {
+        if (reported === undefined || typeof swatch !== 'string' || swatch === '')
+            return undefined;
+        const [r, g, b] = hexToRgb(swatch);
+        const index = nearestPaletteIndex({ r, g, b }, reported);
+        return index === undefined ? undefined : ansiIndexSgr(index, asBackground);
+    };
+    const getFgAnsi = (color) => {
+        if (!colors)
+            return '';
+        return quantized(palette[color], false) ?? swatchCode(palette[color], resolvedDepth, ansi[color], 38);
+    };
+    const rawBgAnsi = (color) => {
+        if (!colors)
+            return '';
+        return quantized(palette[color], true) ?? swatchCode(palette[color], resolvedDepth, ansiBg[color], 48);
+    };
+    /**
+     * A tool card must keep telling pending from done from failed on every
+     * terminal, so the three fills are resolved together rather than one at a
+     * time.
+     *
+     * A palette with only sixteen backgrounds, or a 256-color cube with six
+     * levels per channel, has no entries that differ by the handful of units the
+     * truecolor swatches do: nearest-neighbour quantisation sent pending,
+     * success, and error to one and the same black. Every icon that says which
+     * state a card is in was therefore invisible on any terminal that was not
+     * truecolor.
+     */
+    const toolFills = colors && !tc ? resolveToolFills(name, resolvedDepth, terminal) : undefined;
+    const fillsFor = (color) => toolFills !== undefined && Object.hasOwn(toolFills, color)
+        ? toolFills[color]
+        : rawBgAnsi(color);
+    /**
+     * A 16- or 256-color terminal can still collapse the two *alternating* card
+     * surfaces onto one entry. The alternating card then gives up its fill instead
+     * of pretending to have a second one, which keeps consecutive calls readable.
+     */
+    const altBg = colors && !tc && fillsFor('toolSuccessBg') === fillsFor('toolAltBg') ? BG_RESET : undefined;
+    const getBgAnsi = (color) => color === 'toolAltBg' && altBg !== undefined ? altBg : fillsFor(color);
     const paint = (open, text, close) => colors && open !== '' ? open + text + close : text;
     return {
         name,
         colors,
         trueColor: tc,
+        depth: resolvedDepth,
+        key: [name, colors ? 1 : 0, resolvedDepth, terminalColorsKey(terminal)].join('|'),
         getFgAnsi,
         getBgAnsi,
         fg: (color, text) => paint(getFgAnsi(color), text, FG_RESET),