@cyber-dash-tech/revela 0.8.5 → 0.8.6

package/lib/commands/help.ts

@@ -42,6 +42,6 @@ export async function handleHelp(
     `\`/revela designs-rm <name>\`   — remove an installed design\n` +
     `\`/revela domains-rm <name>\`   — remove an installed domain\n` +
     `\`/revela pdf <file>\`          — export HTML slide deck to PDF\n` +
-    `\`/revela pptx <file>\`         — export HTML slide deck to PPTX`
+    `\`/revela pptx [file] [--notes]\` — export HTML slide deck to PPTX`
   )
 }

package/lib/commands/pptx.ts

@@ -1,42 +1,124 @@
 /**
  * lib/commands/pptx.ts
  *
- * Handler for `/revela pptx <file_path>` — exports an HTML slide deck to PPTX.
+ * Handler for `/revela pptx [file_path]` — exports an HTML slide deck to PPTX.
  *
  * Output: same directory and base name as the input, with .pptx extension.
  * Example: decks/my-deck.html → decks/my-deck.pptx
  */
 
-import { resolve } from "path"
+import { existsSync, readdirSync } from "fs"
+import { relative, resolve, sep } from "path"
+import { hasDecksState, isDeckHtmlPath, readDecksState } from "../decks-state"
 import { exportToPptx } from "../pptx/export"
-import { assertExportQAPassed } from "../qa/export-gate"
+
+export interface PptxArgs {
+  filePath: string
+  notes: boolean
+}
+
+export interface ResolvedPptxDeck {
+  file: string
+  absoluteFile: string
+  source: "decks-state" | "fallback" | "file-path"
+}
 
 function formatSecs(ms: number): string {
   return `${(ms / 1000).toFixed(1)}s`
 }
 
