pi-studio 0.5.35 → 0.5.36

package/client/studio-client.js

@@ -241,8 +241,11 @@
       let responseHighlightEnabled = false;
       let editorHighlightRenderRaf = null;
       let annotationsEnabled = true;
-      const ANNOTATION_MARKER_REGEX = /\[an:\s*([^\]]+?)\]/gi;
       const PREVIEW_ANNOTATION_PLACEHOLDER_PREFIX = "PISTUDIOANNOT";
+      const annotationHelpers = globalThis.PiStudioAnnotationHelpers;
+      if (!annotationHelpers || typeof annotationHelpers.collectInlineAnnotationMarkers !== "function") {
+        throw new Error("Studio annotation helpers failed to load.");
+      }
       const EMPTY_OVERLAY_LINE = "\u200b";
       const MERMAID_CDN_URL = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
       const MATHJAX_CDN_URL = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js";
@@ -1163,15 +1166,11 @@
       }
 
       function hasAnnotationMarkers(text) {
-        const source = String(text || "");
-        ANNOTATION_MARKER_REGEX.lastIndex = 0;
-        const hasMarker = ANNOTATION_MARKER_REGEX.test(source);
-        ANNOTATION_MARKER_REGEX.lastIndex = 0;
-        return hasMarker;
+        return annotationHelpers.hasAnnotationMarkers(text);
       }
 
       function stripAnnotationMarkers(text) {
-        return String(text || "").replace(ANNOTATION_MARKER_REGEX, "");
+        return annotationHelpers.stripAnnotationMarkers(text);
       }
 
       function prepareEditorTextForSend(text) {
@@ -1184,78 +1183,8 @@
         return annotationsEnabled ? raw : stripAnnotationMarkers(raw);
       }
 
