claude-plan-viewer 1.3.0 → 1.4.1

package/openapi.json

@@ -0,0 +1,237 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Claude Plan Viewer API",
+    "description": "API for browsing and searching Claude Code plans",
+    "version": "1.4.0",
+    "license": {
+      "name": "MIT",
+      "url": "https://opensource.org/licenses/MIT"
+    }
+  },
+  "servers": [
+    {
+      "url": "/",
+      "description": "Current server"
+    }
+  ],
+  "paths": {
+    "/api/plans": {
+      "get": {
+        "summary": "List all plans",
+        "description": "Returns metadata for all plans without content. Use /api/plans/{filename}/content to get content.",
+        "operationId": "listPlans",
+        "responses": {
+          "200": {
+            "description": "List of plans",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "plans": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/PlanMetadata"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/plans/{filename}/content": {
+      "get": {
+        "summary": "Get plan content",
+        "description": "Returns the markdown content for a specific plan",
+        "operationId": "getPlanContent",
+        "parameters": [
+          {
+            "name": "filename",
+            "in": "path",
+            "required": true,
+            "description": "The plan filename (e.g., my-plan.md)",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Plan content",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "content": {
+                      "type": "string",
+                      "description": "Markdown content of the plan"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Plan not found"
+          }
+        }
+      }
+    },
+    "/api/projects": {
+      "get": {
+        "summary": "List all projects",
+        "description": "Returns a list of unique project names associated with plans",
+        "operationId": "listProjects",
+        "responses": {
+          "200": {
+            "description": "List of project names",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "projects": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/refresh": {
+      "post": {
+        "summary": "Refresh cache",
+        "description": "Invalidates the plan cache and reloads all plans from disk",
+        "operationId": "refreshCache",
+        "responses": {
+          "200": {
+            "description": "Cache refreshed successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/open": {
+      "post": {
+        "summary": "Open plan in editor",
+        "description": "Opens the specified plan file in the system's default editor",
+        "operationId": "openInEditor",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["filepath"],
+                "properties": {
+                  "filepath": {
+                    "type": "string",
+                    "description": "Absolute path to the plan file"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "File opened successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid path"
+          },
+          "500": {
+            "description": "Failed to open file"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "PlanMetadata": {
+        "type": "object",
+        "properties": {
+          "filename": {
+            "type": "string",
+            "description": "Plan filename (e.g., my-plan.md)"
+          },
+          "filepath": {
+            "type": "string",
+            "description": "Absolute path to the plan file"
+          },
+          "title": {
+            "type": "string",
+            "description": "Plan title extracted from markdown heading"
+          },
+          "size": {
+            "type": "integer",
+            "description": "File size in bytes"
+          },
+          "modified": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Last modification timestamp"
+          },
+          "created": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Creation timestamp"
+          },
+          "lineCount": {
+            "type": "integer",
+            "description": "Number of lines in the plan"
+          },
+          "wordCount": {
+            "type": "integer",
+            "description": "Number of words in the plan"
+          },
+          "project": {
+            "type": "string",
+            "nullable": true,
+            "description": "Associated Claude Code project name"
+          },
+          "sessionId": {
+            "type": "string",
+            "nullable": true,
+            "description": "Associated Claude Code session ID"
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plan-viewer",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "A web-based viewer for Claude Code plan files",
   "type": "module",
   "bin": {
@@ -8,23 +8,28 @@
   },
   "files": [
     "index.ts",
-    "index.html",
-    "src",
-    "styles.css",
-    "prism.bundle.js"
+    "openapi.json",
+    "src"
   ],
   "scripts": {
     "start": "bun index.ts",
     "dev": "bun --hot index.ts",
-    "test": "bun test index.test.ts frontend.test.ts",
+    "test": "bun test test/",
+    "test:api": "bun test test/api.test.ts",
     "test:e2e": "bunx playwright test",
-    "build": "bun build --compile --minify --bytecode ./index.ts --outfile ./dist/plans-viewer",
-    "build:macos-arm64": "bun build --compile --target=bun-darwin-arm64 --minify --bytecode ./index.ts --outfile ./dist/plans-viewer-macos-arm64",
-    "build:macos-x64": "bun build --compile --target=bun-darwin-x64 --minify --bytecode ./index.ts --outfile ./dist/plans-viewer-macos-x64",
-    "build:linux-x64": "bun build --compile --target=bun-linux-x64 --minify --bytecode ./index.ts --outfile ./dist/plans-viewer-linux-x64",
-    "build:linux-arm64": "bun build --compile --target=bun-linux-arm64 --minify --bytecode ./index.ts --outfile ./dist/plans-viewer-linux-arm64",
-    "build:windows": "bun build --compile --target=bun-windows-x64 --minify --bytecode ./index.ts --outfile ./dist/plans-viewer-windows.exe",
-    "build:all": "bun run build:macos-arm64 && bun run build:macos-x64 && bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:windows"
+    "build": "bun build --compile --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer",
+    "build:macos-arm64": "bun build --compile --target=bun-darwin-arm64 --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer-macos-arm64",
+    "build:macos-x64": "bun build --compile --target=bun-darwin-x64 --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer-macos-x64",
+    "build:linux-x64": "bun build --compile --target=bun-linux-x64 --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer-linux-x64",
+    "build:linux-arm64": "bun build --compile --target=bun-linux-arm64 --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer-linux-arm64",
+    "build:windows": "bun build --compile --target=bun-windows-x64 --minify --bytecode ./index.ts --outfile ./dist/claude-plan-viewer-windows.exe",
+    "build:all": "bun run build:macos-arm64 && bun run build:macos-x64 && bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:windows",
+    "clean": "rm -rf ./dist",
+    "install:link": "bun link",
+    "install:local": "bun scripts/install-local.ts",
+    "uninstall:link": "bun unlink",
+    "uninstall:local": "bun scripts/uninstall-local.ts",
+    "format": "bunx prettier --write src"
   },
   "keywords": [
     "claude",
@@ -49,8 +54,10 @@
   "devDependencies": {
     "@playwright/test": "^1.57.0",
     "@types/bun": "latest",
+    "@types/prismjs": "^1.26.5",
     "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3"
+    "@types/react-dom": "^19.2.3",
+    "@types/react-syntax-highlighter": "^15.5.13"
   },
   "peerDependencies": {
     "typescript": "^5.9.3"
@@ -58,6 +65,10 @@
   "dependencies": {
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
-    "react-select": "^5.10.2"
+    "react-markdown": "^10.1.0",
+    "react-select": "^5.10.2",
+    "react-syntax-highlighter": "^16.1.0",
+    "remark-gfm": "^4.0.1",
+    "swr": "^2.3.8"
   }
 }

package/src/api-docs.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Plans Viewer API</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+    <script>
+      Scalar.createApiReference("#app", {
+        url: "/api/openapi.json",
+      });
+    </script>
+  </body>
+</html>

package/src/client/App.tsx

@@ -16,6 +16,7 @@ export function App() {
   const [selectedPlan, setSelectedPlan] = useState<Plan | null>(null);
   const [showOverlay, setShowOverlay] = useState(false);
   const [showHelp, setShowHelp] = useState(false);
+  const [copied, setCopied] = useState(false);
 
   // Filter state
   const {
@@ -35,11 +36,11 @@ export function App() {
   // Convert Set to array for API
   const projectsArray = useMemo(
     () => Array.from(selectedProjects),
-    [selectedProjects]
+    [selectedProjects],
   );
 
   // Fetch plans with server-side filtering
-  const { plans, loading, refresh, ensureContent } = usePlans({
+  const { plans, loading, refreshing, refresh, ensureContent } = usePlans({
     q: debouncedSearch,
     sort: sortKey,
     dir: sortDir,
@@ -52,6 +53,15 @@ export function App() {
   // Load content when plan is selected
   const handleSelectPlan = useCallback(
     async (plan: Plan | null) => {
+      // Update URL query parameter
+      const url = new URL(window.location.href);
+      if (plan) {
+        url.searchParams.set("plan", plan.filename);
+      } else {
+        url.searchParams.delete("plan");
+      }
+      window.history.replaceState({}, "", url.toString());
+
       if (plan) {
         const withContent = await ensureContent(plan);
         setSelectedPlan(withContent);
@@ -59,7 +69,7 @@ export function App() {
         setSelectedPlan(null);
       }
     },
-    [ensureContent]
+    [ensureContent],
   );
 
   // Open in editor
@@ -74,6 +84,20 @@ export function App() {
     navigator.clipboard.writeText(`claude --resume ${sessionId}`);
   }, []);
 
+  // Copy filepath
+  const handleCopyFilepath = useCallback((filepath: string) => {
+    navigator.clipboard.writeText(filepath);
+  }, []);
+
+  // Copy plan content
+  const handleCopyPlan = useCallback(() => {
+    if (selectedPlan?.content) {
+      navigator.clipboard.writeText(selectedPlan.content);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    }
+  }, [selectedPlan]);
+
   // Clear search
   const handleClearSearch = useCallback(() => {
     setSearchQuery("");
@@ -92,19 +116,34 @@ export function App() {
     onClearSearch: handleClearSearch,
   });
 
-  // Auto-select first plan when plans change
+  // Select plan from URL or auto-select first plan
   useEffect(() => {
-    if (!selectedPlan && plans.length > 0) {
-      const firstPlan = plans[0];
-      if (firstPlan) {
-        handleSelectPlan(firstPlan);
+    if (plans.length === 0) return;
+
+    // Check URL for plan parameter
+    const url = new URL(window.location.href);
+    const planFromUrl = url.searchParams.get("plan");
+
+    if (planFromUrl) {
+      const matchingPlan = plans.find((p) => p.filename === planFromUrl);
+      if (matchingPlan && selectedPlan?.filename !== planFromUrl) {
+        handleSelectPlan(matchingPlan);
+        return;
       }
     }
+
+    // Fall back to selecting first plan if nothing selected
+    if (!selectedPlan) {
+      handleSelectPlan(plans[0]);
+    }
   }, [plans, selectedPlan, handleSelectPlan]);
 
   // Clear selection if selected plan is no longer in results
   useEffect(() => {
-    if (selectedPlan && !plans.find((p) => p.filename === selectedPlan.filename)) {
+    if (
+      selectedPlan &&
+      !plans.find((p) => p.filename === selectedPlan.filename)
+    ) {
       setSelectedPlan(null);
     }
   }, [plans, selectedPlan]);
@@ -130,6 +169,7 @@ export function App() {
           onToggleProject={toggleProject}
           onClearProjects={clearProjects}
           onRefresh={refresh}
+          refreshing={refreshing}
         />
 
         {plans.length === 0 ? (
@@ -156,6 +196,9 @@ export function App() {
         onOpenEditor={handleOpenEditor}
         onToggleOverlay={() => setShowOverlay(true)}
         onCopySession={handleCopySession}
+        onCopyFilepath={handleCopyFilepath}
+        onCopyPlan={handleCopyPlan}
+        copied={copied}
       />
 
       {showOverlay && selectedPlan && (
@@ -164,6 +207,8 @@ export function App() {
           onClose={() => setShowOverlay(false)}
           onOpenEditor={handleOpenEditor}
           onCopySession={handleCopySession}
+          onCopyPlan={handleCopyPlan}
+          copied={copied}
         />
       )}
 

package/src/client/components/DetailOverlay.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useCallback } from "react";
+import { useEffect, useCallback, useRef } from "react";
+import { useFocusTrap } from "../hooks/useFocusTrap";
 import type { Plan } from "../types.ts";
 import { formatFullDate, formatSize } from "../utils/formatters.ts";
 import { Markdown } from "./Markdown.tsx";
@@ -8,6 +9,8 @@ interface DetailOverlayProps {
   onClose: () => void;
   onOpenEditor: () => void;
   onCopySession: (sessionId: string) => void;
+  onCopyPlan: () => void;
+  copied: boolean;
 }
 
 export function DetailOverlay({
@@ -15,7 +18,12 @@ export function DetailOverlay({
   onClose,
   onOpenEditor,
   onCopySession,
+  onCopyPlan,
+  copied,
 }: DetailOverlayProps) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  useFocusTrap(panelRef, true);
+
   const handleKeyDown = useCallback(
     (e: KeyboardEvent) => {
       if (e.key === "Escape" || e.key === "f") {
@@ -23,7 +31,7 @@ export function DetailOverlay({
         onClose();
       }
     },
-    [onClose]
+    [onClose],
   );
 
   useEffect(() => {
@@ -43,11 +51,20 @@ export function DetailOverlay({
       aria-hidden="false"
       onClick={onClose}
     >
-      <div className="detail-overlay-panel" onClick={(e) => e.stopPropagation()}>
+      <div
+        ref={panelRef}
+        className="detail-overlay-panel"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="detail-overlay-title"
+        onClick={(e) => e.stopPropagation()}
+      >
         <div className="detail-overlay-bar">
           <div className="detail-meta detail-overlay-meta">
-            {plan.project && <span className="project-tag">{plan.project}</span>}
-            <span>{plan.filename}</span>
+            {plan.project && (
+              <span className="project-tag">{plan.project}</span>
+            )}
+            <span id="detail-overlay-title">{plan.filename}</span>
             <span>{formatFullDate(plan.modified)}</span>
             <span>{formatSize(plan.size)}</span>
             <span>{plan.lineCount} lines</span>
@@ -61,14 +78,42 @@ export function DetailOverlay({
               </button>
             )}
           </div>
+          <button
+            className={copied ? "action-btn copied" : "action-btn"}
+            onClick={onCopyPlan}
+            title="Copy plan to clipboard"
+          >
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              className="icon"
+            >
+              <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+              <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+            </svg>
+          </button>
           <button
             className="action-btn"
             onClick={onOpenEditor}
             title="Open in editor (Enter)"
           >
-            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="icon">
-              <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/>
-              <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/>
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              className="icon"
+            >
+              <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" />
+              <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z" />
             </svg>
           </button>
           <button
@@ -76,7 +121,19 @@ export function DetailOverlay({
             onClick={onClose}
             title="Close fullscreen (Esc or F)"
           >
-            ×
+            <svg
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2.5"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <line x1="18" y1="6" x2="6" y2="18" />
+              <line x1="6" y1="6" x2="18" y2="18" />
+            </svg>
           </button>
         </div>
         <div className="detail-overlay-content">