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

web/src/components/Editor/SuggestionHighlight.ts

@@ -0,0 +1,121 @@
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import type { EditorState, Transaction } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+import type { Node as PMNode } from '@tiptap/pm/model'
+import type { Suggestion } from '../../api/client'
+
+// SuggestionHighlight renders LLM suggestions as ProseMirror *decorations*, not
+// stored marks. Decorations are ephemeral overlays recomputed from the live
+// document on every change, which is exactly the string-anchoring the spec
+// requires (Note #6): each suggestion is re-located by matching its `original`
+// text in the current doc, so edits made while a checkpoint is in flight never
+// leave a highlight stranded on stale coordinates.
+
+export const suggestionPluginKey = new PluginKey<PluginState>('petalSuggestions')
+
+interface PluginState {
+  suggestions: Suggestion[]
+  decorations: DecorationSet
+}
+
+// mapOffset converts a character offset within a textblock's flattened text into
+// an absolute ProseMirror position, accounting for inline atoms (e.g. hard
+// breaks) that occupy a position but contribute no text.
+function mapOffset(block: PMNode, blockPos: number, targetOffset: number): number {
+  let textOffset = 0
+  let pmPos = blockPos + 1 // inline content starts just inside the block
+  let result = pmPos
+  let done = false
+  block.forEach((child) => {
+    if (done) return
+    const len = child.isText ? (child.text?.length ?? 0) : 0
+    if (textOffset + len >= targetOffset) {
+      result = pmPos + (targetOffset - textOffset)
+      done = true
+    } else {
+      textOffset += len
+      pmPos += child.nodeSize
+    }
+  })
+  if (!done) result = pmPos
+  return result
+}
+
+// findRange locates the first occurrence of `search` within a single textblock
+// and returns its ProseMirror range, or null if the string isn't present (the
+// user may have edited or removed it since the checkpoint ran). Exported so the
+// accept flow can resolve the same span to replace.
+export function findRange(doc: PMNode, search: string): { from: number; to: number } | null {
+  if (!search) return null
+  let result: { from: number; to: number } | null = null
+  doc.descendants((node, pos) => {
+    if (result) return false
+    if (!node.isTextblock) return true // keep descending to the textblock
+    const idx = node.textContent.indexOf(search)
+    if (idx >= 0) {
+      result = {
+        from: mapOffset(node, pos, idx),
+        to: mapOffset(node, pos, idx + search.length),
+      }
+    }
+    return false // never descend into a textblock's inline children
+  })
+  return result
+}
+
+function buildDecorations(doc: PMNode, suggestions: Suggestion[]): DecorationSet {
+  const decos: Decoration[] = []
+  for (const s of suggestions) {
+    const range = findRange(doc, s.original)
+    if (!range) continue
+    decos.push(
+      Decoration.inline(range.from, range.to, {
+        class: `petal-suggestion petal-suggestion-${s.type}`,
+        'data-suggestion-id': s.id,
+      }),
+    )
+  }
+  return DecorationSet.create(doc, decos)
+}
+
+// setSuggestions pushes a new suggestion list into the plugin. Decorations are
+// rebuilt against the current document immediately.
+export function setSuggestions(state: EditorState, dispatch: (tr: Transaction) => void, suggestions: Suggestion[]) {
+  const tr = state.tr.setMeta(suggestionPluginKey, suggestions)
+  dispatch(tr)
+}
+
+export const SuggestionHighlight = Extension.create({
+  name: 'suggestionHighlight',
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin<PluginState>({
+        key: suggestionPluginKey,
+        state: {
+          init: () => ({ suggestions: [], decorations: DecorationSet.empty }),
+          apply(tr, value, _oldState, newState) {
+            const meta = tr.getMeta(suggestionPluginKey) as Suggestion[] | undefined
+            if (meta) {
+              return { suggestions: meta, decorations: buildDecorations(newState.doc, meta) }
+            }
+            // On any document change, re-anchor by string against the new doc.
+            if (tr.docChanged) {
+              return {
+                suggestions: value.suggestions,
+                decorations: buildDecorations(newState.doc, value.suggestions),
+              }
+            }
+            return value
+          },
+        },
+        props: {
+          decorations(state) {
+            return suggestionPluginKey.getState(state)?.decorations
+          },
+        },
+      }),
+    ]
+  },
+})