pi-studio 0.5.55 → 0.5.57

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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
+- Removed Studio's standalone npm update checker and footer update badge now that package update tracking is handled in pi.
+
+### Fixed
+- Studio now always prints its localhost URL even when automatic browser open fails, and SSH sessions get a localhost-only port-forwarding hint instead of needing non-local binding.
+
 ## [0.5.54] — 2026-04-13
 
 ### Fixed

package/README.md

@@ -74,6 +74,7 @@ pi -e https://github.com/omaclaren/pi-studio
 ## Notes
 
 - Local-only server (`127.0.0.1`) with tokenized Studio URLs.
+- For remote SSH sessions, keep Studio bound to localhost and use SSH local port forwarding; `/studio` prints the localhost URL and an SSH tunnel hint when SSH is detected.
 - Full Studio is a singleton per Pi session: use `/studio` to open it, `/studio-replace` to explicitly replace it, and `/studio-editor-only` for extra editing/preview tabs that do not take over the full Studio session view.
 - Studio is designed as a complement to terminal pi, not a replacement.
 - Editor/code font uses a best-effort terminal-monospace match when the current terminal config exposes it; set `PI_STUDIO_FONT_MONO` to force a specific CSS `font-family` stack.

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

@@ -202,8 +202,6 @@
       let contextTokens = null;
       let contextWindow = null;
       let contextPercent = null;
-      let updateInstalledVersion = null;
-      let updateLatestVersion = null;
       let windowHasFocus = typeof document.hasFocus === "function" ? document.hasFocus() : true;
       let titleAttentionMessage = "";
       let titleAttentionRequestId = null;
@@ -664,8 +662,6 @@
         if (typeof message.contextTokens === "number") summary.contextTokens = message.contextTokens;
         if (typeof message.contextWindow === "number") summary.contextWindow = message.contextWindow;
         if (typeof message.contextPercent === "number") summary.contextPercent = message.contextPercent;
-        if (typeof message.updateInstalledVersion === "string") summary.updateInstalledVersion = message.updateInstalledVersion;
-        if (typeof message.updateLatestVersion === "string") summary.updateLatestVersion = message.updateLatestVersion;
         if (message.document && typeof message.document === "object" && typeof message.document.text === "string") {
           summary.documentLength = message.document.text.length;
           if (typeof message.document.label === "string") summary.documentLabel = message.document.label;
@@ -926,30 +922,6 @@
         return changed;
       }
 
-      function applyUpdateInfoFromMessage(message) {
-        if (!message || typeof message !== "object") return false;
-
-        let changed = false;
-
-        if (Object.prototype.hasOwnProperty.call(message, "updateInstalledVersion")) {
-          const nextInstalled = parseNonEmptyString(message.updateInstalledVersion);
-          if (nextInstalled !== updateInstalledVersion) {
-            updateInstalledVersion = nextInstalled;
-            changed = true;
-          }
-        }
-
-        if (Object.prototype.hasOwnProperty.call(message, "updateLatestVersion")) {
-          const nextLatest = parseNonEmptyString(message.updateLatestVersion);
-          if (nextLatest !== updateLatestVersion) {
-            updateLatestVersion = nextLatest;
-            changed = true;
-          }
-        }
-
-        return changed;
-      }
-
       function isTitleAttentionRequestKind(kind) {
         return kind === "annotation" || kind === "critique" || kind === "direct";
       }
@@ -1134,13 +1106,7 @@
         const modelText = modelLabel && modelLabel.trim() ? modelLabel.trim() : "none";
         const terminalText = terminalSessionLabel && terminalSessionLabel.trim() ? terminalSessionLabel.trim() : "unknown";
         const contextText = formatContextUsageText();
-        let updateText = "";
-        if (updateLatestVersion) {
-          updateText = updateInstalledVersion
-            ? "Update: " + updateInstalledVersion + " → " + updateLatestVersion
-            : "Update: " + updateLatestVersion + " available";
-        }
-        const text = "Model: " + modelText + " · Terminal: " + terminalText + " · " + contextText + (updateText ? " · " + updateText : "");
+        const text = "Model: " + modelText + " · Terminal: " + terminalText + " · " + contextText;
         if (footerMetaTextEl) {
           footerMetaTextEl.textContent = text;
           footerMetaTextEl.title = text;
@@ -8137,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");
@@ -8203,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()) {
@@ -9000,8 +8950,7 @@
         debugTrace("server_message", summarizeServerMessage(message));
 
         const contextChanged = applyContextUsageFromMessage(message);
-        const updateInfoChanged = applyUpdateInfoFromMessage(message);
-        if (contextChanged || updateInfoChanged) {
+        if (contextChanged) {
           updateFooterMeta();
         }
 
@@ -9719,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;
       }
 
@@ -9732,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";
@@ -272,7 +275,6 @@ const PREVIEW_RENDER_MAX_CHARS = 400_000;
 const PDF_EXPORT_MAX_CHARS = 400_000;
 const REQUEST_BODY_MAX_BYTES = 1_000_000;
 const RESPONSE_HISTORY_LIMIT = 30;
-const UPDATE_CHECK_TIMEOUT_MS = 1800;
 const CMUX_NOTIFY_TIMEOUT_MS = 1200;
 const PREPARED_PDF_EXPORT_TTL_MS = 5 * 60 * 1000;
 const MAX_PREPARED_PDF_EXPORTS = 8;
@@ -478,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");
@@ -544,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";
@@ -2737,93 +2739,6 @@ function readStudioGitDiff(baseDir: string):
 	return { ok: true, text: fullDiff, label };
 }
 
