@plannotator/ui 0.28.0 → 0.29.0

package/utils/skillReferences.ts

@@ -0,0 +1,475 @@
+/**
+ * Skill references in comments — pure logic.
+ *
+ * A comment may reference agent skills by name with a `/` or `$` trigger
+ * (interchangeable). References live in the comment TEXT itself (`$write-better`),
+ * never as separate annotation state, so they survive draft restore, panel
+ * edits, and share round-trips, and deleting the token deletes the reference.
+ *
+ * The catalog comes from `/api/skills` (see utils/skillCatalog.ts). This module
+ * is browser-safe and dependency-free: trigger detection for the composer,
+ * token extraction against a known catalog, and the export rendering hook the
+ * feedback exporters call through a module-level registry seam
+ * (`setSkillCatalogForExport`) whose default — an empty catalog — reproduces
+ * pre-feature behavior byte-for-byte.
+ */
+
+export type SkillRootId = 'claude' | 'codex' | 'universal';
+
+export interface SkillCatalogEntry {
+  name: string;
+  root: SkillRootId;
+  description?: string;
+  /** Skill frontmatter carries `disable-model-invocation: true`: only a human can invoke it. */
+  humanOnly: boolean;
+  /** Absolute path to the skill directory, when the server provides it. */
+  dir?: string;
+}
+
+export const SKILL_TRIGGER_CHARS = ['/', '$'] as const;
+export type SkillTriggerChar = (typeof SKILL_TRIGGER_CHARS)[number];
+
+/** Longest query the composer keeps treating as a skill lookup. */
+export const MAX_SKILL_QUERY_LEN = 48;
+
+/** Characters a skill name (and thus an in-progress query) may contain. */
+const TOKEN_CHARS = /^[A-Za-z0-9._-]*$/;
+
+export interface SkillTriggerContext {
+  /** Index of the trigger character in the text. */
+  start: number;
+  trigger: SkillTriggerChar;
+  /** Text between the trigger character and the caret. */
+  query: string;
+}
+
+/**
+ * The active skill trigger at `caret`, or null.
+ *
+ * A trigger is a `/` or `$` that starts a word: at position 0 or preceded by
+ * whitespace or `(`. This is what keeps ordinary typing inert — `packages/ui`,
+ * `and/or`, and `a/b` never trigger because their `/` follows a word character.
+ * The query runs from the trigger to the caret and must stay within skill-name
+ * characters, so typing a space (or any other breaking character) ends the
+ * lookup naturally.
+ *
+ * A bare `/` or `$` (empty query) IS a trigger: it opens the full catalog,
+ * matching how slash/skill menus behave in the host agents. The safety story
+ * for a multi-line composer where Enter means newline and Tab means leave the
+ * field lives in the MENU, not here: while the menu is open with NO row
+ * explicitly activated (arrow keys), every key behaves exactly as if the menu
+ * were closed — "This costs $" + Enter is a newline, "cd /" + Tab leaves the
+ * field. See useSkillReferenceAutocomplete.
+ */
+export function findSkillTrigger(text: string, caret: number): SkillTriggerContext | null {
+  if (caret < 1 || caret > text.length) return null;
+
+  // Walk back over query characters to the nearest candidate trigger.
+  let start = caret - 1;
+  while (start >= 0 && !SKILL_TRIGGER_CHARS.includes(text[start] as SkillTriggerChar)) {
+    if (caret - start > MAX_SKILL_QUERY_LEN) return null;
+    start--;
+  }
+  if (start < 0) return null;
+
+  const trigger = text[start] as SkillTriggerChar;
+  const before = start === 0 ? '' : text[start - 1];
+  if (before !== '' && !/[\s(]/.test(before)) return null;
+
+  const query = text.slice(start + 1, caret);
+  if (query.length > MAX_SKILL_QUERY_LEN) return null;
+  if (!TOKEN_CHARS.test(query)) return null;
+
+  return { start, trigger, query };
+}
+
+/**
+ * Filter the catalog for the picker: case-insensitive, name prefix matches
+ * first, then name substring, then description substring. Stable within each
+ * tier (catalog order is alphabetical from the server).
+ */
+export function filterSkillCatalog(
+  catalog: SkillCatalogEntry[],
+  query: string,
+  limit = 50,
+): SkillCatalogEntry[] {
+  const q = query.toLowerCase();
+  if (!q) return catalog.slice(0, limit);
+
+  const prefix: SkillCatalogEntry[] = [];
+  const substring: SkillCatalogEntry[] = [];
+  const description: SkillCatalogEntry[] = [];
+  for (const entry of catalog) {
+    const name = entry.name.toLowerCase();
+    if (name.startsWith(q)) prefix.push(entry);
+    else if (name.includes(q)) substring.push(entry);
+    else if (entry.description?.toLowerCase().includes(q)) description.push(entry);
+  }
+  return [...prefix, ...substring, ...description].slice(0, limit);
+}
+
+/**
+ * Well-known single-segment absolute paths (Filesystem Hierarchy Standard
+ * roots). `/run`, `/tmp`, `/etc`… read as filesystem paths in prose, so a
+ * `/`-triggered token with one of these names is never extracted as a skill
+ * reference, even when a skill shares the name. `$name` remains fully
+ * available for such skills, and menu insertion switches a `/` trigger to `$`
+ * for them so an inserted reference always survives extraction.
+ */
+const RESERVED_PATH_SEGMENTS = new Set([
+  'bin', 'boot', 'dev', 'etc', 'home', 'lib', 'lib64', 'media', 'mnt', 'opt',
+  'proc', 'root', 'run', 'sbin', 'srv', 'sys', 'tmp', 'usr', 'var',
+]);
+
+/**
+ * Words that, when they immediately precede a `/`-triggered token on the same
+ * line, mark it as prose rather than a skill reference (reproduced false
+ * positives against real review comments — see #1229 hardening):
+ *
+ * - HTTP method verbs: "a POST /agents endpoint", "a GET /show route" — the
+ *   token reads as a route path.
+ * - Modal auxiliaries: "this step could /simplify a lot" — a modal is
+ *   followed by a bare verb, so the token reads as an emphasized verb, not a
+ *   skill noun.
+ *
+ * Deliberately narrow: ordinary verbs ("use /write-better here") and
+ * line-starting or post-newline tokens are untouched, `$name` is never
+ * affected, and menu insertion switches `/` to `$` when the reference would
+ * land after one of these words (see insertSkillReference), so an inserted
+ * reference always survives extraction.
+ */
+const SLASH_PROSE_PRECEDING_WORDS = new Set([
+  // HTTP method verbs
+  'get', 'head', 'post', 'put', 'delete', 'options', 'patch',
+  // Modal auxiliaries
+  'can', 'could', 'may', 'might', 'must', 'shall', 'should', 'will', 'would',
+]);
+
+/**
+ * True when the character run immediately before `triggerIndex` is same-line
+ * whitespace preceded by one of SLASH_PROSE_PRECEDING_WORDS. A newline (or
+ * any non-space boundary) between the word and the trigger breaks the pairing
+ * — a line-starting `/name` always reads as deliberate.
+ */
+function slashTokenReadsAsProse(text: string, triggerIndex: number): boolean {
+  const before = text.slice(0, triggerIndex);
+  const word = /([A-Za-z]+)[ \t]+$/.exec(before)?.[1];
+  return word !== undefined && SLASH_PROSE_PRECEDING_WORDS.has(word.toLowerCase());
+}
+
+/**
+ * Replace the in-progress trigger token with the chosen skill (keeping the
+ * trigger character the user typed) plus a trailing space, so the inserted
+ * reference is always cleanly word-bounded. The exceptions to "keep the
+ * typed trigger" all switch `/` to `$` because extraction would otherwise
+ * drop the inserted reference:
+ * - a skill whose name is a well-known absolute path segment (`run`, `tmp`…)
+ *   — extraction reads `/run` as a path;
+ * - a trigger immediately preceded by an HTTP verb or modal auxiliary
+ *   ("could /simplify") — extraction reads that `/name` as prose (see
+ *   SLASH_PROSE_PRECEDING_WORDS).
+ */
+export function insertSkillReference(
+  text: string,
+  caret: number,
+  trigger: SkillTriggerContext,
+  skill: SkillCatalogEntry,
+): { text: string; caret: number } {
+  const triggerChar =
+    trigger.trigger === '/' &&
+    (RESERVED_PATH_SEGMENTS.has(skill.name.toLowerCase()) ||
+      slashTokenReadsAsProse(text, trigger.start))
+      ? '$'
+      : trigger.trigger;
+  const inserted = `${triggerChar}${skill.name} `;
+  return {
+    text: text.slice(0, trigger.start) + inserted + text.slice(caret),
+    caret: trigger.start + inserted.length,
+  };
+}
+
+/** One skill-reference occurrence in a text, with its exact span. */
+export interface SkillReferenceToken {
+  /** Index of the trigger character. */
+  start: number;
+  /** Index just past the last name character (excludes trailing punctuation). */
+  end: number;
+  entry: SkillCatalogEntry;
+}
+
+/**
+ * Every skill-reference occurrence in the text, in order, WITH positions and
+ * without dedupe — this is what the composer's highlight overlay paints, so a
+ * name referenced twice highlights twice.
+ *
+ * A reference is a word-starting `/name` or `$name` whose name matches a
+ * catalog entry — an exact-case match wins, with case-insensitive matching as
+ * a fallback so a catalog holding two skills differing only by case (e.g.
+ * `Write-Better` and `write-better` from different roots) never swaps
+ * identities on an explicit pick. Path and prose forms are excluded:
+ * - followed by `/` or `\` — a path continuation (`/docs/foo`, `$HOME/bin`);
+ * - preceded by `](` — a markdown link destination (`[x](/write-better)`);
+ * - a `/` token naming a well-known absolute path segment (`/run`, `/tmp`) —
+ *   see RESERVED_PATH_SEGMENTS; `$run` still counts;
+ * - a `/` token immediately preceded on the same line by an HTTP verb or a
+ *   modal auxiliary ("GET /show", "could /simplify") — see
+ *   SLASH_PROSE_PRECEDING_WORDS; `$show` still counts.
+ *
+ * There is deliberately NO shell-redirect exclusion (`cat /run > out`): the
+ * motivating case is already covered by the reserved-path rule, and excluding
+ * on a following `<`/`>` produced false negatives on ordinary prose
+ * ("use /animate <- this one", "quality: /write-better > everything else").
+ */
+export function findSkillReferenceTokens(
+  text: string,
+  catalog: SkillCatalogEntry[],
+): SkillReferenceToken[] {
+  if (!text || catalog.length === 0) return [];
+  // Exact-case entries win; the lowercase map is only a fallback, so two
+  // skills differing only by case never collapse into one identity (an
+  // explicit `$Write-Better` must never resolve to `write-better` — wrong
+  // skill, wrong humanOnly flag, wrong SKILL.md injected). First catalog
+  // entry wins each fallback slot, matching discovery's first-seen precedence.
+  const byExactName = new Map<string, SkillCatalogEntry>();
+  const byLowerName = new Map<string, SkillCatalogEntry>();
+  for (const s of catalog) {
+    if (!byExactName.has(s.name)) byExactName.set(s.name, s);
+    const lower = s.name.toLowerCase();
+    if (!byLowerName.has(lower)) byLowerName.set(lower, s);
+  }
+  const lookup = (n: string) => byExactName.get(n) ?? byLowerName.get(n.toLowerCase());
+
+  const tokens: SkillReferenceToken[] = [];
+  const re = /(^|[\s(])([$/])([A-Za-z0-9][A-Za-z0-9._-]*)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    const after = text[m.index + m[0].length];
+    if (after === '/' || after === '\\') continue;
+    // Markdown link destination: `[label](/name)` is a URL, not a reference.
+    if (m[1] === '(' && text[m.index - 1] === ']') continue;
+    // Sentence-final dots are punctuation, not part of the name ("use $humanizer.").
+    const name = m[3].toLowerCase();
+    const trimmed = m[3].replace(/\.+$/, '');
+    const trimmedName = trimmed.toLowerCase();
+    // `/run`-style well-known absolute paths never count (only for `/`).
+    if (m[2] === '/' && (RESERVED_PATH_SEGMENTS.has(name) || RESERVED_PATH_SEGMENTS.has(trimmedName)))
+      continue;
+    // Prose guard (only for `/`): "GET /show" is a route, "could /simplify"
+    // is an emphasized verb — never a skill reference.
+    if (m[2] === '/' && slashTokenReadsAsProse(text, m.index + m[1].length)) continue;
+    const exact = lookup(m[3]);
+    const entry = exact ?? lookup(trimmed);
+    if (!entry) continue;
+    const start = m.index + m[1].length;
+    const nameLen = exact ? m[3].length : trimmed.length;
+    tokens.push({ start, end: start + 1 + nameLen, entry });
+  }
+  return tokens;
+}
+
+/**
+ * Every skill the text references, in first-appearance order, deduped by name.
+ * Same matching rules as findSkillReferenceTokens above.
+ */
+export function extractSkillReferences(
+  text: string,
+  catalog: SkillCatalogEntry[],
+): SkillCatalogEntry[] {
+  const found: SkillCatalogEntry[] = [];
+  const seen = new Set<string>();
+  for (const token of findSkillReferenceTokens(text, catalog)) {
+    if (seen.has(token.entry.name)) continue;
+    seen.add(token.entry.name);
+    found.push(token.entry);
+  }
+  return found;
+}
+
+// ---------------------------------------------------------------------------
+// Export seam
+// ---------------------------------------------------------------------------
+
+// Module-level registry seam (see packages/ui/CLAUDE.md): the exporters in
+// utils/parser.ts are pure and cannot fetch, so the app registers the fetched
+// catalog here once per session. Default (empty) means the exporters emit
+// nothing extra — hosts without the endpoint are byte-for-byte unchanged.
+let exportCatalog: SkillCatalogEntry[] = [];
+
+export function setSkillCatalogForExport(catalog: SkillCatalogEntry[]): void {
+  exportCatalog = catalog;
+}
+
+export function resetSkillCatalogForExport(): void {
+  exportCatalog = [];
+}
+
+/**
+ * A human-only skill's SKILL.md body, fetched from the server for injection
+ * into exported feedback (see utils/skillCatalog.ts, primeSkillContentsForExport).
+ */
+export interface SkillExportContent {
+  /** Verbatim SKILL.md body (frontmatter stripped), possibly truncated. */
+  content: string;
+  /** True when the server cut the body at its injection bound. */
+  truncated: boolean;
+  /** Absolute path to the skill directory. */
+  dir: string;
+  /** Absolute path to SKILL.md. */
+  path: string;
+}
+
+// Companion registry to the export catalog: bodies of the human-only skills
+// the session has referenced, fetched lazily. Default (empty) means human-only
+// references fall back to naming the skill plus its directory.
+const exportContents = new Map<string, SkillExportContent>();
+
+export function registerSkillContentForExport(name: string, content: SkillExportContent): void {
+  exportContents.set(name, content);
+}
+
+export function resetSkillContentsForExport(): void {
+  exportContents.clear();
+}
+
+const HUMAN_ONLY_EXPORT_NOTE =
+  'human-invocation-only: you cannot invoke this skill; the reviewer included it as context';
+
+/**
+ * The structural forms the injection block itself uses: the BEGIN/END markers
+ * and the truncation notice. A skill body line matching one of these could
+ * close our block early (everything after it then reads to the receiving
+ * agent as the reviewer's own words), forge a BEGIN marker for a skill nobody
+ * referenced, or forge a truncation notice pointing at an attacker-chosen
+ * path. Skill bodies are user-installed — routinely from third-party repos —
+ * so lookalike lines are neutralized before injection. Leading whitespace and
+ * case variants count, as do lines dressed in markdown decoration (`> `,
+ * `**`, backticks, `#`), unicode-dash or `=` rules, and invisible format
+ * characters laced through the words: a loose reader would still take every
+ * one of them for markers. The match stays anchored to a leading dash/equals
+ * run (after optional decoration), so the words "BEGIN SKILL INSTRUCTIONS"
+ * appearing mid-sentence in ordinary prose are never touched.
+ */
+const MARKER_LOOKALIKE_RE =
+  // Dash run: ASCII hyphen, `=`, the unicode hyphen/dash block U+2010–U+2015
+  // (incl. en/em dash), and the minus sign U+2212.
+  /^[\s>*_#`]*(?:[-=‐-―−]{2,}\s*(?:BEGIN|END)\s*SKILL\s*INSTRUCTIONS\b|\[\s*Instructions\s*truncated\b)/i;
+
+/**
+ * Invisible format characters (Unicode category Cf: zero-width space/joiners
+ * U+200B–U+200D, word joiner U+2060, BOM/zero-width no-break space U+FEFF,
+ * soft hyphens, bidi controls, …). JS `\s` matches none of these, so
+ * `---​BEGIN​SKILL​INSTRUCTIONS` slipped past the old regex
+ * while still reading as a marker to an LLM. They are stripped (removed, not
+ * replaced — an attacker can also lace them INSIDE a word) before matching;
+ * the ORIGINAL line is what gets neutralized. The inter-word `\s*` in the
+ * regex above is what keeps the stripped, jammed-together form matchable.
+ */
+const INVISIBLE_FORMAT_CHARS_RE = /\p{Cf}/gu;
+
+const NEUTRALIZED_LINE_PREFIX =
+  '[plannotator: the following skill-body line matched an injection marker and was neutralized] ';
+
+/**
+ * Neutralize body lines that match our own structural markers, visibly: each
+ * matching line is kept verbatim but prefixed, never silently deleted, so the
+ * line no longer parses as a marker while the reader can still see exactly
+ * what the body contained. Matching runs against the line with invisible
+ * format characters stripped, but the original line is what is prefixed.
+ */
+export function neutralizeSkillMarkerLines(body: string): string {
+  return body
+    .split('\n')
+    .map((line) =>
+      MARKER_LOOKALIKE_RE.test(line.replace(INVISIBLE_FORMAT_CHARS_RE, ''))
+        ? NEUTRALIZED_LINE_PREFIX + line
+        : line,
+    )
+    .join('\n');
+}
+
+/** Instruction block for one injected human-only skill. Unmistakably delimited
+ *  (BEGIN/END markers survive any markdown inside the body, unlike a fence)
+ *  and labeled so it can never read as the reviewer's own words. Body lines
+ *  that imitate the markers are neutralized (see neutralizeSkillMarkerLines)
+ *  so the body cannot close the block early or forge a sibling block. */
+function injectedSkillSection(name: string, body: SkillExportContent): string {
+  let out = `--- BEGIN SKILL INSTRUCTIONS: ${name} ---\n`;
+  out += `This skill cannot be invoked by a model, so its instructions are included here at the reviewer's request. Follow them when acting on this feedback.\n`;
+  out += `Skill directory: ${body.dir}\n`;
+  out += `Resolve any relative paths in the instructions below (e.g. references/, scripts/, assets/) against that absolute directory; your working directory is not the skill directory.\n\n`;
+  out += `${neutralizeSkillMarkerLines(body.content)}\n`;
+  if (body.truncated) {
+    out += `\n[Instructions truncated: this is not the full skill. Read the rest at ${body.path}]\n`;
+  }
+  out += `--- END SKILL INSTRUCTIONS: ${name} ---\n`;
+  return out;
+}
+
+/**
+ * The export block for a comment's skill references, or '' when the comment
+ * references none (or no catalog was registered). Appended to the comment in
+ * the exported feedback so the acting agent knows which skills to apply.
+ *
+ * Model-invocable skills export as names — the agent can fetch those itself.
+ * Human-only skills cannot be invoked by the agent, so their SKILL.md body is
+ * injected verbatim (when the session fetched it): a human referencing a
+ * human-only skill IS the human invocation. When no body is available the
+ * skill falls back to its name plus its directory, and to the plain context
+ * note when not even the directory is known. Never throws, never emits a
+ * partial block.
+ *
+ * `injectedNames` is an optional per-export dedupe: exporters thread one Set
+ * through every comment of a single export so a skill's instructions are
+ * injected once, and later references point at the earlier injection.
+ *
+ * `options.external` marks a comment that was NOT written by the reviewer in
+ * this UI — it arrived through the unauthenticated external-annotations API
+ * (annotations carrying a `source`), which any local process can post to.
+ * The whole justification for injection is that a human referencing a
+ * human-only skill IS the human invocation, so a tool-submitted comment must
+ * never cause it: external comments still LIST their skill references, but a
+ * human-only reference falls back to naming the skill plus its directory
+ * (the same shape as the content-unavailable path) instead of injecting.
+ */
+export function skillReferenceExportBlock(
+  text: string | undefined,
+  injectedNames?: Set<string>,
+  options?: { external?: boolean },
+): string {
+  if (!text) return '';
+  const refs = extractSkillReferences(text, exportCatalog);
+  if (refs.length === 0) return '';
+
+  const external = options?.external === true;
+  const toInject: Array<{ name: string; body: SkillExportContent }> = [];
+  let out = `**Skills referenced** (the reviewer is asking you to invoke these skills when acting on this feedback):\n`;
+  for (const ref of refs) {
+    if (!ref.humanOnly) {
+      out += `- \`${ref.name}\`\n`;
+      continue;
+    }
+    const body = exportContents.get(ref.name);
+    if (body && injectedNames?.has(ref.name)) {
+      // Already injected earlier in this export (necessarily by a reviewer-
+      // written comment) — true regardless of who references it now.
+      out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions are included earlier in this feedback)\n`;
+    } else if (external) {
+      // Tool-submitted comment: name + directory, never verbatim injection.
+      out += ref.dir
+        ? `- \`${ref.name}\` (cannot be invoked by a model; this comment came from an external tool, so its instructions are not included — SKILL.md is in ${ref.dir})\n`
+        : `- \`${ref.name}\` (${HUMAN_ONLY_EXPORT_NOTE})\n`;
+    } else if (body) {
+      injectedNames?.add(ref.name);
+      toInject.push({ name: ref.name, body });
+      out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions are included below at the reviewer's request)\n`;
+    } else if (ref.dir) {
+      out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions could not be included, read SKILL.md in ${ref.dir} and follow it)\n`;
+    } else {
+      out += `- \`${ref.name}\` (${HUMAN_ONLY_EXPORT_NOTE})\n`;
+    }
+  }
+  for (const { name, body } of toInject) {
+    out += `\n${injectedSkillSection(name, body)}`;
+  }
+  return out;
+}

