pi-studio 0.9.52 → 0.9.54

package/client/studio-client.js

@@ -155,6 +155,7 @@
       const shortcutsCloseBtn = document.getElementById("shortcutsCloseBtn");
       const leftFocusBtn = document.getElementById("leftFocusBtn");
       const rightFocusBtn = document.getElementById("rightFocusBtn");
+      const watchedOpenEditableBtn = document.getElementById("watchedOpenEditableBtn");
       const reviewNotesBtn = document.getElementById("reviewNotesBtn");
       const outlineBtn = document.getElementById("outlineBtn");
       const scratchpadBtn = document.getElementById("scratchpadBtn");
@@ -192,6 +193,7 @@
         ? "editor-only"
         : "full";
       const isEditorOnlyMode = studioMode === "editor-only";
+      const isWatchedFilePreview = Boolean(document.body && document.body.dataset && document.body.dataset.watchedFilePreview === "1");
       const isSshStudioSession = Boolean(document.body && document.body.dataset && document.body.dataset.sshSession === "1");
       const EDITOR_ONLY_RIGHT_VIEW_ALLOWED = new Set(["editor-preview", "editor-quarto-preview", "files", "changes", "repl", "side-questions"]);
       const RIGHT_VIEW_LABELS = {
@@ -242,6 +244,7 @@
         || typeof previewResourceHelpers.buildStudioPdfVersionSignature !== "function"
         || typeof previewResourceHelpers.createStudioPdfVersionObservationState !== "function"
         || typeof previewResourceHelpers.hydrateStudioPreviewLocalImages !== "function"
+        || typeof previewResourceHelpers.hydrateStudioPreviewLocalPdfEmbeds !== "function"
         || typeof previewResourceHelpers.observeStudioPdfVersion !== "function"
       ) {
         throw new Error("Studio preview resource helpers failed to load.");
@@ -281,6 +284,16 @@
       };
       const initialResourceDir = initialQueryParams.get("resourceDir")
         || ((document.body && document.body.dataset && document.body.dataset.initialResourceDir) || "");
+      const initialDiskRevision = (document.body && document.body.dataset && document.body.dataset.initialDiskRevision) || "";
+      let watchedFilePreviewState = {
+        enabled: isWatchedFilePreview,
+        path: isWatchedFilePreview && initialSourceState.path ? initialSourceState.path : "",
+        diskRevision: isWatchedFilePreview ? initialDiskRevision : "",
+        generation: 0,
+        lastError: "",
+        renderError: "",
+      };
+      const watchedFilePreviewReadingPositions = { source: null, response: null };
 
       let ws = null;
       let wsState = "Connecting";
@@ -332,6 +345,7 @@
       let studioDecisionMessageEl = null;
       let studioDecisionInputEl = null;
       let studioDecisionCancelBtn = null;
+      let studioDecisionTertiaryBtn = null;
       let studioDecisionSecondaryBtn = null;
       let studioDecisionConfirmBtn = null;
       let studioDecisionState = null;
@@ -339,6 +353,7 @@
       let pendingRequestId = null;
       let pendingKind = null;
       let stickyStudioKind = null;
+      const pendingSaveOperations = new Map();
       const pendingCompanionLaunches = new Map();
       const activeStudioTabLaunches = new Set();
       let sourceOriginSummaryEl = null;
@@ -368,6 +383,7 @@
 
       function normalizeRightViewValue(nextView) {
         const normalized = canonicalRightViewValue(nextView);
+        if (isWatchedFilePreview && normalized !== "editor-preview") return "editor-preview";
         if (normalized === "editor-quarto-preview" && !isCurrentStudioQuartoDocument()) {
           return "editor-preview";
         }
@@ -379,6 +395,7 @@
 
       function isRightViewAvailableInCurrentMode(view) {
         const normalized = canonicalRightViewValue(view);
+        if (isWatchedFilePreview) return normalized === "editor-preview";
         if (normalized === "editor-quarto-preview" && !isCurrentStudioQuartoDocument()) return false;
         return !isEditorOnlyMode || EDITOR_ONLY_RIGHT_VIEW_ALLOWED.has(normalized);
       }
@@ -398,12 +415,17 @@
         Array.from(rightViewSelect.options).forEach((option) => {
           if (!option) return;
           const isQuartoOption = option.value === "editor-quarto-preview";
+          if (isWatchedFilePreview && option.value === "editor-preview") option.textContent = "Watched preview";
           if (isQuartoOption) option.hidden = !quartoRelevant;
-          option.disabled = (isEditorOnlyMode && !EDITOR_ONLY_RIGHT_VIEW_ALLOWED.has(option.value)) || (isQuartoOption && !quartoRelevant);
+          option.disabled = (isWatchedFilePreview && option.value !== "editor-preview")
+            || (isEditorOnlyMode && !EDITOR_ONLY_RIGHT_VIEW_ALLOWED.has(option.value))
+            || (isQuartoOption && !quartoRelevant);
         });
-        rightViewSelect.title = isEditorOnlyMode
-          ? "Editor-only views: Editor Preview, contextual Quarto Preview for .qmd/.md/.markdown files, Changes, Files, REPL, or Side questions. F7 cycles; Cmd/Ctrl+Alt+3/5/6/7/8 switch directly to numbered right-pane views, and Cmd/Ctrl+Alt+Q opens Side questions."
-          : "Right pane view mode. F7 cycles, including contextual Quarto Preview for file-backed .qmd, .md, and .markdown documents; Cmd/Ctrl+Alt+1–8 switches directly between the numbered views. Cmd/Ctrl+Alt+P/E/W keep their mnemonic Preview/Editor Preview/Working shortcuts.";
+        rightViewSelect.title = isWatchedFilePreview
+          ? "Read-only watched preview follows this file on disk."
+          : (isEditorOnlyMode
+          ? "Editor-only views: Editor Preview, contextual Quarto Preview for .qmd/.md/.markdown files, Changes, Files, REPL, or Side questions. F7 cycles; Cmd/Ctrl+Alt+3/5/6/7/8 switch directly to numbered right-pane views, and Cmd/Ctrl+Alt+F/Q open Files/Side questions."
+          : "Right pane view mode. F7 cycles, including contextual Quarto Preview for file-backed .qmd, .md, and .markdown documents; Cmd/Ctrl+Alt+1–8 switches directly between the numbered views. Cmd/Ctrl+Alt+P/E/W/F/Q keep mnemonic shortcuts for Preview, Editor Preview, Working, Files, and Side questions.");
       }
 
       function getInitialRightView(source) {
@@ -478,6 +500,7 @@
       let sideQuestionAvailablePiTools = [];
       let sideQuestionPreviewRenderNonce = 0;
       let sideQuestionContextRefreshHandle = null;
+      let sideQuestionContextGrantPending = false;
       let sideQuestionMarkdownExportRequest = null;
       const sideQuestionMarkdownRenderCache = new Map();
       let sideQuestionUi = {
@@ -2162,6 +2185,7 @@
         actionRequestId: null,
       };
       let fileBackedBaselineText = null;
+      let fileBackedDiskRevision = null;
       let activePane = initialPaneFocusTarget === "right" ? "right" : "left";
       let paneFocusTarget = initialPaneFocusTarget;
       let paneSplitPercent = 50;
@@ -2293,6 +2317,9 @@
         relativeDir: "",
         parentDir: null,
         entries: [],
+        exactFiles: [],
+        locations: [],
+        grantRequiredPath: "",
         omitted: 0,
         omittedIgnored: 0,
         sort: fileBrowserSortMode,
@@ -2918,6 +2945,7 @@
           rightTitleGroupEl.appendChild(rightViewSelect);
           rightIdentityEl.appendChild(rightTitleGroupEl);
           const rightToolsEl = makeStudioUiRefreshElement("div", "studio-refresh-pane-tools");
+          if (watchedOpenEditableBtn && isWatchedFilePreview) rightToolsEl.appendChild(watchedOpenEditableBtn);
           if (exportPreviewControlsEl) {
             rightToolsEl.appendChild(exportPreviewControlsEl);
           } else if (exportPdfBtn) {
@@ -3841,7 +3869,7 @@
       }
 
       function getStudioDecisionFocusableElements() {
-        return [studioDecisionInputEl, studioDecisionCancelBtn, studioDecisionSecondaryBtn, studioDecisionConfirmBtn]
+        return [studioDecisionInputEl, studioDecisionCancelBtn, studioDecisionTertiaryBtn, studioDecisionSecondaryBtn, studioDecisionConfirmBtn]
           .filter((element) => element && !element.hidden && !element.disabled);
       }
 
@@ -3889,13 +3917,41 @@
         cancelBtn.addEventListener("click", () => finishStudioDecision(null));
         actions.appendChild(cancelBtn);
 
+        const tertiaryBtn = document.createElement("button");
+        tertiaryBtn.type = "button";
+        tertiaryBtn.className = "studio-decision-tertiary";
+        tertiaryBtn.hidden = true;
+        tertiaryBtn.addEventListener("click", () => {
+          const state = studioDecisionState;
+          const handler = state && state.onTertiary;
+          if (typeof handler !== "function") {
+            if (state && state.hasTertiaryValue) finishStudioDecision(state.tertiaryValue);
+            return;
+          }
+          try {
+            const result = handler();
+            if (result && typeof result.catch === "function") {
+              result.catch((error) => {
+                setStatus("Action failed: " + (error && error.message ? error.message : String(error || "unknown error")), "warning");
+              });
+            }
+          } catch (error) {
+            setStatus("Action failed: " + (error && error.message ? error.message : String(error || "unknown error")), "warning");
+          }
+        });
+        actions.appendChild(tertiaryBtn);
+
         const secondaryBtn = document.createElement("button");
         secondaryBtn.type = "button";
         secondaryBtn.className = "studio-decision-secondary";
         secondaryBtn.hidden = true;
         secondaryBtn.addEventListener("click", () => {
-          const handler = studioDecisionState && studioDecisionState.onSecondary;
-          if (typeof handler !== "function") return;
+          const state = studioDecisionState;
+          const handler = state && state.onSecondary;
+          if (typeof handler !== "function") {
+            if (state && state.hasSecondaryValue) finishStudioDecision(state.secondaryValue);
+            return;
+          }
           try {
             const result = handler();
             if (result && typeof result.catch === "function") {
@@ -3955,6 +4011,7 @@
         studioDecisionMessageEl = message;
         studioDecisionInputEl = input;
         studioDecisionCancelBtn = cancelBtn;
+        studioDecisionTertiaryBtn = tertiaryBtn;
         studioDecisionSecondaryBtn = secondaryBtn;
         studioDecisionConfirmBtn = confirmBtn;
         return overlay;
@@ -3967,6 +4024,7 @@
         if (studioDecisionState) finishStudioDecision(null, false);
         const returnFocusEl = document.activeElement instanceof HTMLElement ? document.activeElement : null;
 
+        const tertiaryLabel = String(settings.tertiaryLabel || "").trim();
         const secondaryLabel = String(settings.secondaryLabel || "").trim();
         studioDecisionTitleEl.textContent = String(settings.title || (mode === "prompt" ? "Enter a value" : "Confirm action"));
         studioDecisionMessageEl.textContent = String(settings.message || "");
@@ -3975,9 +4033,13 @@
         studioDecisionInputEl.placeholder = mode === "prompt" ? String(settings.placeholder || "") : "";
         studioDecisionInputEl.setAttribute("aria-label", String(settings.inputLabel || "Value"));
         studioDecisionCancelBtn.textContent = String(settings.cancelLabel || "Cancel");
+        studioDecisionTertiaryBtn.hidden = !tertiaryLabel;
+        studioDecisionTertiaryBtn.disabled = settings.tertiaryDisabled === true;
+        studioDecisionTertiaryBtn.textContent = tertiaryLabel;
         studioDecisionSecondaryBtn.hidden = !secondaryLabel;
         studioDecisionSecondaryBtn.disabled = settings.secondaryDisabled === true;
         studioDecisionSecondaryBtn.textContent = secondaryLabel;
+        studioDecisionConfirmBtn.disabled = settings.confirmDisabled === true;
         studioDecisionConfirmBtn.textContent = String(settings.confirmLabel || (mode === "prompt" ? "Continue" : "Confirm"));
         studioDecisionConfirmBtn.classList.toggle("is-destructive", settings.destructive === true);
         studioDecisionDialogEl.classList.toggle("is-destructive", settings.destructive === true);
@@ -3989,7 +4051,12 @@
             mode,
             resolve,
             returnFocusEl,
+            onTertiary: typeof settings.onTertiary === "function" ? settings.onTertiary : null,
+            hasTertiaryValue: Object.prototype.hasOwnProperty.call(settings, "tertiaryValue"),
+            tertiaryValue: settings.tertiaryValue,
             onSecondary: typeof settings.onSecondary === "function" ? settings.onSecondary : null,
+            hasSecondaryValue: Object.prototype.hasOwnProperty.call(settings, "secondaryValue"),
+            secondaryValue: settings.secondaryValue,
           };
           studioDecisionState = decisionState;
           const schedule = typeof window.requestAnimationFrame === "function"
@@ -4048,12 +4115,20 @@
         }
       });
 
-      function markFileBackedBaseline(text) {
+      function normalizeStudioDiskRevision(value) {
+        const revision = typeof value === "string" ? value.trim().toLowerCase() : "";
+        return /^sha256:[a-f0-9]{64}$/.test(revision) ? revision : null;
+      }
+
+      function markFileBackedBaseline(text, diskRevision) {
         fileBackedBaselineText = String(text || "");
+        fileBackedDiskRevision = normalizeStudioDiskRevision(diskRevision);
+        scheduleWorkspacePersistence();
       }
 
       function clearFileBackedBaseline() {
         fileBackedBaselineText = null;
+        fileBackedDiskRevision = null;
       }
 
       function hasRefreshableFilePath() {
@@ -4068,13 +4143,17 @@
 
       function updateSourceBadge() {
         const label = sourceState && sourceState.label ? sourceState.label : "blank";
-        const originText = (studioUiRefreshEnabled ? "Origin: " : "Editor origin: ") + label + (hasRefreshableFilePath() ? " · file" : "");
+        const originText = isWatchedFilePreview
+          ? ("Watching: " + label + " · read-only" + (watchedFilePreviewState.lastError || watchedFilePreviewState.renderError ? " · last good preview" : ""))
+          : ((studioUiRefreshEnabled ? "Origin: " : "Editor origin: ") + label + (hasRefreshableFilePath() ? " · file" : ""));
         const descriptor = getCurrentStudioDocumentDescriptor();
         if (sourceBadgeEl) {
           sourceBadgeEl.textContent = originText;
-          sourceBadgeEl.title = descriptor.fileBacked
+          sourceBadgeEl.title = isWatchedFilePreview
+            ? ("Read-only watched file: " + (descriptor.label || label) + "\nStudio follows settled disk changes and keeps the last good rendered preview through temporary failures.")
+            : (descriptor.fileBacked
             ? ("Editor origin: " + label + "\nClick to reset origin and detach the current editor text into a new draft. The file on disk will not be changed.")
-            : ("Editor origin: " + label + "\nClick to reset origin and start a new independent draft while keeping the current text and local notes.");
+            : ("Editor origin: " + label + "\nClick to reset origin and start a new independent draft while keeping the current text and local notes."));
         }
         if (sourceOriginSummaryEl) {
           sourceOriginSummaryEl.textContent = originText;
@@ -4533,10 +4612,14 @@
       }
 
       function triggerEditorSaveShortcut() {
-        if (saveOverBtn && !saveOverBtn.disabled && !saveOverBtn.hidden) {
+        if (hasRefreshableFilePath() && saveOverBtn && !saveOverBtn.disabled && !saveOverBtn.hidden) {
           saveOverBtn.click();
           return true;
         }
+        return triggerEditorSaveAsShortcut();
+      }
+
+      function triggerEditorSaveAsShortcut() {
         if (saveAsBtn && !saveAsBtn.disabled && !saveAsBtn.hidden) {
           saveAsBtn.click();
           return true;
@@ -4821,6 +4904,16 @@
           return;
         }
 
+        const isFilesShortcut = (key.toLowerCase() === "f" || code === "KeyF")
+          && (event.metaKey || event.ctrlKey)
+          && event.altKey
+          && !event.shiftKey;
+        if (isFilesShortcut) {
+          event.preventDefault();
+          switchRightPaneToView("files");
+          return;
+        }
+
         const isSideQuestionsShortcut = (key.toLowerCase() === "q" || code === "KeyQ")
           && (event.metaKey || event.ctrlKey)
           && event.altKey
@@ -4869,6 +4962,22 @@
           return;
         }
 
+        const isSaveAsShortcut =
+          key.toLowerCase() === "s"
+          && (event.metaKey || event.ctrlKey)
+          && !event.altKey
+          && event.shiftKey;
+
+        if (isSaveAsShortcut) {
+          event.preventDefault();
+          if (isWatchedFilePreview) {
+            setStatus("This preview is read-only. Open a file tab to edit or save a copy.", "warning");
+            return;
+          }
+          triggerEditorSaveAsShortcut();
+          return;
+        }
+
         const isSaveShortcut =
           key.toLowerCase() === "s"
           && (event.metaKey || event.ctrlKey)
@@ -4877,6 +4986,10 @@
 
         if (isSaveShortcut) {
           event.preventDefault();
+          if (isWatchedFilePreview) {
+            setStatus("This preview follows disk and cannot save. Open a file tab to edit safely.", "warning");
+            return;
+          }
           triggerEditorSaveShortcut();
           return;
         }
@@ -5623,6 +5736,8 @@
         clearPreviewJumpHighlight(targetEl);
         finishPreviewRender(targetEl);
         targetEl.innerHTML = html;
+        clearWatchedPreviewRenderError();
+        scheduleWatchedPreviewReadingPositionRestore(targetEl, text);
         if (pane === "response") {
           applyPendingResponseScrollReset();
           scheduleResponsePaneRepaintNudge();
@@ -6041,7 +6156,8 @@
           + "    const images = Array.prototype.slice.call(document.querySelectorAll('img[src]'));\n"
           + "    images.forEach((image) => {\n"
           + "      if (!image || !image.getAttribute) return;\n"
-          + "      if (image.getAttribute('data-pi-studio-html-resource-resolved') === 'true') return;\n"
+          + "      const resourceState = image.getAttribute('data-pi-studio-html-resource-resolved') || '';\n"
+          + "      if (resourceState === 'true' || resourceState === 'blocked' || resourceState === 'failed') return;\n"
           + "      const raw = String(image.getAttribute('src') || '').trim();\n"
           + "      if (!shouldResolveHtmlPreviewResourceUrl(raw)) return;\n"
           + "      let resourceId = image.getAttribute('data-pi-studio-html-resource-id') || '';\n"
@@ -6073,6 +6189,7 @@
           + "        image.setAttribute('data-pi-studio-html-resource-resolved', 'true');\n"
           + "      } else if (typeof result.error === 'string' && result.error) {\n"
           + "        image.setAttribute('title', result.error);\n"
+          + "        image.setAttribute('data-pi-studio-html-resource-resolved', result.blocked === true ? 'blocked' : 'failed');\n"
           + "      }\n"
           + "      htmlResourcePlaceholders.delete(resourceId);\n"
           + "    });\n"
@@ -6523,18 +6640,28 @@
           const message = payload && typeof payload.error === "string"
             ? payload.error
             : (timeoutLabel || "Local preview resource load") + " failed with HTTP " + response.status + ".";
-          throw new Error(message);
+          const requestError = new Error(message);
+          requestError.studioPayload = payload && typeof payload === "object" ? payload : null;
+          requestError.studioStatus = response.status;
+          throw requestError;
         }
         return payload.dataUrl;
       }
 
       function postHtmlArtifactResourceResults(record, results) {
         if (!record || !record.iframe || !record.iframe.isConnected || !record.iframe.contentWindow) return;
+        const publicResults = Array.isArray(results) ? results.map((result) => ({
+          resourceId: result && result.resourceId ? result.resourceId : "",
+          ok: Boolean(result && result.ok === true),
+          dataUrl: result && typeof result.dataUrl === "string" ? result.dataUrl : undefined,
+          error: result && typeof result.error === "string" ? result.error : undefined,
+          blocked: Boolean(result && result.blocked === true),
+        })) : [];
         try {
           record.iframe.contentWindow.postMessage({
             type: "pi-studio-html-artifact-resources-resolved",
             id: record.id || "",
-            results: Array.isArray(results) ? results : [],
+            results: publicResults,
           }, "*");
         } catch {
           // Ignore iframe postMessage failures.
@@ -6552,14 +6679,58 @@
           );
           return { resourceId, ok: true, dataUrl };
         } catch (error) {
-          return { resourceId, ok: false, error: error && error.message ? error.message : String(error || "HTML preview resource load failed.") };
+          const grantRequest = getStudioResourceGrantRequest(error);
+          return {
+            resourceId,
+            ok: false,
+            error: error && error.message ? error.message : String(error || "HTML preview resource load failed."),
+            blocked: Boolean(grantRequest),
+            grantRequest,
+            sourceUrl: item && item.url ? String(item.url) : "",
+          };
         }
       }
 
+      function renderHtmlArtifactBlockedResources(record) {
+        if (!record || !record.shell) return;
+        const existing = record.shell.querySelector(".studio-html-artifact-blocked-media");
+        if (existing) existing.remove();
+        const blocked = record.blockedResources instanceof Map ? Array.from(record.blockedResources.values()) : [];
+        if (!blocked.length) return;
+        const container = document.createElement("div");
+        container.className = "studio-html-artifact-blocked-media";
+        blocked.forEach((entry) => {
+          const notice = createStudioBlockedMediaNoticeForRequest(entry.grantRequest, "image", entry.sourceUrl);
+          if (notice) container.appendChild(notice);
+        });
+        if (!container.childNodes.length) return;
+        const frame = record.iframe && record.iframe.parentNode === record.shell ? record.iframe : null;
+        record.shell.insertBefore(container, frame);
+      }
+
+      function syncHtmlArtifactBlockedResources(record, results) {
+        if (!record) return;
+        if (!(record.blockedResources instanceof Map)) record.blockedResources = new Map();
+        (Array.isArray(results) ? results : []).forEach((result) => {
+          const resourceId = result && result.resourceId ? String(result.resourceId) : "";
+          if (!resourceId) return;
+          if (result.blocked === true && result.grantRequest) {
+            record.blockedResources.set(resourceId, {
+              grantRequest: result.grantRequest,
+              sourceUrl: result.sourceUrl || "local image",
+            });
+          } else {
+            record.blockedResources.delete(resourceId);
+          }
+        });
+        renderHtmlArtifactBlockedResources(record);
+      }
+
       async function resolveHtmlArtifactResources(record, items) {
         if (!record || !Array.isArray(items) || items.length === 0) return;
         if (record.detail) record.detail.textContent = "HTML preview · loading local images";
         const results = await Promise.all(items.map((item) => fetchHtmlArtifactResource(record, item)));
+        syncHtmlArtifactBlockedResources(record, results);
         postHtmlArtifactResourceResults(record, results);
         setHtmlArtifactDetailText(record, "HTML preview");
       }
@@ -6620,12 +6791,14 @@
         const action = typeof data.action === "string" ? data.action : "open";
         if (action === "contextmenu") {
           const point = getHtmlArtifactLocalLinkClientPoint(record, data);
-          showPreviewLinkMenu(null, point, context);
+          void showPreviewLinkMenu(null, point, context);
           return;
         }
         const kind = getPreviewLocalLinkKind(context.href);
         if (kind === "pdf") {
-          openPreviewPdfLink(context.href, context.title, context);
+          void openPreviewPdfLink(context.href, context.title, context).catch((error) => {
+            setStatus((error && error.message) ? error.message : String(error || "Could not open linked PDF."), "warning");
+          });
           return;
         }
         if (kind === "image") {
@@ -6635,9 +6808,8 @@
           return;
         }
         if (kind === "text" || kind === "office") {
-          void openPreviewDocumentInNewEditor(context.href, context).catch((error) => {
-            setStatus((error && error.message) ? error.message : String(error || "Could not open linked file."), "warning");
-          });
+          const point = getHtmlArtifactLocalLinkClientPoint(record, data);
+          void showPreviewLinkMenu(null, point, context);
           return;
         }
         setStatus("Right-click this local HTML preview link for file actions.", "warning");
@@ -7041,9 +7213,12 @@
           mathRenderItemCount: 0,
           resourceResolveBatchCount: 0,
           resourceResolveItemCount: 0,
+          blockedResources: new Map(),
         });
 
         targetEl.appendChild(shell);
+        clearWatchedPreviewRenderError();
+        scheduleWatchedPreviewReadingPositionRestore(targetEl, html);
 
         if (pane === "response") {
           applyPendingResponseScrollReset();
@@ -7927,6 +8102,13 @@
         const target = event && event.target;
         if (!(target instanceof Element)) return;
 
+        const blockedMediaButton = target.closest("button.studio-blocked-media-allow");
+        if (blockedMediaButton) {
+          consumeStudioPreviewMediaEvent(event);
+          void handleStudioBlockedMediaAllowButton(blockedMediaButton);
+          return;
+        }
+
         const imageEl = target.closest("img.studio-image-focus-target");
         if (imageEl) {
           consumeStudioPreviewMediaEvent(event);
@@ -8400,7 +8582,53 @@
         });
       }
 
