pi-studio 0.9.52 → 0.9.53

package/client/studio-client.js

@@ -242,6 +242,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.");
@@ -402,8 +403,8 @@
           option.disabled = (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.";
+          ? "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 +479,7 @@
       let sideQuestionAvailablePiTools = [];
       let sideQuestionPreviewRenderNonce = 0;
       let sideQuestionContextRefreshHandle = null;
+      let sideQuestionContextGrantPending = false;
       let sideQuestionMarkdownExportRequest = null;
       const sideQuestionMarkdownRenderCache = new Map();
       let sideQuestionUi = {
@@ -2293,6 +2295,9 @@
         relativeDir: "",
         parentDir: null,
         entries: [],
+        exactFiles: [],
+        locations: [],
+        grantRequiredPath: "",
         omitted: 0,
         omittedIgnored: 0,
         sort: fileBrowserSortMode,
@@ -3894,8 +3899,12 @@
         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") {
@@ -3990,6 +3999,8 @@
             resolve,
             returnFocusEl,
             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"
@@ -4821,6 +4832,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
@@ -6041,7 +6062,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 +6095,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 +6546,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 +6585,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 +6697,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 +6714,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,6 +7119,7 @@
           mathRenderItemCount: 0,
           resourceResolveBatchCount: 0,
           resourceResolveItemCount: 0,
+          blockedResources: new Map(),
         });
 
         targetEl.appendChild(shell);
@@ -7927,6 +8006,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 +8486,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 +8695,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,6 +9277,91 @@
         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.querySelector(".preview-loading")) return false;
@@ -10451,6 +10668,33 @@
         });
       }
 
+      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");
+            },
+          },
+        );
+      }
+
       async function applyRenderedMarkdown(targetEl, markdown, pane, nonce) {
         const previewPrepared = annotationsEnabled
           ? prepareMarkdownForPandocPreview(markdown)
@@ -10477,15 +10721,8 @@
           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);
+          await hydrateStudioPreviewLocalMedia(targetEl, previewResourceContext);
+          await renderStudioPdfBlocksInElement(targetEl, pdfPrepared.blocks, previewingEditorText);
           applyPreviewAnnotationPlaceholdersToElement(targetEl, previewPrepared.placeholders);
           await renderAnnotationMathInElement(targetEl);
           decoratePdfEmbeds(targetEl);
@@ -11355,71 +11592,92 @@
         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 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'>"
+          + 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 +11692,9 @@
             relativeDir: "",
             parentDir: null,
             entries: [],
+            exactFiles: [],
+            locations: [],
+            grantRequiredPath: "",
             omitted: 0,
             omittedIgnored: 0,
             sort: fileBrowserSortMode,
@@ -11455,12 +11716,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 +11735,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 +11748,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 +11764,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,
@@ -11546,7 +11823,7 @@
           return;
         }
         if (kind === "pdf") {
-          openPreviewPdfLink(path, path, context);
+          await openPreviewPdfLink(path, path, context);
           return;
         }
         if (kind === "image") {
@@ -11556,6 +11833,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 +11882,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 +11895,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 +11921,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,14 +11942,6 @@
             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;
           }
@@ -12345,6 +12655,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 +12706,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 +12773,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 +12784,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 +12855,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 +12875,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 +13015,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 +13068,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 +13082,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) {
@@ -14538,6 +14901,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 +14984,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 +15020,7 @@
       ]);
       let previewLinkMenuEl = null;
       let activePreviewLinkContext = null;
+      let previewLinkMenuRequestId = 0;
 
       function stripPreviewLocalLinkUrlSuffix(href) {
         const raw = String(href || "").trim();
@@ -14715,7 +15087,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,19 +15157,35 @@
         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");
@@ -14814,7 +15202,7 @@
         }
         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 +15210,102 @@
         return true;
       }
 
-      async function fetchPreviewLocalLink(action, href, contextOverride) {
-        return fetchStudioJson("/local-preview-link", {
+      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 = () => fetchStudioJson("/local-preview-link", {
           query: { ...getPreviewLinkResourceQuery(href, contextOverride), action },
         });
+        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 +15316,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 +15334,7 @@
       }
 
       async function openPreviewImageLink(href, title, contextOverride) {
+        await fetchPreviewLocalLink("resolve", href, contextOverride);
         const payload = await fetchStudioJson("/html-preview-resource", {
           query: getPreviewLinkResourceQuery(href, contextOverride),
         });
@@ -14955,7 +15436,11 @@
           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;
         }
       }
@@ -14970,7 +15455,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 +15474,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 +15488,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;
           }
@@ -15043,7 +15534,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 +15546,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 +15557,7 @@
         if (!anchor) return;
         event.preventDefault();
         event.stopPropagation();
-        showPreviewLinkMenu(anchor, event);
+        void showPreviewLinkMenu(anchor, event);
       }
 
       function makeRequestId() {
@@ -15245,6 +15736,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);