pi-studio 0.9.48 → 0.9.49

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.9.49] — 2026-08-24
+
+### Added
+- Open local PDFs directly with `/studio <path.pdf>` or `/studio-editor-only <path.pdf>` in a read-only, right-focused companion preview, including optional `#page=N` hints and the existing PDF viewer actions without replacing an open full Studio workspace.
+- Add opt-in PDF auto-refresh through `/studio --watch <path.pdf>`, `watch: true` preview blocks, and synchronized card/focus-viewer toggles; Studio checks only visible tabs, waits for a changed file to stabilize, and retains **Cmd/Ctrl+Alt+R** as a manual refresh shortcut.
+
+### Changed
+- Show active PDF auto-refresh controls as plain accent text, matching Studio's current active-tool treatment instead of using a filled toggle pill.
+
 ## [0.9.48] — 2026-08-21
 
 ### Added

package/README.md

@@ -54,7 +54,7 @@ _The video shows an earlier version of the Studio interface. The basic workflow
 - Renders Markdown/LaTeX/code previews (math + Mermaid) plus lightweight CSV/TSV table previews, theme-synced with pi, with copy buttons for code blocks and blockquotes; Mermaid previews include Lucide/Logos icon nodes and accessible label contrast over custom fills
 - Adds a contextual **Editor (Quarto Preview)** right-pane view for file-backed `.qmd`, `.md`, and `.markdown` documents. Studio checks Quarto and the document/project configuration before showing an explicit start action, launches a single loopback `quarto preview` process with `--no-execute`, embeds Quarto's authoritative saved-file output without restyling it, and provides open-in-browser, restart, stop, logs, and unsaved-editor warnings. If Quarto is missing, the view remains available with an actionable dependency message.
 - Renders straight, unfenced interactive HTML in preview via a sandboxed browser iframe with zoom controls, while fenced `html` blocks remain source code
-- Embeds local PDFs in Studio Markdown previews via explicit `studio-pdf` fenced blocks, with Focus, browser-tab, system-viewer, and show-in-folder actions
+- Embeds local PDFs in Studio Markdown previews via explicit `studio-pdf` fenced blocks and opens existing PDFs directly with `/studio <path.pdf>`, with Focus, browser-tab, system-viewer, show-in-folder, manual refresh, and opt-in stable-file auto-refresh actions
 - Ships optional `pi-studio-dark` and `pi-studio-light` themes tuned for Studio's browser workspace
 - Exports right-pane preview as PDF (pandoc + LaTeX) or standalone HTML into the source file directory, Studio working directory, or Pi session directory; PDF export can open in a Studio preview tab or the default PDF viewer, and HTML export can open in the default browser or in a new Studio editor tab for inspection/commenting, while preserving authored HTML previews as HTML and rendering CSV/TSV editor previews as tables
 - Exports local files headlessly via `/studio-pdf <path>` to `<name>.studio.pdf` or `/studio-html <path>` to `<name>.studio.html`; without a path, those commands export the last model response to a timestamped file. Agent tools `studio_export_pdf` and `studio_export_html` expose the same export pipeline for remote/Telegram-style sessions.
@@ -65,7 +65,8 @@ _The video shows an earlier version of the Studio interface. The basic workflow
 | Command | Description |
 |---|---|
 | `/studio` | Open in Muxy or cmux when available, otherwise the system browser, with the last assistant response (fallback: blank) |
-| `/studio <path>` | Open with file preloaded |
+| `/studio <path>` | Open a text file in the editor, or a PDF in a read-only companion preview tab |
+| `/studio --watch <pdf>` | Open a local PDF with stable-file auto-refresh enabled |
 | `/studio --last` | Force last response |
 | `/studio --blank` | Force blank editor |
 | `/studio --no-browser` | Start/print the Studio URL without opening a browser, useful for forwarded or phone/browser sessions |
@@ -74,7 +75,7 @@ _The video shows an earlier version of the Studio interface. The basic workflow
 | `/studio --stop` | Stop studio server |
 | `/studio --help` | Show help |
 | `/studio-replace [path\|--blank\|--last]` | Replace the current full Studio view with a new full Studio view |
-| `/studio-editor-only [path\|--blank\|--last]` | Open an editor-only Studio view; multiple editor-only views may be open at once |
+| `/studio-editor-only [path\|--blank\|--last]` | Open an editor-only view, or a read-only PDF preview; multiple companion views may be open at once |
 | `/studio-current <path>` | Load a file into currently open Studio tab(s) without opening a new browser window |
 | `/studio-pdf [path] [options]` | Export a local file, or the last model response when no path is given, via the Studio PDF pipeline |
 | `/studio-html [path]` | Export a local file, or the last model response when no path is given, to standalone HTML via the Studio preview pipeline |
@@ -118,11 +119,14 @@ path: attachments/paper.pdf
 title: Optional title
 page: 3
 height: 760
+watch: true
 caption: Optional caption
 ```
 ````
 
-`path` must point to a local `.pdf` within the current Studio resource directory. Relative paths resolve from the opened document's directory, or from Studio's working dir for non-file-backed content. `page` is an initial page hint for the browser PDF viewer, and `height` controls the embedded frame height in pixels. Use normal Markdown links for PDFs when embedding is not useful.
+`path` must point to a local `.pdf` within the current Studio resource directory. Relative paths resolve from the opened document's directory, or from Studio's working dir for non-file-backed content. `page` is an initial page hint for the browser PDF viewer, `height` controls the embedded frame height in pixels, and `watch: true` enables auto-refresh after Studio observes the changed file in a stable state. Use normal Markdown links for PDFs when embedding is not useful.
+
+To view an existing PDF directly, run `/studio report.pdf` (or `/studio "path with spaces/report.pdf"`). The PDF opens read-only in a focused companion preview, even when the full Studio workspace is already open. A `#page=N` suffix selects the initial page. Auto-refresh is off by default; use `/studio --watch report.pdf` to start with it on, or toggle **Auto-refresh** in the PDF card or focused viewer. Studio checks only while the tab is visible and waits for two matching file-version observations before reloading, which avoids reading a PDF while LaTeX is still writing it. **Cmd/Ctrl+Alt+R** manually refreshes the focused or visible PDF. This is distinct from `/studio-pdf`, which exports Markdown, LaTeX, code, or the last response to a new PDF.
 
 ### Mermaid icons
 

package/client/studio-client.js

@@ -227,7 +227,10 @@
       if (
         !previewResourceHelpers
         || typeof previewResourceHelpers.areStudioPreviewResourceContextsEqual !== "function"
+        || typeof previewResourceHelpers.buildStudioPdfVersionSignature !== "function"
+        || typeof previewResourceHelpers.createStudioPdfVersionObservationState !== "function"
         || typeof previewResourceHelpers.hydrateStudioPreviewLocalImages !== "function"
+        || typeof previewResourceHelpers.observeStudioPdfVersion !== "function"
       ) {
         throw new Error("Studio preview resource helpers failed to load.");
       }
@@ -271,11 +274,17 @@
       let studioPdfFocusOpenLinkEl = null;
       let studioPdfFocusSystemViewerBtn = null;
       let studioPdfFocusRevealBtn = null;
+      let studioPdfFocusAutoRefreshBtn = null;
       let studioPdfFocusFullscreenBtn = null;
       let studioPdfFocusCloseBtn = null;
       let studioPdfFocusLastFocusedEl = null;
       let studioPdfFocusMovedFrameState = null;
       let studioPdfFocusResourceQuery = null;
