@cyber-dash-tech/revela 0.7.4 → 0.7.5

package/lib/edit/prompt.ts

@@ -76,6 +76,7 @@ Instructions:
 - 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.
-- Design compliance is checked automatically after deck writes. Run ${"`revela-qa`"} on ${payload.file} only when the edit may affect layout geometry, such as size, spacing, font scale, content amount, or container structure; fix any overflow it reports.
+- Static design compliance is checked automatically after deck writes. If the tool result reports unknown classes, replace them with classes from the active design.
+- Do not run QA after the edit unless the user explicitly asks for diagnostics. PDF/PPTX export commands run hard-error pre-export QA automatically.
 - If the comment is ambiguous, ask one concise clarification question instead of guessing.`
 }

package/lib/edit/server.ts

@@ -94,16 +94,22 @@ async function handleRequest(req: Request): Promise<Response> {
 
 function handleDeckVersion(session: EditSession): Response {
   try {
-    const stat = statSync(session.absoluteFile)
+    const version = readDeckVersion(session)
     session.lastActiveAt = Date.now()
     scheduleIdleStop()
-    return jsonResponse({ ok: true, mtimeMs: stat.mtimeMs, size: stat.size })
+    return jsonResponse({ ok: true, ...version })
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
     return jsonResponse({ ok: false, error: message }, 404)
   }
 }
 
+function readDeckVersion(session: EditSession): { mtimeMs: number; size: number; version: string } {
+  const stat = statSync(session.absoluteFile)
+  const version = `${stat.mtimeMs}:${stat.size}`
+  return { mtimeMs: stat.mtimeMs, size: stat.size, version }
+}
+
 async function handleComment(req: Request, session: EditSession): Promise<Response> {
   let body: Partial<EditCommentPayload>
   try {
@@ -132,6 +138,7 @@ async function handleComment(req: Request, session: EditSession): Promise<Respon
     elements,
     comments,
   })
+  const deckVersion = readDeckVersion(session).version
 
   await session.client.session.prompt({
     path: { id: session.sessionID },
@@ -142,7 +149,7 @@ async function handleComment(req: Request, session: EditSession): Promise<Respon
 
   session.lastActiveAt = Date.now()
   scheduleIdleStop()
-  return jsonResponse({ ok: true })
+  return jsonResponse({ ok: true, deckVersion })
 }
 
 function validateSession(token: string | null): { ok: true; value: EditSession } | { ok: false; response: Response } {
@@ -233,11 +240,13 @@ function renderEditorShell(token: string): string {
     .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.applied { border-color: rgba(34,197,94,.55); background: rgba(22,101,52,.18); }
+    .comment-bubble.stale { border-color: rgba(251,191,36,.6); background: rgba(120,53,15,.2); }
     .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.applied .comment-bubble-state { color: #86efac; }
+    .comment-bubble.stale .comment-bubble-state { color: #fcd34d; }
     .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; }
@@ -265,6 +274,7 @@ function renderEditorShell(token: string): string {
   <script>
     (() => {
       const token = ${encodedToken};
+      const COMMENT_STALE_MS = 60000;
       const state = {
         references: [],
         pendingComments: [],
@@ -374,7 +384,6 @@ function renderEditorShell(token: string): string {
           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.');
@@ -394,13 +403,18 @@ function renderEditorShell(token: string): string {
           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);
+          const nextVersion = body.version || (String(body.mtimeMs) + ':' + String(body.size));
           if (!state.deckVersion) {
             state.deckVersion = nextVersion;
+            markStaleComments();
+            return;
+          }
+          if (state.deckVersion === nextVersion) {
+            markStaleComments();
             return;
           }
-          if (state.deckVersion === nextVersion) return;
           state.deckVersion = nextVersion;
+          markCommentsAppliedForVersion(nextVersion);
           refreshDeckPreview(body.mtimeMs);
         } catch (error) {
           reportError(error);
@@ -482,7 +496,7 @@ function renderEditorShell(token: string): string {
           });
           const body = await res.json().catch(() => ({}));
           if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to send comment');
-          updatePendingCommentStatus(commentId, 'sent');
+          updatePendingCommentStatus(commentId, 'sent', { baseDeckVersion: body.deckVersion || state.deckVersion });
           setStatus('Comment sent. Waiting for deck update...');
           updateSendState();
         } catch (error) {
@@ -555,29 +569,53 @@ function renderEditorShell(token: string): string {
           text,
           elements,
           status,
+          createdAt: Date.now(),
+          baseDeckVersion: state.deckVersion,
+          appliedVersion: null,
         });
         renderCommentThread();
         return id;
       }
 
-      function updatePendingCommentStatus(id, status) {
+      function updatePendingCommentStatus(id, status, updates) {
         const comment = state.pendingComments.find((item) => item.id === id);
         if (!comment) return;
+        if (comment.status === 'applied' && status !== 'failed') return;
         comment.status = status;
+        if (updates) Object.assign(comment, updates);
         renderCommentThread();
       }
 
-      function markPendingCommentsDone() {
+      function markCommentsAppliedForVersion(version) {
         let changed = false;
         state.pendingComments.forEach((comment) => {
-          if (comment.status === 'sent' || comment.status === 'sending') {
-            comment.status = 'done';
+          if ((comment.status === 'sent' || comment.status === 'sending' || comment.status === 'stale') && comment.baseDeckVersion !== version) {
+            comment.status = 'applied';
+            comment.appliedVersion = version;
             changed = true;
           }
         });
         if (changed) renderCommentThread();
       }
 
+      function markStaleComments() {
+        const now = Date.now();
+        let changed = false;
+        const hasWaiting = state.pendingComments.some((comment) => {
+          if (comment.status !== 'sent' && comment.status !== 'sending') return false;
+          if (now - comment.createdAt < COMMENT_STALE_MS) return true;
+          comment.status = 'stale';
+          changed = true;
+          return true;
+        });
+        if (changed) {
+          renderCommentThread();
+          setStatus('Still waiting for deck file update. If OpenCode already finished, refresh the editor.');
+        } else if (hasWaiting) {
+          setStatus('Comment sent. Waiting for deck update...');
+        }
+      }
+
       function renderCommentThread() {
         els.commentThread.textContent = '';
         state.pendingComments.forEach((comment) => {
@@ -599,7 +637,8 @@ function renderEditorShell(token: string): string {
       }
 
       function commentStatusLabel(status) {
-        if (status === 'done') return '✅ Applied';
+        if (status === 'applied') return '✅ Applied';
+        if (status === 'stale') return 'Still waiting for deck file update';
         if (status === 'failed') return 'Failed to send';
         if (status === 'sending') return 'Sending to OpenCode...';
         return '⏳ Sent to OpenCode';

package/lib/qa/index.ts

@@ -2,8 +2,8 @@
  * lib/qa/index.ts
  *
  * Public entry point for hard-error slide QA.
- * Runs overflow measurement only; design compliance is an automatic post-write
- * hook concern, not part of manual/export QA.
+ * Runs overflow measurement only. Static design compliance is handled by a
+ * separate post-write/post-patch/post-edit hook.
  */
 
 import { measureSlides } from "./measure"
@@ -22,8 +22,8 @@ export type { RunChecksOptions } from "./checks"
  * 3. Runs hard-error overflow checks only
  * 4. Returns a structured QAReport
  *
- * Pass `vocabulary` (from `extractDesignClasses()`) to enable compliance checks.
- * Omit it to run geometry-only checks (backward compatible).
+ * The optional `vocabulary` argument is retained for backward compatibility;
+ * compliance is intentionally not part of hard-error QA.
  *
  * Throws if the file cannot be opened or Chrome is not found.
  */

package/package.json

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

package/plugin.ts

@@ -11,7 +11,7 @@
  * 5. experimental.chat.system.transform: inject three-layer prompt when enabled
  * 6. chat.message: intercept @-referenced / pasted binary files → extract text → replace FilePart with TextPart
  * 7. tool.execute.before: intercept read on DOCX/PPTX/XLSX → preRead()
- * 8. tool.execute.after: intercept read on PDF/images → postRead(); run fast design compliance after deck writes/patches/edits
+ * 8. tool.execute.after: intercept read on PDF/images → postRead(); run static compliance after deck writes/patches/edits
  */
 
 import type { Plugin } from "@opencode-ai/plugin"
@@ -98,6 +98,11 @@ const INTERNAL_AGENT_SIGNATURES = [
 ]
 
 function appendToolResult(output: any, text: string): void {
+  if (typeof output.output === "string") {
+    output.output = (output.output ? output.output + "\n\n" : "") + text
+    return
+  }
+
   const existing = output.result ?? ""
   output.result = (existing ? existing + "\n\n" : "") + text
 }
@@ -154,11 +159,11 @@ const server: Plugin = (async (pluginCtx) => {
 
       appendToolResult(
         output,
-        "---\n\n**[revela design compliance]** Auto-check completed:\n\n" +
+        "---\n\n**[revela design compliance]** Static check completed:\n\n" +
         formatReport(report)
       )
     } catch (e) {
-      childLog("qa").warn("auto compliance failed", {
+      childLog("compliance").warn("static compliance failed", {
         filePath,
         error: e instanceof Error ? e.message : String(e),
       })
@@ -613,7 +618,8 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
     // Handles PDF and images — read tool succeeds with base64 attachment.
     // PDF: extract text, remove base64. Images: jimp compress.
     //
-    // Also handles: fast design compliance after writing/patching/editing decks/*.html
+    // Also reports writes/patches blocked by the DECKS.json prewrite gate and
+    // runs lightweight static design compliance after successful deck changes.
     "tool.execute.after": async (input, output) => {
       if (!ctx.enabled) return
 
@@ -630,7 +636,7 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
         return
       }
 
-      // ── Fast design compliance after deck HTML writes/patches/edits ───
+      // ── Report blocked deck writes and run static compliance ──────────
       if (input.tool === "write") {
         const filePath: string = input.args?.filePath ?? ""
         const blockedReason = blockedDeckWrites.get(filePath)

package/skill/SKILL.md

@@ -232,8 +232,8 @@ layouts (cover, TOC, closing, quote, summary, etc.). When unsure, use `"false"`.
 
 Example: `<section class="slide" slide-qa="true" data-index="0">`
 
-The current QA path treats this as deck metadata. Automated checks focus on
-design compliance and hard overflow errors, not subjective fill or spacing.
+The export QA path treats this as deck metadata. It is consumed when PDF/PPTX
+export runs preflight checks.
 
 ### Domain Context
 
@@ -323,7 +323,7 @@ After generating, briefly tell the user:
 - How to navigate (arrow keys / swipe)
 - One line invitation to request changes
 
-Then use `revela-decks` to record written/QA status when available. Preserve
+Then use `revela-decks` to record written status when available. Preserve
 stable decisions in deck memory when useful.
 
 For change requests: re-generate the **entire** file (don't patch). Apply the
@@ -382,11 +382,14 @@ exclusively for fine-tuning spacing and sizing (`margin`, `padding`, `gap`,
 component — **NEVER adapt the component structure to fit content. NEVER create
 a new component because the existing ones "don't quite fit".**
 
-The automatic compliance check will flag any unrecognised CSS class. If the
-QA report contains compliance issues after you write the file, you MUST
-fix them immediately — remove the offending classes and replace them with the
-closest component from the Component Index. Do not move on until all compliance
-issues are resolved.
+The automatic static compliance check will flag any unrecognised CSS class after
+deck HTML writes or patches. If the tool result reports compliance issues, fix
+them immediately by removing the offending classes and replacing them with the
+closest component from the Component Index.
+
+Do not run `revela-qa` after writing or editing HTML unless the user explicitly
+asks for diagnostics. PDF/PPTX export commands run hard-error pre-export QA
+automatically and will report overflow issues that must be fixed before exporting.
 
 ### Inline Editing
 

package/tools/qa.ts

@@ -3,7 +3,7 @@
  *
  * revela-qa — Hard-error quality assurance for generated slide HTML files.
  *
- * Exposed to the LLM so it can check overflow and design compliance.
+ * Exposed as a manual diagnostic tool. Export commands run pre-export QA automatically.
  */
 
 import { tool } from "@opencode-ai/plugin"
@@ -17,7 +17,7 @@ export default tool({
     "Opens the file in a headless browser and measures actual rendered geometry. " +
     "Checks for element overflow. " +
     "Returns a structured report with specific issues and fix instructions. " +
-    "Call this when an edit may affect layout, or before delivery if export commands are not used.",
+    "Normally PDF/PPTX export commands run this automatically; call it directly only for explicit diagnostics.",
   args: {
     file: tool.schema
       .string()