@celestia-island/hikari 0.55.158 → 0.55.160

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.158",
+  "version": "0.55.160",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkInfiniteTail.tsx

@@ -25,11 +25,14 @@ import "./HkInfiniteTail.scss";
  * - `"idle"` — more exists, nothing in flight. With `auto` (default)
  *   the invisible sentinel watches the viewport and emits `loadMore`
  *   as it approaches; with `auto={false}` the explicit load-more
- *   button (HkLoadMore) renders instead. NOTE: with `auto`, a tail
- *   page failure retries in place every time the sentinel re-enters
- *   view (the machine's error guard paces it to one attempt per
- *   emission, no backoff) — hosts that want backoff map the error
- *   state away from `"idle"` themselves.
+ *   button (HkLoadMore) renders instead. NOTE: a failed page
+ *   terminalizes the machine's walk — the tail keeps emitting
+ *   `loadMore` as the sentinel re-enters view, but each emission is a
+ *   no-op until the host calls `reload()` (the retry verb; the
+ *   delivered rows stay on screen under the host's stale banner).
+ *   Auto-retrying from the tail is deliberately not supported: the
+ *   sentinel would re-fire on a fixed geometry with no backoff, one
+ *   RPC per round trip, which locks a shared rate budget.
  *
  * The sentinel observes the BROWSER viewport (IntersectionObserver,
  * `rootMargin` lookahead), so it works inside any nested scroll

package/src/composables/languageForPath.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+
+import { languageForPath } from "./useHighlight";
+import { LANGUAGE_LOADERS } from "./highlightLanguages";
+
+/**
+ * `languageForPath` is the ONE mapping from a file path to a highlight.js
+ * language — shared so a diff pane, a file browser and a markdown fence
+ * all derive the same language from the same path. Its two contracts:
+ * every non-empty answer must be a language the lazy loader can actually
+ * load (otherwise the promise is a lie), and unknown paths must answer ""
+ * (callers treat "" as plaintext/auto-detect, never as an error).
+ */
+describe("languageForPath", () => {
+  it("maps the common extensions onto canonical ids", () => {
+    expect(languageForPath("crates/scheduler/src/main.rs")).toBe("rust");
+    expect(languageForPath("src/index.ts")).toBe("typescript");
+    expect(languageForPath("App.tsx")).toBe("typescript");
+    expect(languageForPath("script.js")).toBe("javascript");
+    expect(languageForPath("world.toml")).toBe("toml");
+    expect(languageForPath("Cargo.toml")).toBe("toml");
+    expect(languageForPath("config/world.yml")).toBe("yaml");
+    expect(languageForPath("run.sh")).toBe("bash");
+    expect(languageForPath("notes.md")).toBe("markdown");
+    expect(languageForPath("query.sql")).toBe("sql");
+    expect(languageForPath("theme.scss")).toBe("scss");
+    expect(languageForPath("index.html")).toBe("xml");
+  });
+
+  it("is case-insensitive on name and extension", () => {
+    expect(languageForPath("src/Main.RS")).toBe("rust");
+    expect(languageForPath("Dockerfile")).toBe("dockerfile");
+    expect(languageForPath("Makefile")).toBe("makefile");
+    expect(languageForPath("CMakeLists.txt")).toBe("cmake");
+    expect(languageForPath("Jenkinsfile")).toBe("groovy");
+  });
+
+  it("keeps dotted stems like Dockerfile.dev on their dialect", () => {
+    expect(languageForPath("deploy/Dockerfile.dev")).toBe("dockerfile");
+    expect(languageForPath("dockerfile.prod")).toBe("dockerfile");
+    expect(languageForPath("Makefile.am")).toBe("makefile");
+  });
+
+  it("answers \"\" for unknown or extensionless paths, not a guess", () => {
+    expect(languageForPath("bin/run")).toBe("");
+    expect(languageForPath("README")).toBe("");
+    expect(languageForPath("data.xyzzy")).toBe("");
+    expect(languageForPath("")).toBe("");
+  });
+
+  it("every mapped id is a language the loader actually has", () => {
+    const loaders = new Set(Object.keys(LANGUAGE_LOADERS));
+    expect(loaders.size).toBeGreaterThan(50); // positive control
+    const probes = [
+      "a.rs", "a.ts", "a.tsx", "a.js", "a.json", "a.py", "a.rb", "a.go",
+      "a.java", "a.kt", "a.scala", "a.groovy", "a.c", "a.h", "a.cpp",
+      "a.hpp", "a.cs", "a.fs", "a.php", "a.swift", "a.m", "a.mm",
+      "a.dart", "a.ex", "a.erl", "a.hs", "a.elm", "a.lua", "a.pl",
+      "a.r", "a.jl", "a.nim", "a.cr", "a.ml", "a.vb", "a.pas", "a.bas",
+      "a.f90", "a.coffee", "a.ls", "a.clj", "a.scm", "a.el", "a.xml",
+      "a.html", "a.vue", "a.hbs", "a.twig", "a.haml", "a.erb", "a.dust",
+      "a.css", "a.scss", "a.less", "a.yml", "a.yaml", "a.toml", "a.ini",
+      "a.cfg", "a.properties", "a.env", "a.md", "a.graphql", "a.gql",
+      "a.http", "a.sh", "a.zsh", "a.ps1", "a.bat", "a.cmd", "a.mk",
+      "a.cmake", "a.awk", "a.tcl", "a.vim", "a.sql", "a.psql", "a.proto",
+      "a.thrift", "a.glsl", "a.vert", "a.frag", "a.wasm", "a.asm",
+      "a.v", "a.sv", "a.vhd", "a.vhdl", "a.tex", "a.sty", "a.diff",
+      "a.patch", "a.txt", "a.log", "Dockerfile", "Makefile", "Jenkinsfile",
+      "CMakeLists.txt", "Cargo.lock", ".gitignore", ".env", ".bashrc",
+    ];
+    const mapped = probes
+      .map((p) => languageForPath(p))
+      .filter((id): id is string => id !== "");
+    // Each probe resolves to SOMETHING (the table is broad)…
+    expect(mapped.length).toBe(probes.length);
+    // …and every answer is loadable — no lying promises.
+    for (const id of mapped) {
+      expect(loaders, `languageForPath answered "${id}", which no loader provides`).toContain(id);
+    }
+  });
+
+  it("does not fall off the path on dots in directories", () => {
+    expect(languageForPath("my.dir/stuff/main.rs")).toBe("rust");
+    expect(languageForPath("v1.2/config.yaml")).toBe("yaml");
+  });
+});

package/src/composables/useHighlight.ts

@@ -84,6 +84,125 @@ function ensureAutoLangs(): void {
   for (const l of AUTO_LANGS) loadLanguage(l);
 }
 
+/** Whole filenames (lowercased) that carry no useful extension, or whose
+ *  dialect is decided by the name: `Dockerfile.dev`, `CMakeLists.txt`. */
+const PATH_FILENAME_LANG: Record<string, string> = {
+  dockerfile: "dockerfile",
+  makefile: "makefile",
+  gnumakefile: "makefile",
+  "cmakelists.txt": "cmake",
+  jenkinsfile: "groovy",
+  nginx: "nginx",
+  "cargo.lock": "toml",
+  ".env": "ini",
+  ".gitignore": "ini",
+  ".gitattributes": "ini",
+  ".gitmodules": "ini",
+  ".editorconfig": "ini",
+  ".bashrc": "bash",
+  ".zshrc": "bash",
+  ".profile": "bash",
+};
+
+/** Extension (lowercased) → canonical highlight.js language id. Only ids
+ *  that exist in LANGUAGE_LOADERS: anything else would render plaintext
+ *  anyway, just with a misleading promise attached. */
+const EXT_TABLE: Record<string, string> = {
+  rs: "rust",
+  ts: "typescript", tsx: "typescript", mts: "typescript", cts: "typescript",
+  js: "javascript", jsx: "javascript", mjs: "javascript", cjs: "javascript",
+  json: "json", jsonc: "json",
+  py: "python", pyi: "python", pyw: "python",
+  rb: "ruby",
+  go: "go",
+  java: "java",
+  kt: "kotlin", kts: "kotlin",
+  scala: "scala", sc: "scala",
+  groovy: "groovy", gradle: "groovy",
+  c: "c", h: "c",
+  cpp: "cpp", cc: "cpp", cxx: "cpp", hpp: "cpp", hh: "cpp", hxx: "cpp",
+  cs: "csharp",
+  fs: "fsharp", fsx: "fsharp",
+  php: "php",
+  swift: "swift",
+  m: "objectivec", mm: "objectivec",
+  dart: "dart",
+  ex: "elixir", exs: "elixir",
+  erl: "erlang", hrl: "erlang",
+  hs: "haskell", lhs: "haskell",
+  elm: "elm",
+  lua: "lua",
+  pl: "perl", pm: "perl",
+  r: "r",
+  jl: "julia",
+  nim: "nim",
+  cr: "crystal",
+  ml: "ocaml", mli: "ocaml", mll: "ocaml", mly: "ocaml",
+  vb: "vbnet",
+  pas: "delphi", dpr: "delphi",
+  bas: "basic",
+  f: "fortran", f90: "fortran", f95: "fortran", f03: "fortran", for: "fortran",
+  coffee: "coffeescript",
+  ls: "livescript",
+  clj: "clojure", cljs: "clojure", cljc: "clojure", edn: "clojure",
+  scm: "scheme", ss: "scheme", el: "lisp", lisp: "lisp",
+  xml: "xml", html: "xml", htm: "xml", svg: "xml", vue: "xml", xhtml: "xml",
+  cshtml: "xml", jsp: "xml", erb: "erb", ejs: "xml",
+  hbs: "handlebars", handlebars: "handlebars",
+  twig: "twig",
+  haml: "haml",
+  dust: "dust",
+  css: "css", scss: "scss", less: "less",
+  yml: "yaml", yaml: "yaml",
+  toml: "toml",
+  ini: "ini", cfg: "ini", conf: "ini", properties: "properties", env: "ini",
+  md: "markdown", markdown: "markdown",
+  graphql: "graphql", gql: "graphql",
+  http: "http",
+  sh: "bash", bash: "bash", zsh: "bash", shell: "bash", fish: "bash",
+  ps1: "powershell", psm1: "powershell",
+  bat: "dos", cmd: "dos",
+  mk: "makefile",
+  cmake: "cmake",
+  dockerfile: "dockerfile",
+  nginx: "nginx",
+  awk: "awk",
+  tcl: "tcl",
+  vim: "vim",
+  sql: "sql", psql: "pgsql",
+  proto: "protobuf",
+  thrift: "thrift",
+  glsl: "glsl", vert: "glsl", frag: "glsl", geom: "glsl",
+  wasm: "wasm",
+  asm: "x86asm",
+  v: "verilog", sv: "verilog",
+  vhd: "vhdl", vhdl: "vhdl",
+  tex: "latex", sty: "latex",
+  diff: "diff", patch: "diff",
+  txt: "plaintext", text: "plaintext", log: "plaintext",
+};
+
+/**
+ * A file path → the canonical highlight.js language id for it, or "" when
+ * nothing sensible is known (callers pass "" as "no language" and the
+ * block renders plaintext or auto-detects). One mapping for every code
+ * surface — diff panes, file browsers, markdown fences — so the same
+ * path always highlights the same way; aliases are resolved by
+ * `normalize()` at highlight time, so the table lists canonical ids.
+ */
+export function languageForPath(path: string): string {
+  const name = path.split("/").pop()?.trim().toLowerCase() ?? "";
+  if (!name) return "";
+  // Extensionless build scripts: `Dockerfile`, `Jenkinsfile`, `Makefile`.
+  const bare = PATH_FILENAME_LANG[name];
+  if (bare) return bare;
+  // `Dockerfile.dev` / `dockerfile.prod` — the dialect IS the stem.
+  if (name.startsWith("dockerfile")) return "dockerfile";
+  if (name.startsWith("makefile")) return "makefile";
+  const ext = name.includes(".") ? name.split(".").pop()! : "";
+  return EXT_TABLE[ext] ?? "";
+}
+
 /**
  * Highlight `code` for the given language (or auto-detect when omitted).
  * Returns highlight.js HTML when the grammar is ready, otherwise an

package/src/composables/useInfinitePages.test.ts

@@ -114,7 +114,7 @@ describe("useInfinitePages", () => {
     expect(handle.exhausted.value).toBe(true);
   });
 
-  it("a failed later page keeps the delivered rows and retries in place", async () => {
+  it("a failed later page keeps the delivered rows and terminalizes the walk", async () => {
     const fetcher = vi
       .fn(async (): Promise<HkPageResultLike<Row>> => page([], 0, false))
       .mockImplementationOnce(async () => page([{ id: "a" }], 3, true))
@@ -127,10 +127,36 @@ describe("useInfinitePages", () => {
     await handle.loadMore();
     expect(handle.error.value).toBe("boom");
     expect(handle.items.value.map((r) => r.id)).toEqual(["a"]);
-    // The tail failure is retriable without a full reload.
+    // A tail failure does NOT auto-retry: the sentinel's idle re-check
+    // would re-fire loadMore on a fixed geometry with no backoff — one
+    // RPC per round trip forever, locking any shared rate budget. The
+    // failure is terminal until `reload`.
     await handle.loadMore();
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(handle.items.value.map((r) => r.id)).toEqual(["a"]);
+    // `reload` is the retry verb: it clears the failure and refetches
+    // from page one.
+    await handle.reload();
     expect(handle.error.value).toBeNull();
-    expect(handle.items.value.map((r) => r.id)).toEqual(["a", "b", "c"]);
+    expect(handle.items.value.map((r) => r.id)).toEqual(["b", "c"]);
+  });
+
+  it("a tail failure cannot storm: repeated loadMore stays a no-op", async () => {
+    const fetcher = vi
+      .fn(async (): Promise<HkPageResultLike<Row>> => page([], 0, false))
+      .mockImplementationOnce(async () => page([{ id: "a" }], 5, true))
+      .mockImplementation(async () => {
+        throw new Error("tail down");
+      });
+    const { handle } = withHandle(() => useInfinitePages<Row>({ fetcher, pageSize: 1 }));
+    await vi.waitFor(() => expect(handle.loading.value).toBe(false));
+    await handle.loadMore();
+    expect(handle.error.value).toBe("tail down");
+    // Ten idle-entry re-checks (the tail sentinel's emission pattern)
+    // spend ZERO further RPCs.
+    for (let i = 0; i < 10; i++) await handle.loadMore();
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(handle.items.value.map((r) => r.id)).toEqual(["a"]);
   });
 
   it("a param change triggers a debounced reload from page one", async () => {

package/src/composables/useInfinitePages.ts

@@ -83,9 +83,9 @@ export interface InfinitePagesHandle<T> {
   error: Ref<string | null>;
   /** One-based index of the next page to fetch. */
   nextPage: Ref<number>;
-  /** Fetch the next page (guarded: no-op while busy or exhausted).
-   * A TAIL-page failure stays retriable in place — the next `loadMore`
-   * refetches the same page; only a page-one failure needs `reload`. */
+  /** Fetch the next page (guarded: no-op while busy, exhausted, or
+   * after ANY failure — `reload` is the retry verb for both the
+   * first-page and the tail-page error dialects). */
   loadMore: () => Promise<void>;
   /** Reset to page one and fetch (also the error-clearing retry). */
   reload: () => Promise<void>;
@@ -101,7 +101,11 @@ export interface InfinitePagesHandle<T> {
  *
  * Error dialect: a failed page keeps everything already delivered (the
  * consumer renders it as a stale banner — one failed fetch must never
- * hide rows the user was reading); `reload` is the retry verb.
+ * hide rows the user was reading) and terminalizes the walk; `reload`
+ * is the retry verb for every failure. Auto-retrying a tail failure is
+ * deliberately NOT done: the tail's sentinel would re-fire on a fixed
+ * geometry with no backoff, turning one flaky page into an RPC storm
+ * that locks a shared rate budget.
  */
 export function useInfinitePages<T, P extends Record<string, unknown> = Record<string, unknown>>(
   options: InfinitePagesOptions<T, P>,
@@ -123,9 +127,6 @@ export function useInfinitePages<T, P extends Record<string, unknown> = Record<s
   let seq = 0;
   let reloadTimer: ReturnType<typeof setTimeout> | null = null;
   let disposed = false;
-  /** Which phase the current `error` came from — a tail-page failure
-   * retried by `loadMore` in place, a first-page failure by `reload`. */
-  let errorPhase: "load" | "more" = "load";
 
   function normalize(result: HkPageResultLike<T>): HkPageResult<T> {
     const loose = result as {
@@ -196,14 +197,20 @@ export function useInfinitePages<T, P extends Record<string, unknown> = Record<s
   }
 
   async function loadMore(): Promise<void> {
-    // A failure from a LATER page is retriable in place (the delivered
-    // rows stay, the cursor stays); a failure from page one needs a
-    // full reload (the retry verb for the hard-error state).
+    // ANY failure terminalizes the walk until `reload()` — including a
+    // tail-page failure. The in-place retry this used to allow read
+    // fine in isolation but stormed in the field: a failed tail leaves
+    // the state machine "idle", the tail's sentinel stays in view, and
+    // its idle-entry re-check fires loadMore again with no geometry
+    // change — one RPC per round trip, no backoff, forever. On a shared
+    // per-user rate budget that loop locks the bucket and denies every
+    // OTHER paged page, so the retry verb is `reload()` (the delivered
+    // rows stay on screen under the stale banner; the header refresh is
+    // the user's affordance).
     if (loading.value || loadingMore.value || exhausted.value) return;
-    if (error.value && errorPhase !== "more") return;
+    if (error.value) return;
     if (nextPage.value > 1 && items.value.length === 0) return;
     loadingMore.value = true;
-    errorPhase = "more";
     const mine = ++seq;
     try {
       await fetchPage(nextPage.value, mine);
@@ -225,7 +232,6 @@ export function useInfinitePages<T, P extends Record<string, unknown> = Record<s
       reloadTimer = null;
     }
     loading.value = true;
-    errorPhase = "load";
     error.value = null;
     if (!options.keepDuringReload) {
       // Invalidate the cursor BEFORE the fetch so a straggler from the

package/src/index.ts

@@ -460,7 +460,7 @@ export type { OriginProbe } from "./utils/connectivity";
 export { probeHealthEndpoint } from "./utils/healthProbe";
 export type { HealthProbeBody, HealthProbeResult } from "./utils/healthProbe";
 
-export { highlight, useHighlight } from "./composables/useHighlight";
+export { highlight, languageForPath, useHighlight } from "./composables/useHighlight";
 export { LANGUAGE_LOADERS } from "./composables/highlightLanguages";
 export {
   iconByName,

package/src/styles/highlightPalette.contract.test.ts

@@ -0,0 +1,91 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+/**
+ * The syntax-palette contract (theme/highlight.scss).
+ *
+ * `useHighlight()` emits `.hljs-*` spans; this sheet is the ONLY thing
+ * that colours them, so the pairs documented in channels.scss must stay
+ * mapped to their `--code-*` tokens — if a restyle ever swaps a var() for
+ * a bare hex, themed hosts stop flipping light/dark for that class and
+ * the sheet silently forks the palette the host owns.
+ *
+ * Assertions run on the BODY (comment lines stripped): the header and
+ * inline comments deliberately NAME the classes they explain, so matching
+ * against the raw sheet would hit prose instead of rules.
+ */
+const body = readFileSync(
+  resolve(dirname(fileURLToPath(import.meta.url)), "theme/highlight.scss"),
+  "utf-8",
+)
+  .split("\n")
+  .filter((line) => !line.trim().startsWith("//"))
+  .join("\n");
+
+/** Pull one declaration block by a selector fragment (regex-escaped). */
+function blockFor(selector: string): string {
+  const esc = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(
+    String.raw`\.hljs-${esc}\b[\s\S]*?\{([^}]*)\}`,
+  );
+  const m = re.exec(body);
+  expect(m, `positive control: the .hljs-${selector} rule exists`).not.toBeNull();
+  return m![1];
+}
+
+describe("highlight palette (theme/highlight.scss)", () => {
+  it("rides the --code-* family for every colour, One Dark as fallback", () => {
+    const colorRules = body.match(/color:\s*[^;]+;/g) ?? [];
+    expect(colorRules.length).toBeGreaterThan(5); // positive control
+    for (const rule of colorRules) {
+      expect(
+        rule,
+        `every colour must ride the token family: "${rule}"`,
+      ).toMatch(/color:\s*var\(--code-[a-z]+,\s*#[0-9a-fA-F]{6}\);/);
+    }
+  });
+
+  it("keeps the pairs channels.scss documents canonical", () => {
+    expect(blockFor("keyword")).toContain("var(--code-keyword, #c678dd)");
+    expect(blockFor("selector-tag")).toContain("var(--code-keyword, #c678dd)");
+    expect(blockFor("built_in")).toContain("var(--code-builtin, #c678dd)");
+    expect(blockFor("string")).toContain("var(--code-string, #98c379)");
+    expect(blockFor("number")).toContain("var(--code-number, #d19a66)");
+    expect(blockFor("literal")).toContain("var(--code-number, #d19a66)");
+    expect(blockFor("attr")).toContain("var(--code-number, #d19a66)");
+    expect(blockFor("title.function_")).toContain("var(--code-function, #61afef)");
+    expect(blockFor("type")).toContain("var(--code-type, #e5c07b)");
+    expect(blockFor("title.class_")).toContain("var(--code-type, #e5c07b)");
+    expect(blockFor("variable")).toContain("var(--code-variable, #e06c75)");
+    expect(blockFor("template-variable")).toContain("var(--code-variable, #e06c75)");
+  });
+
+  it("renders comments grey AND italic, as documented", () => {
+    const b = blockFor("comment");
+    expect(b).toContain("var(--code-comment, #5c6370)");
+    expect(b).toMatch(/font-style:\s*italic/);
+  });
+
+  it("does not paint backgrounds or the .hljs base — surfaces own those", () => {
+    expect(body).not.toMatch(/background[^;{]*:/);
+    expect(body).not.toMatch(/^\.hljs\s*\{/m);
+    // The diff classes belong to the diff surfaces, not the palette.
+    expect(body).not.toContain(".hljs-addition");
+    expect(body).not.toContain(".hljs-deletion");
+  });
+
+  it("is actually composed into the styles entry — a sheet nobody @uses is dead", () => {
+    const entry = readFileSync(
+      resolve(dirname(fileURLToPath(import.meta.url)), "index.scss"),
+      "utf-8",
+    );
+    expect(
+      entry.match(/@use\s+"\.\/theme\/[^"]+\.scss";/g) ?? [],
+      "positive control: the entry composes theme sheets",
+    ).toContain("@use \"./theme/channels.scss\";");
+    expect(entry).toContain('@use "./theme/highlight.scss";');
+  });
+});

package/src/styles/index.scss

@@ -12,7 +12,10 @@
 //   3. theme/scrollbar.scss — the shared overlay-scrollbar chrome
 //      (.hk-scrollbar-track/thumb) that attachOverlayScrollbars() attaches
 //      to every scroll region (vendored from packages/theme/styles).
-//   4. admin-tokens.scss — the plana-ui shared surface: layout tokens,
+//   4. theme/highlight.scss — the syntax palette: colours the .hljs-*
+//      spans useHighlight() emits, riding the --code-* family the host
+//      theme owns (vendored from packages/theme/styles).
+//   5. admin-tokens.scss — the plana-ui shared surface: layout tokens,
 //      brand-color aliases and the shared admin component classes.
 //
 // initTheme() (runtime) writes only deltas against this base into a
@@ -28,4 +31,5 @@
 @use "./theme/channels.scss";
 @use "./theme/scale.scss";
 @use "./theme/scrollbar.scss";
+@use "./theme/highlight.scss";
 @use "./admin-tokens.scss";

package/src/styles/theme/highlight.scss

@@ -0,0 +1,117 @@
+// Vendored from packages/theme/styles/_highlight.scss so npm registry
+// installs can resolve it — the exports map only exposes ./styles/*.
+// This sheet is what COLOURS the `.hljs-*` spans that useHighlight() and
+// any other highlight.js driver emit; without it the grammars load and
+// the code still renders monochrome (infra without a palette).
+// Edit the upstream file, then re-copy; do not hand-edit here.
+
+// _highlight.scss — the syntax palette for highlight.js output.
+//
+// `useHighlight()` (and anything else driving highlight.js) emits
+// `.hljs-*` spans; this sheet is what actually COLOURS them. Without it
+// the grammars load, the spans land in the DOM, and the code stays
+// monochrome — infra without a palette.
+//
+// Every colour rides the `--code-*` family documented in channels.scss
+// (the family the host theme owns; extend it only by adding a token with
+// a fallback equal to the current visual). The fallbacks here are the
+// canonical One Dark values, so a standalone/themeless consumer renders
+// like One Dark and a themed host (which defines `--code-*` in both
+// modes) flips light/dark automatically — no `.hljs-*` rule anywhere in
+// this sheet hardcodes a palette colour outside a var() fallback.
+//
+// The explicit pairs from the channels.scss doc block are canonical:
+//   keyword  ← .hljs-keyword / .hljs-selector-tag
+//   builtin  ← .hljs-built_in
+//   string   ← .hljs-string
+//   number   ← .hljs-number / .hljs-literal / .hljs-attr
+//   comment  ← .hljs-comment / .hljs-doctag          (grey, italic)
+//   function ← .hljs-title.function_
+//   type     ← .hljs-type / class titles
+//   variable ← .hljs-variable / .hljs-template-variable
+// The remaining highlight.js classes are bucketed to the nearest of the
+// same eight by judgement (the canonical pairs above are exact); the
+// goal is that every span lands in the family, not that each bucket
+// matches One Dark's own file class-for-class.
+//
+// Deliberately NOT set: `.hljs` base colour/background and the
+// `.hljs-addition` / `.hljs-deletion` diff classes — containers (diff
+// panes, markdown fences) own their surfaces, and a palette layer that
+// painted backgrounds would fight them.
+
+// keyword — purple
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-formula {
+  color: var(--code-keyword, #c678dd);
+}
+
+// builtin — purple in dark, blue in light
+.hljs-built_in,
+.hljs-selector-id,
+.hljs-symbol,
+.hljs-bullet,
+.hljs-link,
+.hljs-meta {
+  color: var(--code-builtin, #c678dd);
+}
+
+// string — green
+.hljs-string,
+.hljs-regexp,
+.hljs-attribute,
+.hljs-meta .hljs-string {
+  color: var(--code-string, #98c379);
+}
+
+// number — orange in dark, blue in light
+.hljs-number,
+.hljs-literal,
+.hljs-attr,
+.hljs-property,
+.hljs-selector-class,
+.hljs-selector-attr,
+.hljs-selector-pseudo {
+  color: var(--code-number, #d19a66);
+}
+
+// comment — grey, italic
+.hljs-comment,
+.hljs-quote,
+.hljs-doctag {
+  color: var(--code-comment, #5c6370);
+  font-style: italic;
+}
+
+// function — blue
+.hljs-title,
+.hljs-title.function_,
+.hljs-title.function_.invoke__,
+.hljs-section {
+  color: var(--code-function, #61afef);
+}
+
+// type — yellow in dark, green in light
+.hljs-type,
+.hljs-title.class_,
+.hljs-class .hljs-title {
+  color: var(--code-type, #e5c07b);
+}
+
+// variable — red in dark, orange in light
+.hljs-variable,
+.hljs-template-variable,
+.hljs-subst,
+.hljs-name,
+.hljs-tag {
+  color: var(--code-variable, #e06c75);
+}
+
+// Non-colour emphasis classes: keep the shapes highlight.js intends.
+.hljs-emphasis {
+  font-style: italic;
+}
+
+.hljs-strong {
+  font-weight: bold;
+}

package/src/styles/vendoredSync.test.ts

@@ -52,6 +52,8 @@ const VENDORED_FROM_VUE: Array<[string, string]> = [
   // (packages/theme/styles) and is vendored here so npm consumers can
   // resolve it — the exports map only exposes ./styles/*.
   ["theme/scrollbar.scss", "../../theme/styles/_scrollbar.scss"],
+  // The syntax palette for .hljs-* spans lives there for the same reason.
+  ["theme/highlight.scss", "../../theme/styles/_highlight.scss"],
 ];