pi-studio 0.5.56 → 0.5.57

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.5.57] — 2026-04-20
+
+### Changed
+- The inserted annotated-reply scaffold now renders more cleanly in Markdown preview, using `annotated reply: below` plus a short metadata list instead of relying on hard line-break spacing.
+- Local review-note comment boxes now use normal multiline textarea behavior, so `Enter` inserts a newline while edits continue saving automatically as you type.
+
+### Fixed
+- Markdown preview now preserves standalone LaTeX math definition lines such as `\newcommand`, `\def`, and `\DeclareMathOperator` so custom math macros/operators can work in Markdown documents instead of showing up as literal preview text.
+- Markdown PDF export now moves standalone LaTeX math definition lines into the generated PDF preamble when needed, avoiding LaTeX errors like `Can be used only in preamble` for commands such as `\DeclareMathOperator`.
+- Annotated-reply header detection now accepts both the older `annotated reply below:` form and the newer `annotated reply: below` form when removing/reapplying the scaffold.
+
 ## [0.5.56] — 2026-04-15
 
 ### Removed

package/WORKFLOW.md

@@ -20,9 +20,11 @@ Studio uses a **single workspace**:
 Adds/updates an `annotated-reply` compatible scaffold in the editor:
 
 ```md
-annotated reply below:
-original source: <last model response | file <path> | studio editor>
-annotation syntax: [an: your note]
+annotated reply: below
+
+- original source: <last model response | file <path> | studio editor>
+- user annotation syntax: [an: your note]
+- precedence: later messages supersede these annotations unless user explicitly references them
 
 ---
 

package/client/studio-client.js

@@ -8103,7 +8103,7 @@
           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.";
+          textarea.title = "Write a local comment. Enter inserts a new line; changes save automatically as you type.";
           card.appendChild(textarea);
 
           const footer = document.createElement("div");
@@ -8169,22 +8169,6 @@
             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()) {
@@ -9684,10 +9668,10 @@
 
       function buildAnnotationHeader() {
         const sourceDescriptor = describeSourceForAnnotation();
-        let header = "annotated reply below:\n";
-        header += "original source: " + sourceDescriptor + "\n";
-        header += "user annotation syntax: [an: note]\n";
-        header += "precedence: later messages supersede these annotations unless user explicitly references them\n\n---\n\n";
+        let header = "annotated reply: below\n\n";
+        header += "- original source: " + sourceDescriptor + "\n";
+        header += "- user annotation syntax: [an: note]\n";
+        header += "- precedence: later messages supersede these annotations unless user explicitly references them\n\n---\n\n";
         return header;
       }
 
@@ -9697,7 +9681,8 @@
 
       function stripAnnotationHeader(text) {
         const normalized = String(text || "").replace(/\r\n/g, "\n");
-        if (!normalized.toLowerCase().startsWith("annotated reply below:")) {
+        const lower = normalized.toLowerCase();
+        if (!lower.startsWith("annotated reply: below") && !lower.startsWith("annotated reply below:")) {
           return { hadHeader: false, body: normalized };
         }
 

package/index.ts

@@ -20,7 +20,10 @@ import {
 	transformStudioMarkdownOutsideFences,
 } from "./shared/studio-annotation-scanner.js";
 import { stripStudioMarkdownHtmlComments } from "./shared/studio-markdown-html-comments.js";
-import { preserveLiteralLatexCommandsInMarkdown } from "./shared/studio-markdown-latex-literals.js";
+import {
+	extractStandaloneLatexDefinitionsFromMarkdown,
+	preserveLiteralLatexCommandsInMarkdown,
+} from "./shared/studio-markdown-latex-literals.js";
 import { escapeStudioPdfLatexTextFragment } from "./shared/studio-pdf-escape.js";
 
 type Lens = "writing" | "code";
@@ -477,7 +480,7 @@ function buildStudioPdfCalloutTitleSizeCommand(options?: StudioPdfRenderOptions)
 	return "\\footnotesize";
 }
 
-function buildStudioPdfPreamble(options?: StudioPdfRenderOptions): string {
+function buildStudioPdfPreamble(options?: StudioPdfRenderOptions, extraPreamble = ""): string {
 	const sectionHeadingSize = buildStudioPdfHeadingSizeCommand(options?.sectionSize, "\\Large");
 	const subsectionHeadingSize = buildStudioPdfHeadingSizeCommand(options?.subsectionSize, "\\large");
 	const subsubsectionHeadingSize = buildStudioPdfHeadingSizeCommand(options?.subsubsectionSize, "\\normalsize");
@@ -543,7 +546,7 @@ function buildStudioPdfPreamble(options?: StudioPdfRenderOptions): string {
   \\RecustomVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\\\\{\\},breaklines,breakanywhere,bgcolor=StudioCodeBlockBg,framesep=2mm}%
 }
 \\makeatother
-`;
+${extraPreamble ? `${extraPreamble.trim()}\n` : ""}`;
 }
 
 type StudioThemeMode = "dark" | "light";
@@ -4478,6 +4481,7 @@ async function renderStudioPdfFromGeneratedLatex(
 	calloutBlocks: StudioPdfMarkdownCalloutBlock[] = [],
 	alignedImageBlocks: StudioPdfAlignedImageBlock[] = [],
 	pdfOptions?: StudioPdfRenderOptions,
+	extraPreamble = "",
 ): Promise<{ pdf: Buffer; warning?: string }> {
 	const tempDir = join(tmpdir(), `pi-studio-pdf-${Date.now()}-${randomUUID()}`);
 	const preamblePath = join(tempDir, "_pdf_preamble.tex");
@@ -4485,7 +4489,7 @@ async function renderStudioPdfFromGeneratedLatex(
 	const outputPath = join(tempDir, "studio-export.pdf");
 
 	await mkdir(tempDir, { recursive: true });
-	await writeFile(preamblePath, buildStudioPdfPreamble(pdfOptions), "utf-8");
+	await writeFile(preamblePath, buildStudioPdfPreamble(pdfOptions, extraPreamble), "utf-8");
 
 	const pandocArgs = [
 		"-f", inputFormat,
@@ -4767,17 +4771,22 @@ async function renderStudioPdfWithPandoc(
 		? "latex"
 		: "markdown+lists_without_preceding_blankline-blank_before_blockquote-blank_before_header+tex_math_dollars+tex_math_single_backslash+tex_math_double_backslash+autolink_bare_uris+superscript+subscript-raw_html";
 	const normalizedMarkdown = prepareStudioPdfMarkdown(pdfAlignedImageTransform.markdown, isLatex, effectiveEditorLanguage);
+	const markdownPreambleSplit = !isLatex && (!effectiveEditorLanguage || effectiveEditorLanguage === "markdown")
+		? extractStandaloneLatexDefinitionsFromMarkdown(normalizedMarkdown)
+		: { body: normalizedMarkdown, definitions: [], preamble: "" };
+	const normalizedMarkdownBody = markdownPreambleSplit.body;
+	const extraPdfPreamble = markdownPreambleSplit.preamble;
 
 	const tempDir = join(tmpdir(), `pi-studio-pdf-${Date.now()}-${randomUUID()}`);
 	const preamblePath = join(tempDir, "_pdf_preamble.tex");
 	const outputPath = join(tempDir, "studio-export.pdf");
 
 	await mkdir(tempDir, { recursive: true });
-	await writeFile(preamblePath, buildStudioPdfPreamble(pdfOptions), "utf-8");
+	await writeFile(preamblePath, buildStudioPdfPreamble(pdfOptions, extraPdfPreamble), "utf-8");
 
 	const mermaidPrepared: StudioMermaidPdfPreprocessResult = isLatex
-		? { markdown: normalizedMarkdown, found: 0, replaced: 0, failed: 0, missingCli: false }
-		: await preprocessStudioMermaidForPdf(normalizedMarkdown, tempDir);
+		? { markdown: normalizedMarkdownBody, found: 0, replaced: 0, failed: 0, missingCli: false }
+		: await preprocessStudioMermaidForPdf(normalizedMarkdownBody, tempDir);
 	const markdownForPdf = mermaidPrepared.markdown;
 	const hasDiffBlocks = !isLatex && hasStudioMarkdownDiffFence(markdownForPdf);
 
@@ -4795,6 +4804,7 @@ async function renderStudioPdfWithPandoc(
 			pdfCalloutTransform.blocks,
 			pdfAlignedImageTransform.blocks,
 			pdfOptions,
+			extraPdfPreamble,
 		);
 		await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
 		return { pdf: rendered.pdf, warning: mermaidPrepared.warning ?? rendered.warning };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.5.56",
+  "version": "0.5.57",
   "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",

package/shared/studio-markdown-latex-literals.js

@@ -51,6 +51,18 @@ const STUDIO_LITERAL_MARKDOWN_LATEX_COMMANDS = new Set([
   "tex",
 ]);
 
+const STUDIO_STANDALONE_MARKDOWN_LATEX_DEFINITION_COMMANDS = new Set([
+  "newcommand",
+  "renewcommand",
+  "providecommand",
+  "declaremathoperator",
+  "def",
+  "gdef",
+  "edef",
+  "xdef",
+  "let",
+]);
+
 function isEscapedAt(text, index) {
   let slashCount = 0;
   for (let i = index - 1; i >= 0 && text[i] === "\\"; i -= 1) {
@@ -70,12 +82,40 @@ function findClosingUnescapedDelimiter(text, startIndex, delimiter) {
   return -1;
 }
 
+function isStandaloneLatexDefinitionLine(line) {
+  const commandMatch = String(line || "").match(/^[ \t]{0,3}\\([A-Za-z@]+)\*?(?=\s|\\|\{|\[|$)/);
+  if (!commandMatch) return false;
+
+  const commandName = String(commandMatch[1] || "").toLowerCase();
+  return STUDIO_STANDALONE_MARKDOWN_LATEX_DEFINITION_COMMANDS.has(commandName);
+}
+
+function readStandaloneLatexDefinitionLine(text, startIndex) {
+  if (startIndex > 0 && text[startIndex - 1] !== "\n") return null;
+
+  const lineEndIndex = text.indexOf("\n", startIndex);
+  const sliceEnd = lineEndIndex >= 0 ? lineEndIndex : text.length;
+  const line = text.slice(startIndex, sliceEnd);
+  if (!isStandaloneLatexDefinitionLine(line)) return null;
+
+  return {
+    text: lineEndIndex >= 0 ? text.slice(startIndex, lineEndIndex + 1) : line,
+    nextIndex: lineEndIndex >= 0 ? lineEndIndex + 1 : text.length,
+  };
+}
+
 function preserveLiteralLatexCommandsInMarkdownSegment(markdown) {
   const source = String(markdown || "");
   let out = "";
   let index = 0;
 
   while (index < source.length) {
+    const standaloneDefinitionLine = readStandaloneLatexDefinitionLine(source, index);
+    if (standaloneDefinitionLine) {
+      out += standaloneDefinitionLine.text;
+      index = standaloneDefinitionLine.nextIndex;
+      continue;
+    }
     if (source[index] === "`") {
       let tickCount = 1;
       while (source[index + tickCount] === "`") tickCount += 1;