+      let studioPdfFocusSourceCard = null;
+      let studioPdfFocusStandaloneAutoRefreshState = null;
+      const studioPdfCardAutoRefreshStates = new WeakMap();
+      const STUDIO_PDF_AUTO_REFRESH_INTERVAL_MS = 1_000;
+      const STUDIO_PDF_AUTO_REFRESH_STABLE_OBSERVATIONS = 2;
       let studioHtmlFocusOverlayEl = null;
       let studioHtmlFocusShellEl = null;
       let studioHtmlFocusFullscreenBtn = null;
@@ -4489,6 +4498,15 @@
 
         if (handleStudioImageFocusShortcut(event)) return;
 
+        const otherModalOwnsEvent = scratchpadOwnsEvent
+          || reviewNotesOwnsEvent
+          || outlineOwnsEvent
+          || shortcutsOwnsEvent
+          || htmlFocusOwnsEvent
+          || imageFocusOwnsEvent
+          || quizOwnsEvent;
+        if (!otherModalOwnsEvent && handleStudioPdfRefreshShortcut(event)) return;
+
         if (isScratchpadOpen() && plainEscape) {
           event.preventDefault();
           closeScratchpad();
@@ -6851,7 +6869,7 @@
       }
 
       function parseStudioPdfBlockOptions(body) {
-        const options = { path: "", title: "", caption: "", page: "", height: "" };
+        const options = { path: "", title: "", caption: "", page: "", height: "", watch: "" };
         String(body || "").split(/\r?\n/).forEach((line) => {
           const raw = String(line || "").trim();
           if (!raw || raw.startsWith("#")) return;
@@ -6864,6 +6882,7 @@
             else if (key === "caption") options.caption = value;
             else if (key === "page") options.page = value;
             else if (key === "height") options.height = value;
+            else if (key === "watch" || key === "auto-refresh" || key === "autorefresh") options.watch = value;
             return;
           }
           if (!options.path) options.path = stripMatchingQuotes(raw);
@@ -6895,6 +6914,10 @@
         return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
       }
 
+      function normalizeStudioPdfAutoRefresh(value) {
+        return /^(?:1|true|yes|on|watch)$/i.test(String(value || "").trim());
+      }
+
       function isStudioPdfFocusOpen() {
         return Boolean(studioPdfFocusOverlayEl && studioPdfFocusOverlayEl.hidden === false);
       }
@@ -6969,11 +6992,21 @@
         refreshBtn.type = "button";
         refreshBtn.className = "studio-pdf-focus-btn studio-pdf-focus-refresh";
         refreshBtn.textContent = "Refresh";
-        refreshBtn.title = "Reload this PDF preview from disk.";
+        refreshBtn.title = "Reload this PDF preview from disk. Shortcut: Cmd/Ctrl+Alt+R.";
         refreshBtn.setAttribute("aria-label", "Refresh PDF preview from disk");
         refreshBtn.addEventListener("click", () => refreshStudioPdfFocusViewer());
         actions.appendChild(refreshBtn);
 
+        const autoRefreshBtn = document.createElement("button");
+        autoRefreshBtn.type = "button";
+        autoRefreshBtn.className = "studio-pdf-focus-btn studio-pdf-focus-auto-refresh";
+        autoRefreshBtn.textContent = "Auto-refresh";
+        autoRefreshBtn.title = "Watch this local PDF and reload it after a changed file is stable on disk.";
+        autoRefreshBtn.setAttribute("aria-label", "Enable PDF auto-refresh");
+        autoRefreshBtn.setAttribute("aria-pressed", "false");
+        autoRefreshBtn.addEventListener("click", () => toggleStudioPdfFocusAutoRefresh());
+        actions.appendChild(autoRefreshBtn);
+
         const fullscreenBtn = document.createElement("button");
         fullscreenBtn.type = "button";
         fullscreenBtn.className = "studio-pdf-focus-btn studio-pdf-focus-fullscreen";
@@ -7030,6 +7063,7 @@
         studioPdfFocusOpenLinkEl = openLink;
         studioPdfFocusSystemViewerBtn = systemViewerBtn;
         studioPdfFocusRevealBtn = revealBtn;
+        studioPdfFocusAutoRefreshBtn = autoRefreshBtn;
         studioPdfFocusFullscreenBtn = fullscreenBtn;
         studioPdfFocusCloseBtn = closeBtn;
         syncStudioPdfFocusFullscreenButton();
@@ -7037,11 +7071,12 @@
         return overlay;
       }
 
