pi-studio 0.9.50 → 0.9.52

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [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
+- Add a Studio-native **Side questions** right-pane thread that runs independently of the main Pi conversation, supports follow-ups and explicit copy/insert/promote actions, and keeps the side exchange out of main history unless the user chooses **Bring to main conversation**.
+- Separate the starting-text snapshot from progressive file access: side threads can start from an editor selection, Markdown/LaTeX heading block, nearby text, whole editor, displayed response, or no starting text, then selectively map, search, and read a bounded document folder, repository, or chosen folder through root-confined read-only tools.
+- Add opt-in Brave web search with cited result URLs, plus read-only text extraction for local PDF, DOCX, ODT, and EPUB context when the corresponding command-line dependency is available.
+- Let side threads use an explicit, remembered selection of eligible tools already registered by installed Pi extensions. Studio resolves each selected tool through Pi's provenance metadata, loads only its owning extension into the isolated side runtime, freezes the allowlist for the thread, labels and separately confirms gateway tools, and has no package-specific dependency on an MCP or research extension.
+- Add opt-in, thread-frozen Git context for repository side questions: bounded status, staged and unstaged tracked-file diffs, and up to 20 recent commit summaries are exposed through fixed read-only tools rather than arbitrary command execution.
+- Add explicit side-thread export with Markdown as the canonical durable format: save or copy the visible transcript, open it as an unsaved editor copy, or render it to PDF or HTML without silently persisting hidden source context or raw tool output.
+
+### Changed
+- Keep the editor-only header destination labelled **Side questions**, while full Studio continues to group its broader critique, explanation, quiz, and side-question actions under **Review**.
+- Add **Cmd/Ctrl+Enter** submission for the initial side question and follow-ups while keeping plain **Enter** for multiline text and retaining the submit buttons; add **Cmd/Ctrl+Alt+Q** as a mnemonic direct switch to the Side questions view.
+- Rename the **Ask aside** action to **Side question**, replace ambiguous current-section wording with a compact **Automatic** rule disclosure and separate **Starting text** / **Related files** summary rows, prevent an empty explicit selection from falling back to the whole document, and keep primary side-question buttons readable on hover.
+- Align Studio's Pi SDK development/runtime compatibility dependencies with Pi 0.84.3 and declare that minimum host version for isolated selected-extension lifecycle support.
+- Update the direct `ws` dependency to 8.21.3, which includes the current memory-disclosure and fragment-exhaustion fixes.
+
 ## [0.9.50] — 2026-08-25
 
 ### 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)
@@ -28,11 +30,12 @@ _The video shows an earlier version of the Studio interface. The basic workflow
 
 ## What it does
 
-- Opens a two-pane browser workspace: **Editor** (left) + **Response/Working/Editor Preview/Quarto Preview** (right)
+- Opens a two-pane browser workspace: **Editor** (left) + **Response/Working/Editor Preview/Quarto Preview/Side questions** (right)
 - Supports one canonical full Studio view per Pi session, plus additional editor-only companion views when you want extra editing/preview surfaces; editor-only views can also browse files and use the Studio REPL send controls without taking over the full Studio session view
 - 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
-- 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–7` 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
+- 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 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
 - 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
@@ -51,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; 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.
@@ -103,6 +106,22 @@ Run once without installing:
 pi -e https://github.com/omaclaren/pi-studio
 ```
 
+## Side questions and research context
+
+Open **Review → Side question**, select **Side questions** in the right pane, or press **Cmd/Ctrl+Alt+Q**. A new side thread captures its starting text while keeping related-file access separate:
+
+- **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.
+- 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.
+- **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.
+
+The current side thread is ephemeral but survives Studio browser refreshes while the same Pi Studio server remains running. **Export thread** can save the visible discussion and context summary as Markdown, copy that Markdown, open it as an unsaved editor copy, or render it to PDF or HTML. Markdown is the canonical durable format; exports omit hidden starting-text contents, inherited main-conversation contents, and raw tool output. Studio never supplies the side agent with shell or file-writing tools, and known execution/mutation surfaces are excluded from the picker. Selected third-party tools retain their own behavior, permissions, and downstream scope, so choose tools you trust for read-only research.
+
 ## 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:
@@ -162,6 +181,7 @@ Studio only passes icon-pack arguments when a diagram actually references `lucid
 - Installing pi-studio makes the optional `pi-studio-dark` and `pi-studio-light` themes available in pi's theme selector; it does not change your active theme.
 - Editor/code font uses a best-effort terminal-monospace match when the current terminal config exposes it; set `PI_STUDIO_FONT_MONO` to force a specific CSS `font-family` stack. Use `PI_STUDIO_FONT_UI` or `PI_STUDIO_FONT_PROSE` to override the Studio UI or rendered-preview font stacks.
 - The optional REPL view requires `tmux`. Studio can start and stop Studio-owned `pi-studio-repl-*` sessions and can mirror detected `pi-repl-*` sessions, but it will not stop external `pi-repl-*` sessions.
+- Side-question web search requires `BRAVE_API_KEY`; without it, local and conversation context still work, and the web option is shown as unavailable. Side sub-sessions are deliberately read-only and can run independently while the main Pi agent is busy.
 - Full preview/PDF quality depends on `pandoc` (and `xelatex` for PDF):
   - `brew install pandoc`
   - install TeX Live/MacTeX for PDF export

package/ROADMAP.md

@@ -0,0 +1,74 @@
+# 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
+
+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
+
+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;
+- 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.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.