-function readLocalPackageMetadata(): { name: string; version: string } | null {
-	try {
-		const raw = readFileSync(new URL("./package.json", import.meta.url), "utf-8");
-		const parsed = JSON.parse(raw) as { name?: unknown; version?: unknown };
-		const name = typeof parsed.name === "string" ? parsed.name.trim() : "";
-		const version = typeof parsed.version === "string" ? parsed.version.trim() : "";
-		if (!name || !version) return null;
-		return { name, version };
-	} catch {
-		return null;
-	}
-}
-
-interface ParsedSemver {
-	major: number;
-	minor: number;
-	patch: number;
-	prerelease: string | null;
-}
-
-function parseSemverLoose(version: string): ParsedSemver | null {
-	const normalized = String(version || "").trim().replace(/^v/i, "");
-	const match = normalized.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?/);
-	if (!match) return null;
-	const major = Number.parseInt(match[1] ?? "", 10);
-	const minor = Number.parseInt(match[2] ?? "0", 10);
-	const patch = Number.parseInt(match[3] ?? "0", 10);
-	if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch)) return null;
-	const prerelease = typeof match[4] === "string" && match[4].trim() ? match[4].trim() : null;
-	return { major, minor, patch, prerelease };
-}
-
-function compareSemverLoose(a: string, b: string): number {
-	const pa = parseSemverLoose(a);
-	const pb = parseSemverLoose(b);
-	if (!pa || !pb) {
-		return a.localeCompare(b, undefined, { numeric: true, sensitivity: "base" });
-	}
-	if (pa.major !== pb.major) return pa.major - pb.major;
-	if (pa.minor !== pb.minor) return pa.minor - pb.minor;
-	if (pa.patch !== pb.patch) return pa.patch - pb.patch;
-	if (pa.prerelease && !pb.prerelease) return -1;
-	if (!pa.prerelease && pb.prerelease) return 1;
-	if (!pa.prerelease && !pb.prerelease) return 0;
-	return (pa.prerelease ?? "").localeCompare(pb.prerelease ?? "", undefined, {
-		numeric: true,
-		sensitivity: "base",
-	});
-}
-
-function isVersionBehind(installedVersion: string, latestVersion: string): boolean {
-	return compareSemverLoose(installedVersion, latestVersion) < 0;
-}
-
-async function fetchLatestNpmVersion(packageName: string, timeoutMs = UPDATE_CHECK_TIMEOUT_MS): Promise<string | null> {
-	const pkg = String(packageName || "").trim();
-	if (!pkg) return null;
-	const encodedPackage = encodeURIComponent(pkg).replace(/^%40/, "@");
-	const endpoint = `https://registry.npmjs.org/${encodedPackage}/latest`;
-	const controller = typeof AbortController === "function" ? new AbortController() : null;
-	const timer = controller
-		? setTimeout(() => {
-			try {
-				controller.abort();
-			} catch {
-				// ignore abort race
-			}
-		}, timeoutMs)
-		: null;
-
-	try {
-		const response = await fetch(endpoint, {
-			method: "GET",
-			headers: { Accept: "application/json" },
-			signal: controller?.signal,
-		});
-		if (!response.ok) return null;
-		const payload = await response.json() as { version?: unknown };
-		const version = typeof payload.version === "string" ? payload.version.trim() : "";
-		return version || null;
-	} catch {
-		return null;
-	} finally {
-		if (timer) clearTimeout(timer);
-	}
-}
-
 function isLikelyMathExpression(expr: string): boolean {
 	const content = expr.trim();
 	if (content.length === 0) return false;
@@ -4566,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");
@@ -4573,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,
@@ -4855,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);
 
@@ -4883,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 };
@@ -5842,6 +5764,17 @@ function buildStudioUrl(
 	return `http://127.0.0.1:${port}/?${params.toString()}`;
 }
 
