feat(mdviewer): simplify mode controls (Option D+)

Hide Phoenix play button and mode dropdown for MD files — md iframe
handles its own Edit/Reader toggle. Add cursor sync toggle (link-2 /
link-2-off icons) in md toolbar. Remove _syncMdviewrPreviewMode
complexity. Preserve edit mode across reload.

Author: abose

src-mdviewer/src/bridge.js

@@ -13,7 +13,7 @@ let _syncId = 0;
 let _lastReceivedSyncId = -1;
 let _suppressContentChange = false;
 let _baseURL = "";
-let _pendingReloadScroll = null; // { filePath, scrollPos, editMode } for scroll restore after reload
+let _pendingReloadScroll = null; // { filePath, scrollSourceLine } for scroll restore after reload
 
 /**
  * Check if a URL is absolute (not relative to the document).
@@ -175,6 +175,7 @@ export function initBridge() {
 
     // Detect source line from data-source-line attributes for scroll sync.
     // In read mode, also refocus CM5 unless the user has a text selection.
+    // Disabled in preview mode (no cursor sync).
     document.addEventListener("click", (e) => {
         const sourceLine = _getSourceLineFromElement(e.target);
         if (getState().editMode) {
@@ -222,6 +223,11 @@ export function initBridge() {
         sendToParent("mdviewrRequestEditMode", {});
     });
 
+    // Cursor sync toggle
+    on("toggle:cursorSync", ({ enabled }) => {
+        sendToParent("mdviewrCursorSyncToggle", { enabled });
+    });
+
     // Notify parent that iframe is ready
     sendToParent("mdviewrReady", {});
 }
@@ -359,12 +365,13 @@ function handleSwitchFile(data) {
         docCache.createEntry(filePath, markdown, parseResult);
         docCache.switchTo(filePath);
 
-        // Restore scroll position from reload if applicable
+        // Restore scroll position and edit mode from reload if applicable
         if (_pendingReloadScroll && _pendingReloadScroll.filePath === filePath) {
             const entry = docCache.getEntry(filePath);
             if (entry) {
                 entry._scrollSourceLine = _pendingReloadScroll.scrollSourceLine;
             }
+            const restoreEditMode = _pendingReloadScroll.editMode;
             _pendingReloadScroll = null;
 
             setState({
@@ -385,6 +392,10 @@ function handleSwitchFile(data) {
                     }
                 });
             }
+
+            if (restoreEditMode) {
+                setState({ editMode: true });
+            }
         } else {
             setState({
                 currentContent: markdown,
@@ -442,11 +453,12 @@ function handleReloadFile(data) {
         const activeEntry = docCache.getEntry(filePath);
         if (activeEntry) {
             const scrollSourceLine = activeEntry._scrollSourceLine;
-            if (getState().editMode) {
+            const wasEditMode = getState().editMode;
+            if (wasEditMode) {
                 setState({ editMode: false });
             }
             docCache.removeEntry(filePath);
-            _pendingReloadScroll = { filePath, scrollSourceLine };
+            _pendingReloadScroll = { filePath, scrollSourceLine, editMode: wasEditMode };
         }
     } else {
         docCache.removeEntry(filePath);
@@ -471,6 +483,7 @@ function handleSetEditMode(data) {
     setState({ editMode });
 }
 
+
 function handleSetLocale(data) {
     const { locale } = data;
     if (locale) {

src-mdviewer/src/components/embedded-toolbar.js

@@ -27,7 +27,9 @@ import {
     ChevronDown,
     Type,
     MoreHorizontal,
-    BookOpen
+    BookOpen,
+    Link2,
+    Link2Off
 } from "lucide";
 import { on, emit } from "../core/events.js";
 import { getState, setState } from "../core/state.js";
@@ -43,7 +45,7 @@ const THRESHOLD_LISTS = 520;   // then lists
 const THRESHOLD_TEXT = 420;    // finally text formatting
 
 const allIcons = { Bold, Italic, Strikethrough, Underline, Code, Link, List, ListOrdered,
-    ListChecks, Quote, Minus, Table, FileCode, ChevronDown, Type, MoreHorizontal, Pencil, BookOpen };
+    ListChecks, Quote, Minus, Table, FileCode, ChevronDown, Type, MoreHorizontal, Pencil, BookOpen, Link2, Link2Off };
 
 export function initEmbeddedToolbar() {
     toolbar = document.getElementById("toolbar");
@@ -76,13 +78,19 @@ function render() {
 function renderReadMode() {
     toolbar.innerHTML = `<div class="embedded-toolbar">
         <div class="toolbar-spacer"></div>
+        <button class="toolbar-btn cursor-sync-btn active" id="emb-cursor-sync" data-tooltip="${t("toolbar.cursor_sync") || "Cursor sync"}" aria-pressed="true">
+            <i data-lucide="link-2" class="sync-on-icon"></i>
+            <i data-lucide="link-2-off" class="sync-off-icon" style="display:none"></i>
+        </button>
         <button class="edit-toggle-btn" id="emb-edit-btn" title="${t("toolbar.switch_to_edit") || "Switch to edit mode"}">
             <i data-lucide="pencil"></i>
             <span>${t("toolbar.edit") || "Edit"}</span>
         </button>
     </div>`;
 
-    createIcons({ icons: { Pencil }, attrs: { class: "" } });
+    createIcons({ icons: { Pencil, Link2, Link2Off }, attrs: { class: "" } });
+
+    wireCursorSyncButton();
 
     const editBtn = document.getElementById("emb-edit-btn");
     if (editBtn) {
@@ -166,6 +174,10 @@ function renderEditMode(level) {
     toolbar.innerHTML = `<div class="embedded-toolbar">
         ${formatRow}
         <div class="toolbar-spacer"></div>
+        <button class="toolbar-btn cursor-sync-btn active" id="emb-cursor-sync" data-tooltip="${t("toolbar.cursor_sync") || "Cursor sync"}" aria-pressed="true">
+            <i data-lucide="link-2" class="sync-on-icon"></i>
+            <i data-lucide="link-2-off" class="sync-off-icon" style="display:none"></i>
+        </button>
         <button class="done-btn" id="emb-done-btn" title="${t("toolbar.switch_to_reader") || "Switch to reader mode"}">
             <i data-lucide="book-open"></i>
             <span>${t("toolbar.reader") || "Reader"}</span>
@@ -179,6 +191,7 @@ function renderEditMode(level) {
     if (level > 0) {
         wireDropdowns();
     }
+    wireCursorSyncButton();
     wireDoneButton();
 }
 
@@ -251,6 +264,21 @@ function closeAllDropdowns() {
     }
 }
 
+function wireCursorSyncButton() {
+    const syncBtn = document.getElementById("emb-cursor-sync");
+    if (syncBtn) {
+        syncBtn.addEventListener("click", () => {
+            const isActive = syncBtn.classList.toggle("active");
+            syncBtn.setAttribute("aria-pressed", String(isActive));
+            const onIcon = syncBtn.querySelector(".sync-on-icon");
+            const offIcon = syncBtn.querySelector(".sync-off-icon");
+            if (onIcon) onIcon.style.display = isActive ? "" : "none";
+            if (offIcon) offIcon.style.display = isActive ? "none" : "";
+            emit("toggle:cursorSync", { enabled: isActive });
+        });
+    }
+}
+
 function wireDoneButton() {
     const doneBtn = document.getElementById("emb-done-btn");
     if (doneBtn) {

src-mdviewer/src/locales/en.json

@@ -17,7 +17,8 @@
     "more": "More",
     "reader": "Reader",
     "switch_to_reader": "Switch to reader mode",
-    "switch_to_edit": "Switch to edit mode"
+    "switch_to_edit": "Switch to edit mode",
+    "cursor_sync": "Toggle cursor sync"
   },
   "sidebar": {
     "toc": "Table of Contents",

src-mdviewer/src/styles/app.css

@@ -100,6 +100,12 @@ html, body {
   background: var(--color-accent-subtle);
 }
 
+.cursor-sync-btn,
+.cursor-sync-btn.active {
+  color: var(--color-text-secondary);
+  background: transparent;
+}
+
 .toolbar-btn svg {
   width: 14px;
   height: 14px;

src/extensionsIntegrated/Phoenix-live-preview/MarkdownSync.js

@@ -45,6 +45,7 @@ define(function (require, exports, module) {
     let _cursorHandler = null;
     let _onEditModeRequest = null;
     let _onIframeReadyCallback = null;
+    let _cursorSyncEnabled = true;
 
     const DEBOUNCE_TO_IFRAME_MS = 150;
     const SCROLL_SYNC_DEBOUNCE_MS = 100;
@@ -110,19 +111,24 @@ define(function (require, exports, module) {
                     _onEditModeRequest();
                 }
                 break;
+            case "mdviewrCursorSyncToggle":
+                _cursorSyncEnabled = !!data.enabled;
+                break;
             case "embeddedIframeFocusEditor":
                 if (data.sourceLine != null) {
                     _scrollCMToLine(data.sourceLine);
                 }
                 utils.focusActiveEditorIfFocusInLivePreview();
                 break;
             case "mdviewrScrollSync":
-                if (data.sourceLine != null) {
+                if (_cursorSyncEnabled && data.sourceLine != null) {
                     _scrollCMToLine(data.sourceLine);
                 }
                 break;
             case "mdviewrSelectionSync":
-                _handleSelectionFromIframe(data);
+                if (_cursorSyncEnabled) {
+                    _handleSelectionFromIframe(data);
+                }
                 break;
             case "embeddedIframeHrefClick":
                 _handleHrefClick(data);
@@ -157,7 +163,7 @@ define(function (require, exports, module) {
 
         // Listen for cursor activity in CM5 for scroll sync and selection sync (CM5 → iframe)
         _cursorHandler = function () {
-            if (_syncingFromIframe || !_iframeReady) {
+            if (_syncingFromIframe || !_iframeReady || !_cursorSyncEnabled) {
                 return;
             }
             clearTimeout(_scrollSyncTimer);
@@ -651,11 +657,20 @@ define(function (require, exports, module) {
         _onIframeReadyCallback = handler;
     }
 
+    /**
+     * Enable or disable cursor/scroll sync between CM and mdviewer.
+     * Content sync still works regardless.
+     */
+    function setCursorSyncEnabled(enabled) {
+        _cursorSyncEnabled = enabled;
+    }
+
     exports.activate = activate;
     exports.deactivate = deactivate;
     exports.isActive = isActive;
     exports.reloadCurrentFile = reloadCurrentFile;
     exports.setEditModeRequestHandler = setEditModeRequestHandler;
     exports.setEditMode = setEditMode;
     exports.setIframeReadyHandler = setIframeReadyHandler;
