@cyber-dash-tech/revela 0.16.3 → 0.16.4

package/lib/refine/server.ts

@@ -11,6 +11,7 @@ import { createInspectRequest, failInspectRequest, getInspectRequest } from "../
 import { saveMediaAsset } from "../media/save"
 import { searchRemoteImages, type ImageCandidate } from "../media/search"
 import type { MediaAssetRecord, MediaPurpose } from "../media/types"
+import { annotateVisualEditTargets, applyVisualTargetChanges, type VisualEditTarget } from "./visual-targets"
 
 const TOKEN_BYTES = 24
 const SESSION_TTL_MS = 2 * 60 * 60 * 1000
@@ -36,6 +37,8 @@ interface EditSession {
   createdAt: number
   lastActiveAt: number
   defaultMode: RefineMode
+  visualTargets: Map<string, VisualEditTarget>
+  visualTargetDeckVersion?: string
 }
 
 export type RefineMode = "edit" | "inspect"
@@ -79,6 +82,7 @@ export function startRefineServer(): RefineServerHandle {
         existing.session.file = input.deck.file
         existing.session.workspaceRoot = resolve(input.workspaceRoot)
         existing.session.defaultMode = input.mode ?? "edit"
+        existing.session.visualTargets = existing.session.visualTargets ?? new Map()
         return {
           token: existing.token,
           reused: true,
@@ -101,6 +105,7 @@ export function startRefineServer(): RefineServerHandle {
         createdAt: Date.now(),
         lastActiveAt: Date.now(),
         defaultMode: input.mode ?? "edit",
+        visualTargets: new Map(),
       })
       return { token, reused: false, live: false }
     },
@@ -193,6 +198,12 @@ async function handleRequest(req: Request): Promise<Response> {
     return handleDeckVersion(session.value)
   }
 
