@cyber-dash-tech/revela 0.6.2 → 0.7.0

package/lib/commands/edit.ts

@@ -0,0 +1,69 @@
+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")
+}
+
+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 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({
+      client: options.client,
+      sessionID: options.sessionID,
+      deck,
+    })
+    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` +
+      `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/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 "aurora"
+  }
+}
+
+function safeActiveDomain(): string {
+  try {
+    return activeDomain()
+  } catch {
+    return "general"
+  }
+}

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, "")
+}

package/lib/edit/server.ts

@@ -0,0 +1,851 @@
+import { randomBytes } from "crypto"
+import { readFileSync, statSync } from "fs"
+import type { EditableDeck } from "./resolve-deck"
+import { buildEditPrompt, type EditCommentPayload } from "./prompt"
+
+const TOKEN_BYTES = 24
+const SESSION_TTL_MS = 2 * 60 * 60 * 1000
+const IDLE_STOP_MS = 30 * 60 * 1000
+
+interface EditSession {
+  token: string
+  client: any
+  sessionID: string
+  deck: string
+  file: string
+  absoluteFile: string
+  createdAt: number
+  lastActiveAt: number
+}
+
+export interface EditServerHandle {
+  baseUrl: string
+  createSession(input: { client: any; sessionID: string; deck: EditableDeck }): string
+}
+
+let server: ReturnType<typeof Bun.serve> | undefined
+let baseUrl = ""
+let idleTimer: Timer | undefined
+const sessions = new Map<string, EditSession>()
+
+export function startEditServer(): EditServerHandle {
+  if (!server) {
+    server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch: handleRequest,
+    })
+    baseUrl = `http://127.0.0.1:${server.port}`
+    scheduleIdleStop()
+  }
+
+  return {
+    baseUrl,
+    createSession(input) {
+      cleanupExpiredSessions()
+      const token = randomBytes(TOKEN_BYTES).toString("base64url")
+      sessions.set(token, {
+        token,
+        client: input.client,
+        sessionID: input.sessionID,
+        deck: input.deck.slug,
+        file: input.deck.file,
+        absoluteFile: input.deck.absoluteFile,
+        createdAt: Date.now(),
+        lastActiveAt: Date.now(),
+      })
+      return token
+    },
+  }
+}
+
+async function handleRequest(req: Request): Promise<Response> {
+  cleanupExpiredSessions()
+  const url = new URL(req.url)
+
+  if (url.pathname === "/health") return textResponse("ok")
+
+  if (url.pathname === "/edit" && req.method === "GET") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return htmlResponse(renderEditorShell(session.value.token))
+  }
+
+  if (url.pathname === "/deck" && req.method === "GET") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return htmlResponse(readFileSync(session.value.absoluteFile, "utf-8"))
+  }
+
+  if (url.pathname === "/api/comment" && req.method === "POST") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return handleComment(req, session.value)
+  }
+
+  if (url.pathname === "/api/deck-version" && req.method === "GET") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return handleDeckVersion(session.value)
+  }
+
+  return textResponse("Not found", 404)
+}
+
+function handleDeckVersion(session: EditSession): Response {
+  try {
+    const stat = statSync(session.absoluteFile)
+    session.lastActiveAt = Date.now()
+    scheduleIdleStop()
+    return jsonResponse({ ok: true, mtimeMs: stat.mtimeMs, size: stat.size })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return jsonResponse({ ok: false, error: message }, 404)
+  }
+}
+
+async function handleComment(req: Request, session: EditSession): Promise<Response> {
+  let body: Partial<EditCommentPayload>
+  try {
+    body = await req.json()
+  } catch {
+    return jsonResponse({ ok: false, error: "Invalid JSON body" }, 400)
+  }
+
+  const comments = Array.isArray(body.comments)
+    ? body.comments
+      .map((draft: any) => ({
+        comment: typeof draft?.comment === "string" ? draft.comment.trim() : "",
+        elements: Array.isArray(draft?.elements) ? draft.elements : [],
+      }))
+      .filter((draft) => draft.comment && draft.elements.length > 0)
+    : []
+  const comment = typeof body.comment === "string" ? body.comment.trim() : ""
+  const elements = Array.isArray(body.elements) ? body.elements : []
+  if (!comment && comments.length === 0) return jsonResponse({ ok: false, error: "Comment is required" }, 400)
+
+  const prompt = buildEditPrompt({
+    ...body,
+    deck: session.deck,
+    file: session.file,
+    comment,
+    elements,
+    comments,
+  })
+
+  await session.client.session.prompt({
+    path: { id: session.sessionID },
+    body: {
+      parts: [{ type: "text", text: prompt }],
+    },
+  })
+
+  session.lastActiveAt = Date.now()
+  scheduleIdleStop()
+  return jsonResponse({ ok: true })
+}
+
+function validateSession(token: string | null): { ok: true; value: EditSession } | { ok: false; response: Response } {
+  if (!token) return { ok: false, response: textResponse("Missing token", 401) }
+  const session = sessions.get(token)
+  if (!session) return { ok: false, response: textResponse("Invalid or expired token", 401) }
+  if (Date.now() - session.createdAt > SESSION_TTL_MS) {
+    sessions.delete(token)
+    return { ok: false, response: textResponse("Expired token", 401) }
+  }
+  session.lastActiveAt = Date.now()
+  return { ok: true, value: session }
+}
+
+function cleanupExpiredSessions(): void {
+  const now = Date.now()
+  for (const [token, session] of sessions) {
+    if (now - session.createdAt > SESSION_TTL_MS) sessions.delete(token)
+  }
+}
+
+function scheduleIdleStop(): void {
+  if (idleTimer) clearTimeout(idleTimer)
+  idleTimer = setTimeout(() => {
+    const now = Date.now()
+    const active = [...sessions.values()].some((session) => now - session.lastActiveAt < IDLE_STOP_MS)
+    if (active) {
+      scheduleIdleStop()
+      return
+    }
+    sessions.clear()
+    server?.stop()
+    server = undefined
+    baseUrl = ""
+    idleTimer = undefined
+  }, IDLE_STOP_MS)
+}
+
+function htmlResponse(body: string, status = 200): Response {
+  return new Response(body, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store, max-age=0",
+    },
+  })
+}
+
+function textResponse(body: string, status = 200): Response {
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/plain; charset=utf-8" },
+  })
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" },
+  })
+}
+
+function renderEditorShell(token: string): string {
+  const encodedToken = JSON.stringify(token)
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Revela Edit</title>
+  <style>
+    :root { color-scheme: dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    * { box-sizing: border-box; }
+    body { margin: 0; background: #0d1117; color: #f0f6fc; height: 100vh; overflow: hidden; }
+    .app { display: grid; grid-template-columns: minmax(0, 1fr) 380px; height: 100vh; }
+    .preview { position: relative; min-width: 0; background: #05070a; border-right: 1px solid #30363d; }
+    iframe { display: block; width: 100%; height: 100%; border: 0; background: white; }
+    .hitbox { position: absolute; inset: 0; z-index: 2; cursor: crosshair; background: transparent; }
+    aside { display: flex; flex-direction: column; gap: 16px; padding: 18px; background: #111827; }
+    h1 { margin: 0; font-size: 18px; line-height: 1.2; }
+    .hint { margin: 0; color: #9ca3af; font-size: 13px; line-height: 1.5; }
+    .panel { display: flex; flex-direction: column; gap: 10px; }
+    .label { color: #9ca3af; font-size: 12px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; }
+    .comment-editor { width: 100%; min-height: 160px; max-height: 42vh; overflow: auto; padding: 12px; border: 1px solid #374151; border-radius: 12px; background: #020617; color: #f8fafc; font: inherit; line-height: 1.5; outline: none; white-space: pre-wrap; }
+    .comment-editor:focus { border-color: #38bdf8; box-shadow: 0 0 0 2px rgba(56,189,248,.18); }
+    .comment-editor:empty::before { content: attr(data-placeholder); color: #64748b; pointer-events: none; }
+    .ref-chip { display: inline-flex; align-items: center; margin: 0 2px; padding: 1px 6px; border-radius: 999px; background: rgba(56,189,248,.18); color: #bae6fd; border: 1px solid rgba(56,189,248,.45); font-weight: 700; white-space: nowrap; }
+    .comment-thread { display: flex; flex-direction: column; gap: 10px; max-height: 30vh; overflow: auto; }
+    .comment-bubble { border: 1px solid #374151; border-radius: 14px; padding: 10px 12px; background: #0f172a; color: #e5e7eb; font-size: 13px; line-height: 1.45; }
+    .comment-bubble.sending { border-color: rgba(56,189,248,.5); background: rgba(14,116,144,.14); }
+    .comment-bubble.done { border-color: rgba(34,197,94,.55); background: rgba(22,101,52,.18); }
+    .comment-bubble.failed { border-color: rgba(248,113,113,.65); background: rgba(127,29,29,.2); }
+    .comment-bubble-text { white-space: pre-wrap; overflow-wrap: anywhere; }
+    .comment-bubble-state { margin-top: 8px; color: #93c5fd; font-size: 12px; font-weight: 700; }
+    .comment-bubble.done .comment-bubble-state { color: #86efac; }
+    .comment-bubble.failed .comment-bubble-state { color: #fca5a5; }
+    button { width: 100%; padding: 12px 14px; border: 0; border-radius: 12px; background: #38bdf8; color: #04111d; font-weight: 700; cursor: pointer; }
+    button:disabled { cursor: not-allowed; opacity: .5; }
+    .status { min-height: 20px; color: #93c5fd; font-size: 13px; }
+    @media (max-width: 900px) { .app { grid-template-columns: 1fr; grid-template-rows: minmax(0, 1fr) auto; } aside { max-height: 48vh; } }
+  </style>
+</head>
+<body>
+  <main class="app">
+    <section class="preview"><iframe id="deck" src="/deck?token=${encodeURIComponent(token)}"></iframe><div id="hitbox" class="hitbox" aria-label="Deck element selection layer"></div></section>
+    <aside>
+      <div>
+        <h1>Revela Visual Edit</h1>
+        <p class="hint">Write one comment. Use Ctrl/Cmd + click on deck elements to insert precise references into the comment.</p>
+      </div>
+      <div class="panel">
+        <div class="label">Comment</div>
+        <div id="comment" class="comment-editor" contenteditable="true" role="textbox" aria-multiline="true" data-placeholder="Example: Align @Metric 1 with @Metric 2, and remove @Text block 3."></div>
+      </div>
+      <div id="commentThread" class="comment-thread" aria-live="polite"></div>
+      <button id="send" disabled>Send comments</button>
+      <div id="status" class="status"></div>
+    </aside>
+  </main>
+  <script>
+    (() => {
+      const token = ${encodedToken};
+      const state = {
+        references: [],
+        pendingComments: [],
+        hoverEl: null,
+        hoverOutline: null,
+        referenceOutlines: [],
+        nextReferenceId: 1,
+        nextCommentId: 1,
+        initializedDoc: null,
+        deckVersion: null,
+        pendingRefreshMessage: false,
+        bound: false,
+        commentRange: null,
+      };
+      const els = {
+        frame: null,
+        hitbox: null,
+        comment: null,
+        commentThread: null,
+        send: null,
+        status: null,
+      };
+
+      window.addEventListener('error', (event) => reportError(event.error || event.message));
+      window.addEventListener('unhandledrejection', (event) => reportError(event.reason));
+
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', boot, { once: true });
+      } else {
+        boot();
+      }
+
+      function boot() {
+        try {
+          els.frame = document.getElementById('deck');
+          els.hitbox = document.getElementById('hitbox');
+          els.comment = document.getElementById('comment');
+          els.commentThread = document.getElementById('commentThread');
+          els.send = document.getElementById('send');
+          els.status = document.getElementById('status');
+
+          if (!els.frame || !els.hitbox || !els.comment || !els.commentThread || !els.send || !els.status) {
+            throw new Error('Editor boot failed: required DOM nodes are missing.');
+          }
+
+          bindEvents();
+          setStatus('Editor ready. Ctrl/Cmd + click deck elements to reference them.');
+          initFrame();
+          startDeckVersionPolling();
+        } catch (error) {
+          reportError(error);
+        }
+      }
+
+      function bindEvents() {
+        if (state.bound) return;
+        state.bound = true;
+        els.frame.addEventListener('load', initFrame);
+        document.addEventListener('keydown', (event) => {
+          if (event.key === 'Escape') clearHover();
+        });
+        els.comment.addEventListener('input', () => {
+          saveCommentRange();
+          syncReferencesFromComment(false);
+          updateSendState();
+        });
+        els.comment.addEventListener('keyup', saveCommentRange);
+        els.comment.addEventListener('mouseup', saveCommentRange);
+        document.addEventListener('selectionchange', saveCommentRange);
+        els.hitbox.addEventListener('pointermove', onHover);
+        els.hitbox.addEventListener('pointerdown', onPointerDown);
+        els.hitbox.addEventListener('click', onClick);
+        els.hitbox.addEventListener('contextmenu', (event) => {
+          if (event.ctrlKey || event.metaKey) event.preventDefault();
+        });
+        els.hitbox.addEventListener('wheel', (event) => {
+          const win = els.frame.contentWindow;
+          if (!win) return;
+          event.preventDefault();
+          win.scrollBy({ top: event.deltaY, left: event.deltaX, behavior: 'auto' });
+          renderHoverOutline(state.hoverEl);
+          renderReferenceOutlines();
+        }, { passive: false });
+        els.send.addEventListener('click', sendComment);
+      }
+
+      function initFrame() {
+        try {
+          const doc = els.frame.contentDocument;
+          if (!doc) {
+            setStatus('Unable to access deck iframe.');
+            return;
+          }
+          if (doc === state.initializedDoc) return;
+          if (doc.location.href === 'about:blank') return;
+          if (doc.readyState === 'loading') return;
+          state.initializedDoc = doc;
+          clearReferences(false);
+          state.hoverEl = null;
+          state.hoverOutline = createOutline(doc, '#38bdf8', 'rgba(56,189,248,.12)');
+          state.referenceOutlines = [];
+          doc.addEventListener('scroll', () => {
+            renderHoverOutline(state.hoverEl);
+            renderReferenceOutlines();
+          }, true);
+          const slides = getSlides(doc);
+          updateSendState();
+          if (state.pendingRefreshMessage) {
+            state.pendingRefreshMessage = false;
+            markPendingCommentsDone();
+            setStatus('Deck updated. Preview refreshed. Element references were cleared.');
+          } else {
+            setStatus(slides.length > 0 ? 'Editor ready. Found ' + slides.length + ' slides. Ctrl/Cmd + click to reference elements.' : 'Editor ready, but no .slide elements were found. Ctrl/Cmd + click to reference elements.');
+          }
+        } catch (error) {
+          reportError(error);
+        }
+      }
+
+      function startDeckVersionPolling() {
+        pollDeckVersion();
+        window.setInterval(pollDeckVersion, 2000);
+      }
+
+      async function pollDeckVersion() {
+        try {
+          const res = await fetch('/api/deck-version?token=' + encodeURIComponent(token), { cache: 'no-store' });
+          const body = await res.json().catch(() => ({}));
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to check deck version');
+          const nextVersion = String(body.mtimeMs) + ':' + String(body.size);
+          if (!state.deckVersion) {
+            state.deckVersion = nextVersion;
+            return;
+          }
+          if (state.deckVersion === nextVersion) return;
+          state.deckVersion = nextVersion;
+          refreshDeckPreview(body.mtimeMs);
+        } catch (error) {
+          reportError(error);
+        }
+      }
+
+      function refreshDeckPreview(version) {
+        state.pendingRefreshMessage = true;
+        state.initializedDoc = null;
+        clearReferences(true);
+        state.hoverEl = null;
+        if (state.hoverOutline) state.hoverOutline.style.display = 'none';
+        state.referenceOutlines.forEach((outline) => outline.style.display = 'none');
+        state.referenceOutlines = [];
+        updateSendState();
+        els.frame.src = '/deck?token=' + encodeURIComponent(token) + '&v=' + encodeURIComponent(String(version));
+        setStatus('Deck changed. Refreshing preview...');
+      }
+
+      function onHover(event) {
+        try {
+          initFrame();
+          const target = selectable(targetFromPointer(event));
+          if (!target || isReferenced(target)) {
+            renderHoverOutline(null);
+            return;
+          }
+          state.hoverEl = target;
+          renderHoverOutline(target);
+        } catch (error) {
+          reportError(error);
+        }
+      }
+
+      function onClick(event) {
+        try {
+          initFrame();
+          const target = selectable(targetFromPointer(event));
+          if (event.ctrlKey || event.metaKey) {
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+          } else if (target) {
+            setStatus('Use Ctrl/Cmd + click to reference this element in your comment.');
+          }
+        } catch (error) {
+          reportError(error);
+        }
+      }
+
+      function onPointerDown(event) {
+        if (!event.ctrlKey && !event.metaKey) return;
+        try {
+          initFrame();
+          event.preventDefault();
+          event.stopPropagation();
+          toggleReference(selectable(targetFromPointer(event)));
+        } catch (error) {
+          reportError(error);
+        }
+      }
+
+      async function sendComment() {
+        syncReferencesFromComment(false);
+        const text = getCommentText().trim();
+        if (!text) return;
+        const elements = state.references.map((reference) => reference.payload);
+        const commentId = addPendingComment(text, elements, 'sending');
+        clearReferences(false);
+        els.comment.textContent = '';
+        renderReferenceOutlines();
+        els.send.disabled = true;
+        setStatus('Sending...');
+        try {
+          const res = await fetch('/api/comment?token=' + encodeURIComponent(token), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ comment: text, elements }),
+          });
+          const body = await res.json().catch(() => ({}));
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to send comment');
+          updatePendingCommentStatus(commentId, 'sent');
+          setStatus('Comment sent. Waiting for deck update...');
+          updateSendState();
+        } catch (error) {
+          updatePendingCommentStatus(commentId, 'failed');
+          reportError(error);
+          updateSendState();
+        }
+      }
+
+      function selectable(node) {
+        if (!node || node.nodeType !== 1) return null;
+        if (node === state.hoverOutline || state.referenceOutlines.includes(node)) return null;
+        return findSlide(node) ? node : null;
+      }
+
+      function toggleReference(target) {
+        if (!target) {
+          setStatus('No selectable deck element found under pointer.');
+          return;
+        }
+        const existing = findReferenceIndex(target);
+        if (existing >= 0) {
+          const label = state.references[existing].label;
+          removeReferenceAt(existing, true);
+          setStatus('Removed @' + label + '.');
+          return;
+        }
+        const payload = collectPayload(target);
+        const id = 'ref-' + state.nextReferenceId++;
+        const label = nextReferenceLabel(payload);
+        const reference = { id, target, label, payload };
+        state.references.push(reference);
+        insertReferenceChip(reference);
+        renderReferenceOutlines();
+        updateSendState();
+        setStatus('Inserted @' + label + '. ' + state.references.length + ' reference' + (state.references.length === 1 ? '' : 's') + ' will be sent.');
+      }
+
+      function isReferenced(target) {
+        return findReferenceIndex(target) >= 0;
+      }
+
+      function findReferenceIndex(target) {
+        return state.references.findIndex((reference) => reference.target === target);
+      }
+
+      function removeReferenceAt(index, removeToken) {
+        const reference = state.references[index];
+        if (!reference) return;
+        state.references.splice(index, 1);
+        if (removeToken) removeReferenceChip(reference.id);
+        renderReferenceOutlines();
+        updateSendState();
+      }
+
+      function syncReferencesFromComment(showStatus) {
+        const activeIds = new Set(Array.from(els.comment.querySelectorAll('.ref-chip[data-ref-id]')).map((chip) => chip.getAttribute('data-ref-id')));
+        const before = state.references.length;
+        state.references = state.references.filter((reference) => activeIds.has(reference.id));
+        if (state.references.length !== before) {
+          renderReferenceOutlines();
+          if (showStatus) setStatus('References synced with comment text.');
+        }
+      }
+
+      function addPendingComment(text, elements, status) {
+        const id = 'comment-' + state.nextCommentId++;
+        state.pendingComments.push({
+          id,
+          text,
+          elements,
+          status,
+        });
+        renderCommentThread();
+        return id;
+      }
+
+      function updatePendingCommentStatus(id, status) {
+        const comment = state.pendingComments.find((item) => item.id === id);
+        if (!comment) return;
+        comment.status = status;
+        renderCommentThread();
+      }
+
+      function markPendingCommentsDone() {
+        let changed = false;
+        state.pendingComments.forEach((comment) => {
+          if (comment.status === 'sent' || comment.status === 'sending') {
+            comment.status = 'done';
+            changed = true;
+          }
+        });
+        if (changed) renderCommentThread();
+      }
+
+      function renderCommentThread() {
+        els.commentThread.textContent = '';
+        state.pendingComments.forEach((comment) => {
+          const bubble = document.createElement('div');
+          bubble.className = 'comment-bubble ' + comment.status;
+
+          const text = document.createElement('div');
+          text.className = 'comment-bubble-text';
+          text.textContent = comment.text;
+
+          const status = document.createElement('div');
+          status.className = 'comment-bubble-state';
+          status.textContent = commentStatusLabel(comment.status);
+
+          bubble.appendChild(text);
+          bubble.appendChild(status);
+          els.commentThread.appendChild(bubble);
+        });
+      }
+
+      function commentStatusLabel(status) {
+        if (status === 'done') return '✅ Applied';
+        if (status === 'failed') return 'Failed to send';
+        if (status === 'sending') return 'Sending to OpenCode...';
+        return '⏳ Sent to OpenCode';
+      }
+
+      function targetFromPointer(event) {
+        const doc = els.frame.contentDocument;
+        if (!doc || doc.location.href === 'about:blank') return null;
+        const frameRect = els.frame.getBoundingClientRect();
+        const x = event.clientX - frameRect.left;
+        const y = event.clientY - frameRect.top;
+        if (x < 0 || y < 0 || x > frameRect.width || y > frameRect.height) return null;
+        return doc.elementFromPoint(x, y);
+      }
+
+      function createOutline(doc, border, fill) {
+        const outline = doc.createElement('div');
+        outline.style.cssText = 'position:fixed;z-index:2147483647;pointer-events:none;border:2px solid ' + border + ';background:' + fill + ';border-radius:6px;display:none;';
+        doc.body.appendChild(outline);
+        return outline;
+      }
+
+      function renderBox(outline, target) {
+        if (!outline || !target || !target.getBoundingClientRect) {
+          if (outline) outline.style.display = 'none';
+          return;
+        }
+        const rect = target.getBoundingClientRect();
+        outline.style.display = 'block';
+        outline.style.left = rect.left + 'px';
+        outline.style.top = rect.top + 'px';
+        outline.style.width = rect.width + 'px';
+        outline.style.height = rect.height + 'px';
+      }
+
+      function renderHoverOutline(target) {
+        renderBox(state.hoverOutline, target);
+      }
+
+      function renderReferenceOutlines() {
+        const doc = els.frame.contentDocument;
+        if (!doc || doc.location.href === 'about:blank') return;
+        while (state.referenceOutlines.length < state.references.length) state.referenceOutlines.push(createOutline(doc, '#f59e0b', 'rgba(245,158,11,.16)'));
+        state.referenceOutlines.forEach((outline, index) => renderBox(outline, state.references[index]?.target));
+      }
+
+      function clearHover() {
+        state.hoverEl = null;
+        setStatus('Hover cleared. Existing references are kept.');
+        if (state.hoverOutline) state.hoverOutline.style.display = 'none';
+      }
+
+      function updateSendState() {
+        els.send.disabled = !getCommentText().trim();
+      }
+
+      function nextReferenceLabel(payload) {
+        return humanElementName(payload) + ' ' + (state.references.length + 1);
+      }
+
+      function insertReferenceChip(reference) {
+        const chip = document.createElement('span');
+        chip.className = 'ref-chip';
+        chip.contentEditable = 'false';
+        chip.dataset.refId = reference.id;
+        chip.textContent = '@' + reference.label;
+        const trailingSpace = document.createTextNode(' ');
+        const range = getCommentInsertRange();
+        if (range) {
+          range.insertNode(trailingSpace);
+          range.insertNode(chip);
+          range.setStartAfter(trailingSpace);
+          range.collapse(true);
+          applyCommentRange(range);
+        } else {
+          if (els.comment.textContent && !/\\s$/.test(els.comment.textContent)) els.comment.appendChild(document.createTextNode(' '));
+          els.comment.appendChild(chip);
+          els.comment.appendChild(trailingSpace);
+          placeCaretAfter(trailingSpace);
+        }
+        els.comment.focus();
+      }
+
+      function removeReferenceChip(id) {
+        const chip = els.comment.querySelector('.ref-chip[data-ref-id="' + cssEscape(id) + '"]');
+        if (!chip) return;
+        const next = chip.nextSibling;
+        chip.remove();
+        if (next && next.nodeType === Node.TEXT_NODE && next.textContent === ' ') next.remove();
+      }
+
+      function clearReferences(removeChips) {
+        state.references = [];
+        if (removeChips) els.comment.querySelectorAll('.ref-chip').forEach((chip) => chip.remove());
+      }
+
+      function getCommentText() {
+        return (els.comment.innerText || els.comment.textContent || '').replace(/\\u00a0/g, ' ');
+      }
+
+      function placeCaretAfter(node) {
+        const range = document.createRange();
+        range.setStartAfter(node);
+        range.collapse(true);
+        applyCommentRange(range);
+      }
+
+      function saveCommentRange() {
+        const selection = window.getSelection();
+        if (!selection || selection.rangeCount === 0) return;
+        if (!els.comment || !els.comment.contains(selection.anchorNode)) return;
+        state.commentRange = selection.getRangeAt(0).cloneRange();
+      }
+
+      function getCommentInsertRange() {
+        const selection = window.getSelection();
+        if (selection && selection.rangeCount > 0 && els.comment.contains(selection.anchorNode)) {
+          const range = selection.getRangeAt(0).cloneRange();
+          range.deleteContents();
+          return range;
+        }
+        if (state.commentRange && els.comment.contains(state.commentRange.commonAncestorContainer)) {
+          const range = state.commentRange.cloneRange();
+          range.deleteContents();
+          return range;
+        }
+        return null;
+      }
+
+      function applyCommentRange(range) {
+        const selection = window.getSelection();
+        if (!selection) return;
+        selection.removeAllRanges();
+        selection.addRange(range);
+        state.commentRange = range.cloneRange();
+      }
+
+      function humanElementName(payload) {
+        const tag = payload.tagName || 'element';
+        const classes = payload.classList || [];
+        if (/^h[1-6]$/.test(tag)) return 'Heading';
+        if (tag === 'p') return 'Text block';
+        if (classes.some((name) => /card/i.test(name))) return 'Card';
+        if (classes.some((name) => /stat|metric|value/i.test(name))) return 'Metric';
+        if (tag === 'img' || tag === 'svg') return 'Visual';
+        return 'Element';
+      }
+
+      function collectPayload(el) {
+        const doc = els.frame.contentDocument;
+        const slides = getSlides(doc);
+        const slide = findSlide(el);
+        const rect = el.getBoundingClientRect();
+        const slideIndex = slide ? slides.indexOf(slide) + 1 : undefined;
+        const win = els.frame.contentWindow;
+        return {
+          slideIndex,
+          slideTitle: slide ? ((slide.querySelector('h1,h2,h3,[data-title]') || {}).textContent || '').trim().slice(0, 160) : undefined,
+          selector: buildSelector(el, slide),
+          domPath: buildDomPath(el, slide),
+          tagName: el.tagName.toLowerCase(),
+          id: el.id || undefined,
+          classList: Array.from(el.classList || []),
+          text: (el.innerText || el.textContent || '').trim().replace(/\\s+/g, ' ').slice(0, 600),
+          outerHTMLExcerpt: (el.outerHTML || '').replace(/\\s+/g, ' ').slice(0, 1200),
+          nearbyText: slide ? (slide.innerText || slide.textContent || '').trim().replace(/\\s+/g, ' ').slice(0, 1200) : undefined,
+          boundingBox: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+          viewport: { width: win ? win.innerWidth : undefined, height: win ? win.innerHeight : undefined },
+        };
+      }
+
+      function buildSelector(el, slide) {
+        if (el.id) return '#' + cssEscape(el.id);
+        const parts = [];
+        let node = el;
+        while (node && node.nodeType === 1 && node !== slide) {
+          let part = node.tagName.toLowerCase();
+          const stable = Array.from(node.attributes || []).find((attr) => attr.name.startsWith('data-'));
+          if (stable) {
+            part += '[' + stable.name + '="' + stable.value.replace(/"/g, '\\"') + '"]';
+            parts.unshift(part);
+            break;
+          }
+          const classes = Array.from(node.classList || []).slice(0, 2).map(cssEscape);
+          if (classes.length) part += '.' + classes.join('.');
+          const siblings = Array.from(node.parentElement ? node.parentElement.children : []).filter((child) => child.tagName === node.tagName);
+          if (siblings.length > 1) part += ':nth-of-type(' + (siblings.indexOf(node) + 1) + ')';
+          parts.unshift(part);
+          node = node.parentElement;
+        }
+        const slidePart = slide ? slideSelector(slide) : '.slide';
+        return [slidePart].concat(parts).join(' > ');
+      }
+
+      function findSlide(node) {
+        return node.closest('.slide, [slide-qa], .slide-canvas, .page');
+      }
+
+      function getSlides(doc) {
+        const slides = Array.from(doc.querySelectorAll('.slide'));
+        if (slides.length) return slides;
+        const qaSlides = Array.from(doc.querySelectorAll('[slide-qa]'));
+        if (qaSlides.length) return qaSlides;
+        const canvases = Array.from(doc.querySelectorAll('.slide-canvas'));
+        if (canvases.length) return canvases;
+        return Array.from(doc.querySelectorAll('.page'));
+      }
+
+      function slideSelector(slide) {
+        if (slide.id) return '#' + cssEscape(slide.id);
+        const doc = els.frame.contentDocument;
+        const slides = getSlides(doc);
+        const index = slides.indexOf(slide) + 1;
+        if (slide.classList && slide.classList.contains('slide')) return '.slide:nth-of-type(' + index + ')';
+        if (slide.hasAttribute && slide.hasAttribute('slide-qa')) return '[slide-qa]:nth-of-type(' + index + ')';
+        if (slide.classList && slide.classList.contains('slide-canvas')) return '.slide-canvas:nth-of-type(' + index + ')';
+        return '.page:nth-of-type(' + index + ')';
+      }
+
+      function buildDomPath(el, stop) {
+        const parts = [];
+        let node = el;
+        while (node && node.nodeType === 1 && node !== stop) {
+          const siblings = Array.from(node.parentElement ? node.parentElement.children : []);
+          parts.unshift(node.tagName.toLowerCase() + '[' + (siblings.indexOf(node) + 1) + ']');
+          node = node.parentElement;
+        }
+        return parts.join(' > ');
+      }
+
+      function cssEscape(value) {
+        if (window.CSS && CSS.escape) return CSS.escape(value);
+        return String(value).replace(/[^a-zA-Z0-9_-]/g, '\\$&');
+      }
+
+      function setStatus(message) {
+        if (els.status) els.status.textContent = message;
+      }
+
+      function reportError(error) {
+        const message = error && error.message ? error.message : String(error);
+        setStatus('Editor error: ' + message);
+        console.error('[Revela edit]', error);
+      }
+    })();
+  </script>
+</body>
+</html>`
+}

package/package.json

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

package/plugin.ts

@@ -45,6 +45,7 @@ import {
 } from "./lib/commands/domains"
 import { handlePdf } from "./lib/commands/pdf"
 import { handlePptx } from "./lib/commands/pptx"
+import { handleEdit } from "./lib/commands/edit"
 import { handleDesignsPreview } from "./lib/commands/designs-preview"
 import {
   parseDesignsNewArgs,
@@ -243,6 +244,10 @@ const server: Plugin = (async (pluginCtx) => {
         } as any)
         return
       }
+      if (sub === "edit") {
+        await handleEdit(param, { client, sessionID, workspaceRoot }, send)
+        throw new Error("__REVELA_EDIT_HANDLED__")
+      }
       if (sub === "designs" && !param) {
         await handleDesignsList(send)
         throw new Error("__REVELA_DESIGNS_LIST_HANDLED__")