@cyber-dash-tech/revela 0.7.0 → 0.7.3

package/README.md

@@ -23,6 +23,7 @@ Enable it for the current session, assign a presentation task, and the agent can
 - uses workspace `DECKS.json` as machine-readable deck memory, slide spec, and prewrite readiness state
 - blocks premature writes to `decks/*.html` until the active deck is marked structurally ready
 - runs automatic layout QA whenever the agent writes `decks/*.html`
+- opens a visual comment editor for existing decks so users can Ctrl/Cmd-click elements and send precise edit requests back to OpenCode
 - exports finished decks to PDF and editable PPTX
 - switches designs and domains locally with zero LLM cost
 
@@ -139,6 +140,7 @@ Disable presentation mode when done:
 /revela init                     initialize or refresh workspace DECKS.json
 /revela review [slug]            review active deck readiness before writing HTML
 /revela remember <text>          save an explicit user/workflow preference
+/revela edit <target>            open visual comment editor for a deck slug or decks/*.html
 
 /revela designs                  list installed designs
 /revela designs <name>           activate a design
@@ -157,7 +159,7 @@ Disable presentation mode when done:
 /revela pptx <file>              export an HTML deck to editable PPTX in the same directory
 ```
 
-Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela review`, `/revela remember`, `/revela designs-new`, and `/revela designs-edit` start AI-assisted workflows because they need to read or update project files.
+Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela review`, `/revela remember`, `/revela designs-new`, and `/revela designs-edit` start AI-assisted workflows because they need to read or update project files. `/revela edit` opens a local visual editor and then sends user comments back into the current OpenCode session when the user submits them.
 
 ---
 
@@ -592,6 +594,23 @@ A custom domain is a folder containing `INDUSTRY.md`.
 
 ---
 
+## Visual Editing
+
+Open the visual editor for an existing deck by slug or workspace-relative HTML path:
+
+```text
+/revela edit my-deck
+/revela edit decks/my-deck.html
+```
+
+The editor opens in your browser. Use `Ctrl`/`Cmd` + click to reference deck elements, write a natural-language comment, then send it back to OpenCode. Revela sends a structured edit prompt that includes the deck file, slide context, selected element metadata, and your comment.
+
+LLM tool equivalent: `revela-edit` with `{ "target": "decks/my-deck.html" }`. This lets the agent open the same editor when you say things like “I want to edit @decks/my-deck.html”.
+
+`/revela edit` prepares minimal `DECKS.json` state for the existing HTML deck if needed, so the normal deck write gate can still protect `decks/*.html` while allowing targeted edits.
+
+---
+
 ## Export
 
 PDF export:

package/README.zh-CN.md

@@ -23,6 +23,7 @@ Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使
 - 使用工作区 `DECKS.json` 保存机器可读的 deck 记忆、逐页规格和写入前 readiness 状态
 - 在 active deck 结构化 ready 前，阻止过早写入 `decks/*.html`
 - agent 每次写入 `decks/*.html` 时自动执行布局 QA
+- 为已有 deck 打开可视化评论编辑器，用户可以 Ctrl/Cmd + 点击元素，并把精确修改意见发回 OpenCode
 - 支持导出成 PDF 和可编辑 PPTX
 - design 和 domain 的切换都在本地完成，不消耗 LLM token
 
@@ -138,6 +139,7 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 /revela init                     初始化或刷新工作区 DECKS.json
 /revela review [slug]            写 HTML 前检查 active deck readiness
 /revela remember <text>          保存明确的用户/工作流偏好
+/revela edit <target>            为 deck slug 或 decks/*.html 打开可视化评论编辑器
 
 /revela designs                  列出已安装 design
 /revela designs <name>           激活某个 design
@@ -156,7 +158,7 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 /revela pptx <file>              将 HTML deck 导出为同目录可编辑 PPTX
 ```
 
-大多数 `/revela` 命令都在本地执行，不消耗 LLM token。`/revela init`、`/revela review`、`/revela remember`、`/revela designs-new` 和 `/revela designs-edit` 会启动 AI 辅助流程，因为它们需要读取或更新项目状态。
+大多数 `/revela` 命令都在本地执行，不消耗 LLM token。`/revela init`、`/revela review`、`/revela remember`、`/revela designs-new` 和 `/revela designs-edit` 会启动 AI 辅助流程，因为它们需要读取或更新项目状态。`/revela edit` 会打开本地可视化编辑器，并在用户提交评论后把修改请求发回当前 OpenCode 会话。
 
 ---
 
@@ -557,6 +559,23 @@ Prompt 注入规则：
 
 ---
 
+## 可视化编辑
+
+可以通过 deck slug 或工作区相对 HTML 路径打开可视化编辑器：
+
+```text
+/revela edit my-deck
+/revela edit decks/my-deck.html
+```
+
+编辑器会在浏览器中打开。使用 `Ctrl`/`Cmd` + 点击 deck 元素来引用它们，写一段自然语言评论，然后发送回 OpenCode。Revela 会把 deck 文件、slide 上下文、选中元素 metadata 和你的评论整理成结构化 edit prompt。
+
+对应的 LLM tool：`revela-edit`，参数为 `{ "target": "decks/my-deck.html" }`。因此当你说“我要编辑 @decks/my-deck.html”时，agent 也可以主动打开同一个编辑器。
+
+如果已有 HTML deck 缺少 `DECKS.json` 状态，`/revela edit` 会自动准备最小 deck state，让正常的 `decks/*.html` 写入门禁仍然生效，同时允许后续精准修改。
+
+---
+
 ## 导出
 
 PDF 导出：

package/lib/commands/edit.ts

@@ -1,27 +1,4 @@
-import { existsSync } from "fs"
-import { ctx } from "../ctx"
-import { ACTIVE_PROMPT_FILE } from "../config"
-import { buildPrompt } from "../prompt-builder"
-import { resolveEditableDeck } from "../edit/resolve-deck"
-import { ensureEditableDeckState } from "../edit/deck-state"
-import { startEditServer } from "../edit/server"
-
-function openUrl(url: string): void {
-  if (process.platform === "darwin") {
-    const proc = Bun.spawnSync(["open", url])
-    if (proc.exitCode !== 0) throw new Error(proc.stderr.toString() || "Failed to open edit page")
-    return
-  }
-
-  if (process.platform === "win32") {
-    const proc = Bun.spawnSync(["cmd", "/c", "start", "", url])
-    if (proc.exitCode !== 0) throw new Error(proc.stderr.toString() || "Failed to open edit page")
-    return
-  }
-
-  const proc = Bun.spawnSync(["xdg-open", url])
-  if (proc.exitCode !== 0) throw new Error(proc.stderr.toString() || "Failed to open edit page")
-}
+import { openEditableDeck } from "../edit/open"
 
 export async function handleEdit(
   input: string,
@@ -35,32 +12,17 @@ export async function handleEdit(
   }
 
   try {
-    const deck = resolveEditableDeck(options.workspaceRoot, target)
-    const preflight = ensureEditableDeckState(options.workspaceRoot, deck)
-    if (!preflight.readiness.ready) {
-      await send(`**Edit blocked:** ${preflight.readiness.blocker || "Deck is not ready for HTML edits."}`)
-      return
-    }
-
-    ctx.enabled = true
-    if (!existsSync(ACTIVE_PROMPT_FILE)) buildPrompt()
-
-    const editServer = startEditServer()
-    const token = editServer.createSession({
+    const result = openEditableDeck(target, {
       client: options.client,
       sessionID: options.sessionID,
-      deck,
+      workspaceRoot: options.workspaceRoot,
     })
-    const url = `${editServer.baseUrl}/edit?token=${encodeURIComponent(token)}`
-    openUrl(url)
 
-    const source = deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path"
-    const stateNote = preflight.changed ? "Deck state was prepared in DECKS.json before opening the editor.\n" : "Deck state is ready in DECKS.json.\n"
     await send(
-      `Opened visual editor for deck \`${deck.slug}\`.\n` +
-      `File: \`${deck.file}\` (${source})\n` +
-      stateNote +
-      `URL: ${url}\n\n` +
+      `Opened visual editor for deck \`${result.deck.slug}\`.\n` +
+      `File: \`${result.deck.file}\` (${result.source})\n` +
+      `${result.stateNote}\n` +
+      `URL: ${result.url}\n\n` +
       `Use Ctrl/Cmd + click in the browser to reference elements, write a comment, then send comments. Revela mode has been enabled for the edit prompt.`
     )
   } catch (e: any) {

package/lib/config.ts

@@ -28,7 +28,7 @@ export const CONFIG_FILE = join(CONFIG_DIR, "config.json")
 export const ACTIVE_PROMPT_FILE = join(CONFIG_DIR, "_active-prompt.md")
 
 /** Default design name. */