-      function openStudioPdfFocusViewer(viewerUrl, title, sourceFrame, resourceQuery) {
+      function openStudioPdfFocusViewer(viewerUrl, title, sourceFrame, resourceQuery, sourceCard) {
         const src = String(viewerUrl || "").trim();
         if (!src) return;
         ensureStudioPdfFocusViewer();
         studioPdfFocusResourceQuery = normalizeStudioPdfResourceQuery(resourceQuery);
+        setStudioPdfFocusAutoRefreshSource(sourceCard, studioPdfFocusResourceQuery);
         syncStudioPdfFocusResourceActions();
         studioPdfFocusLastFocusedEl = document.activeElement instanceof HTMLElement ? document.activeElement : null;
         if (studioPdfFocusTitleEl) studioPdfFocusTitleEl.textContent = String(title || "PDF preview").trim() || "PDF preview";
@@ -7071,6 +7106,7 @@
         restoreStudioPdfFocusMovedFrame();
         if (studioPdfFocusFrameEl) studioPdfFocusFrameEl.src = "about:blank";
         if (document.body) document.body.classList.remove("studio-pdf-focus-open");
+        clearStudioPdfFocusAutoRefreshSource();
         studioPdfFocusResourceQuery = null;
         syncStudioPdfFocusResourceActions();
         syncStudioPdfFocusFullscreenButton();
@@ -7113,6 +7149,214 @@
         return query;
       }
 
+      function syncStudioPdfAutoRefreshButton(button, enabled, available) {
+        if (!button) return;
+        const active = Boolean(enabled && available);
+        button.disabled = !available;
+        button.setAttribute("aria-pressed", active ? "true" : "false");
+        button.setAttribute("aria-label", active ? "Disable PDF auto-refresh" : "Enable PDF auto-refresh");
+        button.textContent = "Auto-refresh";
+        button.title = active
+          ? "Auto-refresh is on. Studio checks this PDF while the tab is visible and reloads it after a changed file is stable on disk."
+          : "Watch this local PDF and reload it after a changed file is stable on disk.";
+      }
+
+      function createStudioPdfAutoRefreshState(resourceQuery, hooks) {
+        return {
+          resourceQuery: normalizeStudioPdfResourceQuery(resourceQuery),
+          enabled: false,
+          timer: null,
+          inFlight: false,
+          generation: 0,
+          observation: previewResourceHelpers.createStudioPdfVersionObservationState(),
+          isAlive: hooks && typeof hooks.isAlive === "function" ? hooks.isAlive : () => false,
+          refresh: hooks && typeof hooks.refresh === "function" ? hooks.refresh : () => false,
+          sync: hooks && typeof hooks.sync === "function" ? hooks.sync : () => {},
+        };
+      }
+
+      function resetStudioPdfAutoRefreshObservation(state) {
+        if (!state) return;
+        state.observation = previewResourceHelpers.createStudioPdfVersionObservationState();
+      }
+
+      function scheduleStudioPdfAutoRefreshPoll(state, delayMs) {
+        if (!state || !state.enabled) return;
+        if (state.timer) window.clearTimeout(state.timer);
+        state.timer = window.setTimeout(() => {
+          state.timer = null;
+          void pollStudioPdfAutoRefreshState(state);
+        }, Math.max(0, Number(delayMs) || 0));
+      }
+
+      function stopStudioPdfAutoRefreshState(state) {
+        if (!state) return;
+        state.enabled = false;
+        state.inFlight = false;
+        state.generation += 1;
+        if (state.timer) window.clearTimeout(state.timer);
+        state.timer = null;
+        resetStudioPdfAutoRefreshObservation(state);
+        state.sync();
+      }
+
+      function setStudioPdfAutoRefreshEnabled(state, enabled, options) {
+        if (!state) return false;
+        const nextEnabled = Boolean(enabled && state.resourceQuery);
+        if (state.enabled === nextEnabled) {
+          state.sync();
+          return nextEnabled;
+        }
+        if (state.timer) window.clearTimeout(state.timer);
+        state.timer = null;
+        state.enabled = nextEnabled;
+        state.inFlight = false;
+        state.generation += 1;
+        resetStudioPdfAutoRefreshObservation(state);
+        state.sync();
+        if (nextEnabled) {
+          if (!options || !options.silent) state.refresh();
+          scheduleStudioPdfAutoRefreshPoll(state, 0);
+        }
+        if (!options || !options.silent) {
+          setStatus(nextEnabled ? "PDF auto-refresh on." : "PDF auto-refresh off.", "success");
+        }
+        return nextEnabled;
+      }
+
+      async function fetchStudioPdfVersionSignature(resourceQuery) {
+        const url = buildStudioPdfResourceUrl(resourceQuery, false);
+        if (!url) throw new Error("Could not resolve this PDF for auto-refresh.");
+        const response = await fetchWithTimeout(url, {
+          method: "HEAD",
+          cache: "no-store",
+        }, 4_000, "PDF auto-refresh check");
+        if (!response.ok) throw new Error("PDF auto-refresh check failed with HTTP " + response.status + ".");
+        return previewResourceHelpers.buildStudioPdfVersionSignature(response.headers);
+      }
+
+      async function pollStudioPdfAutoRefreshState(state) {
+        if (!state || !state.enabled || state.inFlight) return;
+        if (!state.isAlive()) {
+          stopStudioPdfAutoRefreshState(state);
+          return;
+        }
+        if (document.hidden || document.visibilityState === "hidden") {
+          scheduleStudioPdfAutoRefreshPoll(state, STUDIO_PDF_AUTO_REFRESH_INTERVAL_MS);
+          return;
+        }
+        const generation = state.generation;
+        state.inFlight = true;
+        try {
+          const signature = await fetchStudioPdfVersionSignature(state.resourceQuery);
+          if (!state.enabled || state.generation !== generation) return;
+          if (document.hidden || document.visibilityState === "hidden") return;
+          if (!state.isAlive()) {
+            stopStudioPdfAutoRefreshState(state);
+            return;
+          }
+          const observed = previewResourceHelpers.observeStudioPdfVersion(
+            state.observation,
+            signature,
+            STUDIO_PDF_AUTO_REFRESH_STABLE_OBSERVATIONS,
+          );
+          state.observation = observed.state;
+          if (observed.changed) state.refresh();
+        } catch {
+          // LaTeX tools may briefly replace or lock the output PDF. Retry quietly.
+        } finally {
+          if (state.generation !== generation) return;
+          state.inFlight = false;
+          if (state.enabled) scheduleStudioPdfAutoRefreshPoll(state, STUDIO_PDF_AUTO_REFRESH_INTERVAL_MS);
+        }
+      }
+
+      function syncStudioPdfCardAutoRefreshButton(card) {
+        if (!card) return;
+        const state = studioPdfCardAutoRefreshStates.get(card) || null;
+        const button = typeof card.querySelector === "function" ? card.querySelector(".studio-pdf-card-auto-refresh") : null;
+        syncStudioPdfAutoRefreshButton(button, state && state.enabled, Boolean(state && state.resourceQuery));
+      }
+
+      function ensureStudioPdfCardAutoRefreshState(card, resourceQuery) {
+        if (!card) return null;
+        let state = studioPdfCardAutoRefreshStates.get(card) || null;
+        if (state) return state;
+        state = createStudioPdfAutoRefreshState(resourceQuery, {
+          isAlive: () => Boolean(card.isConnected || (isStudioPdfFocusOpen() && studioPdfFocusSourceCard === card)),
+          refresh: () => {
+            if (isStudioPdfFocusOpen() && studioPdfFocusSourceCard === card) {
+              return refreshStudioPdfFocusViewer({ automatic: true });
+            }
+            return refreshStudioPdfCard(card, { automatic: true });
+          },
+          sync: () => {
+            syncStudioPdfCardAutoRefreshButton(card);
+            if (studioPdfFocusSourceCard === card) syncStudioPdfFocusAutoRefreshButton();
+          },
+        });
+        studioPdfCardAutoRefreshStates.set(card, state);
+        syncStudioPdfCardAutoRefreshButton(card);
+        return state;
+      }
+
+      function setStudioPdfCardAutoRefresh(card, enabled, options) {
+        const state = studioPdfCardAutoRefreshStates.get(card) || null;
+        return setStudioPdfAutoRefreshEnabled(state, enabled, options);
+      }
+
+      function getStudioPdfFocusAutoRefreshState() {
+        if (studioPdfFocusSourceCard) return studioPdfCardAutoRefreshStates.get(studioPdfFocusSourceCard) || null;
+        return studioPdfFocusStandaloneAutoRefreshState;
+      }
+
+      function syncStudioPdfFocusAutoRefreshButton() {
+        const state = getStudioPdfFocusAutoRefreshState();
+        syncStudioPdfAutoRefreshButton(
+          studioPdfFocusAutoRefreshBtn,
+          state && state.enabled,
+          Boolean(state && state.resourceQuery),
+        );
+      }
+
+      function clearStudioPdfFocusAutoRefreshSource() {
+        if (studioPdfFocusStandaloneAutoRefreshState) stopStudioPdfAutoRefreshState(studioPdfFocusStandaloneAutoRefreshState);
+        studioPdfFocusStandaloneAutoRefreshState = null;
+        studioPdfFocusSourceCard = null;
+        syncStudioPdfFocusAutoRefreshButton();
+      }
+
+      function setStudioPdfFocusAutoRefreshSource(sourceCard, resourceQuery) {
+        clearStudioPdfFocusAutoRefreshSource();
+        const card = sourceCard instanceof Element ? sourceCard : null;
+        if (card) {
+          studioPdfFocusSourceCard = card;
+          ensureStudioPdfCardAutoRefreshState(card, resourceQuery);
+          syncStudioPdfFocusAutoRefreshButton();
+          return;
+        }
+        const query = normalizeStudioPdfResourceQuery(resourceQuery);
+        if (!query) {
+          syncStudioPdfFocusAutoRefreshButton();
+          return;
+        }
+        studioPdfFocusStandaloneAutoRefreshState = createStudioPdfAutoRefreshState(query, {
+          isAlive: () => Boolean(isStudioPdfFocusOpen() && !studioPdfFocusSourceCard),
+          refresh: () => refreshStudioPdfFocusViewer({ automatic: true }),
+          sync: () => syncStudioPdfFocusAutoRefreshButton(),
+        });
+        syncStudioPdfFocusAutoRefreshButton();
+      }
+
+      function toggleStudioPdfFocusAutoRefresh() {
+        const state = getStudioPdfFocusAutoRefreshState();
+        if (!state) {
+          setStatus("Could not resolve this PDF for auto-refresh.", "warning");
+          return false;
+        }
+        return setStudioPdfAutoRefreshEnabled(state, !state.enabled);
+      }
+
       async function runStudioPdfLocalAction(action, resourceQuery) {
         const query = normalizeStudioPdfResourceQuery(resourceQuery);
         if (!query) {
@@ -7174,7 +7418,7 @@
         if (focusBtn && focusBtn.dataset) focusBtn.dataset.studioPdfViewerUrl = nextUrl;
       }
 
-      function refreshStudioPdfCard(card) {
+      function refreshStudioPdfCard(card, options) {
         if (!card) return false;
         const frame = typeof card.querySelector === "function" ? card.querySelector("iframe.studio-pdf-frame") : null;
         const currentUrl = String(card.dataset && card.dataset.studioPdfViewerUrl ? card.dataset.studioPdfViewerUrl : "").trim()
@@ -7182,7 +7426,14 @@
         const nextUrl = buildRefreshedStudioPdfViewerUrl(currentUrl);
         if (!nextUrl) return false;
         syncStudioPdfCardViewerUrl(card, nextUrl);
-        setStatus("Refreshed PDF preview from disk.", "success");
+        if (!options || !options.automatic) {
+          resetStudioPdfAutoRefreshObservation(studioPdfCardAutoRefreshStates.get(card) || null);
+        }
+        if (!options || !options.silent) {
+          setStatus(options && options.automatic
+            ? "PDF changed on disk; refreshed preview."
+            : "Refreshed PDF preview from disk.", "success");
+        }
         return true;
       }
 
@@ -7193,7 +7444,7 @@
         return studioPdfFocusFrameEl;
       }
 
-      function refreshStudioPdfFocusViewer() {
+      function refreshStudioPdfFocusViewer(options) {
         const frame = getStudioPdfFocusActiveFrame();
         const currentUrl = String(frame && frame.src ? frame.src : "").trim()
           || String(studioPdfFocusOpenLinkEl && studioPdfFocusOpenLinkEl.href ? studioPdfFocusOpenLinkEl.href : "").trim();
@@ -7204,7 +7455,58 @@
         }
         if (frame) frame.src = nextUrl;
         if (studioPdfFocusOpenLinkEl) studioPdfFocusOpenLinkEl.href = nextUrl;
-        setStatus("Refreshed PDF preview from disk.", "success");
+        if (studioPdfFocusSourceCard) syncStudioPdfCardViewerUrl(studioPdfFocusSourceCard, nextUrl);
+        if (!options || !options.automatic) {
+          resetStudioPdfAutoRefreshObservation(getStudioPdfFocusAutoRefreshState());
+        }
+        if (!options || !options.silent) {
+          setStatus(options && options.automatic
+            ? "PDF changed on disk; refreshed preview."
+            : "Refreshed PDF preview from disk.", "success");
+        }
+        return true;
+      }
+
+      function getVisibleStudioPdfCards() {
+        return Array.from(document.querySelectorAll(".studio-pdf-card")).filter((card) => {
+          if (!card || !card.isConnected || card.hidden) return false;
+          if (typeof card.getClientRects === "function" && card.getClientRects().length === 0) return false;
+          try {
+            const style = window.getComputedStyle(card);
+            return style.display !== "none" && style.visibility !== "hidden";
+          } catch {
+            return true;
+          }
+        });
+      }
+
+      function refreshVisibleStudioPdfPreviews() {
+        if (isStudioPdfFocusOpen()) return refreshStudioPdfFocusViewer();
+        const cards = getVisibleStudioPdfCards();
+        let refreshed = 0;
+        cards.forEach((card) => {
+          if (refreshStudioPdfCard(card, { silent: true })) refreshed += 1;
+        });
+        if (refreshed > 0) {
+          setStatus(refreshed === 1
+            ? "Refreshed PDF preview from disk."
+            : ("Refreshed " + refreshed + " PDF previews from disk."), "success");
+          return true;
+        }
+        return false;
+      }
+
+      function handleStudioPdfRefreshShortcut(event) {
+        if (!event) return false;
+        const key = typeof event.key === "string" ? event.key.toLowerCase() : "";
+        const code = typeof event.code === "string" ? event.code : "";
+        const matches = (key === "r" || code === "KeyR")
+          && (event.metaKey || event.ctrlKey)
+          && event.altKey
+          && !event.shiftKey;
+        if (!matches) return false;
+        if (!refreshVisibleStudioPdfPreviews()) return false;
+        event.preventDefault();
         return true;
       }
 
@@ -7285,7 +7587,7 @@
             })
           : null;
         if (!viewerUrl) return false;
