pi-studio 0.5.44 → 0.5.45

package/client/studio-client.js

@@ -47,6 +47,8 @@
       const sourceEditorWrapEl = document.getElementById("sourceEditorWrap");
       const sourceTextEl = document.getElementById("sourceText");
       const sourceHighlightEl = document.getElementById("sourceHighlight");
+      const reviewNoteGutterEl = document.getElementById("reviewNoteGutter");
+      const reviewNoteGutterContentEl = document.getElementById("reviewNoteGutterContent");
       const lineNumberGutterEl = document.getElementById("lineNumberGutter");
       const lineNumberGutterContentEl = document.getElementById("lineNumberGutterContent");
       const lineNumberMeasureEl = document.getElementById("lineNumberMeasure");
@@ -98,6 +100,7 @@
       const compactBtn = document.getElementById("compactBtn");
       const leftFocusBtn = document.getElementById("leftFocusBtn");
       const rightFocusBtn = document.getElementById("rightFocusBtn");
+      const reviewNotesBtn = document.getElementById("reviewNotesBtn");
       const scratchpadBtn = document.getElementById("scratchpadBtn");
       const scratchpadOverlayEl = document.getElementById("scratchpadOverlay");
       const scratchpadDialogEl = document.getElementById("scratchpadDialog");
@@ -108,16 +111,35 @@
       const scratchpadClearBtn = document.getElementById("scratchpadClearBtn");
       const scratchpadCloseBtn = document.getElementById("scratchpadCloseBtn");
       const scratchpadDoneBtn = document.getElementById("scratchpadDoneBtn");
+      const reviewNotesOverlayEl = document.getElementById("reviewNotesOverlay");
+      const reviewNotesDialogEl = document.getElementById("reviewNotesDialog");
+      const reviewNotesMetaEl = document.getElementById("reviewNotesMeta");
+      const reviewNotesListEl = document.getElementById("reviewNotesList");
+      const reviewNotesEmptyStateEl = document.getElementById("reviewNotesEmptyState");
+      const reviewNotesAddBtn = document.getElementById("reviewNotesAddBtn");
+      const reviewNotesInlineAllBtn = document.getElementById("reviewNotesInlineAllBtn");
+      const reviewNotesCloseBtn = document.getElementById("reviewNotesCloseBtn");
+      const reviewNotesDoneBtn = document.getElementById("reviewNotesDoneBtn");
 
       const studioMode = (document.body && document.body.dataset && document.body.dataset.studioMode) === "editor-only"
         ? "editor-only"
         : "full";
       const isEditorOnlyMode = studioMode === "editor-only";
 
+      const initialQueryParams = new URLSearchParams(window.location.search || "");
+      const explicitDocumentIdentityFromUrl = initialQueryParams.has("docSource")
+        || initialQueryParams.has("docLabel")
+        || initialQueryParams.has("docPath")
+        || initialQueryParams.has("draftId");
       const initialSourceState = {
-        source: (document.body && document.body.dataset && document.body.dataset.initialSource) || "blank",
-        label: (document.body && document.body.dataset && document.body.dataset.initialLabel) || "blank",
-        path: (document.body && document.body.dataset && document.body.dataset.initialPath) || null,
+        source: initialQueryParams.get("docSource")
+          || ((document.body && document.body.dataset && document.body.dataset.initialSource) || "blank"),
+        label: initialQueryParams.get("docLabel")
+          || ((document.body && document.body.dataset && document.body.dataset.initialLabel) || "blank"),
+        path: initialQueryParams.get("docPath")
+          || ((document.body && document.body.dataset && document.body.dataset.initialPath) || null),
+        draftId: initialQueryParams.get("draftId")
+          || ((document.body && document.body.dataset && document.body.dataset.initialDraftId) || null),
       };
 
       let ws = null;
@@ -206,6 +228,7 @@
         source: initialSourceState.source,
         label: initialSourceState.label,
         path: initialSourceState.path,
+        draftId: initialSourceState.draftId,
       };
       let fileBackedBaselineText = null;
       let activePane = "left";
@@ -255,7 +278,6 @@
       const RESPONSE_HIGHLIGHT_MAX_CHARS = 120_000;
       const RESPONSE_HIGHLIGHT_STORAGE_KEY = "piStudio.responseHighlightEnabled";
       const ANNOTATION_MODE_STORAGE_KEY = "piStudio.annotationsEnabled";
-      const SCRATCHPAD_STORAGE_KEY = "piStudio.scratchpad";
       const PREVIEW_INPUT_DEBOUNCE_MS = 0;
       const PREVIEW_PENDING_BADGE_DELAY_MS = 220;
       const previewPendingTimers = new WeakMap();
@@ -274,6 +296,14 @@
       let annotationsEnabled = true;
       let scratchpadText = "";
       let scratchpadReturnFocusEl = null;
