@cyber-dash-tech/revela 0.18.4 → 0.18.5

package/README.md

@@ -2,7 +2,7 @@
 
 **English** | [中文](README.zh-CN.md)
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-691%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-709%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
@@ -34,8 +34,8 @@ To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 Requirements:
 
 - The Codex CLI must be installed and the `codex` command must be available in your shell.
-- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.4 mcp` to start the MCP server.
-- For interactive Review actions, `codex exec` must also work because the Review UI uses it for Comment/Apply Fix requests.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.18.5 mcp` to start the MCP server.
+- For interactive Review Apply actions, `codex exec` must also work because the Review UI uses it after saved comments are applied.
 
 Optional preflight:
 
@@ -55,16 +55,18 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 Install Revela through the Codex Git marketplace:
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.4
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.5
 codex plugin add revela@revela
 ```
 
-The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.18.4 mcp` so npm can fetch the published package and its dependencies.
+The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.18.5 mcp` so npm can fetch the published package and its dependencies.
 
 You do not need to run `bun install` inside the Codex marketplace clone.
 
 Start a new Codex thread after installing so Codex loads the Revela skills, MCP tools, and hooks.
 
+Codex uses five Revela skills: `revela-helper` for status and active design/domain, `revela-research` for local and web research saved under `researches/`, `revela-make-deck` for design-aware `deck-plan.md` plus `decks/*.html`, `revela-review` for the Review UI, and `revela-export` for PDF/PPTX/PNG.
+
 For release-aligned local validation, run `bun run smoke:mcp-pack`. It packs the current checkout to a temporary npm tarball and starts the MCP server through `npx`, matching the published Codex launcher path without requiring a registry publish.
 
 #### Codex Upgrade

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | **中文**
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-691%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-709%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="560" />
@@ -34,8 +34,8 @@ Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材
 环境要求：
 
 - 需要已安装 Codex CLI，并且 shell 中可以执行 `codex`。
-- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.4 mcp` 启动 MCP server。
-- 如果使用 Review UI 的 Comment 或 Apply Fix，需要 `codex exec` 可用。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.18.5 mcp` 启动 MCP server。
+- 如果使用 Review UI 的 Apply，需要 `codex exec` 可用；评论会先保存，点击 Apply 后才执行修复。
 
 可选的安装前检查：
 
@@ -55,16 +55,18 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 通过 Codex Git marketplace 安装 Revela：
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.4
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.5
 codex plugin add revela@revela
 ```
 
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.4 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.18.5 mcp`，由 npm 获取已发布 package 及其 dependencies。
 
 不需要在 Codex marketplace clone 里运行 `bun install`。
 
 安装后开启一个新的 Codex thread，让 Codex 加载 Revela 的 skills、MCP tools 和 hooks。
 
+Codex 使用五个 Revela skills：`revela-helper` 查看状态和 active design/domain，`revela-research` 调研本地与网络资料并保存到 `researches/`，`revela-make-deck` 基于 design 工具生成 `deck-plan.md` 和 `decks/*.html`，`revela-review` 打开 Review UI，`revela-export` 导出 PDF/PPTX/PNG。
+
 如果要按发布路径做本地验证，运行 `bun run smoke:mcp-pack`。它会把当前 checkout 打成临时 npm tarball，再通过 `npx` 启动 MCP server，不需要先发布到 registry。
 
 #### Codex 升级

package/lib/commands/refine.ts

@@ -18,7 +18,7 @@ export async function handleRefine(
       `File: \`${result.deck.file}\`\n` +
       `${result.stateNote}\n` +
       `URL: ${result.url}\n\n` +
-      `Use Ctrl/Cmd-click in the browser to reference deck elements. The Comment tab sends targeted change comments and applies deck edits after artifact QA.`
+      `Use Ctrl/Cmd-click in the browser to reference deck elements. The Comment tab saves targeted comments; use Apply on a saved comment to run deck edits.`
     )
   } catch (e: any) {
     await send(`**Review failed:** ${e.message || String(e)}`)

package/lib/refine/comment-requests.ts

@@ -13,7 +13,7 @@ export interface PendingCommentRequest {
   raw?: string
 }
 
-const REQUEST_TTL_MS = 120 * 1000
+const REQUEST_TTL_MS = 360 * 1000
 const requests = new Map<string, PendingCommentRequest>()
 const subscribers = new Map<string, Set<(event: ReviewBridgeEvent) => void>>()
 

package/lib/refine/prompt-bridge.ts

@@ -36,6 +36,9 @@ export interface CodexExecRunResult {
   stderr: string
 }
 
+const DEFAULT_COMMENT_TIMEOUT_MS = 300_000
+const DEFAULT_INSPECT_TIMEOUT_MS = 120_000
+
 export type CodexExecRunner = (input: {
   action: ReviewPromptAction
   prompt: string
@@ -71,39 +74,57 @@ export function createOpenCodeReviewPromptBridge(client: any, sessionID: string)
 export function createCodexExecReviewPromptBridge(options: {
   runner?: CodexExecRunner
   timeoutMs?: number
+  heartbeatMs?: number
 } = {}): ReviewPromptBridge {
   const runner = options.runner ?? runCodexExec
-  const timeoutMs = options.timeoutMs ?? 120_000
+  const heartbeatMs = options.heartbeatMs ?? 10_000
   return {
     kind: "codex-exec",
     async send(input) {
       const sandboxMode = input.action === "comment" ? "workspace-write" : "read-only"
+      const timeoutMs = input.timeoutMs ?? options.timeoutMs ?? (input.action === "comment" ? DEFAULT_COMMENT_TIMEOUT_MS : DEFAULT_INSPECT_TIMEOUT_MS)
       input.onEvent?.(bridgeEvent("started", "Starting Codex..."))
-      const output = await runner({
-        action: input.action,
-        prompt: input.prompt,
-        workspaceRoot: input.workspaceRoot,
-        timeoutMs: input.timeoutMs ?? timeoutMs,
-        sandboxMode,
-        skipGitRepoCheck: true,
-        onEvent: input.onEvent,
-      })
+      const startedAt = Date.now()
+      const heartbeat = input.onEvent
+        ? setInterval(() => {
+          const elapsedSeconds = Math.max(1, Math.round((Date.now() - startedAt) / 1000))
+          input.onEvent?.(bridgeEvent("codex_event", "Codex is still working...", `elapsedSeconds=${elapsedSeconds}`))
+        }, heartbeatMs)
+        : undefined
+      let output: CodexExecRunResult
+      try {
+        output = await runner({
+          action: input.action,
+          prompt: input.prompt,
+          workspaceRoot: input.workspaceRoot,
+          timeoutMs,
+          sandboxMode,
+          skipGitRepoCheck: true,
+          onEvent: input.onEvent,
+        })
+      } finally {
+        if (heartbeat) clearInterval(heartbeat)
+      }
       const raw = [output.stdout, output.stderr].filter(Boolean).join("\n")
-      if (output.exitCode !== 0) {
-        input.onEvent?.(bridgeEvent("failed", `codex exec failed with exit code ${output.exitCode ?? "unknown"}.`, boundedTail(raw)))
+      if (input.action === "comment" && isCodexWriteBlocked(raw)) {
+        input.onEvent?.(bridgeEvent("failed", "codex exec could not write the deck because its sandbox blocked file changes.", boundedTail(raw)))
         return {
           ok: false,
           status: "failed",
-          error: `codex exec failed with exit code ${output.exitCode ?? "unknown"}.`,
+          error: "codex exec could not write the deck because its sandbox blocked file changes.",
           raw,
         }
       }
-      if (input.action === "comment" && isCodexWriteBlocked(raw)) {
-        input.onEvent?.(bridgeEvent("failed", "codex exec could not write the deck because its sandbox blocked file changes.", boundedTail(raw)))
+      if (output.exitCode !== 0) {
+        if (input.action === "comment" && output.exitCode === 124 && hasTrustedCodexCompletion(output.stdout)) {
+          input.onEvent?.(bridgeEvent("completed", "Codex completed."))
+          return { ok: true, status: "completed", raw }
+        }
+        input.onEvent?.(bridgeEvent("failed", `codex exec failed with exit code ${output.exitCode ?? "unknown"}.`, boundedTail(raw)))
         return {
           ok: false,
           status: "failed",
-          error: "codex exec could not write the deck because its sandbox blocked file changes.",
+          error: `codex exec failed with exit code ${output.exitCode ?? "unknown"}.`,
           raw,
         }
       }
@@ -146,6 +167,7 @@ async function runCodexExec(input: {
     let stdout = ""
     let stderr = ""
     let stdoutLineBuffer = ""
+    let sawTrustedCompletion = false
     let resolved = false
     const resolveOnce = (output: CodexExecRunResult) => {
       if (resolved) return
@@ -155,7 +177,11 @@ async function runCodexExec(input: {
     const timer = setTimeout(() => {
       child.kill()
       const nextStderr = `${stderr}${stderr ? "\n" : ""}codex exec timed out after ${input.timeoutMs}ms.`
-      input.onEvent?.(bridgeEvent("timeout", "Codex timed out before completing.", boundedTail(nextStderr)))
+      if (input.action === "comment" && sawTrustedCompletion) {
+        input.onEvent?.(bridgeEvent("completed", "Codex completed."))
+      } else {
+        input.onEvent?.(bridgeEvent("timeout", "Codex timed out before completing.", boundedTail(nextStderr)))
+      }
       resolveOnce({
         exitCode: 124,
         stdout,
@@ -165,7 +191,9 @@ async function runCodexExec(input: {
     child.stdout?.on("data", (chunk) => {
       const text = chunk.toString()
       stdout += text
-      stdoutLineBuffer = emitCodexJsonProgress(stdoutLineBuffer + text, input.action, input.onEvent)
+      const progress = emitCodexJsonProgress(stdoutLineBuffer + text, input.action, input.onEvent)
+      stdoutLineBuffer = progress.remainder
+      sawTrustedCompletion = sawTrustedCompletion || progress.sawTrustedCompletion
     })
     child.stderr?.on("data", (chunk) => {
       const text = chunk.toString()
@@ -179,17 +207,20 @@ async function runCodexExec(input: {
     })
     child.on("close", (code) => {
       clearTimeout(timer)
-      emitCodexJsonProgress(`${stdoutLineBuffer}\n`, input.action, input.onEvent)
+      const progress = emitCodexJsonProgress(`${stdoutLineBuffer}\n`, input.action, input.onEvent)
+      sawTrustedCompletion = sawTrustedCompletion || progress.sawTrustedCompletion
       resolveOnce({ exitCode: code, stdout, stderr })
     })
   })
 }
 
-function emitCodexJsonProgress(buffer: string, action: ReviewPromptAction, onEvent?: (event: ReviewBridgeEvent) => void): string {
+function emitCodexJsonProgress(buffer: string, action: ReviewPromptAction, onEvent?: (event: ReviewBridgeEvent) => void): { remainder: string; sawTrustedCompletion: boolean } {
   const lines = buffer.split(/\r?\n/)
   const remainder = lines.pop() ?? ""
+  let sawTrustedCompletion = false
   for (const line of lines) {
     const parsed = parseJson(line)
+    sawTrustedCompletion = sawTrustedCompletion || isTrustedCodexCompletionRecord(parsed)
     const message = codexProgressMessage(parsed, action)
     if (message) {
       onEvent?.(bridgeEvent("codex_event", message, boundedTail(line)))
@@ -197,7 +228,7 @@ function emitCodexJsonProgress(buffer: string, action: ReviewPromptAction, onEve
       onEvent?.(bridgeEvent("stdout", "Codex wrote output.", boundedTail(line)))
     }
   }
-  return remainder
+  return { remainder, sawTrustedCompletion }
 }
 
 function codexProgressMessage(value: unknown, action: ReviewPromptAction): string | undefined {
@@ -207,14 +238,18 @@ function codexProgressMessage(value: unknown, action: ReviewPromptAction): strin
   const event = typeof record.event === "string" ? record.event.toLowerCase() : ""
   const name = `${type} ${event}`
   if (!name.trim()) return undefined
-  if (name.includes("turn_completed") || name.includes("completed")) {
+  const normalized = name.replace(/[._-]+/g, " ")
+  if (normalized.includes("turn completed") || normalized.includes("thread completed") || normalized.includes("completed")) {
     return action === "comment" ? undefined : "Codex completed the inspection."
   }
-  if (name.includes("exec") || name.includes("patch") || name.includes("tool") || name.includes("apply")) {
+  if (normalized.includes("thread started") || normalized.includes("turn started") || normalized.includes("session started")) {
+    return "Codex started reading the deck..."
+  }
+  if (normalized.includes("exec") || normalized.includes("patch") || normalized.includes("tool") || normalized.includes("apply")) {
     return action === "comment" ? "Codex is applying the requested edit..." : "Codex is reading the deck..."
   }
-  if (name.includes("session") || name.includes("turn") || name.includes("start")) return "Codex is reading the deck..."
-  if (name.includes("message") || name.includes("delta") || name.includes("agent")) return "Codex is working..."
+  if (normalized.includes("session") || normalized.includes("thread") || normalized.includes("turn") || normalized.includes("start")) return "Codex is reading the deck..."
+  if (normalized.includes("message") || normalized.includes("delta") || normalized.includes("agent")) return "Codex is working..."
   return "Codex is working..."
 }
 
@@ -227,6 +262,40 @@ function boundedTail(text: string, limit = 4096): string {
   return text.slice(text.length - limit)
 }
 
+function hasTrustedCodexCompletion(stdout: string): boolean {
+  for (const line of stdout.split(/\r?\n/)) {
+    const parsed = parseJson(line)
+    if (isTrustedCodexCompletionRecord(parsed)) return true
+  }
+  for (const block of extractJsonBlocks(stdout)) {
+    const parsed = parseJson(block)
+    if (isTrustedCodexCompletionRecord(parsed)) return true
+  }
+  return false
+}
+
+function isTrustedCodexCompletionRecord(value: unknown): boolean {
+  if (!value) return false
+  if (typeof value === "string") return isTrustedCodexCompletionRecord(parseJson(value))
+  if (Array.isArray(value)) return value.some((item) => isTrustedCodexCompletionRecord(item))
+  if (typeof value !== "object") return false
+
+  const record = value as Record<string, unknown>
+  const type = typeof record.type === "string" ? record.type.toLowerCase() : ""
+  const event = typeof record.event === "string" ? record.event.toLowerCase() : ""
+  const status = typeof record.status === "string" ? record.status.toLowerCase() : ""
+  const normalized = `${type} ${event}`.replace(/[._-]+/g, " ")
+  const exitCode = typeof record.exit_code === "number" ? record.exit_code : typeof record.exitCode === "number" ? record.exitCode : undefined
+
+  if (normalized.includes("turn completed") || normalized.includes("thread completed")) return true
+  if (status === "completed" && exitCode === 0) return true
+
+  for (const key of ["item", "result", "output", "event", "payload"]) {
+    if (isTrustedCodexCompletionRecord(record[key])) return true
+  }
+  return false
+}
+
 function isCodexWriteBlocked(raw: string): boolean {
   const text = raw.toLowerCase()
   return (

package/lib/refine/review-comments.ts

@@ -0,0 +1,203 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs"
+import { join } from "path"
+import { randomBytes } from "crypto"
+import { workspaceMetaPath } from "../workspace-meta"
+
+export type ReviewCommentStatus = "open" | "queued" | "applying" | "applied" | "failed"
+
+export interface ReviewCommentRecord {
+  id: string
+  deckFile: string
+  slideIndex: number
+  deckVersion: string
+  comment: string
+  elements: any[]
+  asset?: any
+  drop?: any
+  status: ReviewCommentStatus
+  createdAt: string
+  updatedAt: string
+  lastApplyRequestId?: string
+  lastApplyError?: string
+  lastApplyRaw?: string
+}
+
+export interface ReviewCommentCreateInput {
+  deckFile: string
+  deckVersion: string
+  comment: string
+  elements: any[]
+  asset?: any
+  drop?: any
+}
+
+export function createReviewComment(workspaceRoot: string, input: ReviewCommentCreateInput): ReviewCommentRecord {
+  const comment = input.comment.trim()
+  if (!comment) throw new Error("Comment is required")
+  const elements = Array.isArray(input.elements) ? input.elements : []
+  const slideIndex = deriveSlideIndex(elements)
+  const now = new Date().toISOString()
+  const record: ReviewCommentRecord = {
+    id: randomBytes(10).toString("base64url"),
+    deckFile: normalizeDeckFile(input.deckFile),
+    slideIndex,
+    deckVersion: input.deckVersion,
+    comment,
+    elements,
+    ...(input.asset ? { asset: input.asset } : {}),
+    ...(input.drop ? { drop: input.drop } : {}),
+    status: "open",
+    createdAt: now,
+    updatedAt: now,
+  }
+  writeReviewComment(workspaceRoot, record)
+  return record
+}
+
+export function listReviewComments(workspaceRoot: string, deckFile: string): ReviewCommentRecord[] {
+  const file = normalizeDeckFile(deckFile)
+  const dir = reviewCommentsDir(workspaceRoot)
+  if (!existsSync(dir)) return []
+  const registry = readRegistry(workspaceRoot)
+  const records = registry.commentIds
+    .map((id) => readReviewComment(workspaceRoot, id))
+    .filter((record): record is ReviewCommentRecord => Boolean(record))
+  return records
+    .filter((record) => record.deckFile === file)
+    .sort((a, b) => a.slideIndex - b.slideIndex || a.createdAt.localeCompare(b.createdAt))
+}
+
+export function readReviewComment(workspaceRoot: string, id: string): ReviewCommentRecord | undefined {
+  const safeId = normalizeId(id)
+  if (!safeId) return undefined
+  const path = reviewCommentPath(workspaceRoot, safeId)
+  if (!existsSync(path)) return undefined
+  return JSON.parse(readFileSync(path, "utf-8")) as ReviewCommentRecord
+}
+
+export function markReviewCommentApplying(workspaceRoot: string, id: string, requestId: string): ReviewCommentRecord | undefined {
+  return updateReviewComment(workspaceRoot, id, (record) => ({
+    ...record,
+    status: "applying",
+    lastApplyRequestId: requestId,
+    lastApplyError: undefined,
+    lastApplyRaw: undefined,
+  }))
+}
+
+export function markReviewCommentQueued(workspaceRoot: string, id: string): ReviewCommentRecord | undefined {
+  return updateReviewComment(workspaceRoot, id, (record) => ({
+    ...record,
+    status: "queued",
+    lastApplyError: undefined,
+    lastApplyRaw: undefined,
+  }))
+}
+
+export function markReviewCommentApplied(workspaceRoot: string, id: string): ReviewCommentRecord | undefined {
+  return updateReviewComment(workspaceRoot, id, (record) => ({
+    ...record,
+    status: "applied",
+    lastApplyError: undefined,
+    lastApplyRaw: undefined,
+  }))
+}
+
+export function markReviewCommentFailed(workspaceRoot: string, id: string, error: string, raw?: string): ReviewCommentRecord | undefined {
+  return updateReviewComment(workspaceRoot, id, (record) => ({
+    ...record,
+    status: "failed",
+    lastApplyError: error,
+    ...(raw ? { lastApplyRaw: boundedTail(raw) } : {}),
+  }))
+}
+
+export function markReviewCommentStopped(workspaceRoot: string, id: string): ReviewCommentRecord | undefined {
+  return markReviewCommentFailed(workspaceRoot, id, "Stopped by user.", "Stopped by user.")
+}
+
+export function deleteReviewComment(workspaceRoot: string, id: string): boolean {
+  const safeId = normalizeId(id)
+  if (!safeId) return false
+  const path = reviewCommentPath(workspaceRoot, safeId)
+  if (!existsSync(path)) return false
+  unlinkSync(path)
+  const registry = readRegistry(workspaceRoot)
+  writeRegistry(workspaceRoot, {
+    version: 1,
+    commentIds: registry.commentIds.filter((item) => item !== safeId),
+  })
+  return true
+}
+
+function updateReviewComment(
+  workspaceRoot: string,
+  id: string,
+  update: (record: ReviewCommentRecord) => ReviewCommentRecord,
+): ReviewCommentRecord | undefined {
+  const record = readReviewComment(workspaceRoot, id)
+  if (!record) return undefined
+  const next = { ...update(record), updatedAt: new Date().toISOString() }
+  writeReviewComment(workspaceRoot, next)
+  return next
+}
+
+function writeReviewComment(workspaceRoot: string, record: ReviewCommentRecord): void {
+  const registry = readRegistry(workspaceRoot)
+  const dir = reviewCommentsDir(workspaceRoot)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(reviewCommentPath(workspaceRoot, record.id), `${JSON.stringify(record, null, 2)}\n`, "utf-8")
+  if (!registry.commentIds.includes(record.id)) {
+    registry.commentIds.push(record.id)
+    writeRegistry(workspaceRoot, registry)
+  }
+}
+
+function readRegistry(workspaceRoot: string): { version: 1; commentIds: string[] } {
+  const path = join(reviewCommentsDir(workspaceRoot), "registry.json")
+  if (!existsSync(path)) return { version: 1, commentIds: [] }
+  const parsed = JSON.parse(readFileSync(path, "utf-8")) as { version?: number; commentIds?: unknown[] }
+  return {
+    version: 1,
+    commentIds: Array.isArray(parsed.commentIds) ? parsed.commentIds.filter((item): item is string => typeof item === "string") : [],
+  }
+}
+
+function writeRegistry(workspaceRoot: string, registry: { version: 1; commentIds: string[] }): void {
+  const dir = reviewCommentsDir(workspaceRoot)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, "registry.json"), `${JSON.stringify(registry, null, 2)}\n`, "utf-8")
+}
+
+function reviewCommentsDir(workspaceRoot: string): string {
+  return workspaceMetaPath(workspaceRoot, "review-comments")
+}
+
+function reviewCommentPath(workspaceRoot: string, id: string): string {
+  return join(reviewCommentsDir(workspaceRoot), `${id}.json`)
+}
+
+function normalizeDeckFile(file: string): string {
+  return file.replace(/\\/g, "/").replace(/^\.\//, "")
+}
+
+function normalizeId(id: string): string {
+  const trimmed = id.trim()
+  return /^[A-Za-z0-9_-]+$/.test(trimmed) ? trimmed : ""
+}
+
+function deriveSlideIndex(elements: any[]): number {
+  const indexes = new Set<number>()
+  for (const element of elements) {
+    const value = element?.slideIndex
+    if (Number.isInteger(value) && value > 0) indexes.add(value)
+  }
+  if (indexes.size === 0) throw new Error("Comment must reference one slide. Ctrl/Cmd-click an element on the target slide first.")
+  if (indexes.size > 1) throw new Error("Comment references multiple slides. Split this into per-slide comments before applying fixes.")
+  return [...indexes][0]
+}
+
+function boundedTail(text: string, limit = 4096): string {
+  if (text.length <= limit) return text
+  return text.slice(text.length - limit)
+}