-      function createStudioPdfCard(block, useEditorResourceContext) {
+      function createStudioPdfStatusCard(block, content) {
+        const options = block && block.options ? block.options : {};
+        const path = String(options.path || "").trim();
+        const title = String(options.title || path || "Embedded PDF").trim();
+        const caption = String(options.caption || "").trim();
+        const card = document.createElement("figure");
+        card.className = "studio-pdf-card studio-pdf-card-status";
+        const header = document.createElement("figcaption");
+        header.className = "studio-pdf-card-header";
+        const titleEl = document.createElement("div");
+        titleEl.className = "studio-pdf-card-title";
+        titleEl.textContent = title;
+        header.appendChild(titleEl);
+        card.appendChild(header);
+        if (caption) {
+          const captionEl = document.createElement("div");
+          captionEl.className = "studio-pdf-card-caption";
+          captionEl.textContent = caption;
+          card.appendChild(captionEl);
+        }
+        if (content instanceof Element) {
+          card.appendChild(content);
+        } else {
+          const errorEl = document.createElement("div");
+          errorEl.className = "studio-pdf-card-error";
+          errorEl.textContent = String(content || "PDF resource unavailable.");
+          card.appendChild(errorEl);
+        }
+        return card;
+      }
+
+      async function createStudioPdfCard(block, useEditorResourceContext) {
+        const options = block && block.options ? block.options : {};
+        const path = String(options.path || "").trim();
+        if (!path) return createAuthorizedStudioPdfCard(block, useEditorResourceContext);
+        const resourceQuery = buildStudioPdfResourceQuery(options, useEditorResourceContext);
+        try {
+          await fetchPreviewLocalLink("resolve", path, resourceQuery, { skipGrantPrompt: true });
+          return createAuthorizedStudioPdfCard(block, useEditorResourceContext);
+        } catch (error) {
+          const notice = createStudioBlockedMediaNotice(error, "pdf", path);
+          if (notice) return createStudioPdfStatusCard(block, notice);
+          return createStudioPdfStatusCard(block, error && error.message ? error.message : "PDF resource unavailable.");
+        }
+      }
+
+      function createAuthorizedStudioPdfCard(block, useEditorResourceContext) {
         const options = block && block.options ? block.options : {};
         const path = String(options.path || "").trim();
         const title = String(options.title || path || "Embedded PDF").trim();
@@ -8563,17 +8791,17 @@
         return card;
       }
 
-      function renderStudioPdfBlocksInElement(targetEl, blocks, useEditorResourceContext) {
+      async function renderStudioPdfBlocksInElement(targetEl, blocks, useEditorResourceContext) {
         if (!targetEl || !Array.isArray(blocks) || blocks.length === 0) return;
         const candidates = Array.from(targetEl.querySelectorAll("p, pre, div"));
-        blocks.forEach((block) => {
+        for (const block of blocks) {
           const placeholder = block && block.placeholder ? block.placeholder : "";
-          if (!placeholder) return;
+          if (!placeholder) continue;
           const match = candidates.find((el) => String(el.textContent || "").trim() === placeholder);
-          if (match && match.parentNode) {
-            match.replaceWith(createStudioPdfCard(block, useEditorResourceContext));
-          }
-        });
+          if (!match || !match.parentNode) continue;
+          const card = await createStudioPdfCard(block, useEditorResourceContext);
+          if (match.isConnected && match.parentNode) match.replaceWith(card);
+        }
       }
 
       function sanitizeRenderedHtml(html, markdown, options) {
@@ -9145,13 +9373,206 @@
         targetEl.appendChild(el);
       }
 
+      function createStudioBlockedMediaNotice(error, mediaKind, sourceLabel) {
+        return createStudioBlockedMediaNoticeForRequest(getStudioResourceGrantRequest(error), mediaKind, sourceLabel);
+      }
+
+      function createStudioBlockedMediaNoticeForRequest(grantRequest, mediaKind, sourceLabel) {
+        if (!grantRequest) return null;
+        const kind = mediaKind === "pdf" ? "PDF" : "image";
+        const notice = document.createElement("span");
+        notice.className = "studio-blocked-media studio-blocked-media-" + (mediaKind === "pdf" ? "pdf" : "image");
+        notice.setAttribute("role", "note");
+
+        const text = document.createElement("span");
+        text.className = "studio-blocked-media-text";
+        const title = document.createElement("strong");
+        title.textContent = "Local " + kind + " blocked";
+        const detail = document.createElement("span");
+        detail.textContent = "This media is outside the locations allowed for the current Studio session.";
+        const path = document.createElement("code");
+        path.textContent = grantRequest.path || String(sourceLabel || "local media");
+        path.title = "Path on the computer running Pi";
+        text.appendChild(title);
+        text.appendChild(detail);
+        text.appendChild(path);
+        notice.appendChild(text);
+
+        const allowButton = document.createElement("button");
+        allowButton.type = "button";
+        allowButton.className = "studio-blocked-media-allow";
+        allowButton.textContent = "Allow local " + kind + "…";
+        allowButton.title = "Choose whether to allow only this file or its containing folder for the current Studio session.";
+        allowButton.dataset.studioBlockedMediaPath = grantRequest.path;
+        allowButton.dataset.studioBlockedMediaDirectory = grantRequest.directoryPath;
+        allowButton.dataset.studioBlockedMediaLabel = grantRequest.label;
+        allowButton.dataset.studioBlockedMediaKind = mediaKind === "pdf" ? "pdf" : "image";
+        notice.appendChild(allowButton);
+        return notice;
+      }
+
+      function replaceStudioBlockedMediaElement(element, source, error, mediaKind) {
+        if (!element || !element.parentNode) return false;
+        const notice = createStudioBlockedMediaNotice(error, mediaKind, source);
+        if (!notice) return false;
+        element.replaceWith(notice);
+        return true;
+      }
+
+      function refreshStudioPassiveMediaAfterGrant() {
+        renderSourcePreview({ previewDelayMs: 0 });
+        if (rightView === "preview" || rightView === "editor-preview" || rightView === "side-questions") {
+          renderActiveResult();
+        }
+        if (isQuizOpen()) renderQuizOverlay({ preserveScroll: true });
+      }
+
+      async function handleStudioBlockedMediaAllowButton(button) {
+        if (!(button instanceof HTMLButtonElement) || button.dataset.studioBlockedMediaBusy === "1") return false;
+        const request = {
+          path: String(button.dataset.studioBlockedMediaPath || "").trim(),
+          directoryPath: String(button.dataset.studioBlockedMediaDirectory || "").trim(),
+          label: String(button.dataset.studioBlockedMediaLabel || "local media").trim() || "local media",
+        };
+        if (!request.path || !request.directoryPath) {
+          setStatus("Could not resolve this blocked media path.", "warning");
+          return false;
+        }
+        button.dataset.studioBlockedMediaBusy = "1";
+        button.disabled = true;
+        const baselineText = button.textContent;
+        button.textContent = "Choosing…";
+        try {
+          if (!(await requestStudioResourceGrant(request))) return false;
+          refreshStudioPassiveMediaAfterGrant();
+          return true;
+        } catch (error) {
+          setStatus("Could not allow local media: " + (error && error.message ? error.message : String(error || "unknown error")), "warning");
+          return false;
+        } finally {
+          if (button.isConnected) {
+            delete button.dataset.studioBlockedMediaBusy;
+            button.disabled = false;
+            button.textContent = baselineText;
+          }
+        }
+      }
+
       function hasMeaningfulPreviewContent(targetEl) {
         if (!targetEl || typeof targetEl.querySelector !== "function") return false;
+        if (targetEl.dataset && targetEl.dataset.studioPreviewCommitted === "1") return true;
         if (targetEl.querySelector(".preview-loading")) return false;
         const text = typeof targetEl.textContent === "string" ? targetEl.textContent.trim() : "";
         return text.length > 0;
       }
 
+      function getWatchedPreviewAnchorSignature(element) {
+        if (!element || !element.tagName) return "";
+        const text = String(element.textContent || "").replace(/\s+/g, " ").trim().slice(0, 180);
+        if (!text) return "";
+        return String(element.tagName).toLowerCase() + ":" + text;
+      }
+
+      function captureWatchedPreviewReadingPosition(targetEl) {
+        if (!isWatchedFilePreview || !targetEl || typeof targetEl.querySelectorAll !== "function") return null;
+        const maxScroll = Math.max(0, Number(targetEl.scrollHeight || 0) - Number(targetEl.clientHeight || 0));
+        const ratio = maxScroll > 0 ? Math.max(0, Math.min(1, Number(targetEl.scrollTop || 0) / maxScroll)) : 0;
+        if (typeof targetEl.getBoundingClientRect !== "function") return { ratio };
+        const targetRect = targetEl.getBoundingClientRect();
+        const anchorLine = Number(targetRect.top || 0) + Math.max(20, Math.min(Number(targetEl.clientHeight || 0) * 0.22, 140));
+        const candidates = Array.from(targetEl.querySelectorAll("h1,h2,h3,h4,h5,h6,p,li,pre,table,blockquote,figure"));
+        let anchor = null;
+        for (const candidate of candidates) {
+          if (!candidate || typeof candidate.getBoundingClientRect !== "function") continue;
+          const rect = candidate.getBoundingClientRect();
+          if (Number(rect.bottom || rect.top || 0) >= anchorLine) {
+            anchor = candidate;
+            break;
+          }
+        }
+        if (!anchor && candidates.length) anchor = candidates[candidates.length - 1];
+        const signature = getWatchedPreviewAnchorSignature(anchor);
+        if (!anchor || !signature) return { ratio };
+        let occurrence = 0;
+        for (const candidate of candidates) {
+          if (candidate === anchor) break;
+          if (getWatchedPreviewAnchorSignature(candidate) === signature) occurrence += 1;
+        }
+        const anchorRect = anchor.getBoundingClientRect();
+        return {
+          ratio,
+          signature,
+          occurrence,
+          offset: Number(anchorRect.top || 0) - Number(targetRect.top || 0),
+        };
+      }
+
+      function restoreWatchedPreviewReadingPosition(targetEl, snapshot) {
+        if (!isWatchedFilePreview || !targetEl || !snapshot) return;
+        const candidates = typeof targetEl.querySelectorAll === "function"
+          ? Array.from(targetEl.querySelectorAll("h1,h2,h3,h4,h5,h6,p,li,pre,table,blockquote,figure"))
+          : [];
+        const matching = snapshot.signature
+          ? candidates.filter((candidate) => getWatchedPreviewAnchorSignature(candidate) === snapshot.signature)
+          : [];
+        const anchor = matching[Math.max(0, Number(snapshot.occurrence) || 0)] || null;
+        if (anchor && typeof anchor.getBoundingClientRect === "function" && typeof targetEl.getBoundingClientRect === "function") {
+          const targetRect = targetEl.getBoundingClientRect();
+          const anchorRect = anchor.getBoundingClientRect();
+          const delta = (Number(anchorRect.top || 0) - Number(targetRect.top || 0)) - (Number(snapshot.offset) || 0);
+          targetEl.scrollTop = Math.max(0, Number(targetEl.scrollTop || 0) + delta);
+          return;
+        }
+        const maxScroll = Math.max(0, Number(targetEl.scrollHeight || 0) - Number(targetEl.clientHeight || 0));
+        targetEl.scrollTop = Math.max(0, Math.min(maxScroll, maxScroll * Math.max(0, Math.min(1, Number(snapshot.ratio) || 0))));
+      }
+
+      function scheduleWatchedPreviewReadingPositionRestore(targetEl, renderedText) {
+        if (!isWatchedFilePreview || !targetEl) return;
+        const pane = targetEl === sourcePreviewEl ? "source" : (targetEl === critiqueViewEl ? "response" : "");
+        if (!pane || !watchedFilePreviewReadingPositions[pane]) return;
+        const pending = watchedFilePreviewReadingPositions[pane];
+        if (String(pending.text || "") !== String(renderedText || "")) return;
+        const snapshot = pending.snapshot;
+        watchedFilePreviewReadingPositions[pane] = null;
+        let restored = false;
+        const applyRestore = () => {
+          if (restored) return;
+          restored = true;
+          restoreWatchedPreviewReadingPosition(targetEl, snapshot);
+        };
+        if (typeof window.requestAnimationFrame === "function") {
+          window.requestAnimationFrame(applyRestore);
+        }
+        // Hidden embedded/headless surfaces can suspend animation frames entirely.
+        window.setTimeout(applyRestore, 80);
+      }
+
+      function showWatchedPreviewRenderError(targetEl, message) {
+        if (!isWatchedFilePreview || !targetEl || typeof targetEl.appendChild !== "function") return false;
+        const existing = typeof targetEl.querySelector === "function" ? targetEl.querySelector(".studio-watched-preview-error") : null;
+        if (existing && existing.remove) existing.remove();
+        const notice = document.createElement("div");
+        notice.className = "preview-warning studio-watched-preview-error";
+        notice.setAttribute("role", "status");
+        notice.appendChild(document.createTextNode("Could not render the latest disk revision; keeping the last good preview. " + String(message || "Preview renderer unavailable.") + " "));
+        const retry = document.createElement("button");
+        retry.type = "button";
+        retry.textContent = "Retry";
+        retry.addEventListener("click", () => renderActiveResult());
+        notice.appendChild(retry);
+        targetEl.appendChild(notice);
+        return true;
+      }
+
+      function clearWatchedPreviewRenderError() {
+        if (!isWatchedFilePreview) return;
+        const recovered = Boolean(watchedFilePreviewState.renderError);
+        watchedFilePreviewState.renderError = "";
+        updateSourceBadge();
+        if (recovered) setStatus("Rendered the latest watched file revision.", "success");
+      }
+
       function beginPreviewRender(targetEl) {
         if (!targetEl || !targetEl.classList) return;
 
@@ -10451,6 +10872,55 @@
         });
       }
 
