pi-studio 0.9.51 → 0.9.53

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.9.53] — 2026-08-31
+
+### Added
+- Add a bounded, session-scoped workspace grant registry that canonicalizes exact-file and directory grants, rejects symlink escapes, automatically records trusted document/workspace locations, and stays separate from the current editor document.
+- When an explicit local preview link crosses the current resource boundary, show an in-page **Allow this file** / **Allow this folder for this Studio session** / **Cancel** decision, identify the path as belonging to the computer running Pi, and retry the original PDF, image, document, copy, reveal, or system-viewer action only after a grant is confirmed.
+- Root the Files view in session directory grants, add an explicit **Allow folder…** action and allowed-location selector, and show exact-file grants without exposing or making their parent folders browsable.
+- Add `Cmd/Ctrl+Alt+F` as a mnemonic shortcut for switching the right pane directly to Files (`Ctrl+Option+F` is accepted on macOS).
+- Keep passive local images and embedded PDFs behind the same server-side session grants: already allowed media loads without interruption, while blocked media stays unloaded and presents an explicit **Allow local image/PDF…** action for choosing an exact-file or containing-folder grant.
+- Require a directory grant before a new Side questions thread can map, search, or read related files, with a trusted outer-Studio confirmation that names the canonical folder and explains the read-only scope.
+
+### Changed
+- Check local-link access before presenting its action menu, and route text/office links through that menu, so permission decisions remain visible in the originating Studio page instead of being hidden behind a preliminary waiting tab.
+- Resolve interactive preview media only through authenticated Studio endpoints rather than allowing Pandoc to embed files from a client-supplied resource directory; authored-HTML image blocks are surfaced in trusted outer Studio UI.
+- Revalidate Side questions' selected context root before prompting and before each built-in local context tool call; exact-file grants cannot authorize parent-folder access, and replacement symlinks cannot redirect an active context root.
+
+### Fixed
+- Keep confirmation-button text legible on hover in the light theme by retaining an accent background instead of inheriting the generic pale button hover state.
+
+## [0.9.52] — 2026-08-28
+
+### Added
+- Add a visible **Enlarge** control for embedded PDF cards, plus **Copy path** alongside PDF actions that operate on the computer running Pi.
+
+### Changed
+- Offer true browser fullscreen only when the current browser exposes the Fullscreen API, while retaining Studio's in-page image, PDF, and HTML focus viewers everywhere.
+- Keep ordinary images and rendered PDF figures unobscured by using their hover zoom cursor and whole-media click target instead of overlay buttons.
+
+### Fixed
+- Restore a clear, explicitly sized H1–H6 hierarchy in rendered Markdown without allowing application-header styles to override document headings.
+- Apply click-to-focus image behavior consistently to Side-question and Quiz Markdown as well as the main Editor, Response, and Working surfaces.
+- Keep image, rendered-PDF, and PDF-card actions interactive after the response pane resets its scroll position by adding clone-safe delegated handling; preserve rendered PDF canvas pixels across the reset so inline and enlarged figures do not become blank; show contextual success/failure feedback for host PDF actions.
+- Hide side-thread-only Markdown save, copy, and editor actions from ordinary Response, Editor Preview, and REPL export menus, with a runtime guard against stale menu activation.
+
 ## [0.9.51] — 2026-08-26
 
 ### Added

package/README.md