package/utils/syntaxTheme.ts

@@ -0,0 +1,83 @@
+/**
+ * Maps a Plannotator colour theme onto the Shiki theme that renders code in it.
+ *
+ * This used to live in `packages/review-editor/hooks/usePierreTheme.ts` and only
+ * served the diff pane. It moved here so the plan/annotate editor's markdown
+ * fences resolve the SAME theme the diff pane resolves, which is what makes a
+ * fenced code block and a diff hunk finally look like they belong to the same
+ * app. `usePierreTheme` re-exports both symbols, so the review editor's imports
+ * are unchanged.
+ *
+ * Names on the right are resolved by `@pierre/diffs` — the `pierre-*` ones come
+ * from `@pierre/theme`, the rest from `@shikijs/themes`. Both registries are
+ * already bundled (Pierre pulls in Shiki's full bundle), so consuming them here
+ * costs no additional bytes.
+ */
+
+/** Plannotator theme id -> Shiki theme name, per mode. `null` = this palette
+ *  has no counterpart in that mode and falls back to the Pierre default. */
+export const SHIKI_THEME_MAP: Record<string, { dark: string | null; light: string | null }> = {
+  'andromeeda': { dark: 'andromeeda', light: null },
+  'aurora-x': { dark: 'aurora-x', light: null },
+  'ayu-dark': { dark: 'ayu-dark', light: null },
+  'catppuccin': { dark: 'catppuccin-mocha', light: 'catppuccin-latte' },
+  'colorblind': { dark: 'pierre-dark-protanopia-deuteranopia', light: 'pierre-light-protanopia-deuteranopia' },
+  'dark-plus': { dark: 'dark-plus', light: 'light-plus' },
+  'dracula': { dark: 'dracula', light: null },
+  'everforest': { dark: 'everforest-dark', light: 'everforest-light' },
+  'everforest-hard': { dark: 'everforest-dark', light: 'everforest-light' },
+  'everforest-soft': { dark: 'everforest-dark', light: 'everforest-light' },
+  'github': { dark: 'github-dark', light: 'github-light' },
+  'gruvbox': { dark: 'gruvbox-dark-medium', light: 'gruvbox-light-medium' },
+  'houston': { dark: 'houston', light: null },
+  'kanagawa-dragon': { dark: 'kanagawa-dragon', light: null },
+  'kanagawa-lotus': { dark: null, light: 'kanagawa-lotus' },
+  'kanagawa-wave': { dark: 'kanagawa-wave', light: null },
+  'laserwave': { dark: 'laserwave', light: null },
+  'material': { dark: 'material-theme', light: 'material-theme-lighter' },
+  'min': { dark: 'min-dark', light: 'min-light' },
+  'monokai-pro': { dark: 'monokai', light: null },
+  'night-owl': { dark: 'night-owl', light: null },
+  'nord': { dark: 'nord', light: null },
+  'one-dark-pro': { dark: 'one-dark-pro', light: null },
+  'one-light': { dark: null, light: 'one-light' },
+  'plastic': { dark: 'plastic', light: null },
+  'poimandres': { dark: 'poimandres', light: null },
+  'red': { dark: 'red', light: null },
+  'rose-pine': { dark: 'rose-pine', light: 'rose-pine-dawn' },
+  'slack': { dark: 'slack-dark', light: 'slack-ochin' },
+  'snazzy-light': { dark: null, light: 'snazzy-light' },
+  'solarized': { dark: 'solarized-dark', light: 'solarized-light' },
+  'synthwave-84': { dark: 'synthwave-84', light: null },
+  'tokyo-night': { dark: 'tokyo-night', light: null },
+  'vesper': { dark: 'vesper', light: null },
+  'vitesse': { dark: 'vitesse-dark', light: 'vitesse-light' },
+  'vitesse-black': { dark: 'vitesse-black', light: null },
+};
+
+/** `@pierre/diffs`' own `DEFAULT_THEMES`. Anything the map does not cover (the
+ *  Plannotator default palette, plus every palette with no counterpart in the
+ *  active mode) renders in these, which is exactly what the diff pane does when
+ *  `resolveSyntaxTheme` returns `undefined`. */
+export const DEFAULT_SYNTAX_THEME = { dark: 'pierre-dark', light: 'pierre-light' } as const;
+
+/**
+ * The theme pair to hand `@pierre/diffs`, or `undefined` to let it use its own
+ * defaults. Returning `undefined` (rather than the default pair) is deliberate:
+ * it keeps the diff pane's prop identity stable for palettes that never
+ * customised it.
+ */
+export function resolveSyntaxTheme(colorTheme: string, mode: 'dark' | 'light'): { dark: string; light: string } | undefined {
+  const map = SHIKI_THEME_MAP[colorTheme];
+  if (!map || !map[mode]) return undefined;
+  return { dark: map.dark || DEFAULT_SYNTAX_THEME.dark, light: map.light || DEFAULT_SYNTAX_THEME.light };
+}
+
+/**
+ * The single concrete Shiki theme name for the palette currently on screen.
+ * Markdown fences render one mode at a time, so unlike the diff pane (which
+ * hands Pierre a dark/light pair and lets CSS pick) they want a resolved name.
+ */
+export function resolveFenceTheme(colorTheme: string, mode: 'dark' | 'light'): string {
+  return resolveSyntaxTheme(colorTheme, mode)?.[mode] ?? DEFAULT_SYNTAX_THEME[mode];
+}