+      async function hydrateStudioPreviewLocalMedia(targetEl, resourceContext) {
+        const fetchResource = (resourceUrl, timeoutLabel) => fetchLocalPreviewResourceDataUrl(
+          resourceContext,
+          resourceUrl,
+          RENDERED_PREVIEW_IMAGE_FETCH_TIMEOUT_MS,
+          timeoutLabel,
+        );
+        await previewResourceHelpers.hydrateStudioPreviewLocalImages(
+          targetEl,
+          (resourceUrl) => fetchResource(resourceUrl, "Preview image load"),
+          {
+            onError: (imageEl, resourceUrl, error) => {
+              replaceStudioBlockedMediaElement(imageEl, resourceUrl, error, "image");
+            },
+          },
+        );
+        await previewResourceHelpers.hydrateStudioPreviewLocalPdfEmbeds(
+          targetEl,
+          (resourceUrl) => fetchResource(resourceUrl, "Preview PDF load"),
+          {
+            onError: (embedEl, resourceUrl, error) => {
+              replaceStudioBlockedMediaElement(embedEl, resourceUrl, error, "pdf");
+            },
+          },
+        );
+      }
+
+      function isCurrentStudioPreviewRender(pane, nonce) {
+        if (pane === "source") {
+          return nonce === sourcePreviewRenderNonce && editorView === "preview";
+        }
+        return nonce === responsePreviewRenderNonce && (rightView === "preview" || rightView === "editor-preview");
+      }
+
+      function createStudioPreviewStagingElement(targetEl) {
+        const staging = document.createElement("div");
+        staging.className = String(targetEl && targetEl.className ? targetEl.className : "rendered-markdown") + " studio-preview-staging";
+        staging.setAttribute("aria-hidden", "true");
+        staging.style.width = Math.max(320, Number(targetEl && targetEl.clientWidth) || 0) + "px";
+        document.body.appendChild(staging);
+        return staging;
+      }
+
+      function commitStudioPreviewStagingElement(targetEl, staging) {
+        const nodes = Array.from(staging.childNodes || []);
+        targetEl.replaceChildren(...nodes);
+        staging.remove();
+      }
+
       async function applyRenderedMarkdown(targetEl, markdown, pane, nonce) {
         const previewPrepared = annotationsEnabled
           ? prepareMarkdownForPandocPreview(markdown)
@@ -10461,42 +10931,44 @@
         };
         const pdfPrepared = prepareStudioPdfBlocksForPreview(previewPrepared.markdown);
         const previewResourceContext = getHtmlPreviewResourceContextOptions();
+        let staging = null;
+        let previewCommitted = false;
+        const stillCurrent = () => isCurrentStudioPreviewRender(pane, nonce);
+        const abandonIfStale = () => {
+          if (stillCurrent()) return false;
+          if (staging && staging.remove) staging.remove();
+          staging = null;
+          return true;
+        };
 
         try {
           const renderedHtml = await renderMarkdownWithPandoc(pdfPrepared.markdown, {
             includeEditorLanguage: pane === "source" || rightView === "editor-preview",
             resourceContext: previewResourceContext,
           });
-
-          if (pane === "source") {
-            if (nonce !== sourcePreviewRenderNonce || editorView !== "preview") return;
-          } else {
-            if (nonce !== responsePreviewRenderNonce || (rightView !== "preview" && rightView !== "editor-preview")) return;
-          }
-
-          clearPreviewJumpHighlight(targetEl);
-          finishPreviewRender(targetEl);
-          targetEl.innerHTML = sanitizeRenderedHtml(renderedHtml, markdown, previewFallbackOptions);
-          await previewResourceHelpers.hydrateStudioPreviewLocalImages(targetEl, (resourceUrl) => (
-            fetchLocalPreviewResourceDataUrl(
-              previewResourceContext,
-              resourceUrl,
-              RENDERED_PREVIEW_IMAGE_FETCH_TIMEOUT_MS,
-              "Preview image load",
-            )
-          ));
-          renderStudioPdfBlocksInElement(targetEl, pdfPrepared.blocks, previewingEditorText);
-          applyPreviewAnnotationPlaceholdersToElement(targetEl, previewPrepared.placeholders);
-          await renderAnnotationMathInElement(targetEl);
-          decoratePdfEmbeds(targetEl);
-          await renderPdfPreviewsInElement(targetEl);
-          decoratePreviewPdfFigures(targetEl);
+          if (abandonIfStale()) return;
+
+          staging = createStudioPreviewStagingElement(targetEl);
+          staging.innerHTML = sanitizeRenderedHtml(renderedHtml, markdown, previewFallbackOptions);
+          await hydrateStudioPreviewLocalMedia(staging, previewResourceContext);
+          if (abandonIfStale()) return;
+          await renderStudioPdfBlocksInElement(staging, pdfPrepared.blocks, previewingEditorText);
+          if (abandonIfStale()) return;
+          applyPreviewAnnotationPlaceholdersToElement(staging, previewPrepared.placeholders);
+          await renderAnnotationMathInElement(staging);
+          if (abandonIfStale()) return;
+          decoratePdfEmbeds(staging);
+          await renderPdfPreviewsInElement(staging);
+          if (abandonIfStale()) return;
+          decoratePreviewPdfFigures(staging);
           const annotationMode = (pane === "source" || pane === "response")
             ? (annotationsEnabled ? "highlight" : "hide")
             : "none";
-          applyAnnotationMarkersToElement(targetEl, annotationMode);
-          await renderMermaidInElement(targetEl);
-          await renderMathFallbackInElement(targetEl);
+          applyAnnotationMarkersToElement(staging, annotationMode);
+          await renderMermaidInElement(staging);
+          if (abandonIfStale()) return;
+          await renderMathFallbackInElement(staging);
+          if (abandonIfStale()) return;
 
           const shouldDecoratePreviewComments = supportsPreviewCommentsForCurrentEditor()
             && (
@@ -10504,35 +10976,56 @@
               || (pane === "response" && rightView === "editor-preview")
             );
           if (shouldDecoratePreviewComments) {
-            decorateRenderedEditorPreviewComments(targetEl, sourceTextEl.value || "");
+            decorateRenderedEditorPreviewComments(staging, sourceTextEl.value || "");
           }
-          decorateCopyablePreviewBlocks(targetEl);
-          decoratePreviewImages(targetEl);
+          decorateCopyablePreviewBlocks(staging);
+          decoratePreviewImages(staging);
 
-          // Warn if relative images are present but unlikely to resolve (non-file-backed content)
+          // Warn if relative images are present but unlikely to resolve (non-file-backed content).
           if (!sourceState.path && !getCurrentResourceDirValue()) {
             var hasRelativeImages = /!\[.*?\]\((?!https?:\/\/|data:)[^)]+\)/.test(markdown || "");
             var hasLatexImages = /\\includegraphics/.test(markdown || "");
             if (hasRelativeImages || hasLatexImages) {
-              appendPreviewNotice(targetEl, "Images not displaying? Set working dir in the editor pane or open via /studio <path>.");
+              appendPreviewNotice(staging, "Images not displaying? Set working dir in the editor pane or open via /studio <path>.");
             }
           }
+          if (abandonIfStale()) return;
 