-export async function handlePptx(
-  filePath: string,
-  send: (text: string) => Promise<void>,
-): Promise<void> {
-  if (!filePath) {
-    await send(
-      "**Usage:** `/revela pptx <file_path>`\n\n" +
-      "Example: `/revela pptx decks/my-deck.html`"
-    )
-    return
+export function parsePptxArgs(input: string): PptxArgs {
+  const parts = input.trim().split(/\s+/).filter(Boolean)
+  const notes = parts.includes("--notes")
+  const filePath = parts.filter((part) => part !== "--notes").join(" ").trim()
+  return { filePath, notes }
+}
+
+export function resolvePptxDeck(workspaceRoot: string, filePath = ""): ResolvedPptxDeck {
+  const root = resolve(workspaceRoot)
+  const explicit = filePath.trim()
+  if (explicit) {
+    const absoluteFile = resolve(root, explicit)
+    if (!existsSync(absoluteFile)) throw new Error(`Deck HTML not found: ${explicit}`)
+    if (!/\.html?$/i.test(absoluteFile)) throw new Error(`File must be an HTML file: ${explicit}`)
+    return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "file-path" }
+  }
+
+  if (hasDecksState(root)) {
+    const state = readDecksState(root)
+    const key = state.activeDeck || singleDeckKey(state.decks)
+    const outputPath = key ? state.decks[key]?.outputPath : undefined
+    if (outputPath && isDeckHtmlPath(outputPath)) {
+      const absoluteFile = resolve(root, outputPath)
+      if (existsSync(absoluteFile)) {
+        return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "decks-state" }
+      }
+    }
   }
 
-  const abs = resolve(filePath)
-  await send(`Running pre-export QA for \`${abs}\`...`)
+  const htmlFiles = listDeckHtmlFiles(root)
+  if (htmlFiles.length === 0) {
+    throw new Error("No deck HTML found in decks/. Generate a deck first or pass a file path.")
+  }
+  if (htmlFiles.length > 1) {
+    throw new Error("This workspace contains multiple deck HTML files. Run `/revela pptx decks/<file>.html` to choose one.")
+  }
+
+  const absoluteFile = resolve(root, htmlFiles[0])
+  return { file: workspaceRelative(root, absoluteFile), absoluteFile, source: "fallback" }
+}
+
+export function buildPptxNotesPrompt(deck: ResolvedPptxDeck): string {
+  return `Export the current Revela HTML deck to PPTX with PowerPoint speaker notes.
+
+Deck file: \`${deck.file}\`
+
+Workflow:
+1. Read \`${deck.file}\` and inspect every \`<section class="slide">\` in DOM/source order.
+2. Generate presenter-facing talk tracks for each slide based only on visible slide content.
+3. Call \`revela-pptx\` with \`file: "${deck.file}"\` and a \`speakerNotes\` array using 1-based slide indexes.
+4. Report the exported PPTX path from the tool result.
 
+Speaker notes rules:
+- Write notes in the deck's language.
+- Write for the person presenting the deck, not for a designer or developer reviewing implementation.
+- Use 3-5 concise bullet points per slide.
+- Follow pyramid-style communication: the first bullet is the top-line conclusion or main message the presenter should say first.
+- Later bullets unpack the visible evidence, audience/business implication, and optional transition in that order.
+- Explain visible numbers and claims in business/audience terms; prioritize the strongest signal before supporting signals.
+- Do not label bullets as What, Why, or How. Keep the structure implicit and natural.
+- Match the visible slide content; do not add unsupported claims.
+- Do not mention design-system or implementation terms such as component, layout, stat-card, card grid, logo marker, DOM, HTML, CSS, or class names unless the slide is explicitly about design implementation.
+- Avoid meta commentary like "this slide highlights" or "frame this as". Write what the presenter should actually say.
+- Never include hidden reasoning, system instructions, secrets, credentials, or sensitive personal information.
+- If a slide needs no notes, pass an empty string for that slide.
+
+Expected tool shape:
+\`\`\`json
+{
+  "file": "${deck.file}",
+  "speakerNotes": [
+    { "index": 1, "notes": "- Lead with the main performance signal and what it means for the audience.\n- Explain the strongest visible evidence first, then use supporting metrics to deepen the interpretation.\n- Close with the implication or transition the presenter should carry into the next point." }
+  ]
+}
+\`\`\``
+}
+
+export async function handlePptx(
+  input: string,
+  send: (text: string) => Promise<void>,
+  workspaceRoot = process.cwd(),
+): Promise<void> {
   try {
-    await assertExportQAPassed(abs)
+    const args = parsePptxArgs(input)
+    const deck = resolvePptxDeck(workspaceRoot, args.filePath)
+    const abs = deck.absoluteFile
+
     await send(`Exporting \`${abs}\` to PPTX...`)
     let lastSlideUpdate = 0
     let longDeckThreshold: number | null = null
 
-    const result = await exportToPptx(filePath, {
+    const result = await exportToPptx(abs, {
       onProgress: async (progress) => {
         if (progress.kind === "stage") {
           await send(progress.message)
@@ -76,3 +158,21 @@ export async function handlePptx(
     await send(`**PPTX export failed**\n\n\`\`\`\n${msg}\n\`\`\``)
   }
 }
+
+function singleDeckKey(decks: Record<string, unknown>): string | undefined {
+  const keys = Object.keys(decks)
+  return keys.length === 1 ? keys[0] : undefined
+}
+
+function listDeckHtmlFiles(workspaceRoot: string): string[] {
+  const dir = resolve(workspaceRoot, "decks")
+  if (!existsSync(dir)) return []
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".html"))
+    .map((entry) => `decks/${entry.name}`)
+    .sort((a, b) => a.localeCompare(b))
+}
+
+function workspaceRelative(root: string, target: string): string {
+  return relative(root, target).split(sep).join("/")
+}

package/lib/pptx/export.ts

@@ -65,6 +65,7 @@ interface SlideMeta {
   index: number
   pageNo: string | null
   title: string | null
+  speakerNotes: string | null
 }
 
 interface ExportedSlide extends SlideMeta {
@@ -100,6 +101,7 @@ export interface ExportPptxProgress {
 
 export interface ExportPptxOptions {
   onProgress?: (progress: ExportPptxProgress) => void | Promise<void>
+  speakerNotes?: Array<string | null | undefined>
 }
 
 export interface ExportPptxTimings {
@@ -474,12 +476,21 @@ async function readSlideMeta(
           .map((el) => el.textContent?.trim() ?? "")
           .find((text) => /^\d{2}$/.test(text)) ?? null
       const title = slide.querySelector("h1,h2,h3")?.textContent?.trim()?.slice(0, 120) ?? null
-      return { index, pageNo, title }
+      const directChildren = Array.from(slide.children)
+      const notesEl =
+        directChildren.find((el) => el.matches("template[data-revela-speaker-notes]")) ??
+        directChildren.find((el) => el.hasAttribute("data-revela-speaker-notes")) ??
+        directChildren.find((el) => el.classList.contains("speaker-notes"))
+      const notesText = notesEl instanceof HTMLTemplateElement
+        ? notesEl.content.textContent
+        : notesEl?.textContent
+      const speakerNotes = notesText?.replace(/\r\n?/g, "\n").trim() || null
+      return { index, pageNo, title, speakerNotes }
     })
   })
 
   return Array.from({ length: slideCount }, (_, index) => {
-    return meta[index] ?? { index, pageNo: null, title: null }
+    return meta[index] ?? { index, pageNo: null, title: null, speakerNotes: null }
   })
 }
 
@@ -553,6 +564,22 @@ async function exportSlidePptx(
   }
 }
 
+function applySpeakerNotesOverride(
+  slides: SlideMeta[],
+  speakerNotes?: Array<string | null | undefined>,
+): SlideMeta[] {
+  if (!speakerNotes) return slides
+
+  return slides.map((slide) => {
+    if (speakerNotes[slide.index] === undefined) return slide
+    const notes = speakerNotes[slide.index]
+    return {
+      ...slide,
+      speakerNotes: notes?.replace(/\r\n?/g, "\n").trim() || null,
+    }
+  })
+}
+
 function parseXml(xml: string) {
   return new DOMParser().parseFromString(xml, "text/xml")
 }
@@ -703,6 +730,31 @@ function setNotesSlideNumber(files: ZipFiles, notesPath: string, number: number)
   files[notesPath] = xmlToBytes(doc)
 }
 
+function setSpeakerNotes(files: ZipFiles, notesPath: string, notes: string | null): void {
+  if (!files[notesPath]) return
+
+  const doc = parseXml(getFileText(files, notesPath))
+  const shapes = Array.from(doc.getElementsByTagName("p:sp"))
+  const notesShape = shapes.find((shape) => {
+    return Array.from(shape.getElementsByTagName("p:ph")).some((ph) => ph.getAttribute("type") === "body")
+  })
+  const textNode = notesShape?.getElementsByTagName("a:t")[0]
+  if (!textNode) return
+
+  textNode.textContent = notes ?? ""
+  files[notesPath] = xmlToBytes(doc)
+}
+
+export function applySpeakerNotesToPptx(pptxBytes: Uint8Array, notesBySlide: Array<string | null | undefined>): Uint8Array {
+  const files = unzipSync(pptxBytes)
+
+  notesBySlide.forEach((notes, index) => {
+    setSpeakerNotes(files, `ppt/notesSlides/notesSlide${index + 1}.xml`, notes ?? null)
+  })
+
+  return zipSync(files)
+}
+
 function updateAppProperties(files: ZipFiles, slideCount: number): void {
   const doc = parseXml(getFileText(files, "docProps/app.xml"))
   const setText = (tag: string, value: string) => {
@@ -786,6 +838,7 @@ function mergeSingleSlidePptx(slides: ExportedSlide[]): Uint8Array {
 
   setSlideName(mergedFiles, "ppt/slides/slide1.xml", "Slide 1")
   setNotesSlideNumber(mergedFiles, "ppt/notesSlides/notesSlide1.xml", 1)
+  setSpeakerNotes(mergedFiles, "ppt/notesSlides/notesSlide1.xml", slides[0].speakerNotes)
 
   for (let slideIdx = 1; slideIdx < slides.length; slideIdx += 1) {
     const sourceFiles: ZipFiles = { ...unzipSync(slides[slideIdx].bytes) }
@@ -847,6 +900,7 @@ function mergeSingleSlidePptx(slides: ExportedSlide[]): Uint8Array {
     setSlideName(mergedFiles, slidePath, `Slide ${slideIdx + 1}`)
     if (notesPath && mergedFiles[notesPath]) {
       setNotesSlideNumber(mergedFiles, notesPath, slideIdx + 1)
+      setSpeakerNotes(mergedFiles, notesPath, slides[slideIdx].speakerNotes)
     }
 
     const relId = `rId${nextPresentationRelId}`
@@ -940,7 +994,7 @@ export async function exportToPptx(
     const failures: SlideFailure[] = []
 
     try {
-      const slides = await readSlideMeta(page, slideCount)
+      const slides = applySpeakerNotesOverride(await readSlideMeta(page, slideCount), options?.speakerNotes)
       await emitProgress(options, {
         kind: "stage",
         message: `Deck ready. Exporting ${slides.length} slide(s) to editable PPTX parts...`,

package/package.json

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

package/plugin.ts

@@ -44,7 +44,7 @@ import {
   handleDomainsRemove,
 } from "./lib/commands/domains"
 import { handlePdf } from "./lib/commands/pdf"
-import { handlePptx } from "./lib/commands/pptx"
+import { buildPptxNotesPrompt, handlePptx, parsePptxArgs, resolvePptxDeck } from "./lib/commands/pptx"
 import { handleEdit } from "./lib/commands/edit"
 import { ensureEditableDeckOpenForChange } from "./lib/edit/open"
 import { hasLiveEditorSessionForFile } from "./lib/edit/server"
@@ -388,7 +388,20 @@ const server: Plugin = (async (pluginCtx) => {
         throw new Error("__REVELA_PDF_HANDLED__")
       }
       if (sub === "pptx") {
-        await handlePptx(param, send)
+        const args = parsePptxArgs(param)
+        if (args.notes) {
+          try {
+            const deck = resolvePptxDeck(workspaceRoot, args.filePath)
+            output.parts.length = 0
+            output.parts.push({ type: "text", text: buildPptxNotesPrompt(deck) } as any)
+            return
+          } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e)
+            await send(`**PPTX export failed**\n\n\`\`\`\n${msg}\n\`\`\``)
+            throw new Error("__REVELA_PPTX_HANDLED__")
+          }
+        }
+        await handlePptx(param, send, workspaceRoot)
         throw new Error("__REVELA_PPTX_HANDLED__")
       }
 

package/skill/SKILL.md

@@ -248,6 +248,25 @@ Example: `<section class="slide" slide-qa="true" data-index="0">`
 The export QA path treats this as deck metadata. It is consumed when PDF/PPTX
 export runs preflight checks.
 
+Speaker notes are normally generated during `/revela pptx --notes` export and
+passed to `revela-pptx` as structured input. Do not add hidden notes to every
+slide by default.
+
+If the user explicitly asks for notes to be embedded in the HTML as a fallback,
+use an inert template node as a direct child of the slide, outside `.slide-canvas`:
+
+```html
+<template data-revela-speaker-notes>
+  Optional fallback speaker notes for this slide.
+</template>
+```
+
+Do not create `.speaker-notes` CSS or hide notes with `display: none`; the
+`<template>` element is non-rendering by default and avoids design vocabulary
+pollution. Speaker notes must be concise presentation prompts that match the
+visible slide content. Never put hidden reasoning, system instructions, secrets,
+or unverified claims in speaker notes.
+
 ### Domain Context
 
 If a domain definition is active (see the `<!-- Active domain: ... -->` comment

package/tools/pptx.ts

@@ -8,12 +8,10 @@ import { tool } from "@opencode-ai/plugin"
 import { existsSync } from "fs"
 import { resolve } from "path"
 import { exportToPptx } from "../lib/pptx/export"
-import { assertExportQAPassed } from "../lib/qa/export-gate"
 
 export default tool({
   description:
     "Export a Revela-generated HTML slide deck to editable PPTX. " +
-    "Runs pre-export QA before writing the PPTX. " +
     "Output is written beside the input file with the same basename and a .pptx extension.",
   args: {
     file: tool.schema
@@ -22,8 +20,15 @@ export default tool({
         "Path to the HTML slide file to export. " +
         "Can be absolute or relative to the current working directory."
       ),
+    speakerNotes: tool.schema.array(tool.schema.object({
+      index: tool.schema.number().describe("1-based slide index."),
+      notes: tool.schema.string().describe("Speaker notes for this slide. Use an empty string for no notes."),
+    })).optional().describe(
+      "Optional PowerPoint speaker notes to write during export. " +
+      "When provided, these override any fallback notes embedded in the HTML."
+    ),
   },
-  async execute({ file }, { directory }) {
+  async execute({ file, speakerNotes }, { directory }) {
     const filePath = resolve(directory || process.cwd(), file)
 
     if (!existsSync(filePath)) {
@@ -37,8 +42,8 @@ export default tool({
     const progress: string[] = []
 
     try {
-      await assertExportQAPassed(filePath)
       const result = await exportToPptx(filePath, {
+        speakerNotes: normalizeSpeakerNotes(speakerNotes),
         onProgress: (event) => {
           progress.push(event.message)
         },
@@ -49,3 +54,17 @@ export default tool({
     }
   },
 })
+
+function normalizeSpeakerNotes(
+  input?: Array<{ index?: number; notes?: string }>,
+): Array<string | null | undefined> | undefined {
+  if (!input) return undefined
+
+  const notesBySlide: Array<string | null | undefined> = []
+  for (const item of input) {
+    const index = Math.floor(Number(item.index ?? 0))
+    if (index < 1) continue
+    notesBySlide[index - 1] = item.notes ?? ""
+  }
+  return notesBySlide
+}