+  if (url.pathname === "/api/visual-changes" && req.method === "POST") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return handleVisualChanges(req, session.value)
+  }
+
   if (url.pathname === "/api/assets/search" && req.method === "GET") {
     const session = validateSession(url.searchParams.get("token"))
     if (!session.ok) return session.response
@@ -339,8 +350,12 @@ function handleDeck(session: EditSession): Response {
   session.assets.clear()
   session.assetKeys.clear()
   session.nextAssetId = 1
-  const html = readFileSync(session.absoluteFile, "utf-8")
-  return htmlResponse(rewriteLocalAssetRefs(html, {
+  const sourceHtml = readFileSync(session.absoluteFile, "utf-8")
+  const version = readDeckVersion(session).version
+  const annotated = annotateVisualEditTargets(sourceHtml)
+  session.visualTargets = annotated.targets
+  session.visualTargetDeckVersion = version
+  return htmlResponse(rewriteLocalAssetRefs(annotated.html, {
     session,
     sourceFile: session.absoluteFile,
     contentType: "html",
@@ -550,6 +565,33 @@ function readDeckVersion(session: EditSession): { mtimeMs: number; size: number;
   return { mtimeMs: stat.mtimeMs, size: stat.size, version }
 }
 
+async function handleVisualChanges(req: Request, session: EditSession): Promise<Response> {
+  let body: any
+  try {
+    body = await req.json()
+  } catch {
+    return jsonResponse({ ok: false, error: "Invalid JSON body" }, 400)
+  }
+
+  const changes = Array.isArray(body?.changes) ? body.changes : []
+  if (!changes.length) return jsonResponse({ ok: false, error: "No visual changes to save." }, 400)
+  try {
+    const result = applyVisualTargetChanges({
+      file: session.absoluteFile,
+      deckVersion: typeof body?.deckVersion === "string" ? body.deckVersion : undefined,
+      targetDeckVersion: session.visualTargetDeckVersion,
+      targets: session.visualTargets,
+      changes,
+    })
+    session.lastActiveAt = Date.now()
+    scheduleIdleStop()
+    return jsonResponse({ ok: true, deckVersion: result.deckVersion, changeCount: result.changeCount })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return jsonResponse({ ok: false, error: message }, 400)
+  }
+}
+
 async function handleComment(req: Request, session: EditSession): Promise<Response> {
   let body: Partial<EditCommentPayload>
   try {
@@ -778,6 +820,14 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     .resize-handle:hover::before, body.resizing .resize-handle::before { height: 52px; background: #94a3b8; box-shadow: 0 0 0 4px rgba(148,163,184,.16); }
     iframe { display: block; width: 100%; height: 100%; border: 0; background: #fff; }
     .hitbox { position: absolute; inset: 0; z-index: 2; cursor: crosshair; background: transparent; }
+    .visual-move-handle { position: absolute; z-index: 4; width: 16px; height: 16px; border: 2px solid #111827; border-radius: 999px; background: #fbfaf7; box-shadow: 0 6px 16px rgba(31,41,51,.22); transform: translate(-50%, -50%); pointer-events: none; display: none; }
+    .visual-move-handle::before { content: ""; position: absolute; inset: 4px; border-top: 2px solid #111827; border-left: 2px solid #111827; transform: rotate(45deg); }
+    .visual-resize-handle { position: absolute; z-index: 3; width: 14px; height: 14px; border: 2px solid #111827; border-radius: 4px; background: #fbfaf7; box-shadow: 0 6px 16px rgba(31,41,51,.22); transform: translate(-50%, -50%); pointer-events: none; display: none; }
+    .visual-resize-handle[data-mode="text-width"] { width: 10px; height: 28px; border-radius: 999px; cursor: ew-resize; }
+    .visual-edit-toolbar { position: absolute; top: 14px; left: 50%; z-index: 6; display: none; align-items: center; gap: 8px; transform: translateX(-50%); padding: 8px 10px; border: 1px solid rgba(148,163,184,.42); border-radius: 999px; background: rgba(17,24,39,.88); color: #fbfaf7; box-shadow: 0 16px 40px rgba(31,41,51,.26); backdrop-filter: blur(12px); -webkit-backdrop-filter: blur(12px); font-size: 12px; font-weight: 800; }
+    .visual-edit-toolbar.active { display: inline-flex; }
+    .visual-edit-toolbar button { width: auto; min-width: 0; padding: 7px 10px; border-radius: 999px; border-color: rgba(255,255,255,.2); background: rgba(255,255,255,.12); color: #fff; box-shadow: none; font-size: 12px; }
+    .visual-edit-toolbar .save-visual { background: #fbfaf7; color: #111827; }
     .deck-nav { position: absolute; left: 50%; bottom: 18px; z-index: 4; display: inline-flex; align-items: center; gap: 8px; transform: translateX(-50%); padding: 7px; border: 1px solid rgba(148,163,184,.42); border-radius: 999px; background: rgba(15,23,42,.76); box-shadow: 0 16px 44px rgba(15,23,42,.24); backdrop-filter: blur(14px); -webkit-backdrop-filter: blur(14px); pointer-events: auto; }
     .deck-nav button { width: auto; min-width: 84px; padding: 8px 12px; border-radius: 999px; background: rgba(255,255,255,.12); color: #fff; box-shadow: none; font-size: 12px; font-weight: 900; }
     .deck-nav button:hover:not(:disabled) { background: rgba(255,255,255,.22); }
@@ -882,7 +932,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
 </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><nav class="deck-nav" aria-label="Deck navigation"><button id="deckPrev" type="button" title="Previous slide (ArrowLeft / ArrowUp / PageUp)">Previous</button><div id="deckCounter" class="deck-nav-status" aria-live="polite">-- / --</div><button id="deckNext" type="button" title="Next slide (ArrowRight / ArrowDown / Space / PageDown)">Next</button></nav></section>
+    <section class="preview"><iframe id="deck" src="/deck?token=${encodeURIComponent(token)}"></iframe><div id="hitbox" class="hitbox" aria-label="Deck element selection layer"></div><div id="visualMoveHandle" class="visual-move-handle" aria-hidden="true"></div><div id="visualResizeHandle" class="visual-resize-handle" aria-hidden="true"></div><div id="visualEditToolbar" class="visual-edit-toolbar" aria-live="polite"><span id="visualEditCount">No unsaved visual changes</span><button id="visualUndo" type="button">Undo</button><button id="visualReset" type="button">Reset</button><button id="visualSave" class="save-visual" type="button">Save Changes</button></div><nav class="deck-nav" aria-label="Deck navigation"><button id="deckPrev" type="button" title="Previous slide (ArrowLeft / ArrowUp / PageUp)">Previous</button><div id="deckCounter" class="deck-nav-status" aria-live="polite">-- / --</div><button id="deckNext" type="button" title="Next slide (ArrowRight / ArrowDown / Space / PageDown)">Next</button></nav></section>
     <div id="resizeHandle" class="resize-handle" role="separator" aria-label="Resize editor panel" aria-orientation="vertical" title="Drag to resize editor. Double-click to reset."></div>
     <aside>
       <div>
@@ -970,6 +1020,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         resizeDrag: null,
         deckSlideIndex: 0,
         deckSlideCount: 0,
+        pendingDeckSlideRestore: null,
         mode: defaultMode === 'inspect' ? 'inspect' : 'edit',
         inspecting: false,
         activeInspectRequestId: '',
@@ -988,11 +1039,23 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         assetSearchKey: '',
         assetVisibleCount: 0,
         assetPendingCount: 0,
+        visualChanges: [],
+        activeVisualMove: null,
+        activeVisualResize: null,
+        hoverVisualTarget: null,
+        savingVisualChanges: false,
       };
       const els = {
         frame: null,
         hitbox: null,
         resizeHandle: null,
+        visualMoveHandle: null,
+        visualResizeHandle: null,
+        visualEditToolbar: null,
+        visualEditCount: null,
+        visualUndo: null,
+        visualReset: null,
+        visualSave: null,
         deckPrev: null,
         deckNext: null,
         deckCounter: null,
@@ -1036,6 +1099,13 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           els.frame = document.getElementById('deck');
           els.hitbox = document.getElementById('hitbox');
           els.resizeHandle = document.getElementById('resizeHandle');
+          els.visualMoveHandle = document.getElementById('visualMoveHandle');
+          els.visualResizeHandle = document.getElementById('visualResizeHandle');
+          els.visualEditToolbar = document.getElementById('visualEditToolbar');
+          els.visualEditCount = document.getElementById('visualEditCount');
+          els.visualUndo = document.getElementById('visualUndo');
+          els.visualReset = document.getElementById('visualReset');
+          els.visualSave = document.getElementById('visualSave');
           els.deckPrev = document.getElementById('deckPrev');
           els.deckNext = document.getElementById('deckNext');
           els.deckCounter = document.getElementById('deckCounter');
@@ -1065,7 +1135,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
 
           els.inspectLanguage = document.getElementById('inspectLanguage');
 
-          if (!els.frame || !els.hitbox || !els.resizeHandle || !els.deckPrev || !els.deckNext || !els.deckCounter || !els.selectionSummary || !els.selectionChips || !els.editTab || !els.inspectTab || !els.editPanel || !els.inspectPanel || !els.comment || !els.commentThread || !els.send || !els.inspectComment || !els.inspectButton || !els.inspectLanguage || !els.inspectCards || !els.inspectStale || !els.assetSearchToggle || !els.assetSearchBack || !els.assetSearchView || !els.assetQuery || !els.assetPurpose || !els.assetSearchButton || !els.assetShuffleButton || !els.assetResults || !els.editSavedAssets || !els.status) {
+          if (!els.frame || !els.hitbox || !els.resizeHandle || !els.visualMoveHandle || !els.visualResizeHandle || !els.visualEditToolbar || !els.visualEditCount || !els.visualUndo || !els.visualReset || !els.visualSave || !els.deckPrev || !els.deckNext || !els.deckCounter || !els.selectionSummary || !els.selectionChips || !els.editTab || !els.inspectTab || !els.editPanel || !els.inspectPanel || !els.comment || !els.commentThread || !els.send || !els.inspectComment || !els.inspectButton || !els.inspectLanguage || !els.inspectCards || !els.inspectStale || !els.assetSearchToggle || !els.assetSearchBack || !els.assetSearchView || !els.assetQuery || !els.assetPurpose || !els.assetSearchButton || !els.assetShuffleButton || !els.assetResults || !els.editSavedAssets || !els.status) {
             throw new Error('Editor boot failed: required DOM nodes are missing.');
           }
 
@@ -1132,6 +1202,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         }, { passive: false });
         els.resizeHandle.addEventListener('pointerdown', startEditorResize);
         els.resizeHandle.addEventListener('dblclick', resetEditorWidth);
+        els.visualUndo.addEventListener('click', undoVisualChange);
+        els.visualReset.addEventListener('click', resetVisualChanges);
+        els.visualSave.addEventListener('click', saveVisualChanges);
         els.deckPrev.addEventListener('click', prevDeckSlide);
         els.deckNext.addEventListener('click', nextDeckSlide);
         els.send.addEventListener('click', sendComment);
@@ -1223,6 +1296,329 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         setEditorWidth(DEFAULT_EDITOR_WIDTH, true);
       }
 
+      function isDirectResizable(target) {
+        if (!target || !target.dataset || !target.dataset.revelaEditId || !target.dataset.revelaEditKind) return false;
+        if (target.dataset.revelaEditKind === 'image') return target.tagName?.toLowerCase() === 'img';
+        if (target.dataset.revelaEditKind === 'box') {
+          const computed = els.frame.contentWindow?.getComputedStyle(target);
+          return computed ? computed.display !== 'inline' : true;
+        }
+        if (target.dataset.revelaEditKind === 'text-width') {
+          const computed = els.frame.contentWindow?.getComputedStyle(target);
+          return computed ? computed.display !== 'inline' : true;
+        }
+        return false;
+      }
+
+      function isDirectMovable(target) {
+        return isDirectResizable(target);
+      }
+
+      function visualResizeMode(target) {
+        if (target?.dataset?.revelaEditKind === 'text-width') return 'text-width';
+        if (target?.dataset?.revelaEditKind === 'image') return 'image';
+        return 'box';
+      }
+
+      function visualChangeKey(payload) {
+        return (payload?.type || '') + ':' + (payload?.editId || '');
+      }
+
+      function upsertVisualChange(change) {
+        const key = visualChangeKey(change);
+        const existing = state.visualChanges.find((item) => visualChangeKey(item) === key);
+        if (existing) {
+          existing.after = change.after;
+          return;
+        }
+        state.visualChanges.push(change);
+      }
+
+      function currentTranslate(target) {
+        const computed = els.frame.contentWindow?.getComputedStyle(target);
+        return simpleTranslateFromTranslate(target.style.translate)
+          || simpleTranslateFromTranslate(computed?.translate)
+          || simpleTranslateFromTransform(target.style.transform)
+          || simpleTranslateFromTransform(computed?.transform)
+          || { x: 0, y: 0 };
+      }
+
+      function simpleTranslateFromTranslate(translate) {
+        const normalized = String(translate || '').trim();
+        if (!normalized || normalized === 'none') return null;
+        const match = /^(-?\d+(?:\.\d+)?)px(?:\s+|\s*,\s*)(-?\d+(?:\.\d+)?)px$/.exec(normalized);
+        return match ? finitePoint(Number(match[1]), Number(match[2])) : null;
+      }
+
+      function simpleTranslateFromTransform(transform) {
+        const normalized = String(transform || '').trim();
+        if (!normalized || normalized === 'none') return { x: 0, y: 0 };
+        const translate = /^translate\(\s*(-?\d+(?:\.\d+)?)px(?:\s*,\s*|\s+)(-?\d+(?:\.\d+)?)px\s*\)$/.exec(normalized);
+        if (translate) return finitePoint(Number(translate[1]), Number(translate[2]));
+        const matrix = /^matrix\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)$/.exec(normalized);
+        if (!matrix) return null;
+        const a = Number(matrix[1]);
+        const b = Number(matrix[2]);
+        const c = Number(matrix[3]);
+        const d = Number(matrix[4]);
+        if (a !== 1 || b !== 0 || c !== 0 || d !== 1) return null;
+        return finitePoint(Number(matrix[5]), Number(matrix[6]));
+      }
+
+      function finitePoint(x, y) {
+        return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null;
+      }
+
+      function renderVisualMoveHandle(target) {
+        if (!els.visualMoveHandle) return;
+        if (!target || !isDirectMovable(target) || state.activeVisualMove) {
+          els.visualMoveHandle.style.display = 'none';
+          return;
+        }
+        const rect = target.getBoundingClientRect();
+        els.visualMoveHandle.style.display = 'block';
+        els.visualMoveHandle.style.left = rect.left + 'px';
+        els.visualMoveHandle.style.top = rect.top + 'px';
+      }
+
+      function boundedImageSize(active, event) {
+        const dx = event.clientX - active.startX;
+        const dy = event.clientY - active.startY;
+        const width = Math.max(24, Math.round(active.startWidth + dx));
+        if (event.shiftKey) return { width, height: Math.max(24, Math.round(active.startHeight + dy)) };
+        const ratio = active.startHeight && active.startWidth ? active.startHeight / active.startWidth : 1;
+        return { width, height: Math.max(24, Math.round(width * ratio)) };
+      }
+
+      function boundedBoxSize(active, event) {
+        return {
+          width: Math.max(40, Math.round(active.startWidth + event.clientX - active.startX)),
+          height: Math.max(24, Math.round(active.startHeight + event.clientY - active.startY)),
+        };
+      }
+
+      function boundedTextWidth(active, event) {
+        return Math.max(80, Math.round(active.startWidth + event.clientX - active.startX));
+      }
+
+      function renderVisualResizeHandle(target) {
+        if (!els.visualResizeHandle) return;
+        if (!target || !isDirectResizable(target) || state.activeVisualResize) {
+          els.visualResizeHandle.style.display = 'none';
+          return;
+        }
+        const rect = target.getBoundingClientRect();
+        const mode = visualResizeMode(target);
+        els.visualResizeHandle.dataset.mode = mode;
+        els.visualResizeHandle.style.display = 'block';
+        els.visualResizeHandle.style.left = rect.right + 'px';
+        els.visualResizeHandle.style.top = (mode === 'text-width' ? rect.top + rect.height / 2 : rect.bottom) + 'px';
+      }
+
+      function renderVisualHandles(target) {
+        state.hoverVisualTarget = target && (isDirectResizable(target) || isDirectMovable(target)) ? target : null;
+        renderVisualMoveHandle(state.hoverVisualTarget);
+        renderVisualResizeHandle(state.hoverVisualTarget);
+      }
+
+      function pointerIsOnVisualMoveHandle(event) {
+        if (!state.hoverVisualTarget || !els.visualMoveHandle || els.visualMoveHandle.style.display === 'none') return false;
+        const rect = els.visualMoveHandle.getBoundingClientRect();
+        return event.clientX >= rect.left - 6 && event.clientX <= rect.right + 6 && event.clientY >= rect.top - 6 && event.clientY <= rect.bottom + 6;
+      }
+
+      function pointerIsOnVisualResizeHandle(event) {
+        if (!state.hoverVisualTarget || !els.visualResizeHandle || els.visualResizeHandle.style.display === 'none') return false;
+        const rect = els.visualResizeHandle.getBoundingClientRect();
+        return event.clientX >= rect.left - 6 && event.clientX <= rect.right + 6 && event.clientY >= rect.top - 6 && event.clientY <= rect.bottom + 6;
+      }
+
+      function startVisualMove(event) {
+        const target = state.hoverVisualTarget;
+        if (!target || !isDirectMovable(target)) return false;
+        event.preventDefault();
+        event.stopPropagation();
+        const beforeStyle = target.getAttribute('style') || '';
+        const startTranslate = currentTranslate(target);
+        state.activeVisualMove = {
+          target,
+          payload: { editId: target.dataset.revelaEditId, kind: target.dataset.revelaEditKind },
+          startX: event.clientX,
+          startY: event.clientY,
+          beforeStyle,
+          startTranslate,
+        };
+        setStatus('Moving preview only. Click Save Changes to write the deck.');
+        window.addEventListener('pointermove', updateVisualMove);
+        window.addEventListener('pointerup', finishVisualMove, { once: true });
+        return true;
+      }
+
+      function updateVisualMove(event) {
+        const active = state.activeVisualMove;
+        if (!active) return;
+        let dx = Math.round(event.clientX - active.startX);
+        let dy = Math.round(event.clientY - active.startY);
+        if (event.shiftKey) {
+          if (Math.abs(dx) >= Math.abs(dy)) dy = 0;
+          else dx = 0;
+        }
+        const nextX = active.startTranslate.x + dx;
+        const nextY = active.startTranslate.y + dy;
+        active.target.style.translate = nextX + 'px ' + nextY + 'px';
+        renderHoverOutline(active.target);
+        renderVisualMoveHandle(active.target);
+        renderVisualResizeHandle(active.target);
+      }
+
+      function finishVisualMove() {
+        const active = state.activeVisualMove;
+        state.activeVisualMove = null;
+        window.removeEventListener('pointermove', updateVisualMove);
+        if (!active) return;
+        const translate = active.target.style.translate || 'none';
+        if (translate !== 'none') {
+          upsertVisualChange({
+            type: 'move',
+            editId: active.payload.editId,
+            kind: active.payload.kind,
+            before: { style: active.beforeStyle },
+            after: { stylePatch: { translate } },
+          });
+        }
+        updateVisualToolbar();
+        renderVisualMoveHandle(active.target);
+        renderVisualResizeHandle(active.target);
+      }
+
+      function startVisualResize(event) {
+        const target = state.hoverVisualTarget;
+        if (!target || !isDirectResizable(target)) return false;
+        event.preventDefault();
+        event.stopPropagation();
+        const rect = target.getBoundingClientRect();
+        const tag = target.tagName.toLowerCase();
+        const beforeStyle = target.getAttribute('style') || '';
+        state.activeVisualResize = {
+          target,
+          payload: { editId: target.dataset.revelaEditId, kind: target.dataset.revelaEditKind },
+          tag,
+          startX: event.clientX,
+          startY: event.clientY,
+          startWidth: rect.width,
+          startHeight: rect.height,
+          beforeStyle,
+          mode: visualResizeMode(target),
+          before: { width: rect.width, height: rect.height },
+        };
+        setStatus('Resizing preview only. Click Save Changes to write the deck.');
+        window.addEventListener('pointermove', updateVisualResize);
+        window.addEventListener('pointerup', finishVisualResize, { once: true });
+        return true;
+      }
+
+      function updateVisualResize(event) {
+        const active = state.activeVisualResize;
+        if (!active) return;
+        if (active.mode === 'text-width') {
+          const width = boundedTextWidth(active, event);
+          active.target.style.width = width + 'px';
+          active.target.style.maxWidth = width + 'px';
+        } else if (active.mode === 'image') {
+          const size = boundedImageSize(active, event);
+          const width = size.width;
+          const height = size.height;
+          active.target.style.width = width + 'px';
+          active.target.style.height = height + 'px';
+        } else {
+          const size = boundedBoxSize(active, event);
+          active.target.style.width = size.width + 'px';
+          active.target.style.height = size.height + 'px';
+        }
+        renderHoverOutline(active.target);
+        renderVisualMoveHandle(active.target);
+        renderVisualResizeHandle(active.target);
+      }
+
+      function finishVisualResize() {
+        const active = state.activeVisualResize;
+        state.activeVisualResize = null;
+        window.removeEventListener('pointermove', updateVisualResize);
+        if (!active) return;
+        const rect = active.target.getBoundingClientRect();
+        const stylePatch = active.mode === 'text-width'
+          ? { width: Math.round(rect.width) + 'px', 'max-width': Math.round(rect.width) + 'px' }
+          : { width: Math.round(rect.width) + 'px', height: Math.round(rect.height) + 'px' };
+        upsertVisualChange({
+          type: 'resize',
+          editId: active.payload.editId,
+          kind: active.payload.kind,
+          before: { style: active.beforeStyle, width: active.before.width, height: active.before.height },
+          after: { stylePatch, width: rect.width, height: rect.height },
+        });
+        updateVisualToolbar();
+        renderVisualMoveHandle(active.target);
+        renderVisualResizeHandle(active.target);
+      }
+
+      function undoVisualChange() {
+        const change = state.visualChanges.pop();
+        if (!change) return;
+        const target = elementFromVisualChange(change);
+        if (target) target.setAttribute('style', change.before.style || '');
+        updateVisualToolbar();
+        renderHoverOutline(state.hoverEl);
+        renderVisualHandles(state.hoverEl);
+        setStatus('Undid last visual change.');
+      }
+
+      function resetVisualChanges() {
+        while (state.visualChanges.length) {
+          const change = state.visualChanges.pop();
+          const target = change ? elementFromVisualChange(change) : null;
+          if (target) target.setAttribute('style', change.before.style || '');
+        }
+        updateVisualToolbar();
+        renderHoverOutline(state.hoverEl);
+        renderVisualHandles(state.hoverEl);
+        setStatus('Reset unsaved visual changes.');
+      }
+
+      function updateVisualToolbar() {
+        const count = state.visualChanges.length;
+        els.visualEditToolbar.classList.toggle('active', count > 0);
+        els.visualEditCount.textContent = count + ' unsaved visual change' + (count === 1 ? '' : 's');
+        els.visualUndo.disabled = count === 0 || state.savingVisualChanges;
+        els.visualReset.disabled = count === 0 || state.savingVisualChanges;
+        els.visualSave.disabled = count === 0 || state.savingVisualChanges;
+      }
+
+      async function saveVisualChanges() {
+        if (!state.visualChanges.length || state.savingVisualChanges) return;
+        state.savingVisualChanges = true;
+        updateVisualToolbar();
+        setStatus('Saving visual changes...');
+        try {
+          const res = await fetch('/api/visual-changes?token=' + encodeURIComponent(token), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ deckVersion: state.deckVersion, changes: state.visualChanges }),
+          });
+          const body = await res.json().catch(() => ({}));
+          if (!res.ok || !body.ok) throw new Error(body.error || 'Could not save visual changes.');
+          state.visualChanges = [];
+          state.deckVersion = body.deckVersion || state.deckVersion;
+          updateVisualToolbar();
+          refreshDeckPreview(Date.now());
+          setStatus('Visual changes saved. Refreshing preview...');
+        } catch (error) {
+          reportError(error);
+        } finally {
+          state.savingVisualChanges = false;
+          updateVisualToolbar();
+        }
+      }
+
       function setEditorWidth(width, persist) {
         const nextWidth = clampEditorWidth(width);
         document.querySelector('.app')?.style.setProperty('--editor-width', nextWidth + 'px');
@@ -1255,10 +1651,12 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           state.referenceOutlines = [];
           doc.addEventListener('scroll', () => {
             renderHoverOutline(state.hoverEl);
+            renderVisualHandles(state.hoverEl);
             renderReferenceOutlines();
           }, true);
           const slides = getSlides(doc);
           syncDeckNavigation();
+          restoreDeckSlideAfterRefresh();
           updateSendState();
           if (state.pendingRefreshMessage) {
             state.pendingRefreshMessage = false;
@@ -1342,12 +1740,47 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           updateDeckNavControls();
           if (changed) clearHoverSilently();
           else renderHoverOutline(state.hoverEl);
+          renderVisualHandles(state.hoverEl);
           renderReferenceOutlines();
         } catch (error) {
           reportError(error);
         }
       }
 
+      function restoreDeckSlideAfterRefresh() {
+        if (state.pendingDeckSlideRestore === null || state.pendingDeckSlideRestore === undefined) return;
+        const targetIndex = state.pendingDeckSlideRestore;
+        state.pendingDeckSlideRestore = null;
+        restoreDeckSlide(targetIndex);
+      }
+
+      function restoreDeckSlide(index) {
+        try {
+          const doc = els.frame.contentDocument;
+          const win = els.frame.contentWindow;
+          if (!doc || !win) return;
+          const slides = getSlides(doc);
+          if (!slides.length) {
+            syncDeckNavigation();
+            return;
+          }
+          const clamped = Math.max(0, Math.min(slides.length - 1, index));
+          const nav = win.RevelaDeckNav;
+          let handled = false;
+          if (nav && typeof nav.goTo === 'function') {
+            try {
+              nav.goTo(clamped);
+              handled = true;
+            } catch {}
+          }
+          if (!handled) applyFallbackDeckNavigation(win, doc, slides, clamped);
+          state.deckSlideIndex = clamped;
+          updateDeckNavControls();
+        } catch (error) {
+          reportError(error);
+        }
+      }
+
       function applyFallbackDeckNavigation(win, doc, slides, index) {
         const target = slides[index];
         const usesOverlaySlides = slides.some((slide) => {
@@ -1400,10 +1833,16 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
 
       function refreshDeckPreview(version) {
         state.pendingRefreshMessage = true;
+        state.pendingDeckSlideRestore = state.deckSlideIndex;
         state.initializedDoc = null;
+        state.visualChanges = [];
+        updateVisualToolbar();
         clearReferences(true);
         state.hoverEl = null;
         if (state.hoverOutline) state.hoverOutline.style.display = 'none';
+        if (els.visualMoveHandle) els.visualMoveHandle.style.display = 'none';
+        if (els.visualResizeHandle) els.visualResizeHandle.style.display = 'none';
+        state.hoverVisualTarget = null;
         state.assetDropTarget = null;
         if (state.assetDropOutline) state.assetDropOutline.style.display = 'none';
         state.referenceOutlines.forEach((outline) => outline.style.display = 'none');
@@ -1416,14 +1855,17 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       function onHover(event) {
         try {
           initFrame();
-          const target = selectable(targetFromPointer(event));
+          const directTarget = visualTargetFromPointer(event);
+          const target = directTarget || selectable(targetFromPointer(event));
           if (!target || isReferenced(target)) {
             state.hoverEl = null;
             renderHoverOutline(null);
+            renderVisualHandles(null);
             return;
           }
           state.hoverEl = target;
           renderHoverOutline(target);
+          renderVisualHandles(target);
         } catch (error) {
           reportError(error);
         }
@@ -1446,6 +1888,12 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       }
 
       function onPointerDown(event) {
+        if (!event.ctrlKey && !event.metaKey && pointerIsOnVisualMoveHandle(event)) {
+          if (startVisualMove(event)) return;
+        }
+        if (!event.ctrlKey && !event.metaKey && pointerIsOnVisualResizeHandle(event)) {
+          if (startVisualResize(event)) return;
+        }
         if (!event.ctrlKey && !event.metaKey) return;
         try {
           initFrame();
@@ -1779,6 +2227,17 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         return slide;
       }
 
+      function elementFromVisualChange(change) {
+        const editId = change?.editId;
+        const doc = els.frame.contentDocument;
+        if (!editId || !doc) return null;
+        try {
+          return doc.querySelector('[data-revela-edit-id="' + cssEscape(editId) + '"]');
+        } catch {
+          return null;
+        }
+      }
+
       async function sendAssetPlacement(asset, placement) {
         const modeText = placement.targetMode === 'replace'
           ? 'replace the image at the drop target'
@@ -1968,6 +2427,12 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         return doc.elementFromPoint(x, y);
       }
 
+      function visualTargetFromPointer(event) {
+        const raw = targetFromPointer(event);
+        const target = raw?.closest?.('[data-revela-edit-id]') || null;
+        return isDirectResizable(target) || isDirectMovable(target) ? target : null;
+      }
+
       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;';
@@ -2020,12 +2485,14 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       function clearHoverSilently() {
         state.hoverEl = null;
         if (state.hoverOutline) state.hoverOutline.style.display = 'none';
+        renderVisualHandles(null);
       }
 
       function clearHover() {
         state.hoverEl = null;
         setStatus('Hover cleared. Existing references are kept.');
         if (state.hoverOutline) state.hoverOutline.style.display = 'none';
+        renderVisualHandles(null);
       }
 
       function updateSendState() {

package/lib/refine/visual-targets.ts

@@ -0,0 +1,295 @@
+import { readFileSync, statSync, writeFileSync } from "fs"
+
+export type VisualEditKind = "image" | "text-width" | "box"
+
+export interface VisualEditTarget {
+  editId: string
+  kind: VisualEditKind
+  tagName: "img" | "h1" | "h2" | "h3" | "h4" | "p" | "div" | "figure"
+  startOffset: number
+  openEndOffset: number
+  originalOpenTag: string
+  originalStyle: string
+}
+
+export interface VisualTargetResizeChange {
+  type: "resize"
+  editId: string
+  kind?: VisualEditKind
+  after: {
+    stylePatch?: Record<string, unknown>
+    width?: number
+    height?: number
+  }
+}
+
+export interface VisualTargetMoveChange {
+  type: "move"
+  editId: string
+  kind?: VisualEditKind
+  after: {
+    stylePatch?: Record<string, unknown>
+    dx?: number
+    dy?: number
+  }
+}
+
+export type VisualTargetChange = VisualTargetResizeChange | VisualTargetMoveChange
+
+export interface ApplyVisualTargetChangesInput {
+  file: string
+  deckVersion?: string
+  targetDeckVersion?: string
+  targets: Map<string, VisualEditTarget>
+  changes: VisualTargetChange[]
+}
+
+export interface ApplyVisualTargetChangesResult {
+  ok: true
+  deckVersion: string
+  changeCount: number
+}
+
+const TEXT_TAGS = new Set(["h1", "h2", "h3", "h4", "p"])
+const BOX_TAGS = new Set(["div", "figure"])
+const EDIT_TAGS = new Set(["img", ...TEXT_TAGS, ...BOX_TAGS])
+const MAX_DIMENSION_PX = 3840
+const MIN_IMAGE_DIMENSION_PX = 24
+const MIN_TEXT_WIDTH_PX = 80
+const MIN_BOX_WIDTH_PX = 40
+const MIN_BOX_HEIGHT_PX = 24
+
+export function annotateVisualEditTargets(html: string): { html: string; targets: Map<string, VisualEditTarget> } {
+  const targets = new Map<string, VisualEditTarget>()
+  const insertions: Array<{ offset: number; text: string }> = []
+  let nextId = 1
+
+  for (const tag of scanOpeningTags(html)) {
+    if (!EDIT_TAGS.has(tag.tagName)) continue
+    if (BOX_TAGS.has(tag.tagName) && !isSafeBoxTarget(tag.openTag)) continue
+    const editId = `rve-${nextId++}`
+    const kind: VisualEditKind = tag.tagName === "img" ? "image" : BOX_TAGS.has(tag.tagName) ? "box" : "text-width"
+    targets.set(editId, {
+      editId,
+      kind,
+      tagName: tag.tagName as VisualEditTarget["tagName"],
+      startOffset: tag.startOffset,
+      openEndOffset: tag.openEndOffset,
+      originalOpenTag: tag.openTag,
+      originalStyle: attrValue(tag.openTag, "style") || "",
+    })
+    insertions.push({ offset: tag.openEndOffset - (tag.openTag.endsWith("/>") ? 2 : 1), text: ` data-revela-edit-id="${editId}" data-revela-edit-kind="${kind}"` })
+  }
+
+  let annotated = html
+  for (const insertion of insertions.reverse()) {
+    annotated = annotated.slice(0, insertion.offset) + insertion.text + annotated.slice(insertion.offset)
+  }
+  return { html: annotated, targets }
+}
+
+export function applyVisualTargetChanges(input: ApplyVisualTargetChangesInput): ApplyVisualTargetChangesResult {
+  const currentVersion = readDeckVersion(input.file).version
+  if (input.deckVersion && input.deckVersion !== currentVersion) throw new Error("Deck changed outside Review. Refresh Review before saving visual edits.")
+  if (input.targetDeckVersion && input.targetDeckVersion !== currentVersion) throw new Error("Review visual targets are stale. Refresh Review before saving visual edits.")
+  if (!input.changes.length) throw new Error("No visual changes to save.")
+
+  let html = readFileSync(input.file, "utf-8")
+  const resolved = new Map<string, { target: VisualEditTarget; patch: Record<string, string> }>()
+  for (const change of input.changes) {
+    const target = input.targets.get(change.editId)
+    if (!target) throw new Error("Target is no longer editable. Refresh Review and try again.")
+    if (change.kind && change.kind !== target.kind) throw new Error("Visual edit target kind changed. Refresh Review and try again.")
+    const currentOpenTag = html.slice(target.startOffset, target.openEndOffset)
+    if (currentOpenTag !== target.originalOpenTag) throw new Error("Target is no longer editable. Refresh Review and try again.")
+    const patch = normalizeStylePatch(target, change)
+    if (!Object.keys(patch).length) throw new Error("Visual change does not contain valid style updates.")
+    const existing = resolved.get(target.editId)
+    resolved.set(target.editId, { target, patch: { ...(existing?.patch ?? {}), ...patch } })
+  }
+
+  for (const { target, patch } of Array.from(resolved.values()).sort((a, b) => b.target.startOffset - a.target.startOffset)) {
+    const updatedOpenTag = patchOpenTagStyle(target.originalOpenTag, patch)
+    html = html.slice(0, target.startOffset) + updatedOpenTag + html.slice(target.openEndOffset)
+  }
+
+  writeFileSync(input.file, html, "utf-8")
+  return { ok: true, deckVersion: readDeckVersion(input.file).version, changeCount: input.changes.length }
+}
+
+export function readDeckVersion(file: string): { mtimeMs: number; size: number; version: string } {
+  const stat = statSync(file)
+  return { mtimeMs: stat.mtimeMs, size: stat.size, version: `${stat.mtimeMs}:${stat.size}` }
+}
+
+function normalizeStylePatch(target: VisualEditTarget, change: VisualTargetChange): Record<string, string> {
+  const input = change.after.stylePatch ?? {}
+  if (change.type === "move") return normalizeMovePatch(target, input)
+  if (change.type !== "resize") throw new Error(`Unsupported visual change type: ${(change as any).type}`)
+  return normalizeResizePatch(target.kind, input)
+}
+
+function normalizeResizePatch(kind: VisualEditKind, input: Record<string, unknown>): Record<string, string> {
+  const patch: Record<string, string> = {}
+  const width = typeof input.width === "string" ? normalizePxValue(input.width, kind === "image" ? MIN_IMAGE_DIMENSION_PX : kind === "box" ? MIN_BOX_WIDTH_PX : MIN_TEXT_WIDTH_PX) : null
+  if (width) patch.width = width
+  if (kind === "image" || kind === "box") {
+    const height = typeof input.height === "string" ? normalizePxValue(input.height, kind === "image" ? MIN_IMAGE_DIMENSION_PX : MIN_BOX_HEIGHT_PX) : null
+    if (height) patch.height = height
+  } else {
+    const maxWidth = typeof input["max-width"] === "string" ? normalizePxValue(input["max-width"], MIN_TEXT_WIDTH_PX) : null
+    if (maxWidth) patch["max-width"] = maxWidth
+  }
+  return patch
+}
+
+function normalizeMovePatch(target: VisualEditTarget, input: Record<string, unknown>): Record<string, string> {
+  const translate = typeof input.translate === "string" ? normalizeTranslateValue(input.translate) : null
+  if (translate) return { translate }
+  const transform = typeof input.transform === "string" ? normalizeLegacyTransformValue(input.transform) : null
+  return transform ? { translate: transform } : {}
+}
+
+function normalizeTranslateValue(value: string): string | null {
+  const direct = parseTranslateProperty(value)
+  if (direct) return normalizeTranslatePoint(direct)
+  return normalizeLegacyTransformValue(value)
+}
+
+function normalizeLegacyTransformValue(value: string): string | null {
+  const parsed = parseSimpleTranslate(value)
+  if (!parsed) return null
+  return normalizeTranslatePoint(parsed)
+}
+
+function normalizeTranslatePoint(parsed: { x: number; y: number }): string | null {
+  const { x, y } = parsed
+  if (Math.abs(x) > MAX_DIMENSION_PX || Math.abs(y) > MAX_DIMENSION_PX) return null
+  return `${Math.round(x)}px ${Math.round(y)}px`
+}
+
+function parseTranslateProperty(value: string): { x: number; y: number } | null {
+  const normalized = value.trim()
+  const match = /^(-?\d+(?:\.\d+)?)px(?:\s+|\s*,\s*)(-?\d+(?:\.\d+)?)px$/.exec(normalized)
+  return match ? finitePoint(Number(match[1]), Number(match[2])) : null
+}
+
+function parseSimpleTranslate(value: string): { x: number; y: number } | null {
+  const normalized = value.trim()
+  if (!normalized || normalized === "none") return { x: 0, y: 0 }
+  const translate = /^translate\(\s*(-?\d+(?:\.\d+)?)px(?:\s*,\s*|\s+)(-?\d+(?:\.\d+)?)px\s*\)$/.exec(normalized)
+  if (translate) return finitePoint(Number(translate[1]), Number(translate[2]))
+  const matrix = /^matrix\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)$/.exec(normalized)
+  if (!matrix) return null
+  const a = Number(matrix[1])
+  const b = Number(matrix[2])
+  const c = Number(matrix[3])
+  const d = Number(matrix[4])
+  if (a !== 1 || b !== 0 || c !== 0 || d !== 1) return null
+  return finitePoint(Number(matrix[5]), Number(matrix[6]))
+}
+
+function finitePoint(x: number, y: number): { x: number; y: number } | null {
+  return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null
+}
+
+function normalizePxValue(value: string, min: number): string | null {
+  const match = /^(\d+(?:\.\d+)?)px$/.exec(value.trim())
+  if (!match) return null
+  const number = Number(match[1])
+  if (!Number.isFinite(number) || number < min || number > MAX_DIMENSION_PX) return null
+  return `${Math.round(number)}px`
+}
+
+function patchOpenTagStyle(openTag: string, patch: Record<string, string>): string {
+  const styleMatch = /\sstyle=("([^"]*)"|'([^']*)')/i.exec(openTag)
+  const current = styleMatch ? parseStyle(styleMatch[2] ?? styleMatch[3] ?? "") : {}
+  const next = serializeStyle({ ...current, ...patch })
+  if (styleMatch) return openTag.slice(0, styleMatch.index) + ` style="${escapeAttr(next)}"` + openTag.slice(styleMatch.index + styleMatch[0].length)
+  return openTag.replace(/\s*\/?>$/, (ending) => ` style="${escapeAttr(next)}"${ending}`)
+}
+
+function parseStyle(style: string): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const part of style.split(";")) {
+    const index = part.indexOf(":")
+    if (index < 0) continue
+    const key = part.slice(0, index).trim().toLowerCase()
+    const value = part.slice(index + 1).trim()
+    if (key && value) result[key] = value
+  }
+  return result
+}
+
+function serializeStyle(style: Record<string, string>): string {
+  return Object.entries(style).map(([key, value]) => `${key}: ${value}`).join("; ")
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;")
+}
+
+interface OpenTagRegion {
+  tagName: string
+  startOffset: number
+  openEndOffset: number
+  openTag: string
+}
+
+function scanOpeningTags(html: string): OpenTagRegion[] {
+  const tags: OpenTagRegion[] = []
+  let index = 0
+  while (index < html.length) {
+    const open = html.indexOf("<", index)
+    if (open < 0) break
+    if (html.startsWith("<!--", open)) {
+      const close = html.indexOf("-->", open + 4)
+      index = close < 0 ? html.length : close + 3
+      continue
+    }
+    const close = html.indexOf(">", open + 1)
+    if (close < 0) break
+    const raw = html.slice(open, close + 1)
+    const tagName = normalizeName(/^<\s*([a-zA-Z0-9-]+)/.exec(raw)?.[1] || "")
+    if (!tagName || /^<\s*[!/]/.test(raw) || /^<\s*\//.test(raw)) {
+      index = close + 1
+      continue
+    }
+    tags.push({ tagName, startOffset: open, openEndOffset: close + 1, openTag: raw })
+    if (tagName === "script" || tagName === "style") {
+      const closeTag = new RegExp(`</\\s*${tagName}\\s*>`, "ig")
+      closeTag.lastIndex = close + 1
+      const match = closeTag.exec(html)
+      index = match ? match.index + match[0].length : close + 1
+    } else {
+      index = close + 1
+    }
+  }
+  return tags
+}
+
+function attrValue(openTag: string, name: string): string | undefined {
+  const escaped = escapeRegExp(name)
+  const match = new RegExp(`\\s${escaped}=("([^"]*)"|'([^']*)')`, "i").exec(openTag)
+  return match ? match[2] ?? match[3] : undefined
+}
+
+function isSafeBoxTarget(openTag: string): boolean {
+  const tagName = normalizeName(/^<\s*([a-zA-Z0-9-]+)/.exec(openTag)?.[1] || "")
+  const className = attrValue(openTag, "class") || ""
+  const classes = className.split(/\s+/).map((item) => item.trim().toLowerCase()).filter(Boolean)
+  if (tagName === "div" && classes.length === 0) return false
+  if (/\s(?:data-chart|data-echarts|_echarts_instance_)\b/i.test(openTag)) return false
+  if (classes.some((name) => name === "slide" || name === "slide-canvas" || name === "deck" || name === "page")) return false
+  if (classes.some((name) => name.startsWith("revela-") || name.startsWith("echarts-") || name === "echart-container" || name === "echart-panel")) return false
+  if (classes.some((name) => /(^|-)echart($|-)/.test(name) || name === "chart-container" || name === "chart-panel")) return false
+  return true
+}
+
+function normalizeName(value: string | undefined): string {
+  return (value || "").trim().toLowerCase()
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}

package/package.json

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