@cyber-dash-tech/revela 0.6.2 → 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

@@ -0,0 +1,31 @@
+import { openEditableDeck } from "../edit/open"
+
+export async function handleEdit(
+  input: string,
+  options: { client: any; sessionID: string; workspaceRoot: string },
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  const target = input.trim()
+  if (!target) {
+    await send("**Usage:** `/revela edit <deck-slug|decks/file.html>`\n\nExamples: `/revela edit investor-update`, `/revela edit decks/investor-update.html`")
+    return
+  }
+
+  try {
+    const result = openEditableDeck(target, {
+      client: options.client,
+      sessionID: options.sessionID,
+      workspaceRoot: options.workspaceRoot,
+    })
+
+    await send(
+      `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) {
+    await send(`**Edit failed:** ${e.message || String(e)}`)
+  }
+}

package/lib/commands/help.ts

@@ -28,6 +28,7 @@ export async function handleHelp(
     `\`/revela disable\`             — disable slide generation mode\n` +
     `\`/revela init\`                — initialize or refresh workspace DECKS.json\n` +
     `\`/revela review [slug]\`       — review active deck readiness before writing HTML\n` +
+    `\`/revela edit <target>\`       — open visual comment editor for a deck slug or decks/*.html\n` +
     `\`/revela remember <text>\`     — save an explicit preference to DECKS.json\n` +
     `\`/revela designs\`             — list installed designs\n` +
     `\`/revela designs <name>\`      — activate a design\n` +

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

@@ -0,0 +1,125 @@
+import { readFileSync } from "fs"
+import { activeDesign } from "../design/designs"
+import { activeDomain } from "../domain/domains"
+import {
+  defaultRequiredInputs,
+  readOrCreateDecksState,
+  reviewDeckState,
+  upsertDeck,
+  upsertSlides,
+  writeDecksState,
+  type DeckStateReadinessResult,
+  type SlideSpec,
+} from "../decks-state"
+import type { EditableDeck } from "./resolve-deck"
+
+export interface EditDeckStatePreflightResult {
+  changed: boolean
+  readiness: DeckStateReadinessResult
+}
+
+export function ensureEditableDeckState(workspaceRoot: string, deck: EditableDeck): EditDeckStatePreflightResult {
+  let state = readOrCreateDecksState(workspaceRoot)
+  const existing = state.decks[deck.slug]
+  const existingReady = existing?.writeReadiness?.status === "ready" && existing.writeReadiness.blockers.length === 0
+  let changed = !existing || existing.outputPath !== deck.file
+
+  state = upsertDeck(state, {
+    ...existing,
+    slug: deck.slug,
+    goal: existing?.goal || `Edit existing Revela deck ${deck.slug}.`,
+    audience: existing?.audience || "Existing deck viewers",
+    language: existing?.language || "en",
+    slideCount: existing?.slideCount || inferSlideCount(deck.absoluteFile),
+    outputPath: deck.file,
+    theme: {
+      design: existing?.theme?.design || safeActiveDesign(),
+      domain: existing?.theme?.domain || safeActiveDomain(),
+    },
+    requiredInputs: defaultRequiredInputs({
+      ...existing?.requiredInputs,
+      topicClarified: true,
+      audienceClarified: true,
+      slideCountDecided: true,
+      languageDecided: true,
+      visualStyleSelected: true,
+      sourceMaterialsIdentified: true,
+      researchNeedAssessed: true,
+      researchFindingsRead: true,
+      slidePlanConfirmed: true,
+      designLayoutsFetched: true,
+    }),
+    researchPlan: existing?.researchPlan || [],
+  })
+
+  const current = state.decks[deck.slug]
+  if (current.slides.length === 0) {
+    state = upsertSlides(state, deck.slug, inferSlides(deck.absoluteFile))
+    changed = true
+  }
+
+  const reviewed = reviewDeckState(state, deck.slug)
+  writeDecksState(workspaceRoot, reviewed.state)
+
+  return {
+    changed: changed || !existingReady,
+    readiness: reviewed.result,
+  }
+}
+
+function inferSlideCount(filePath: string): number {
+  return inferSlides(filePath).length
+}
+
+function inferSlides(filePath: string): SlideSpec[] {
+  const html = readFileSync(filePath, "utf-8")
+  const chunks = html.match(/<section\b[\s\S]*?<\/section>/gi) || [html]
+  return chunks.map((chunk, index) => {
+    const title = extractTitle(chunk) || `Slide ${index + 1}`
+    return {
+      index: index + 1,
+      title,
+      purpose: "Existing HTML slide prepared for targeted visual edits.",
+      layout: "existing-html",
+      qa: /slide-qa=["']true["']/i.test(chunk),
+      components: ["existing-html"],
+      content: {
+        headline: title,
+        body: [extractText(chunk) || "Existing HTML slide content."],
+      },
+      evidence: [],
+      visuals: [],
+      status: "ready",
+      notes: "Inferred automatically by /revela edit preflight.",
+    }
+  })
+}
+
+function extractTitle(html: string): string {
+  const match = /<(?:h1|h2|h3|title)\b[^>]*>([\s\S]*?)<\/(?:h1|h2|h3|title)>/i.exec(html)
+  return normalizeText(match?.[1] || "").slice(0, 160)
+}
+
+function extractText(html: string): string {
+  return normalizeText(html.replace(/<script\b[\s\S]*?<\/script>/gi, " ").replace(/<style\b[\s\S]*?<\/style>/gi, " ").replace(/<[^>]+>/g, " ")).slice(0, 600)
+}
+
+function normalizeText(value: string): string {
+  return value.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/\s+/g, " ").trim()
+}
+
+function safeActiveDesign(): string {
+  try {
+    return activeDesign()
+  } catch {
+    return "summit"
+  }
+}
+
+function safeActiveDomain(): string {
+  try {
+    return activeDomain()
+  } catch {
+    return "general"
+  }
+}

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/lib/edit/prompt.ts

@@ -0,0 +1,81 @@
+export interface EditSelectedElementPayload {
+  slideIndex?: number
+  slideTitle?: string
+  selector?: string
+  domPath?: string
+  tagName?: string
+  id?: string
+  classList?: string[]
+  text?: string
+  outerHTMLExcerpt?: string
+  nearbyText?: string
+  boundingBox?: Record<string, unknown>
+  viewport?: Record<string, unknown>
+}
+
+export interface EditCommentDraftPayload {
+  comment: string
+  elements: EditSelectedElementPayload[]
+}
+
+export interface EditCommentPayload extends EditSelectedElementPayload {
+  deck: string
+  file: string
+  comment: string
+  elements?: EditSelectedElementPayload[]
+  comments?: EditCommentDraftPayload[]
+}
+
+export function buildEditPrompt(payload: EditCommentPayload): string {
+  const elements = payload.elements?.length
+    ? payload.elements
+    : [{
+        slideIndex: payload.slideIndex,
+        slideTitle: payload.slideTitle,
+        selector: payload.selector,
+        domPath: payload.domPath,
+        tagName: payload.tagName,
+        id: payload.id,
+        classList: payload.classList ?? [],
+        text: payload.text,
+        outerHTMLExcerpt: payload.outerHTMLExcerpt,
+        nearbyText: payload.nearbyText,
+        boundingBox: payload.boundingBox,
+        viewport: payload.viewport,
+      }]
+  const comments = payload.comments?.length
+    ? payload.comments
+    : [{
+        comment: payload.comment,
+        elements,
+      }]
+
+  const compact = {
+    deck: payload.deck,
+    file: payload.file,
+    comments,
+  }
+
+  return `The user left a visual edit comment on a Revela slide deck.
+
+Target deck: ${payload.deck}
+Target file: ${payload.file}
+
+Structured selection payload:
+
+\`\`\`json
+${JSON.stringify(compact, null, 2)}
+\`\`\`
+
+Instructions:
+- Make the smallest targeted change that satisfies the user's comment.
+- If there are multiple comments, apply them as one coherent edit pass and avoid changes from one comment overwriting another.
+- Each comment may reference one or more selected elements. Treat the elements in a single comment as a group.
+- Preserve the existing deck structure, active design language, typography, spacing system, animations, and slide count unless the comment explicitly asks otherwise.
+- Do not rewrite unrelated slides or broad sections of the deck.
+- Locate each target primarily with slideIndex, slideTitle, selected text, nearbyText, and outerHTMLExcerpt. Use selector/domPath as hints; they may be approximate.
+- Before patching or writing ${"`decks/*.html`"}, ensure ${"`DECKS.json`"} contains this deck and call ${"`revela-decks`"} with action ${"`review`"}. If ${"`DECKS.json`"} or the deck entry is missing, initialize/upsert the deck state with ${"`revela-decks`"} first. If readiness remains blocked, explain the blockers instead of forcing the edit.
+- Apply the edit to ${payload.file} only after readiness allows deck HTML changes.
+- After editing, run ${"`revela-qa`"} on ${payload.file} and fix any relevant regressions caused by the edit.
+- If the comment is ambiguous, ask one concise clarification question instead of guessing.`
+}

package/lib/edit/resolve-deck.ts

@@ -0,0 +1,99 @@
+import { existsSync } from "fs"
+import { basename, relative, resolve, sep } from "path"
+import { DECKS_STATE_FILE, hasDecksState, isDeckHtmlPath, readDecksState } from "../decks-state"
+
+export interface EditableDeck {
+  slug: string
+  file: string
+  absoluteFile: string
+  source: "decks-state" | "fallback" | "file-path"
+}
+
+export function resolveEditableDeck(workspaceRoot: string, input: string): EditableDeck {
+  const requested = input.trim()
+  if (!requested) throw new Error("Usage: /revela edit <deck-slug|decks/file.html>")
+
+  const slug = normalizeSlug(requested)
+
+  if (hasDecksState(workspaceRoot)) {
+    const state = readDecksState(workspaceRoot)
+    const deck = state.decks[requested] ?? (slug ? state.decks[slug] : undefined)
+    if (deck) {
+      return resolveDeckFile(workspaceRoot, deck.slug, deck.outputPath, "decks-state")
+    }
+  }
+
+  if (looksLikePath(requested)) {
+    return resolvePathTarget(workspaceRoot, requested)
+  }
+
+  if (!slug) throw new Error("Deck target must be a deck slug or decks/*.html path.")
+
+  return resolveDeckFile(workspaceRoot, slug, `decks/${slug}.html`, "fallback")
+}
+
+function resolvePathTarget(workspaceRoot: string, requested: string): EditableDeck {
+  if (isAbsoluteLike(requested)) {
+    throw new Error("/revela edit only accepts workspace-relative decks/*.html paths.")
+  }
+
+  const normalized = normalizePath(requested).replace(/^\.\//, "")
+  if (!isDeckHtmlPath(normalized)) {
+    throw new Error("/revela edit file paths must point to decks/*.html.")
+  }
+
+  const slug = normalizeSlug(basename(normalized, ".html"))
+  if (!slug) throw new Error("Deck target must be a deck slug or decks/*.html path.")
+  return resolveDeckFile(workspaceRoot, slug, normalized, "file-path")
+}
+
+function resolveDeckFile(
+  workspaceRoot: string,
+  slug: string,
+  file: string,
+  source: EditableDeck["source"],
+): EditableDeck {
+  if (!isDeckHtmlPath(file)) {
+    throw new Error(`${DECKS_STATE_FILE} deck outputPath must be decks/*.html, got ${file || "missing"}.`)
+  }
+
+  const root = resolve(workspaceRoot)
+  const absoluteFile = resolve(root, file)
+  if (!isInside(root, absoluteFile)) {
+    throw new Error(`Resolved deck file is outside the workspace: ${file}`)
+  }
+  if (!existsSync(absoluteFile)) {
+    throw new Error(`Deck HTML not found: ${workspaceRelative(root, absoluteFile)}`)
+  }
+
+  return {
+    slug: normalizeSlug(slug),
+    file: workspaceRelative(root, absoluteFile),
+    absoluteFile,
+    source,
+  }
+}
+
+function isInside(root: string, target: string): boolean {
+  return target === root || target.startsWith(root.endsWith(sep) ? root : root + sep)
+}
+
+function workspaceRelative(root: string, target: string): string {
+  return relative(root, target).split(sep).join("/")
+}
+
+function looksLikePath(value: string): boolean {
+  return value.includes("/") || value.includes("\\") || value.endsWith(".html")
+}
+
+function isAbsoluteLike(value: string): boolean {
+  return value.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(value)
+}
+
+function normalizePath(value: string): string {
+  return value.replace(/\\/g, "/")
+}
+
+function normalizeSlug(value: string): string {
+  return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "")
+}