+    exports.setCursorSyncEnabled = setCursorSyncEnabled;
 });

src/extensionsIntegrated/Phoenix-live-preview/main.js

@@ -324,9 +324,19 @@ define(function (require, exports, module) {
     }
 
     /**
-     * update the mode button text in the live preview toolbar UI based on the current mode
-     * @param {String} mode - The current mode ("preview", "highlight", or "edit")
+     * Hide the play button and mode dropdown when mdviewer is active,
+     * since MD files have their own Edit/Reader toggle in the iframe toolbar.
+     * Does not hide in custom server mode (handled by _isMdviewrActive being false).
      */
+    function _updateLPControlsForMdviewer() {
+        if ($previewBtn) {
+            $previewBtn.toggle(!_isMdviewrActive);
+        }
+        if ($modeBtn) {
+            $modeBtn.toggle(!_isMdviewrActive);
+        }
+    }
+
     function _updateModeButton(mode) {
         if ($modeBtn) {
             if (mode === "highlight") {
@@ -910,8 +920,8 @@ define(function (require, exports, module) {
 
         _isMdviewrActive = true;
         MarkdownSync.activate(currentDoc, $iframe, baseURL);
-        // Set initial edit mode based on entitlement (for reuse case where iframe is already ready)
-        MarkdownSync.setEditMode(isProEditUser);
+        // Sync preview mode and edit mode for reuse case where iframe is already ready
+        _updateLPControlsForMdviewer();
 
         Metrics.countEvent(Metrics.EVENT_TYPE.LIVE_PREVIEW, "render", "mdviewr");
     }
@@ -945,6 +955,7 @@ define(function (require, exports, module) {
             if ($mdviewrIframe) {
                 $mdviewrIframe.hide();
             }
+            _updateLPControlsForMdviewer();
         }
         let newSrc = encodeURI(previewDetails.URL);
         if($iframe.attr('src') === newSrc && !force){
@@ -1543,7 +1554,7 @@ define(function (require, exports, module) {
 
         // When iframe first loads, send initial edit mode based on entitlement
         MarkdownSync.setIframeReadyHandler(function () {
-            MarkdownSync.setEditMode(isProEditUser);
+            _updateLPControlsForMdviewer();
         });
 
         _projectOpened();