-export const DEFAULT_DESIGN = "aurora"
+export const DEFAULT_DESIGN = "summit"
 
 /** Default domain name. */
 export const DEFAULT_DOMAIN = "general"

package/lib/edit/deck-state.ts

@@ -112,7 +112,7 @@ function safeActiveDesign(): string {
   try {
     return activeDesign()
   } catch {
-    return "aurora"
+    return "summit"
   }
 }
 

package/lib/edit/open.ts

@@ -0,0 +1,76 @@
+import { existsSync } from "fs"
+import { ctx } from "../ctx"
+import { ACTIVE_PROMPT_FILE } from "../config"
+import { seedBuiltinDesigns } from "../design/designs"
+import { seedBuiltinDomains } from "../domain/domains"
+import { buildPrompt } from "../prompt-builder"
+import { ensureEditableDeckState } from "./deck-state"
+import { resolveEditableDeck, type EditableDeck } from "./resolve-deck"
+import { startEditServer } from "./server"
+
+export interface OpenEditableDeckResult {
+  deck: EditableDeck
+  url: string
+  source: string
+  stateNote: string
+  preflightChanged: boolean
+}
+
+export interface OpenEditableDeckOptions {
+  client: any
+  sessionID: string
+  workspaceRoot: string
+  openBrowser?: boolean
+}
+
+export function openUrl(url: string): void {
+  if (process.platform === "darwin") {
+    const proc = Bun.spawnSync(["open", url])
+    if (proc.exitCode !== 0) throw new Error(proc.stderr.toString() || "Failed to open edit page")
+    return
+  }
+
+  if (process.platform === "win32") {
+    const proc = Bun.spawnSync(["cmd", "/c", "start", "", url])
+    if (proc.exitCode !== 0) throw new Error(proc.stderr.toString() || "Failed to open edit page")
+    return
+  }
+
+  const proc = Bun.spawnSync(["xdg-open", url])
+  if (proc.exitCode !== 0) throw new Error(proc.stderr.toString() || "Failed to open edit page")
+}
+
+export function openEditableDeck(target: string, options: OpenEditableDeckOptions): OpenEditableDeckResult {
+  const deck = resolveEditableDeck(options.workspaceRoot, target)
+  const preflight = ensureEditableDeckState(options.workspaceRoot, deck)
+  if (!preflight.readiness.ready) {
+    throw new Error(preflight.readiness.blocker || "Deck is not ready for HTML edits.")
+  }
+
+  ctx.enabled = true
+  if (!existsSync(ACTIVE_PROMPT_FILE)) {
+    seedBuiltinDesigns()
+    seedBuiltinDomains()
+    buildPrompt()
+  }
+
+  const editServer = startEditServer()
+  const token = editServer.createSession({
+    client: options.client,
+    sessionID: options.sessionID,
+    deck,
+  })
+  const url = `${editServer.baseUrl}/edit?token=${encodeURIComponent(token)}`
+  if (options.openBrowser !== false) openUrl(url)
+
+  const source = deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path"
+  const stateNote = preflight.changed ? "Deck state was prepared in DECKS.json before opening the editor." : "Deck state is ready in DECKS.json."
+
+  return {
+    deck,
+    url,
+    source,
+    stateNote,
+    preflightChanged: preflight.changed,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.7.0",
+  "version": "0.7.3",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",

package/plugin.ts

@@ -83,6 +83,7 @@ import extractDocumentMaterialsTool from "./tools/extract-document-materials"
 import qaTool from "./tools/qa"
 import pdfTool from "./tools/pdf"
 import pptxTool from "./tools/pptx"
+import createEditTool from "./tools/edit"
 import { RESEARCH_PROMPT, RESEARCH_AGENT_SIGNATURE } from "./lib/agents/research-prompt"
 import { runQA, formatReport } from "./lib/qa"
 import { extractDesignClasses } from "./lib/design/designs"
@@ -338,6 +339,7 @@ const server: Plugin = (async (pluginCtx) => {
       "revela-qa": qaTool,
       "revela-pdf": pdfTool,
       "revela-pptx": pptxTool,
+      "revela-edit": createEditTool({ client, workspaceRoot }),
     },
 
     // ── chat.message: intercept @-referenced / pasted binary files ────────

package/tools/edit.ts

@@ -0,0 +1,61 @@
+/**
+ * tools/edit.ts
+ *
+ * revela-edit — Open Revela's visual comment editor for an existing deck.
+ */
+
+import { tool } from "@opencode-ai/plugin"
+import { openEditableDeck } from "../lib/edit/open"
+
+export function createEditTool(options: { client: any; workspaceRoot: string; openBrowser?: boolean }) {
+  return tool({
+    description:
+      "Open Revela's visual comment editor for an existing slide deck. " +
+      "Use this when the user asks to edit, revise, annotate, or visually comment on a deck, " +
+      "including when they reference a decks/*.html file with @. " +
+      "Accepts either a deck slug from DECKS.json or a workspace-relative decks/*.html path. " +
+      "This opens a local browser editor where the user can Ctrl/Cmd-click deck elements, write comments, " +
+      "and send precise edit requests back to the current OpenCode session.",
+    args: {
+      target: tool.schema
+        .string()
+        .describe("Deck slug or workspace-relative deck HTML path, e.g. investor-update or decks/investor-update.html."),
+    },
+    async execute({ target }, context: any) {
+      const sessionID = context?.sessionID ?? context?.session?.id ?? ""
+      if (!sessionID) {
+        return JSON.stringify({
+          ok: false,
+          error: "Cannot open visual editor because the current OpenCode session id is unavailable.",
+        })
+      }
+
+      try {
+        const result = openEditableDeck(target, {
+          client: options.client,
+          sessionID,
+          workspaceRoot: options.workspaceRoot,
+          openBrowser: options.openBrowser,
+        })
+
+        return JSON.stringify({
+          ok: true,
+          deck: result.deck.slug,
+          file: result.deck.file,
+          source: result.source,
+          url: result.url,
+          message:
+            `${result.stateNote} Opened visual editor. ` +
+            "Ask the user to use Ctrl/Cmd + click in the browser to reference elements, write a comment, then send comments.",
+        }, null, 2)
+      } catch (error) {
+        return JSON.stringify({
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    },
+  })
+}
+
+export default createEditTool