feat(theme): load a VS Code/Shiki theme JSON for syntax highlighting

Custom themes could only approximate syntax colors with nine semantic
tokens, so any real VS Code theme (e.g. Shades of Purple) rendered as a
rough remap of Pierre's default theme rather than the theme itself.

Add `custom_theme.syntax_theme`: a path (absolute, or relative to the
config file) to a full VS Code/Shiki theme JSON. The file is loaded and
validated at config time, registered with Pierre's highlighter, and used
as the active syntax theme so code is colored exactly as that theme would
in the editor. The nine `[custom_theme.syntax]` tokens stay as the
collision-normalization palette against diff add/remove backgrounds.

Author: eduwass

.changeset/custom-syntax-theme-json.md

@@ -0,0 +1,5 @@
+---
+"hunkdiff": minor
+---
+
+Add `custom_theme.syntax_theme` to load a full VS Code / Shiki theme JSON for source-accurate syntax highlighting. The referenced theme is registered with the highlighter and drives code coloring, so any VS Code theme renders exactly as it would in the editor instead of being approximated by the nine `[custom_theme.syntax]` tokens.

README.md

@@ -157,6 +157,16 @@ variable = "#eef4ff"
 
 All custom theme colors must use `#rrggbb` hex values. Press `t` in the app, or choose `View -> Themes…`, to open the theme selector.
 
+For source-accurate syntax highlighting, point `syntax_theme` at a VS Code / Shiki theme JSON file. Hunk loads it and hands it to its Shiki-based highlighter, so any VS Code theme colors your code exactly as that theme would:
+
+```toml
+[custom_theme]
+base = "catppuccin-mocha"
+syntax_theme = "shades-of-purple.json"   # absolute, or relative to this config file
+```
+
+When `syntax_theme` is set it drives code highlighting; the `[custom_theme.syntax]` colors then only refine tokens that would otherwise collide with diff add/remove backgrounds.
+
 ### Git integration
 
 Set Hunk as your Git pager so `git diff` and `git show` open in Hunk automatically:

src/core/config.test.ts

@@ -221,6 +221,72 @@ describe("config resolution", () => {
     ).toThrow("Expected custom_theme.accent to be a hex color like #112233.");
   });
 