+          clearPreviewJumpHighlight(targetEl);
+          finishPreviewRender(targetEl);
+          commitStudioPreviewStagingElement(targetEl, staging);
+          staging = null;
+          if (targetEl.dataset) targetEl.dataset.studioPreviewCommitted = "1";
+          previewCommitted = true;
+          if (shouldDecoratePreviewComments) updatePreviewCommentBlocksForElement(targetEl);
+          clearWatchedPreviewRenderError();
+          scheduleWatchedPreviewReadingPositionRestore(targetEl, markdown);
           if (pane === "response") {
             applyPendingResponseScrollReset();
             scheduleResponsePaneRepaintNudge();
           }
         } catch (error) {
-          if (pane === "source") {
-            if (nonce !== sourcePreviewRenderNonce || editorView !== "preview") return;
-          } else {
-            if (nonce !== responsePreviewRenderNonce || (rightView !== "preview" && rightView !== "editor-preview")) return;
+          if (staging && staging.remove) staging.remove();
+          staging = null;
+          if (previewCommitted) {
+            console.error("Preview post-render update failed after the staged document was committed:", error);
+            return;
           }
+          if (!stillCurrent()) return;
 
           const detail = error && error.message ? error.message : String(error || "unknown error");
           clearPreviewJumpHighlight(targetEl);
           finishPreviewRender(targetEl);
+          if (isWatchedFilePreview && hasMeaningfulPreviewContent(targetEl)) {
+            watchedFilePreviewState.renderError = detail;
+            showWatchedPreviewRenderError(targetEl, detail);
+            updateSourceBadge();
+            scheduleWatchedPreviewReadingPositionRestore(targetEl, markdown);
+            setStatus("Could not render the latest disk revision; keeping the last good preview.", "warning");
+            return;
+          }
           targetEl.innerHTML = buildPreviewErrorHtml("Preview renderer unavailable (" + detail + "). Showing plain markdown.", markdown, previewFallbackOptions);
+          scheduleWatchedPreviewReadingPositionRestore(targetEl, markdown);
           if (pane === "response") {
             applyPendingResponseScrollReset();
             scheduleResponsePaneRepaintNudge();
@@ -11355,71 +11848,96 @@
         return "<select class='files-sort-select' data-files-sort aria-label='Files sort order' title='Sort file browser entries. Folders remain grouped first.'>" + options + "</select>";
       }
 
+      function buildFileBrowserEntryRowHtml(entry) {
+        const type = entry && entry.type === "directory" ? "directory" : "file";
+        const kind = (entry && entry.kind) || (type === "directory" ? "directory" : "other");
+        const path = String((entry && entry.path) || "");
+        const name = String((entry && entry.name) || basenameForStudioPath(path));
+        const icon = type === "directory" ? "📁" : (kind === "pdf" ? "📄" : (kind === "image" ? "🖼️" : (kind === "text" || kind === "office" ? "📝" : "📦")));
+        const metaParts = [getFileBrowserKindLabel(entry)];
+        if (type === "file") metaParts.push(formatFileBrowserSize(entry && entry.size));
+        const time = formatFileBrowserTime(entry && entry.mtimeMs);
+        if (time) metaParts.push(time);
+        const newTabAction = kind === "text" || kind === "office"
+          ? "open-new"
+          : ((kind === "pdf" || kind === "image") ? "open-preview-new" : "");
+        const newTabLabel = kind === "text"
+          ? "Open file-backed tab"
+          : (kind === "office" ? "Convert tab" : ((kind === "pdf" || kind === "image") ? "Preview tab" : "New tab"));
+        const newTabTitle = kind === "text"
+          ? "Open this file-backed document in a new refreshable editor tab. Save editor and Refresh from disk will use this file."
+          : (kind === "office" ? "Convert this document to Markdown in a new editor tab." : ((kind === "pdf" || kind === "image") ? "Open this preview in a new Studio tab." : "Open in a new Studio tab."));
+        const newTabButton = newTabAction
+          ? "<button type='button' data-files-action='" + escapeHtml(newTabAction) + "' data-files-path='" + escapeHtml(path) + "' data-files-kind='" + escapeHtml(kind) + "' title='" + escapeHtml(newTabTitle) + "'>" + escapeHtml(newTabLabel) + "</button>"
+          : "";
+        const watchButton = kind === "text"
+          ? "<button type='button' data-files-action='watch-new' data-files-path='" + escapeHtml(path) + "' data-files-kind='text' title='Open a read-only rendered preview that follows this file on disk.'>Preview (follow)</button>"
+          : "";
+        const openTitle = type === "directory"
+          ? "Open folder"
+          : (kind === "text" ? "Open file-backed document in the current editor. Save editor and Refresh from disk will use this file." : (kind === "office" ? "Convert to Markdown in the current editor" : (kind === "pdf" ? "Open PDF preview" : (kind === "image" ? "Open image preview" : "Copy or reveal this file"))));
+        return "<div class='files-row files-row-" + escapeHtml(type) + " files-kind-" + escapeHtml(kind) + "'>"
+          + "<button type='button' class='files-open-btn' data-files-action='" + (type === "directory" ? "open-dir" : "open") + "' data-files-path='" + escapeHtml(path) + "' data-files-kind='" + escapeHtml(kind) + "' title='" + escapeHtml(openTitle) + "'>"
+          + "<span class='files-icon' aria-hidden='true'>" + icon + "</span>"
+          + "<span class='files-name'>" + escapeHtml(name) + "</span>"
+          + "<span class='files-meta'>" + escapeHtml(metaParts.filter(Boolean).join(" · ")) + "</span>"
+          + "</button>"
+          + "<span class='files-actions'>"
+          + watchButton
+          + newTabButton
+          + "<button type='button' data-files-action='copy-path' data-files-path='" + escapeHtml(path) + "'>Copy path</button>"
+          + (type === "file" ? "<button type='button' data-files-action='reveal' data-files-path='" + escapeHtml(path) + "'>Reveal</button>" : "")
+          + "</span>"
+          + "</div>";
+      }
+
+      function buildFileBrowserLocationSelectHtml(state) {
+        const locations = Array.isArray(state && state.locations) ? state.locations : [];
+        if (!locations.length) return "<span class='files-no-locations'>No allowed folders</span>";
+        const rootDir = String((state && state.rootDir) || "");
+        const options = locations.map((location) => {
+          const path = String((location && location.path) || "");
+          const label = String((location && location.label) || basenameForStudioPath(path) || path);
+          return "<option value='" + escapeHtml(path) + "'" + (path === rootDir ? " selected" : "") + ">" + escapeHtml(label + " — " + path) + "</option>";
+        }).join("");
+        return "<select class='files-location-select' data-files-location aria-label='Allowed Files location' title='Choose a folder allowed for this Studio session on the computer running Pi.'>" + options + "</select>";
+      }
+
       function buildFileBrowserPanelHtml() {
         const state = fileBrowserState || {};
         const entries = Array.isArray(state.entries) ? state.entries : [];
+        const exactFiles = Array.isArray(state.exactFiles) ? state.exactFiles : [];
         const currentDir = state.currentDir || "";
         const rootDir = state.rootDir || "";
         const relativeDir = state.relativeDir || ".";
         const parentDisabled = state.parentDir ? "" : " disabled";
         const rows = entries.length
-          ? entries.map((entry) => {
-            const type = entry.type === "directory" ? "directory" : "file";
-            const kind = entry.kind || (type === "directory" ? "directory" : "other");
-            const icon = type === "directory" ? "📁" : (kind === "pdf" ? "📄" : (kind === "image" ? "🖼️" : (kind === "text" || kind === "office" ? "📝" : "📦")));
-            const metaParts = [];
-            metaParts.push(getFileBrowserKindLabel(entry));
-            if (type === "file") metaParts.push(formatFileBrowserSize(entry.size));
-            const time = formatFileBrowserTime(entry.mtimeMs);
-            if (time) metaParts.push(time);
-            const newTabAction = kind === "text" || kind === "office"
-              ? "open-new"
-              : ((kind === "pdf" || kind === "image") ? "open-preview-new" : "");
-            const newTabLabel = kind === "text"
-              ? "Open file-backed tab"
-              : (kind === "office" ? "Convert tab" : ((kind === "pdf" || kind === "image") ? "Preview tab" : "New tab"));
-            const newTabTitle = kind === "text"
-              ? "Open this file-backed document in a new refreshable editor tab. Save editor and Refresh from disk will use this file."
-              : (kind === "office" ? "Convert this document to Markdown in a new editor tab." : ((kind === "pdf" || kind === "image") ? "Open this preview in a new Studio tab." : "Open in a new Studio tab."));
-            const textActions = newTabAction
-              ? "<button type='button' data-files-action='" + escapeHtml(newTabAction) + "' data-files-path='" + escapeHtml(entry.path) + "' title='" + escapeHtml(newTabTitle) + "'>" + escapeHtml(newTabLabel) + "</button>"
-              : "";
-            const openTitle = type === "directory"
-              ? "Open folder"
-              : (kind === "text" ? "Open file-backed document in the current editor. Save editor and Refresh from disk will use this file." : (kind === "office" ? "Convert to Markdown in the current editor" : (kind === "pdf" ? "Open PDF preview" : (kind === "image" ? "Open image preview" : "Copy or reveal this file"))));
-            return "<div class='files-row files-row-" + escapeHtml(type) + " files-kind-" + escapeHtml(kind) + "'>"
-              + "<button type='button' class='files-open-btn' data-files-action='" + (type === "directory" ? "open-dir" : "open") + "' data-files-path='" + escapeHtml(entry.path) + "' data-files-kind='" + escapeHtml(kind) + "' title='" + escapeHtml(openTitle) + "'>"
-              + "<span class='files-icon' aria-hidden='true'>" + icon + "</span>"
-              + "<span class='files-name'>" + escapeHtml(entry.name) + "</span>"
-              + "<span class='files-meta'>" + escapeHtml(metaParts.filter(Boolean).join(" · ")) + "</span>"
-              + "</button>"
-              + "<span class='files-actions'>"
-              + textActions
-              + "<button type='button' data-files-action='copy-path' data-files-path='" + escapeHtml(entry.path) + "'>Copy path</button>"
-              + (type === "file" ? "<button type='button' data-files-action='reveal' data-files-path='" + escapeHtml(entry.path) + "'>Reveal</button>" : "")
-              + "</span>"
-              + "</div>";
-          }).join("")
+          ? entries.map(buildFileBrowserEntryRowHtml).join("")
           : "<div class='files-empty'>" + (state.loading ? "Loading files…" : "This folder is empty.") + "</div>";
+        const exactRows = exactFiles.map(buildFileBrowserEntryRowHtml).join("");
         const notices = [];
         if (state.error) notices.push("<div class='files-notice files-notice-error'>" + escapeHtml(state.error) + "</div>");
+        if (state.grantRequiredPath) notices.push("<div class='files-notice'>Allow that folder to browse it in Files. Exact-file grants do not expose their parent folders.</div>");
         if (state.omitted) notices.push("<div class='files-notice'>" + escapeHtml(String(state.omitted)) + " item" + (state.omitted === 1 ? "" : "s") + " omitted.</div>");
         if (state.omittedIgnored) notices.push("<div class='files-notice'>" + escapeHtml(String(state.omittedIgnored)) + " heavy/cache folder" + (state.omittedIgnored === 1 ? "" : "s") + " hidden.</div>");
         return "<div class='files-panel'>"
           + "<div class='files-toolbar'>"
           + "<div class='files-path-group'><span class='files-label'>Files</span><span class='files-path' title='" + escapeHtml(currentDir) + "'>" + escapeHtml(relativeDir || ".") + "</span></div>"
           + "<div class='files-toolbar-actions'>"
+          + buildFileBrowserLocationSelectHtml(state)
           + buildFileBrowserSortSelectHtml()
+          + "<button type='button' data-files-action='allow-folder'>Allow folder…</button>"
           + "<button type='button' data-files-action='parent'" + parentDisabled + ">Parent</button>"
           + "<button type='button' data-files-action='refresh'>Refresh</button>"
           + (currentDir ? "<button type='button' data-files-action='copy-current' data-files-path='" + escapeHtml(currentDir) + "'>Copy path</button>" : "")
           + (currentDir ? "<button type='button' data-files-action='use-working-dir' data-files-path='" + escapeHtml(currentDir) + "'>Use as working dir</button>" : "")
-          + (rootDir ? "<button type='button' data-files-action='open-root' data-files-path='" + escapeHtml(rootDir) + "' title='Open the Files root folder in Finder or the system file manager.'>Open root</button>" : "")
+          + (rootDir ? "<button type='button' data-files-action='open-root' data-files-path='" + escapeHtml(rootDir) + "' title='Open the Files root folder in Finder or the system file manager on the computer running Pi.'>Open root</button>" : "")
           + (rootDir ? "<button type='button' data-files-action='copy-root' data-files-path='" + escapeHtml(rootDir) + "'>Copy root</button>" : "")
           + "</div>"
           + "</div>"
-          + "<div class='files-subtitle'>Root: <span title='" + escapeHtml(rootDir) + "'>" + escapeHtml(rootDir || "current Studio directory") + "</span></div>"
+          + "<div class='files-subtitle'>Allowed root on the computer running Pi: <span title='" + escapeHtml(rootDir) + "'>" + escapeHtml(rootDir || "none selected") + "</span></div>"
           + notices.join("")
+          + (exactRows ? "<section class='files-exact-section'><div class='files-section-title'>Allowed exact files</div><div class='files-list' role='list'>" + exactRows + "</div></section>" : "")
           + "<div class='files-list' role='list'>" + rows + "</div>"
           + "</div>";
       }
@@ -11434,6 +11952,9 @@
             relativeDir: "",
             parentDir: null,
             entries: [],
+            exactFiles: [],
+            locations: [],
+            grantRequiredPath: "",
             omitted: 0,
             omittedIgnored: 0,
             sort: fileBrowserSortMode,
@@ -11455,12 +11976,17 @@
       async function loadFileBrowserDirectory(dir, options) {
         const context = getHtmlPreviewResourceContextOptions();
         const contextKey = getFileBrowserContextKey();
+        const config = options && typeof options === "object" ? options : {};
+        const requestedRoot = Object.prototype.hasOwnProperty.call(config, "root")
+          ? normalizeStudioResourceDirValue(config.root || "")
+          : normalizeStudioResourceDirValue(fileBrowserState.rootDir || "");
         const nonce = ++fileBrowserLoadNonce;
         fileBrowserState = {
           ...fileBrowserState,
           contextKey,
           loading: true,
           error: "",
+          grantRequiredPath: "",
         };
         if (rightView === "files") {
           finishPreviewRender(critiqueViewEl);
@@ -11469,6 +11995,7 @@
         try {
           const query = {};
           if (dir) query.dir = String(dir);
+          if (requestedRoot) query.root = requestedRoot;
           if (context.sourcePath) query.sourcePath = context.sourcePath;
           if (context.resourceDir) query.resourceDir = context.resourceDir;
           query.sort = normalizeFileBrowserSortMode(fileBrowserSortMode);
@@ -11481,6 +12008,9 @@
             relativeDir: typeof payload.relativeDir === "string" ? payload.relativeDir : ".",
             parentDir: typeof payload.parentDir === "string" ? payload.parentDir : null,
             entries: Array.isArray(payload.entries) ? payload.entries : [],
+            exactFiles: Array.isArray(payload.exactFiles) ? payload.exactFiles : [],
+            locations: Array.isArray(payload.locations) ? payload.locations : [],
+            grantRequiredPath: "",
             omitted: Number(payload.omitted) || 0,
             omittedIgnored: Number(payload.omittedIgnored) || 0,
             sort: normalizeFileBrowserSortMode(payload.sort || fileBrowserSortMode),
@@ -11494,11 +12024,18 @@
             critiqueViewEl.innerHTML = buildFileBrowserPanelHtml();
             scheduleResponsePaneRepaintNudge();
           }
-          if (options && options.user) setStatus("Loaded file list.", "success");
+          if (config.user) setStatus("Loaded file list.", "success");
         } catch (error) {
           if (nonce !== fileBrowserLoadNonce) return;
+          const errorPayload = error && error.studioPayload && typeof error.studioPayload === "object" ? error.studioPayload : null;
+          const grantRequiredPath = errorPayload && errorPayload.code === "studio-resource-directory-grant-required" && typeof errorPayload.directoryPath === "string"
+            ? normalizeStudioResourceDirValue(errorPayload.directoryPath)
+            : "";
           fileBrowserState = {
             ...fileBrowserState,
+            exactFiles: errorPayload && Array.isArray(errorPayload.exactFiles) ? errorPayload.exactFiles : fileBrowserState.exactFiles,
+            locations: errorPayload && Array.isArray(errorPayload.locations) ? errorPayload.locations : fileBrowserState.locations,
+            grantRequiredPath,
             loading: false,
             error: (error && error.message) ? error.message : String(error || "Could not load files."),
             loaded: true,
@@ -11520,7 +12057,7 @@
       function ensureCurrentEditorFileBackedFromFilesPath(path) {
         const cleanPath = stripPreviewLocalLinkUrlSuffix(path || "").trim();
         if (!isLikelyAbsoluteStudioPath(cleanPath)) return;
-        if (sourceState && sourceState.path === cleanPath) return;
+        if (sourceState && sourceState.path) return;
         const resourceDir = normalizeStudioResourceDirValue(fileBrowserState.rootDir || getCurrentResourceDirValue() || dirnameForDisplayPath(cleanPath));
         if (resourceDirInput && resourceDir) resourceDirInput.value = resourceDir;
         setSourceState({
@@ -11528,7 +12065,7 @@
           label: sourceState && sourceState.label && sourceState.label !== "blank" ? sourceState.label : basenameForStudioPath(cleanPath),
           path: cleanPath,
         });
-        markFileBackedBaseline(sourceTextEl.value);
+        markFileBackedBaseline(sourceTextEl.value, null);
       }
 
       async function openFileBrowserEntry(path, kind) {
@@ -11546,7 +12083,7 @@
           return;
         }
         if (kind === "pdf") {
-          openPreviewPdfLink(path, path, context);
+          await openPreviewPdfLink(path, path, context);
           return;
         }
         if (kind === "image") {
@@ -11556,6 +12093,34 @@
         setStatus("No Studio preview for this file type. Use Copy path or Reveal.", "warning");
       }
 
+      async function allowFileBrowserFolder() {
+        const context = getHtmlPreviewResourceContextOptions();
+        const suggested = normalizeStudioResourceDirValue(
+          fileBrowserState.grantRequiredPath
+          || fileBrowserState.currentDir
+          || fileBrowserState.rootDir
+          || context.resourceDir
+          || (context.sourcePath ? dirnameForDisplayPath(context.sourcePath) : "")
+          || "./",
+        );
+        const path = await requestStudioTextInput(
+          "Allow a folder on the computer running Pi for this Studio session:",
+          suggested,
+          { title: "Allow folder", confirmLabel: "Allow folder", inputLabel: "Folder path" },
+        );
+        if (!path) return;
+        const payload = await fetchStudioJson("/resource-grants", {
+          method: "POST",
+          body: JSON.stringify({ grantKind: "directory", path }),
+        });
+        const grantedPath = payload && payload.grant && payload.grant.kind === "directory" && typeof payload.grant.path === "string"
+          ? payload.grant.path
+          : "";
+        if (!grantedPath) throw new Error("Studio did not return the allowed folder.");
+        await loadFileBrowserDirectory("", { root: grantedPath });
+        setStatus(typeof payload.message === "string" ? payload.message : "Allowed folder for this Studio session.", "success");
+      }
+
       function setFileBrowserCurrentDirectoryAsWorkingDir(path) {
         const nextDir = normalizeStudioResourceDirValue(path || fileBrowserState.currentDir || "");
         if (!nextDir) {
@@ -11577,6 +12142,7 @@
         }
         const context = getHtmlPreviewResourceContextOptions();
         const body = { dir: targetDir };
+        if (fileBrowserState.rootDir) body.root = fileBrowserState.rootDir;
         if (context.sourcePath) body.sourcePath = context.sourcePath;
         if (context.resourceDir) body.resourceDir = context.resourceDir;
         const payload = await fetchStudioJson("/file-browser-open", {
@@ -11589,6 +12155,14 @@
       async function handleFilesPaneChange(event) {
         if (rightView !== "files") return;
         const target = event.target;
+        const locationSelect = target instanceof Element ? target.closest("[data-files-location]") : null;
+        if (locationSelect && "value" in locationSelect) {
+          const nextRoot = normalizeStudioResourceDirValue(locationSelect.value || "");
+          if (nextRoot && nextRoot !== fileBrowserState.rootDir) {
+            await loadFileBrowserDirectory("", { root: nextRoot, user: true });
+          }
+          return;
+        }
         const sortSelect = target instanceof Element ? target.closest("[data-files-sort]") : null;
         if (!sortSelect || !("value" in sortSelect)) return;
         const nextSort = writeFileBrowserSortMode(sortSelect.value);
@@ -11607,6 +12181,10 @@
         const path = actionEl.getAttribute("data-files-path") || "";
         const kind = actionEl.getAttribute("data-files-kind") || getPreviewLocalLinkKind(path);
         try {
+          if (action === "allow-folder") {
+            await allowFileBrowserFolder();
+            return;
+          }
           if (action === "parent") {
             if (fileBrowserState.parentDir) await loadFileBrowserDirectory(fileBrowserState.parentDir, { user: true });
             return;
@@ -11624,17 +12202,13 @@
             return;
           }
           if (action === "open-new") {
-            if (kind === "text" && isLikelyAbsoluteStudioPath(path)) {
-              openFileBackedStudioEditorTab(path, {
-                label: basenameForStudioPath(path),
-                resourceDir: fileBrowserState.rootDir || getCurrentResourceDirValue() || dirnameForDisplayPath(path),
-              });
-              setStatus("Opening file-backed document in a new editor.");
-              return;
-            }
             await openPreviewDocumentInNewEditor(path, getFileBrowserLocalLinkContext());
             return;
           }
+          if (action === "watch-new") {
+            await openPreviewDocumentInWatchedPreview(path, getFileBrowserLocalLinkContext());
+            return;
+          }
           if (action === "open-preview-new") {
             await openPreviewResourceInNewEditor(path, getFileBrowserLocalLinkContext());
             return;
@@ -12345,6 +12919,33 @@
         };
       }
 
+      async function ensureSideQuestionContextRootAuthorized(context) {
+        if (!context || context.gatherScope === "none") return { contextRoot: "" };
+        const body = JSON.stringify({
+          gatherScope: context.gatherScope,
+          sourcePath: context.sourcePath,
+          resourceDir: context.resourceDir,
+          contextPath: context.contextPath,
+        });
+        const check = () => fetchStudioJson("/side-question-context-root", { method: "POST", body });
+        try {
+          return await check();
+        } catch (error) {
+          const request = getStudioDirectoryGrantRequest(error);
+          if (!request) throw error;
+          const allowed = await requestStudioDirectoryGrant(request, {
+            message: "Side questions can map, search, and read supported files beneath this folder through read-only context tools. Allow that access for this Studio session?",
+            cancelStatus: "Side-question folder access cancelled.",
+          });
+          if (!allowed) {
+            const cancelled = new Error("Side-question folder access cancelled.");
+            cancelled.studioCancelled = true;
+            throw cancelled;
+          }
+          return check();
+        }
+      }
+
       async function renderSideQuestionMarkdownToHtml(markdown) {
         const source = String(markdown || "");
         if (sideQuestionMarkdownRenderCache.has(source)) return sideQuestionMarkdownRenderCache.get(source);
@@ -12369,7 +12970,11 @@
             const html = await renderSideQuestionMarkdownToHtml(markdown);
             if (nonce !== sideQuestionPreviewRenderNonce || rightView !== "side-questions" || !critiqueViewEl.contains(target)) return;
             target.innerHTML = html;
+            await hydrateStudioPreviewLocalMedia(target, getHtmlPreviewResourceContextOptions());
             await renderAnnotationMathInElement(target);
+            decoratePdfEmbeds(target);
+            await renderPdfPreviewsInElement(target);
+            decoratePreviewPdfFigures(target);
             await renderMermaidInElement(target);
             await renderMathFallbackInElement(target);
             decorateCopyablePreviewBlocks(target);
@@ -12432,6 +13037,7 @@
           ], sideQuestionUi.thinking) + "</select></label>"
           + "</div>"
           + "<details class='side-question-context-rule'><summary id='sideQuestionContextRule'>Automatic: selection → heading block at cursor → nearby text</summary><p>A heading block starts at the nearest Markdown/LaTeX heading above the cursor and ends before the next heading of the same or higher level. With no heading, Studio uses the surrounding text block or a nearby excerpt.</p></details>"
+          + (scope === "none" ? "" : "<p class='side-question-context-access-note'>Related-file access is limited to folders allowed for this Studio session. Studio asks before starting if this folder is not already allowed.</p>")
           + (scope === "custom" ? "<label class='side-question-path-label'>Folder path<input data-side-question-field='customPath' type='text' value='" + escapeHtml(sideQuestionUi.customPath) + "' placeholder='Folder on the computer running Pi'></label>" : "")
           + "<div class='side-question-checks'>"
           + "<label><input data-side-question-field='includeConversation' type='checkbox'" + (sideQuestionUi.includeConversation ? " checked" : "") + "> Include the current main conversation snapshot</label>"
@@ -12442,7 +13048,7 @@
           + "<dl class='side-question-context-summary'><div><dt>Starting text</dt><dd>" + escapeHtml(summary.attachmentText) + "</dd></div><div><dt>Related files</dt><dd>" + escapeHtml(summary.relatedFilesText) + "</dd></div>" + (summary.gitContextText ? "<div><dt>Git context</dt><dd>" + escapeHtml(summary.gitContextText) + "</dd></div>" : "") + "</dl>"
           + "<label class='side-question-composer-label'>Question<textarea data-side-question-field='draft' rows='4' title='Enter adds a new line. Cmd/Ctrl+Enter asks the side question.' placeholder='Ask about the starting text or anything you want checked…'>" + escapeHtml(sideQuestionUi.draft) + "</textarea></label>"
           + (sideQuestionState && sideQuestionState.error ? "<div class='side-question-error'>" + escapeHtml(sideQuestionState.error) + "</div>" : "")
-          + "<div class='side-question-actions'><button type='button' class='side-question-primary' data-side-question-action='ask' aria-keyshortcuts='Meta+Enter Control+Enter' title='Ask side question (Cmd/Ctrl+Enter)'" + (!isSideQuestionConnectionReady() || (sideQuestionState && sideQuestionState.status === "running") || !sideQuestionUi.draft.trim() || (scope === "custom" && !sideQuestionUi.customPath.trim()) ? " disabled" : "") + ">" + (sideQuestionState && sideQuestionState.status === "running" ? "Preparing side thread…" : "Ask side question") + "</button></div>"
+          + "<div class='side-question-actions'><button type='button' class='side-question-primary' data-side-question-action='ask' aria-keyshortcuts='Meta+Enter Control+Enter' title='Ask side question (Cmd/Ctrl+Enter)'" + (sideQuestionContextGrantPending || !isSideQuestionConnectionReady() || (sideQuestionState && sideQuestionState.status === "running") || !sideQuestionUi.draft.trim() || (scope === "custom" && !sideQuestionUi.customPath.trim()) ? " disabled" : "") + ">" + (sideQuestionContextGrantPending ? "Checking related-file access…" : (sideQuestionState && sideQuestionState.status === "running" ? "Preparing side thread…" : "Ask side question")) + "</button></div>"
           + "</div>";
       }
 
@@ -12513,7 +13119,8 @@
         }
       }
 
-      function submitSideQuestion() {
+      async function submitSideQuestion() {
+        if (sideQuestionContextGrantPending) return;
         const question = String(sideQuestionUi.draft || "").trim();
         if (!question) {
           setStatus("Enter a side question first.", "warning");
@@ -12532,11 +13139,31 @@
         if (sideQuestionState && sideQuestionState.threadId) {
           message.threadId = sideQuestionState.threadId;
         } else {
-          message.context = buildSideQuestionContextPayload();
-          if (message.context.gatherScope === "custom" && !String(message.context.contextPath || "").trim()) {
+          const context = buildSideQuestionContextPayload();
+          if (context.gatherScope === "custom" && !String(context.contextPath || "").trim()) {
             setStatus("Choose a custom context path first.", "warning");
             return;
           }
+          if (context.gatherScope !== "none") {
+            sideQuestionContextGrantPending = true;
+            if (rightView === "side-questions") renderSideQuestionView();
+            setStatus("Checking side-question folder access…", "warning");
+            try {
+              await ensureSideQuestionContextRootAuthorized(context);
+            } catch (error) {
+              if (!(error && error.studioCancelled)) {
+                const messageText = error && error.message ? error.message : String(error || "Could not authorize side-question context.");
+                if (!sideQuestionState) sideQuestionState = normalizeSideQuestionState(null);
+                sideQuestionState.error = messageText;
+                setStatus("Could not use related files: " + messageText, "warning");
+              }
+              return;
+            } finally {
+              sideQuestionContextGrantPending = false;
+              if (rightView === "side-questions" && (!sideQuestionState || !sideQuestionState.threadId)) renderSideQuestionView();
+            }
+          }
+          message.context = context;
         }
         if (!sendMessage(message)) return;
         sideQuestionUi.draft = "";
@@ -12652,7 +13279,7 @@
         event.preventDefault();
         const action = target.getAttribute("data-side-question-action");
         if (action === "ask") {
-          submitSideQuestion();
+          await submitSideQuestion();
         } else if (action === "stop") {
           if (sideQuestionState && sideQuestionState.threadId && sideQuestionState.requestId) {
             sendMessage({ type: "side_question_cancel_request", threadId: sideQuestionState.threadId, requestId: sideQuestionState.requestId });
@@ -12705,7 +13332,7 @@
         if (field === "draft") sideQuestionUi.draft = target.value;
         if (field === "customPath") sideQuestionUi.customPath = target.value;
         const askButton = critiqueViewEl.querySelector("[data-side-question-action='ask']");
-        if (askButton) askButton.disabled = !isSideQuestionConnectionReady() || !sideQuestionUi.draft.trim() || (getSideQuestionGatherScope() === "custom" && !sideQuestionUi.customPath.trim());
+        if (askButton) askButton.disabled = sideQuestionContextGrantPending || !isSideQuestionConnectionReady() || !sideQuestionUi.draft.trim() || (getSideQuestionGatherScope() === "custom" && !sideQuestionUi.customPath.trim());
       }
 
       function handleSideQuestionKeydown(event) {
@@ -12719,7 +13346,7 @@
         if (!submitShortcut) return;
         event.preventDefault();
         event.stopPropagation();
-        if (!sideQuestionState || sideQuestionState.status !== "running") submitSideQuestion();
+        if (!sideQuestionState || sideQuestionState.status !== "running") void submitSideQuestion();
       }
 
       async function handleSideQuestionChange(event) {
@@ -13212,13 +13839,13 @@
       function updateSaveFileTooltip() {
         if (!saveOverBtn) return;
 
-        var effectivePath = getEffectiveSavePath();
+        var effectivePath = sourceState && sourceState.path ? sourceState.path : "";
         if (effectivePath) {
-          saveOverBtn.title = "Overwrite file: " + effectivePath + " · Shortcut: Cmd/Ctrl+S.";
+          saveOverBtn.title = "Save file when its disk revision still matches: " + effectivePath + " · Shortcut: Cmd/Ctrl+S.";
           return;
         }
 
-        saveOverBtn.title = "Save editor is available after opening a file, setting a working dir, or using Save editor as…. Shortcut: Cmd/Ctrl+S falls back to Save editor as… when needed.";
+        saveOverBtn.title = "Save editor is available after opening a file-backed document. Use Save editor as… for a new file.";
       }
 
       function updateRefreshFromDiskTooltip() {
@@ -13233,13 +13860,13 @@
       }
 
       function syncActionButtons() {
-        const canSaveOver = Boolean(getEffectiveSavePath());
+        const canSaveOver = hasRefreshableFilePath();
         const canRefreshFromDisk = hasRefreshableFilePath();
 
-        fileInput.disabled = uiBusy;
-        if (importFileBtn) importFileBtn.disabled = uiBusy;
-        if (sourceBadgeEl) sourceBadgeEl.disabled = uiBusy;
-        if (sourceResetOriginBtn) sourceResetOriginBtn.disabled = uiBusy;
+        fileInput.disabled = uiBusy || isWatchedFilePreview;
+        if (importFileBtn) importFileBtn.disabled = uiBusy || isWatchedFilePreview;
+        if (sourceBadgeEl) sourceBadgeEl.disabled = uiBusy || isWatchedFilePreview;
+        if (sourceResetOriginBtn) sourceResetOriginBtn.disabled = uiBusy || isWatchedFilePreview;
         if (sourceOpenCurrentFileTabBtn) {
           sourceOpenCurrentFileTabBtn.disabled = uiBusy || !hasRefreshableFilePath();
           sourceOpenCurrentFileTabBtn.title = hasRefreshableFilePath()
@@ -13247,17 +13874,21 @@
             : "Available after opening a file-backed document.";
         }
         if (sourceOpenCurrentTextCopyTabBtn) sourceOpenCurrentTextCopyTabBtn.disabled = uiBusy || wsState !== "Ready" || !String(sourceTextEl.value || "").trim();
-        saveAsBtn.disabled = uiBusy;
-        saveOverBtn.disabled = uiBusy || !canSaveOver;
-        if (refreshFromDiskBtn) refreshFromDiskBtn.disabled = uiBusy || !canRefreshFromDisk;
-        if (clearWorkspaceBtn) clearWorkspaceBtn.disabled = uiBusy;
+        saveAsBtn.disabled = uiBusy || isWatchedFilePreview;
+        saveOverBtn.disabled = uiBusy || isWatchedFilePreview || !canSaveOver;
+        if (refreshFromDiskBtn) refreshFromDiskBtn.disabled = uiBusy || isWatchedFilePreview || !canRefreshFromDisk;
+        if (clearWorkspaceBtn) clearWorkspaceBtn.disabled = uiBusy || isWatchedFilePreview;
         sendEditorBtn.disabled = uiBusy || isEditorOnlyMode;
-        if (getEditorBtn) getEditorBtn.disabled = uiBusy;
+        if (getEditorBtn) getEditorBtn.disabled = uiBusy || isWatchedFilePreview;
+        if (watchedOpenEditableBtn) {
+          watchedOpenEditableBtn.hidden = !isWatchedFilePreview;
+          watchedOpenEditableBtn.disabled = uiBusy || !watchedFilePreviewState.path;
+        }
         syncRunAndCritiqueButtons();
         copyDraftBtn.disabled = uiBusy;
         if (suggestCompletionBtn) {
           const hasSuggestionForCurrentText = Boolean(completionSuggestionState && sourceTextEl && sourceTextEl.value === completionSuggestionState.baseText);
-          suggestCompletionBtn.disabled = wsState !== "Ready" || (!completionSuggestionInFlight && (uiBusy || !String(sourceTextEl.value || "").trim()));
+          suggestCompletionBtn.disabled = isWatchedFilePreview || wsState !== "Ready" || (!completionSuggestionInFlight && (uiBusy || !String(sourceTextEl.value || "").trim()));
           suggestCompletionBtn.textContent = completionSuggestionInFlight ? "Stop" : (hasSuggestionForCurrentText ? "Try another" : "Suggest");
           suggestCompletionBtn.title = completionSuggestionInFlight
             ? "Stop the current suggestion request."
@@ -13273,15 +13904,15 @@
         if (highlightSelect) highlightSelect.disabled = uiBusy;
         if (lineNumbersSelect) lineNumbersSelect.disabled = uiBusy;
         if (annotationModeSelect) annotationModeSelect.disabled = uiBusy;
-        if (saveAnnotatedBtn) saveAnnotatedBtn.disabled = uiBusy;
-        if (stripAnnotationsBtn) stripAnnotationsBtn.disabled = uiBusy || !hasAnnotationMarkers(sourceTextEl.value);
+        if (saveAnnotatedBtn) saveAnnotatedBtn.disabled = uiBusy || isWatchedFilePreview;
+        if (stripAnnotationsBtn) stripAnnotationsBtn.disabled = uiBusy || isWatchedFilePreview || !hasAnnotationMarkers(sourceTextEl.value);
         if (compactBtn) compactBtn.disabled = isEditorOnlyMode || uiBusy || compactInProgress || wsState === "Disconnected";
         editorViewSelect.disabled = isEditorOnlyMode;
         syncRightViewModeOptions();
-        rightViewSelect.disabled = false;
+        rightViewSelect.disabled = isWatchedFilePreview;
         followSelect.disabled = isEditorOnlyMode || uiBusy;
         if (responseHighlightSelect) responseHighlightSelect.disabled = isEditorOnlyMode || rightView !== "markdown";
-        insertHeaderBtn.disabled = uiBusy;
+        insertHeaderBtn.disabled = uiBusy || isWatchedFilePreview;
         lensSelect.disabled = uiBusy || isEditorOnlyMode;
         updateSaveFileTooltip();
         updateRefreshFromDiskTooltip();
@@ -13298,9 +13929,14 @@
 
       function setSourceState(next, options) {
         const previousDescriptor = getCurrentStudioDocumentDescriptor();
+        const previousPath = sourceState && sourceState.path ? sourceState.path : null;
         const previousQuartoPath = getCurrentStudioQuartoSourcePath();
         const previousPreviewResourceContext = getHtmlPreviewResourceContextOptions();
         const nextPath = next && next.path ? next.path : null;
+        if (isWatchedFilePreview && watchedFilePreviewState.path && nextPath !== watchedFilePreviewState.path) {
+          setStatus("This read-only preview remains bound to its watched file.", "warning");
+          return false;
+        }
         sourceState = {
           source: next && next.source ? next.source : "blank",
           label: next && next.label ? next.label : "blank",
@@ -13318,7 +13954,7 @@
           quartoPreviewActionRequestId = null;
           quartoPreviewLogVisible = false;
         }
-        if (!sourceState.path) {
+        if (!sourceState.path || sourceState.path !== previousPath) {
           clearFileBackedBaseline();
         }
         syncRightViewModeOptions();
@@ -13425,6 +14061,7 @@
           version: 1,
           savedAt: lastWorkspacePersistenceSavedAt,
           sourceState: normalizeWorkspaceSourceState(sourceState),
+          diskRevision: fileBackedDiskRevision,
           resourceDir: getCurrentResourceDirValue(),
           editorView,
           rightView: normalizeRightViewValue(rightView),
@@ -13460,7 +14097,7 @@
       }
 
       function persistWorkspaceStateNow(options) {
-        if (!workspacePersistenceReady) return;
+        if (!workspacePersistenceReady || isWatchedFilePreview) return;
         try {
           const payload = buildWorkspacePersistencePayload();
           if (payload.text.length > STUDIO_WORKSPACE_MAX_TEXT_CHARS) {
@@ -13482,7 +14119,7 @@
       }
 
       function scheduleWorkspacePersistence() {
-        if (!workspacePersistenceReady || workspacePersistTimer !== null) return;
+        if (!workspacePersistenceReady || isWatchedFilePreview || workspacePersistTimer !== null) return;
         workspacePersistTimer = window.setTimeout(() => {
           workspacePersistTimer = null;
           persistWorkspaceStateNow();
@@ -13490,6 +14127,7 @@
       }
 
       function flushWorkspacePersistence(options) {
+        if (isWatchedFilePreview) return;
         if (workspacePersistTimer !== null) {
           window.clearTimeout(workspacePersistTimer);
           workspacePersistTimer = null;
@@ -13519,9 +14157,17 @@
         if (!shouldRestorePersistedWorkspaceState(state)) return false;
         const nextSourceState = normalizeWorkspaceSourceState(state.sourceState);
         const nextResourceDir = normalizeStudioResourceDirValue(typeof state.resourceDir === "string" ? state.resourceDir : "");
+        const currentBaselineText = fileBackedBaselineText;
+        const currentDiskRevision = fileBackedDiskRevision;
+        const persistedDiskRevision = normalizeStudioDiskRevision(state.diskRevision);
         if (resourceDirInput) resourceDirInput.value = nextResourceDir;
         setEditorText(state.text, { preserveScroll: false, preserveSelection: false });
         setSourceState(nextSourceState);
+        if (nextSourceState.path) {
+          fileBackedBaselineText = currentBaselineText;
+          fileBackedDiskRevision = persistedDiskRevision
+            || (currentBaselineText !== null && state.text === currentBaselineText ? currentDiskRevision : null);
+        }
         if (resourceDirInput && nextResourceDir) {
           resourceDirInput.value = nextResourceDir;
           updateSourceBadge();
@@ -13607,6 +14253,10 @@
       }
 
       function setEditorText(nextText, options) {
+        if (isWatchedFilePreview && !(options && options.allowWatchedFileUpdate === true)) {
+          setStatus("This preview is read-only and follows its watched file on disk.", "warning");
+          return false;
+        }
         const value = String(nextText || "");
         const preserveScroll = Boolean(options && options.preserveScroll);
         const preserveSelection = Boolean(options && options.preserveSelection);
@@ -13654,9 +14304,14 @@
         updateEditorSelectionCommentUi();
         updateOutlineUi();
         scheduleWorkspacePersistence();
+        return true;
       }
 
       function applySourceTextEdit(nextText, selectionStart, selectionEnd) {
+        if (isWatchedFilePreview) {
+          setStatus("This preview is read-only and follows its watched file on disk.", "warning");
+          return false;
+        }
         const value = String(nextText || "");
         sourceTextEl.value = value;
         const maxIndex = value.length;
@@ -13668,6 +14323,7 @@
         if (editorView === "markdown") {
           scheduleEditorLineNumberRender();
         }
+        return true;
       }
 
       function readCompletionSuggestionContextMode() {
@@ -14538,6 +15194,11 @@
         return launch.fail(message || "Studio could not prepare this tab. Return to the originating Studio page for details.");
       }
 
+      function cancelPendingStudioTab(launch, message) {
+        if (!launch || typeof launch.cancel !== "function") return false;
+        return launch.cancel(message || "Studio tab launch was cancelled.");
+      }
+
       function abandonAllStudioTabLaunches(message) {
         const launches = Array.from(activeStudioTabLaunches);
         activeStudioTabLaunches.clear();
@@ -14616,7 +15277,10 @@
           const message = payload && typeof payload.error === "string"
             ? payload.error
             : (response.status + " " + response.statusText).trim();
-          throw new Error(message || (method + " " + pathname + " failed."));
+          const requestError = new Error(message || (method + " " + pathname + " failed."));
+          requestError.studioPayload = payload && typeof payload === "object" ? payload : null;
+          requestError.studioStatus = response.status;
+          throw requestError;
         }
         return payload;
       }
@@ -14649,6 +15313,7 @@
       ]);
       let previewLinkMenuEl = null;
       let activePreviewLinkContext = null;
+      let previewLinkMenuRequestId = 0;
 
       function stripPreviewLocalLinkUrlSuffix(href) {
         const raw = String(href || "").trim();
@@ -14715,7 +15380,7 @@
         if (!raw || raw.charAt(0) === "#") return false;
         if (/^\/\//.test(raw)) return false;
         if (/^(?:https?|mailto|tel|data|blob|javascript|about):/i.test(raw)) return false;
-        if (/^\/(?:pdf-resource|html-preview-resource|export-pdf|export-html|render-preview|render-math|import-file-copy|local-preview-link|reveal-local-resource|open-local-resource)(?:[?#/]|$)/i.test(raw)) return false;
+        if (/^\/(?:pdf-resource|html-preview-resource|export-pdf|export-html|render-preview|render-math|import-file-copy|resource-grants|local-preview-link|reveal-local-resource|open-local-resource)(?:[?#/]|$)/i.test(raw)) return false;
         return true;
       }
 
@@ -14785,36 +15450,53 @@
         menu.style.top = y + "px";
       }
 
-      function showPreviewLinkMenu(anchor, event, contextOverride) {
+      async function showPreviewLinkMenu(anchor, event, contextOverride) {
         const href = String(anchor && anchor.getAttribute ? anchor.getAttribute("href") || "" : (contextOverride && contextOverride.href ? contextOverride.href : "")).trim();
         if (!isStudioLocalPreviewHref(href)) return false;
         const kind = getPreviewLocalLinkKind(href);
-        const menu = ensurePreviewLinkMenu();
-        menu.innerHTML = "";
         const linkContext = getEffectivePreviewLinkContext(contextOverride);
-        activePreviewLinkContext = {
+        const nextContext = {
           href,
           title: String((contextOverride && contextOverride.title) || (anchor && anchor.textContent) || href || "local link").trim() || href,
           sourcePath: linkContext.sourcePath,
           resourceDir: linkContext.resourceDir,
         };
+        const menuPoint = {
+          clientX: event && event.clientX,
+          clientY: event && event.clientY,
+        };
+        closePreviewLinkMenu();
+        const menuRequestId = ++previewLinkMenuRequestId;
+        try {
+          await fetchPreviewLocalLink("resolve", href, nextContext);
+        } catch (error) {
+          if (!(error && error.studioCancelled)) {
+            setStatus((error && error.message) ? error.message : String(error || "Could not inspect this local resource."), "warning");
+          }
+          return false;
+        }
+        if (menuRequestId !== previewLinkMenuRequestId) return false;
+        const menu = ensurePreviewLinkMenu();
+        menu.innerHTML = "";
+        activePreviewLinkContext = nextContext;
         if (kind === "pdf") {
           appendPreviewLinkMenuButton(menu, "Open PDF preview", "open-pdf");
           appendPreviewLinkMenuButton(menu, "Open in new Studio tab", "open-preview-new");
           appendPreviewLinkMenuButton(menu, "Open in system viewer", "open-system");
         } else if (kind === "text") {
+          appendPreviewLinkMenuButton(menu, "Preview file (follow changes)", "watch-new");
           appendPreviewLinkMenuButton(menu, "Open file tab", "open-new");
-          appendPreviewLinkMenuButton(menu, "Open here", "open-here");
+          if (!isWatchedFilePreview) appendPreviewLinkMenuButton(menu, "Open here", "open-here");
         } else if (kind === "office") {
           appendPreviewLinkMenuButton(menu, "Convert tab", "open-new");
-          appendPreviewLinkMenuButton(menu, "Convert here", "open-here");
+          if (!isWatchedFilePreview) appendPreviewLinkMenuButton(menu, "Convert here", "open-here");
         } else if (kind === "image") {
           appendPreviewLinkMenuButton(menu, "Open image preview", "open-image");
           appendPreviewLinkMenuButton(menu, "Open in new Studio tab", "open-preview-new");
         }
         appendPreviewLinkMenuButton(menu, "Reveal in file manager", "reveal");
         appendPreviewLinkMenuButton(menu, "Copy path", "copy-path");
-        positionPreviewLinkMenu(menu, event && event.clientX, event && event.clientY);
+        positionPreviewLinkMenu(menu, menuPoint.clientX, menuPoint.clientY);
         const firstButton = menu.querySelector("button");
         if (firstButton && typeof firstButton.focus === "function") {
           window.setTimeout(() => firstButton.focus({ preventScroll: true }), 0);
@@ -14822,10 +15504,108 @@
         return true;
       }
 
-      async function fetchPreviewLocalLink(action, href, contextOverride) {
-        return fetchStudioJson("/local-preview-link", {
-          query: { ...getPreviewLinkResourceQuery(href, contextOverride), action },
+      function getStudioResourceGrantRequest(error) {
+        const payload = error && error.studioPayload && typeof error.studioPayload === "object"
+          ? error.studioPayload
+          : null;
+        if (!payload || payload.code !== "studio-resource-grant-required") return null;
+        const path = typeof payload.path === "string" ? payload.path.trim() : "";
+        const directoryPath = typeof payload.directoryPath === "string" ? payload.directoryPath.trim() : "";
+        if (!path || !directoryPath) return null;
+        return {
+          path,
+          directoryPath,
+          label: typeof payload.label === "string" && payload.label.trim() ? payload.label.trim() : basenameForStudioPath(path),
+        };
+      }
+
+      function getStudioDirectoryGrantRequest(error) {
+        const payload = error && error.studioPayload && typeof error.studioPayload === "object"
+          ? error.studioPayload
+          : null;
+        if (!payload || payload.code !== "studio-resource-directory-grant-required") return null;
+        const directoryPath = typeof payload.directoryPath === "string" ? payload.directoryPath.trim() : "";
+        if (!directoryPath) return null;
+        return {
+          directoryPath,
+          label: typeof payload.label === "string" && payload.label.trim() ? payload.label.trim() : basenameForStudioPath(directoryPath),
+        };
+      }
+
+      async function requestStudioDirectoryGrant(request, options) {
+        if (!request || !request.directoryPath) return false;
+        const config = options && typeof options === "object" ? options : {};
+        const choice = await openStudioDecision({
+          mode: "confirm",
+          title: "Allow " + (request.label || "this folder") + "?",
+          message: (config.message || "Allow read-only access beneath this folder for the current Studio session?")
+            + "\n\nFolder on the computer running Pi:\n" + request.directoryPath,
+          cancelLabel: "Cancel",
+          confirmLabel: "Allow this folder for this Studio session",
         });
+        if (choice !== true) {
+          setStatus(config.cancelStatus || "Folder access cancelled.", "warning");
+          return false;
+        }
+        const payload = await fetchStudioJson("/resource-grants", {
+          method: "POST",
+          body: JSON.stringify({ grantKind: "directory", path: request.directoryPath }),
+        });
+        fileBrowserState = { ...fileBrowserState, contextKey: "", loaded: false };
+        setStatus(typeof payload.message === "string" ? payload.message : "Allowed this folder for the current Studio session.", "success");
+        return true;
+      }
+
+      async function requestStudioResourceGrant(request) {
+        if (!request) return false;
+        const choice = await openStudioDecision({
+          mode: "confirm",
+          title: "Allow " + request.label + "?",
+          message: "This local resource is outside the locations currently available to Studio.\n\n"
+            + "File on the computer running Pi:\n" + request.path + "\n\n"
+            + "Allow only this file, or allow its containing folder for this Studio session?",
+          cancelLabel: "Cancel",
+          secondaryLabel: "Allow this folder for this Studio session",
+          secondaryValue: "directory",
+          confirmLabel: "Allow this file",
+        });
+        const grantKind = choice === true ? "file" : choice === "directory" ? "directory" : "";
+        if (!grantKind) {
+          setStatus("Local resource access cancelled.", "warning");
+          return false;
+        }
+        const grantPath = grantKind === "directory" ? request.directoryPath : request.path;
+        const payload = await fetchStudioJson("/resource-grants", {
+          method: "POST",
+          body: JSON.stringify({ grantKind, path: grantPath }),
+        });
+        fileBrowserState = { ...fileBrowserState, contextKey: "", loaded: false };
+        setStatus(typeof payload.message === "string" ? payload.message : "Allowed local resource for this Studio session.", "success");
+        return true;
+      }
+
+      async function fetchPreviewLocalLink(action, href, contextOverride, options) {
+        const request = () => {
+          const query = { ...getPreviewLinkResourceQuery(href, contextOverride), action };
+          if (isWatchedFilePreview) {
+            query.watchedFile = "1";
+            const watchedDocId = initialQueryParams.get("docId") || "";
+            if (watchedDocId) query.docId = watchedDocId;
+          }
+          return fetchStudioJson("/local-preview-link", { query });
+        };
+        try {
+          return await request();
+        } catch (error) {
+          const grantRequest = getStudioResourceGrantRequest(error);
+          if (!grantRequest || (options && options.skipGrantPrompt === true)) throw error;
+          if (!(await requestStudioResourceGrant(grantRequest))) {
+            const cancelled = new Error("Local resource access cancelled.");
+            cancelled.studioCancelled = true;
+            throw cancelled;
+          }
+          return request();
+        }
       }
 
       function getPreviewPdfViewerUrl(href, contextOverride) {
@@ -14836,16 +15616,16 @@
         return resourceUrl && page ? resourceUrl + "#page=" + encodeURIComponent(String(page)) : resourceUrl;
       }
 
-      function openPreviewPdfLink(href, title, contextOverride) {
+      async function openPreviewPdfLink(href, title, contextOverride) {
+        await fetchPreviewLocalLink("resolve", href, contextOverride);
         const viewerUrl = getPreviewPdfViewerUrl(href, contextOverride);
         if (!viewerUrl) {
           setStatus("Could not resolve this PDF link. Open the source file or set a working directory first.", "warning");
           return false;
         }
-        const cleanPath = stripPreviewLocalLinkUrlSuffix(href);
         const context = contextOverride && typeof contextOverride === "object" ? contextOverride : {};
         const resourceQuery = buildStudioPdfResourceQuery({
-          path: cleanPath,
+          path: stripPreviewLocalLinkUrlSuffix(href),
           sourcePath: context.sourcePath || "",
           resourceDir: context.resourceDir || "",
         }, true);
@@ -14854,6 +15634,7 @@
       }
 
       async function openPreviewImageLink(href, title, contextOverride) {
+        await fetchPreviewLocalLink("resolve", href, contextOverride);
         const payload = await fetchStudioJson("/html-preview-resource", {
           query: getPreviewLinkResourceQuery(href, contextOverride),
         });
@@ -14904,6 +15685,9 @@
       }
 
       async function openPreviewDocumentHere(href, contextOverride, options) {
+        if (isWatchedFilePreview) {
+          throw new Error("This preview follows one disk file and cannot open another document here. Open a new file tab instead.");
+        }
         if (!(await confirmPreviewOfficeConversion(href, "here"))) return;
         if (editorHasPotentialUnsavedContent()) {
           const kind = getPreviewLocalLinkKind(href);
@@ -14933,7 +15717,7 @@
           setSourceState({ source: "blank", label, path: null });
         } else {
           setSourceState({ source: "file", label, path });
-          markFileBackedBaseline(payload.text);
+          markFileBackedBaseline(payload.text, payload.diskRevision);
         }
         const detected = converted ? "markdown" : detectLanguageFromName(path || label);
         if (detected) setEditorLanguage(detected);
@@ -14955,7 +15739,30 @@
           navigatePendingStudioTab(launch, relativeUrl);
           setStatus(payload && payload.converted ? "Opening converted document in a new editor." : "Opening file-backed document in a new editor.");
         } catch (error) {
-          failPendingStudioTab(launch, "Studio could not prepare this document tab. Return to the originating Studio page for details.");
+          if (error && error.studioCancelled) {
+            cancelPendingStudioTab(launch, "Local resource access was cancelled.");
+          } else {
+            failPendingStudioTab(launch, "Studio could not prepare this document tab. Return to the originating Studio page for details.");
+          }
+          throw error;
+        }
+      }
+
+      async function openPreviewDocumentInWatchedPreview(href, contextOverride) {
+        let launch = null;
+        try {
+          launch = openPendingStudioTab("preview");
+          const payload = await fetchPreviewLocalLink("watch-url", href, contextOverride);
+          const relativeUrl = payload && typeof payload.relativeUrl === "string" ? payload.relativeUrl : "";
+          if (!relativeUrl) throw new Error("Studio did not return a watched-preview URL.");
+          navigatePendingStudioTab(launch, relativeUrl);
+          setStatus("Opening read-only preview that follows disk changes.");
+        } catch (error) {
+          if (error && error.studioCancelled) {
+            cancelPendingStudioTab(launch, "Local resource access was cancelled.");
+          } else {
+            failPendingStudioTab(launch, "Studio could not prepare this watched preview. Return to the originating Studio page for details.");
+          }
           throw error;
         }
       }
@@ -14970,7 +15777,11 @@
           navigatePendingStudioTab(launch, relativeUrl);
           setStatus("Opening preview in a new Studio tab.");
         } catch (error) {
-          failPendingStudioTab(launch, "Studio could not prepare this preview tab. Return to the originating Studio page for details.");
+          if (error && error.studioCancelled) {
+            cancelPendingStudioTab(launch, "Local resource access was cancelled.");
+          } else {
+            failPendingStudioTab(launch, "Studio could not prepare this preview tab. Return to the originating Studio page for details.");
+          }
           throw error;
         }
       }
@@ -14985,6 +15796,7 @@
       }
 
       async function revealPreviewLocalLink(href, contextOverride) {
+        await fetchPreviewLocalLink("resolve", href, contextOverride);
         const query = getPreviewLinkResourceQuery(href, contextOverride);
         const payload = await fetchStudioJson("/reveal-local-resource", {
           method: "POST",
@@ -14998,10 +15810,11 @@
         if (!href) return;
         try {
           if (action === "open-pdf") {
-            openPreviewPdfLink(href, context.title || href, context);
+            await openPreviewPdfLink(href, context.title || href, context);
             return;
           }
           if (action === "open-system") {
+            await fetchPreviewLocalLink("resolve", href, context);
             await runStudioPdfLocalAction("system-viewer", getPreviewLinkResourceQuery(href, context));
             return;
           }
@@ -15009,6 +15822,10 @@
             await openPreviewDocumentInNewEditor(href, context);
             return;
           }
+          if (action === "watch-new") {
+            await openPreviewDocumentInWatchedPreview(href, context);
+            return;
+          }
           if (action === "open-preview-new") {
             await openPreviewResourceInNewEditor(href, context);
             return;
@@ -15043,7 +15860,9 @@
         closePreviewLinkMenu();
         const title = String(anchor.textContent || href).trim() || href;
         if (kind === "pdf") {
-          openPreviewPdfLink(href, title);
+          void openPreviewPdfLink(href, title).catch((error) => {
+            setStatus((error && error.message) ? error.message : String(error || "Could not open linked PDF."), "warning");
+          });
           return;
         }
         if (kind === "image") {
@@ -15053,9 +15872,7 @@
           return;
         }
         if (kind === "text" || kind === "office") {
-          void openPreviewDocumentInNewEditor(href).catch((error) => {
-            setStatus((error && error.message) ? error.message : String(error || "Could not open linked file."), "warning");
-          });
+          void showPreviewLinkMenu(anchor, event);
           return;
         }
         setStatus("Right-click this local link for file actions.", "warning");
@@ -15066,7 +15883,7 @@
         if (!anchor) return;
         event.preventDefault();
         event.stopPropagation();
-        showPreviewLinkMenu(anchor, event);
+        void showPreviewLinkMenu(anchor, event);
       }
 
       function makeRequestId() {
@@ -15245,6 +16062,7 @@
             const html = await renderQuizMarkdownToHtml(markdown);
             if (nonce !== quizPreviewRenderNonce || !quizDialogEl || !quizDialogEl.contains(target)) return;
             target.innerHTML = html;
+            await hydrateStudioPreviewLocalMedia(target, getHtmlPreviewResourceContextOptions());
             await renderAnnotationMathInElement(target);
             decoratePdfEmbeds(target);
             await renderPdfPreviewsInElement(target);
@@ -16369,6 +17187,8 @@
         ensurePreviewSelectionActions(targetEl);
         updatePreviewCommentBlocksForElement(targetEl);
         decorateCopyablePreviewBlocks(targetEl);
+        clearWatchedPreviewRenderError();
+        scheduleWatchedPreviewReadingPositionRestore(targetEl, text);
         if (pane === "response") {
           applyPendingResponseScrollReset();
           scheduleResponsePaneRepaintNudge();
@@ -21242,7 +22062,11 @@
         } catch {}
       }
 
-      function setEditorLanguage(lang) {
+      function setEditorLanguage(lang, options) {
+        if (isWatchedFilePreview && !(options && options.allowWatchedFileUpdate === true)) {
+          setStatus("The watched preview language follows its file path.", "warning");
+          return false;
+        }
         editorLanguage = (lang && SUPPORTED_LANGUAGES.indexOf(lang) !== -1) ? lang : "markdown";
         persistEditorLanguage(editorLanguage);
         syncHighlightSelectUi();
@@ -21257,6 +22081,7 @@
         }
         updateOutlineUi();
         scheduleWorkspacePersistence();
+        return true;
       }
 
       function setEditorHighlightMode(mode) {
@@ -21558,11 +22383,90 @@
         return true;
       }
 
+      function handleWatchedFileUpdate(message) {
+        if (!isWatchedFilePreview || !message || typeof message.text !== "string") return;
+        const messagePath = String(message.path || "");
+        if (!watchedFilePreviewState.path || messagePath !== watchedFilePreviewState.path) return;
+        const generation = Math.max(0, Number(message.generation) || 0);
+        if (generation < watchedFilePreviewState.generation) return;
+
+        const expectedPreviewText = prepareEditorTextForPreview(message.text);
+        watchedFilePreviewReadingPositions.source = {
+          snapshot: captureWatchedPreviewReadingPosition(sourcePreviewEl),
+          text: expectedPreviewText,
+        };
+        watchedFilePreviewReadingPositions.response = {
+          snapshot: captureWatchedPreviewReadingPosition(critiqueViewEl),
+          text: expectedPreviewText,
+        };
+        const textareaMaxScroll = Math.max(0, Number(sourceTextEl.scrollHeight || 0) - Number(sourceTextEl.clientHeight || 0));
+        const textareaScrollRatio = textareaMaxScroll > 0 ? Number(sourceTextEl.scrollTop || 0) / textareaMaxScroll : 0;
+        const selectionStart = Math.max(0, Number(sourceTextEl.selectionStart) || 0);
+        const selectionEnd = Math.max(selectionStart, Number(sourceTextEl.selectionEnd) || selectionStart);
+
+        sourceTextEl.value = message.text;
+        const nextMaxScroll = Math.max(0, Number(sourceTextEl.scrollHeight || 0) - Number(sourceTextEl.clientHeight || 0));
+        sourceTextEl.scrollTop = Math.max(0, Math.min(nextMaxScroll, nextMaxScroll * textareaScrollRatio));
+        try {
+          sourceTextEl.setSelectionRange(
+            Math.min(selectionStart, message.text.length),
+            Math.min(selectionEnd, message.text.length),
+          );
+        } catch {
+          // Selection APIs are not guaranteed in every embedded browser.
+        }
+
+        watchedFilePreviewState.generation = generation;
+        watchedFilePreviewState.diskRevision = normalizeStudioDiskRevision(message.diskRevision) || watchedFilePreviewState.diskRevision;
+        watchedFilePreviewState.lastError = "";
+        fileBackedBaselineText = message.text;
+        fileBackedDiskRevision = watchedFilePreviewState.diskRevision || null;
+        editorLanguage = detectLanguageFromName(watchedFilePreviewState.path) || editorLanguage;
+        syncHighlightSelectUi();
+        scheduleEditorHighlightRender();
+        renderSourcePreview({ previewDelayMs: 0 });
+        renderActiveResult();
+        updateSourceBadge();
+        setStatus(message.message || "Watched preview updated from disk.", "success");
+      }
+
+      function handleWatchedFileError(message) {
+        if (!isWatchedFilePreview || !message) return;
+        const messagePath = String(message.path || "");
+        if (watchedFilePreviewState.path && messagePath && messagePath !== watchedFilePreviewState.path) return;
+        watchedFilePreviewState.lastError = String(message.message || "Could not refresh the watched file.");
+        updateSourceBadge();
+        setStatus(watchedFilePreviewState.lastError, "warning");
+      }
+
+      function handleWatchedFileReady(message) {
+        if (!isWatchedFilePreview || !message) return;
+        const messagePath = String(message.path || "");
+        if (watchedFilePreviewState.path && messagePath && messagePath !== watchedFilePreviewState.path) return;
+        watchedFilePreviewState.diskRevision = normalizeStudioDiskRevision(message.diskRevision) || watchedFilePreviewState.diskRevision;
+        watchedFilePreviewState.lastError = "";
+        updateSourceBadge();
+        setStatus(message.message || "Watching file for disk changes.", "success");
+      }
+
       function handleServerMessage(message) {
         if (!message || typeof message !== "object") return;
 
         debugTrace("server_message", summarizeServerMessage(message));
 
+        if (message.type === "watched_file_update") {
+          handleWatchedFileUpdate(message);
+          return;
+        }
+        if (message.type === "watched_file_error") {
+          handleWatchedFileError(message);
+          return;
+        }
+        if (message.type === "watched_file_ready") {
+          handleWatchedFileReady(message);
+          return;
+        }
+
         const contextChanged = applyContextUsageFromMessage(message);
         if (contextChanged) {
           updateFooterMeta();
@@ -21799,7 +22703,11 @@
             message.initialDocument &&
             typeof message.initialDocument.text === "string"
           ) {
-            setEditorText(message.initialDocument.text, { preserveScroll: false, preserveSelection: false });
+            setEditorText(message.initialDocument.text, {
+              preserveScroll: false,
+              preserveSelection: false,
+              allowWatchedFileUpdate: isWatchedFilePreview,
+            });
             initialDocumentApplied = true;
             loadedInitialDocument = true;
             setSourceState({
@@ -21811,7 +22719,7 @@
                 : (initialSourceState.draftId || null),
             });
             if (message.initialDocument.path) {
-              markFileBackedBaseline(message.initialDocument.text);
+              markFileBackedBaseline(message.initialDocument.text, message.initialDocument.diskRevision);
             }
             refreshResponseUi();
             if (typeof message.initialDocument.label === "string" && message.initialDocument.label.length > 0) {
@@ -22172,7 +23080,19 @@
           return;
         }
 
+        if (message.type === "save_conflict") {
+          void handleEditorSaveConflict(message);
+          return;
+        }
+
+        if (message.type === "save_as_conflict") {
+          void handleEditorSaveAsConflict(message);
+          return;
+        }
+
         if (message.type === "saved") {
+          const savedOperation = typeof message.requestId === "string" ? pendingSaveOperations.get(message.requestId) : null;
+          if (typeof message.requestId === "string") pendingSaveOperations.delete(message.requestId);
           if (typeof message.requestId === "string" && pendingRequestId === message.requestId) {
             pendingRequestId = null;
             pendingKind = null;
@@ -22191,7 +23111,7 @@
             }, {
               carryCurrentMetadataToNewDocument: true,
             });
-            markFileBackedBaseline(sourceTextEl.value);
+            markFileBackedBaseline(savedOperation && typeof savedOperation.content === "string" ? savedOperation.content : sourceTextEl.value, message.diskRevision);
           }
           setBusy(false);
           setWsState("Ready");
@@ -22211,6 +23131,10 @@
         }
 
         if (message.type === "editor_snapshot") {
+          if (isWatchedFilePreview) {
+            setStatus("Ignored editor snapshot because this preview follows its watched file on disk.", "warning");
+            return;
+          }
           if (typeof message.requestId === "string" && pendingRequestId && message.requestId !== pendingRequestId) {
             return;
           }
@@ -22234,6 +23158,10 @@
         }
 
         if (message.type === "studio_document") {
+          if (isWatchedFilePreview) {
+            setStatus("Ignored document replacement because this preview follows its watched file on disk.", "warning");
+            return;
+          }
           const nextDoc = message.document;
           if (!nextDoc || typeof nextDoc !== "object" || typeof nextDoc.text !== "string") {
             return;
@@ -22271,7 +23199,7 @@
             draftId: typeof nextDoc.draftId === "string" && nextDoc.draftId.trim() ? nextDoc.draftId.trim() : null,
           });
           if (nextPath) {
-            markFileBackedBaseline(nextDoc.text);
+            markFileBackedBaseline(nextDoc.text, nextDoc.diskRevision);
           }
           refreshResponseUi();
           setStatus(
@@ -22414,6 +23342,7 @@
 
         if (message.type === "busy") {
           if (typeof message.requestId === "string") {
+            pendingSaveOperations.delete(message.requestId);
             failPendingCompanionLaunch(message.requestId, "Studio could not start the companion editor because another request was busy.");
           }
           if (message.requestId && pendingRequestId === message.requestId) {
@@ -22435,6 +23364,7 @@
 
         if (message.type === "error") {
           if (typeof message.requestId === "string") {
+            pendingSaveOperations.delete(message.requestId);
             failPendingCompanionLaunch(message.requestId, "Studio could not prepare the companion editor. Return to the originating Studio page for details.");
           }
           if (message.requestId && pendingRequestId === message.requestId) {
@@ -22541,6 +23471,11 @@
         if (studioMode !== "full") {
           wsParams.set("mode", studioMode);
         }
+        if (isWatchedFilePreview && watchedFilePreviewState.path) {
+          wsParams.set("watchPath", watchedFilePreviewState.path);
+          const watchedDocId = initialQueryParams.get("docId") || "";
+          if (watchedDocId) wsParams.set("docId", watchedDocId);
+        }
         if (DEBUG_ENABLED) {
           wsParams.set("debug", "1");
         }
@@ -22591,6 +23526,14 @@
             return;
           }
 
+          if (kind === "watch_unauthorized") {
+            clearScheduledReconnect();
+            reconnectAttempt = 0;
+            setWsState("Disconnected");
+            setStatus("Watched preview authorization is unavailable. Reload this tab or open a new watched preview from Studio.", "warning");
+            return;
+          }
+
           if (kind === "shutdown") {
             clearScheduledReconnect();
             reconnectAttempt = 0;
@@ -22606,14 +23549,28 @@
         };
 
         socket.addEventListener("open", () => {
+          if (ws !== socket) {
+            try { socket.close(); } catch {}
+            return;
+          }
           window.clearTimeout(connectWatchdog);
           setWsState("Ready");
           setStatus(wasReconnect ? "Reconnected. Syncing…" : "Connected. Syncing…");
           sendMessage({ type: "hello" });
+          if (isWatchedFilePreview && watchedFilePreviewState.path) {
+            watchedFilePreviewState.generation = 0;
+            sendMessage({
+              type: "watch_file_subscribe",
+              path: watchedFilePreviewState.path,
+              revision: watchedFilePreviewState.diskRevision || undefined,
+            });
+            setStatus(wasReconnect ? "Reconnected. Resuming watched preview…" : "Connected. Starting watched preview…");
+          }
           reconnectAttempt = 0;
         });
 
         socket.addEventListener("message", (event) => {
+          if (ws !== socket) return;
           try {
             const message = JSON.parse(event.data);
             handleServerMessage(message);
@@ -22624,6 +23581,7 @@
         });
 
         socket.addEventListener("close", (event) => {
+          if (ws !== socket && !disconnectHandled) return;
           if (event && event.code === 4001) {
             handleDisconnect("invalidated", 4001);
             return;
@@ -22632,6 +23590,10 @@
             handleDisconnect("full_conflict", 4004);
             return;
           }
+          if (event && event.code === 4003) {
+            handleDisconnect("watch_unauthorized", 4003);
+            return;
+          }
           if (event && event.code === 1001) {
             handleDisconnect("shutdown", 1001);
             return;
@@ -22641,6 +23603,7 @@
         });
 
         socket.addEventListener("error", () => {
+          if (ws !== socket) return;
           handleDisconnect("error");
         });
       }
@@ -22869,6 +23832,25 @@
         });
       }
 
+      if (watchedOpenEditableBtn) {
+        watchedOpenEditableBtn.addEventListener("click", () => {
+          const path = watchedFilePreviewState.path;
+          if (!path) {
+            setStatus("This watched preview no longer has a file path.", "warning");
+            return;
+          }
+          try {
+            openFileBackedStudioEditorTab(path, {
+              label: sourceState && sourceState.label ? sourceState.label : basenameForStudioPath(path),
+              resourceDir: getCurrentResourceDirValue() || dirnameForDisplayPath(path),
+            });
+            setStatus("Opening watched file in a separate editable tab.");
+          } catch (error) {
+            setStatus(error && error.message ? error.message : String(error || "Could not open editable tab."), "warning");
+          }
+        });
+      }
+
       updatePaneFocusButtons();
       window.addEventListener("keydown", handlePaneShortcut);
       window.addEventListener("pagehide", () => {
@@ -23390,100 +24372,249 @@
         setFooterThemeMenuOpen(false);
       });
 
-      saveAsBtn.addEventListener("click", async () => {
-        const content = sourceTextEl.value;
-        if (!content.trim()) {
-          setStatus("Editor is empty. Nothing to save.", "warning");
-          return;
+      function abandonPendingSaveRequest(requestId) {
+        pendingSaveOperations.delete(requestId);
+        if (requestId) clearArmedTitleAttention(requestId);
+        if (pendingRequestId === requestId) {
+          pendingRequestId = null;
+          pendingKind = null;
         }
+        stickyStudioKind = null;
+        setBusy(false);
+        setWsState("Ready");
+      }
 
-        var suggestedName = sourceState.label ? stripImportedFileLabel(sourceState.label) : "draft.md";
-        var suggestedDir = getCurrentResourceDirValue() ? getCurrentResourceDirValue().replace(/\/$/, "") + "/" : "./";
-        const suggested = sourceState.path || (suggestedDir + suggestedName);
+      function sendEditorSaveAsRequest(path, content, overwrite, expectedRevision) {
+        const cleanPath = String(path || "").trim();
+        if (!cleanPath) {
+          setStatus("Save cancelled: path is required.", "warning");
+          return false;
+        }
+        const requestId = beginUiAction("save_as");
+        if (!requestId) return false;
+        const operation = {
+          kind: "save_as",
+          path: cleanPath,
+          content: String(content ?? ""),
+          overwrite: overwrite === true,
+          expectedRevision: normalizeStudioDiskRevision(expectedRevision),
+        };
+        pendingSaveOperations.set(requestId, operation);
+        if (!sendMessage({
+          type: "save_as_request",
+          requestId,
+          path: operation.path,
+          content: operation.content,
+          overwrite: operation.overwrite,
+          expectedRevision: operation.expectedRevision || undefined,
+        })) {
+          abandonPendingSaveRequest(requestId);
+          return false;
+        }
+        return true;
+      }
+
+      async function openEditorSaveAsDialog(options) {
+        if (uiBusy) return false;
+        const settings = options && typeof options === "object" ? options : {};
+        const resourceDir = getCurrentResourceDirValue();
+        const currentPath = getEffectiveSavePath();
+        const label = sourceState.label ? stripImportedFileLabel(sourceState.label) : "draft.md";
+        const suggested = typeof settings.suggestedPath === "string" && settings.suggestedPath.trim()
+          ? settings.suggestedPath.trim()
+          : (currentPath || (resourceDir ? resourceDir.replace(/\/$/, "") + "/" + label : "./draft.md"));
         const path = await requestStudioTextInput("Save editor content as:", suggested, {
           title: "Save editor as",
           confirmLabel: "Save",
+          inputLabel: "File path",
         });
-        if (!path) return;
-
-        const requestId = beginUiAction("save_as");
-        if (!requestId) return;
+        if (path === null) {
+          if (settings.reportCancellation === true) setStatus("Save As cancelled; editor changes were kept.", "warning");
+          return false;
+        }
+        const content = Object.prototype.hasOwnProperty.call(settings, "content")
+          ? String(settings.content ?? "")
+          : sourceTextEl.value;
+        return sendEditorSaveAsRequest(path, content, false);
+      }
 
-        const sent = sendMessage({
-          type: "save_as_request",
-          requestId,
+      function sendEditorSaveOverRequest(options) {
+        const settings = options && typeof options === "object" ? options : {};
+        const path = typeof settings.path === "string" && settings.path.trim()
+          ? settings.path.trim()
+          : (sourceState && sourceState.path ? sourceState.path : "");
+        if (!path) {
+          setStatus("Save editor requires a file-backed document. Use Save editor as… for a new file.", "warning");
+          return false;
+        }
+        const requestId = beginUiAction("save_over");
+        if (!requestId) return false;
+        const operation = {
+          kind: "save_over",
           path,
-          content,
-        });
+          content: Object.prototype.hasOwnProperty.call(settings, "content")
+            ? String(settings.content ?? "")
+            : sourceTextEl.value,
+          expectedRevision: Object.prototype.hasOwnProperty.call(settings, "expectedRevision")
+            ? normalizeStudioDiskRevision(settings.expectedRevision)
+            : fileBackedDiskRevision,
+          force: settings.force === true,
+        };
+        pendingSaveOperations.set(requestId, operation);
+        if (!sendMessage({
+          type: "save_over_request",
+          requestId,
+          path: operation.path,
+          content: operation.content,
+          expectedRevision: operation.expectedRevision || undefined,
+          force: operation.force,
+        })) {
+          abandonPendingSaveRequest(requestId);
+          return false;
+        }
+        return true;
+      }
 
-        if (!sent) {
+      async function requestEditorRefreshFromDisk(options) {
+        const settings = options && typeof options === "object" ? options : {};
+        if (uiBusy) return false;
+        const path = typeof settings.path === "string" && settings.path.trim()
+          ? settings.path.trim()
+          : (sourceState && sourceState.path ? sourceState.path : "");
+        if (!path) {
+          setStatus("Refresh from disk requires a file-backed editor. Open one from Files or use /studio-editor-only <path>.", "warning");
+          return false;
+        }
+        if (settings.skipConfirm !== true && editorDiffersFromFileBackedBaseline()) {
+          const confirmed = await requestStudioConfirmation(
+            "Replace the current editor contents with the latest version from disk? Unsaved editor changes will be lost.\n\n" + path,
+            { title: "Refresh from disk?", confirmLabel: "Replace", destructive: true },
+          );
+          if (!confirmed) return false;
+        }
+        const requestId = beginUiAction("refresh_from_disk");
+        if (!requestId) return false;
+        if (!sendMessage({ type: "refresh_from_disk_request", requestId, path })) {
           pendingRequestId = null;
           pendingKind = null;
+          stickyStudioKind = null;
           setBusy(false);
+          setWsState("Ready");
+          return false;
         }
-      });
-
-      saveOverBtn.addEventListener("click", async () => {
-        var effectivePath = getEffectiveSavePath();
-        if (!effectivePath) {
-          setStatus("Save editor requires a file path. Open via /studio <path>, set a working dir, or use Save editor as…", "warning");
-          return;
-        }
+        return true;
+      }
 
-        const confirmed = await requestStudioConfirmation("Overwrite " + effectivePath + "?", {
-          title: "Overwrite file?",
+      async function handleEditorSaveConflict(message) {
+        const requestId = typeof message.requestId === "string" ? message.requestId : "";
+        const operation = pendingSaveOperations.get(requestId) || {
+          kind: "save_over",
+          path: typeof message.path === "string" ? message.path : (sourceState.path || ""),
+          content: sourceTextEl.value,
+          expectedRevision: fileBackedDiskRevision,
+          force: false,
+        };
+        abandonPendingSaveRequest(requestId);
+        const conflictPath = typeof message.path === "string" && message.path.trim() ? message.path.trim() : operation.path;
+        const canOverwrite = message.canOverwrite !== false;
+        const detail = (typeof message.message === "string" && message.message.trim()
+          ? message.message.trim()
+          : "The file changed on disk after Studio loaded it.")
+          + "\n\n" + conflictPath
+          + "\n\nReload replaces the editor with disk content. Save As keeps both versions."
+          + (canOverwrite ? " Overwrite replaces the reported disk revision with the current editor text." : " Overwrite is unavailable for this file location; use Save As to preserve link and path safety.");
+        setStatus("Save paused because the file changed on disk.", "warning");
+        const decision = await openStudioDecision({
+          mode: "confirm",
+          title: "File changed on disk",
+          message: detail,
+          cancelLabel: "Cancel",
+          tertiaryLabel: "Reload",
+          tertiaryValue: "reload",
+          secondaryLabel: "Save As…",
+          secondaryValue: "save-as",
           confirmLabel: "Overwrite",
+          confirmDisabled: !canOverwrite,
           destructive: true,
         });
-        if (!confirmed) return;
-
-        const requestId = beginUiAction("save_over");
-        if (!requestId) return;
+        if (decision === "reload") {
+          await requestEditorRefreshFromDisk({ path: conflictPath, skipConfirm: true });
+          return;
+        }
+        if (decision === "save-as") {
+          await openEditorSaveAsDialog({ content: operation.content, suggestedPath: conflictPath, reportCancellation: true });
+          return;
+        }
+        if (decision === true && canOverwrite) {
+          sendEditorSaveOverRequest({
+            path: conflictPath,
+            content: operation.content,
+            expectedRevision: message.currentRevision,
+            force: true,
+          });
+          return;
+        }
+        setStatus("Save cancelled; editor changes were kept.", "warning");
+      }
 
-        // Use save_as with the effective path for both file-backed and derived paths
-        const sent = sendMessage({
-          type: "save_as_request",
-          requestId,
-          path: effectivePath,
+      async function handleEditorSaveAsConflict(message) {
+        const requestId = typeof message.requestId === "string" ? message.requestId : "";
+        const operation = pendingSaveOperations.get(requestId) || {
+          kind: "save_as",
+          path: typeof message.path === "string" ? message.path : "",
           content: sourceTextEl.value,
+          overwrite: false,
+          expectedRevision: null,
+        };
+        abandonPendingSaveRequest(requestId);
+        const conflictPath = typeof message.path === "string" && message.path.trim() ? message.path.trim() : operation.path;
+        const targetExists = Boolean(normalizeStudioDiskRevision(message.currentRevision));
+        const unsafeReplacement = message.reason === "location-changed" || message.reason === "hard-linked-file";
+        const canCommitHere = !unsafeReplacement;
+        setStatus(unsafeReplacement
+          ? "Save As cannot replace this target safely; choose another path."
+          : (targetExists
+            ? "Save As paused because the target already exists."
+            : "Save As paused because the target changed while confirmation was open."), "warning");
+        const decision = await openStudioDecision({
+          mode: "confirm",
+          title: unsafeReplacement ? "Cannot replace existing file" : (targetExists ? "Replace existing file?" : "Create file at this path?"),
+          message: (typeof message.message === "string" && message.message.trim()
+            ? message.message.trim()
+            : (targetExists ? "A file already exists at this location." : "The previous replacement target is no longer present."))
+            + (unsafeReplacement
+              ? "\n\nStudio will not replace a symlink, moved path, or hard-linked file. Choose another location instead."
+              : (targetExists ? "\n\nReplacing it cannot be undone." : "\n\nCreating it will keep the current editor text at this path.")),
+          cancelLabel: "Cancel",
+          secondaryLabel: "Choose another…",
+          secondaryValue: "choose-another",
+          confirmLabel: targetExists ? "Replace" : "Create",
+          confirmDisabled: !canCommitHere,
+          destructive: targetExists,
         });
-
-        if (!sent) {
-          pendingRequestId = null;
-          pendingKind = null;
-          setBusy(false);
+        if (decision === "choose-another") {
+          await openEditorSaveAsDialog({ content: operation.content, suggestedPath: conflictPath, reportCancellation: true });
+          return;
         }
-      });
-
-      if (refreshFromDiskBtn) {
-        refreshFromDiskBtn.addEventListener("click", async () => {
-          if (!hasRefreshableFilePath()) {
-            setStatus("Refresh from disk needs a file path. Use Files → Open here, Files → Open file tab, or /studio-editor-only <path> for a refreshable editor tab.", "warning");
-            return;
-          }
-
-          if (editorDiffersFromFileBackedBaseline()) {
-            const confirmed = await requestStudioConfirmation(
-              "Replace current editor contents with the latest version from disk?",
-              { title: "Refresh from disk?", confirmLabel: "Replace", destructive: true },
-            );
-            if (!confirmed) return;
-          }
+        if (decision === true && canCommitHere) {
+          sendEditorSaveAsRequest(conflictPath, operation.content, true, message.currentRevision);
+          return;
+        }
+        setStatus("Save As cancelled; editor changes were kept.", "warning");
+      }
 
-          const requestId = beginUiAction("refresh_from_disk");
-          if (!requestId) return;
+      saveAsBtn.addEventListener("click", () => {
+        void openEditorSaveAsDialog();
+      });
 
-          const sent = sendMessage({
-            type: "refresh_from_disk_request",
-            requestId,
-            path: sourceState.path,
-          });
+      saveOverBtn.addEventListener("click", () => {
+        if (uiBusy) return;
+        sendEditorSaveOverRequest();
+      });
 
-          if (!sent) {
-            pendingRequestId = null;
-            pendingKind = null;
-            setBusy(false);
-          }
+      if (refreshFromDiskBtn) {
+        refreshFromDiskBtn.addEventListener("click", () => {
+          void requestEditorRefreshFromDisk();
         });
       }
 
@@ -24217,7 +25348,16 @@
         resourceDirInput.value = normalizeStudioResourceDirValue(initialResourceDir);
       }
       setSourceState(initialSourceState);
-      if (initialSourceState.path) markFileBackedBaseline(sourceTextEl.value);
+      if (initialSourceState.path) markFileBackedBaseline(sourceTextEl.value, initialDiskRevision);
+      if (isWatchedFilePreview) {
+        sourceTextEl.readOnly = true;
+        sourceTextEl.setAttribute("aria-readonly", "true");
+        sourceTextEl.title = "Read-only disk-backed source. Open a file tab to edit and save safely.";
+        editorView = "markdown";
+        rightView = "editor-preview";
+        followLatest = false;
+        if (document.body && document.body.classList) document.body.classList.add("watched-file-preview");
+      }
       refreshResponseUi();
       updateAnnotatedReplyHeaderButton();
       setActivePane(initialPaneFocusTarget === "off" ? "left" : initialPaneFocusTarget);
@@ -24230,7 +25370,9 @@
 
       const initialDetectedLang = detectLanguageFromName(initialSourceState.path || initialSourceState.label || "");
       const storedLang = readStoredEditorLanguage();
-      setEditorLanguage(initialDetectedLang || storedLang || "markdown");
+      setEditorLanguage(initialDetectedLang || storedLang || "markdown", {
+        allowWatchedFileUpdate: isWatchedFilePreview,
+      });
 
       const storedLineNumbersEnabled = readStoredEditorLineNumbersEnabled();
       const initialLineNumbersEnabled = storedLineNumbersEnabled ?? Boolean(lineNumbersSelect && lineNumbersSelect.value === "on");