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 prepack — 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)
@@ -206,7 +209,7 @@ Ask AI's "changes under review" context for **code review** is generated by the
 
 ## 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 |
 |--------|---------------------------|

adr/decisions/005-publish-document-ui-as-packages-20260701-150551.md

@@ -0,0 +1,58 @@
+# 005. Publish the document UI as `@plannotator/ui` + `@plannotator/core`
+
+Date: 2026-07-01
+
+## Status
+
+Accepted
+
+## Context
+
+The commercial Workspaces app (Cloudflare Workers + D1 + R2 + Durable Objects, WorkOS identity, Yjs realtime) needs Plannotator's document UI: the markdown rendering engine, the annotation/comment machinery, the markdown editor, and the theme. Plannotator's open-source experience must not change while making that possible.
+
+Two approaches were on the table:
+
+1. **Copy/vendor** — fork the UI source into the Workspaces repo (an earlier from-scratch reimplementation of this UI was attempted, broke the app, and was reverted).
+2. **Publish** — make the UI an installable package with host-override seams.
+
+Copy/vendor loses on two facts we've since measured:
+
+- **The reusable pieces sit deep in the package graph.** `packages/ui` imported freely from `@plannotator/shared`, which is Node-bound (fs/git/server). A copy would have to sever those imports by hand and re-sever them on every sync.
+- **Main moves too fast for a fork.** During the packaging PR (#957) alone, the branch was rebased onto main **four times** (46 commits, then #979/#980, #981/#983, #878 + the 0.21.4 release). A vendored copy would already be four syncs behind; every UI feature landing on main (math rendering, parser hardening, PR-context work) would need manual porting.
+
+Seams beat surgery for the same reason: an override point whose default *is* today's code keeps one source of truth, whereas editing call sites per-consumer creates two.
+
+## Decision
+
+Publish two packages, keep one private, and decouple via seams — never rewrite:
+
+- **`@plannotator/core`** — browser-safe, zero-dependency pure utils + types, carved out of `@plannotator/shared` with `git mv`. CI typechecks it without `@types/node` so a `node:` import cannot sneak in. Published.
+- **`@plannotator/ui`** — the React components, hooks, theme, and `configurePlannotatorUI()`. Depends on `core`. Published.
+- **`@plannotator/shared`** — stays private; re-exports the moved core modules via one-line shims (`export * from '@plannotator/core/x'`), so none of Plannotator's ~99 internal import sites changed.
+
+**The seam pattern:** every place the UI touches a backend is a module-level singleton with a setter — `let impl = default; setX(); resetX(); getX()` — where the default reproduces Plannotator's literal behavior (`/api/*` over fetch). Plannotator passes nothing and stays byte-for-byte unchanged; a host calls `configurePlannotatorUI({...})` once at startup. Seams shipped: storage, identity (incl. `isEditable`), image resolving, uploads, doc previews, file tree, drafts, external annotations, AI transport, server sync.
+
+**Singleton, not a React Provider — with a named revisit condition:** module-level state is safe for client-side apps (one user per browser). It is wrong under SSR, where one server process renders for many users. Neither Plannotator nor Workspaces does SSR. **If SSR is ever added for this UI, that is the trigger to introduce a `<PlannotatorUIServices>` provider** and turn `configurePlannotatorUI` into a compatibility shim over it. Until then the complexity is not paid.
+
+**The law** (guardrails, enforced socially and by CI where possible):
+
+1. Don't reimplement the document UI from scratch — add a seam.
+2. Every seam's default must reproduce today's Plannotator behavior.
+3. `@plannotator/core` stays browser-safe and zero-dep — no `node:` imports.
+4. Never delete working Plannotator code until a human confirms parity in the browser.
+
+**Publish model:** both packages version **in lockstep with the repo** (currently 0.21.4). They ship TypeScript source (consumers bundle it); `styles.css` is precompiled by `prepack`. `workspace:*` inter-deps must resolve to exact versions at publish time, so the flow is `bun pm pack` then `npm publish *.tgz --provenance --access public`, **`core` first, then `ui`**. First publish is manual from `main` after merge; a CI publish job is a follow-up.
+
+## Consequences
+
+- Workspaces installs the packages and plugs in its Cloudflare backend (localStorage settings, WorkOS identity with `isEditable() => false`, R2 uploads, D1 doc previews, DO-backed annotation transport) without forking. Its repo writes the matching consumer-side ADR.
+- The published exports map is broad; **importable ≠ supported**. The supported-import allowlist and the unsupported "calls Plannotator's local server" list live in `packages/ui/HANDOFF.md`, alongside the annotation anchor schema and the editor/Yjs status. Restructuring exports was deliberately deferred.
+- Known rough edges accepted for v1 (documented in HANDOFF.md): `AITransport`/`FileTreeBackend` leak `Response` objects; the markdown editor doesn't yet accept CM6 extensions (live collab lands via a later atomic PR threading `extensions?` through both wrapper layers after `@plannotator/markdown-editor` is imported into the monorepo).
+- Every future "the host needs different behavior" request has one sanctioned shape: add an optional seam in a Plannotator PR whose default is today's behavior.
+- Version lockstep means UI releases are repo releases; publishing stays owner-authorized.
+
+## References
+
+- PR #957 (`feat/pkg-document-ui`)
+- `packages/ui/HANDOFF.md` — consumer handoff (seam catalog, supported imports, anchor schema)
+- `packages/ui/README.md`, `packages/ui/CLAUDE.md` — the short version next to the code

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-context-live 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 guide 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 commit-avatars commit-history; 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-context-live 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 guide commit-avatars commit-history; do
   src="../../packages/shared/$f.ts"
   printf '// @generated — DO NOT EDIT. Source: packages/shared/%s.ts\n' "$f" | cat - "$src" > "generated/$f.ts"
 done
@@ -56,9 +78,15 @@ for f in guide-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-app-server 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,89 +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. Used as a fallback when the changeset can't be
-   *  reproduced locally with a single VCS command. */
-  patch: string;
-  /** The VCS diff type (e.g. "uncommitted", "branch", "merge-base"). When set
-   *  to a git-reproducible type, the prompt tells the agent how to inspect the
-   *  changes with git instead of pasting the whole diff. */
-  diffType?: string;
-  /** The base branch/ref the diff is computed against (for branch/merge-base). */
-  base?: 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