@cyber-dash-tech/revela 0.13.0 → 0.14.0

package/lib/refine/server.ts

@@ -459,6 +459,7 @@ async function handleInspect(req: Request, session: EditSession): Promise<Respon
   }
 
   const snapshot = normalizeSnapshot(body?.snapshot ?? body)
+  const language = normalizeInspectLanguage(body?.language)
   const requestId = typeof body?.requestId === "string" && body.requestId.trim() ? body.requestId.trim() : randomBytes(10).toString("base64url")
   const version = readDeckVersion(session).version
   const staleReason = typeof body?.deckVersion === "string" && body.deckVersion !== version
@@ -480,6 +481,7 @@ async function handleInspect(req: Request, session: EditSession): Promise<Respon
           text: buildInspectionPrompt({
             requestId,
             file: session.file,
+            language,
             projection: staleReason
               ? { ...projection, stale: { stale: true, reason: staleReason } } as any
               : projection,
@@ -491,7 +493,7 @@ async function handleInspect(req: Request, session: EditSession): Promise<Respon
       failInspectRequest(requestId, message)
     })
 
-    return jsonResponse({ ok: true, requestId, deckVersion: version, status: "pending", preprocess })
+    return jsonResponse({ ok: true, requestId, deckVersion: version, status: "pending", language, preprocess })
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
     failInspectRequest(requestId, message)
@@ -510,6 +512,11 @@ function handleInspectResult(requestId: string | null, session: EditSession): Re
   return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion })
 }
 