-        openStudioPdfFocusViewer(viewerUrl, title, sourceFrame, resourceQuery);
+        openStudioPdfFocusViewer(viewerUrl, title, sourceFrame, resourceQuery, card);
         return true;
       }
 
@@ -7698,6 +8000,7 @@
         const caption = String(options.caption || "").trim();
         const height = normalizeStudioPdfHeight(options.height);
         const page = normalizeStudioPdfPage(options.page);
+        const autoRefreshRequested = normalizeStudioPdfAutoRefresh(options.watch);
         const resourceQuery = buildStudioPdfResourceQuery(options, useEditorResourceContext);
         const resourceUrl = buildStudioPdfResourceUrl(options, useEditorResourceContext);
         const viewerUrl = resourceUrl && page ? resourceUrl + "#page=" + encodeURIComponent(String(page)) : resourceUrl;
@@ -7778,7 +8081,7 @@
           refreshBtn.type = "button";
           refreshBtn.className = "studio-pdf-card-action studio-pdf-card-refresh";
           refreshBtn.textContent = "Refresh";
-          refreshBtn.title = "Reload this PDF preview from disk.";
+          refreshBtn.title = "Reload this PDF preview from disk. Shortcut: Cmd/Ctrl+Alt+R.";
           refreshBtn.addEventListener("click", (event) => {
             event.preventDefault();
             event.stopPropagation();
@@ -7786,6 +8089,25 @@
           });
           actions.appendChild(refreshBtn);
 
+          const autoRefreshBtn = document.createElement("button");
+          autoRefreshBtn.type = "button";
+          autoRefreshBtn.className = "studio-pdf-card-action studio-pdf-card-auto-refresh";
+          autoRefreshBtn.textContent = "Auto-refresh";
+          autoRefreshBtn.title = "Watch this local PDF and reload it after a changed file is stable on disk.";
+          autoRefreshBtn.setAttribute("aria-label", "Enable PDF auto-refresh");
+          autoRefreshBtn.setAttribute("aria-pressed", "false");
+          autoRefreshBtn.addEventListener("click", (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            const state = ensureStudioPdfCardAutoRefreshState(card, resourceQuery);
+            if (!state) {
+              setStatus("Could not resolve this PDF for auto-refresh.", "warning");
+              return;
+            }
+            setStudioPdfCardAutoRefresh(card, !state.enabled);
+          });
+          actions.appendChild(autoRefreshBtn);
+
           header.appendChild(actions);
         }
         card.appendChild(header);
@@ -7812,6 +8134,12 @@
         iframe.loading = "lazy";
         iframe.style.height = height + "px";
         card.appendChild(iframe);
+        const autoRefreshState = ensureStudioPdfCardAutoRefreshState(card, resourceQuery);
+        if (autoRefreshRequested) {
+          setStudioPdfAutoRefreshEnabled(autoRefreshState, true, { silent: true });
+        } else {
+          syncStudioPdfCardAutoRefreshButton(card);
+        }
         return card;
       }
 