-      function normalizePreviewAnnotationLabel(text) {
-        return String(text || "")
-          .replace(/\r\n/g, "\n")
-          .replace(/\s*\n\s*/g, " ")
-          .replace(/\s{2,}/g, " ")
-          .trim();
-      }
-
       function prepareMarkdownForPandocPreview(markdown) {
-        const source = String(markdown || "").replace(/\r\n/g, "\n");
-        const placeholders = [];
-        if (!source) {
-          return { markdown: source, placeholders: placeholders };
-        }
-
-        const lines = source.split("\n");
-        const out = [];
-        let plainBuffer = [];
-        let inFence = false;
-        let fenceChar = null;
-        let fenceLength = 0;
-
-        function flushPlain() {
-          if (plainBuffer.length === 0) return;
-          const segment = plainBuffer.join("\n").replace(/\[an:\s*([^\]]+?)\]/gi, function(_match, markerText) {
-            const label = normalizePreviewAnnotationLabel(markerText);
-            if (!label) return "";
-            const token = PREVIEW_ANNOTATION_PLACEHOLDER_PREFIX + placeholders.length + "TOKEN";
-            placeholders.push({ token: token, text: label, title: "[an: " + label + "]" });
-            return token;
-          });
-          out.push(segment);
-          plainBuffer = [];
-        }
-
-        for (const line of lines) {
-          const trimmed = line.trimStart();
-          const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
-
-          if (fenceMatch) {
-            const marker = fenceMatch[1] || "";
-            const markerChar = marker.charAt(0);
-            const markerLength = marker.length;
-
-            if (!inFence) {
-              flushPlain();
-              inFence = true;
-              fenceChar = markerChar;
-              fenceLength = markerLength;
-              out.push(line);
-              continue;
-            }
-
-            if (fenceChar === markerChar && markerLength >= fenceLength) {
-              inFence = false;
-              fenceChar = null;
-              fenceLength = 0;
-            }
-
-            out.push(line);
-            continue;
-          }
-
-          if (inFence) {
-            out.push(line);
-          } else {
-            plainBuffer.push(line);
-          }
-        }
-
-        flushPlain();
-        return { markdown: out.join("\n"), placeholders: placeholders };
+        return annotationHelpers.prepareMarkdownForPandocPreview(markdown, PREVIEW_ANNOTATION_PLACEHOLDER_PREFIX);
       }
 
       function wrapAsFencedCodeBlock(text, language) {
@@ -1774,8 +1703,9 @@
             if (entry) {
               const markerEl = document.createElement("span");
               markerEl.className = "annotation-preview-marker";
-              markerEl.textContent = typeof entry.text === "string" ? entry.text : token;
-              markerEl.title = typeof entry.title === "string" ? entry.title : markerEl.textContent;
+              const markerText = typeof entry.text === "string" ? entry.text : token;
+              markerEl.title = typeof entry.title === "string" ? entry.title : markerText;
+              setAnnotationPreviewMarkerContent(markerEl, markerText);
               fragment.appendChild(markerEl);
             } else {
               fragment.appendChild(document.createTextNode(token));
@@ -1819,33 +1749,28 @@
         for (const textNode of textNodes) {
           const text = typeof textNode.nodeValue === "string" ? textNode.nodeValue : "";
           if (!text) continue;
-          ANNOTATION_MARKER_REGEX.lastIndex = 0;
-          if (!ANNOTATION_MARKER_REGEX.test(text)) continue;
-          ANNOTATION_MARKER_REGEX.lastIndex = 0;
+          const markers = annotationHelpers.collectInlineAnnotationMarkers(text);
+          if (markers.length === 0) continue;
 
           const fragment = document.createDocumentFragment();
           let lastIndex = 0;
-          let match;
-          while ((match = ANNOTATION_MARKER_REGEX.exec(text)) !== null) {
-            const token = match[0] || "";
-            const start = typeof match.index === "number" ? match.index : 0;
-            if (start > lastIndex) {
-              fragment.appendChild(document.createTextNode(text.slice(lastIndex, start)));
+          markers.forEach(function(marker) {
+            const token = marker.raw || "";
+            if (marker.start > lastIndex) {
+              fragment.appendChild(document.createTextNode(text.slice(lastIndex, marker.start)));
             }
 
             if (mode === "highlight") {
               const markerEl = document.createElement("span");
               markerEl.className = "annotation-preview-marker";
-              markerEl.textContent = typeof match[1] === "string" ? match[1].trim() : token;
+              const markerText = annotationHelpers.normalizePreviewAnnotationLabel(marker.body) || token;
               markerEl.title = token;
+              setAnnotationPreviewMarkerContent(markerEl, markerText);
               fragment.appendChild(markerEl);
             }
 
-            lastIndex = start + token.length;
-            if (token.length === 0) {
-              ANNOTATION_MARKER_REGEX.lastIndex += 1;
-            }
-          }
+            lastIndex = marker.end;
+          });
 
           if (lastIndex < text.length) {
             fragment.appendChild(document.createTextNode(text.slice(lastIndex)));
@@ -2732,50 +2657,44 @@
         return "<span class='" + className + "'>" + escapeHtml(String(text || "")) + "</span>";
       }
 
-      function wrapHighlightWithTitle(className, text, title) {
+      function buildAnnotationPreviewMarkerHtml(text, title) {
         const titleAttr = title ? " title='" + escapeHtml(String(title)) + "'" : "";
-        return "<span class='" + className + "'" + titleAttr + ">" + escapeHtml(String(text || "")) + "</span>";
+        const rendered = typeof annotationHelpers.renderPreviewAnnotationHtml === "function"
+          ? annotationHelpers.renderPreviewAnnotationHtml(text)
+          : escapeHtml(String(text || ""));
+        return "<span class='annotation-preview-marker'" + titleAttr + ">" + rendered + "</span>";
+      }
+
+      function setAnnotationPreviewMarkerContent(markerEl, text) {
+        if (!markerEl) return;
+        const rendered = typeof annotationHelpers.renderPreviewAnnotationHtml === "function"
+          ? annotationHelpers.renderPreviewAnnotationHtml(text)
+          : escapeHtml(String(text || ""));
+        markerEl.innerHTML = rendered;
       }
 
       function highlightInlineAnnotations(text, mode) {
         const source = String(text || "");
         const renderMode = mode === "preview" ? "preview" : "overlay";
-        ANNOTATION_MARKER_REGEX.lastIndex = 0;
-        let lastIndex = 0;
-        let out = "";
-
-        let match;
-        while ((match = ANNOTATION_MARKER_REGEX.exec(source)) !== null) {
-          const token = match[0] || "";
-          const start = typeof match.index === "number" ? match.index : 0;
-          const markerText = typeof match[1] === "string" ? match[1].trim() : token;
-
-          if (start > lastIndex) {
-            out += escapeHtml(source.slice(lastIndex, start));
-          }
-
-          if (renderMode === "preview") {
-            out += wrapHighlightWithTitle("annotation-preview-marker", markerText || token, token);
-          } else {
-            out += wrapHighlight(annotationsEnabled ? "hl-annotation" : "hl-annotation-muted", token);
-          }
-          lastIndex = start + token.length;
-          if (token.length === 0) {
-            ANNOTATION_MARKER_REGEX.lastIndex += 1;
-          }
-        }
-
-        ANNOTATION_MARKER_REGEX.lastIndex = 0;
-        if (lastIndex < source.length) {
-          out += escapeHtml(source.slice(lastIndex));
-        }
-
-        return out;
+        return annotationHelpers.replaceInlineAnnotationMarkers(
+          source,
+          function(marker) {
+            const token = marker.raw || "";
+            const markerText = annotationHelpers.normalizePreviewAnnotationLabel(marker.body) || token;
+            if (renderMode === "preview") {
+              return buildAnnotationPreviewMarkerHtml(markerText, token);
+            }
+            return wrapHighlight(annotationsEnabled ? "hl-annotation" : "hl-annotation-muted", token);
+          },
+          function(segment) {
+            return escapeHtml(segment);
+          },
+        );
       }
 
-      function highlightInlineMarkdown(text) {
+      function highlightInlineMarkdownWithoutAnnotations(text) {
         const source = String(text || "");
-        const pattern = /(\x60[^\x60]*\x60)|(\[[^\]]+\]\([^)]+\))|(\[an:\s*[^\]]+\])/gi;
+        const pattern = /(\x60[^\x60]*\x60)|(\[[^\]]+\]\([^)]+\))/g;
         let lastIndex = 0;
         let out = "";
 
@@ -2798,8 +2717,6 @@
             } else {
               out += escapeHtml(token);
             }
-          } else if (match[3]) {
-            out += highlightInlineAnnotations(token);
           } else {
             out += escapeHtml(token);
           }