@@ -201,3 +241,49 @@ export function preserveLiteralLatexCommandsInMarkdown(markdown) {
   flushPlain();
   return out.join("\n");
 }
+
+export function extractStandaloneLatexDefinitionsFromMarkdown(markdown) {
+  const lines = String(markdown || "").split("\n");
+  const bodyLines = [];
+  const definitions = [];
+  let inFence = false;
+  let fenceChar;
+  let fenceLength = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trimStart();
+    const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+
+    if (fenceMatch) {
+      const marker = fenceMatch[1];
+      const markerChar = marker[0];
+      const markerLength = marker.length;
+
+      if (!inFence) {
+        inFence = true;
+        fenceChar = markerChar;
+        fenceLength = markerLength;
+      } else if (fenceChar === markerChar && markerLength >= fenceLength) {
+        inFence = false;
+        fenceChar = undefined;
+        fenceLength = 0;
+      }
+
+      bodyLines.push(line);
+      continue;
+    }
+
+    if (!inFence && isStandaloneLatexDefinitionLine(line)) {
+      definitions.push(line);
+      continue;
+    }
+
+    bodyLines.push(line);
+  }
+
+  return {
+    body: bodyLines.join("\n"),
+    definitions,
+    preamble: definitions.join("\n"),
+  };
+}