package/client/studio-preview-resource-helpers.js

@@ -43,10 +43,62 @@
     return { attempted: images.length, resolved };
   }
 
+  function buildStudioPdfVersionSignature(headers) {
+    if (!headers || typeof headers.get !== "function") return "";
+    const etag = String(headers.get("etag") || "").trim();
+    const modified = String(headers.get("last-modified") || "").trim();
+    const length = String(headers.get("content-length") || "").trim();
+    if (!etag && !modified && !length) return "";
+    return [etag, modified, length].join("\n");
+  }
+
+  function createStudioPdfVersionObservationState() {
+    return {
+      baseline: "",
+      candidate: "",
+      candidateCount: 0,
+    };
+  }
+
+  function observeStudioPdfVersion(previousState, signature, stableObservations) {
+    const state = previousState && typeof previousState === "object"
+      ? previousState
+      : createStudioPdfVersionObservationState();
+    const nextSignature = String(signature || "").trim();
+    const required = Math.max(2, Number.parseInt(String(stableObservations || "2"), 10) || 2);
+    if (!nextSignature) return { state, changed: false };
+    if (!state.baseline) {
+      return {
+        state: { baseline: nextSignature, candidate: "", candidateCount: 0 },
+        changed: false,
+      };
+    }
+    if (nextSignature === state.baseline) {
+      return {
+        state: { baseline: state.baseline, candidate: "", candidateCount: 0 },
+        changed: false,
+      };
+    }
+    const candidateCount = nextSignature === state.candidate ? state.candidateCount + 1 : 1;
+    if (candidateCount < required) {
+      return {
+        state: { baseline: state.baseline, candidate: nextSignature, candidateCount },
+        changed: false,
+      };
+    }
+    return {
+      state: { baseline: nextSignature, candidate: "", candidateCount: 0 },
+      changed: true,
+    };
+  }
+
   globalThis.PiStudioPreviewResourceHelpers = Object.freeze({
     STUDIO_PREVIEW_LOCAL_IMAGE_LIMIT,
     areStudioPreviewResourceContextsEqual,
+    buildStudioPdfVersionSignature,
+    createStudioPdfVersionObservationState,
     hydrateStudioPreviewLocalImages,
     isResolvableStudioPreviewImageSource,
+    observeStudioPdfVersion,
   });
 })();

package/client/studio.css

@@ -1822,6 +1822,20 @@
       border-color: var(--control-border);
     }
 
+    .rendered-markdown button.studio-pdf-card-auto-refresh[aria-pressed="true"] {
+      background: transparent;
+      color: var(--accent);
+      border-color: transparent;
+      font-weight: 600;
+    }
+
+    .rendered-markdown button.studio-pdf-card-auto-refresh[aria-pressed="true"]:not(:disabled):hover,
+    .rendered-markdown button.studio-pdf-card-auto-refresh[aria-pressed="true"]:focus-visible {
+      background: var(--panel);
+      color: var(--accent);
+      border-color: var(--control-border);
+    }
+
     .rendered-markdown button.studio-pdf-card-focus {
       width: 29px;
       min-width: 29px;
@@ -1983,6 +1997,20 @@
       color: var(--text);
     }
 