@@ -2814,6 +2731,18 @@
         return out;
       }
 
+      function highlightInlineMarkdown(text) {
+        return annotationHelpers.replaceInlineAnnotationMarkers(
+          String(text || ""),
+          function(marker) {
+            return highlightInlineAnnotations(marker.raw || "");
+          },
+          function(segment) {
+            return highlightInlineMarkdownWithoutAnnotations(segment);
+          },
+        );
+      }
+
       function normalizeFenceLanguage(info) {
         const raw = String(info || "").trim();
         if (!raw) return "";

package/client/studio.css

@@ -523,6 +523,14 @@
       vertical-align: baseline;
     }
 
+    .annotation-preview-marker code {
+      font-family: var(--mono-font, ui-monospace, SFMono-Regular, Menlo, monospace);
+      font-size: 0.95em;
+      background: rgba(0, 0, 0, 0.08);
+      border-radius: 3px;
+      padding: 0 0.2em;
+    }
+
     #sourcePreview {
       flex: 1 1 auto;
       min-height: 0;

package/index.ts

@@ -8,6 +8,16 @@ import { homedir, tmpdir } from "node:os";
 import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { URL, pathToFileURL } from "node:url";
 import { WebSocketServer, WebSocket, type RawData } from "ws";
+import {
+	collectStudioInlineAnnotationMarkers,
+	hasStudioMarkdownAnnotationMarkers,
+	isStudioAnnotationWordChar,
+	normalizeStudioAnnotationText,
+	readStudioAnnotationProtectedTokenAt,
+	replaceStudioInlineAnnotationMarkers,
+	transformStudioMarkdownOutsideFences,
+} from "./shared/studio-annotation-scanner.js";
+import { escapeStudioPdfLatexTextFragment } from "./shared/studio-pdf-escape.js";
 
 type Lens = "writing" | "code";
 type RequestedLens = Lens | "auto";
