@plannotator/ui 0.28.0 → 0.29.0

package/components/icons/themeIcons.tsx

@@ -12,7 +12,7 @@ import React from 'react';
  * the dropdown segmented controls use w-3.5, the settings tab uses w-3.
  */
 
-interface IconProps {
+export interface IconProps {
   className?: string;
 }
 

package/components/plan-diff/PlanCleanDiffView.tsx

@@ -7,8 +7,9 @@
  */
 
 import React, { useEffect, useRef, useState, useCallback } from "react";
-import hljs from "highlight.js";
 import { parseMarkdownToBlocks, computeListIndices } from "../../utils/parser";
+import { applyHighlight, codeBlockClassName } from "../../utils/codeHighlight";
+import { useFenceTheme } from "../../hooks/useFenceTheme";
 import { ListItemBody } from "../ListItemBody";
 import type { Block, Annotation, EditorMode, ImageAttachment } from "../../types";
 import { AnnotationType } from "../../types";
@@ -331,6 +332,7 @@ export const PlanCleanDiffView: React.FC<PlanCleanDiffViewProps> = ({
           initialText={commentPopover.initialText}
           onSubmit={handleCommentSubmit}
           onClose={handleCommentClose}
+          skillReferences
         />
       )}
 
@@ -695,22 +697,20 @@ const SimpleBlockRenderer: React.FC<{ block: Block; orderedIndex?: number | null
 
 const SimpleCodeBlock: React.FC<{ block: Block }> = ({ block }) => {
   const codeRef = useRef<HTMLElement>(null);
+  const fenceTheme = useFenceTheme();
 
   useEffect(() => {
     if (codeRef.current) {
-      codeRef.current.removeAttribute("data-highlighted");
-      codeRef.current.className = `hljs font-mono${block.language ? ` language-${block.language}` : ""}`;
-      hljs.highlightElement(codeRef.current);
+      codeRef.current.className = codeBlockClassName(block.language);
+      // Language-less fences stay plain (#1212) — applyHighlight never guesses.
+      applyHighlight(codeRef.current, block.content, block.language, fenceTheme);
     }
-  }, [block.content, block.language]);
+  }, [block.content, block.language, fenceTheme]);
 
   return (
     <div className="relative group my-5">
       <pre className="bg-muted/50 border border-border/30 rounded-lg overflow-x-auto">
-        <code
-          ref={codeRef}
-          className={`hljs font-mono${block.language ? ` language-${block.language}` : ""}`}
-        >
+        <code ref={codeRef} className={codeBlockClassName(block.language)}>
           {block.content}
         </code>
       </pre>

package/components/plan-diff/PlanDiffBadge.tsx

@@ -13,6 +13,18 @@ interface PlanDiffBadgeProps {
   isActive: boolean;
   onToggle: () => void;
   hasPreviousVersion: boolean;
+  /**
+   * Optional baseline context for surfaces whose diff baseline is NOT "the
+   * previous plan revision" — annotate/folder sessions pass "since last
+   * review" so the counts read against the right baseline (not, e.g., the
+   * git uncommitted-vs-HEAD numbers shown elsewhere). Rendered as a short
+   * muted suffix after the counts. Plan review passes nothing and renders
+   * exactly as before.
+   */
+  baselineLabel?: string;
+  /** Tooltip override for the inactive state, paired with `baselineLabel`
+   *  (e.g. "Changes since you last reviewed this file"). */
+  baselineTooltip?: string;
 }
 
 export const PlanDiffBadge: React.FC<PlanDiffBadgeProps> = ({
@@ -20,6 +32,8 @@ export const PlanDiffBadge: React.FC<PlanDiffBadgeProps> = ({
   isActive,
   onToggle,
   hasPreviousVersion,
+  baselineLabel,
+  baselineTooltip,
 }) => {
   if (!hasPreviousVersion || !stats) return null;
 
@@ -34,7 +48,11 @@ export const PlanDiffBadge: React.FC<PlanDiffBadgeProps> = ({
           ? "bg-primary/15"
           : "bg-muted/50 hover:bg-muted"
       }`}
-      title={isActive ? "Exit plan diff view" : "Show what changed from previous version"}
+      title={
+        isActive
+          ? "Exit plan diff view"
+          : baselineTooltip ?? "Show what changed from previous version"
+      }
     >
       <span className={isActive ? "text-success" : "text-success/70"}>
         +{stats.additions}
@@ -43,6 +61,9 @@ export const PlanDiffBadge: React.FC<PlanDiffBadgeProps> = ({
       <span className={isActive ? "text-destructive" : "text-destructive/70"}>
         -{stats.deletions}
       </span>
+      {baselineLabel && (
+        <span className="text-muted-foreground/60 ml-1">{baselineLabel}</span>
+      )}
     </button>
   );
 };

package/components/settings/HooksTab.tsx

@@ -1,5 +1,6 @@
 import React, { useEffect, useState } from 'react';
-import { FAVICON_SVG } from '@plannotator/core/favicon';
+import { FAVICON_PNG_DATA_URL } from '@plannotator/core/favicon';
+import { copyTextToClipboard } from '../../utils/clipboard';
 
 interface HooksStatus {
   pfmReminder: { enabled: boolean };
@@ -22,7 +23,8 @@ const CopyPathButton: React.FC<{ filePath: string }> = ({ filePath }) => {
   const [copied, setCopied] = useState(false);
 
   const copy = () => {
-    navigator.clipboard.writeText(filePath).then(() => {
+    void copyTextToClipboard(filePath).then((ok) => {
+      if (!ok) return;
       setCopied(true);
       setTimeout(() => setCopied(false), 1500);
     });
@@ -86,9 +88,10 @@ export const HooksTab: React.FC = () => {
       {/* PFM Reminder Card */}
       <div className="rounded-lg border border-border bg-card p-4 space-y-3">
         <div className="flex items-start gap-3">
-          <div
-            className="w-8 h-8 flex-shrink-0 rounded-md overflow-hidden"
-            dangerouslySetInnerHTML={{ __html: FAVICON_SVG }}
+          <img
+            src={FAVICON_PNG_DATA_URL}
+            alt=""
+            className="w-8 h-8 flex-shrink-0 object-contain"
           />
           <div className="flex-1 min-w-0">
             <div className="flex items-center justify-between gap-2">
@@ -130,9 +133,10 @@ export const HooksTab: React.FC = () => {
       {/* Compound Improvement Hook Card */}
       <div className="rounded-lg border border-border bg-card p-4 space-y-3">
         <div className="flex items-start gap-3">
-          <div
-            className="w-8 h-8 flex-shrink-0 rounded-md overflow-hidden"
-            dangerouslySetInnerHTML={{ __html: FAVICON_SVG }}
+          <img
+            src={FAVICON_PNG_DATA_URL}
+            alt=""
+            className="w-8 h-8 flex-shrink-0 object-contain"
           />
           <div className="flex-1 min-w-0">
             <div className="flex items-center justify-between gap-2">

package/components/sidebar/FileBrowser.tsx

@@ -43,6 +43,9 @@ interface AggregateWorkspaceChange {
   files: number;
 }
 
+// Display-name stripping only — deliberately narrower than the annotatable
+// set. Config files (config.yaml vs config.json) keep their extensions so
+// same-named siblings stay distinguishable in the tree.
 const FILE_EXTENSION_RE = /\.(mdx?|txt|html?)$/i;
 
 function normalizeFilterText(value: string): string {
@@ -418,7 +421,7 @@ const DirSection: React.FC<{
   if (dir.tree.length === 0) {
     return (
       <div className="px-3 py-2 text-[11px] text-muted-foreground">
-        No markdown or text files found
+        No annotatable files found
       </div>
     );
   }

package/components/themeModes.tsx

@@ -0,0 +1,28 @@
+import type { FC } from 'react';
+import { MoonIcon, SunIcon, SystemIcon, type IconProps } from './icons/themeIcons';
+
+interface ThemeMode {
+  readonly id: string;
+  readonly label: string;
+  readonly Icon: FC<IconProps>;
+}
+
+/** The shared catalog rendered by every Light/Dark/System picker. */
+export const THEME_MODES = [
+  { id: 'light', label: 'Light', Icon: SunIcon },
+  { id: 'dark', label: 'Dark', Icon: MoonIcon },
+  { id: 'system', label: 'System', Icon: SystemIcon },
+] as const satisfies readonly ThemeMode[];
+
+/** A persisted theme-mode preference. */
+export type Mode = (typeof THEME_MODES)[number]['id'];
+
+/** Return whether an unknown persisted value is a supported theme mode. */
+export function isThemeMode(value: unknown): value is Mode {
+  return typeof value === 'string' && THEME_MODES.some(({ id }) => id === value);
+}
+
+/** Parse an unknown persisted value, falling back to a caller-provided mode. */
+export function parseThemeMode(value: unknown, fallback: Mode): Mode {
+  return isThemeMode(value) ? value : fallback;
+}

package/config/configStore.ts

@@ -29,6 +29,28 @@ function deepMerge(target: Record<string, unknown>, source: Record<string, unkno
   }
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Remove every leaf `shape` describes from `target`, pruning containers that
+ * empty out. Used to retract a queued server write once the server has spoken
+ * for the same leaves.
+ */
+function deletePaths(target: Record<string, unknown>, shape: Record<string, unknown>): void {
+  for (const key of Object.keys(shape)) {
+    if (!(key in target)) continue;
+    if (isPlainObject(target[key]) && isPlainObject(shape[key])) {
+      const child = target[key] as Record<string, unknown>;
+      deletePaths(child, shape[key] as Record<string, unknown>);
+      if (Object.keys(child).length === 0) delete target[key];
+    } else {
+      delete target[key];
+    }
+  }
+}
+
 /** Server write-back transport: posts a batch of changed server-synced settings. */
 export type ServerSyncFn = (payload: Record<string, unknown>) => void;
 
@@ -56,6 +78,10 @@ class ConfigStore {
   private serverSyncTimer: ReturnType<typeof setTimeout> | null = null;
   private pagehideFlushRegistered = false;
   private serverSync: ServerSyncFn = defaultServerSync;
+  /** True once a host installed its own transport via setServerSync(). */
+  private serverSyncInstalled = false;
+  /** Settings whose value came from the server config; seeds must not undo them. */
+  private serverOverridden = new Set<string>();
   private loaded = false;
 
   /**
@@ -132,6 +158,17 @@ class ConfigStore {
           if (fromServer !== undefined) {
             this.values.set(name, fromServer);
             def.toCookie(fromServer as never);
+            this.serverOverridden.add(name);
+            // Retract any write still queued for the leaves the server just
+            // spoke for. Without this, a write queued before init() flushes
+            // AFTER it and pushes the pre-init value back to the config file,
+            // which the next session would then restore over the cookie.
+            if (def.toServer) {
+              deletePaths(
+                this.pendingServerWrites,
+                def.toServer(fromServer as never) as Record<string, unknown>,
+              );
+            }
           }
         }
       }
@@ -139,6 +176,40 @@ class ConfigStore {
     this.notify();
   }
 
+  /**
+   * Install a resolved default for a setting: memory + cookie, never the
+   * server. For values a component computes at mount (e.g. ThemeProvider's
+   * default theme pair) rather than values a user chose — seeding must not
+   * write to ~/.plannotator/config.json, and must never overwrite a value the
+   * server already supplied through init().
+   */
+  seed<K extends SettingName>(key: K, value: SettingValue<K>): void {
+    this.ensureLoaded();
+    if (this.serverOverridden.has(key)) return;
+    const def = SETTINGS[key];
+    this.values.set(key, value);
+    def.toCookie(value as never);
+    this.notify();
+  }
+
+  /**
+   * Persist a user choice to memory + cookie, queuing the server write-back
+   * only when this store is actually talking to a server. Hosts that never
+   * installed a serverSync seam have no /api/config endpoint, so the legacy
+   * cookie-only APIs (ThemeProvider.setColorTheme) use this instead of set().
+   */
+  setLocal<K extends SettingName>(key: K, value: SettingValue<K>): void {
+    if (this.serverSyncInstalled) {
+      this.set(key, value);
+      return;
+    }
+    this.ensureLoaded();
+    const def = SETTINGS[key];
+    this.values.set(key, value);
+    def.toCookie(value as never);
+    this.notify();
+  }
+
   /** Get a resolved config value. Works outside React. */
   get<K extends SettingName>(key: K): SettingValue<K> {
     this.ensureLoaded();
@@ -169,9 +240,13 @@ class ConfigStore {
   /** Override the server write-back transport (default = inline POST /api/config). */
   setServerSync(fn: ServerSyncFn): void {
     this.serverSync = fn;
+    this.serverSyncInstalled = true;
   }
 
-  resetServerSync(): void { this.serverSync = defaultServerSync; }
+  resetServerSync(): void {
+    this.serverSync = defaultServerSync;
+    this.serverSyncInstalled = false;
+  }
 
   private notify(): void {
     this.version++;

package/config/settings.ts

@@ -12,6 +12,69 @@
 import type { DiffLineBgIntensity } from '@plannotator/core/config-types';
 import { storage } from '../utils/storage';
 import { generateIdentity } from '../utils/generateIdentity';
+import {
+  getDefaultThemePair,
+  normalizeThemePair,
+  seedThemePair,
+  type ThemePair,
+} from '../utils/themeRegistry';
+import { parseThemeMode } from '../components/themeModes';
+
+/** Legacy single-palette key, still written so a downgrade renders styled. */
+const COLOR_THEME_COOKIE = 'plannotator-color-theme';
+const MODE_COOKIE = 'plannotator-theme';
+const LIGHT_THEME_COOKIE = 'plannotator-light-theme';
+const DARK_THEME_COOKIE = 'plannotator-dark-theme';
+
+/**
+ * Where a host keeps the two PRE-PAIR values, if not under Plannotator's own
+ * keys. These mirror ThemeProvider's `storageKey` / `colorThemeStorageKey`
+ * props, which existed before the pair and are what a host's already-stored
+ * user preference lives under.
+ *
+ * Only these two legacy keys are overridable. The pair halves are a new
+ * concept with no pre-existing host data, so they always use the fixed
+ * `plannotator-light-theme` / `plannotator-dark-theme` keys; two hosts sharing
+ * one origin with different key prefixes would share those halves.
+ */
+export interface ThemePairLegacyKeys {
+  /** Where the mode is stored (ThemeProvider's `storageKey`). */
+  mode?: string;
+  /** Where the single pre-pair palette is stored (`colorThemeStorageKey`). */
+  colorTheme?: string;
+}
+
+/**
+ * Persist a pair to its cookies without touching the server.
+ *
+ * ThemeProvider calls this once it has resolved a pair, because a pair
+ * migrated from the legacy single-palette key is DERIVED until it is written:
+ * the provider then mirrors the active palette back onto that legacy key, so
+ * leaving the halves underived would lose the migration on the next load.
+ */
+export function writeThemePairCookies(pair: ThemePair, keys?: ThemePairLegacyKeys): void {
+  storage.setItem(keys?.mode ?? MODE_COOKIE, pair.mode);
+  storage.setItem(LIGHT_THEME_COOKIE, pair.light);
+  storage.setItem(DARK_THEME_COOKIE, pair.dark);
+}
+
+/**
+ * Read the persisted pair, seeding either half from the single palette older
+ * releases stored. Returns undefined only when the user has never expressed a
+ * theme preference at all — ThemeProvider reads that as "my props decide".
+ *
+ * `keys` points the two legacy reads at a host's own storage keys so an
+ * upgrade migrates that host's stored preference instead of discarding it.
+ */
+export function readThemePairCookies(keys?: ThemePairLegacyKeys): ThemePair | undefined {
+  const mode = storage.getItem(keys?.mode ?? MODE_COOKIE);
+  const light = storage.getItem(LIGHT_THEME_COOKIE);
+  const dark = storage.getItem(DARK_THEME_COOKIE);
+  const legacy = storage.getItem(keys?.colorTheme ?? COLOR_THEME_COOKIE);
+  if (!mode && !light && !dark && !legacy) return undefined;
+  const seeded = seedThemePair(legacy, parseThemeMode(mode, getDefaultThemePair().mode));
+  return normalizeThemePair({ mode, light: light ?? seeded.light, dark: dark ?? seeded.dark }, seeded);
+}
 
 const DIFF_LINE_BG_INTENSITY_VALUES = ['subtle', 'normal', 'strong'] as const;
 function isDiffLineBgIntensity(v: unknown): v is DiffLineBgIntensity {
@@ -28,6 +91,7 @@ export interface SettingDef<T> {
   toServer?: (value: T) => Record<string, unknown>;
 }
 
+/** Typed registry of persisted UI settings and their storage codecs. */
 export const SETTINGS = {
   displayName: {
     defaultValue: () => generateIdentity(),
@@ -39,6 +103,35 @@ export const SETTINGS = {
     toServer: (v: string) => ({ displayName: v }),
   },
 
+  /**
+   * Appearance: the mode plus the palette assigned to each half of the pair.
+   * Stored as one value because the three fields are only meaningful together —
+   * `mode: system` picks between `light` and `dark` at render time.
+   *
+   * Cookies: `plannotator-theme` (mode) keeps its meaning, joined by
+   * `plannotator-light-theme` / `plannotator-dark-theme`. A user arriving from
+   * an older release has neither half, so the pair is seeded from the single
+   * `plannotator-color-theme` palette they were on (ThemeProvider keeps writing
+   * that key, so a downgrade still finds a palette and never renders unstyled).
+   *
+   * Server: round-trips through `theme` in ~/.plannotator/config.json exactly
+   * like `diffOptions` does, so the choice survives the random port each hook
+   * invocation runs on.
+   */
+  themePair: {
+    defaultValue: () => getDefaultThemePair(),
+    fromCookie: () => readThemePairCookies(),
+    toCookie: (v: ThemePair) => writeThemePairCookies(v),
+    serverKey: 'theme',
+    fromServer: (sc: Record<string, unknown>) => {
+      const theme = sc.theme as Record<string, unknown> | undefined;
+      if (!theme || typeof theme !== 'object') return undefined;
+      if (theme.mode === undefined && theme.light === undefined && theme.dark === undefined) return undefined;
+      return normalizeThemePair(theme, getDefaultThemePair());
+    },
+    toServer: (v: ThemePair) => ({ theme: { mode: v.mode, light: v.light, dark: v.dark } }),
+  },
+
   gridEnabled: {
     // Default ON: plans open in the classic grid / floating-card look. The UI 2.0
     // flat look is offered as an opt-in via the look-and-feel chooser dialog.
@@ -51,6 +144,46 @@ export const SETTINGS = {
     serverKey: undefined, fromServer: undefined, toServer: undefined,
   },
 
+  vimModeEnabled: {
+    // Vim bindings deliberately default OFF. Unmodified letter keys must remain
+    // inert for existing users until they explicitly opt into modal document
+    // navigation from Settings > Vim.
+    defaultValue: false as boolean,
+    fromCookie: () => {
+      const value = storage.getItem('plannotator-vim-mode-enabled');
+      return value === 'true' ? true : value === 'false' ? false : undefined;
+    },
+    toCookie: (value: boolean) =>
+      storage.setItem('plannotator-vim-mode-enabled', String(value)),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
+  vimHudEnabled: {
+    // The larger command HUD is an optional presentation layer on top of Vim
+    // controls. It has no effect while Vim mode itself is disabled.
+    defaultValue: false as boolean,
+    fromCookie: () => {
+      const value = storage.getItem('plannotator-vim-hud-enabled');
+      return value === 'true' ? true : value === 'false' ? false : undefined;
+    },
+    toCookie: (value: boolean) =>
+      storage.setItem('plannotator-vim-hud-enabled', String(value)),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
+  vimHudKeyPanelEnabled: {
+    // Preserve the existing full HUD for current users while allowing the
+    // bottom-right key panel to be hidden independently from the reticle.
+    defaultValue: true as boolean,
+    fromCookie: () => {
+      const value = storage.getItem('plannotator-vim-hud-key-panel-enabled');
+      return value === 'true' ? true : value === 'false' ? false : undefined;
+    },
+    toCookie: (value: boolean) =>
+      storage.setItem('plannotator-vim-hud-key-panel-enabled', String(value)),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
   // --- Diff display options (namespaced under diffOptions in config.json) ---
 
   // Which left-panel view a code review OPENS in. 'sections' = the git-status
@@ -262,6 +395,25 @@ export const SETTINGS = {
     },
     toServer: (v: DiffLineBgIntensity) => ({ diffOptions: { lineBgIntensity: v } }),
   },
+  /** Experimental: author suggestions by editing code in place in the review
+   *  all-files view. Cookie-only (no server sync) while the feature is
+   *  experimental — default OFF, and when off no edit UI renders and no
+   *  editor is ever constructed. (In code-split hosts the editor chunk is
+   *  never fetched; Plannotator's single-file production build inlines all
+   *  dynamic imports, so there the module namespace exists at page load —
+   *  audited free of top-level side effects — but stays inert.) */
+  editSuggestions: {
+    defaultValue: false as boolean,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-experimental-edit-suggestions');
+      return v === 'true' ? true : v === 'false' ? false : undefined;
+    },
+    toCookie: (v: boolean) =>
+      storage.setItem('plannotator-experimental-edit-suggestions', String(v)),
+    serverKey: undefined,
+    fromServer: undefined,
+    toServer: undefined,
+  },
   conventionalComments: {
     defaultValue: false as boolean,
     fromCookie: () => {

package/configure.ts

@@ -7,6 +7,7 @@ import { setFileTreeBackend, type FileTreeBackend } from './hooks/useFileBrowser
 import { setDraftTransport, type DraftTransport } from './hooks/useAnnotationDraft';
 import { setExternalAnnotationTransport, type ExternalAnnotationTransport } from './hooks/useExternalAnnotations';
 import { setAITransport, type AITransport } from './hooks/useAIChat';
+import { setSkillCatalogTransport, setSkillContentTransport, type SkillCatalogTransport, type SkillContentTransport } from './utils/skillCatalog';
 import { configStore } from './config';
 import type { ServerSyncFn } from './config/configStore';
 import type { ExternalAnnotationEvent, VaultNode } from './types';
@@ -27,6 +28,8 @@ export type {
   ExternalAnnotationTransport,
   ExternalAnnotationEvent,
   AITransport,
+  SkillCatalogTransport,
+  SkillContentTransport,
   ServerSyncFn,
 };
 
@@ -48,6 +51,10 @@ export interface PlannotatorUIConfig {
    */
   externalAnnotationTransport?: ExternalAnnotationTransport<ExternalAnnotationBase>;
   aiTransport?: AITransport;
+  /** Skill-reference catalog request. Default: `GET /api/skills` on the page origin. */
+  skillCatalogTransport?: SkillCatalogTransport;
+  /** Human-only skill contents request for feedback injection. Default: `GET /api/skills/content?name=` on the page origin. */
+  skillContentTransport?: SkillContentTransport;
   serverSync?: ServerSyncFn;
   /** Re-hydrate settings from the installed (SYNCHRONOUS) storageBackend after install. */
   loadSettingsFromBackend?: boolean;
@@ -63,6 +70,8 @@ export function configurePlannotatorUI(config: PlannotatorUIConfig): void {
   if (config.draftTransport) setDraftTransport(config.draftTransport);
   if (config.externalAnnotationTransport) setExternalAnnotationTransport(config.externalAnnotationTransport);
   if (config.aiTransport) setAITransport(config.aiTransport);
+  if (config.skillCatalogTransport) setSkillCatalogTransport(config.skillCatalogTransport);
+  if (config.skillContentTransport) setSkillContentTransport(config.skillContentTransport);
   if (config.serverSync) configStore.setServerSync(config.serverSync);
   // Re-hydrate AFTER storageBackend is installed (load-bearing order — gated last).
   if (config.loadSettingsFromBackend) configStore.loadFromBackend();

package/globals.d.ts

@@ -1,4 +1,4 @@
-// Allow side-effect CSS imports (highlight.js themes, overlayscrollbars, etc.)
+// Allow side-effect CSS imports (overlayscrollbars, fontsource, etc.)
 declare module '*.css';
 
 // Image asset imports (sprites, screenshots). Consumers compiling this shipped
@@ -12,3 +12,9 @@ declare module '*.webp' {
   const src: string;
   export default src;
 }
+// Video asset imports (announcement demo recordings). Inlined as data URIs by
+// the single-file build (assetsInlineLimit), so the import resolves to a string.
+declare module '*.webm' {
+  const src: string;
+  export default src;
+}

package/hooks/useAIChat.ts

@@ -224,6 +224,7 @@ export function useAIChat({
   }, []);
 
   const setSessionId = useCallback((sessionId: string | null) => {
+    sessionIdRef.current = sessionId;
     setThread(prev => ({ ...prev, sessionId }));
   }, []);
 
@@ -486,11 +487,12 @@ export function useAIChat({
     if (abortRef.current) {
       abortRef.current.abort();
       abortRef.current = null;
+      pendingAbortRef.current = postServerAbort();
     }
     setSessionId(null);
     setIsCreatingSession(false);
     setIsStreaming(false);
-  }, [setSessionId]);
+  }, [postServerAbort, setSessionId]);
 
   const resetThread = useCallback(() => {
     sessionEpochRef.current += 1;
@@ -498,12 +500,13 @@ export function useAIChat({
     if (abortRef.current) {
       abortRef.current.abort();
       abortRef.current = null;
+      pendingAbortRef.current = postServerAbort();
     }
     setThread(createThread(threadTitle));
     setIsCreatingSession(false);
     setIsStreaming(false);
     setError(null);
-  }, [threadTitle]);
+  }, [postServerAbort, threadTitle]);
 
   useEffect(() => {
     return () => {

package/hooks/useAIProviderActivation.ts

@@ -0,0 +1,47 @@
+import { useCallback, useRef } from 'react';
+import type { AIProviderOption } from '../utils/aiProvider';
+
+/**
+ * Explicit AI provider activation for lazily-initialized providers.
+ *
+ * Codex model discovery is deferred until a session starts (it spawns a
+ * `codex app-server` process — see #1144), so /api/ai/capabilities advertises
+ * static fallback metadata until then. This hook lets the apps run that same
+ * deferred initializer on an explicit user gesture — opening the Ask AI
+ * surface, or switching the provider picker — via
+ * `GET /api/ai/capabilities?activate=<providerId>`, then merge the refreshed
+ * provider metadata (real model list + reasoning efforts) back into app state.
+ *
+ * Single-flight per provider id: repeated gestures don't re-fetch (activation
+ * is idempotent server-side anyway), but a failed fetch un-latches so a later
+ * gesture can retry. Providers without deferred initialization are a server-side
+ * no-op, so callers don't need to know which providers are lazy.
+ */
+export interface ActivatedAIProvider extends AIProviderOption {
+  capabilities: Record<string, boolean>;
+}
+
+export function useAIProviderActivation(options: {
+  onCapabilities: (providers: ActivatedAIProvider[], defaultProvider: string | null) => void;
+}) {
+  const activatedRef = useRef<Set<string>>(new Set());
+  const onCapabilitiesRef = useRef(options.onCapabilities);
+  onCapabilitiesRef.current = options.onCapabilities;
+
+  return useCallback((providerId: string | null | undefined) => {
+    if (!providerId || activatedRef.current.has(providerId)) return;
+    activatedRef.current.add(providerId);
+    fetch(`/api/ai/capabilities?activate=${encodeURIComponent(providerId)}`)
+      .then(res => (res.ok ? res.json() : null))
+      .then(data => {
+        if (!data?.available) {
+          activatedRef.current.delete(providerId);
+          return;
+        }
+        onCapabilitiesRef.current(data.providers ?? [], data.defaultProvider ?? null);
+      })
+      .catch(() => {
+        activatedRef.current.delete(providerId);
+      });
+  }, []);
+}

package/hooks/useAIProviderConfig.ts

@@ -99,9 +99,13 @@ export function useAIProviderConfig({
         }
         const reasoningEffort = model ? (reasoningEffortByModel[model] ?? null) : null;
         const next = { ...prev, providerId, model, reasoningEffort, reasoningEffortByModel };
+        // Only an explicit model pick is persisted. A resolver-derived model
+        // (e.g. the static fallback a lazily-discovered provider advertises
+        // before activation) must never overwrite the user's saved preference
+        // — the session request may fall back, the cookie may not.
         saveAIProviderSelection({
           providerId: next.providerId,
-          model: next.model,
+          model: config.model !== undefined ? next.model : null,
           origin,
           settings: saved,
         });