Phase 3: LLM grammar checkpoint

Backend (internal/llm): backend-agnostic LLMClient interface + factory
with vLLM (OpenAI-compat) and Ollama (native) clients, each Complete +
Stream. prompts.go holds the checkpoint and Ask Petal templates;
checkpoint.go salvages JSON from model output (brace-matched), enforces a
per-doc 30s RateLimiter, and truncates the doc to a latency cap.

internal/suggestions: POST /api/docs/:id/check runs a checkpoint and
replaces the doc's pending suggestions in one tx (accepted/rejected kept
as history); GET /api/docs/:id/suggestions lists pending;
POST /api/suggestions/:id/{accept,dismiss} resolves one. Throttled checks
return the current set rather than erroring.

Frontend: useCheckpoint (4s debounce, loads existing on open, stale-guard
tokens); SuggestionHighlight renders ProseMirror decorations re-anchored
by the `original` string on every doc change (not stored marks), with
precise textblock-offset→PM-position mapping; SuggestionCard shows the
type tag + diff + explanation and applies the replacement in-editor on
accept; breathing rose checkpoint dot in the StatusBar; fade-float +
breathe animations.

Tests: llm parse/rate-limit/truncate; suggestions full flow + rate-limit
over httptest with a stub client. Smoke-tested end-to-end against a fake
vLLM endpoint (anchoring verified) and the LLM-unreachable 502 path.

Claude-Session: https://claude.ai/code/session_016Yr6jELuRc7hyzYLccQKZd

internal/llm/checkpoint_test.go

@@ -0,0 +1,93 @@
+package llm
+
+import (
+	"testing"
+	"time"
+)
+
+func TestParseCheckpoint(t *testing.T) {
+	tests := []struct {
+		name    string
+		raw     string
+		want    int
+		wantErr bool
+	}{
+		{
+			name: "clean json",
+			raw:  `{"suggestions":[{"original":"I has","replacement":"I have","explanation":"subject-verb agreement","type":"grammar"}]}`,
+			want: 1,
+		},
+		{
+			name: "wrapped in markdown fence",
+			raw:  "Here you go:\n```json\n{\"suggestions\":[{\"original\":\"a apple\",\"replacement\":\"an apple\",\"explanation\":\"use an before a vowel\",\"type\":\"grammar\"}]}\n```",
+			want: 1,
+		},
+		{
+			name: "empty suggestions",
+			raw:  `{"suggestions":[]}`,
+			want: 0,
+		},
+		{
+			name: "drops items with empty original",
+			raw:  `{"suggestions":[{"original":"","replacement":"x","explanation":"e","type":"grammar"},{"original":"teh","replacement":"the","explanation":"typo","type":"grammar"}]}`,
+			want: 1,
+		},
+		{
+			name:    "no json at all",
+			raw:     "I could not find any issues!",
+			wantErr: true,
+		},
+		{
+			name: "braces inside string values",
+			raw:  `{"suggestions":[{"original":"use {x}","replacement":"use x","explanation":"drop the braces","type":"clarity"}]}`,
+			want: 1,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ParseCheckpoint(tt.raw)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got none")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if len(got) != tt.want {
+				t.Fatalf("got %d suggestions, want %d", len(got), tt.want)
+			}
+		})
+	}
+}
+
+func TestRateLimiter(t *testing.T) {
+	rl := NewRateLimiter(30 * time.Second)
+
+	if ok, _ := rl.Allow("doc1"); !ok {
+		t.Fatal("first call should be allowed")
+	}
+	if ok, retry := rl.Allow("doc1"); ok || retry <= 0 {
+		t.Fatalf("immediate second call should be throttled, got ok=%v retry=%v", ok, retry)
+	}
+	// A different document is independent.
+	if ok, _ := rl.Allow("doc2"); !ok {
+		t.Fatal("different doc should be allowed")
+	}
+}
+
+func TestTruncateDoc(t *testing.T) {
+	short := "hello"
+	if got := TruncateDoc(short); got != short {
+		t.Fatalf("short doc should be unchanged")
+	}
+	long := make([]byte, maxDocChars+500)
+	for i := range long {
+		long[i] = 'a'
+	}
+	got := TruncateDoc(string(long))
+	if len(got) != maxDocChars {
+		t.Fatalf("truncated length = %d, want %d", len(got), maxDocChars)
+	}
+}