@plannotator/ui 0.22.0

package/config/configStore.ts

@@ -0,0 +1,214 @@
+/**
+ * ConfigStore — Unified config resolver for Plannotator
+ *
+ * Singleton that resolves settings with precedence:
+ *   server config file > cookie > default
+ *
+ * Works both inside and outside React. React components subscribe
+ * via useSyncExternalStore (see useConfig.ts).
+ *
+ * Server-synced settings automatically write back to ~/.plannotator/config.json
+ * via a debounced POST /api/config.
+ */
+
+import { SETTINGS, type SettingName, type SettingsMap } from './settings';
+
+type Listener = () => void;
+
+/** Deep-merge source into target, recursing into plain objects. */
+function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const key of Object.keys(source)) {
+    if (
+      typeof target[key] === 'object' && target[key] !== null && !Array.isArray(target[key]) &&
+      typeof source[key] === 'object' && source[key] !== null && !Array.isArray(source[key])
+    ) {
+      deepMerge(target[key] as Record<string, unknown>, source[key] as Record<string, unknown>);
+    } else {
+      target[key] = source[key];
+    }
+  }
+}
+
+/** Server write-back transport: posts a batch of changed server-synced settings. */
+export type ServerSyncFn = (payload: Record<string, unknown>) => void;
+
+/** Default = today's inline POST /api/config (best-effort).
+    keepalive lets the request outlive page teardown (pagehide flush). */
+const defaultServerSync: ServerSyncFn = (payload) => {
+  fetch('/api/config', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+    keepalive: true,
+  }).catch(() => {}); // best-effort
+};
+
+/** Infer the value type from a SettingDef */
+type SettingValue<K extends SettingName> = SettingsMap[K] extends { defaultValue: infer D }
+  ? D extends (...args: unknown[]) => infer R ? R : D
+  : never;
+
+class ConfigStore {
+  private values = new Map<string, unknown>();
+  private listeners = new Set<Listener>();
+  private version = 0;
+  private pendingServerWrites: Record<string, unknown> = {};
+  private serverSyncTimer: ReturnType<typeof setTimeout> | null = null;
+  private pagehideFlushRegistered = false;
+  private serverSync: ServerSyncFn = defaultServerSync;
+  private loaded = false;
+
+  /**
+   * Resolve all settings from the LIVE storage backend (cookie > default) on
+   * first use — deliberately not in the constructor. The singleton is created
+   * at module import, which for a host app is before configurePlannotatorUI()
+   * can install its StorageBackend; resolving eagerly there would write every
+   * missing default (including a generated identity) as cookies onto the host's
+   * origin. Deferring to first use means a host that configures at startup gets
+   * its own backend for the initial resolution too — no cookies are ever
+   * written on a configured host. Plannotator is unchanged: same resolution,
+   * same default-seeding writes, on first settings access instead of at import.
+   */
+  private ensureLoaded(): void {
+    if (this.loaded) return;
+    this.loaded = true;
+    for (const [name, def] of Object.entries(SETTINGS)) {
+      const fromCookie = def.fromCookie();
+      const defaultVal = typeof def.defaultValue === 'function'
+        ? (def.defaultValue as () => unknown)()
+        : def.defaultValue;
+      const resolved = fromCookie ?? defaultVal;
+      this.values.set(name, resolved);
+      // Persist generated defaults to cookie so the value is stable across calls
+      if (fromCookie === undefined) {
+        def.toCookie(resolved as never);
+      }
+    }
+  }
+
+  /**
+   * Re-hydrate all settings from the currently installed StorageBackend.
+   * ADDITIVE host hook — Plannotator never calls this (eager cookie default unchanged).
+   * Host installs a SYNCHRONOUS StorageBackend serving prefetched settings, then calls
+   * this to route the initial load through that backend. Precedence after a host call:
+   * server (init) > host backend (loadFromBackend) > cookie/default (constructor).
+   * Call this BEFORE init(serverConfig): init() always wins, so calling loadFromBackend()
+   * after init() would silently overwrite server-supplied settings.
+   */
+  loadFromBackend(): void {
+    this.ensureLoaded();
+    for (const [name, def] of Object.entries(SETTINGS)) {
+      const fromBackend = def.fromCookie();
+      if (fromBackend !== undefined) {
+        this.values.set(name, fromBackend);
+      } else {
+        // Seed the host backend with the resolved default. This matters when
+        // the store was already resolved BEFORE the host installed its
+        // StorageBackend (e.g. something read a setting pre-configure): those
+        // default-seeding writes went to the earlier backend, not this one.
+        // Without this, a fresh host store is never populated, so generated
+        // defaults (e.g. displayName) regenerate on every reload. In the normal
+        // configure-at-startup flow ensureLoaded() above already resolved
+        // through the host backend and this loop is a no-op re-read.
+        def.toCookie(this.values.get(name) as never);
+      }
+    }
+    this.notify();
+  }
+
+  /**
+   * Apply server config overrides.
+   * Call once after fetching /api/plan or /api/diff.
+   *
+   * Server values take precedence over the cookie/default already resolved
+   * by the constructor. Settings without a server value are left untouched.
+   */
+  init(serverConfig?: Record<string, unknown>): void {
+    this.ensureLoaded();
+    if (serverConfig) {
+      for (const [name, def] of Object.entries(SETTINGS)) {
+        if (def.serverKey && def.fromServer) {
+          const fromServer = def.fromServer(serverConfig);
+          if (fromServer !== undefined) {
+            this.values.set(name, fromServer);
+            def.toCookie(fromServer as never);
+          }
+        }
+      }
+    }
+    this.notify();
+  }
+
+  /** Get a resolved config value. Works outside React. */
+  get<K extends SettingName>(key: K): SettingValue<K> {
+    this.ensureLoaded();
+    return this.values.get(key) as SettingValue<K>;
+  }
+
+  /** Set a config value. Writes cookie (sync), queues server write-back if applicable. */
+  set<K extends SettingName>(key: K, value: SettingValue<K>): void {
+    this.ensureLoaded();
+    const def = SETTINGS[key];
+    this.values.set(key, value);
+    def.toCookie(value as never);
+
+    if (def.serverKey && def.toServer) {
+      deepMerge(this.pendingServerWrites, def.toServer(value as never) as Record<string, unknown>);
+      this.scheduleServerSync();
+    }
+
+    this.notify();
+  }
+
+  /** Subscribe to changes. Returns unsubscribe function. */
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Override the server write-back transport (default = inline POST /api/config). */
+  setServerSync(fn: ServerSyncFn): void {
+    this.serverSync = fn;
+  }
+
+  resetServerSync(): void { this.serverSync = defaultServerSync; }
+
+  private notify(): void {
+    this.version++;
+    for (const fn of this.listeners) fn();
+  }
+
+  private scheduleServerSync(): void {
+    // The debounce loses writes when the page goes away within 300ms — and
+    // review/plan sessions end abruptly (approve/feedback shuts the server
+    // down right after a settings change). A lost write leaves the cookie and
+    // ~/.plannotator/config.json disagreeing; on the next session init() then
+    // "restores" the stale server value over the cookie. Flush on pagehide so
+    // the two stores can't diverge this way.
+    if (!this.pagehideFlushRegistered && typeof window !== 'undefined') {
+      this.pagehideFlushRegistered = true;
+      window.addEventListener('pagehide', () => this.flushServerSync());
+    }
+    if (this.serverSyncTimer) clearTimeout(this.serverSyncTimer);
+    this.serverSyncTimer = setTimeout(() => this.flushServerSync(), 300);
+  }
+
+  private flushServerSync(): void {
+    if (this.serverSyncTimer) {
+      clearTimeout(this.serverSyncTimer);
+      this.serverSyncTimer = null;
+    }
+    if (Object.keys(this.pendingServerWrites).length === 0) return;
+    const payload = { ...this.pendingServerWrites };
+    this.pendingServerWrites = {};
+    this.serverSync(payload);
+  }
+}
+
+export const configStore = new ConfigStore();
+export type { SettingValue };
+
+/** @internal Exported for tests only — lets the lazy-resolution contract be
+    verified on a fresh instance without depending on module-graph isolation
+    (the singleton may already be resolved by the time a given test file runs). */
+export { ConfigStore as ConfigStoreForTest };