@@ -18,6 +28,7 @@ type StudioPromptMode = "response" | "run" | "effective";
 type StudioPromptTriggerKind = "run" | "steer";
 
 const STUDIO_CSS_URL = new URL("./client/studio.css", import.meta.url);
+const STUDIO_ANNOTATION_HELPERS_URL = new URL("./client/studio-annotation-helpers.js", import.meta.url);
 const STUDIO_CLIENT_URL = new URL("./client/studio-client.js", import.meta.url);
 
 interface StudioServerState {
@@ -3023,14 +3034,6 @@ function inferStudioPdfLanguage(markdown: string, editorLanguage?: string): stri
 	return undefined;
 }
 
-function escapeStudioPdfLatexTextFragment(text: string): string {
-	return String(text ?? "")
-		.replace(/\\/g, "\\textbackslash{}")
-		.replace(/([{}%#$&_])/g, "\\$1")
-		.replace(/~/g, "\\textasciitilde{}")
-		.replace(/\^/g, "\\textasciicircum{}");
-}
-
 function escapeStudioPdfLatexText(text: string): string {
 	const normalized = String(text ?? "")
 		.replace(/\r\n/g, "\n")
@@ -3085,71 +3088,158 @@ function escapeStudioPdfLatexText(text: string): string {
 	return out.trim();
 }
 
-function replaceStudioAnnotationMarkersForPdfInSegment(text: string): string {
-	return String(text ?? "")
-		.replace(/\[an:\s*([^\]]+?)\]/gi, (_match, markerText: string) => {
-			const cleaned = escapeStudioPdfLatexText(markerText);
-			if (!cleaned) return "";
-			return `\\studioannotation{${cleaned}}`;
-		})
-		.replace(/\{\[\}\s*an:\s*([\s\S]*?)\s*\{\]\}/gi, (_match, markerText: string) => {
-			const cleaned = escapeStudioPdfLatexText(markerText);
-			if (!cleaned) return "";
-			return `\\studioannotation{${cleaned}}`;
-		});
+function renderStudioAnnotationCodeSpanPdfLatex(rawToken: string): string {
+	const raw = String(rawToken ?? "");
+	if (!raw || raw[0] !== "`") return escapeStudioPdfLatexTextFragment(raw);
+
+	let fenceLength = 1;
+	while (raw[fenceLength] === "`") fenceLength += 1;
+	const fence = "`".repeat(fenceLength);
+	if (raw.length < fenceLength * 2 || raw.slice(raw.length - fenceLength) !== fence) {
+		return escapeStudioPdfLatexTextFragment(raw);
+	}
+
+	return `\\texttt{${escapeStudioPdfLatexTextFragment(raw.slice(fenceLength, raw.length - fenceLength))}}`;
 }
 
-function replaceStudioAnnotationMarkersForPdf(markdown: string): string {
-	const lines = String(markdown ?? "").split("\n");
-	const out: string[] = [];
-	let plainBuffer: string[] = [];
-	let inFence = false;
-	let fenceChar: "`" | "~" | undefined;
-	let fenceLength = 0;
+function canOpenStudioAnnotationEmphasisDelimiter(source: string, startIndex: number, delimiter: string): boolean {
+	if (source.slice(startIndex, startIndex + delimiter.length) !== delimiter) return false;
+	const prev = startIndex > 0 ? source[startIndex - 1] ?? "" : "";
+	const next = source[startIndex + delimiter.length] ?? "";
+	if (!next || /\s/.test(next)) return false;
+	return !isStudioAnnotationWordChar(prev);
+}
 
-	const flushPlain = () => {
-		if (plainBuffer.length === 0) return;
-		out.push(replaceStudioAnnotationMarkersForPdfInSegment(plainBuffer.join("\n")));
-		plainBuffer = [];
-	};
+function canCloseStudioAnnotationEmphasisDelimiter(source: string, startIndex: number, delimiter: string): boolean {
+	if (source.slice(startIndex, startIndex + delimiter.length) !== delimiter) return false;
+	const prev = startIndex > 0 ? source[startIndex - 1] ?? "" : "";
+	const next = source[startIndex + delimiter.length] ?? "";
+	if (!prev || /\s/.test(prev)) return false;
+	return !isStudioAnnotationWordChar(next);
+}
 
-	for (const line of lines) {
-		const trimmed = line.trimStart();
-		const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+function renderStudioAnnotationPdfLatexContent(text: string): string {
+	const source = String(text ?? "");
+	let out = "";
+	let plainStart = 0;
+	let index = 0;
 
-		if (fenceMatch) {
-			const marker = fenceMatch[1]!;
-			const markerChar = marker[0] as "`" | "~";
-			const markerLength = marker.length;
+	while (index < source.length) {
+		const token = readStudioAnnotationProtectedTokenAt(source, index);
+		if (!token) {
+			index += 1;
+			continue;
+		}
 
-			if (!inFence) {
-				flushPlain();
-				inFence = true;
-				fenceChar = markerChar;
-				fenceLength = markerLength;
-				out.push(line);
-				continue;
-			}
+		if (index > plainStart) {
+			out += renderStudioAnnotationPlainTextPdfLatex(source.slice(plainStart, index));
+		}
 
-			if (fenceChar === markerChar && markerLength >= fenceLength) {
-				inFence = false;
-				fenceChar = undefined;
-				fenceLength = 0;
-			}
+		if (token.type === "code") {
+			out += renderStudioAnnotationCodeSpanPdfLatex(token.raw);
+		} else if (token.type === "math") {
+			out += escapeStudioPdfLatexText(token.raw);
+		} else {
+			out += escapeStudioPdfLatexTextFragment(token.raw);
+		}
 
-			out.push(line);
+		index = token.end;
+		plainStart = index;
+	}
+
+	if (plainStart < source.length) {
+		out += renderStudioAnnotationPlainTextPdfLatex(source.slice(plainStart));
+	}
+
+	return out;
+}
+
+function readStudioAnnotationPdfEmphasisSpanAt(source: string, startIndex: number, delimiter: string, commandName: string): { end: number; latex: string } | null {
+	if (!canOpenStudioAnnotationEmphasisDelimiter(source, startIndex, delimiter)) return null;
+
+	let index = startIndex + delimiter.length;
+	while (index < source.length) {
+		if (source[index] === "\\") {
+			index = Math.min(source.length, index + 2);
 			continue;
 		}
 
-		if (inFence) {
-			out.push(line);
-		} else {
-			plainBuffer.push(line);
+		const protectedToken = readStudioAnnotationProtectedTokenAt(source, index);
+		if (protectedToken) {
+			index = protectedToken.end;
+			continue;
+		}
+
+		if (canCloseStudioAnnotationEmphasisDelimiter(source, index, delimiter)) {
+			const inner = source.slice(startIndex + delimiter.length, index);
+			return {
+				end: index + delimiter.length,
+				latex: `\\${commandName}{${renderStudioAnnotationPdfLatexContent(inner)}}`,
+			};
 		}
+
+		index += 1;
 	}
 
-	flushPlain();
-	return out.join("\n");
+	return null;
+}
+
+function renderStudioAnnotationPlainTextPdfLatex(text: string): string {
+	const source = String(text ?? "");
+	let out = "";
+	let index = 0;
+
+	while (index < source.length) {
+		const strongMatch = readStudioAnnotationPdfEmphasisSpanAt(source, index, "**", "textbf")
+			?? readStudioAnnotationPdfEmphasisSpanAt(source, index, "__", "textbf");
+		if (strongMatch) {
+			out += strongMatch.latex;
+			index = strongMatch.end;
+			continue;
+		}
+
+		const emphasisMatch = readStudioAnnotationPdfEmphasisSpanAt(source, index, "*", "emph")
+			?? readStudioAnnotationPdfEmphasisSpanAt(source, index, "_", "emph");
+		if (emphasisMatch) {
+			out += emphasisMatch.latex;
+			index = emphasisMatch.end;
+			continue;
+		}
+
+		out += escapeStudioPdfLatexTextFragment(source[index] ?? "");
+		index += 1;
+	}
+
+	return out;
+}
+
+function renderStudioAnnotationPdfLatex(text: string): string {
+	const normalized = normalizeStudioAnnotationText(text);
+	if (!normalized) return "";
+	return renderStudioAnnotationPdfLatexContent(normalized).trim();
+}
+
+function replaceStudioAnnotationMarkersForPdfInSegment(text: string): string {
+	const replaced = replaceStudioInlineAnnotationMarkers(
+		String(text ?? ""),
+		(marker) => {
+			const cleaned = renderStudioAnnotationPdfLatex(marker.body);
+			if (!cleaned) return "";
+			return `\\studioannotation{${cleaned}}`;
+		},
+	);
+
+	return String(replaced ?? "")
+		.replace(/\{\[\}\s*an:\s*([\s\S]*?)\s*\{\]\}/gi, (_match, markerText: string) => {
+			const cleaned = renderStudioAnnotationPdfLatex(markerText);
+			if (!cleaned) return "";
+			return `\\studioannotation{${cleaned}}`;
+		});
+}
+
+function replaceStudioAnnotationMarkersForPdf(markdown: string): string {
+	if (!hasStudioMarkdownAnnotationMarkers(markdown)) return String(markdown ?? "");
+	return transformStudioMarkdownOutsideFences(markdown, (segment) => replaceStudioAnnotationMarkersForPdfInSegment(segment));
 }
 
 interface StudioPdfRenderOptions {
@@ -4146,38 +4236,19 @@ function replaceStudioAnnotationMarkersInDiffTokenLine(line: string, macroName:
 	if (!tokenMatch) return line;
 
 	const body = tokenMatch[1] ?? "";
-	const markerPattern = /\[an:\s*([^\]]+?)\]/gi;
-	let lastIndex = 0;
-	let rewritten = "";
-	let match: RegExpExecArray | null;
-
 	const wrapText = (text: string): string => text ? `\\${macroName}{${text}}` : "";
+	const rewritten = replaceStudioInlineAnnotationMarkers(
+		body,
+		(marker) => {
+			const markerText = decodeStudioGeneratedCodeLatexText(normalizeStudioAnnotationText(marker.body));
+			const cleaned = makeStudioHighlightingMathScriptsVerbatimSafe(renderStudioAnnotationPdfLatex(markerText));
+			if (!cleaned) return "";
+			return `\\studioannotation{${cleaned}}`;
+		},
+		(segment) => wrapText(segment),
+	);
 
-	while ((match = markerPattern.exec(body)) !== null) {
-		const token = match[0] ?? "";
-		const start = match.index;
-		if (start > lastIndex) {
-			rewritten += wrapText(body.slice(lastIndex, start));
-		}
-
-		const markerText = decodeStudioGeneratedCodeLatexText((match[1] ?? "").replace(/\s{2,}/g, " ").trim());
-		const cleaned = makeStudioHighlightingMathScriptsVerbatimSafe(escapeStudioPdfLatexText(markerText));
-		if (cleaned) {
-			rewritten += `\\studioannotation{${cleaned}}`;
-		}
-
-		lastIndex = start + token.length;
-		if (token.length === 0) {
-			markerPattern.lastIndex += 1;
-		}
-	}
-
-	if (lastIndex === 0) return line;
-	if (lastIndex < body.length) {
-		rewritten += wrapText(body.slice(lastIndex));
-	}
-
-	return rewritten || wrapText(body);
+	return rewritten === body ? line : (rewritten || wrapText(body));
 }
 
 function rewriteStudioGeneratedDiffHighlighting(latex: string): string {
@@ -4496,7 +4567,7 @@ async function renderStudioPdfWithPandoc(
 		}
 	};
 
-	if (isLatex && (latexSubfigurePdfTransform.groups.length > 0 || /\[an:\s*[^\]]+\]/i.test(sourceWithResolvedRefs))) {
+	if (isLatex && (latexSubfigurePdfTransform.groups.length > 0 || collectStudioInlineAnnotationMarkers(sourceWithResolvedRefs).length > 0)) {
 		return await renderStudioPdfFromGeneratedLatex(
 			sourceWithResolvedRefs,
 			pandocCommand,
@@ -5627,6 +5698,7 @@ function buildStudioHtml(
 	};
 	const cssVarsBlock = Object.entries(vars).map(([k, v]) => `      ${k}: ${v};`).join("\n");
 	const stylesheetHref = `/studio.css?token=${encodeURIComponent(studioToken ?? "")}`;
+	const annotationHelpersScriptHref = `/studio-annotation-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const clientScriptHref = `/studio-client.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const faviconHref = buildStudioFaviconDataUri(style);
 	const bootConfigJson = JSON.stringify({ mermaidConfig }).replace(/</g, "\\u003c");
@@ -5808,6 +5880,7 @@ ${cssVarsBlock}
   <script>
     window.__PI_STUDIO_BOOT__ = ${bootConfigJson};
   </script>
+  <script src="${annotationHelpersScriptHref}"></script>
   <script src="${clientScriptHref}"></script>
 </body>
 </html>`;
@@ -7353,7 +7426,7 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
-		if (requestUrl.pathname === "/studio-client.js") {
+		if (requestUrl.pathname === "/studio-annotation-helpers.js" || requestUrl.pathname === "/studio-client.js") {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
 				respondText(res, 403, "Invalid or expired studio token. Re-run /studio.");
@@ -7367,8 +7440,15 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
+			const targetUrl = requestUrl.pathname === "/studio-annotation-helpers.js"
+				? STUDIO_ANNOTATION_HELPERS_URL
+				: STUDIO_CLIENT_URL;
+			const targetLabel = requestUrl.pathname === "/studio-annotation-helpers.js"
+				? "studio annotation helper script"
+				: "studio client script";
+
 			try {
-				const clientScript = readFileSync(STUDIO_CLIENT_URL, "utf-8");
+				const clientScript = readFileSync(targetUrl, "utf-8");
 				res.writeHead(200, {
 					"Content-Type": "application/javascript; charset=utf-8",
 					"Cache-Control": "no-store",
@@ -7377,7 +7457,7 @@ export default function (pi: ExtensionAPI) {
 				});
 				res.end(clientScript);
 			} catch (error) {
-				respondText(res, 500, `Failed to load studio client script: ${error instanceof Error ? error.message : String(error)}`);
+				respondText(res, 500, `Failed to load ${targetLabel}: ${error instanceof Error ? error.message : String(error)}`);
 			}
 			return;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.5.35",
+  "version": "0.5.36",
   "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, prompt/response history, and live Markdown/LaTeX/code preview",
   "type": "module",
   "license": "MIT",
@@ -18,11 +18,15 @@
   "files": [
     "index.ts",
     "client",
+    "shared",
     "README.md",
     "CHANGELOG.md",
     "WORKFLOW.md",
     "assets/screenshots"
   ],
+  "scripts": {
+    "test": "node --test"
+  },
   "pi": {
     "extensions": [
       "./index.ts"