Render YAML frontmatter as styled metadata card (#45)

Fixes #43 - YAML frontmatter was rendering as ugly text because
the parser treated it as regular markdown content.

Changes:
- Added extractFrontmatter() to parser that parses YAML key-value pairs
- Added FrontmatterCard component that renders frontmatter nicely
- Supports string values and arrays (rendered as tags)
- Card appears at top of plan with muted background

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: backnotprop

.gitignore

@@ -30,3 +30,5 @@ apps/opencode-plugin/plannotator.html
 *.sw?
 opencode.json
 plannotator-local
+# Local research/reference docs (not for repo)
+reference/

packages/editor/App.tsx

@@ -1,5 +1,5 @@
 import React, { useState, useEffect, useMemo, useRef } from 'react';
-import { parseMarkdownToBlocks, exportDiff } from '@plannotator/ui/utils/parser';
+import { parseMarkdownToBlocks, exportDiff, extractFrontmatter, Frontmatter } from '@plannotator/ui/utils/parser';
 import { Viewer, ViewerHandle } from '@plannotator/ui/components/Viewer';
 import { AnnotationPanel } from '@plannotator/ui/components/AnnotationPanel';
 import { ExportModal } from '@plannotator/ui/components/ExportModal';
@@ -301,6 +301,7 @@ const App: React.FC = () => {
   const [annotations, setAnnotations] = useState<Annotation[]>([]);
   const [selectedAnnotationId, setSelectedAnnotationId] = useState<string | null>(null);
   const [blocks, setBlocks] = useState<Block[]>([]);
+  const [frontmatter, setFrontmatter] = useState<Frontmatter | null>(null);
   const [showExport, setShowExport] = useState(false);
   const [showFeedbackPrompt, setShowFeedbackPrompt] = useState(false);
   const [showClaudeCodeWarning, setShowClaudeCodeWarning] = useState(false);
@@ -384,6 +385,8 @@ const App: React.FC = () => {
   }, [isLoadingShared, isSharedSession]);
 
   useEffect(() => {
+    const { frontmatter: fm } = extractFrontmatter(markdown);
+    setFrontmatter(fm);
     setBlocks(parseMarkdownToBlocks(markdown));
   }, [markdown]);
 
@@ -678,6 +681,7 @@ const App: React.FC = () => {
                 ref={viewerRef}
                 blocks={blocks}
                 markdown={markdown}
+                frontmatter={frontmatter}
                 annotations={annotations}
                 onAddAnnotation={handleAddAnnotation}
                 onSelectAnnotation={setSelectedAnnotationId}

packages/ui/components/Viewer.tsx

@@ -4,6 +4,7 @@ import Highlighter from 'web-highlighter';
 import hljs from 'highlight.js';
 import 'highlight.js/styles/github-dark.css';
 import { Block, Annotation, AnnotationType, EditorMode } from '../types';
+import { Frontmatter } from '../utils/parser';
 import { Toolbar } from './Toolbar';
 import { TaterSpriteSitting } from './TaterSpriteSitting';
 import { AttachmentsButton } from './AttachmentsButton';
@@ -12,6 +13,7 @@ import { getIdentity } from '../utils/identity';
 interface ViewerProps {
   blocks: Block[];
   markdown: string;
+  frontmatter?: Frontmatter | null;
   annotations: Annotation[];
   onAddAnnotation: (ann: Annotation) => void;
   onSelectAnnotation: (id: string | null) => void;
@@ -29,9 +31,43 @@ export interface ViewerHandle {
   applySharedAnnotations: (annotations: Annotation[]) => void;
 }
 
+/**
+ * Renders YAML frontmatter as a styled metadata card.
+ */
+const FrontmatterCard: React.FC<{ frontmatter: Frontmatter }> = ({ frontmatter }) => {
+  const entries = Object.entries(frontmatter);
+  if (entries.length === 0) return null;
+
+  return (
+    <div className="mt-4 mb-6 p-4 bg-muted/30 border border-border/50 rounded-lg">
+      <div className="grid gap-2 text-sm">
+        {entries.map(([key, value]) => (
+          <div key={key} className="flex gap-2">
+            <span className="font-medium text-muted-foreground min-w-[80px]">{key}:</span>
+            <span className="text-foreground">
+              {Array.isArray(value) ? (
+                <span className="flex flex-wrap gap-1">
+                  {value.map((v, i) => (
+                    <span key={i} className="px-1.5 py-0.5 bg-primary/10 text-primary rounded text-xs">
+                      {v}
+                    </span>
+                  ))}
+                </span>
+              ) : (
+                value
+              )}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
 export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   blocks,
   markdown,
+  frontmatter,
   annotations,
   onAddAnnotation,
   onSelectAnnotation,
@@ -622,6 +658,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
             )}
           </button>
         </div>
+        {frontmatter && <FrontmatterCard frontmatter={frontmatter} />}
         {blocks.map(block => (
           block.type === 'code' ? (
             <CodeBlock

packages/ui/utils/parser.ts

@@ -1,12 +1,75 @@
 import { Block } from '../types';
 
+/**
+ * Parsed YAML frontmatter as key-value pairs.
+ */
+export interface Frontmatter {
+  [key: string]: string | string[];
+}
+
+/**
+ * Extract YAML frontmatter from markdown if present.
+ * Returns both the parsed frontmatter and the remaining markdown.
+ */
+export function extractFrontmatter(markdown: string): { frontmatter: Frontmatter | null; content: string } {
+  const trimmed = markdown.trimStart();
+  if (!trimmed.startsWith('---')) {
+    return { frontmatter: null, content: markdown };
+  }
+
+  // Find the closing ---
+  const endIndex = trimmed.indexOf('\n---', 3);
+  if (endIndex === -1) {
+    return { frontmatter: null, content: markdown };
+  }
+
+  // Extract frontmatter content (between the --- delimiters)
+  const frontmatterRaw = trimmed.slice(4, endIndex).trim();
+  const afterFrontmatter = trimmed.slice(endIndex + 4).trimStart();
+
+  // Parse simple YAML (key: value pairs)
+  const frontmatter: Frontmatter = {};
+  let currentKey: string | null = null;
+  let currentArray: string[] | null = null;
+
+  for (const line of frontmatterRaw.split('\n')) {
+    const trimmedLine = line.trim();
+
+    // Array item (- value)
+    if (trimmedLine.startsWith('- ') && currentKey) {
+      const value = trimmedLine.slice(2).trim();
+      if (!currentArray) {
+        currentArray = [];
+        frontmatter[currentKey] = currentArray;
+      }
+      currentArray.push(value);
+      continue;
+    }
+
+    // Key: value pair
+    const colonIndex = trimmedLine.indexOf(':');
+    if (colonIndex > 0) {
+      currentKey = trimmedLine.slice(0, colonIndex).trim();
+      const value = trimmedLine.slice(colonIndex + 1).trim();
+      currentArray = null;
+
+      if (value) {
+        frontmatter[currentKey] = value;
+      }
+    }
+  }
+
+  return { frontmatter, content: afterFrontmatter };
+}
+
 /**
  * A simplified markdown parser that splits content into linear blocks.
  * For a production app, we would use a robust AST walker (remark),
  * but for this demo, we want predictable text-anchoring.
  */
 export const parseMarkdownToBlocks = (markdown: string): Block[] => {
-  const lines = markdown.split('\n');
+  const { content: cleanMarkdown } = extractFrontmatter(markdown);
+  const lines = cleanMarkdown.split('\n');
   const blocks: Block[] = [];
   let currentId = 0;
 

tests/manual/local/test-hook.sh

@@ -28,11 +28,11 @@ echo "Starting hook server..."
 echo "Browser should open automatically. Approve or deny the plan."
 echo ""
 
-# Sample plan with code blocks (for tag extraction testing)
+# Sample plan with YAML frontmatter and code blocks
 PLAN_JSON=$(cat << 'EOF'
 {
   "tool_input": {
-    "plan": "# Implementation Plan: User Authentication\n\n## Overview\nAdd secure user authentication using JWT tokens and bcrypt password hashing.\n\n## Phase 1: Database Schema\n\n```sql\nCREATE TABLE users (\n  id UUID PRIMARY KEY,\n  email VARCHAR(255) UNIQUE NOT NULL,\n  password_hash VARCHAR(255) NOT NULL,\n  created_at TIMESTAMP DEFAULT NOW()\n);\n```\n\n## Phase 2: API Endpoints\n\n```typescript\n// POST /auth/register\napp.post('/auth/register', async (req, res) => {\n  const { email, password } = req.body;\n  const hash = await bcrypt.hash(password, 10);\n  // ... create user\n});\n\n// POST /auth/login\napp.post('/auth/login', async (req, res) => {\n  // ... verify credentials\n  const token = jwt.sign({ userId }, SECRET);\n  res.json({ token });\n});\n```\n\n## Checklist\n\n- [ ] Set up database migrations\n- [ ] Implement password hashing\n- [ ] Add JWT token generation\n- [ ] Create login/register endpoints\n- [x] Design database schema\n\n---\n\n**Target:** Complete by end of sprint"
+    "plan": "---\ntitle: User Authentication Plan\nauthor: Claude\ndate: 2026-01-09\ntags:\n  - auth\n  - security\n  - backend\n---\n\n# Implementation Plan: User Authentication\n\n## Overview\nAdd secure user authentication using JWT tokens and bcrypt password hashing.\n\n## Phase 1: Database Schema\n\n```sql\nCREATE TABLE users (\n  id UUID PRIMARY KEY,\n  email VARCHAR(255) UNIQUE NOT NULL,\n  password_hash VARCHAR(255) NOT NULL,\n  created_at TIMESTAMP DEFAULT NOW()\n);\n```\n\n## Phase 2: API Endpoints\n\n```typescript\n// POST /auth/register\napp.post('/auth/register', async (req, res) => {\n  const { email, password } = req.body;\n  const hash = await bcrypt.hash(password, 10);\n  // ... create user\n});\n\n// POST /auth/login\napp.post('/auth/login', async (req, res) => {\n  // ... verify credentials\n  const token = jwt.sign({ userId }, SECRET);\n  res.json({ token });\n});\n```\n\n## Checklist\n\n- [ ] Set up database migrations\n- [ ] Implement password hashing\n- [ ] Add JWT token generation\n- [ ] Create login/register endpoints\n- [x] Design database schema\n\n---\n\n**Target:** Complete by end of sprint"
   }
 }
 EOF