@plannotator/ui 0.22.0

package/README.md

@@ -0,0 +1,60 @@
+# @plannotator/ui
+
+Plannotator's document UI — markdown rendering, themes, the annotation editor, settings, comments, and layout — as installable building blocks. Published so a separate app (the commercial Workspaces app) can reuse the exact same experience, while Plannotator itself stays unchanged.
+
+Ships with **`@plannotator/core`**: a small, browser-safe, zero-dependency package of the pure utilities and types `ui` builds on (carved out so `ui` can be installed standalone without Plannotator's server code).
+
+## Why this exists
+
+Workspaces needs the same document experience Plannotator has — render docs, annotate, comment, theme, edit — but backed by its own infrastructure (its own storage, auth, realtime, AI). Rather than fork or rebuild, it **installs these packages and plugs in its own backend.** Plannotator passes nothing and behaves exactly as before.
+
+## How it works: host-override seams
+
+Every place the UI talks to a backend (loading a doc preview, saving settings, persisting drafts, streaming comments, listing files, calling AI, etc.) is an **optional seam** that defaults to Plannotator's behavior. A host swaps in its own implementations through **one call at startup**:
+
+```ts
+import { configurePlannotatorUI } from "@plannotator/ui/configure";
+
+configurePlannotatorUI({
+  storageBackend,              // where settings persist
+  identityProvider,           // who the current user is
+  imageSrcResolver,           // how image paths resolve to URLs
+  docPreviewFetcher,
+  fileTreeBackend,
+  draftTransport,
+  externalAnnotationTransport, // live/agent comments
+  aiTransport,
+  serverSync,
+});
+```
+
+Anything you don't pass keeps Plannotator's default. A few component-specific overrides (e.g. an "open in editor" diff action) are passed as props where you render that component.
+
+## Consuming it (e.g. from Workspaces)
+
+```bash
+npm install @plannotator/ui @plannotator/core
+```
+
+1. Call `configurePlannotatorUI({ ... })` once at startup with your backend.
+2. Import the stylesheet: `import "@plannotator/ui/styles.css";` (precompiled — no Tailwind wiring needed; if you'd rather run your own Tailwind over the package source, add `@source` globs for `@plannotator/ui`'s `components/`, `hooks/`, and `utils/` dirs in your own CSS — the package doesn't ship its build entry).
+3. **Load the fonts in your app entry** — the stylesheet references `--font-sans` / `--font-mono` but does not ship font binaries (standard for a shared UI package; your app owns font loading). Plannotator uses Inter + Geist Mono:
+   ```ts
+   import "@fontsource-variable/inter";
+   import "@fontsource-variable/geist-mono";
+   ```
+   Or provide your own fonts and set `--font-sans` / `--font-mono` to match.
+   The same policy covers math: KaTeX's stylesheet + fonts are deliberately not in `styles.css` — if you render math, load `katex/dist/katex.min.css` yourself (import, CDN tag, or self-hosted copy; see HANDOFF.md "Math rendering").
+4. Import components: `import { Viewer } from "@plannotator/ui/components/Viewer";`
+5. Build with a bundler that compiles TS/TSX (Vite + React 19 + Tailwind v4). The packages ship **source**, so your bundler compiles them — set `moduleResolution: "bundler"`, `allowImportingTsExtensions`, `jsx: "react-jsx"`.
+
+## Packages & publishing
+
+- `@plannotator/core` — pure utils + types, zero deps, browser-safe (CI enforces no `node:` imports). Published.
+- `@plannotator/ui` — React components/hooks + theme + `configure()`. Depends on `@plannotator/core` (exact-version lockstep). Published.
+- `@plannotator/shared`, `@plannotator/ai` — stay private to the monorepo; `shared` re-exports `core`'s modules via shims so Plannotator's internals are untouched.
+- Versioned in lockstep with the repo. Publish `core` then `ui`: build each tarball with **`bun pm pack`** (resolves `workspace:*` to the exact version at pack time), then **`npm publish *.tgz --provenance --access public`** — the repo's existing flow.
+
+## The one rule
+
+**Do not reimplement the document UI from scratch.** A prior from-scratch rewrite broke the app and was reverted. The supported path is always: keep these components as-is and add a seam where a host needs different backend behavior. Never delete working Plannotator code until a human has confirmed parity in the browser.

package/components/AISettingsTab.tsx

@@ -0,0 +1,145 @@
+import type React from 'react';
+import { getProviderMeta } from './ProviderIcons';
+import {
+  getAIProviderSettings,
+  resolveAIModelForProvider,
+  resolveAIProviderSelection,
+  saveAIProviderSelection,
+  savePreferredModel,
+  type AIProviderOption,
+} from '../utils/aiProvider';
+import { useState } from 'react';
+import type { Origin } from '@plannotator/core/agents';
+
+interface AIProvider extends AIProviderOption {
+  capabilities: Record<string, boolean>;
+}
+
+interface AISettingsTabProps {
+  providers: AIProvider[];
+  selectedProviderId: string | null;
+  origin?: Origin | null;
+  onProviderChange: (providerId: string | null) => void;
+}
+
+export const AISettingsTab: React.FC<AISettingsTabProps> = ({
+  providers,
+  selectedProviderId,
+  origin,
+  onProviderChange,
+}) => {
+  const settings = getAIProviderSettings();
+  const originDefault = resolveAIProviderSelection({ providers, origin, settings }).providerId;
+  const effectiveSelection = selectedProviderId ?? originDefault ?? providers[0]?.id ?? null;
+  const [preferredModels, setPreferredModels] = useState<Record<string, string>>(() =>
+    getAIProviderSettings().preferredModels
+  );
+
+  const handleSelectProvider = (providerId: string) => {
+    onProviderChange(providerId);
+    const provider = providers.find(p => p.id === providerId) ?? null;
+    const model = resolveAIModelForProvider(provider, getAIProviderSettings().preferredModels);
+    saveAIProviderSelection({ providerId, model, origin });
+  };
+
+  const handleModelChange = (providerId: string, modelId: string) => {
+    savePreferredModel(providerId, modelId);
+    setPreferredModels(prev => ({ ...prev, [providerId]: modelId }));
+  };
+
+  if (providers.length === 0) {
+    return (
+      <>
+        <div>
+          <div className="text-sm font-medium">AI Provider</div>
+        </div>
+        <div className="flex items-start gap-2 p-3 bg-amber-500/10 border border-amber-500/30 rounded-lg text-xs text-amber-600 dark:text-amber-400">
+          <svg className="w-4 h-4 flex-shrink-0 mt-0.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+            <path strokeLinecap="round" strokeLinejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
+          </svg>
+          <span>No AI providers detected. Install the <strong>claude</strong> or <strong>codex</strong> CLI and make sure you're authenticated. <a href="https://plannotator.ai/docs/guides/ai-features/" target="_blank" rel="noopener noreferrer" className="underline hover:text-amber-700 dark:hover:text-amber-300">Setup guide</a></span>
+        </div>
+      </>
+    );
+  }
+
+  return (
+    <>
+      <div>
+        <div className="text-sm font-medium">AI Provider</div>
+        <div className="text-xs text-muted-foreground">
+          Choose which AI provider and model to use for inline chat
+        </div>
+      </div>
+
+      <div className="space-y-2">
+        {providers.map((p) => {
+          const meta = getProviderMeta(p.name);
+          const Icon = meta.icon;
+          const isSelected = effectiveSelection === p.id;
+          const models = p.models ?? [];
+          const defaultModel = models.find(m => m.default) ?? models[0];
+          const selectedModel = preferredModels[p.id] ?? defaultModel?.id ?? null;
+
+          return (
+            <div key={p.id}>
+              <button
+                type="button"
+                onClick={() => handleSelectProvider(p.id)}
+                className={`w-full flex items-center gap-3 p-3 rounded-lg border transition-colors text-left ${
+                  isSelected
+                    ? 'border-primary bg-primary/5'
+                    : 'border-border hover:border-muted-foreground/30 hover:bg-muted/50'
+                } ${models.length > 1 && isSelected ? 'rounded-b-none border-b-0' : ''}`}
+              >
+                <div className="w-6 h-6 rounded-md bg-muted flex items-center justify-center text-muted-foreground">
+                  <Icon className="w-4 h-4" />
+                </div>
+                <div className="flex-1 min-w-0">
+                  <div className="text-sm font-medium">{meta.label}</div>
+                </div>
+                {isSelected && (
+                  <svg className="w-4 h-4 text-primary flex-shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
+                  </svg>
+                )}
+              </button>
+
+              {/* Model selector — shown for selected provider when models available */}
+              {isSelected && models.length > 1 && (
+                <div className="border border-t-0 border-primary bg-primary/5 rounded-b-lg px-3 pb-3 pt-1">
+                  <label className="flex items-center gap-2">
+                    <span className="text-[11px] text-muted-foreground">Model</span>
+                    <select
+                      value={selectedModel ?? ''}
+                      onChange={(e) => handleModelChange(p.id, e.target.value)}
+                      className="flex-1 text-xs bg-muted rounded px-2 py-1 focus:outline-none focus:ring-1 focus:ring-primary/50 cursor-pointer"
+                    >
+                      {models.map(m => (
+                        <option key={m.id} value={m.id}>{m.label}</option>
+                      ))}
+                    </select>
+                  </label>
+                </div>
+              )}
+
+              {/* Show current model as muted text for unselected providers */}
+              {!isSelected && models.length > 0 && (
+                <div className="px-3 -mt-0.5">
+                  <span className="text-[10px] text-muted-foreground/50">
+                    {models.find(m => m.id === (preferredModels[p.id] ?? defaultModel?.id))?.label ?? defaultModel?.label}
+                  </span>
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+
+      <div className="text-[10px] text-muted-foreground/70">
+        Providers are detected from installed CLI tools. No API keys are managed by Plannotator — you must be authenticated with each CLI independently.{' '}
+        <a href="https://plannotator.ai/docs/guides/ai-features/" target="_blank" rel="noopener noreferrer" className="text-primary hover:underline">Learn more</a>
+      </div>
+    </>
+  );
+};

package/components/ActionMenu.tsx

@@ -0,0 +1,101 @@
+import React, { useEffect, useRef, useState } from 'react';
+
+interface ActionMenuProps {
+  className?: string;
+  panelClassName?: string;
+  renderTrigger: (props: {
+    isOpen: boolean;
+    toggleMenu: () => void;
+  }) => React.ReactNode;
+  children: (props: { closeMenu: () => void }) => React.ReactNode;
+}
+
+export const ActionMenu: React.FC<ActionMenuProps> = ({
+  className,
+  panelClassName,
+  renderTrigger,
+  children,
+}) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handlePointerDown = (event: PointerEvent) => {
+      if (menuRef.current && !menuRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        setIsOpen(false);
+      }
+    };
+
+    document.addEventListener('pointerdown', handlePointerDown);
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('pointerdown', handlePointerDown);
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [isOpen]);
+
+  return (
+    <div ref={menuRef} className={className ? `relative ${className}` : 'relative'}>
+      {renderTrigger({
+        isOpen,
+        toggleMenu: () => setIsOpen(open => !open),
+      })}
+
+      {isOpen && (
+        <div className={panelClassName ?? 'absolute top-full right-0 mt-1 w-56 rounded-lg border border-border bg-popover py-1 shadow-xl z-[70]'}>
+          {children({ closeMenu: () => setIsOpen(false) })}
+        </div>
+      )}
+    </div>
+  );
+};
+
+interface ActionMenuItemProps {
+  onClick: () => void;
+  icon: React.ReactNode;
+  label: string;
+  subtitle?: string;
+  badge?: React.ReactNode;
+}
+
+export const ActionMenuItem: React.FC<ActionMenuItemProps> = ({
+  onClick,
+  icon,
+  label,
+  subtitle,
+  badge,
+}) => (
+  <button
+    onClick={onClick}
+    className="flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors hover:bg-muted"
+  >
+    <span className="text-muted-foreground">{icon}</span>
+    {subtitle ? (
+      <span className="flex flex-1 flex-col gap-0.5">
+        <span>{label}</span>
+        <span className="text-[10px] text-muted-foreground">{subtitle}</span>
+      </span>
+    ) : (
+      <span className="flex-1">{label}</span>
+    )}
+    {badge}
+  </button>
+);
+
+export const ActionMenuDivider: React.FC = () => (
+  <div className="my-1 border-t border-border" />
+);
+
+export const ActionMenuSectionLabel: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+  <div className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+    {children}
+  </div>
+);

package/components/AgentControls.tsx

@@ -0,0 +1,216 @@
+import React, { useState } from 'react';
+import { ChevronDown, Plus } from 'lucide-react';
+import { cn } from '../lib/utils';
+
+// --- Launch-control primitives (ported from the prototype's sidebar) ---
+
+// A labelled config row. Inline (label left, control right) by default; pass
+// `stacked` to put a full-width control under the label — used for the model
+// dropdown and the effort/reasoning segmented pickers, which need the room.
+export function ConfigRow({ label, stacked, children }: { label: string; stacked?: boolean; children: React.ReactNode }) {
+  if (stacked) {
+    return (
+      <div className="space-y-1">
+        <span className="block text-[10px] text-muted-foreground/50">{label}</span>
+        {children}
+      </div>
+    );
+  }
+  return (
+    <div className="flex items-center justify-between gap-2">
+      <span className="shrink-0 text-[10px] text-muted-foreground/50">{label}</span>
+      {children}
+    </div>
+  );
+}
+
+// Pill selector for small option sets (effort, reasoning, tour engine).
+export function SegmentedPicker({ options, value, onChange }: { options: Array<{ value: string; label: string }>; value: string; onChange: (v: string) => void }) {
+  return (
+    <div className="flex items-center gap-px rounded-lg bg-surface-1/50 p-0.5">
+      {options.map((opt) => (
+        <button
+          key={opt.value}
+          type="button"
+          onClick={() => onChange(opt.value)}
+          className={cn(
+            'flex-1 rounded-md px-2 py-1 font-medium text-[9px] transition-colors',
+            value === opt.value
+              ? 'bg-card text-foreground shadow-sm'
+              : 'text-muted-foreground/50 hover:text-muted-foreground',
+          )}
+        >
+          {opt.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+// Animated on/off switch (fast mode).
+export function Toggle({ checked, onChange }: { checked: boolean; onChange: (v: boolean) => void }) {
+  return (
+    <button
+      type="button"
+      onClick={() => onChange(!checked)}
+      className={cn('relative h-5 w-9 shrink-0 rounded-full transition-colors', checked ? 'bg-primary' : 'bg-border/50')}
+    >
+      <span
+        className={cn(
+          'absolute top-0.5 left-0.5 h-4 w-4 rounded-full bg-white shadow-sm transition-transform',
+          checked && 'translate-x-4',
+        )}
+      />
+    </button>
+  );
+}
+
+// Lists longer than this get a type-to-filter input and provider grouping —
+// marker-engine catalogs (Cursor ~150, Pi ~59, OpenCode ~25) are unusable as a
+// flat list; the classic Claude/Codex catalogs (7–11) stay a plain menu.
+// Exported so other pickers over the same catalogs (e.g. GuideEmptyState's
+// InlinePicker in review-editor) share this one threshold instead of hardcoding it.
+export const SEARCHABLE_THRESHOLD = 12;
+
+export interface SelectOptionGroup {
+  /** null = ungrouped (single flat list). */
+  label: string | null;
+  options: Array<{ value: string; label: string }>;
+}
+
+/** Group `provider/model`-shaped option lists by their provider prefix.
+ *  Returns one ungrouped bucket when the list is small or ids aren't
+ *  provider-prefixed (Claude aliases, Codex models, Cursor ids). */
+export function groupModelOptions(options: Array<{ value: string; label: string }>): SelectOptionGroup[] {
+  const slashed = options.filter((o) => o.value.includes('/')).length;
+  if (options.length <= SEARCHABLE_THRESHOLD || slashed < options.length / 2) {
+    return [{ label: null, options }];
+  }
+  const groups = new Map<string, Array<{ value: string; label: string }>>();
+  for (const o of options) {
+    const key = o.value.includes('/') ? o.value.slice(0, o.value.indexOf('/')) : 'other';
+    const bucket = groups.get(key);
+    if (bucket) bucket.push(o);
+    else groups.set(key, [o]);
+  }
+  return [...groups.entries()].map(([label, opts]) => ({ label, options: opts }));
+}
+
+/** Strip a redundant `group/` prefix from an option label rendered under its
+ *  group header (e.g. "anthropic/claude-sonnet-4-6" under "anthropic"). */
+export function labelWithinGroup(label: string, group: string | null): string {
+  if (group && label.startsWith(`${group}/`)) return label.slice(group.length + 1);
+  return label;
+}
+
+// Dropdown button + downward popover. Reused for the provider selector and the
+// model picker (whose 7–9 options rule out a segmented control). The popover
+// opens downward (`top-full`) because the launch panel is pinned to the top of
+// the tab. Long catalogs automatically gain a filter input + provider grouping.
+export function SelectMenu({ value, options, onChange, icon, placeholder, footerAction }: { value: string; options: Array<{ value: string; label: string }>; onChange: (v: string) => void; icon?: React.ReactNode; placeholder?: string; footerAction?: { label: string; onClick: () => void } }) {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const current = options.find((o) => o.value === value);
+  const searchable = options.length > SEARCHABLE_THRESHOLD;
+
+  const q = query.trim().toLowerCase();
+  const filtered = q
+    ? options.filter((o) => o.label.toLowerCase().includes(q) || o.value.toLowerCase().includes(q))
+    : options;
+  const grouped = groupModelOptions(filtered);
+
+  const close = () => {
+    setOpen(false);
+    setQuery('');
+  };
+  const select = (v: string) => {
+    onChange(v);
+    close();
+  };
+
+  return (
+    <div className="relative w-full">
+      <button
+        type="button"
+        onClick={() => (open ? close() : setOpen(true))}
+        className="flex w-full items-center gap-2 rounded-lg border border-border/30 bg-surface-1/30 px-2.5 py-1.5 text-left transition-colors hover:bg-surface-1/50"
+      >
+        {icon}
+        <span className="min-w-0 flex-1 truncate text-[11px] text-foreground/80">{current?.label ?? placeholder}</span>
+        <ChevronDown className={cn('shrink-0 text-muted-foreground/30 transition-transform', open && 'rotate-180')} size={10} />
+      </button>
+      {open && (
+        <>
+          <div className="fixed inset-0 z-10" onClick={close} />
+          <div
+            className={cn(
+              'absolute right-0 top-full left-0 z-20 mt-1 rounded-xl bg-card shadow-[var(--card-shadow)] ring-1 ring-border/20',
+              searchable && 'min-w-[240px]',
+            )}
+          >
+            {searchable && (
+              <div className="p-1 pb-0">
+                <input
+                  autoFocus
+                  value={query}
+                  onChange={(e) => setQuery(e.target.value)}
+                  onKeyDown={(e) => {
+                    e.stopPropagation();
+                    if (e.key === 'Escape') close();
+                    if (e.key === 'Enter' && filtered.length > 0) select(filtered[0].value);
+                  }}
+                  placeholder="Type to filter…"
+                  className="w-full rounded-lg border border-border/30 bg-surface-1/30 px-2.5 py-1.5 text-[11px] text-foreground outline-none placeholder:text-muted-foreground/40 focus:border-border/60"
+                />
+              </div>
+            )}
+            <div className={cn('overflow-y-auto p-1', searchable ? 'max-h-72' : 'max-h-56')}>
+              {filtered.length === 0 && (
+                <div className="px-2.5 py-2 text-[11px] text-muted-foreground/50">No matches</div>
+              )}
+              {grouped.map((group) => (
+                <React.Fragment key={group.label ?? '__flat'}>
+                  {group.label && (
+                    <div className="px-2.5 pb-0.5 pt-1.5 font-medium text-[9px] uppercase tracking-wider text-muted-foreground/40">
+                      {group.label}
+                    </div>
+                  )}
+                  {group.options.map((o) => (
+                    <button
+                      key={o.value}
+                      type="button"
+                      onClick={() => select(o.value)}
+                      className={cn(
+                        'flex w-full items-center gap-2 rounded-lg px-2.5 py-1.5 text-left text-[11px] transition-colors',
+                        value === o.value
+                          ? 'bg-surface-1 text-foreground'
+                          : 'text-muted-foreground hover:bg-surface-1/50 hover:text-foreground',
+                      )}
+                    >
+                      <span className="min-w-0 flex-1 truncate">{labelWithinGroup(o.label, group.label)}</span>
+                    </button>
+                  ))}
+                </React.Fragment>
+              ))}
+            </div>
+            {footerAction && (
+              <div className="border-t border-border/20 p-1">
+                <button
+                  type="button"
+                  onClick={() => {
+                    close();
+                    footerAction.onClick();
+                  }}
+                  className="flex w-full items-center gap-2 rounded-lg px-2.5 py-1.5 text-[11px] text-muted-foreground transition-colors hover:bg-surface-1/50 hover:text-foreground"
+                >
+                  <Plus className="shrink-0" size={11} />
+                  {footerAction.label}
+                </button>
+              </div>
+            )}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}