+  test("loads a custom_theme.syntax_theme JSON relative to the config file", () => {
+    const home = createTempDir("hunk-config-home-");
+    const hunkDir = join(home, ".config", "hunk");
+    mkdirSync(hunkDir, { recursive: true });
+    writeFileSync(
+      join(hunkDir, "my-theme.json"),
+      JSON.stringify({ name: "My VS Code Theme", type: "dark", tokenColors: [] }),
+    );
+    writeFileSync(
+      join(hunkDir, "config.toml"),
+      [
+        'theme = "custom"',
+        "",
+        "[custom_theme]",
+        'base = "github-dark-default"',
+        'syntax_theme = "my-theme.json"',
+      ].join("\n"),
+    );
+
+    const resolved = resolveConfiguredCliInput(createPatchPagerInput(), {
+      cwd: createTempDir("hunk-config-cwd-"),
+      env: { HOME: home },
+    });
+
+    expect(resolved.customTheme?.syntaxThemePath).toBe("my-theme.json");
+    expect(resolved.customTheme?.syntaxThemeData).toEqual({
+      name: "My VS Code Theme",
+      type: "dark",
+      tokenColors: [],
+    });
+  });
+
+  test("rejects a custom_theme.syntax_theme that does not exist", () => {
+    const home = createTempDir("hunk-config-home-");
+    mkdirSync(join(home, ".config", "hunk"), { recursive: true });
+    writeFileSync(
+      join(home, ".config", "hunk", "config.toml"),
+      ["[custom_theme]", 'syntax_theme = "missing.json"'].join("\n"),
+    );
+
+    expect(() =>
+      resolveConfiguredCliInput(createPatchPagerInput(), {
+        cwd: createTempDir("hunk-config-cwd-"),
+        env: { HOME: home },
+      }),
+    ).toThrow("Expected custom_theme.syntax_theme to point at a file.");
+  });
+
+  test("rejects a custom_theme.syntax_theme JSON without a name", () => {
+    const home = createTempDir("hunk-config-home-");
+    const hunkDir = join(home, ".config", "hunk");
+    mkdirSync(hunkDir, { recursive: true });
+    writeFileSync(join(hunkDir, "nameless.json"), JSON.stringify({ type: "dark" }));
+    writeFileSync(
+      join(hunkDir, "config.toml"),
+      ["[custom_theme]", 'syntax_theme = "nameless.json"'].join("\n"),
+    );
+
+    expect(() =>
+      resolveConfiguredCliInput(createPatchPagerInput(), {
+        cwd: createTempDir("hunk-config-cwd-"),
+        env: { HOME: home },
+      }),
+    ).toThrow('to be a Shiki theme with a non-empty "name".');
+  });
+
   test("rejects theme = custom when no [custom_theme] table is configured", () => {
     const home = createTempDir("hunk-config-home-");
     mkdirSync(join(home, ".config", "hunk"), { recursive: true });

src/core/config.ts

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { BUNDLED_SHIKI_THEME_IDS } from "../ui/lib/shikiThemes";
 import { normalizeBuiltInThemeId } from "../ui/themes";
 import { resolveGlobalConfigPath } from "./paths";
@@ -8,6 +8,7 @@ import type {
   CliInput,
   CommonOptions,
   CustomSyntaxColorsConfig,
+  CustomSyntaxThemeData,
   CustomThemeConfig,
   LayoutMode,
   PersistedViewPreferences,
@@ -161,8 +162,52 @@ function readCustomSyntaxColors(
   return Object.keys(syntax).length > 0 ? syntax : undefined;
 }
 
+/**
+ * Load and validate a full Shiki theme JSON referenced by `custom_theme.syntax_theme`.
+ * The path may be absolute or relative to the config file that declared it. We read it
+ * eagerly so a bad path fails fast at config time rather than silently dropping
+ * highlighting later.
+ */
+function readCustomSyntaxTheme(
+  value: unknown,
+  configPath: string | undefined,
+): CustomSyntaxThemeData | undefined {
+  const rawPath = normalizeString(value);
+  if (rawPath === undefined) {
+    return undefined;
+  }
+
+  const basis = configPath ? dirname(configPath) : process.cwd();
+  const themePath = isAbsolute(rawPath) ? rawPath : resolve(basis, rawPath);
+
+  if (!fs.existsSync(themePath)) {
+    throw new Error(`Expected custom_theme.syntax_theme to point at a file. Missing: ${themePath}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(themePath, "utf8"));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Expected custom_theme.syntax_theme (${themePath}) to be valid JSON: ${reason}`,
+    );
+  }
+
+  if (!isRecord(parsed) || typeof parsed.name !== "string" || parsed.name.length === 0) {
+    throw new Error(
+      `Expected custom_theme.syntax_theme (${themePath}) to be a Shiki theme with a non-empty "name".`,
+    );
+  }
+
+  return parsed as CustomSyntaxThemeData;
+}
+
 /** Read the optional config-defined custom theme palette from one TOML object level. */
-function readCustomTheme(source: Record<string, unknown>): CustomThemeConfig | undefined {
+function readCustomTheme(
+  source: Record<string, unknown>,
+  configPath?: string,
+): CustomThemeConfig | undefined {
   const customThemeSource = source.custom_theme;
   if (!isRecord(customThemeSource)) {
     return undefined;
@@ -181,6 +226,12 @@ function readCustomTheme(source: Record<string, unknown>): CustomThemeConfig | u
     customTheme.label = label;
   }
 
+  const syntaxThemePath = normalizeString(customThemeSource.syntax_theme);
+  if (syntaxThemePath !== undefined) {
+    customTheme.syntaxThemePath = syntaxThemePath;
+    customTheme.syntaxThemeData = readCustomSyntaxTheme(customThemeSource.syntax_theme, configPath);
+  }
+
   for (const key of CUSTOM_THEME_COLOR_KEYS) {
     const value = normalizeThemeColor(customThemeSource[key], `custom_theme.${key}`);
     if (value !== undefined) {
@@ -215,6 +266,8 @@ function mergeCustomTheme(
     ...overrides,
     base: overrides.base ?? base.base ?? "github-dark-default",
     label: overrides.label ?? base.label,
+    syntaxThemePath: overrides.syntaxThemePath ?? base.syntaxThemePath,
+    syntaxThemeData: overrides.syntaxThemeData ?? base.syntaxThemeData,
     syntax:
       base.syntax || overrides.syntax
         ? {
@@ -333,13 +386,19 @@ export function resolveConfiguredCliInput(
   if (userConfigPath) {
     const userConfig = readTomlRecord(userConfigPath);
     resolvedOptions = mergeOptions(resolvedOptions, resolveConfigLayer(userConfig, input));
-    resolvedCustomTheme = mergeCustomTheme(resolvedCustomTheme, readCustomTheme(userConfig));
+    resolvedCustomTheme = mergeCustomTheme(
+      resolvedCustomTheme,
+      readCustomTheme(userConfig, userConfigPath),
+    );
   }
 
   if (repoConfigPath) {
     const repoConfig = readTomlRecord(repoConfigPath);
     resolvedOptions = mergeOptions(resolvedOptions, resolveConfigLayer(repoConfig, input));
-    resolvedCustomTheme = mergeCustomTheme(resolvedCustomTheme, readCustomTheme(repoConfig));
+    resolvedCustomTheme = mergeCustomTheme(
+      resolvedCustomTheme,
+      readCustomTheme(repoConfig, repoConfigPath),
+    );
   }
 
   resolvedOptions = mergeOptions(resolvedOptions, input.options);

src/core/types.ts

@@ -110,9 +110,23 @@ export interface CustomSyntaxColorsConfig {
   punctuation?: string;
 }
 
+/**
+ * A full VS Code / Shiki theme JSON loaded from disk and registered with the
+ * highlighter for source-accurate syntax coloring. Only `name` is required; the
+ * remaining TextMate fields are passed through to Shiki untouched.
+ */
+export interface CustomSyntaxThemeData {
+  name: string;
+  [key: string]: unknown;
+}
+
 export interface CustomThemeConfig {
   base?: string;
   label?: string;
+  /** Path (from config) to a Shiki theme JSON used for syntax highlighting. */
+  syntaxThemePath?: string;
+  /** The loaded + validated Shiki theme JSON referenced by `syntaxThemePath`. */
+  syntaxThemeData?: CustomSyntaxThemeData;
   background?: string;
   panel?: string;
   panelAlt?: string;

src/ui/diff/pierre.ts

@@ -2,6 +2,7 @@ import {
   cleanLastNewline,
   getHighlighterOptions,
   getSharedHighlighter,
+  registerCustomTheme,
   renderDiffWithHighlighter,
   renderFileWithHighlighter,
   type FileContents,
@@ -571,8 +572,33 @@ export function trailingCollapsedLines(metadata: FileDiffMetadata) {
   return Math.max(additionRemaining, 0);
 }
 
+// Custom Shiki themes are registered once with Pierre's global theme registry. Track which
+// names we've registered so repeated highlight passes don't re-register (Pierre warns on dupes).
+const registeredCustomSyntaxThemes = new Set<string>();
+
+/** Register a config-provided Shiki theme JSON with Pierre before it's referenced by name. */
+function ensureCustomSyntaxThemeRegistered(theme: HighlightThemeInput) {
+  if (typeof theme === "string") {
+    return;
+  }
+
+  const data = theme.syntaxThemeData;
+  if (!data || registeredCustomSyntaxThemes.has(data.name)) {
+    return;
+  }
+
+  registeredCustomSyntaxThemes.add(data.name);
+  // Pierre resolves themes by name against its custom registry first, then Shiki's bundled
+  // themes. The registry stores async loaders, so hand it one resolving to the loaded JSON.
+  type CustomThemeLoader = Parameters<typeof registerCustomTheme>[1];
+  const loader: CustomThemeLoader = () =>
+    Promise.resolve(data as unknown as Awaited<ReturnType<CustomThemeLoader>>);
+  registerCustomTheme(data.name, loader);
+}
+
 /** Prepare syntax highlighting for one language/theme pair using Pierre's shared highlighter. */
 async function prepareHighlighter(language: string | undefined, theme: HighlightThemeInput) {
+  ensureCustomSyntaxThemeRegistered(theme);
   const resolvedLanguage = language ?? "text";
   const syntaxTheme = highlighterThemeName(theme);
   const cacheKey = `${syntaxTheme}:${resolvedLanguage}`;

src/ui/themes.test.ts

@@ -247,6 +247,22 @@ describe("themes", () => {
     expect(custom.syntaxColors.keyword).toBe("#ff00ff");
   });
 
+  test("a full syntax theme JSON drives highlighting by name", () => {
+    const syntaxThemeData = { name: "Shades of Purple", type: "dark" as const, tokenColors: [] };
+    const custom = resolveTheme("custom", null, {
+      base: "catppuccin-mocha",
+      label: "My Theme",
+      syntaxThemeData,
+      // A 9-token block is present too, but the full theme JSON should take precedence.
+      syntax: { keyword: "#ff00ff" },
+    });
+
+    expect(custom.syntaxTheme).toBe("Shades of Purple");
+    expect(custom.syntaxThemeData).toEqual(syntaxThemeData);
+    // The 9-token palette is still kept for collision normalization against diff backgrounds.
+    expect(custom.syntaxColors.keyword).toBe("#ff00ff");
+  });
+
   test("withTransparentBackground only swaps painted background fields", () => {
     const theme = resolveTheme("github-dark-default", null);
     const transparent = withTransparentBackground(theme);

src/ui/themes.ts

@@ -290,9 +290,15 @@ function buildCustomTheme(customTheme: CustomThemeConfig) {
     noteBackground: customTheme.noteBackground ?? baseTheme.noteBackground,
     noteTitleBackground: customTheme.noteTitleBackground ?? baseTheme.noteTitleBackground,
     noteTitleText: customTheme.noteTitleText ?? baseTheme.noteTitleText,
-    // Explicit syntax color overrides should use Hunk's semantic remap path rather than the
-    // inherited Shiki theme, otherwise the overrides would never affect highlighted code.
-    syntaxTheme: customTheme.syntax ? undefined : baseTheme.syntaxTheme,
+    // A full Shiki theme JSON wins: highlight from its own tokens for source-accurate color.
+    // Otherwise explicit 9-token overrides use Hunk's semantic remap path (so they actually
+    // affect highlighted code), and a bare custom palette inherits the base theme's syntax.
+    syntaxTheme: customTheme.syntaxThemeData
+      ? customTheme.syntaxThemeData.name
+      : customTheme.syntax
+        ? undefined
+        : baseTheme.syntaxTheme,
+    syntaxThemeData: customTheme.syntaxThemeData,
   };
 
   return withLazySyntaxStyle(themeBase, {

src/ui/themes/types.ts

@@ -1,4 +1,5 @@
 import type { SyntaxStyle } from "@opentui/core";
+import type { CustomSyntaxThemeData } from "../../core/types";
 
 export interface AppTheme {
   id: string;
@@ -39,6 +40,8 @@ export interface AppTheme {
   noteTitleText: string;
   /** Optional Shiki/Pierre theme name for source-accurate code highlighting. */
   syntaxTheme?: string;
+  /** Optional full Shiki theme JSON registered with the highlighter under `syntaxTheme`. */
+  syntaxThemeData?: CustomSyntaxThemeData;
   syntaxColors: SyntaxColors;
   syntaxStyle: SyntaxStyle;
 }