+function normalizeInspectLanguage(input: unknown): string {
+  const value = typeof input === "string" ? input.trim() : ""
+  return value || "Auto"
+}
+
 function normalizeSnapshot(input: any): InspectionElementSnapshot {
   return {
     scope: input?.scope === "selection" || input?.scope === "slide" || input?.scope === "element" ? input.scope : undefined,
@@ -657,6 +664,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     .comment-bubble.stale .comment-bubble-state { color: #a16207; }
     .comment-bubble.failed .comment-bubble-state { color: #b91c1c; }
     .inspect-actions { display: flex; flex-direction: column; gap: 8px; }
+    .inspect-options { display: flex; flex-direction: column; gap: 5px; }
+    .inspect-options label { color: #64748b; font-size: 11px; font-weight: 800; text-transform: uppercase; letter-spacing: .05em; }
+    .inspect-select { width: 100%; padding: 10px 11px; border: 1px solid #d7e0ea; border-radius: 12px; background: #fff; color: #0f172a; font-weight: 700; }
     .inspect-cards { display: flex; flex-direction: column; gap: 12px; }
     .inspect-card { border: 1px solid #d7e0ea; border-radius: 16px; background: #fff; padding: 13px; box-shadow: 0 10px 24px rgba(15,23,42,.05); }
     .inspect-card-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 8px; }
@@ -681,7 +691,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     <aside>
       <div>
         <h1><span class="wordmark">REVELA</span> Refine</h1>
-        <p class="hint">Cmd/Ctrl-click slide elements once, then use Edit for fast changes or Inspect for Source/Purpose review.</p>
+        <p class="hint">Cmd/Ctrl-click slide elements once, then use Edit for fast changes or Inspect for Narrative Reading, Exploratory Reading, Source, and Purpose review.</p>
       </div>
       <div id="selectionSummary" class="selection-summary"><strong>Selection</strong><span>No references selected.</span><div id="selectionChips" class="selection-chips"></div></div>
       <div class="tabs" role="tablist" aria-label="Refine mode">
@@ -698,10 +708,11 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       </div>
       <div id="inspectPanel" class="tab-panel">
         <div class="inspect-actions">
+          <div class="inspect-options"><label for="inspectLanguage">Display Language</label><select id="inspectLanguage" class="inspect-select"><option>Auto</option><option>English</option><option>简体中文</option><option>繁體中文</option><option>日本語</option><option>Deutsch</option><option>Français</option><option>Español</option><option>Português</option><option>Arabic</option></select></div>
           <button id="inspectButton" disabled>Inspect Selection</button>
           <div id="inspectStale"></div>
         </div>
-        <div id="inspectCards" class="inspect-cards"><div class="inspect-empty">Select one or more deck elements, then inspect them for Source and Purpose. This does not edit the deck.</div></div>
+        <div id="inspectCards" class="inspect-cards"><div class="inspect-empty">Select one or more deck elements, then inspect them for Narrative Reading, Exploratory Reading, Source, and Purpose. This does not edit the deck.</div></div>
       </div>
       <div id="status" class="status"></div>
     </aside>
@@ -744,6 +755,8 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         mode: defaultMode === 'inspect' ? 'inspect' : 'edit',
         inspecting: false,
         activeInspectRequestId: '',
+        inspectLanguage: 'Auto',
+        inspectFallback: null,
       };
       const els = {
         frame: null,
@@ -759,6 +772,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         commentThread: null,
         send: null,
         inspectButton: null,
+        inspectLanguage: null,
         inspectCards: null,
         inspectStale: null,
         status: null,
@@ -792,7 +806,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           els.inspectStale = document.getElementById('inspectStale');
           els.status = document.getElementById('status');
 
-          if (!els.frame || !els.hitbox || !els.resizeHandle || !els.selectionSummary || !els.selectionChips || !els.editTab || !els.inspectTab || !els.editPanel || !els.inspectPanel || !els.comment || !els.commentThread || !els.send || !els.inspectButton || !els.inspectCards || !els.inspectStale || !els.status) {
+          els.inspectLanguage = document.getElementById('inspectLanguage');
+
+          if (!els.frame || !els.hitbox || !els.resizeHandle || !els.selectionSummary || !els.selectionChips || !els.editTab || !els.inspectTab || !els.editPanel || !els.inspectPanel || !els.comment || !els.commentThread || !els.send || !els.inspectButton || !els.inspectLanguage || !els.inspectCards || !els.inspectStale || !els.status) {
             throw new Error('Editor boot failed: required DOM nodes are missing.');
           }
 
@@ -840,6 +856,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         els.resizeHandle.addEventListener('dblclick', resetEditorWidth);
         els.send.addEventListener('click', sendComment);
         els.inspectButton.addEventListener('click', inspectCurrentSelection);
+        els.inspectLanguage.addEventListener('change', () => {
+          state.inspectLanguage = els.inspectLanguage.value || 'Auto';
+        });
         els.editTab.addEventListener('click', () => setMode('edit'));
         els.inspectTab.addEventListener('click', () => setMode('inspect'));
       }
@@ -1075,7 +1094,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         renderReferenceOutlines();
         updateSendState();
         renderSelectionSummary();
-        resetInspectCards('References ready. Open Inspect and click Inspect Selection when you want Source/Purpose review.');
+        resetInspectCards('References ready. Open Inspect and click Inspect Selection when you want Narrative Reading, Exploratory Reading, Source, and Purpose review.');
         setStatus('Inserted @' + label + '. ' + state.references.length + ' reference' + (state.references.length === 1 ? '' : 's') + ' will be sent.');
       }
 
@@ -1286,22 +1305,28 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         updateSendState();
         setMode('inspect');
         els.inspectStale.innerHTML = '';
-        els.inspectCards.innerHTML = '<div class="inspect-loading"><b>Preparing inspection...</b><br>Deterministic Source/Purpose appears first; generated cards update lazily.</div>';
+        state.inspectFallback = null;
+        els.inspectCards.innerHTML = '<div class="inspect-loading"><b>Reading selection...</b><br>Sending grounded selection context to OpenCode. Deterministic context is kept as fallback if generation fails.</div>';
         try {
           const res = await fetch('/api/inspect?token=' + encodeURIComponent(token), {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ snapshot, deckVersion: state.deckVersion }),
+            body: JSON.stringify({ snapshot, deckVersion: state.deckVersion, language: state.inspectLanguage }),
           });
           const body = await res.json().catch(() => ({}));
           if (!res.ok || !body.ok) throw new Error(body.error || 'Inspection failed');
           state.deckVersion = body.deckVersion || state.deckVersion;
           state.activeInspectRequestId = body.requestId;
-          if (body.preprocess) renderInspectResult(body.preprocess, 'Preprocessed');
-          els.inspectCards.insertAdjacentHTML('beforeend', '<div class="inspect-loading"><b>Generating lazy inspection...</b><br>Waiting for structured result from OpenCode.</div>');
+          state.inspectFallback = body.preprocess || null;
+          els.inspectCards.innerHTML = '<div class="inspect-loading"><b>Reading selection...</b><br>Waiting for localized structured reading cards.</div>';
           await pollInspectResult(body.requestId);
         } catch (error) {
-          resetInspectCards(error && error.message ? error.message : String(error));
+          if (state.inspectFallback) {
+            renderInspectResult(state.inspectFallback, 'Deterministic fallback');
+            els.inspectCards.insertAdjacentHTML('afterbegin', '<div class="inspect-warning">Generated inspection failed or timed out. Showing deterministic fallback context only.</div>');
+          } else {
+            resetInspectCards(error && error.message ? error.message : String(error));
+          }
         } finally {
           state.inspecting = false;
           updateSendState();
@@ -1309,7 +1334,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       }
 
       async function pollInspectResult(requestId) {
-        for (;;) {
+        for (let attempt = 0; attempt < 80; attempt++) {
           await delay(900);
           const res = await fetch('/api/inspect-result?token=' + encodeURIComponent(token) + '&requestId=' + encodeURIComponent(requestId));
           const body = await res.json().catch(() => ({}));
@@ -1321,6 +1346,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           }
           if (body.status === 'failed' || body.status === 'expired') throw new Error(body.error || 'Inspection failed');
         }
+        throw new Error('Inspection timed out while waiting for OpenCode result');
       }
 
       function collectReferenceSnapshot() {
@@ -1351,6 +1377,8 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         else els.inspectStale.innerHTML = '';
         els.inspectCards.innerHTML = [
           '<div class="status">' + escapeHtml(phase || 'Inspection') + '</div>',
+          result.cards.reading ? renderInspectCard('Narrative Reading', result.cards.reading.status, result.cards.reading.rationale, renderReading(result.cards.reading)) : '',
+          result.cards.exploratory ? renderInspectCard('Exploratory Reading', result.cards.exploratory.status, result.cards.exploratory.rationale, renderExploratory(result.cards.exploratory)) : '',
           renderInspectCard('Purpose', result.cards.purpose.status, result.cards.purpose.rationale, renderPurpose(result.cards.purpose)),
           renderInspectCard('Source', result.cards.source.status, result.cards.source.rationale, renderSource(result.cards.source)),
         ].join('');
@@ -1364,6 +1392,49 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         return '<div class="inspect-item">' + field('Role', card.role) + field('Why it matters', card.whyItMatters) + '</div>';
       }
 
+      function renderReading(card) {
+        return '<div class="inspect-item">'
+          + field('Claim ID', card.claimId)
+          + field('Canonical claim ID', card.canonicalClaimId)
+          + field('Claim', card.claimText)
+          + field('Evidence status', card.evidenceStatus)
+          + field('Evidence bindings', card.evidenceBindingIds && card.evidenceBindingIds.length ? card.evidenceBindingIds.join(', ') : '')
+          + field('Supported scope', card.supportedScope)
+          + field('Unsupported scope', card.unsupportedScope)
+          + '</div>'
+          + renderSectionList('Caveats', card.caveats)
+          + renderSectionList('Objections', card.relatedObjections)
+          + renderSectionList('Risks', card.relatedRisks)
+          + renderArtifactCoverage(card.artifactCoverage);
+      }
+
+      function renderArtifactCoverage(items) {
+        if (!items || !items.length) return '';
+        return '<div class="label">Artifact Coverage</div>' + items.map((item) => {
+          const title = (item.type || 'artifact') + (item.outputPath ? ' · ' + item.outputPath : '');
+          const status = (item.coverageStatus || 'unknown') + (item.containsClaim ? ' · contains claim' : ' · claim not rendered');
+          return '<div class="inspect-item"><b>' + escapeHtml(title) + '</b>'
+            + field('Coverage', status)
+            + field('Stale', item.stale ? (item.staleReason || 'stale') : '')
+            + field('Note', item.note)
+            + renderSectionList('Locations', item.locations)
+            + '</div>';
+        }).join('');
+      }
+
+      function renderExploratory(card) {
+        return '<div class="inspect-item"><b>Non-official reading aid</b>'
+          + field('Official artifact content', card.official === false ? 'No' : '')
+          + field('Audience', card.audience)
+          + field('Claim focus', card.claimFocus)
+          + field('Audience reframe boundary', card.audienceReframe)
+          + '</div>'
+          + renderSectionList('Objection Prep', card.objectionPrompts)
+          + renderSectionList('Appendix Leads', card.appendixLeads)
+          + renderSectionList('Meeting Prep', card.meetingPrep)
+          + renderSectionList('Boundaries', card.boundaries);
+      }
+
       function renderSource(card) {
         return renderSources(card.sources) + renderWarnings(card.warnings) + renderSectionList('Gaps', card.gaps) + renderSectionList('Caveats', card.caveats);
       }
@@ -1422,7 +1493,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         state.references = [];
         if (removeChips) els.comment.querySelectorAll('.ref-chip').forEach((chip) => chip.remove());
         renderSelectionSummary();
-        resetInspectCards('Select one or more deck elements, then inspect them for Source and Purpose. This does not edit the deck.');
+        resetInspectCards('Select one or more deck elements, then inspect them for Narrative Reading, Exploratory Reading, Source, and Purpose. This does not edit the deck.');
       }
 
       function getCommentText() {
@@ -1525,10 +1596,17 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       }
 
       function findSlide(node) {
-        return node.closest('.slide, [slide-qa], .slide-canvas, .page');
+        if (!node || !node.closest) return null;
+        return node.closest('.slide[data-slide-index]')
+          || node.closest('.slide')
+          || node.closest('[slide-qa]')
+          || node.closest('.slide-canvas')
+          || node.closest('.page');
       }
 
       function getSlides(doc) {
+        const canonicalSlides = Array.from(doc.querySelectorAll('.slide[data-slide-index]'));
+        if (canonicalSlides.length) return canonicalSlides;
         const slides = Array.from(doc.querySelectorAll('.slide'));
         if (slides.length) return slides;
         const qaSlides = Array.from(doc.querySelectorAll('[slide-qa]'));

package/package.json

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

package/plugin.ts

@@ -423,7 +423,7 @@ const server: Plugin = (async (pluginCtx) => {
       }
       if (sub === "edit") {
         if (param) {
-          await send("`/revela edit` no longer accepts a target. It opens the only HTML deck in `decks/`.")
+          await send("`/revela edit` is deprecated and does not accept a target. Use `/revela refine` for the unified refinement workspace.")
           throw new Error("__REVELA_EDIT_USAGE_HANDLED__")
         }
         await handleEdit({ client, sessionID, workspaceRoot }, send)
@@ -431,7 +431,7 @@ const server: Plugin = (async (pluginCtx) => {
       }
       if (sub === "inspect") {
         if (param) {
-          await send("`/revela inspect` does not accept a target. It opens the only HTML deck in `decks/`.")
+          await send("`/revela inspect` is deprecated and does not accept a target. Use `/revela refine` for the unified reading and refinement workspace.")
           throw new Error("__REVELA_INSPECT_USAGE_HANDLED__")
         }
         await handleInspect({ client, sessionID, workspaceRoot }, send)

package/tools/edit.ts

@@ -1,20 +1,20 @@
 /**
  * tools/edit.ts
  *
- * revela-edit — Open Revela's visual comment editor for an existing deck.
+ * revela-edit — Compatibility tool that opens Revela Refine in Edit mode.
  */
 
 import { tool } from "@opencode-ai/plugin"
-import { openEditableDeck } from "../lib/edit/open"
+import { openRefineDeck } from "../lib/refine/open"
 
 export function createEditTool(options: { client: any; workspaceRoot: string; openBrowser?: boolean }) {
   return tool({
     description:
-      "Open Revela's visual comment editor for an existing slide deck. " +
+      "Open Revela Refine in Edit mode for an existing slide deck. " +
       "Use this when the user asks to edit, revise, annotate, or visually comment on a deck, " +
       "including when they reference the current deck. " +
-      "Revela 0.8 opens the only HTML deck in decks/. " +
-      "This opens a local browser editor where the user can Ctrl/Cmd-click deck elements, write comments, " +
+      "This is a compatibility tool for the older edit-only workflow; the user-facing entry is /revela refine. " +
+      "It opens a local browser workspace where the user can Ctrl/Cmd-click deck elements, use the Edit tab, " +
       "and send precise edit requests back to the current OpenCode session.",
     args: {},
     async execute(_args, context: any) {
@@ -27,10 +27,11 @@ export function createEditTool(options: { client: any; workspaceRoot: string; op
       }
 
       try {
-        const result = openEditableDeck("", {
+        const result = openRefineDeck("", {
           client: options.client,
           sessionID,
           workspaceRoot: options.workspaceRoot,
+          mode: "edit",
           openBrowser: options.openBrowser,
         })
 
@@ -40,9 +41,10 @@ export function createEditTool(options: { client: any; workspaceRoot: string; op
           file: result.deck.file,
           source: result.source,
           url: result.url,
+          mode: result.mode,
           message:
-            `${result.stateNote} Opened visual editor. ` +
-            "Ask the user to use Ctrl/Cmd + click in the browser to reference elements, write a comment, then send comments.",
+            `${result.stateNote} Opened Revela Refine in Edit mode. ` +
+            "Ask the user to use Ctrl/Cmd-click in the browser to reference elements, then use the Edit tab to send comments.",
         }, null, 2)
       } catch (error) {
         return JSON.stringify({

package/tools/inspection-result.ts

@@ -29,6 +29,43 @@ export default tool({
       }).optional(),
       matchConfidence: tool.schema.enum(["none", "low", "medium", "high"]),
       cards: tool.schema.object({
+        reading: tool.schema.object({
+          status: tool.schema.enum(["matched", "no_match"]),
+          claimId: tool.schema.string().optional(),
+          canonicalClaimId: tool.schema.string().optional(),
+          claimText: tool.schema.string().optional(),
+          evidenceStatus: tool.schema.string().optional(),
+          evidenceBindingIds: tool.schema.array(tool.schema.string()),
+          supportedScope: tool.schema.string().optional(),
+          unsupportedScope: tool.schema.string().optional(),
+          caveats: tool.schema.array(tool.schema.string()),
+          relatedObjections: tool.schema.array(tool.schema.string()),
+          relatedRisks: tool.schema.array(tool.schema.string()),
+          artifactCoverage: tool.schema.array(tool.schema.object({
+            artifactId: tool.schema.string(),
+            type: tool.schema.string(),
+            outputPath: tool.schema.string().optional(),
+            coverageStatus: tool.schema.enum(["current", "stale", "partial", "missing"]),
+            containsClaim: tool.schema.boolean(),
+            stale: tool.schema.boolean(),
+            staleReason: tool.schema.string().optional(),
+            locations: tool.schema.array(tool.schema.string()),
+            note: tool.schema.string().optional(),
+          })).optional(),
+          rationale: tool.schema.string(),
+        }).optional(),
+        exploratory: tool.schema.object({
+          status: tool.schema.enum(["available", "limited", "unavailable"]),
+          official: tool.schema.boolean().describe("Must be false; exploratory reading is not official artifact content."),
+          audience: tool.schema.string().optional(),
+          claimFocus: tool.schema.string().optional(),
+          objectionPrompts: tool.schema.array(tool.schema.string()),
+          audienceReframe: tool.schema.string(),
+          appendixLeads: tool.schema.array(tool.schema.string()),
+          meetingPrep: tool.schema.array(tool.schema.string()),
+          boundaries: tool.schema.array(tool.schema.string()),
+          rationale: tool.schema.string(),
+        }).optional(),
         purpose: tool.schema.object({
           status: tool.schema.enum(["clear", "weak", "misplaced", "unknown"]),
           role: tool.schema.string().optional(),