@@ -2,6 +2,8 @@
 
 Extension for [pi](https://pi.dev) that opens a local two-pane browser workspace for working with prompts, responses, live working details, Markdown and LaTeX documents, interactive HTML previews, code files, REPL sessions, and other common text-based files side by side. Annotate responses and files, add local comments, write, edit, run prompts, send code to a REPL, browse prompt and response history, request critiques, and use live preview for code, Markdown, LaTeX, and interactive HTML.
 
+See [`ROADMAP.md`](./ROADMAP.md) for the current release plan.
+
 ## Quick demo
 
 [Watch the 2-minute demo (MP4, 2x speed, no audio)](https://github.com/omaclaren/pi-studio/releases/latest/download/pi-studio-demo-2min.mp4)
@@ -33,9 +35,9 @@ _The video shows an earlier version of the Studio interface. The basic workflow
 - Includes a global **Zen** mode that hides the Studio header and secondary chrome without changing the current left/right pane layout; the header can also be hidden independently and restored from the top-right edge
 - Runs editor text directly, asks for structured critique (auto/writing/code focus), offers explicit **Show me** actions for a one-turn compact visual or structural explanation of the editor selection/document, displayed response, or current conversation topic, provides a manual **Suggest completion** action for short cursor-aware continuations (`Option/Alt+Tab` where available or `Cmd/Ctrl+Shift+Space` from the editor, `Tab` to insert a visible suggestion) with an optional editor-plus-latest-response context mode, or opens **Quiz me** for a Studio-native active-recall loop over the current editor text, selection, current file, folder, or repo, with optional focus guidance for shaping question selection
 - Adds a right-pane **Side questions** thread for contextual questions that stay outside the main Pi conversation unless explicitly promoted. It can start with the editor selection, the Markdown/LaTeX heading block at the cursor, nearby unstructured text, the whole editor, the displayed response, or no starting text; independently, it can use read-only tools to map, search, and read the document folder, repository, or another chosen folder—including extracted PDF, DOCX, ODT, and EPUB text—and can optionally search the web through Brave Search.
-- Includes a live **Working** view for following current model/tool activity, with `All` / `Thinking` / `Tools` filters, image previews for image-producing tool outputs, plus **Load visible into editor** and **Copy visible** actions; when cycling response history, Working follows saved working details for the selected response when available, and `Cmd/Ctrl+Alt+1–8` switches directly between right-pane views while `Cmd/Ctrl+Alt+P` / `Cmd/Ctrl+Alt+E` / `Cmd/Ctrl+Alt+W` keep quick mnemonic shortcuts for Response Preview, Editor Preview, and Working
+- Includes a live **Working** view for following current model/tool activity, with `All` / `Thinking` / `Tools` filters, image previews for image-producing tool outputs, plus **Load visible into editor** and **Copy visible** actions; when cycling response history, Working follows saved working details for the selected response when available, and `Cmd/Ctrl+Alt+1–8` switches directly between right-pane views while `Cmd/Ctrl+Alt+P` / `Cmd/Ctrl+Alt+E` / `Cmd/Ctrl+Alt+W` / `Cmd/Ctrl+Alt+F` / `Cmd/Ctrl+Alt+Q` keep quick mnemonic shortcuts for Response Preview, Editor Preview, Working, Files, and Side questions
 - Includes a right-pane **Changes** view for browsing the current git diff by file, previewing per-file diffs, opening changed files, loading the full diff into the editor, and copying the diff
-- Includes a right-pane **Files** view for browsing the current Pi session/resource directory, sorting by name/modified time/size, opening folders, opening the Files root in Finder/the system file manager, loading text/code/CSV/TSV documents into the editor, previewing PDFs/images, opening PDF/image previews in a new Studio tab, converting DOCX/ODT documents to editable Markdown when Pandoc is available after confirmation, copying paths, setting the current folder as the Studio working directory, and revealing files in the file manager
+- Includes a right-pane **Files** view rooted in folders allowed for the current Studio session, with an **Allow folder…** action and location selector; exact-file grants can still be opened independently without exposing their parent folders. Files supports sorting by name/modified time/size, opening folders or the current root in Finder/the system file manager, loading text/code/CSV/TSV documents into the editor, previewing PDFs/images, opening previews in new Studio tabs, converting DOCX/ODT documents to editable Markdown when Pandoc is available after confirmation, copying paths, setting the current folder as the Studio working directory, and revealing files in the file manager
 - Imports detached text-file copies either through the browser's file picker or from a path on the computer running Pi, keeping the path option available in embedded and remote browser views; imported copies remain detached until saved or opened as file-backed documents
 - Includes an optional tmux-backed **REPL** view for Shell, Python, IPython, Julia, R, GHCi, and Clojure sessions, with Raw/Literate send modes, `Cmd/Ctrl+Shift+Enter` **Send to REPL**, session start/stop/interrupt controls, a compact refresh-persistent **Studio REPL Record** of user and Pi-sent code, a secondary raw tmux mirror, agent-facing `studio_repl_status` / `studio_repl_send` tools, and Markdown/PDF/HTML export
 - Includes a local persistent scratchpad for quick notes you want to keep out of the main editor until you're ready to copy or insert them, with a **Recent…** picker for recovering scratchpads saved under earlier file/draft identities
@@ -52,10 +54,10 @@ _The video shows an earlier version of the Studio interface. The basic workflow
   - shows/hides annotation markers in preview
   - strips markers before send (optional)
   - saves `.annotated.md`
-- 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
+- Renders Markdown/LaTeX/code previews (math + Mermaid) plus lightweight CSV/TSV table previews, theme-synced with pi, with an explicit H1–H6 hierarchy, zoomable images across Studio-owned Markdown surfaces, and copy buttons for code blocks and blockquotes; already allowed local media loads silently, while blocked images and embedded PDFs remain unloaded behind an explicit per-file or containing-folder allow action; 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 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
+- Embeds local PDFs in Studio Markdown previews via explicit `studio-pdf` fenced blocks and opens existing PDFs directly with `/studio <path.pdf>`, with visible enlarge, browser-tab, system-viewer, show-in-folder, copy-path, manual refresh, and opt-in stable-file auto-refresh actions; true browser fullscreen is offered only when the browser supports it
 - 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.
@@ -111,10 +113,10 @@ Open **Review → Side question**, select **Side questions** in the right pane,
 - **Starting text** controls what unsaved text begins the thread. The compact **Automatic: selection → heading block at cursor → nearby text** disclosure explains the fallback order; when expanded, it defines the heading boundary. The summary below reports the resolved starting text, editor line range when applicable, and character count separately from the related-file scope.
 - Explicit **Editor selection only** no longer falls back to the whole document when no text is selected; the summary instead reports that no editor text is selected.
 - In the initial-question and follow-up boxes, **Cmd/Ctrl+Enter** submits while plain **Enter** adds a new line. The button remains available for pointer and ordinary keyboard activation.
-- **Also use files from** controls the read-only boundary available to the side agent: no other files, the document folder, the current repository, or another chosen folder.
+- **Also use files from** controls the read-only boundary available to the side agent: no other files, the document folder, the current repository, or another chosen folder. Related-file access requires an allowed folder for the current Studio session; if the selected root is not already allowed, Studio names the canonical folder and asks before starting the thread. An exact-file grant never exposes its parent folder.
 - With **Repository** selected, **Include Git context** can capture status, staged and unstaged tracked-file changes, and up to 20 recent commit summaries. The bounded snapshot is frozen when the thread starts and exposed through fixed read-only tools; untracked contents remain available only through the existing root-confined file reader.
 - **Include the current main conversation snapshot** is opt-in. Side questions and answers otherwise never enter the main Pi history; **Bring to main conversation** is the explicit handoff.
-- Local context tools can map filenames, search readable text, and read selected ranges. Symlinks and traversal outside the chosen root are rejected. PDF extraction uses `pdftotext`; DOCX, ODT, and EPUB extraction uses Pandoc.
+- Local context tools can map filenames, search readable text, and read selected ranges. Studio revalidates the allowed context root before prompts and built-in local tool calls; symlinks, root replacement, and traversal outside that root are rejected. PDF extraction uses `pdftotext`; DOCX, ODT, and EPUB extraction uses Pandoc.
 - **Allow web search** is opt-in and appears when `BRAVE_API_KEY` is available to the Pi process. Model-chosen search queries are sent to Brave Search; the side agent is instructed not to copy private local passages into queries. Web answers cite result URLs and identify when they rely on search-result snippets rather than full page content.
 - **Additional Pi tools** lists eligible tools already registered by the user's installed Pi extensions. Selection is explicit, remembered locally, and frozen when the thread starts. Studio reloads only the extensions owning the selected tools into the isolated side runtime and activates only those tool names; it does not import or depend on any particular third-party extension. Gateway tools are labelled and require an additional confirmation because selecting one may expose further services configured behind it.
 
@@ -122,7 +124,9 @@ The current side thread is ephemeral but survives Studio browser refreshes while
 
 ## Studio Markdown extras
 
-Studio previews standard Markdown, code fences, display math, Mermaid, and local images. When adding companion files such as generated plots or PDFs, prefer the project's existing folder convention. If there is no convention, `attachments/` is a reasonable default for newly generated assets. Use relative paths from the opened Markdown file or Studio working/resource directory, and wrap paths in angle brackets when spaces are possible:
+Studio previews standard Markdown, code fences, display math, Mermaid, and local images. The opened document directory and other explicitly allowed folders are available for local preview resources during the current Studio session. Media already inside those locations loads without interruption. An image or embedded PDF outside them stays unloaded and shows **Allow local image/PDF…**; activating that control offers an exact-file grant, a containing-folder grant for the session, or cancellation. Passive rendering itself never opens the permission decision.
+
+When adding companion files such as generated plots or PDFs, prefer the project's existing folder convention. If there is no convention, `attachments/` is a reasonable default for newly generated assets. Use relative paths from the opened Markdown file or a folder allowed for the current Studio session, and wrap paths in angle brackets when spaces are possible:
 
 ```md
 ![Short descriptive caption](<attachments/plot.png>)
@@ -141,7 +145,7 @@ 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, `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.
+`path` must point to a local `.pdf`. Relative paths resolve from the opened document's directory, or from Studio's working directory for non-file-backed content; the resolved file must be inside a location allowed for the current Studio session before it loads. `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.
 

package/ROADMAP.md

@@ -0,0 +1,87 @@
+# Pi Studio roadmap
+
+This is the current planning source of truth for Studio work. `NEXT-STAGE.md` is historical; `TODO.md` tracks smaller backlog items that are not yet assigned to a release.
+
+## Release approach
+
+Studio development follows two tracks:
+
+- **Stable `0.9.x` releases** contain one coherent family of fixes or incremental features and keep `main` releasable.
+- **`0.10.0`** is reserved for the buffer-first document architecture. Risky prereleases should use the npm `next` tag before replacing `latest`.
+
+Changes should be based on capabilities rather than browser, terminal host, or user-agent detection. Muxy, ordinary Chromium browsers, embedded WebKit views, and SSH/headless use are validation environments, not separate product variants.
+
+Each release should finish with:
+
+1. focused regression tests plus the full test suite;
+2. TypeScript and JavaScript syntax checks;
+3. production dependency audit;
+4. exact package-content and byte-level artifact audit;
+5. a fresh npm installation and naturally rendered Studio smoke test.
+
+Publishing, pushing, and tagging remain explicit release actions rather than automatic consequences of merging work.
+
+## 0.9.52 — Rendering and media consistency (shipped 2026-08-28)
+
+A focused portability and affordance pass:
+
+- scope application-header typography so it cannot override rendered Markdown;
+- define an explicit, visibly ordered H1–H6 scale;
+- apply image focus consistently across Studio-owned same-document Markdown surfaces;
+- give embedded PDF cards and rendered PDF figures an obvious enlarge action;
+- expose true browser fullscreen only when the Fullscreen API is available, while retaining Studio's in-page focus viewer everywhere;
+- make local PDF actions clearly refer to the computer running Pi and provide **Copy path** alongside system-viewer and file-manager actions.
+
+This release must not add Muxy-specific branches or attempt to instrument opaque Quarto/authored-HTML iframe contents.
+
+## 0.9.53 — Resource locations
+
+Status: implementation and release-candidate validation complete; push, tag, and npm publication await explicit approval. The bounded canonical workspace registry now governs explicit local links, the Files view, passive images/PDFs, and Side questions' related-file roots.
+
+Replace the single-root assumption with explicit resource grants:
+
+- grant the current document directory automatically;
+- allow an exact file or additional folder to be granted explicitly;
+- keep grants session-scoped by default;
+- store canonical server-side paths and retain traversal and symlink-escape checks;
+- use the same grants for Markdown resources, local links, PDFs, Files view, and Side questions;
+- keep passive local media unloaded without opening a permission decision, then offer the exact-file/folder choice only through an explicit blocked-media action;
+- explain that paths, Finder/file-manager actions, and system viewers belong to the computer running Pi;
+- offer **Allow this file**, **Allow this folder for this Studio session**, and **Cancel** when an explicit local link crosses the current boundary.
+
+The resource-location registry should be workspace-level rather than tied to the current editor document so it remains compatible with multiple buffers. Remembering grants per project can follow after the session-only model is proven.
+
+## 0.9.54 — Disk-backed preview and safe save
+
+Planned after resource locations stabilize:
+
+- distinguish editable buffers, whose in-memory text drives Editor Preview, from read-only watched previews, whose file on disk is authoritative;
+- add a read-only **Preview file (follow changes)** workflow using the proven debounce, content-hash, atomic-save, preserved-scroll, and last-good-render behaviour from `pandoc-glance` / `pi-markdown-preview` without making Studio depend on another extension;
+- retain a canonical disk revision for file-backed editing, save directly with **Cmd/Ctrl+S** only while that revision still matches, and offer an explicit conflict decision when the file changed externally;
+- add **Cmd/Ctrl+Shift+S** for Save As and keep autosave opt-in rather than default;
+- carry the resulting disk identity and revision model forward into `StudioBufferStore`.
+
+## 0.10.0 — Buffer-first editing
+
+The first architectural `0.10` release should add:
+
+- a `StudioBufferStore` with stable document identity;
+- recovery schema v2 with migration from the single-document schema;
+- buffer-specific text/baseline, dirty state, cursor, selection, scroll, preview context, annotations, and resource directory;
+- tabs at ordinary widths and a compact searchable buffer picker at narrow widths;
+- MRU cycling, next/previous, close, and reopen commands;
+- originating buffer ID and revision targeting for asynchronous Pi work.
+
+PDFs remain preview documents, and conversation history remains session-global. Split panes, arbitrary layouts, project trees, and simultaneous per-buffer Pi conversations are outside the initial `0.10.0` scope.
+
+## Validation matrix
+
+Cross-environment checks should cover, where relevant:
+
+- full and editor-only Studio;
+- file-backed and detached documents;
+- ordinary Chromium and embedded WebKit browser surfaces;
+- local, SSH, and `--no-browser` Pi sessions;
+- paths with spaces, Unicode, traversal attempts, and symlinks;
+- supported and unavailable browser APIs;
+- browser reconstruction, refresh recovery, and clean shutdown.