+      let scratchpadPersistTimer = null;
+      let scratchpadLoadNonce = 0;
+      let reviewNotes = [];
+      let reviewNotesReturnFocusEl = null;
+      let reviewNotesPersistTimer = null;
+      let reviewNotesLoadNonce = 0;
+      let pendingReviewNoteFocusId = null;
+      let pendingReviewNoteInlineFocusId = null;
       const PREVIEW_ANNOTATION_PLACEHOLDER_PREFIX = "PISTUDIOANNOT";
       const annotationHelpers = globalThis.PiStudioAnnotationHelpers;
       if (!annotationHelpers || typeof annotationHelpers.collectInlineAnnotationMarkers !== "function") {
@@ -740,7 +770,8 @@
         if (terminalActivityPhase === "responding") {
           if (activeKind === "critique") return "Critiquing…";
           if (activeKind === "annotation") return "Replying…";
-          return "Responding…";
+          if (activeKind === "direct") return "Thinking…";
+          return "Working…";
         }
 
         if (activeKind) return getTitleActionMessage(activeKind);
@@ -756,29 +787,26 @@
       }
 
       function buildStudioFaviconHref() {
-        const fg = readThemeColor("--text", "#111111");
-        const bg = readThemeColor("--bg", "#ffffff");
-        const accent = readThemeColor("--accent", fg);
+        const idleColor = readThemeColor("--text", "#111111");
+        const accent = readThemeColor("--accent", "#2563eb");
         const ok = readThemeColor("--ok", "#16a34a");
-        const warn = readThemeColor("--warn", accent);
+        const warn = readThemeColor("--warn", "#d97706");
         const error = readThemeColor("--error", "#dc2626");
 
-        let badgeSvg = "";
-
+        let piColor = idleColor;
         if (titleAttentionMessage) {
-          badgeSvg = `<circle cx="50" cy="14" r="9" fill="${ok}" stroke="${bg}" stroke-width="4" />`;
+          piColor = ok;
         } else if (wsState === "Disconnected") {
-          badgeSvg = `<circle cx="50" cy="14" r="9" fill="${error}" stroke="${bg}" stroke-width="4" />`;
+          piColor = error;
         } else if (wsState === "Connecting") {
-          badgeSvg = `<circle cx="50" cy="14" r="9" fill="${accent}" stroke="${bg}" stroke-width="4" />`;
+          piColor = accent;
         } else if (getTitleBusyMessage()) {
-          badgeSvg = `<circle cx="50" cy="14" r="10" fill="none" stroke="${warn}" stroke-width="5" />`;
+          piColor = warn;
         }
 
         const svg = [
           '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">',
-          `<text x="32" y="35" text-anchor="middle" dominant-baseline="middle" font-size="50" font-weight="700" font-family="ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" fill="${fg}">π</text>`,
-          badgeSvg,
+          `<text x="32" y="35" text-anchor="middle" dominant-baseline="middle" font-size="50" font-weight="700" font-family="ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" fill="${piColor}">π</text>`,
           "</svg>",
         ].join("");
         return "data:image/svg+xml," + encodeURIComponent(svg);
@@ -938,6 +966,12 @@
       function updateSourceBadge() {
         const label = sourceState && sourceState.label ? sourceState.label : "blank";
         sourceBadgeEl.textContent = "Editor origin: " + label;
+        const descriptor = getCurrentStudioDocumentDescriptor();
+        if (sourceBadgeEl) {
+          sourceBadgeEl.title = descriptor.fileBacked
+            ? ("Editor origin: " + label + "\nClick to reset origin and detach the current editor text into a new draft. The file on disk will not be changed.")
+            : ("Editor origin: " + label + "\nClick to reset origin and start a new independent draft while keeping the current text and local notes.");
+        }
         // Show "Set working dir" button when not file-backed
         var isFileBacked = hasRefreshableFilePath();
         if (isFileBacked) {
@@ -961,6 +995,26 @@
         }
       }
 
+      function resetEditorOrigin() {
+        const descriptor = getCurrentStudioDocumentDescriptor();
+        const message = descriptor.fileBacked
+          ? ("Reset editor origin and detach the current text from\n\n" + descriptor.label + "\n\ninto a new draft? The file on disk will not be changed, and the current scratchpad/review notes will carry into the new draft.")
+          : ("Reset editor origin and start a new independent draft? The current editor text, scratchpad, and review notes will carry into the new draft.");
+        if (!window.confirm(message)) {
+          return;
+        }
+        const nextLabel = String(sourceTextEl.value || "").trim() ? "draft" : "blank";
+        setSourceState({
+          source: "blank",
+          label: nextLabel,
+          path: null,
+          draftId: makeStudioDraftId(),
+        }, {
+          carryCurrentMetadataToNewDocument: true,
+        });
+        setStatus(descriptor.fileBacked ? "Detached editor from file origin into a new draft." : "Reset editor origin to a new draft.", "success");
+      }
+
       function updatePaneFocusButtons() {
         [
           [leftFocusBtn, "left"],
@@ -1062,6 +1116,12 @@
           && typeof scratchpadDialogEl.contains === "function"
           && scratchpadDialogEl.contains(event.target)
         );
+        const reviewNotesOwnsEvent = Boolean(
+          reviewNotesDialogEl
+          && event.target
+          && typeof reviewNotesDialogEl.contains === "function"
+          && reviewNotesDialogEl.contains(event.target)
+        );
 
         if (isScratchpadOpen() && plainEscape) {
           event.preventDefault();
@@ -1069,7 +1129,13 @@
           return;
         }
 
-        if (scratchpadOwnsEvent) {
+        if (isReviewNotesOpen() && plainEscape) {
+          event.preventDefault();
+          closeReviewNotes();
+          return;
+        }
+
+        if (scratchpadOwnsEvent || reviewNotesOwnsEvent) {
           return;
         }
 
@@ -2545,7 +2611,7 @@
         if (editorHighlightEnabled && editorView === "markdown") {
           scheduleEditorHighlightRender();
         }
-        if (lineNumbersEnabled && editorView === "markdown") {
+        if (editorView === "markdown") {
           scheduleEditorLineNumberRender();
         }
         if (rightView === "editor-preview") {
@@ -2772,6 +2838,7 @@
         const canRefreshFromDisk = hasRefreshableFilePath();
 
         fileInput.disabled = uiBusy;
+        if (sourceBadgeEl) sourceBadgeEl.disabled = uiBusy;
         saveAsBtn.disabled = uiBusy;
         saveOverBtn.disabled = uiBusy || !canSaveOver;
         if (refreshFromDiskBtn) refreshFromDiskBtn.disabled = uiBusy || !canRefreshFromDisk;
@@ -2805,17 +2872,33 @@
         syncActionButtons();
       }
 
-      function setSourceState(next) {
+      function setSourceState(next, options) {
+        const previousDescriptor = getCurrentStudioDocumentDescriptor();
+        const nextPath = next && next.path ? next.path : null;
         sourceState = {
           source: next && next.source ? next.source : "blank",
           label: next && next.label ? next.label : "blank",
-          path: next && next.path ? next.path : null,
+          path: nextPath,
+          draftId: nextPath
+            ? null
+            : (next && next.draftId ? next.draftId : makeStudioDraftId()),
         };
         if (!sourceState.path) {
           clearFileBackedBaseline();
         }
+        updateStudioDocumentUrlState(sourceState);
         updateSourceBadge();
         syncActionButtons();
+        updateScratchpadUi();
+        updateReviewNotesUi();
+        loadScratchpadForCurrentDocument({
+          previousDescriptor: previousDescriptor,
+          carryCurrentMetadataToNewDocument: Boolean(options && options.carryCurrentMetadataToNewDocument),
+        });
+        void loadReviewNotesForCurrentDocument({
+          previousDescriptor: previousDescriptor,
+          carryCurrentMetadataToNewDocument: Boolean(options && options.carryCurrentMetadataToNewDocument),
+        });
       }
 
       function setEditorText(nextText, options) {
@@ -2848,7 +2931,7 @@
         schedule(() => {
           syncEditorHighlightScroll();
         });
-        if (lineNumbersEnabled && editorView === "markdown") {
+        if (editorView === "markdown") {
           scheduleEditorLineNumberRender();
         }
 
@@ -2888,9 +2971,10 @@
         updateEditorHighlightState();
         syncHighlightSelectUi();
         updateLineNumberGutterVisibility();
-        if (!showPreview && lineNumbersEnabled) {
+        if (!showPreview) {
           scheduleEditorLineNumberRender();
         }
+        updateReviewNotesUi();
       }
 
       function setRightView(nextView) {
@@ -2921,27 +3005,53 @@
         );
       }
 
+      function reviewNoteGutterShouldBeVisible() {
+        return Boolean(
+          editorView === "markdown"
+          && sourceEditorWrapEl
+          && reviewNoteGutterEl
+          && reviewNoteGutterContentEl
+          && lineNumberMeasureEl
+          && Array.isArray(reviewNotes)
+          && reviewNotes.length > 0,
+        );
+      }
+
       function getEditorLineNumberGutterWidthCss(lineCount) {
         const digits = Math.max(2, String(Math.max(1, lineCount || 0)).length);
         return "calc(" + digits + "ch + 18px)";
       }
 
       function updateLineNumberGutterVisibility() {
-        const visible = lineNumbersShouldBeVisible();
+        const lineNumbersVisible = lineNumbersShouldBeVisible();
+        const reviewMarkersVisible = reviewNoteGutterShouldBeVisible();
+        const anyVisible = lineNumbersVisible || reviewMarkersVisible;
         if (sourceEditorWrapEl) {
-          sourceEditorWrapEl.classList.toggle("line-numbers-enabled", visible);
-          if (!visible) {
-            sourceEditorWrapEl.style.setProperty("--editor-line-number-gutter-width", "0px");
-          }
+          sourceEditorWrapEl.classList.toggle("line-numbers-enabled", lineNumbersVisible);
+          sourceEditorWrapEl.style.setProperty("--editor-review-note-gutter-width", reviewMarkersVisible ? "28px" : "0px");
+          sourceEditorWrapEl.style.setProperty(
+            "--editor-line-number-gutter-width",
+            lineNumbersVisible
+              ? getEditorLineNumberGutterWidthCss(Math.max(1, String(sourceTextEl.value || "").replace(/\r\n/g, "\n").split("\n").length))
+              : "0px",
+          );
+        }
+        if (reviewNoteGutterEl) {
+          reviewNoteGutterEl.hidden = !reviewMarkersVisible;
         }
         if (lineNumberGutterEl) {
-          lineNumberGutterEl.hidden = !visible;
+          lineNumberGutterEl.hidden = !lineNumbersVisible;
+        }
+        if (!reviewMarkersVisible && reviewNoteGutterContentEl) {
+          reviewNoteGutterContentEl.innerHTML = "";
+        }
+        if (!lineNumbersVisible && lineNumberGutterContentEl) {
+          lineNumberGutterContentEl.innerHTML = "";
         }
-        if (!visible) {
-          if (lineNumberGutterContentEl) lineNumberGutterContentEl.innerHTML = "";
-          if (lineNumberMeasureEl) lineNumberMeasureEl.innerHTML = "";
+        if (!anyVisible && lineNumberMeasureEl) {
+          lineNumberMeasureEl.innerHTML = "";
         }
-        return visible;
+        return anyVisible;
       }
 
       function renderEditorLineNumbersNow() {
@@ -2950,7 +3060,16 @@
         const text = String(sourceTextEl.value || "").replace(/\r\n/g, "\n");
         const lines = text.split("\n");
         const lineCount = Math.max(1, lines.length);
-        sourceEditorWrapEl.style.setProperty("--editor-line-number-gutter-width", getEditorLineNumberGutterWidthCss(lineCount));
+        const lineNumbersVisible = lineNumbersShouldBeVisible();
+        const reviewMarkersVisible = reviewNoteGutterShouldBeVisible();
+
+        if (sourceEditorWrapEl) {
+          sourceEditorWrapEl.style.setProperty("--editor-review-note-gutter-width", reviewMarkersVisible ? "28px" : "0px");
+          sourceEditorWrapEl.style.setProperty(
+            "--editor-line-number-gutter-width",
+            lineNumbersVisible ? getEditorLineNumberGutterWidthCss(lineCount) : "0px",
+          );
+        }
 
         const styles = window.getComputedStyle(sourceTextEl);
         const lineHeightPx = parseFloat(styles.lineHeight) || 18.85;
@@ -2960,24 +3079,107 @@
         const paddingLeft = parseFloat(styles.paddingLeft) || 0;
         const contentWidth = Math.max(1, sourceTextEl.clientWidth - paddingLeft - paddingRight);
 
-        lineNumberGutterContentEl.style.paddingTop = paddingTop + "px";
-        lineNumberGutterContentEl.style.paddingBottom = paddingBottom + "px";
+        if (lineNumberGutterContentEl) {
+          lineNumberGutterContentEl.style.paddingTop = paddingTop + "px";
+          lineNumberGutterContentEl.style.paddingBottom = paddingBottom + "px";
+        }
+        if (reviewNoteGutterContentEl) {
+          reviewNoteGutterContentEl.style.paddingTop = paddingTop + "px";
+          reviewNoteGutterContentEl.style.paddingBottom = paddingBottom + "px";
+        }
         lineNumberMeasureEl.style.width = contentWidth + "px";
         lineNumberMeasureEl.innerHTML = lines
           .map((line) => "<div class='editor-line-number-measure-line'>" + (line.length ? escapeHtml(line) : "&#8203;") + "</div>")
           .join("");
 
         const measureLines = Array.from(lineNumberMeasureEl.children);
-        lineNumberGutterContentEl.innerHTML = measureLines
-          .map((lineEl, index) => {
-            const height = Math.max(lineHeightPx, lineEl.getBoundingClientRect().height || 0);
-            return "<div class='editor-line-number-row' style='height:" + height.toFixed(2) + "px'>" + (index + 1) + "</div>";
-          })
-          .join("");
+        const reviewNoteLineMap = reviewMarkersVisible ? buildReviewNoteLineMap(text) : null;
+
+        if (lineNumbersVisible && lineNumberGutterContentEl) {
+          lineNumberGutterContentEl.innerHTML = measureLines
+            .map((lineEl, index) => {
+              const height = Math.max(lineHeightPx, lineEl.getBoundingClientRect().height || 0);
+              return "<div class='editor-line-number-row' style='height:" + height.toFixed(2) + "px'>" + (index + 1) + "</div>";
+            })
+            .join("");
+        } else if (lineNumberGutterContentEl) {
+          lineNumberGutterContentEl.innerHTML = "";
+        }
+
+        if (reviewMarkersVisible && reviewNoteGutterContentEl && reviewNoteLineMap) {
+          reviewNoteGutterContentEl.innerHTML = measureLines
+            .map((lineEl, index) => {
+              const height = Math.max(lineHeightPx, lineEl.getBoundingClientRect().height || 0);
+              const lineNumber = index + 1;
+              const notesForLine = reviewNoteLineMap.get(lineNumber) || [];
+              const count = notesForLine.length;
+              if (count <= 0) {
+                return "<div class='editor-review-note-row' style='height:" + height.toFixed(2) + "px'></div>";
+              }
+              const title = count === 1
+                ? ("1 local comment on line " + lineNumber + ". Open comments.")
+                : (count + " local comments on line " + lineNumber + ". Open comments.");
+              const markerLabel = count > 9 ? "9+" : (count > 1 ? String(count) : "•");
+              return "<div class='editor-review-note-row' style='height:" + height.toFixed(2) + "px'><button type='button' class='editor-review-note-marker"
+                + (count > 1 ? " has-multiple" : "")
+                + "' data-review-note-id='" + escapeHtml(notesForLine[0].id) + "' title='" + escapeHtml(title) + "' aria-label='" + escapeHtml(title) + "'>"
+                + escapeHtml(markerLabel)
+                + "</button></div>";
+            })
+            .join("");
+        } else if (reviewNoteGutterContentEl) {
+          reviewNoteGutterContentEl.innerHTML = "";
+        }
 
         syncEditorHighlightScroll();
       }
 
+      function scrollEditorRangeIntoView(range) {
+        if (!range || editorView !== "markdown") return;
+        renderEditorLineNumbersNow();
+
+        const text = String(sourceTextEl.value || "");
+        const startLine = getLineNumberAtOffset(text, range.start);
+        const endLine = getLineNumberAtOffset(text, Math.max(range.start, range.end > range.start ? range.end - 1 : range.end));
+        const styles = window.getComputedStyle(sourceTextEl);
+        const lineHeightPx = parseFloat(styles.lineHeight) || 18.85;
+        const paddingTop = parseFloat(styles.paddingTop) || 0;
+        const paddingBottom = parseFloat(styles.paddingBottom) || 0;
+        const measureLines = lineNumberMeasureEl ? Array.from(lineNumberMeasureEl.children) : [];
+
+        function getLineTop(lineNumber) {
+          let top = paddingTop;
+          for (let i = 0; i < lineNumber - 1; i += 1) {
+            const lineEl = measureLines[i];
+            top += Math.max(lineHeightPx, lineEl ? lineEl.getBoundingClientRect().height || 0 : 0);
+          }
+          return top;
+        }
+
+        function getLineBottom(lineNumber) {
+          const lineEl = measureLines[Math.max(0, lineNumber - 1)];
+          return getLineTop(lineNumber) + Math.max(lineHeightPx, lineEl ? lineEl.getBoundingClientRect().height || 0 : 0);
+        }
+
+        const rangeTop = getLineTop(startLine);
+        const rangeBottom = getLineBottom(endLine);
+        const viewportTop = sourceTextEl.scrollTop;
+        const viewportBottom = viewportTop + sourceTextEl.clientHeight;
+        const margin = Math.max(18, Math.round(sourceTextEl.clientHeight * 0.12));
+
+        let nextScrollTop = viewportTop;
+        if (rangeTop - margin < viewportTop) {
+          nextScrollTop = Math.max(0, rangeTop - margin);
+        } else if (rangeBottom + margin > viewportBottom) {
+          nextScrollTop = Math.max(0, rangeBottom - sourceTextEl.clientHeight + margin + paddingBottom);
+        }
+
+        if (Math.abs(nextScrollTop - viewportTop) > 1) {
+          sourceTextEl.scrollTop = nextScrollTop;
+          syncEditorHighlightScroll();
+        }
+      }
+
       function scheduleEditorLineNumberRender() {
         if (lineNumbersRenderRaf !== null) {
           if (typeof window.cancelAnimationFrame === "function") {
@@ -3025,6 +3227,78 @@
         return query.get("token") || hash.get("token") || "";
       }
 
+      function buildAuthedStudioUrl(pathname, extraParams) {
+        const token = getToken();
+        if (!token) {
+          throw new Error("Missing Studio token in URL.");
+        }
+        const params = new URLSearchParams(extraParams || {});
+        params.set("token", token);
+        return pathname + "?" + params.toString();
+      }
+
+      function updateStudioDocumentUrlState(state) {
+        try {
+          const currentUrl = new URL(window.location.href);
+          const params = currentUrl.searchParams;
+          const nextState = state && typeof state === "object" ? state : sourceState;
+          const nextSource = nextState && nextState.source ? String(nextState.source) : "blank";
+          const nextLabel = nextState && nextState.label ? String(nextState.label) : "blank";
+          const nextPath = nextState && nextState.path ? String(nextState.path) : "";
+          const nextDraftId = nextState && nextState.draftId ? String(nextState.draftId) : "";
+          if (nextSource) params.set("docSource", nextSource);
+          else params.delete("docSource");
+          if (nextLabel) params.set("docLabel", nextLabel);
+          else params.delete("docLabel");
+          if (nextPath) params.set("docPath", nextPath);
+          else params.delete("docPath");
+          if (nextDraftId) params.set("draftId", nextDraftId);
+          else params.delete("draftId");
+          window.history.replaceState(null, "", currentUrl.toString());
+        } catch {
+          // Ignore URL-state update failures.
+        }
+      }
+
+      async function fetchStudioJson(pathname, options) {
+        const init = options || {};
+        const headers = new Headers(init.headers || undefined);
+        const method = String(init.method || "GET").toUpperCase();
+        if (init.body != null && !headers.has("Content-Type")) {
+          headers.set("Content-Type", "application/json");
+        }
+        const response = await fetch(buildAuthedStudioUrl(pathname, init.query), {
+          method,
+          headers,
+          body: init.body,
+          cache: "no-store",
+        });
+        let payload = null;
+        try {
+          payload = await response.json();
+        } catch {
+          payload = null;
+        }
+        if (!response.ok || !payload || payload.ok === false) {
+          const message = payload && typeof payload.error === "string"
+            ? payload.error
+            : (response.status + " " + response.statusText).trim();
+          throw new Error(message || (method + " " + pathname + " failed."));
+        }
+        return payload;
+      }
+
+      function trySendStudioJsonBeacon(pathname, payload, extraParams) {
+        try {
+          if (!navigator.sendBeacon || typeof navigator.sendBeacon !== "function") return false;
+          const body = JSON.stringify(payload || {});
+          const blob = new Blob([body], { type: "application/json" });
+          return navigator.sendBeacon(buildAuthedStudioUrl(pathname, extraParams), blob);
+        } catch {
+          return false;
+        }
+      }
+
       function makeRequestId() {
         if (window.crypto && typeof window.crypto.randomUUID === "function") {
           return window.crypto.randomUUID().replace(/[^a-zA-Z0-9_-]/g, "_");
@@ -3032,6 +3306,10 @@
         return "req_" + Date.now() + "_" + Math.random().toString(36).slice(2, 10);
       }
 
+      function makeStudioDraftId() {
+        return "draft_" + makeRequestId();
+      }
+
       function escapeHtml(text) {
         return text
           .replace(/&/g, "&amp;")
@@ -3549,6 +3827,9 @@
           sourceHighlightEl.scrollTop = sourceTextEl.scrollTop;
           sourceHighlightEl.scrollLeft = sourceTextEl.scrollLeft;
         }
+        if (reviewNoteGutterEl) {
+          reviewNoteGutterEl.scrollTop = sourceTextEl.scrollTop;
+        }
         if (lineNumberGutterEl) {
           lineNumberGutterEl.scrollTop = sourceTextEl.scrollTop;
         }
@@ -3628,51 +3909,823 @@
         persistStoredToggle(ANNOTATION_MODE_STORAGE_KEY, enabled);
       }
 
-      function readStoredText(storageKey) {
-        if (!window.localStorage) return null;
+      function isScratchpadOpen() {
+        return Boolean(scratchpadOverlayEl && !scratchpadOverlayEl.hidden);
+      }
+
+      function isReviewNotesOpen() {
+        return Boolean(reviewNotesOverlayEl && !reviewNotesOverlayEl.hidden);
+      }
+
+      function syncModalOpenState() {
+        document.body.classList.toggle("scratchpad-open", isScratchpadOpen());
+      }
+
+      function describeStudioDocument(state) {
+        const currentState = state && typeof state === "object" ? state : sourceState;
+        const source = currentState && currentState.source ? String(currentState.source) : "blank";
+        const label = currentState && currentState.label ? String(currentState.label) : "blank";
+        const path = currentState && currentState.path ? String(currentState.path) : "";
+        const draftId = currentState && currentState.draftId ? String(currentState.draftId) : "";
+        if (path) {
+          return {
+            key: "file:" + path,
+            label: path,
+            fileBacked: true,
+            draftBacked: false,
+          };
+        }
+        const normalizedLabel = label.trim().replace(/\s+/g, " ") || source;
+        if (draftId) {
+          return {
+            key: "draft:" + draftId,
+            label: normalizedLabel,
+            fileBacked: false,
+            draftBacked: true,
+          };
+        }
+        return {
+          key: "doc:" + source + ":" + normalizedLabel,
+          label: normalizedLabel,
+          fileBacked: false,
+          draftBacked: false,
+        };
+      }
+
+      function getCurrentStudioDocumentDescriptor() {
+        return describeStudioDocument(sourceState);
+      }
+
+      async function fetchScratchpadTextForDocumentKey(documentKey) {
+        const payload = await fetchStudioJson("/scratchpad-state", {
+          query: { documentKey: documentKey },
+        });
+        return payload && typeof payload.text === "string" ? payload.text : "";
+      }
+
+      function flushScratchpadPersistence(documentKeyOverride, textOverride) {
+        const descriptor = documentKeyOverride
+          ? { key: String(documentKeyOverride || "").trim() }
+          : getCurrentStudioDocumentDescriptor();
+        const key = String(descriptor && descriptor.key ? descriptor.key : "").trim();
+        if (!key) return;
+        if (scratchpadPersistTimer !== null) {
+          window.clearTimeout(scratchpadPersistTimer);
+          scratchpadPersistTimer = null;
+        }
+        const snapshot = String(arguments.length >= 2 ? textOverride : scratchpadText || "");
+        if (trySendStudioJsonBeacon("/scratchpad-state", { documentKey: key, text: snapshot })) {
+          return;
+        }
+        void fetchStudioJson("/scratchpad-state", {
+          method: "POST",
+          body: JSON.stringify({ documentKey: key, text: snapshot }),
+        }).catch(() => {
+          // Ignore scratchpad persistence failures for now.
+        });
+      }
+
+      function scheduleScratchpadPersistence(text, documentKey) {
+        if (scratchpadPersistTimer !== null) {
+          window.clearTimeout(scratchpadPersistTimer);
+        }
+        const snapshot = String(text || "");
+        const key = String(documentKey || "").trim();
+        if (!key) return;
+        scratchpadPersistTimer = window.setTimeout(() => {
+          scratchpadPersistTimer = null;
+          flushScratchpadPersistence(key, snapshot);
+        }, 180);
+      }
+
+      async function loadScratchpadForDocumentKey(documentKey) {
+        const key = String(documentKey || "").trim();
+        const loadNonce = ++scratchpadLoadNonce;
+        if (!key) {
+          setScratchpadText("", { persist: false });
+          return;
+        }
         try {
-          const value = window.localStorage.getItem(storageKey);
-          return typeof value === "string" ? value : null;
+          const serverText = await fetchScratchpadTextForDocumentKey(key);
+          if (loadNonce !== scratchpadLoadNonce) return;
+          if (key !== getCurrentStudioDocumentDescriptor().key) return;
+          setScratchpadText(serverText, { persist: false });
         } catch {
-          return null;
+          if (loadNonce !== scratchpadLoadNonce) return;
+          if (key !== getCurrentStudioDocumentDescriptor().key) return;
+          setScratchpadText("", { persist: false });
         }
       }
 
-      function persistStoredText(storageKey, value) {
-        if (!window.localStorage) return;
+      async function maybeCarryScratchpadToNewDocument(previousDescriptor, nextDescriptor) {
+        if (!previousDescriptor || !nextDescriptor || previousDescriptor.key === nextDescriptor.key) return;
+        const snapshot = String(scratchpadText || "");
+        if (!snapshot.trim()) return;
         try {
-          window.localStorage.setItem(storageKey, String(value ?? ""));
+          const existing = await fetchScratchpadTextForDocumentKey(nextDescriptor.key);
+          if (String(existing || "").trim()) return;
+          await fetchStudioJson("/scratchpad-state", {
+            method: "POST",
+            body: JSON.stringify({ documentKey: nextDescriptor.key, text: snapshot }),
+          });
         } catch {
-          // ignore storage failures
+          // Ignore carry-over failures and just fall back to normal scope loading.
         }
       }
 
-      function isScratchpadOpen() {
-        return Boolean(scratchpadOverlayEl && !scratchpadOverlayEl.hidden);
+      function loadScratchpadForCurrentDocument(options) {
+        const previousDescriptor = options && options.previousDescriptor ? options.previousDescriptor : null;
+        const shouldCarryToNewDocument = Boolean(options && options.carryCurrentMetadataToNewDocument);
+        const currentDescriptor = getCurrentStudioDocumentDescriptor();
+        void (async () => {
+          if (shouldCarryToNewDocument && previousDescriptor) {
+            await maybeCarryScratchpadToNewDocument(previousDescriptor, currentDescriptor);
+          }
+          await loadScratchpadForDocumentKey(currentDescriptor.key);
+        })();
       }
 
-      function readStoredScratchpadText() {
-        return readStoredText(SCRATCHPAD_STORAGE_KEY);
+      function persistScratchpadText(value) {
+        const descriptor = getCurrentStudioDocumentDescriptor();
+        scheduleScratchpadPersistence(value, descriptor.key);
       }
 
-      function persistScratchpadText(value) {
-        persistStoredText(SCRATCHPAD_STORAGE_KEY, value);
+      function normalizeReviewNote(note) {
+        if (!note || typeof note !== "object") return null;
+        const id = typeof note.id === "string" && note.id.trim() ? note.id : makeRequestId();
+        const text = typeof note.text === "string" ? note.text : "";
+        const createdAt = typeof note.createdAt === "number" && Number.isFinite(note.createdAt)
+          ? note.createdAt
+          : Date.now();
+        const updatedAt = typeof note.updatedAt === "number" && Number.isFinite(note.updatedAt)
+          ? note.updatedAt
+          : createdAt;
+        const selectionStart = typeof note.selectionStart === "number" && Number.isFinite(note.selectionStart)
+          ? Math.max(0, Math.floor(note.selectionStart))
+          : 0;
+        const selectionEnd = typeof note.selectionEnd === "number" && Number.isFinite(note.selectionEnd)
+          ? Math.max(selectionStart, Math.floor(note.selectionEnd))
+          : selectionStart;
+        const lineStart = typeof note.lineStart === "number" && Number.isFinite(note.lineStart)
+          ? Math.max(1, Math.floor(note.lineStart))
+          : 1;
+        const lineEnd = typeof note.lineEnd === "number" && Number.isFinite(note.lineEnd)
+          ? Math.max(lineStart, Math.floor(note.lineEnd))
+          : lineStart;
+        return {
+          id,
+          text,
+          createdAt,
+          updatedAt,
+          selectionStart,
+          selectionEnd,
+          lineStart,
+          lineEnd,
+          selectedText: typeof note.selectedText === "string" ? note.selectedText : "",
+        };
+      }
+
+      function cloneReviewNotes(notes) {
+        return Array.isArray(notes)
+          ? notes
+              .map((note) => normalizeReviewNote(note))
+              .filter(Boolean)
+              .map((note) => ({ ...note }))
+          : [];
+      }
+
+      async function fetchReviewNotesForDocumentKey(documentKey) {
+        const payload = await fetchStudioJson("/review-notes", {
+          query: { documentKey: documentKey },
+        });
+        return cloneReviewNotes(payload && Array.isArray(payload.notes) ? payload.notes : []);
+      }
+
+      function flushReviewNotesPersistence(documentKeyOverride, notesOverride) {
+        const descriptor = documentKeyOverride
+          ? { key: String(documentKeyOverride || "").trim() }
+          : getCurrentStudioDocumentDescriptor();
+        const key = String(descriptor && descriptor.key ? descriptor.key : "").trim();
+        if (!key) return;
+        if (reviewNotesPersistTimer !== null) {
+          window.clearTimeout(reviewNotesPersistTimer);
+          reviewNotesPersistTimer = null;
+        }
+        const snapshot = cloneReviewNotes(arguments.length >= 2 ? notesOverride : reviewNotes);
+        if (trySendStudioJsonBeacon("/review-notes", { documentKey: key, notes: snapshot })) {
+          return;
+        }
+        void fetchStudioJson("/review-notes", {
+          method: "POST",
+          body: JSON.stringify({ documentKey: key, notes: snapshot }),
+        }).catch(() => {
+          // Ignore persistence failures; the in-memory notes list remains available for this session.
+        });
+      }
+
+      function scheduleReviewNotesPersistence() {
+        if (reviewNotesPersistTimer !== null) {
+          window.clearTimeout(reviewNotesPersistTimer);
+        }
+        const descriptor = getCurrentStudioDocumentDescriptor();
+        const snapshot = cloneReviewNotes(reviewNotes);
+        reviewNotesPersistTimer = window.setTimeout(() => {
+          reviewNotesPersistTimer = null;
+          flushReviewNotesPersistence(descriptor.key, snapshot);
+        }, 180);
+      }
+
+      async function maybeCarryReviewNotesToNewDocument(previousDescriptor, nextDescriptor) {
+        if (!previousDescriptor || !nextDescriptor || previousDescriptor.key === nextDescriptor.key) return;
+        const snapshot = cloneReviewNotes(reviewNotes);
+        if (!snapshot.length) return;
+        try {
+          const existing = await fetchReviewNotesForDocumentKey(nextDescriptor.key);
+          if (existing.length > 0) return;
+          await fetchStudioJson("/review-notes", {
+            method: "POST",
+            body: JSON.stringify({ documentKey: nextDescriptor.key, notes: snapshot }),
+          });
+        } catch {
+          // Ignore carry-over failures and just fall back to normal scope loading.
+        }
+      }
+
+      async function loadReviewNotesForCurrentDocument(options) {
+        const descriptor = getCurrentStudioDocumentDescriptor();
+        const previousDescriptor = options && options.previousDescriptor ? options.previousDescriptor : null;
+        const shouldCarryToNewDocument = Boolean(options && options.carryCurrentMetadataToNewDocument);
+        const loadNonce = ++reviewNotesLoadNonce;
+        try {
+          if (shouldCarryToNewDocument && previousDescriptor) {
+            await maybeCarryReviewNotesToNewDocument(previousDescriptor, descriptor);
+          }
+          const notes = await fetchReviewNotesForDocumentKey(descriptor.key);
+          if (loadNonce !== reviewNotesLoadNonce) return;
+          if (descriptor.key !== getCurrentStudioDocumentDescriptor().key) return;
+          reviewNotes = notes;
+        } catch {
+          if (loadNonce !== reviewNotesLoadNonce) return;
+          if (descriptor.key !== getCurrentStudioDocumentDescriptor().key) return;
+          reviewNotes = [];
+        }
+        updateReviewNotesUi();
+        renderReviewNotesList();
+        if (editorView === "markdown") {
+          scheduleEditorLineNumberRender();
+        }
+      }
+
+      function formatReviewNoteTimestamp(timestamp) {
+        if (!Number.isFinite(timestamp)) return "Saved locally";
+        try {
+          return "Updated " + new Date(timestamp).toLocaleString();
+        } catch {
+          return "Saved locally";
+        }
+      }
+
+      function summarizeReviewNoteAnchor(note) {
+        const start = Math.max(1, Number(note && note.lineStart) || 1);
+        const end = Math.max(start, Number(note && note.lineEnd) || start);
+        return start === end ? "Line " + start : ("Lines " + start + "–" + end);
+      }
+
+      function summarizeReviewNoteQuote(note) {
+        const normalized = String(note && note.selectedText ? note.selectedText : "")
+          .replace(/\s+/g, " ")
+          .trim();
+        if (!normalized) return "Anchor: current line / empty selection";
+        return normalized.length > 140 ? normalized.slice(0, 137) + "…" : normalized;
+      }
+
+      function getLineNumberAtOffset(text, offset) {
+        const source = String(text || "");
+        const safeOffset = Math.max(0, Math.min(Number(offset) || 0, source.length));
+        let line = 1;
+        for (let i = 0; i < safeOffset; i += 1) {
+          if (source[i] === "\n") line += 1;
+        }
+        return line;
+      }
+
+      function getLineRangeAtOffset(text, offset) {
+        const source = String(text || "");
+        const safeOffset = Math.max(0, Math.min(Number(offset) || 0, source.length));
+        let start = safeOffset;
+        while (start > 0 && source[start - 1] !== "\n") start -= 1;
+        let end = safeOffset;
+        while (end < source.length && source[end] !== "\n") end += 1;
+        return {
+          start,
+          end,
+          lineNumber: getLineNumberAtOffset(source, safeOffset),
+        };
+      }
+
+      function getLineRangeForNumbers(text, lineStart, lineEnd) {
+        const lines = String(text || "").split("\n");
+        const safeLineStart = Math.max(1, Math.min(Math.floor(lineStart || 1), Math.max(1, lines.length)));
+        const safeLineEnd = Math.max(safeLineStart, Math.min(Math.floor(lineEnd || safeLineStart), Math.max(1, lines.length)));
+        let start = 0;
+        for (let i = 0; i < safeLineStart - 1; i += 1) {
+          start += lines[i].length + 1;
+        }
+        let end = start;
+        for (let i = safeLineStart - 1; i < safeLineEnd; i += 1) {
+          end += lines[i].length;
+          if (i < safeLineEnd - 1) end += 1;
+        }
+        return { start, end };
+      }
+
+      function getEditorAnchorForReviewNote() {
+        const current = String(sourceTextEl.value || "");
+        const start = typeof sourceTextEl.selectionStart === "number" ? sourceTextEl.selectionStart : 0;
+        const end = typeof sourceTextEl.selectionEnd === "number" ? sourceTextEl.selectionEnd : start;
+        const safeStart = Math.max(0, Math.min(start, current.length));
+        const safeEnd = Math.max(safeStart, Math.min(end, current.length));
+        if (safeStart !== safeEnd) {
+          return {
+            selectionStart: safeStart,
+            selectionEnd: safeEnd,
+            lineStart: getLineNumberAtOffset(current, safeStart),
+            lineEnd: getLineNumberAtOffset(current, Math.max(safeStart, safeEnd - 1)),
+            selectedText: current.slice(safeStart, safeEnd),
+          };
+        }
+        const lineRange = getLineRangeAtOffset(current, safeStart);
+        return {
+          selectionStart: lineRange.start,
+          selectionEnd: lineRange.end,
+          lineStart: lineRange.lineNumber,
+          lineEnd: lineRange.lineNumber,
+          selectedText: current.slice(lineRange.start, lineRange.end),
+        };
+      }
+
+      function resolveReviewNoteRange(note, text) {
+        const source = String(text || "");
+        const safeStart = Math.max(0, Math.min(Number(note && note.selectionStart) || 0, source.length));
+        const safeEnd = Math.max(safeStart, Math.min(Number(note && note.selectionEnd) || safeStart, source.length));
+        const selectedText = String(note && note.selectedText ? note.selectedText : "");
+        if (selectedText && source.slice(safeStart, safeEnd) === selectedText) {
+          return { start: safeStart, end: safeEnd };
+        }
+        if (!selectedText && safeEnd >= safeStart) {
+          return { start: safeStart, end: safeEnd };
+        }
+        if (selectedText) {
+          const foundIndex = source.indexOf(selectedText);
+          if (foundIndex >= 0) {
+            return { start: foundIndex, end: foundIndex + selectedText.length };
+          }
+        }
+        return getLineRangeForNumbers(source, note && note.lineStart, note && note.lineEnd);
+      }
+
+      function getResolvedReviewNoteLineBounds(note, text) {
+        const source = String(text || "");
+        const range = resolveReviewNoteRange(note, source);
+        if (!range) return null;
+        const startLine = getLineNumberAtOffset(source, range.start);
+        const endLookupOffset = range.end > range.start ? range.end - 1 : range.start;
+        const endLine = getLineNumberAtOffset(source, endLookupOffset);
+        return {
+          start: range.start,
+          end: range.end,
+          lineStart: startLine,
+          lineEnd: Math.max(startLine, endLine),
+        };
+      }
+
+      function buildReviewNoteLineMap(text) {
+        const source = String(text || "");
+        const lineMap = new Map();
+        for (const note of reviewNotes) {
+          const bounds = getResolvedReviewNoteLineBounds(note, source);
+          if (!bounds) continue;
+          for (let line = bounds.lineStart; line <= bounds.lineEnd; line += 1) {
+            const notesForLine = lineMap.get(line) || [];
+            notesForLine.push(note);
+            lineMap.set(line, notesForLine);
+          }
+        }
+        return lineMap;
+      }
+
+      function getDisplayReviewNotes() {
+        const source = String(sourceTextEl && sourceTextEl.value ? sourceTextEl.value : "");
+        return reviewNotes.slice().sort((left, right) => {
+          const leftBounds = getResolvedReviewNoteLineBounds(left, source);
+          const rightBounds = getResolvedReviewNoteLineBounds(right, source);
+          const leftLine = leftBounds ? leftBounds.lineStart : Math.max(1, Number(left && left.lineStart) || 1);
+          const rightLine = rightBounds ? rightBounds.lineStart : Math.max(1, Number(right && right.lineStart) || 1);
+          if (leftLine !== rightLine) return leftLine - rightLine;
+
+          const leftStart = leftBounds ? leftBounds.start : Math.max(0, Number(left && left.selectionStart) || 0);
+          const rightStart = rightBounds ? rightBounds.start : Math.max(0, Number(right && right.selectionStart) || 0);
+          if (leftStart !== rightStart) return leftStart - rightStart;
+
+          const leftCreated = Number(left && left.createdAt) || 0;
+          const rightCreated = Number(right && right.createdAt) || 0;
+          if (leftCreated !== rightCreated) return leftCreated - rightCreated;
+
+          return String(left && left.id ? left.id : "").localeCompare(String(right && right.id ? right.id : ""));
+        });
+      }
+
+      function focusReviewNoteInPanel(noteId) {
+        const note = reviewNotes.find((entry) => entry && entry.id === noteId);
+        if (!note) return;
+        pendingReviewNoteFocusId = note.id;
+        openReviewNotes();
+      }
+
+      function escapeReviewNoteAnnotationText(text) {
+        return String(text || "")
+          .replace(/\\/g, "\\\\")
+          .replace(/\]/g, "\\]")
+          .trim();
+      }
+
+      function getReviewNoteInlineState(note, text) {
+        const source = String(text || "");
+        const annotationBody = escapeReviewNoteAnnotationText(note && note.text);
+        if (!annotationBody) {
+          return {
+            annotationBody: "",
+            range: null,
+            markerText: "",
+            exists: false,
+            canToggle: false,
+          };
+        }
+        const range = resolveReviewNoteRange(note, source);
+        if (!range) {
+          return {
+            annotationBody,
+            range: null,
+            markerText: "",
+            exists: false,
+            canToggle: false,
+          };
+        }
+        const markerText = (range.start === range.end ? "" : " ") + "[an: " + annotationBody + "]";
+        const exists = source.slice(range.end, range.end + markerText.length) === markerText;
+        return {
+          annotationBody,
+          range,
+          markerText,
+          exists,
+          canToggle: true,
+        };
+      }
+
+      function setReviewNotes(nextNotes, options) {
+        reviewNotes = cloneReviewNotes(nextNotes);
+        updateReviewNotesUi();
+        renderReviewNotesList();
+        if (editorView === "markdown") {
+          scheduleEditorLineNumberRender();
+        }
+        if (!options || options.persist !== false) {
+          scheduleReviewNotesPersistence();
+        }
+      }
+
+      function updateReviewNotesUi() {
+        const descriptor = getCurrentStudioDocumentDescriptor();
+        const count = reviewNotes.length;
+        const hasNotes = count > 0;
+        const isOpen = isReviewNotesOpen();
+        if (reviewNotesBtn) {
+          reviewNotesBtn.textContent = hasNotes ? "Comments •" : "Comments";
+          reviewNotesBtn.classList.toggle("has-content", hasNotes);
+          reviewNotesBtn.classList.toggle("is-active", isOpen);
+          reviewNotesBtn.setAttribute("aria-pressed", isOpen ? "true" : "false");
+          reviewNotesBtn.title = isOpen
+            ? "Hide local comments."
+            : (hasNotes
+              ? (count + " local comment" + (count === 1 ? "" : "s") + " for " + descriptor.label + ". Open the side-by-side comments rail.")
+              : "Open local comments beside the current editor document or draft. Comments stay outside the document text and can later be converted into [an: ...] annotations.");
+        }
+        if (reviewNotesMetaEl) {
+          const scopeLabel = descriptor.fileBacked
+            ? "file-backed"
+            : (descriptor.draftBacked ? "draft-backed" : "local buffer");
+          reviewNotesMetaEl.textContent = hasNotes
+            ? (count + " comment" + (count === 1 ? "" : "s") + " · " + scopeLabel + " · " + descriptor.label)
+            : ("No comments yet · " + scopeLabel);
+        }
+        if (reviewNotesAddBtn) {
+          reviewNotesAddBtn.disabled = editorView !== "markdown";
+          reviewNotesAddBtn.title = editorView === "markdown"
+            ? "Create a new local comment from the current editor selection, or from the current line if nothing is selected."
+            : "Switch to Editor (Raw) to anchor a comment to the current selection or line.";
+        }
+        if (reviewNotesInlineAllBtn) {
+          const currentText = String(sourceTextEl && sourceTextEl.value ? sourceTextEl.value : "");
+          const toggleCandidates = getDisplayReviewNotes().filter((note) => getReviewNoteInlineState(note, currentText).canToggle);
+          const allInline = toggleCandidates.length > 0 && toggleCandidates.every((note) => getReviewNoteInlineState(note, currentText).exists);
+          reviewNotesInlineAllBtn.disabled = uiBusy || toggleCandidates.length === 0;
+          reviewNotesInlineAllBtn.textContent = allInline ? "All inline: On" : "All inline: Off";
+          reviewNotesInlineAllBtn.setAttribute("aria-pressed", allInline ? "true" : "false");
+          reviewNotesInlineAllBtn.title = allInline
+            ? "Inline annotations derived from all non-empty comments are currently on. Click to remove them."
+            : "Inline annotations derived from all non-empty comments are currently off. Click to add them.";
+        }
+        if (reviewNotesDoneBtn) {
+          reviewNotesDoneBtn.disabled = !isOpen;
+        }
+        if (reviewNotesEmptyStateEl) {
+          reviewNotesEmptyStateEl.hidden = hasNotes;
+        }
+      }
+
+      function renderReviewNotesList() {
+        if (!reviewNotesListEl) return;
+        reviewNotesListEl.innerHTML = "";
+        for (const note of getDisplayReviewNotes()) {
+          const card = document.createElement("article");
+          card.className = "review-note-card";
+
+          const header = document.createElement("div");
+          header.className = "review-note-card-header";
+
+          const titleWrap = document.createElement("div");
+          titleWrap.className = "review-note-card-title";
+
+          const anchor = document.createElement("span");
+          anchor.className = "review-note-anchor";
+          anchor.textContent = summarizeReviewNoteAnchor(note);
+          titleWrap.appendChild(anchor);
+
+          const quote = document.createElement("div");
+          quote.className = "review-note-quote";
+          quote.textContent = summarizeReviewNoteQuote(note);
+          titleWrap.appendChild(quote);
+          header.appendChild(titleWrap);
+
+          card.appendChild(header);
+
+          const textarea = document.createElement("textarea");
+          textarea.value = String(note.text || "");
+          textarea.placeholder = "Write a local comment here…";
+          textarea.title = "Write a local comment. Press Enter to finish editing, or Shift+Enter for a new line.";
+          card.appendChild(textarea);
+
+          const footer = document.createElement("div");
+          footer.className = "review-note-card-footer";
+
+          const timestamp = document.createElement("span");
+          timestamp.className = "review-note-timestamp";
+          timestamp.textContent = formatReviewNoteTimestamp(note.updatedAt);
+
+          const actions = document.createElement("div");
+          actions.className = "review-note-card-actions";
+
+          const jumpBtn = document.createElement("button");
+          jumpBtn.type = "button";
+          jumpBtn.textContent = "Jump";
+          jumpBtn.title = "Jump to this comment's anchored location in the editor.";
+          jumpBtn.addEventListener("click", () => {
+            jumpToReviewNote(note.id);
+          });
+          actions.appendChild(jumpBtn);
+
+          const inlineState = getReviewNoteInlineState(note, sourceTextEl.value || "");
+          const convertBtn = document.createElement("button");
+          convertBtn.type = "button";
+          convertBtn.className = "review-note-inline-btn";
+          convertBtn.textContent = inlineState.exists ? "Inline: On" : "Inline: Off";
+          convertBtn.setAttribute("aria-pressed", inlineState.exists ? "true" : "false");
+          convertBtn.disabled = !inlineState.canToggle || uiBusy;
+          convertBtn.title = inlineState.exists
+            ? "This comment currently has an inline [an: ...] annotation in the editor. Click to remove it."
+            : "This comment is currently not inline in the editor. Click to add it as an inline [an: ...] annotation.";
+          convertBtn.addEventListener("click", () => {
+            convertReviewNoteToAnnotation(note.id);
+          });
+          actions.appendChild(convertBtn);
+
+          const deleteBtn = document.createElement("button");
+          deleteBtn.type = "button";
+          deleteBtn.className = "review-note-delete-btn";
+          deleteBtn.textContent = "Delete";
+          deleteBtn.title = "Delete this local comment.";
+          deleteBtn.addEventListener("click", () => {
+            deleteReviewNote(note.id);
+          });
+          actions.appendChild(deleteBtn);
+
+          footer.appendChild(timestamp);
+          footer.appendChild(actions);
+          card.appendChild(footer);
+
+          textarea.addEventListener("input", () => {
+            note.text = textarea.value;
+            note.updatedAt = Date.now();
+            timestamp.textContent = formatReviewNoteTimestamp(note.updatedAt);
+            const nextInlineState = getReviewNoteInlineState(note, sourceTextEl.value || "");
+            convertBtn.disabled = !nextInlineState.canToggle || uiBusy;
+            convertBtn.textContent = nextInlineState.exists ? "Inline: On" : "Inline: Off";
+            convertBtn.setAttribute("aria-pressed", nextInlineState.exists ? "true" : "false");
+            convertBtn.title = nextInlineState.exists
+              ? "This comment currently has an inline [an: ...] annotation in the editor. Click to remove it."
+              : "This comment is currently not inline in the editor. Click to add it as an inline [an: ...] annotation.";
+            scheduleReviewNotesPersistence();
+            updateReviewNotesUi();
+          });
+
+          textarea.addEventListener("keydown", (event) => {
+            if (
+              event.key === "Enter"
+              && !event.shiftKey
+              && !event.altKey
+              && !event.ctrlKey
+              && !event.metaKey
+            ) {
+              event.preventDefault();
+              textarea.blur();
+              if (!convertBtn.disabled) {
+                convertBtn.focus();
+              }
+            }
+          });
+
+          reviewNotesListEl.appendChild(card);
+
+          if (pendingReviewNoteInlineFocusId && pendingReviewNoteInlineFocusId === note.id && isReviewNotesOpen()) {
+            const schedule = typeof window.requestAnimationFrame === "function"
+              ? window.requestAnimationFrame.bind(window)
+              : (cb) => window.setTimeout(cb, 16);
+            schedule(() => {
+              card.scrollIntoView({ block: "nearest" });
+              if (!convertBtn.disabled) convertBtn.focus();
+            });
+          } else if (pendingReviewNoteFocusId && pendingReviewNoteFocusId === note.id && isReviewNotesOpen()) {
+            const schedule = typeof window.requestAnimationFrame === "function"
+              ? window.requestAnimationFrame.bind(window)
+              : (cb) => window.setTimeout(cb, 16);
+            schedule(() => {
+              card.scrollIntoView({ block: "nearest" });
+              textarea.focus();
+              const end = textarea.value.length;
+              textarea.setSelectionRange(end, end);
+            });
+          }
+        }
+        pendingReviewNoteFocusId = null;
+        pendingReviewNoteInlineFocusId = null;
+      }
+
+      function addReviewNoteFromEditorSelection() {
+        if (editorView !== "markdown") {
+          setStatus("Switch to Editor (Raw) before adding an anchored comment.", "warning");
+          return;
+        }
+        const anchor = getEditorAnchorForReviewNote();
+        const note = normalizeReviewNote({
+          id: makeRequestId(),
+          text: "",
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+          selectionStart: anchor.selectionStart,
+          selectionEnd: anchor.selectionEnd,
+          lineStart: anchor.lineStart,
+          lineEnd: anchor.lineEnd,
+          selectedText: anchor.selectedText,
+        });
+        if (!note) return;
+        pendingReviewNoteFocusId = note.id;
+        setReviewNotes(reviewNotes.concat([note]));
+        if (!isReviewNotesOpen()) {
+          openReviewNotes();
+        }
+        setStatus("Added local comment.", "success");
+      }
+
+      function jumpToReviewNote(noteId) {
+        const note = reviewNotes.find((entry) => entry && entry.id === noteId);
+        if (!note) return;
+        const current = String(sourceTextEl.value || "");
+        const range = resolveReviewNoteRange(note, current);
+        if (!range) {
+          setStatus("Could not find the anchored location for this comment.", "warning");
+          return;
+        }
+        setEditorView("markdown");
+        setActivePane("left");
+        sourceTextEl.focus();
+        sourceTextEl.setSelectionRange(range.start, range.end);
+        const schedule = typeof window.requestAnimationFrame === "function"
+          ? window.requestAnimationFrame.bind(window)
+          : (cb) => window.setTimeout(cb, 16);
+        schedule(() => {
+          scrollEditorRangeIntoView(range);
+        });
+      }
+
+      function deleteReviewNote(noteId) {
+        const note = reviewNotes.find((entry) => entry && entry.id === noteId);
+        if (!note) return;
+        const confirmed = window.confirm("Delete this local comment?");
+        if (!confirmed) return;
+        setReviewNotes(reviewNotes.filter((entry) => entry && entry.id !== noteId));
+        setStatus("Deleted local comment.", "success");
+      }
+
+      function convertReviewNoteToAnnotation(noteId) {
+        if (uiBusy) {
+          setStatus("Wait until the current Studio action finishes before toggling inline annotation state.", "warning");
+          return;
+        }
+        const note = reviewNotes.find((entry) => entry && entry.id === noteId);
+        if (!note) return;
+        const current = String(sourceTextEl.value || "");
+        const inlineState = getReviewNoteInlineState(note, current);
+        if (!inlineState.annotationBody) {
+          setStatus("Comment is empty. Add some text before toggling inline annotation state.", "warning");
+          return;
+        }
+        if (!inlineState.range || !inlineState.canToggle) {
+          setStatus("Could not find the anchored location for this comment.", "warning");
+          return;
+        }
+        const next = inlineState.exists
+          ? current.slice(0, inlineState.range.end) + current.slice(inlineState.range.end + inlineState.markerText.length)
+          : current.slice(0, inlineState.range.end) + inlineState.markerText + current.slice(inlineState.range.end);
+        setEditorView("markdown");
+        setEditorText(next, { preserveScroll: true, preserveSelection: true });
+        pendingReviewNoteInlineFocusId = note.id;
+        renderReviewNotesList();
+        updateReviewNotesUi();
+        setStatus(inlineState.exists ? "Removed inline annotation from local comment." : "Added inline annotation from local comment.", "success");
+      }
+
+      function toggleAllReviewNotesInlineAnnotations() {
+        if (uiBusy) {
+          setStatus("Wait until the current Studio action finishes before toggling inline annotations.", "warning");
+          return;
+        }
+        const candidates = getDisplayReviewNotes().filter((note) => getReviewNoteInlineState(note, sourceTextEl.value || "").canToggle);
+        if (candidates.length === 0) {
+          setStatus("No non-empty comments are ready to toggle inline.", "warning");
+          return;
+        }
+        let currentText = String(sourceTextEl.value || "");
+        const shouldRemoveAll = candidates.every((note) => getReviewNoteInlineState(note, currentText).exists);
+        const ordered = candidates
+          .map((note) => ({ note, state: getReviewNoteInlineState(note, currentText) }))
+          .filter((entry) => entry.state.range)
+          .sort((left, right) => (right.state.range ? right.state.range.end : 0) - (left.state.range ? left.state.range.end : 0));
+
+        let changed = false;
+        for (const entry of ordered) {
+          const liveState = getReviewNoteInlineState(entry.note, currentText);
+          if (!liveState.range || !liveState.canToggle) continue;
+          if (shouldRemoveAll) {
+            if (!liveState.exists) continue;
+            currentText = currentText.slice(0, liveState.range.end) + currentText.slice(liveState.range.end + liveState.markerText.length);
+            changed = true;
+          } else {
+            if (liveState.exists) continue;
+            currentText = currentText.slice(0, liveState.range.end) + liveState.markerText + currentText.slice(liveState.range.end);
+            changed = true;
+          }
+        }
+
+        if (!changed) {
+          setStatus(shouldRemoveAll ? "No inline annotations were removed." : "No inline annotations were added.", "warning");
+          return;
+        }
+
+        setEditorView("markdown");
+        setEditorText(currentText, { preserveScroll: true, preserveSelection: true });
+        renderReviewNotesList();
+        updateReviewNotesUi();
+        if (reviewNotesInlineAllBtn && typeof reviewNotesInlineAllBtn.focus === "function") {
+          reviewNotesInlineAllBtn.focus();
+        }
+        setStatus(shouldRemoveAll ? "Removed inline annotations from all comments." : "Added inline annotations from all comments.", "success");
       }
 
       function updateScratchpadUi() {
         const normalized = String(scratchpadText || "");
         const hasContent = Boolean(normalized.trim());
+        const descriptor = getCurrentStudioDocumentDescriptor();
         if (scratchpadBtn) {
           scratchpadBtn.textContent = hasContent ? "Scratchpad •" : "Scratchpad";
           scratchpadBtn.classList.toggle("has-content", hasContent);
           scratchpadBtn.title = hasContent
-            ? "Open your local persistent scratchpad. Current notes persist after closing until you edit or clear them."
-            : "Open a local persistent scratchpad for quick notes. Anything you type will persist after closing until you edit or clear it.";
+            ? ("Open the local persistent scratchpad for this document/draft. Scope: " + descriptor.label + ". File-backed docs come back across Pi restarts; unsaved drafts stay with this draft instance until saved or cleared.")
+            : ("Open a local persistent scratchpad for this document/draft. Scope: " + descriptor.label + ". File-backed docs come back across Pi restarts; unsaved drafts stay with this draft instance until saved or cleared.");
         }
         if (scratchpadMetaEl) {
           scratchpadMetaEl.textContent = hasContent
-            ? "Saved locally · persists after close · " + normalized.length + " chars"
-            : "Empty · local only";
+            ? ("Saved locally for this document/draft · " + normalized.length + " chars")
+            : "Empty · local to this document/draft";
         }
         if (scratchpadInsertBtn) scratchpadInsertBtn.disabled = !hasContent;
         if (scratchpadCopyBtn) scratchpadCopyBtn.disabled = !hasContent;
@@ -3693,7 +4746,7 @@
       function closeScratchpad(options) {
         if (!scratchpadOverlayEl || scratchpadOverlayEl.hidden) return;
         scratchpadOverlayEl.hidden = true;
-        document.body.classList.remove("scratchpad-open");
+        syncModalOpenState();
         const focusTarget = options && Object.prototype.hasOwnProperty.call(options, "focusTarget")
           ? options.focusTarget
           : (scratchpadReturnFocusEl || scratchpadBtn || sourceTextEl);
@@ -3708,11 +4761,14 @@
 
       function openScratchpad() {
         if (!scratchpadOverlayEl) return;
+        if (isReviewNotesOpen()) {
+          closeReviewNotes({ focusTarget: null });
+        }
         scratchpadReturnFocusEl = document.activeElement && document.activeElement !== document.body
           ? document.activeElement
           : sourceTextEl;
         scratchpadOverlayEl.hidden = false;
-        document.body.classList.add("scratchpad-open");
+        syncModalOpenState();
         if (scratchpadTextEl && typeof scratchpadTextEl.focus === "function") {
           const schedule = typeof window.requestAnimationFrame === "function"
             ? window.requestAnimationFrame.bind(window)
@@ -3727,6 +4783,49 @@
         }
       }
 
+      function closeReviewNotes(options) {
+        if (!reviewNotesOverlayEl || reviewNotesOverlayEl.hidden) return;
+        reviewNotesOverlayEl.hidden = true;
+        updateReviewNotesUi();
+        if (editorView === "markdown") {
+          scheduleEditorLineNumberRender();
+        }
+        const focusTarget = options && Object.prototype.hasOwnProperty.call(options, "focusTarget")
+          ? options.focusTarget
+          : (reviewNotesReturnFocusEl || reviewNotesBtn || sourceTextEl);
+        reviewNotesReturnFocusEl = null;
+        if (focusTarget && typeof focusTarget.focus === "function") {
+          const schedule = typeof window.requestAnimationFrame === "function"
+            ? window.requestAnimationFrame.bind(window)
+            : (cb) => window.setTimeout(cb, 16);
+          schedule(() => focusTarget.focus());
+        }
+      }
+
+      function openReviewNotes() {
+        if (!reviewNotesOverlayEl) return;
+        if (isScratchpadOpen()) {
+          closeScratchpad({ focusTarget: null });
+        }
+        reviewNotesReturnFocusEl = document.activeElement && document.activeElement !== document.body
+          ? document.activeElement
+          : sourceTextEl;
+        reviewNotesOverlayEl.hidden = false;
+        renderReviewNotesList();
+        updateReviewNotesUi();
+        if (editorView === "markdown") {
+          scheduleEditorLineNumberRender();
+        }
+      }
+
+      function toggleReviewNotes() {
+        if (isReviewNotesOpen()) {
+          closeReviewNotes({ focusTarget: reviewNotesBtn || sourceTextEl });
+        } else {
+          openReviewNotes();
+        }
+      }
+
       function insertScratchpadIntoEditor() {
         const content = String(scratchpadText || "");
         if (!content.trim()) {
@@ -3932,8 +5031,8 @@
         if (annotationModeSelect) {
           annotationModeSelect.value = annotationsEnabled ? "on" : "off";
           annotationModeSelect.title = annotationsEnabled
-            ? "Annotations On: keep and send [an: ...] markers."
-            : "Annotations Hidden: keep markers in editor, hide in preview, and strip before Run/Critique.";
+            ? "Inline annotations On: keep and send [an: ...] markers."
+            : "Inline annotations Hide: keep markers in the editor, hide them in preview, and strip before Run/Critique.";
         }
 
         syncRunAndCritiqueButtons();
@@ -4110,6 +5209,7 @@
 
           let loadedInitialDocument = false;
           if (
+            !explicitDocumentIdentityFromUrl &&
             !initialDocumentApplied &&
             message.initialDocument &&
             typeof message.initialDocument.text === "string"
@@ -4121,6 +5221,9 @@
               source: message.initialDocument.source || "blank",
               label: message.initialDocument.label || "blank",
               path: message.initialDocument.path || null,
+              draftId: typeof message.initialDocument.draftId === "string" && message.initialDocument.draftId.trim()
+                ? message.initialDocument.draftId.trim()
+                : (initialSourceState.draftId || null),
             });
             if (message.initialDocument.path) {
               markFileBackedBaseline(message.initialDocument.text);
@@ -4333,6 +5436,8 @@
               source: "file",
               label: message.label || message.path,
               path: message.path,
+            }, {
+              carryCurrentMetadataToNewDocument: true,
             });
             markFileBackedBaseline(sourceTextEl.value);
           }
@@ -4403,7 +5508,12 @@
             : null;
 
           setEditorText(nextDoc.text, { preserveScroll: false, preserveSelection: false });
-          setSourceState({ source: nextSource, label: nextLabel, path: nextPath });
+          setSourceState({
+            source: nextSource,
+            label: nextLabel,
+            path: nextPath,
+            draftId: typeof nextDoc.draftId === "string" && nextDoc.draftId.trim() ? nextDoc.draftId.trim() : null,
+          });
           if (nextPath) {
             markFileBackedBaseline(nextDoc.text);
           }
@@ -4855,6 +5965,8 @@
       window.addEventListener("keydown", handlePaneShortcut);
       window.addEventListener("beforeunload", () => {
         stopFooterSpinner();
+        flushScratchpadPersistence();
+        flushReviewNotesPersistence();
       });
 
       editorViewSelect.addEventListener("change", () => {
@@ -5006,6 +6118,10 @@
       sourceTextEl.addEventListener("input", () => {
         renderSourcePreview({ previewDelayMs: PREVIEW_INPUT_DEBOUNCE_MS });
         scheduleEditorMetaUpdate();
+        if (isReviewNotesOpen() && reviewNotes.length > 0) {
+          renderReviewNotesList();
+          updateReviewNotesUi();
+        }
       });
 
       sourceTextEl.addEventListener("scroll", () => {
@@ -5026,9 +6142,7 @@
       window.addEventListener("resize", () => {
         if (editorView !== "markdown") return;
         syncEditorHighlightScroll();
-        if (lineNumbersEnabled) {
-          scheduleEditorLineNumberRender();
-        }
+        scheduleEditorLineNumberRender();
       });
 
       insertHeaderBtn.addEventListener("click", () => {
@@ -5353,6 +6467,47 @@
         }
       });
 
+      if (reviewNotesBtn) {
+        reviewNotesBtn.addEventListener("click", () => {
+          toggleReviewNotes();
+        });
+      }
+
+      if (reviewNotesCloseBtn) {
+        reviewNotesCloseBtn.addEventListener("click", () => {
+          closeReviewNotes();
+        });
+      }
+
+      if (reviewNotesDoneBtn) {
+        reviewNotesDoneBtn.addEventListener("click", () => {
+          closeReviewNotes();
+        });
+      }
+
+      if (reviewNotesAddBtn) {
+        reviewNotesAddBtn.addEventListener("click", () => {
+          addReviewNoteFromEditorSelection();
+        });
+      }
+
+      if (reviewNotesInlineAllBtn) {
+        reviewNotesInlineAllBtn.addEventListener("click", () => {
+          toggleAllReviewNotesInlineAnnotations();
+        });
+      }
+
+      if (reviewNoteGutterContentEl) {
+        reviewNoteGutterContentEl.addEventListener("click", (event) => {
+          const target = event.target;
+          const markerBtn = target instanceof Element ? target.closest(".editor-review-note-marker") : null;
+          if (!markerBtn) return;
+          const noteId = markerBtn.getAttribute("data-review-note-id") || "";
+          if (!noteId) return;
+          focusReviewNoteInPanel(noteId);
+        });
+      }
+
       if (scratchpadBtn) {
         scratchpadBtn.addEventListener("click", () => {
           openScratchpad();
@@ -5487,6 +6642,11 @@
         syncActionButtons();
         renderSourcePreview();
       }
+      if (sourceBadgeEl) {
+        sourceBadgeEl.addEventListener("click", () => {
+          resetEditorOrigin();
+        });
+      }
       if (resourceDirBtn) {
         resourceDirBtn.addEventListener("click", () => {
           showResourceDirState("input");
@@ -5558,7 +6718,7 @@
 
       if (sourceEditorWrapEl && typeof ResizeObserver === "function") {
         const editorResizeObserver = new ResizeObserver(() => {
-          if (editorView !== "markdown" || !lineNumbersEnabled) return;
+          if (editorView !== "markdown") return;
           scheduleEditorLineNumberRender();
         });
         editorResizeObserver.observe(sourceEditorWrapEl);
@@ -5568,7 +6728,6 @@
       refreshResponseUi();
       updateAnnotatedReplyHeaderButton();
       setActivePane("left");
-      setScratchpadText(readStoredScratchpadText() || "", { persist: false });
 
       const storedEditorHighlightEnabled = readStoredEditorHighlightEnabled();
       const initialHighlightEnabled = storedEditorHighlightEnabled ?? Boolean(highlightSelect && highlightSelect.value !== "off");