pi-studio 0.9.63 → 0.10.1

package/BUFFER-DESIGN.md

@@ -0,0 +1,197 @@
+# Active Prompt and editable document buffers
+
+**Hosting follow-up — 2026-09-27:** the uncommitted development checkout now includes separately approved single-owner Document hosting, behind recovery + switching + `PI_STUDIO_DOCUMENT_HOSTING=1`. Prompt stays anchored; move, detached copy, registered blank/text-file opening and existing-owner reuse are distinct operations. Uncertain operations retain their original identities/backups, and Save As metadata attachment requires a prepared receipt. Unsafe legacy entrypoints are explicitly unavailable in this prototype; see [README.md](README.md#additional-opt-in-prototype-single-owner-document-hosting). Source-tree validation does not establish acceptance of an exact alpha package; candidate-scoped artifact and private-install evidence is recorded separately. Finish the [remaining gates](PRERELEASE-CHECKLIST.md#additional-hosting-scope-and-remaining-gates) before packaging/release acceptance; defaults and normal Studio remain unchanged. The earlier status entries below describe their own checkpoints.
+
+**Earlier status — 2026-09-22:** the tested fixed-slot workflow is committed through `40d4462`. Bounded local preparation of `0.10.0-alpha.1` is approved; publication, further commits and installation/default changes are not. The latest checkpoint has 240 focused passes and qualified native pane-scroll confirmation; earlier full-suite/browser counts below belong to their historical checkpoints. Whole-document/composed-Prompt hands-on trials and subsequent ownership fixes are recorded in [ROADMAP.md](ROADMAP.md). Blank-looking Working remains unreproduced and is an explicit local-alpha limitation. The alpha's activation/rollback instructions are in [README.md](README.md#local-alpha-one-prompt--one-document).
+
+**Toolbar follow-up — 2026-09-23:** Oliver approved a bounded cleanup after trying the exact first alpha. The uncommitted rebuild groups **Add to Prompt → Selection / Whole document** and **Open / load**, labels the replacement destination, and removes permanent help/Run-target rows. Selection ownership is preserved through the Add disclosure, not revived after another field/preview. Capacity and disabled-state explanations remain available in the opened menu and action tooltips. This changes no buffer roles, source-loading semantics, defaults or companion behaviour; new artifact evidence is recorded separately from the first candidate.
+
+**Historical status, 2026-09-11:** the foundation and annotation-header compatibility checkpoints are locally committed. A subsequent **one Prompt ↔ one document prototype** is implemented and tested as a local, unreleased checkpoint. It requires both `PI_STUDIO_BUFFER_RECOVERY=1` and `PI_STUDIO_BUFFER_SWITCHING=1`, in a full editable workspace. A separately approved local checkpoint allows switching during an identified direct Run, with 500 passing tests and isolated Brave/Chrome regressions, including the separately approved fixes for stale branch responses and hidden activity-follow state. That checkpoint subsequently passed an isolated live-model hands-on trial. A separately approved **Add selection to Prompt** slice is now a local, unreleased checkpoint: 522 tests and isolated, credential-free Brave/Chrome checks pass after an independent read-only review and separately approved fixes for literal-label boundaries and stale selection presses. No live-provider trial or independent post-fix sign-off is claimed for the selection slice. The earlier Safari evidence covers the foundation, not this switcher. The selection checkpoint subsequently passed a credential-free hands-on trial; Oliver confirmed it worked, and both drafts were backed up before stopping. A separately approved **Add document to Prompt** follow-up is now a local, unreleased checkpoint: 549 tests and twenty isolated Brave/Chrome runs pass after an independent read-only review and separately approved fixes for stale file-open control state and cancelled-press handling. No independent post-fix sign-off or hands-on trial of this follow-up is claimed. Installed Studio, package version and defaults remain unchanged. Updated 2026-09-11.
+
+[ROADMAP.md](ROADMAP.md) owns release scope. `0.9.60` is released; implementation of the store/recovery foundation was approved afterward with the visible UI unchanged. Oliver approved a local checkpoint commit on `feature/buffer-recovery-foundation` on 2026-09-09, without release or default-activation authority. This note records the design and acceptance criteria, not a final wire protocol. The initial module/API boundaries and remaining integration work are in [shared/STUDIO_BUFFER_FOUNDATION.md](shared/STUDIO_BUFFER_FOUNDATION.md).
+
+## Purpose
+
+Studio is primarily a prompt-writing and response-reading workspace. Editable documents and good previews support that loop; Studio does not need to replace Neovim.
+
+The distinction is not whether documents are editable. It is whether selecting a document changes what Run will submit. It must not do so implicitly.
+
+Use **one clearly active Prompt, other prompt drafts that can be parked, and independently editable documents**. Multiple drafts share the Pi conversation; they are not independent chats.
+
+## Current prototype — before general tabs
+
+Oliver approved continuing from the visual guide with a small switching prototype, not the entire interface below. Its two fixed entries are **Prompt** and **Document**:
+
+- A Prompt may be file-backed. Fresh file launches and v1 migration retain the visible editor's file-to-Run intent. Recovering an older v2 file beside a pristine empty Prompt asks **Use file as Prompt / Keep separate Prompt / Cancel**; emptiness alone is not role-change consent.
+- Selecting Document preserves the Prompt. **Open / load → Open file in Document…** and Files' open-here action use the separate document slot. Replacing valuable text requires current consent; reopening its exact canonical path preserves its in-memory edits. **Files → Use as Prompt…** is a separate, explicit file load, not a copy of the other buffer's unsaved text.
+- When idle, Document view offers **Return to Prompt**, with no submission. A separate Run sends the reviewed Prompt, including a file-backed one. Key repeats (including native held Enter with the Prompt editor in Preview) and double-click continuation cannot turn Return into Run. A fresh activation after key release still works; ordinary textarea repeats are unchanged. Existing annotation send/strip behaviour remains.
+- Each buffer retains its text, source, disk baseline/revision, metadata associations, selection, vertical reading positions and preview choices. Response history is still shared. Background history and Follow activity do not steal Document's preview; response-to-editor actions are unavailable there. Returning to a Follow-on Prompt applies a queued response and starts that new response at the top. Follow-off, or returning without a queued update, preserves the earlier response selection and reading position.
+- An identified direct Run on a connected socket permits selecting either existing buffer. The submitted text/source snapshot remains owned by Prompt. **Stop** stays global; the Prompt tab and Run shortcut can return without stopping or steering. Save, file opening/replacement, recovery/reset, unresolved Pi-draft disposition and other local-operation/modal locks remain. Unknown busy states and disconnected/reconnecting sockets do not gain this exception.
+- A response completed in Document waits for Prompt's Follow policy. Explicit Pi tree changes discard the previous branch's queued response; ordinary empty history still permits a current response's payload fallback. History updates do not rebuild Document's live preview or discard interactive iframe state. Returning during the same Run restores its activity-follow ownership or manual opt-out; completing elsewhere retires only the automatically selected Working view. Disabling Follow activity revokes live and saved ownership. Explicitly re-enabling can follow the exact ongoing Prompt request on return without moving Document's view or reviving finished work. Late error/busy results retire their own pending snapshots without unlocking a newer Run.
+- Switching still refuses stale continuations. Whole-pair recovery keeps both buffers; **Reset both buffers** explicitly confirms its scope. Other collections remain retained/exportable rather than being partly adopted.
+
+There is no create/close/park manager, automatic context copying, companion transfer, or non-destructive annotation parking yet. Editing Document does **not** add its edits to the Prompt when returning. Ordinary manual copy/paste remains available. The prototype tests the interaction and preservation boundary; its two-entry strip is not a settled design for many documents. Recovery remains temporary, not a durable draft library.
+
+## Local editor-selection slice
+
+**Add to Prompt → Selection** is an explicit action in the two-buffer strip, available for selected text in Document's editor. It appends the exact in-memory substring, with a literal source label and editor-line range, to the existing Prompt. It does not reread disk, trim the selection, replace the Prompt, switch buffers, save a file, or submit/steer a Run. Document stays selected. Normal recovery persistence still applies to the pair.
+
+The addition is ordinary editable Prompt text; it can be revised or removed there. Each buffer retains its own source, baseline/disk revision, metadata, annotation policy, resources and reading positions. No terminal fingerprint or submission authority comes from Document. During an identified connected Run, an addition prepares the **next** draft; it does not change the already submitted snapshot. Unsafe local work, recovery/modal ownership, unresolved terminal disposition and disconnected/reconnecting states block copying.
+
+The action captures pointer/keyboard intent and rechecks the source, selection owner/range, connection and destination revision. A stale press is not recaptured against a new buffer; held Enter/Space and double-click continuation do not duplicate the addition. Observed range/direction changes and new source focus, pointer or key gestures advance a monotonic owner, so selection A→B→A cannot revive a held press. Preview/iframe/other-field interactions retire the old editor selection as a copy source; select in the editor again. Keyboard focus on the action itself and delayed notifications of its unchanged captured range remain valid.
+
+Source labels are literal code spans, not links or new file grants. Boundary backticks are separated from the delimiters with paired padding, including names supplied through Import file copy, so filename syntax does not become rendered media or links. Line numbers refer to the selected **editor snapshot**, including unsaved edits. Only text is copied: relative resources still use Prompt's own resource context. Existing per-buffer and aggregate limits include the addition and its label; overflow is rejected without partial insertion or eviction. Recovery errors do not roll back or discard an accepted in-memory addition, and existing recovery warnings remain.
+
+Whole-document actions remain separate from selection copying; the local follow-up below does not relax selection ownership. Preview selections, companion transfers, a new undo/history library and general tabs remain deferred.
+
+## Local whole-document append follow-up
+
+**Add to Prompt → Whole document** appends the full selected Document's raw-editor text, including unsaved edits, with a literal **whole document, snapshot** source label. No selection or prior editor focus is required; the action never temporarily selects all, rereads disk or extracts rendered content. It requires the same two opt-ins/full editable mode, and is unavailable in Document Preview/Quarto view. Empty text is refused; whitespace-only text is preserved exactly.
+
+A description in the Add menu and action tooltip reports the complete addition size, including framing, and remaining capacity in UTF-16 string units. It uses the smaller of Prompt's 900,000-unit text headroom and the workspace's 3,000,000-unit aggregate headroom, including baselines. These are editor/recovery limits, not model-context estimates. Oversized additions are refused without truncation or eviction; execution rechecks the destination and capacity.
+
+The append changes only Prompt text/revision and normal workspace/recovery bookkeeping. Both origins, file baselines/revisions, resources, metadata and views remain independent. Document stays selected without a caret/selection/scroll change or preview reconstruction; nothing is saved or sent. The existing identified-Run exception permits next-draft preparation only. Current source/destination revisions, editor/connection consent and a separate interaction generation reject stale held presses, including edit/undo and buffer round trips. Repeats and double-click continuation add once; fresh activations may add again. No selection-owner permission is created for the existing selection action. Local-operation, recovery, modal and terminal-disposition fences remain.
+
+Pending file opens refresh both append controls on entry and cleanup, including stale/error outcomes; an older completion cannot enable them over a newer pending owner. Pointer and keyboard continuation leases stay separate: a fresh click-only activation does not consume a cancelled pointer press, and cannot authorize its later continuation. A completed keyboard lease retires after keyup's native activation task, with a generation check so older cleanup cannot clear a newer press.
+
+This is a local, unreleased checkpoint, not companion transfer, parked prompts or general tabs.
+
+## Proposed next slice: explicit Prompt role
+
+Prompt is an explicit submission role a document can take, independent of file backing, annotations and preview mode. After the fixed-slot alpha, separately scope switching that role between the existing buffers while preserving the previous Prompt. **Annotate** should continue editing the current document; an in-place **Use as Prompt** operation should retain its identity/annotations and send nothing; **Make a prompt copy** should create independent text instead. These are design directions, not implemented alpha controls. The existing Files action loads saved file text, not an in-place promotion of unsaved Document.
+
+Retain document annotation/comments and the editor's available space. The bounded control regrouping above is approved; heading changes and general role switching remain separate proposals. Role switching should be tested for ownership and preservation before adding more documents or companion handoff.
+
+## Intended interaction model
+
+An illustrative later tab strip:
+
+```text
+[ Prompt ▾ ]  [ notes.md • ]  [ script.py ]
+```
+
+- **Prompt:** the active prompt text alongside the session's response/Working views. Editor Preview remains available for prompt formatting and annotation.
+- **Document:** editable source alongside that document's preview. Text, selections, scroll positions, dirty state, and preview choices survive switching away and back.
+- **Prompt picker:** create, park, rename, and switch prompt drafts without discarding the previous one. Keep one active submission destination visible; do not add a separate conversation per draft.
+- **Companions:** existing editor-only browser views remain useful and independently recoverable. They can contribute context to the full workspace without becoming additional full Studio views.
+
+Opening, selecting, saving, or closing a document does not change the active prompt. A document becomes prompt material only through an explicit copy/handoff or an explicitly chosen Prompt file load. A detached context copy has no write-back link to its source; an explicitly file-backed Prompt retains its normal Save behaviour.
+
+Run in Prompt view submits the active prompt, retaining annotation send/strip behaviour. Initially, document views offer **Return to prompt** rather than implicitly submitting the document or sending a hidden prompt. Do not couple this architecture to a global Run-shortcut redesign; preserve the existing REPL and Side question composer bindings.
+
+Response history remains session-global. Restore the prompt's response position on return instead of treating a file preview as a new conversation, except when its enabled Follow setting applies a queued response. Follow activity must not switch away from a manually selected document or steal its preview.
+
+## Context transfer
+
+Two explicit actions in the wider design:
+
+- **Add selection to prompt:** the local slice above implements exact editor-selected text with its source label and editor-line range. Preview extraction is not implemented.
+- **Add document to Prompt:** the local whole-document follow-up implements full raw-editor snapshots with a visible size/capacity check. This is the append-only action previously called **Copy document to prompt** in the wider design; it never replaces an existing Prompt. Preview extraction and companion handoff remain future work.
+
+Use ordinary editable text rather than a new opaque attachment format. Capture the displayed in-memory text, including unsaved edits, rather than rereading disk. Detached sources need a useful label but must not invent a file path or line range. Source labels describe provenance; they do not imply that the copy remains synchronized or grant new file access.
+
+After the handoff:
+
+- prompt annotations affect only the copy;
+- subsequent source edits do not update the staged text;
+- nothing is submitted to Pi;
+- the existing prompt text remains intact, and the insertion can be undone or removed;
+- the source editor and its selection remain available.
+
+For editable companion views, send a bounded transfer request to the same Pi process and explicit destination prompt. The destination owner applies the insertion against current state; do not replace its whole prompt with a stale text snapshot supplied by the companion. Acknowledge only after application, and deduplicate retries by transfer ID. If the full workspace is unavailable, the selected destination changed, or acceptance is uncertain, retain source text and report that state rather than silently retargeting or duplicating the insertion.
+
+Initially, editable documents/companions are the transfer sources. Keep watched-preview sockets read-only; do not broaden their mutation permissions to reuse the new action. Existing copying from watched/PDF previews remains available separately.
+
+## Buffer model and ownership
+
+Introduce `StudioBufferStore` behind the existing editor/preview surfaces before adding the tab UI. The following are design requirements, not fixed serialized field names:
+
+| State | Responsibility |
+| --- | --- |
+| Stable buffer ID | Identity independent of tab order, file label, or selected view |
+| Role | Prompt or document; not inferred solely from whether a path exists |
+| Selected buffer ID | Which editor/preview the user is viewing |
+| Active prompt ID | Which draft is the explicit submission/context destination |
+| Text revision | Monotonic in-memory edit identity for async targeting |
+| Text and baseline | Current text, dirty comparison, original source/draft identity |
+| Disk identity | Canonical path and expected disk revision for file-backed saves |
+| View state | Cursor/selection, source and preview scroll, language, preview mode |
+| Local metadata | Annotations/review-note associations and resource context |
+
+Keep existing canonical file checks and workspace-level resource grants. Two snapshots referring to a file must not bypass disk-revision conflict detection. Closing dirty documents or discarding prompt drafts must require a deliberate choice; reopen/recovery must not silently substitute the current contents of disk for unsaved text.
+
+The full workspace owns its active prompt and draft selection. Companion workspaces retain their own documents; adding context is an explicit operation, not continuous shared-text synchronization. Resource grants and the exact-tmux-lifetime Shared REPL Record do not become buffer-owned.
+
+## Browser-tab continuity
+
+Internal tabs complement, rather than replace, browser tabs/windows. Internal tabs will switch Prompt/documents inside a workspace; browser companions and previews remain useful for simultaneous viewing and other screens. Preserve existing browser-opening actions while implementing the new controls.
+
+Separate browser editors initially remain independent snapshots, not live-synchronized mirrors. Keep canonical-path/disk-revision conflict checks. Future labels such as **Open in Studio tab** and **Open in browser tab** should make the distinction explicit. A true pop-out of an editable buffer must preserve its unsaved text; merely reopening its disk file is not equivalent. Linked pop-outs and live synchronization are not required for the first batch.
+
+With switching off, the transitional single-editor adapter deliberately keeps Run using the visible editor, even when file migration creates a selected document plus an empty active Prompt. The separate switching opt-in changes the controls and submission guard together: Return first, then Run the visible Prompt. A hidden Prompt must never become the accidental submission destination.
+
+## Recovery and asynchronous work
+
+### Recovery schema v2
+
+Persist bounded buffer collections, active/selected identities, ordering, and per-buffer state. Define per-buffer and aggregate limits; reject oversize updates visibly rather than truncating or evicting a live dirty buffer to make room.
+
+Migrate schema v1 without changing disk or losing text:
+
+- a detached editor in full Studio becomes the initial prompt draft;
+- a file-backed editor becomes a document, retaining dirty text and the disk revision it was based on, with a separate empty Prompt;
+- editor-only views retain their document role and cannot become additional full workspaces;
+- preserve the recoverable v1 payload until a complete v2 snapshot has been validated and stored successfully.
+
+Those are the low-level migration rules, also retained by foundation-only mode. The switching adapter then preserves fresh/v1 visible-file intent by making that file the Prompt, without changing its text, source or unknown recovered baseline. Older v2 role changes require the explicit choice described above.
+
+Exercise all legacy source kinds in migration tests. Malformed or future schemas must fail conservatively with a recovery path, not silently reset dirty work. Keep recovery scoped to the existing browser-tab/workspace identities and resource authorization.
+
+Current recovery uses browser session storage plus a bounded in-memory server fallback. Schema v2 must not imply new durable storage or guaranteed Pi-restart recovery unless those are separately designed and tested. Prompt parking must clearly state the recovery lifetime it actually provides.
+
+### Async targeting
+
+Capture originating buffer ID, text revision, and request ID when starting a completion, preview, save, annotation replacement, or context transfer. Keep disk revision separate from the in-memory revision. A late result must not write to whichever buffer happens to be selected now, resurrect a closed buffer, or overwrite newer edits.
+
+Main Pi responses remain conversation events. Their arrival may update response history, but not overwrite a source document or select a different buffer without an explicit policy. A buffer-mutating result whose origin changed needs an explicit accept/retry path.
+
+Preserve the `0.9.59` Pi-terminal-draft handoff: cleanup eligibility stays transient and bound to the originating prompt/submission. Copying document text must not copy terminal cleanup authority. Clear Pi's composer only after an accepted Run and an exact unchanged terminal-text match; never on a context transfer, tab switch, or failed submission.
+
+## Draft replacement and annotation
+
+In `0.9.60`, add the separate Annotate shortcut and protect **unsubmitted or unsaved work**, without introducing this buffer model. Do not ask for confirmation merely because the editor contains text:
+
+- **No warning:** write a prompt → accepted Run → receive response → Annotate response, while the submitted prompt is still unchanged. Empty editors or an exact copy of the response likewise need no replacement warning when no unsaved file changes would be lost.
+- **Protect before replacing:** post-submission prompt edits, another unsent draft, edited response annotations, and unsaved file changes. Cancel leaves the draft and source/view state unchanged; existing save/copy paths can support keeping it before proceeding.
+
+Capture the raw editor text and source identity at submission time, correlate acceptance with that snapshot, and use it as the comparison baseline. A late acknowledgement or response must not mark the then-current editor text as submitted. Failed submissions do not establish the baseline, and a submitted file buffer can still have unsaved edits. This Studio-editor baseline is separate from the Pi-terminal-draft cleanup fingerprint.
+
+Test the confirmation-free normal loop as well as the guarded cases, failed submissions, and typing during acknowledgement/confirmation. Do not claim automatic draft parking in this release.
+
+In `0.10`, **Annotate response** can prepare a detached prompt draft while parking the unfinished active prompt. Copying a document to a prompt likewise leaves its file buffer independent. Resolve these operations through buffer identities rather than overwriting a global editor string.
+
+Neither operation edits the original response in conversation history or the source document. An asynchronous confirmation is not permission to overwrite text typed after it opened.
+
+## Implementation sequence
+
+1. **Store and recovery:** introduce buffer identities/roles behind the single visible editor; test schema migration, bounds, disk identity, and async targeting before exposing tabs.
+2. **Prompt/document switching:** first prove one Prompt ↔ one document with independent state and an explicit submission boundary (the current local prototype). Review file-open intent and Return/Run ergonomics before expanding to creation/closing, more tabs or a narrow-width picker.
+3. **Context handoff:** add document/selection snapshots and acknowledged editable-companion-to-prompt transfer, preserving drafts and source text.
+4. **Parked prompts and annotation:** expose the lightweight draft picker and non-destructive response-to-prompt annotation flow; add MRU/next/previous/close/reopen navigation.
+5. **Release validation:** run the full suite and fresh-package smoke matrix, including migration and browser reconstruction. Use npm `next` for architectural validation before explicit stable-release approval.
+
+Do not require an editor-engine migration, arbitrary pane layout system, or new REPL protocol to complete these steps.
+
+## Acceptance scenarios
+
+1. Start a prompt; edit `notes.md` with preview; append selected context; annotate the detached copy; inspect another file; return and Run. Preserve every draft, document edit, and reading position, and submit only the intended prompt.
+2. Compare two prompt formulations by parking/switching drafts. Run one without discarding the other or creating another Pi conversation.
+3. Add text from an editable companion while the main prompt is being edited. Apply once to the acknowledged destination; never lose intervening typing or append to a newly selected draft silently.
+4. Annotate a response while an unfinished prompt exists. Keep the old draft recoverable and leave the original response unchanged.
+5. Switch or close buffers during completion, rendering, saving, and confirmation. No late result writes into the wrong buffer or bypasses a stale disk revision.
+6. Refresh/reconstruct full and companion views, including with dirty files and parked prompts. Verify bounded recovery and non-destructive v1 migration under unavailable or malformed storage.
+7. Confirm Follow activity respects document navigation; watched previews remain read-only; REPL/Side question workflows and terminal draft cleanup retain their current authority boundaries.
+
+## Out of scope
+
+Replacing Neovim; CodeMirror/Monaco migration; arbitrary multi-pane layouts; project trees; per-buffer conversations or parallel main-agent runs; live attachment synchronization; collaborative document editing; Derived REPL Transcript; changes to protocol v1 or `pi-repl` package independence.

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.10.1] — 2026-10-14
+
+### Fixed
+- Between clicking **Run Prompt** and Pi starting, the button no longer flashes hollow, and the toolbar no longer drops a row and jumps back. The status beside Run now says "Starting…", with the detail kept in the footer; the button keeps its colour, dimmed, until it becomes Stop.
+
+### Changed
+- A shorter, plainer README with new screenshots. The npm package drops from about 8.4 MB to 1.8 MB.
+
+## [0.10.0] — 2026-10-14
+
+### Added
+- **Dual editor mode**, now the default: a **Prompt** for what you send to Pi, and a **Document** for the file you're working on. Each keeps its own edits, preview and reading position. Switch with the Prompt and Document tabs, or Cmd/Ctrl+Shift+1 and 2. Selecting the Document never changes what Run sends.
+- **Single editor mode** keeps the one-editor Studio. Switch from the footer (**Switch to single editor** / **Switch to dual editor**), or with `/studio --single` and `/studio --dual`. Studio restarts and reopens the tab, and the Prompt's text comes with you. The choice is kept per Pi profile. Studio won't switch while the Document or a closed Document window has unsaved text, other Studio tabs are open, or a run, save or side question is in progress; it says why.
+- **Add to Prompt** adds the Document's selection, or the whole Document, to the Prompt as a labelled copy, with Undo.
+- **Document windows:** open a file in a new Document window, or move or copy the Document to one, and find it again from **File**. Each file has one editor, and saving replaces the file atomically.
+- **Recovery:** unsaved Prompt and Document text survives reloads and dropped connections. After you close the tab, `/studio` reopens the same workspace; `--blank` and `--last` start afresh. A clean exit reopens without asking; otherwise Studio asks before resuming.
+- The **Files** pane lists files to open in the Document or Prompt, read, or show in their folder.
+- Links in rendered pages share one menu: Read, Open in Document, Open in Prompt, Show in folder, Copy path. Web links open in a new tab.
+
+### Changed
+- A two-row header: the file and its actions on the first row; the main action and tools on the second. The toolbars fit a 13-inch laptop.
+- **File** shows recovery items only while they apply.
+- **Follow** moves only between Response, Working and the Prompt preview. Files, Changes, the REPL and Side questions keep their place.
+- Side questions show the model and Thinking beside Ask. The REPL's send mode moves to its **More** menu.
+- Plainer interface text throughout.
+- In dual editor mode, `/studio-replace` moves the open Studio to a new tab here, for when it opened in another browser or a tab you can't find; opening its URL offers **Move it here** too. The old tab hands over its text first. `/studio-current`, editable `/studio-editor-only` and Office-to-Markdown opening aren't available in dual editor mode; use Studio's Document controls, or single editor mode.
+- Development checks typecheck against Pi 1.2.0.
+
+### Fixed
+- A pane's reading position could jump after you changed views, because an earlier scroll restore still ran.
+
 ## [0.9.63] — 2026-10-08
 
 ### Fixed