+function isSshSession(): boolean {
+	return Boolean(
+		String(process.env.SSH_CONNECTION ?? process.env.SSH_CLIENT ?? process.env.SSH_TTY ?? "").trim(),
+	);
+}
+
+function buildStudioSshTunnelHint(port: number): string | null {
+	if (!isSshSession()) return null;
+	return `SSH detected. If Studio is running on a remote machine, forward the port from your local machine, then open the Studio URL locally: ssh -L ${port}:127.0.0.1:${port} <remote-host>`;
+}
+
 function resolveRequestedStudioDocumentFromUrl(
 	requestUrl: URL,
 	fallback: InitialStudioDocument | null,
@@ -6382,11 +6315,6 @@ export default function (pi: ExtensionAPI) {
 	};
 	let compactInProgress = false;
 	let compactRequestId: string | null = null;
-	let updateCheckStarted = false;
-	let updateCheckCompleted = false;
-	const packageMetadata = readLocalPackageMetadata();
-	const installedPackageVersion = packageMetadata?.version ?? null;
-	let updateAvailableLatestVersion: string | null = null;
 
 	const isStudioDirectRunChainActive = () => Boolean(studioDirectRunChain);
 	const getQueuedStudioSteeringCount = () => queuedStudioDirectRequests.length;
@@ -6766,28 +6694,6 @@ export default function (pi: ExtensionAPI) {
 		});
 	};
 
-	const maybeNotifyUpdateAvailable = async (ctx: ExtensionCommandContext) => {
-		if (updateCheckStarted || updateCheckCompleted) return;
-		updateCheckStarted = true;
-		try {
-			const metadata = packageMetadata;
-			if (!metadata) return;
-			const latest = await fetchLatestNpmVersion(metadata.name, UPDATE_CHECK_TIMEOUT_MS);
-			if (!latest) return;
-			if (!isVersionBehind(metadata.version, latest)) return;
-
-			updateAvailableLatestVersion = latest;
-			broadcastState();
-
-			const notification =
-				`Update available for ${metadata.name}: ${metadata.version} → ${latest}. Run: pi install npm:${metadata.name}`;
-			ctx.ui.notify(notification, "info");
-			broadcast({ type: "info", message: notification, level: "info" });
-		} finally {
-			updateCheckCompleted = true;
-		}
-	};
-
 	const sendToClient = (client: WebSocket, payload: unknown) => {
 		if (client.readyState !== WebSocket.OPEN) return;
 		try {
@@ -7067,8 +6973,6 @@ export default function (pi: ExtensionAPI) {
 			contextTokens: contextUsageSnapshot.tokens,
 			contextWindow: contextUsageSnapshot.contextWindow,
 			contextPercent: contextUsageSnapshot.percent,
-			updateInstalledVersion: installedPackageVersion,
-			updateLatestVersion: updateAvailableLatestVersion,
 			compactInProgress,
 			activeRequestId: activeRequest?.id ?? compactRequestId ?? null,
 			activeRequestKind: activeRequest?.kind ?? (compactInProgress ? "compact" : null),
@@ -7349,8 +7253,6 @@ export default function (pi: ExtensionAPI) {
 				contextTokens: contextUsageSnapshot.tokens,
 				contextWindow: contextUsageSnapshot.contextWindow,
 				contextPercent: contextUsageSnapshot.percent,
-				updateInstalledVersion: installedPackageVersion,
-				updateLatestVersion: updateAvailableLatestVersion,
 				compactInProgress,
 				activeRequestId: activeRequest?.id ?? compactRequestId ?? null,
 				activeRequestKind: activeRequest?.kind ?? (compactInProgress ? "compact" : null),
@@ -9018,6 +8920,8 @@ export default function (pi: ExtensionAPI) {
 				ctx.ui.notify("A full pi Studio view is already open for this session. Close it first, use /studio-replace for a fresh full Studio view, or use /studio-editor-only for a concurrent editor-only Studio view.", "warning");
 				if (serverState) {
 					ctx.ui.notify(`Studio URL: ${buildStudioUrl(serverState.port, serverState.token, "full")}`, "info");
+					const sshTunnelHint = buildStudioSshTunnelHint(serverState.port);
+					if (sshTunnelHint) ctx.ui.notify(sshTunnelHint, "info");
 				}
 				return;
 			}
@@ -9043,6 +8947,7 @@ export default function (pi: ExtensionAPI) {
 
 		const state = await ensureServer();
 		const url = buildStudioUrl(state.port, state.token, mode, selected);
+		const sshTunnelHint = buildStudioSshTunnelHint(state.port);
 		const openedLabel = mode === "editor-only" ? "pi Studio editor-only view" : "pi Studio";
 
 		try {
@@ -9054,11 +8959,16 @@ export default function (pi: ExtensionAPI) {
 			} else {
 				ctx.ui.notify(`Opened ${openedLabel} with blank editor.`, "info");
 			}
-			ctx.ui.notify(`Studio URL: ${url}`, "info");
 		} catch (error) {
-			ctx.ui.notify(`Failed to open browser: ${error instanceof Error ? error.message : String(error)}`, "error");
+			const message = error instanceof Error ? error.message : String(error);
+			if (isSshSession()) {
+				ctx.ui.notify(`Failed to open browser automatically over SSH: ${message}`, "warning");
+			} else {
+				ctx.ui.notify(`Failed to open browser: ${message}`, "error");
+			}
 		} finally {
-			void maybeNotifyUpdateAvailable(ctx);
+			ctx.ui.notify(`Studio URL: ${url}`, "info");
+			if (sshTunnelHint) ctx.ui.notify(sshTunnelHint, "info");
 		}
 	};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.5.55",
+  "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"),
+  };
+}