package/config/index.ts

@@ -0,0 +1,4 @@
+export { configStore } from './configStore';
+export type { ServerSyncFn } from './configStore';
+export { useConfigValue } from './useConfig';
+export { setReviewPanelView, setReviewDefaultDiffType, type ReviewDefaultDiffType } from './reviewView';

package/config/reviewView.ts

@@ -0,0 +1,42 @@
+import { configStore } from './configStore';
+
+/**
+ * The ONLY writers for the coupled setting pair (reviewPanelView,
+ * defaultDiffType).
+ *
+ * Invariant: the Sections (Git status) view can only render the since-base
+ * diff. So:
+ *   - choosing the sections view forces defaultDiffType = 'since-base'
+ *   - choosing a non-since-base default diff snaps the view to 'tree'
+ *   - tree + since-base IS valid — switching to Tree leaves the diff, and
+ *     choosing since-base leaves the view
+ *
+ * Hand-mirroring these rules at call sites is how the split-brain bug
+ * happened (a writer persisted one half of the pair; configStore.init()
+ * then re-corrupted it from the server every session). Never write either
+ * setting directly — always go through these setters. configStore.init()
+ * remains the one non-writer that can produce a conflicted pair from a
+ * stale config.json; the App-level load reconciler heals that case by
+ * calling setReviewPanelView('sections').
+ */
+export function setReviewPanelView(view: 'sections' | 'tree'): void {
+  configStore.set('reviewPanelView', view);
+  if (view === 'sections' && configStore.get('defaultDiffType') !== 'since-base') {
+    configStore.set('defaultDiffType', 'since-base');
+  }
+}
+
+export type ReviewDefaultDiffType =
+  | 'since-base'
+  | 'uncommitted'
+  | 'unstaged'
+  | 'staged'
+  | 'merge-base'
+  | 'all';
+
+export function setReviewDefaultDiffType(value: ReviewDefaultDiffType): void {
+  configStore.set('defaultDiffType', value);
+  if (value !== 'since-base' && configStore.get('reviewPanelView') !== 'tree') {
+    configStore.set('reviewPanelView', 'tree');
+  }
+}