package/PRERELEASE-CHECKLIST.md

@@ -0,0 +1,100 @@
+# Opt-in two-buffer prerelease checklist
+
+Updated 2026-09-27. **Bounded local alpha preparation, the toolbar cleanup and the opt-in single-owner Document hosting work are approved.** The runtime/test base is `40d4462`; the selected local candidate is `0.10.0-alpha.1`. The follow-up implementation and documentation/package preparation remain uncommitted, and normal Studio remains `0.9.60`. Further commits, a live-model trial, pushing/tagging, publishing and changing the normal installation/default each need separate approval. This is a repository maintainer checklist, not a claim that every gate below has passed; fresh evidence accompanies the exact artifact outside the package.
+
+Work in the isolated `pi-studio-buffer-dev` checkout on `feature/buffer-recovery-foundation`. Keep the original `pi-studio` checkout frozen and the normal installation unchanged. Use new candidate-scoped evidence; old dirty-state/HEAD-pinned verifiers are historical, not scripts to repoint at a new build.
+
+## Scope of the earlier two-flag candidates
+
+The first local `0.10.0-alpha.1` candidate exposes the existing **one Prompt ↔ one Document** workflow only when both `PI_STUDIO_BUFFER_RECOVERY=1` and `PI_STUDIO_BUFFER_SWITCHING=1` are explicitly set for a full editable workspace. Neither flag becomes a default. The version was unused when npm was queried on 2026-09-22 (`latest: 0.9.60`, `next: 0.9.60-rc.0`). Recheck before any eventual publication to npm `next`, never `latest`.
+
+Included: independent editing/previews, switching during an identified Run, explicit selection/full-document snapshot appends, guarded response/critique loading, the leading-only Prompt annotation header, temporary recovery, and the accumulated ownership/reading-state fixes. The separately approved toolbar rebuild groups Add and Open/load actions and moves routine help into their disclosures/tooltips; keep its artifact/results separate from the first alpha.
+
+Excluded: role switching between existing buffers, companion-to-Prompt transfer, preview extraction, multiple documents, create/close/park controls, automatic preservation of an unfinished Prompt when annotating a response, durable draft storage, editor-engine migration and new REPL work. The full architecture in [BUFFER-DESIGN.md](BUFFER-DESIGN.md) remains a later target. These exclusions are not feature work to add to this alpha.
+
+## Additional hosting scope and remaining gates
+
+The development checkout adds a third opt-in flag, `PI_STUDIO_DOCUMENT_HOSTING=1`, effective only with both recovery and switching enabled. Earlier alpha/toolbar tarballs do not contain this work; their full-suite and fresh-install results are historical, not hosting-package acceptance. [README.md](README.md#additional-opt-in-prototype-single-owner-document-hosting) describes the controls and deliberate entrypoint restrictions.
+
+The approved addition is one editing owner per Document: move, detached copy, registered blank/text-file editor creation, existing-owner reuse, atomic text-file replacement and retained save/metadata resolution. Prompt remains anchored. The previous exclusions still apply to simultaneous linked views, Prompt-role migration, durable storage, editor migration and new REPL work. Keep this feature set fixed while closing the gates below.
+
+- [ ] Finish entrypoint and permission/resource checks, including trusted commands/tools, direct URLs, exports, watched mode, hosted Refresh and explicitly refused Office conversions. A retained identity or path hint must not grant access.
+- [ ] Cover remaining disconnect, cancellation/decline, reload, quota/storage-change and delayed source/metadata producers. A missing reply, failed focus or popup refusal must never authorize another independent Document.
+- [ ] Verify original Prompt text, metadata and terminal-consumption authority through each Document operation, including edits made while a reply is pending.
+- [ ] Validate default, recovery-only, two-flag and three-flag modes; watched previews stay read-only. Run the complete suite as well as the focused ownership tests and TypeScript.
+- [ ] Build a **new exact artifact**, audit every packaged file/import and test a fresh private installation of that artifact. Source-tree browser trials and the older toolbar package are not substitutes.
+- [ ] Record native fixture limitations separately from human/provider acceptance; preserve failures, backups, source hashes, resource samples and owned-only cleanup evidence.
+
+None of these gates authorizes a commit, publication, normal installation change or live-provider trial. The release process below still applies to the new artifact; do not mark it complete using results from an earlier candidate.
+
+## Historical evidence already available
+
+The following results belong to `7bdc891` or earlier checkpoints, not the `40d4462` pane-scroll follow-up described in step 1.
+
+| Evidence | What it establishes | Qualification |
+| --- | --- | --- |
+| 718 full-suite tests | Recorded pass on the committed runtime/test bytes | Not rerun on 2026-09-20; not an exact prerelease artifact check |
+| 202 focused tests, normal typecheck, syntax/whitespace and runtime-boundary checks | Fresh pass on 2026-09-20 | Supplemental check-JS remains nonpassing with 493 previously recorded, unchanged diagnostics |
+| 41 Brave checks; 29 Chrome-app + 12 Chrome Headless Shell 153 checks | All cases in the latest 41-case browser matrix have passing coverage | Chrome coverage spans two variants; historical Brave use is not the future automation policy |
+| Earlier hands-on/live-model and rendered-preview trials | Useful workflow evidence at their respective checkpoints | Earlier live-model and Safari-foundation results are not current switcher/provider or fresh-package sign-off |
+
+The final shell trial used a dedicated test binary, took 39 seconds and recorded 20 normal-pressure samples, peak sampled owned RSS of 863 MiB and no swap growth. Its archive was verified before disposal and its processes/listeners were checked stopped. This does not explain earlier Chrome-app startup failures or guarantee headroom for another run.
+
+Local evidence directories (ignored, not package contents): `context/recovery-review-20260920_215659/`, `context/chrome-headless-neighbour-20260920_220551/`, and `context/scroll-ownership-checkpoint-20260920_221223/`. Preserve the earlier settings-drift qualifications; do not claim uninterrupted historical preservation of the whole global settings file.
+
+## 1. Resolve the known release question
+
+Bounded triage was approved and performed on 2026-09-20: current production pane-activation/restore and view/trace-render functions reproduce stale scroll in deterministic VM scheduling, both before the first callback and before the second frame. Settled-frame, same-view and interactive-target controls pass. The pane-restore helper block is byte-identical to `0.9.60`. This establishes a separate older callback-ownership gap, not a new buffer regression or a native timing result. No content mutation occurred in these adapters; that is not a general data-preservation audit. Four warning-pressure samples refused a new browser launch. Local evidence: `context/pane-scroll-triage-20260920_230154/`.
+
+- [x] Choose and implement the separately approved narrow fix with failing regressions first. Pane snapshots retain DOM/view generations and recovery-mode editor/buffer consent without removing same-view or independent-pane restoration. Of 38 new VM cases, 29 failed before the change and 9 controls passed; all 38 now pass. Evidence: `context/pane-scroll-fix-20260920_232725/`. Product/tests were subsequently committed with approval as `40d4462`.
+- [x] Complete bounded native confirmation on 2026-09-21 after passing resource preflight. In dedicated Chrome Headless Shell 153, both immediate and before-second-frame windows move old Working from 10259px to 0 in default/two-buffer modes; the fix retains 10259px. Settled/same-view controls and unaffected-source offsets pass. Trusted pane input plus deliberately scheduled programmatic view changes isolate the windows without patching application functions/RAF; this is not human timing/frequency evidence. All 25 samples across six attempts stayed normal, peak sampled owned RSS 1026.75 MiB, no per-trial swap growth. Backup-before-disposal and process/port cleanup verified, including two retained harness-calibration failures. Evidence: `context/pane-scroll-native-20260921_225607/`.
+- [x] Rerun 240 focused tests, normal typecheck and syntax/whitespace/runtime-boundary checks after browser cleanup. Full suite/supplemental check-JS were not rerun; prerelease artifact gates below remain outstanding.
+- [x] Explicitly accept the separately reported **Working appears empty until interaction** as a documented limitation for local alpha preparation; final publication remains gated. Native view/buffer returns retained content, geometry and inspected screenshots before content interaction; the symptom remains unreproduced, not claimed fixed. Headless tab switching never made the page hidden, so true background-tab/visible-browser paint behaviour is unverified. No rendering/CSS workaround was added.
+- [x] Obtain separate checkpoint approval and commit only the scroll code/tests as `40d4462`. Local alpha preparation is approved; publication is not. Distinguish scroll movement, empty-looking painting and absent content from wrong submission destination or lost edits; do not infer those more serious outcomes from this bounded test. Data loss, unauthorized mutation or wrong-target submission must be fixed before publishing. Any accepted limitation needs Oliver's decision, not an implicit waiver.
+
+Stop this triage once that decision is supported. It is not a new whole-branch review or an invitation to add adjacent features.
+
+## 2. Define the candidate
+
+- [x] Approve the smaller alpha scope and choose unused `0.10.0-alpha.1` after checking the registry. Do not reuse or overwrite a published version.
+- [x] Align README, changelog and the status summaries in the design/foundation docs with the chosen scope. Distinguish historical milestones from current validation, including the two Chrome variants and the remaining timing decision.
+- [x] Document activation, expected behaviour with neither flag/only recovery/both flags, and unchanged editor-only/watched modes. No general tabs or parked-prompt promises.
+- [x] Explain recovery lifetime and rollback: session storage plus a bounded process-memory fallback are **not durable backup**. Save/export both drafts before closing a trial or returning to an older build; older UIs may not display experimental v2 copies. Preserve those copies rather than deleting them.
+- [x] Update package/lock versions together under preparation approval. Record base commit `40d4462` plus the exact candidate worktree/package file list and hashes; this is not yet a candidate commit.
+- [ ] Obtain separate approval before committing documentation/package changes. Do not repoint historical verifiers.
+
+## 3. Validate once against that candidate
+
+### Test setup
+
+- [ ] Start only with normal sampled memory pressure, stable swap, adequate disk headroom and no competing owned test jobs. Use one trial at a time; do not overlap browsers with full-suite/typecheck jobs. Stop/refuse if the resource budget is exceeded rather than weaken test expectations.
+- [ ] Select an existing, executable **test-only Chromium/Chrome Headless Shell** explicitly. Never use everyday Brave for unattended testing or silently fall back to another browser. Record the executable/version and use independent profiles, temporary files, agent state and ports.
+- [ ] Configure and verify `PUPPETEER_EXECUTABLE_PATH` before the full suite. `npm test` includes `test/studio-tab-launcher-browser.test.js`, whose current discovery falls back to ordinary Brave/Chrome if the supplied path is absent or invalid. Refuse the run unless the dedicated path is verified; an unconfigured full suite is not browser-free.
+- [ ] Prepare candidate-scoped launchers without changing the existing behaviour assertions. Keep model credentials/tools and shared REPL access disabled for synthetic checks. Do not use this coding session's global Studio tools to drive the private instance.
+
+### Automated gates
+
+- [ ] Run the full suite serially (`npm test -- --test-concurrency=1`) under the verified browser/resource setup. Record actual counts, failures and skips; do not assume the earlier 718 result covers a newly built artifact.
+- [ ] Run the focused ownership/scroll/append regressions, normal typecheck, client JavaScript syntax and whitespace checks. If supplemental check-JS is used, report its existing baseline separately and investigate new diagnostics; do not label the baseline as a passing check.
+- [ ] Run a production dependency audit. Resolve blockers or record explicit decisions; do not bundle unrelated upgrades into the candidate.
+- [ ] Pack the intended artifact, audit its complete file list and compare packaged runtime/assets to the candidate bytes. Include required modules and usable public documentation links; exclude `context/`, transcripts, recovery archives, private URLs, credentials and test profiles. Record the tarball hash/integrity and version.
+- [ ] Install **that tarball**, not a mutable checkout, in a fresh disposable location. Verify exactly one Studio extension loads from that installation, assets match the package, unauthenticated requests remain rejected, and no normal Pi settings/source entry is changed.
+
+### Fresh-install smoke and short workflow trial
+
+- [ ] In the private fresh installation, check the default, recovery-only and two-flag modes, plus editor-only and watched-preview compatibility. A targeted smoke is sufficient; identify any older evidence being reused and its scope.
+- [ ] Exercise: start Prompt → edit a disposable Document → append selection/full document → annotate the detached Prompt copy → return without sending → explicitly Run. Check the source remains independent and the submitted text is the intended Prompt, not Document or scratchpad. Intercepted/synthetic Runs establish client behaviour only.
+- [ ] Check response/Working ownership across a buffer round trip, protected replacement/Cancel, save versus later typing, acknowledged reload of both drafts, and a visible safe outcome when recovery is unavailable. Include the decision from step 1; do not hide it behind an extra frame wait.
+- [ ] Arrange a short hands-on trial if approved. A real model Run/Stop needs separate provider approval and an isolated credential setup; if omitted, state that live-provider acceptance is unverified rather than counting synthetic messages as model success.
+- [ ] Capture and verify the actual live drafts before disposal, unless their owner explicitly chooses to discard disposable test text. Never assume unsaved work is disposable. Close only owned browsers/runtimes, verify their processes and ports are gone, and retain required recovery artifacts. Cleanup must also cover launch/setup failures; inspect ownership before signalling anything.
+
+Record each result against the candidate/tarball and browser version. If runtime changes, rerun the affected checks and the release gates on the new artifact; do not overwrite old evidence or launch an unbounded review loop.
+
+## 4. Explicit release decision
+
+- [ ] Summarise the exact version/commit/tarball, passed gates, any accepted limitation and unverified environments. Obtain approval to publish **that artifact** to `next`.
+- [ ] Publish the verified tarball with the explicit `next` tag, never the default `latest` tag. Let Oliver handle any npm browser/passkey/OTP authentication; do not create a stored publishing token as a workaround.
+- [ ] Verify the registry version, integrity and dist-tag, confirm `latest` has not moved, and test a disposable installation of the published package against the audited artifact.
+- [ ] Push/tag only with approval. Changing Oliver's normal installation or enabling either flag by default is another decision; publication does not authorize either.
+
+**Done for this alpha:** the approved opt-in package is reproducible, the intended workflow has the stated evidence, limitations and rollback are clear, and the stable installation remains untouched. For the new candidate, this includes the separately approved third-flag hosting scope and its exact artifact gates; broader buffer management remains deferred.