Make the document UI reusable as published building blocks

.gitignore

@@ -62,3 +62,7 @@ plannotator-local
 
 # Local Pi state/memory (not upstream)
 /.pi/
+
+# @plannotator/ui CSS build artifacts (generated by prepublishOnly — not committed)
+packages/ui/styles.css
+packages/ui/styles.js

AGENTS.md

@@ -2,6 +2,8 @@
 
 A plan review UI for Claude Code that intercepts `ExitPlanMode` via hooks, letting users approve or request changes with annotated feedback. Also provides code review for git diffs and annotation of arbitrary markdown files.
 
+> **Reusing the document UI (theme / markdown / editor / settings / comments / layout) in the commercial Workspaces app? Read `packages/ui/README.md` FIRST.** It explains the published `@plannotator/ui` + `@plannotator/core` packages and the host-override seams a host plugs its own backend into via `configurePlannotatorUI()`. A prior from-scratch reimplementation of this UI broke the app and was reverted — do **not** rebuild it or recreate `packages/document-ui`. Add a seam to `@plannotator/ui` instead, keep Plannotator's app unchanged, and never delete working code until a human confirms parity in the browser.
+
 ## Project Structure
 
 ```
@@ -81,7 +83,8 @@ plannotator/
 │   │   ├── hooks/                # useAnnotationHighlighter.ts, useSharing.ts, usePlanDiff.ts, useSidebar.ts, useLinkedDoc.ts, useAnnotationDraft.ts, useCodeAnnotationDraft.ts, useArchive.ts
 │   │   └── types.ts
 │   ├── ai/                       # Provider-agnostic AI backbone (providers, sessions, endpoints)
-│   ├── shared/                   # Shared types, utilities, and cross-runtime logic
+│   ├── core/                     # @plannotator/core — browser-safe, zero-dep universal slice (pure utils + types) shared by ui + shared; published so @plannotator/ui can be installed standalone. `shared` re-exports the moved modules via one-line shims so Plannotator is unchanged.
+│   ├── shared/                   # Node/git/server logic + cross-runtime types (re-exports browser-safe modules from @plannotator/core)
 │   │   ├── storage.ts            # Plan saving, version history, archive listing (node:fs only)
 │   │   ├── draft.ts              # Annotation draft persistence (node:fs only)
 │   │   └── project.ts            # Pure string helpers (sanitizeTag, extractRepoName, extractDirName)
@@ -194,7 +197,7 @@ Approve → "LGTM" sent to agent session
 
 ## Ask AI Provider Defaults
 
-Ask AI providers are detected independently from installed/authenticated local CLIs, then the UI picks a default from the detected Plannotator origin. The mapping lives in `packages/shared/agents.ts` and is applied by `packages/ui/utils/aiProvider.ts`:
+Ask AI providers are detected independently from installed/authenticated local CLIs, then the UI picks a default from the detected Plannotator origin. The mapping lives in `packages/core/agents.ts` (re-exported via the `packages/shared/agents.ts` shim) and is applied by `packages/ui/utils/aiProvider.ts`:
 
 | Origin | Preferred Ask AI provider |
 |--------|---------------------------|

apps/pi-extension/vendor.sh

@@ -7,7 +7,29 @@ cd "$(dirname "$0")"
 rm -rf generated
 mkdir -p generated generated/ai/providers
 
-for f in feedback-templates prompts review-core diff-paths cli-pagination jj-core vcs-core review-args storage draft project pr-types pr-provider pr-stack pr-github pr-gitlab checklist integrations-common repo reference-common favicon code-file resolve-file annotate-reference-roots-node config external-annotation agent-jobs agent-terminal worktree worktree-pool html-to-markdown html-assets html-assets-node url-to-markdown tour annotate-args at-reference review-workspace-node review-workspace pfm-reminder improvement-hooks code-nav data-dir semantic-diff-types semantic-diff source-save source-save-node workspace-status open-in-apps review-profiles; do
+# Modules that MOVED to @plannotator/core — vendor the real impl from core.
+for f in feedback-templates project favicon code-file external-annotation agent-jobs agent-terminal source-save open-in-apps; do
+  src="../../packages/core/$f.ts"
+  printf '// @generated — DO NOT EDIT. Source: packages/core/%s.ts\n' "$f" | cat - "$src" > "generated/$f.ts"
+done
+
+# Node-bound shared modules that now import types from @plannotator/core/*-types —
+# vendor from shared, rewrite the bare core specifier to the flat relative path.
+for f in config storage workspace-status; do
+  src="../../packages/shared/$f.ts"
+  printf '// @generated — DO NOT EDIT. Source: packages/shared/%s.ts\n' "$f" | cat - "$src" \
+    | sed "s|from ['\"]@plannotator/core/\\([^'\"]*\\)-types['\"]|from './\\1-types.js'|g" \
+    > "generated/$f.ts"
+done
+
+# Extracted type files those node-bound modules now depend on — vendor from core.
+for f in config-types storage-types workspace-status-types; do
+  src="../../packages/core/$f.ts"
+  printf '// @generated — DO NOT EDIT. Source: packages/core/%s.ts\n' "$f" | cat - "$src" > "generated/$f.ts"
+done
+
+# Everything else in the original flat list stays sourced from packages/shared.
+for f in prompts review-core diff-paths cli-pagination jj-core vcs-core review-args draft pr-types pr-provider pr-stack pr-github pr-gitlab checklist integrations-common repo reference-common resolve-file annotate-reference-roots-node worktree worktree-pool html-to-markdown html-assets html-assets-node url-to-markdown tour annotate-args at-reference review-workspace-node review-workspace pfm-reminder improvement-hooks code-nav data-dir semantic-diff-types semantic-diff source-save-node review-profiles; do
   src="../../packages/shared/$f.ts"
   printf '// @generated — DO NOT EDIT. Source: packages/shared/%s.ts\n' "$f" | cat - "$src" > "generated/$f.ts"
 done
@@ -40,9 +62,15 @@ for f in tour-review; do
     > "generated/$f.ts"
 done
 
+# Vendor the moved AI context types from core into generated/ai/.
+printf '// @generated — DO NOT EDIT. Source: packages/core/ai-context.ts\n' \
+  | cat - "../../packages/core/ai-context.ts" > "generated/ai/ai-context.ts"
+
 for f in index types provider session-manager endpoints context base-session; do
   src="../../packages/ai/$f.ts"
-  printf '// @generated — DO NOT EDIT. Source: packages/ai/%s.ts\n' "$f" | cat - "$src" > "generated/ai/$f.ts"
+  printf '// @generated — DO NOT EDIT. Source: packages/ai/%s.ts\n' "$f" | cat - "$src" \
+    | sed "s|from ['\"]@plannotator/core/ai-context['\"]|from './ai-context.js'|g" \
+    > "generated/ai/$f.ts"
 done
 
 for f in claude-agent-sdk codex-sdk opencode-sdk command-path pi-sdk pi-sdk-node pi-events; do

package.json

@@ -33,7 +33,8 @@
     "build:vscode": "bun run --cwd apps/vscode-extension build",
     "package:vscode": "bun run --cwd apps/vscode-extension package",
     "test": "bun test",
-    "typecheck": "bash apps/pi-extension/vendor.sh && tsc --noEmit -p packages/shared/tsconfig.json && tsc --noEmit -p packages/ai/tsconfig.json && tsc --noEmit -p packages/server/tsconfig.json && tsc --noEmit -p packages/ui/tsconfig.json && tsc --noEmit -p apps/pi-extension/tsconfig.json"
+    "typecheck": "bash apps/pi-extension/vendor.sh && tsc --noEmit -p packages/core/tsconfig.json && tsc --noEmit -p packages/shared/tsconfig.json && tsc --noEmit -p packages/ai/tsconfig.json && tsc --noEmit -p packages/server/tsconfig.json && tsc --noEmit -p packages/ui/tsconfig.json && tsc --noEmit -p apps/pi-extension/tsconfig.json",
+    "build:ui-css": "bun run --cwd packages/ui build:css"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.92",

packages/ai/package.json

@@ -17,5 +17,7 @@
     "./providers/opencode-sdk": "./providers/opencode-sdk.ts",
     "./providers/pi-sdk-node": "./providers/pi-sdk-node.ts"
   },
-  "dependencies": {}
+  "dependencies": {
+    "@plannotator/core": "workspace:*"
+  }
 }

packages/ai/types.ts

@@ -10,82 +10,8 @@
 // Context — what the AI session knows about
 // ---------------------------------------------------------------------------
 
-/** The surface the user is interacting with when they invoke AI. */
-export type AIContextMode = "plan-review" | "code-review" | "annotate";
-
-/**
- * Describes the parent agent session that originally produced the plan or diff.
- * Used to fork conversations with full history.
- */
-export interface ParentSession {
-  /** Session ID from the host agent (e.g. Claude Code session UUID). */
-  sessionId: string;
-  /** Working directory the parent session was running in. */
-  cwd: string;
-}
-
-/**
- * Snapshot of plan-review-specific context.
- * Passed when AIContextMode is "plan-review".
- */
-export interface PlanContext {
-  /** The full plan markdown as submitted by the agent. */
-  plan: string;
-  /** Previous plan version (if this is a resubmission). */
-  previousPlan?: string;
-  /** The version number in the plan's history. */
-  version?: number;
-  /** Total number of versions in the plan's history. */
-  totalVersions?: number;
-  /** Project/repository label used for plan history. */
-  project?: string;
-  /** Annotations the user has made so far (serialised for the prompt). */
-  annotations?: string;
-}
-
-/**
- * Snapshot of code-review-specific context.
- * Passed when AIContextMode is "code-review".
- */
-export interface CodeReviewContext {
-  /** The unified diff patch. */
-  patch: string;
-  /** The specific file being discussed (if scoped). */
-  filePath?: string;
-  /** The line range being discussed (if scoped). */
-  lineRange?: { start: number; end: number; side: "old" | "new" };
-  /** The code snippet being discussed (if scoped). */
-  selectedCode?: string;
-  /** Summary of annotations the user has made. */
-  annotations?: string;
-}
-
-/**
- * Snapshot of annotate-mode context.
- * Passed when AIContextMode is "annotate".
- */
-export interface AnnotateContext {
-  /** The markdown file content being annotated. */
-  content: string;
-  /** Path to the file on disk. */
-  filePath: string;
-  /** Source attribution shown in the UI, such as an original URL or filename. */
-  sourceInfo?: string;
-  /** True when the document was converted from HTML or a remote reader result. */
-  sourceConverted?: boolean;
-  /** Render mode for the annotated content. */
-  renderAs?: "markdown" | "html";
-  /** Summary of annotations the user has made. */
-  annotations?: string;
-}
-
-/**
- * Union of mode-specific contexts, discriminated by `mode`.
- */
-export type AIContext =
-  | { mode: "plan-review"; plan: PlanContext; parent?: ParentSession }
-  | { mode: "code-review"; review: CodeReviewContext; parent?: ParentSession }
-  | { mode: "annotate"; annotate: AnnotateContext; parent?: ParentSession };
+import type { AIContext, AIContextMode, PlanContext, CodeReviewContext, AnnotateContext, ParentSession } from '@plannotator/core/ai-context';
+export type { AIContext, AIContextMode, PlanContext, CodeReviewContext, AnnotateContext, ParentSession };
 
 // ---------------------------------------------------------------------------
 // Messages — what streams back from the AI