package/config/settings.ts

@@ -0,0 +1,310 @@
+/**
+ * Settings registry — declares all config settings and their resolution rules.
+ *
+ * Each SettingDef describes:
+ *   - defaultValue: fallback (can be a lazy factory for expensive defaults)
+ *   - fromCookie/toCookie: serialization to/from cookie storage
+ *   - serverKey + fromServer/toServer: opt-in sync to ~/.plannotator/config.json
+ *
+ * Add new settings here. Cookie-only settings omit serverKey.
+ */
+
+import type { DiffLineBgIntensity } from '@plannotator/core/config-types';
+import { storage } from '../utils/storage';
+import { generateIdentity } from '../utils/generateIdentity';
+
+const DIFF_LINE_BG_INTENSITY_VALUES = ['subtle', 'normal', 'strong'] as const;
+function isDiffLineBgIntensity(v: unknown): v is DiffLineBgIntensity {
+  return typeof v === 'string' && (DIFF_LINE_BG_INTENSITY_VALUES as readonly string[]).includes(v);
+}
+
+export interface SettingDef<T> {
+  defaultValue: T | (() => T);
+  fromCookie: () => T | undefined;
+  toCookie: (value: T) => void;
+  /** If set, this setting syncs to server via POST /api/config */
+  serverKey?: string;
+  fromServer?: (serverConfig: Record<string, unknown>) => T | undefined;
+  toServer?: (value: T) => Record<string, unknown>;
+}
+
+export const SETTINGS = {
+  displayName: {
+    defaultValue: () => generateIdentity(),
+    fromCookie: () => storage.getItem('plannotator-identity') || undefined,
+    toCookie: (v: string) => storage.setItem('plannotator-identity', v),
+    serverKey: 'displayName',
+    fromServer: (sc: Record<string, unknown>) =>
+      typeof sc.displayName === 'string' && sc.displayName ? sc.displayName : undefined,
+    toServer: (v: string) => ({ displayName: v }),
+  },
+
+  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.
+    defaultValue: true as boolean,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-grid-enabled');
+      return v === 'true' ? true : v === 'false' ? false : undefined;
+    },
+    toCookie: (v: boolean) => storage.setItem('plannotator-grid-enabled', String(v)),
+    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
+  // view (Committed/Changes/Untracked); 'tree' = the classic file tree.
+  // Cookie-only. Written ONLY by Settings and the first-run setup dialog —
+  // the in-review header toggle is session-scoped and never writes this
+  // (looking at another view mid-review must not silently change the default).
+  //
+  // Deliberately NOT a value here: 'commits'. The Commits view is session-only
+  // and never the opening view — a review always opens on files. A
+  // previously-persisted 'commits' cookie is treated as unset.
+  reviewPanelView: {
+    defaultValue: 'sections' as 'sections' | 'tree',
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-review-panel-view');
+      return v === 'tree' || v === 'sections' ? v : undefined;
+    },
+    toCookie: (v: string) => storage.setItem('plannotator-review-panel-view', v),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
+  defaultDiffType: {
+    defaultValue: 'since-base' as 'since-base' | 'uncommitted' | 'unstaged' | 'staged' | 'merge-base' | 'all',
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-default-diff-type');
+      if (v === 'branch') return 'merge-base' as const;
+      return v === 'since-base' || v === 'uncommitted' || v === 'unstaged' || v === 'staged' || v === 'merge-base' || v === 'all' ? v : undefined;
+    },
+    toCookie: (v: string) => storage.setItem('plannotator-default-diff-type', v),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.defaultDiffType;
+      if (v === 'branch') return 'merge-base' as const;
+      return v === 'since-base' || v === 'uncommitted' || v === 'unstaged' || v === 'staged' || v === 'merge-base' || v === 'all' ? v : undefined;
+    },
+    toServer: (v: string) => ({ diffOptions: { defaultDiffType: v } }),
+  },
+
+  diffStyle: {
+    defaultValue: 'split' as 'split' | 'unified',
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-diff-style') ?? storage.getItem('review-diff-style');
+      return v === 'split' || v === 'unified' ? v : undefined;
+    },
+    toCookie: (v: string) => storage.setItem('plannotator-diff-style', v),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.diffStyle;
+      return v === 'split' || v === 'unified' ? v : undefined;
+    },
+    toServer: (v: string) => ({ diffOptions: { diffStyle: v } }),
+  },
+
+  diffOverflow: {
+    defaultValue: 'scroll' as 'scroll' | 'wrap',
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-diff-overflow');
+      return v === 'scroll' || v === 'wrap' ? v : undefined;
+    },
+    toCookie: (v: string) => storage.setItem('plannotator-diff-overflow', v),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.overflow;
+      return v === 'scroll' || v === 'wrap' ? v : undefined;
+    },
+    toServer: (v: string) => ({ diffOptions: { overflow: v } }),
+  },
+
+  diffIndicators: {
+    defaultValue: 'bars' as 'bars' | 'classic' | 'none',
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-diff-indicators');
+      return v === 'bars' || v === 'classic' || v === 'none' ? v : undefined;
+    },
+    toCookie: (v: string) => storage.setItem('plannotator-diff-indicators', v),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.diffIndicators;
+      return v === 'bars' || v === 'classic' || v === 'none' ? v : undefined;
+    },
+    toServer: (v: string) => ({ diffOptions: { diffIndicators: v } }),
+  },
+
+  diffLineDiffType: {
+    defaultValue: 'word-alt' as 'word-alt' | 'word' | 'char' | 'none',
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-diff-line-diff-type');
+      return v === 'word-alt' || v === 'word' || v === 'char' || v === 'none' ? v : undefined;
+    },
+    toCookie: (v: string) => storage.setItem('plannotator-diff-line-diff-type', v),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.lineDiffType;
+      return v === 'word-alt' || v === 'word' || v === 'char' || v === 'none' ? v : undefined;
+    },
+    toServer: (v: string) => ({ diffOptions: { lineDiffType: v } }),
+  },
+
+  diffShowLineNumbers: {
+    defaultValue: true as boolean,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-diff-show-line-numbers');
+      return v === 'true' ? true : v === 'false' ? false : undefined;
+    },
+    toCookie: (v: boolean) => storage.setItem('plannotator-diff-show-line-numbers', String(v)),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.showLineNumbers;
+      return typeof v === 'boolean' ? v : undefined;
+    },
+    toServer: (v: boolean) => ({ diffOptions: { showLineNumbers: v } }),
+  },
+
+  diffShowBackground: {
+    defaultValue: true as boolean,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-diff-show-background');
+      return v === 'true' ? true : v === 'false' ? false : undefined;
+    },
+    toCookie: (v: boolean) => storage.setItem('plannotator-diff-show-background', String(v)),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.showDiffBackground;
+      return typeof v === 'boolean' ? v : undefined;
+    },
+    toServer: (v: boolean) => ({ diffOptions: { showDiffBackground: v } }),
+  },
+
+  diffFontFamily: {
+    defaultValue: '' as string, // empty = theme default
+    fromCookie: () => storage.getItem('plannotator-diff-font-family') || undefined,
+    toCookie: (v: string) => storage.setItem('plannotator-diff-font-family', v),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.fontFamily;
+      return typeof v === 'string' ? v : undefined;
+    },
+    toServer: (v: string) => ({ diffOptions: { fontFamily: v } }),
+  },
+
+  diffHideWhitespace: {
+    defaultValue: false as boolean,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-diff-hide-whitespace');
+      return v === 'true' ? true : v === 'false' ? false : undefined;
+    },
+    toCookie: (v: boolean) => storage.setItem('plannotator-diff-hide-whitespace', String(v)),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.hideWhitespace;
+      return typeof v === 'boolean' ? v : undefined;
+    },
+    toServer: (v: boolean) => ({ diffOptions: { hideWhitespace: v } }),
+  },
+
+  diffExpandUnchanged: {
+    defaultValue: false as boolean,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-diff-expand-unchanged');
+      return v === 'true' ? true : v === 'false' ? false : undefined;
+    },
+    toCookie: (v: boolean) => storage.setItem('plannotator-diff-expand-unchanged', String(v)),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.expandUnchanged;
+      return typeof v === 'boolean' ? v : undefined;
+    },
+    toServer: (v: boolean) => ({ diffOptions: { expandUnchanged: v } }),
+  },
+
+  diffFontSize: {
+    defaultValue: '' as string, // empty = theme default
+    fromCookie: () => storage.getItem('plannotator-diff-font-size') || undefined,
+    toCookie: (v: string) => storage.setItem('plannotator-diff-font-size', v),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.fontSize;
+      return typeof v === 'string' ? v : undefined;
+    },
+    toServer: (v: string) => ({ diffOptions: { fontSize: v } }),
+  },
+  diffTabSize: {
+    defaultValue: 2 as number,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-diff-tab-size');
+      const n = v ? parseInt(v, 10) : NaN;
+      return Number.isFinite(n) && n >= 1 && n <= 8 ? n : undefined;
+    },
+    toCookie: (v: number) => storage.setItem('plannotator-diff-tab-size', String(v)),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.tabSize;
+      return typeof v === 'number' && v >= 1 && v <= 8 ? v : undefined;
+    },
+    toServer: (v: number) => ({ diffOptions: { tabSize: v } }),
+  },
+  diffLineBgIntensity: {
+    defaultValue: 'subtle' as DiffLineBgIntensity,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-diff-line-bg-intensity');
+      return isDiffLineBgIntensity(v) ? v : undefined;
+    },
+    toCookie: (v: DiffLineBgIntensity) =>
+      storage.setItem('plannotator-diff-line-bg-intensity', v),
+    serverKey: 'diffOptions',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = (sc.diffOptions as Record<string, unknown> | undefined)?.lineBgIntensity;
+      return isDiffLineBgIntensity(v) ? v : undefined;
+    },
+    toServer: (v: DiffLineBgIntensity) => ({ diffOptions: { lineBgIntensity: v } }),
+  },
+  conventionalComments: {
+    defaultValue: false as boolean,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-conventional-comments');
+      return v === 'true' ? true : v === 'false' ? false : undefined;
+    },
+    toCookie: (v: boolean) => storage.setItem('plannotator-conventional-comments', String(v)),
+    serverKey: 'conventionalComments',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = sc.conventionalComments;
+      return typeof v === 'boolean' ? v : undefined;
+    },
+    toServer: (v: boolean) => ({ conventionalComments: v }),
+  },
+  /** JSON-serialized array of label configs, or null for defaults.
+   *  Synced to ~/.plannotator/config.json as a parsed array (not a string). */
+  conventionalLabels: {
+    defaultValue: null as string | null,
+    fromCookie: () => storage.getItem('plannotator-cc-labels') || undefined,
+    toCookie: (v: string | null) => {
+      if (v) storage.setItem('plannotator-cc-labels', v);
+      else storage.removeItem('plannotator-cc-labels');
+    },
+    serverKey: 'conventionalLabels',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = sc.conventionalLabels;
+      if (v === null) return null;
+      if (Array.isArray(v)) return JSON.stringify(v);
+      return undefined;
+    },
+    toServer: (v: string | null) => {
+      if (v === null) return { conventionalLabels: null };
+      try {
+        return { conventionalLabels: JSON.parse(v) };
+      } catch {
+        return {};
+      }
+    },
+  },
+  /* SettingDef<any>, not <unknown>: consumers compile this shipped source under
+     their own strictFunctionTypes, where a narrow `toCookie: (v: string) => void`
+     is contravariantly incompatible with `(value: unknown) => void`. */
+} satisfies Record<string, SettingDef<any>>;
+
+export type SettingsMap = typeof SETTINGS;
+export type SettingName = keyof SettingsMap;