+    .studio-pdf-focus-auto-refresh[aria-pressed="true"] {
+      background: transparent;
+      border-color: transparent;
+      color: var(--accent);
+      font-weight: 600;
+    }
+
+    .studio-pdf-focus-auto-refresh[aria-pressed="true"]:not(:disabled):hover,
+    .studio-pdf-focus-auto-refresh[aria-pressed="true"]:focus-visible {
+      background: var(--panel);
+      border-color: var(--control-border);
+      color: var(--accent);
+    }
+
     .studio-pdf-focus-btn .studio-refresh-icon {
       width: 14px;
       height: 14px;

package/index.ts

@@ -28,6 +28,7 @@ import {
 	preserveLiteralLatexCommandsInMarkdown,
 } from "./shared/studio-markdown-latex-literals.js";
 import { escapeStudioPdfLatexTextFragment } from "./shared/studio-pdf-escape.js";
+import { parseStudioLocalPreviewPage, parseStudioPdfLaunchTarget } from "./shared/studio-local-preview-path.js";
 import { resolveStudioPdfResourceFile } from "./shared/studio-pdf-resource.js";
 import { createStudioPandocHtmlResourceFlagResolver } from "./shared/studio-pandoc-resource-flag.js";
 import { prepareStudioLatexForPandoc } from "./shared/studio-latex-pandoc-compat.js";
@@ -276,6 +277,21 @@ interface InitialStudioDocument {
 	resourceDir?: string;
 }
 
+interface StudioLaunchSelection {
+	document: InitialStudioDocument;
+	kind: "document" | "pdf-preview";
+	mode?: StudioUiMode;
+	transient?: boolean;
+	skipWorkspaceRestore?: boolean;
+	paneFocus?: "left" | "right";
+	resourcePath?: string;
+}
+
+interface StudioUrlOptions {
+	skipWorkspaceRestore?: boolean;
+	paneFocus?: "left" | "right";
+}
+
 type PersistedStudioReviewNoteAnchorKind = "source" | "html-selection" | "html-element" | "html-page";
 
 interface PersistedStudioReviewNote {
@@ -2949,35 +2965,6 @@ function decodeStudioHtmlPreviewResourcePath(resourcePath: string): string {
 	}
 }
 
-function parseStudioLocalPreviewResourcePage(resourcePath: string): number | null {
-	const raw = String(resourcePath || "");
-	const parts: string[] = [];
-	const queryIndex = raw.indexOf("?");
-	if (queryIndex >= 0) {
-		const queryEnd = raw.indexOf("#", queryIndex);
-		parts.push(raw.slice(queryIndex + 1, queryEnd >= 0 ? queryEnd : raw.length));
-	}
-	const hashIndex = raw.indexOf("#");
-	if (hashIndex >= 0) parts.push(raw.slice(hashIndex + 1));
-	for (const part of parts) {
-		try {
-			const params = new URLSearchParams(part);
-			const rawPage = params.get("page") || params.get("p");
-			if (rawPage) {
-				const page = Number.parseInt(rawPage, 10);
-				if (Number.isFinite(page) && page > 0) return page;
-			}
-		} catch {
-			const match = part.match(/(?:^|[&;])page=(\d+)/i) || part.match(/^page=(\d+)$/i);
-			if (match && match[1]) {
-				const page = Number.parseInt(match[1], 10);
-				if (Number.isFinite(page) && page > 0) return page;
-			}
-		}
-	}
-	return null;
-}
-
 function getStudioLocalPreviewResourceKind(extension: string, filePathOrName?: string): StudioLocalPreviewResourceKind {
 	const ext = extension.toLowerCase();
 	const name = basename(String(filePathOrName || "")).toLowerCase();
@@ -3022,7 +3009,7 @@ function resolveStudioLocalPreviewResourcePath(
 		label: rel && rel !== "" ? rel : basename(candidateReal),
 		extension,
 		kind: getStudioLocalPreviewResourceKind(extension, candidateReal),
-		page: parseStudioLocalPreviewResourcePage(rawPath),
+		page: parseStudioLocalPreviewPage(rawPath),
 		resourceDir: boundaryReal,
 	};
 }
@@ -7369,16 +7356,31 @@ function respondPdfFile(req: IncomingMessage, res: ServerResponse, filePath: str
 		return;
 	}
 
-	const pdf = readFileSync(filePath);
-	res.writeHead(200, {
+	const stats = statSync(filePath);
+	const etag = `W/"${[
+		stats.size,
+		Math.trunc(stats.mtimeMs),
+		Math.trunc(stats.ctimeMs),
+		stats.ino,
+	].map((value) => Number(value).toString(16)).join("-")}"`;
+	const commonHeaders = {
 		"Content-Type": "application/pdf",
-		"Content-Length": String(pdf.length),
 		"Content-Disposition": `inline; filename="${basename(filePath).replace(/["\\]/g, "") || "document.pdf"}"`,
 		"Cache-Control": "no-store",
 		"X-Content-Type-Options": "nosniff",
 		"Cross-Origin-Resource-Policy": "same-origin",
-	});
-	res.end(method === "HEAD" ? undefined : pdf);
+		"ETag": etag,
+		"Last-Modified": stats.mtime.toUTCString(),
+	};
+	if (method === "HEAD") {
+		res.writeHead(200, { ...commonHeaders, "Content-Length": String(stats.size) });
+		res.end();
+		return;
+	}
+
+	const pdf = readFileSync(filePath);
+	res.writeHead(200, { ...commonHeaders, "Content-Length": String(pdf.length) });
+	res.end(pdf);
 }
 
 function respondHtmlPreviewResourceJson(req: IncomingMessage, res: ServerResponse, filePath: string, mimeType: string): void {
@@ -7406,7 +7408,7 @@ function sanitizeStudioPreviewBlockLine(value: string): string {
 	return String(value || "").replace(/[\r\n]+/g, " ").trim();
 }
 
-function buildStudioLocalResourcePreviewDocument(resource: StudioLocalPreviewResource): InitialStudioDocument {
+function buildStudioLocalResourcePreviewDocument(resource: StudioLocalPreviewResource, options?: { watchPdf?: boolean }): InitialStudioDocument {
 	const label = basename(resource.filePath) || resource.label || "local preview";
 	const resourcePath = resource.label || basename(resource.filePath) || resource.filePath;
 	const title = sanitizeStudioPreviewBlockLine(label);
@@ -7415,6 +7417,8 @@ function buildStudioLocalResourcePreviewDocument(resource: StudioLocalPreviewRes
 		text = "```studio-pdf\n"
 			+ `path: ${sanitizeStudioPreviewBlockLine(resourcePath)}\n`
 			+ `title: ${title || "PDF preview"}\n`
+			+ (resource.page ? `page: ${resource.page}\n` : "")
+			+ (options?.watchPdf ? "watch: true\n" : "")
 			+ "height: 820\n"
 			+ "```\n";
 	} else if (resource.kind === "image") {
@@ -10283,7 +10287,7 @@ function buildStudioRelativeUrl(
 	mode: StudioUiMode = "full",
 	doc?: InitialStudioDocument | null,
 	docId?: string,
-	options?: { skipWorkspaceRestore?: boolean },
+	options?: StudioUrlOptions,
 ): string {
 	const params = new URLSearchParams({ token });
 	if (mode !== "full") params.set("mode", mode);
@@ -10294,6 +10298,7 @@ function buildStudioRelativeUrl(
 	if (doc?.draftId) params.set("draftId", doc.draftId);
 	if (doc?.resourceDir) params.set("resourceDir", doc.resourceDir);
 	if (options?.skipWorkspaceRestore) params.set("skipWorkspaceRestore", "1");
+	if (options?.paneFocus) params.set("paneFocus", options.paneFocus);
 	return `/?${params.toString()}`;
 }
 
@@ -10303,7 +10308,7 @@ function buildStudioUrl(
 	mode: StudioUiMode = "full",
 	doc?: InitialStudioDocument | null,
 	docId?: string,
-	options?: { skipWorkspaceRestore?: boolean },
+	options?: StudioUrlOptions,
 ): string {
 	return `http://127.0.0.1:${port}${buildStudioRelativeUrl(token, mode, doc, docId, options)}`;
 }
@@ -10312,16 +10317,18 @@ interface StudioLaunchFlags {
 	args: string;
 	openRemoteBrowser: boolean;
 	noBrowser: boolean;
+	watchPdf: boolean;
 	port?: number;
 	error?: string;
 }
 
 function parseStudioLaunchOpenFlags(rawArgs: string): StudioLaunchFlags {
 	const parsed = tokenizeStudioCommandArgs(rawArgs);
-	if (parsed.error) return { args: rawArgs, openRemoteBrowser: false, noBrowser: false, error: parsed.error };
+	if (parsed.error) return { args: rawArgs, openRemoteBrowser: false, noBrowser: false, watchPdf: false, error: parsed.error };
 	const remaining: string[] = [];
 	let openRemoteBrowser = false;
 	let noBrowser = false;
+	let watchPdf = false;
 	let port: number | undefined;
 	for (let i = 0; i < parsed.tokens.length; i += 1) {
 		const token = parsed.tokens[i]!;
@@ -10333,14 +10340,18 @@ function parseStudioLaunchOpenFlags(rawArgs: string): StudioLaunchFlags {
 			noBrowser = true;
 			continue;
 		}
+		if (token === "--watch" || token === "--auto-refresh") {
+			watchPdf = true;
+			continue;
+		}
 		if (token === "--port" || token.startsWith("--port=")) {
 			const rawPort = token.startsWith("--port=") ? token.slice("--port=".length) : parsed.tokens[++i];
 			if (!rawPort) {
-				return { args: rawArgs, openRemoteBrowser, noBrowser, error: "Missing value for --port." };
+				return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, error: "Missing value for --port." };
 			}
 			const requestedPort = Number(rawPort);
 			if (!Number.isInteger(requestedPort) || requestedPort < 1 || requestedPort > 65535) {
-				return { args: rawArgs, openRemoteBrowser, noBrowser, error: `Invalid --port value: ${rawPort}. Use an integer from 1 to 65535.` };
+				return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, error: `Invalid --port value: ${rawPort}. Use an integer from 1 to 65535.` };
 			}
 			port = requestedPort;
 			continue;
@@ -10348,9 +10359,9 @@ function parseStudioLaunchOpenFlags(rawArgs: string): StudioLaunchFlags {
 		remaining.push(token);
 	}
 	if (openRemoteBrowser && noBrowser) {
-		return { args: rawArgs, openRemoteBrowser, noBrowser, port, error: "Use either --no-browser or --open-browser, not both." };
+		return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, port, error: "Use either --no-browser or --open-browser, not both." };
 	}
-	return { args: remaining.join(" "), openRemoteBrowser, noBrowser, port };
+	return { args: remaining.join(" "), openRemoteBrowser, noBrowser, watchPdf, port };
 }
 
 function shouldAutoOpenStudioBrowser(options?: { openRemoteBrowser?: boolean; noBrowser?: boolean }): boolean {
@@ -11082,6 +11093,7 @@ ${cssVarsBlock}
             <div><dt>Alt/Option+=</dt><dd>Increase the active pane's text size when not editing text</dd></div>
             <div><dt>Alt/Option+-</dt><dd>Decrease the active pane's text size when not editing text</dd></div>
             <div><dt>Alt/Option+0</dt><dd>Reset the active pane's text size when not editing text</dd></div>
+            <div><dt>Cmd/Ctrl+Alt+R</dt><dd>Refresh the focused or visible PDF preview from disk</dd></div>
           </dl>
         </section>
         <section class="shortcuts-group">
@@ -15744,10 +15756,11 @@ export default function (pi: ExtensionAPI) {
 	const resolveStudioLaunchDocument = (
 		trimmed: string,
 		ctx: ExtensionCommandContext,
-		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string },
-	): InitialStudioDocument | null => {
+		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string; allowPdfPreview?: boolean; watchPdf?: boolean },
+	): StudioLaunchSelection | null => {
 		const defaultSource = options?.defaultSource === "blank" ? "blank" : "last-response";
 		const commandLabel = options?.commandLabel ?? "/studio";
+		const selectDocument = (document: InitialStudioDocument): StudioLaunchSelection => ({ document, kind: "document" });
 		const latestAssistant =
 			extractLatestAssistantFromEntries(ctx.sessionManager.getBranch())
 				?? extractLatestAssistantFromEntries(ctx.sessionManager.getEntries())
@@ -15756,51 +15769,51 @@ export default function (pi: ExtensionAPI) {
 
 		if (!trimmed) {
 			if (defaultSource === "last-response" && latestAssistant) {
-				return {
+				return selectDocument({
 					text: latestAssistant,
 					label: "last model response",
 					source: "last-response",
 					draftId: createStudioDraftId(),
 					resourceDir: ctx.cwd,
-				};
+				});
 			}
-			return {
+			return selectDocument({
 				text: "",
 				label: "blank",
 				source: "blank",
 				draftId: createStudioDraftId(),
 				resourceDir: ctx.cwd,
-			};
+			});
 		}
 
 		if (trimmed === "--blank" || trimmed === "blank") {
-			return {
+			return selectDocument({
 				text: "",
 				label: "blank",
 				source: "blank",
 				draftId: createStudioDraftId(),
 				resourceDir: ctx.cwd,
-			};
+			});
 		}
 
 		if (trimmed === "--last" || trimmed === "last") {
 			if (!latestAssistant) {
 				ctx.ui.notify("No assistant response found; opening blank studio.", "warning");
-				return {
+				return selectDocument({
 					text: "",
 					label: "blank",
 					source: "blank",
 					draftId: createStudioDraftId(),
 					resourceDir: ctx.cwd,
-				};
+				});
 			}
-			return {
+			return selectDocument({
 				text: latestAssistant,
 				label: "last model response",
 				source: "last-response",
 				draftId: createStudioDraftId(),
 				resourceDir: ctx.cwd,
-			};
+			});
 		}
 
 		if (trimmed.startsWith("-")) {
@@ -15814,6 +15827,36 @@ export default function (pi: ExtensionAPI) {
 			return null;
 		}
 
+		const pdfTarget = options?.allowPdfPreview ? parseStudioPdfLaunchTarget(normalizePathInput(pathArg)) : null;
+		if (pdfTarget) {
+			const resolved = resolveStudioPath(pdfTarget.path, ctx.cwd);
+			if (resolved.ok === false) {
+				ctx.ui.notify(resolved.message, "error");
+				return null;
+			}
+			try {
+				const resource = resolveStudioLocalPreviewResourcePath(
+					pdfTarget.page ? `${resolved.resolved}#page=${pdfTarget.page}` : resolved.resolved,
+					resolved.resolved,
+					dirname(resolved.resolved),
+					ctx.cwd,
+				);
+				if (resource.kind !== "pdf") throw new Error("Only local .pdf files can open in the Studio PDF viewer.");
+				return {
+					document: buildStudioLocalResourcePreviewDocument(resource, { watchPdf: options?.watchPdf }),
+					kind: "pdf-preview",
+					mode: "editor-only",
+					transient: true,
+					skipWorkspaceRestore: true,
+					paneFocus: "right",
+					resourcePath: resource.filePath,
+				};
+			} catch (error) {
+				ctx.ui.notify(`Could not open PDF preview: ${error instanceof Error ? error.message : String(error)}`, "error");
+				return null;
+			}
+		}
+
 		const file = readStudioFile(pathArg, ctx.cwd);
 		if (file.ok === false) {
 			ctx.ui.notify(file.message, "error");
@@ -15827,13 +15870,13 @@ export default function (pi: ExtensionAPI) {
 			);
 		}
 
-		return {
+		return selectDocument({
 			text: file.text,
 			label: file.label,
 			source: "file",
 			path: file.resolvedPath,
 			resourceDir: ctx.cwd,
-		};
+		});
 	};
 
 	const resolveLastModelResponseForExport = (ctx: ExtensionContext): { markdown: string } | null => {
@@ -16090,7 +16133,7 @@ export default function (pi: ExtensionAPI) {
 		trimmed: string,
 		ctx: ExtensionCommandContext,
 		mode: StudioUiMode,
-		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string; replaceExistingFull?: boolean },
+		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string; replaceExistingFull?: boolean; allowPdfPreview?: boolean; watchPdf?: boolean },
 	) => {
 		const launchOpenFlags = parseStudioLaunchOpenFlags(trimmed);
 		if (launchOpenFlags.error) {
@@ -16101,7 +16144,17 @@ export default function (pi: ExtensionAPI) {
 		if (serverState && launchOpenFlags.port && serverState.port !== launchOpenFlags.port) {
 			ctx.ui.notify(`Studio server is already running on port ${serverState.port}; requested port ${launchOpenFlags.port}. Use /studio --stop, then restart Studio with --port ${launchOpenFlags.port} to change it.`, "warning");
 		}
-		if (mode === "full" && hasConnectedFullStudioView()) {
+
+		const parsedLaunchPath = options?.allowPdfPreview ? parsePathArgument(launchArgs) : null;
+		const launchesPdfPreview = parsedLaunchPath
+			? Boolean(parseStudioPdfLaunchTarget(normalizePathInput(parsedLaunchPath)))
+			: false;
+		if (launchOpenFlags.watchPdf && !launchesPdfPreview) {
+			ctx.ui.notify("--watch requires a local PDF path, for example: /studio --watch main.pdf", "error");
+			return;
+		}
+		const requestedLaunchMode: StudioUiMode = launchesPdfPreview ? "editor-only" : mode;
+		if (requestedLaunchMode === "full" && hasConnectedFullStudioView()) {
 			if (options?.replaceExistingFull) {
 				closeStudioClientsByMode("full", 4001, "Full Studio replaced");
 			} else {
@@ -16132,9 +16185,14 @@ export default function (pi: ExtensionAPI) {
 			// ignore theme read errors
 		}
 
-		const selected = resolveStudioLaunchDocument(launchArgs, ctx, options);
-		if (!selected) return;
-		initialStudioDocument = selected;
+		const selection = resolveStudioLaunchDocument(launchArgs, ctx, {
+			...options,
+			watchPdf: launchOpenFlags.watchPdf,
+		});
+		if (!selection) return;
+		const selected = selection.document;
+		const launchMode = selection.mode ?? requestedLaunchMode;
+		if (!selection.transient) initialStudioDocument = selected;
 
 		let state: StudioServerState;
 		try {
@@ -16145,10 +16203,16 @@ export default function (pi: ExtensionAPI) {
 			ctx.ui.notify(`Failed to start Studio server${portText}: ${message}`, "error");
 			return;
 		}
-		const url = buildStudioUrl(state.port, state.token, mode, selected);
+		const docId = selection.transient ? storeTransientStudioDocument(selected) : undefined;
+		const url = buildStudioUrl(state.port, state.token, launchMode, selected, docId, {
+			skipWorkspaceRestore: selection.skipWorkspaceRestore,
+			paneFocus: selection.paneFocus,
+		});
 		const tunnelHint = buildStudioSshTunnelHint(state.port, url)
 			?? (launchOpenFlags.noBrowser ? buildStudioForwardingHint(state.port, url, { prefix: "Browser auto-open was skipped because --no-browser was used." }) : null);
-		const openedLabel = mode === "editor-only" ? "pi Studio editor-only view" : "pi Studio";
+		const openedLabel = selection.kind === "pdf-preview"
+			? "pi Studio PDF preview"
+			: (launchMode === "editor-only" ? "pi Studio editor-only view" : "pi Studio");
 
 		const shouldOpenBrowser = shouldAutoOpenStudioBrowser({
 			openRemoteBrowser: launchOpenFlags.openRemoteBrowser,
@@ -16160,7 +16224,10 @@ export default function (pi: ExtensionAPI) {
 				ctx.ui.notify(`${openedLabel} is ready. Browser auto-open was skipped because ${skipReason}.`, "info");
 			} else {
 				await openStudioUrlInBrowser(url);
-				if (selected.source === "file") {
+				if (selection.kind === "pdf-preview") {
+					const watchLabel = launchOpenFlags.watchPdf ? " (auto-refresh on)" : "";
+					ctx.ui.notify(`Opened ${openedLabel}${watchLabel}: ${selection.resourcePath ?? selected.label}`, "info");
+				} else if (selected.source === "file") {
 					ctx.ui.notify(`Opened ${openedLabel} with file loaded: ${selected.label}`, "info");
 				} else if (selected.source === "last-response") {
 					ctx.ui.notify(`Opened ${openedLabel} with last model response (${selected.text.length} chars).`, "info");
@@ -16182,7 +16249,7 @@ export default function (pi: ExtensionAPI) {
 	};
 
 	pi.registerCommand("studio", {
-		description: "Open pi Studio browser UI (/studio, /studio <file>, /studio --blank, /studio --last, /studio --no-browser, /studio --port <port>)",
+		description: "Open pi Studio browser UI or a PDF preview (/studio, /studio <file>, /studio --watch <pdf>, /studio --blank, /studio --last, /studio --no-browser)",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const trimmed = args.trim();
 
@@ -16212,7 +16279,8 @@ export default function (pi: ExtensionAPI) {
 				ctx.ui.notify(
 					"Usage: /studio [path|--blank|--last]\n"
 						+ "  /studio           Open studio with last model response (fallback: blank)\n"
-						+ "  /studio <path>    Open studio with file preloaded\n"
+						+ "  /studio <path>    Open a text file in Studio, or a PDF in a read-only companion preview\n"
+						+ "  /studio --watch <pdf>  Open a PDF with auto-refresh enabled\n"
 						+ "  /studio --blank   Open with blank editor\n"
 						+ "  /studio --last    Open with last model response\n"
 						+ "  /studio --no-browser  Print the Studio URL without opening a browser\n"
@@ -16220,7 +16288,7 @@ export default function (pi: ExtensionAPI) {
 						+ "  /studio --open-remote  Over SSH, open the remote browser anyway\n"
 						+ "  /studio --status  Show studio status\n"
 						+ "  /studio --stop    Stop studio server\n"
-						+ "  Note: only one full /studio view is allowed per Pi session.\n"
+						+ "  Note: only one full /studio view is allowed per Pi session; PDF previews open as companions.\n"
 						+ "  /studio-replace [path]  Replace the current full Studio view with a new one\n"
 						+ "  /studio-editor-only [path]  Open another Studio tab in editor-only mode\n"
 						+ "  /studio-current <path>  Load a file into currently open Studio tab(s)\n"
@@ -16231,7 +16299,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			await openStudioView(trimmed, ctx, "full", { defaultSource: "last-response", commandLabel: "/studio" });
+			await openStudioView(trimmed, ctx, "full", { defaultSource: "last-response", commandLabel: "/studio", allowPdfPreview: true });
 		},
 	});
 
@@ -16263,14 +16331,15 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("studio-editor-only", {
-		description: "Open pi Studio in editor-only mode (/studio-editor-only, /studio-editor-only <file>, /studio-editor-only --no-browser)",
+		description: "Open pi Studio in editor-only mode or preview a PDF (/studio-editor-only, /studio-editor-only <file>, /studio-editor-only --watch <pdf>)",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const trimmed = args.trim();
 			if (trimmed === "help" || trimmed === "--help" || trimmed === "-h") {
 				ctx.ui.notify(
 					"Usage: /studio-editor-only [path|--blank|--last]\n"
 						+ "  /studio-editor-only         Open an editor-only Studio view (default: blank editor)\n"
-						+ "  /studio-editor-only <path>  Open an editor-only Studio view with file preloaded\n"
+						+ "  /studio-editor-only <path>  Open a text file for editing, or a PDF in a read-only preview\n"
+						+ "  /studio-editor-only --watch <pdf>  Open a PDF with auto-refresh enabled\n"
 						+ "  /studio-editor-only --blank Open with blank editor\n"
 						+ "  /studio-editor-only --last  Open with last model response loaded into the editor\n"
 						+ "  /studio-editor-only --no-browser  Print URL without opening a browser\n"
@@ -16281,7 +16350,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			await openStudioView(trimmed, ctx, "editor-only", { defaultSource: "blank", commandLabel: "/studio-editor-only" });
+			await openStudioView(trimmed, ctx, "editor-only", { defaultSource: "blank", commandLabel: "/studio-editor-only", allowPdfPreview: true });
 		},
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.9.48",
+  "version": "0.9.49",
   "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, active quiz, prompt/response history, live previews, and tmux-backed REPL/literate REPL workflows",
   "type": "module",
   "license": "MIT",

package/shared/studio-local-preview-path.js

@@ -0,0 +1,46 @@
+function parseStudioLocalPreviewPage(resourcePath) {
+	const raw = String(resourcePath || "");
+	const parts = [];
+	const queryIndex = raw.indexOf("?");
+	if (queryIndex >= 0) {
+		const queryEnd = raw.indexOf("#", queryIndex);
+		parts.push(raw.slice(queryIndex + 1, queryEnd >= 0 ? queryEnd : raw.length));
+	}
+	const hashIndex = raw.indexOf("#");
+	if (hashIndex >= 0) parts.push(raw.slice(hashIndex + 1));
+	for (const part of parts) {
+		try {
+			const params = new URLSearchParams(part);
+			const rawPage = params.get("page") || params.get("p");
+			if (rawPage) {
+				const page = Number.parseInt(rawPage, 10);
+				if (Number.isFinite(page) && page > 0) return page;
+			}
+		} catch {
+			const match = part.match(/(?:^|[&;])page=(\d+)/i) || part.match(/^page=(\d+)$/i);
+			if (match && match[1]) {
+				const page = Number.parseInt(match[1], 10);
+				if (Number.isFinite(page) && page > 0) return page;
+			}
+		}
+	}
+	return null;
+}
+
+function parseStudioPdfLaunchTarget(pathInput) {
+	const raw = String(pathInput || "").trim();
+	if (!raw || /\0/.test(raw) || /^\/\//.test(raw)) return null;
+	if (/^[a-z][a-z0-9+.-]*:/i.test(raw) && !/^[a-z]:[\\/]/i.test(raw)) return null;
+
+	const match = raw.match(/^(.*?\.pdf)(?:(?:\?[^#]*)?(?:#.*)?)?$/i);
+	if (!match || !match[1]) return null;
+	return {
+		path: match[1],
+		page: parseStudioLocalPreviewPage(raw),
+	};
+}
+
+export {
+	parseStudioLocalPreviewPage,
+	parseStudioPdfLaunchTarget,
+};