package/config/useConfig.ts

@@ -0,0 +1,20 @@
+/**
+ * React hook for consuming ConfigStore values.
+ *
+ * Uses useSyncExternalStore for concurrent-mode-safe subscriptions
+ * to the singleton configStore — no context provider needed.
+ */
+
+import { useCallback, useSyncExternalStore } from 'react';
+import { configStore, type SettingValue } from './configStore';
+import type { SettingName } from './settings';
+
+/** Read a config value reactively. Re-renders when the store changes. */
+export function useConfigValue<K extends SettingName>(key: K): SettingValue<K> {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => configStore.subscribe(onStoreChange),
+    [],
+  );
+  const getSnapshot = useCallback(() => configStore.get(key), [key]);
+  return useSyncExternalStore(subscribe, getSnapshot);
+}

package/configure.ts

@@ -0,0 +1,69 @@
+import { setImageSrcResolver, type ImageSrcResolver } from './components/ImageThumbnail';
+import { setDocPreviewFetcher, type DocPreviewFetcher, type DocPreviewResult } from './components/InlineMarkdown';
+import { setStorageBackend, type StorageBackend } from './utils/storage';
+import { setUploadTransport, type UploadTransport, type UploadResult } from './utils/upload';
+import { setIdentityProvider, type IdentityProvider } from './utils/identity';
+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 { configStore } from './config';
+import type { ServerSyncFn } from './config/configStore';
+import type { ExternalAnnotationEvent, VaultNode } from './types';
+
+// One-stop type barrel: every seam contract a host implements is importable
+// from this module, next to configurePlannotatorUI itself.
+export type {
+  ImageSrcResolver,
+  DocPreviewFetcher,
+  DocPreviewResult,
+  StorageBackend,
+  UploadTransport,
+  UploadResult,
+  IdentityProvider,
+  FileTreeBackend,
+  VaultNode,
+  DraftTransport,
+  ExternalAnnotationTransport,
+  ExternalAnnotationEvent,
+  AITransport,
+  ServerSyncFn,
+};
+
+type ExternalAnnotationBase = { id: string; source?: string };
+
+export interface PlannotatorUIConfig {
+  imageSrcResolver?: ImageSrcResolver;
+  storageBackend?: StorageBackend;
+  uploadTransport?: UploadTransport;
+  docPreviewFetcher?: DocPreviewFetcher;
+  fileTreeBackend?: FileTreeBackend;
+  identityProvider?: IdentityProvider;
+  draftTransport?: DraftTransport;
+  /**
+   * Base-constraint transport. If your annotation type extends the base
+   * constraint ({ id: string; source?: string }) with extra fields, call
+   * setExternalAnnotationTransport<YourType>() directly for full type safety —
+   * this front-door field intentionally pins the base constraint for ergonomics.
+   */
+  externalAnnotationTransport?: ExternalAnnotationTransport<ExternalAnnotationBase>;
+  aiTransport?: AITransport;
+  serverSync?: ServerSyncFn;
+  /** Re-hydrate settings from the installed (SYNCHRONOUS) storageBackend after install. */
+  loadSettingsFromBackend?: boolean;
+}
+
+export function configurePlannotatorUI(config: PlannotatorUIConfig): void {
+  if (config.imageSrcResolver) setImageSrcResolver(config.imageSrcResolver);
+  if (config.storageBackend) setStorageBackend(config.storageBackend);
+  if (config.uploadTransport) setUploadTransport(config.uploadTransport);
+  if (config.docPreviewFetcher) setDocPreviewFetcher(config.docPreviewFetcher);
+  if (config.fileTreeBackend) setFileTreeBackend(config.fileTreeBackend);
+  if (config.identityProvider) setIdentityProvider(config.identityProvider);
+  if (config.draftTransport) setDraftTransport(config.draftTransport);
+  if (config.externalAnnotationTransport) setExternalAnnotationTransport(config.externalAnnotationTransport);
+  if (config.aiTransport) setAITransport(config.aiTransport);
+  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

@@ -0,0 +1,14 @@
+// Allow side-effect CSS imports (highlight.js themes, overlayscrollbars, etc.)
+declare module '*.css';
+
+// Image asset imports (sprites, screenshots). Consumers compiling this shipped
+// source need these ambient declarations too — each asset-importing component
+// carries a /// <reference> to this file so any program that includes it gets them.
+declare module '*.png' {
+  const src: string;
+  export default src;
+}
+declare module '*.webp' {
+  const src: string;
+  export default src;
+}