@marimo-team/islands 0.20.2 → 0.20.3-dev76

package/src/core/codemirror/lsp/normalize-markdown-math.ts

@@ -0,0 +1,381 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as LSP from "vscode-languageserver-protocol";
+
+// Matches inline RST math role: :math:`...`
+const INLINE_MATH_ROLE_REGEX = /(?<!`):math:`([^\n`]+)`/g;
+// Matches role variant with HTML code tag: :math:<code>...</code>
+const INLINE_MATH_ROLE_CODE_REGEX = /:math:\s*<code>(.+?)<\/code>/gs;
+// Matches display bracket delimiters: \[...\]
+const DISPLAY_BRACKET_REGEX = /\\\[(.+?)\\]/gs;
+// Matches inline paren delimiters: \(...\)
+const INLINE_PAREN_REGEX = /\\\((.+?)\\\)/gs;
+// Matches display dollar delimiters: $$...$$
+const DISPLAY_DOLLAR_REGEX = /(?<!\\)\$\$(.+?)(?<!\\)\$\$/gs;
+// Matches inline dollar delimiters: $...$
+const INLINE_DOLLAR_REGEX = /(?<![$\\])\$(?!\$)([^\n$]+?)(?<!\\)\$(?!\$)/g;
+
+interface FencedSegment {
+  text: string;
+  isFenced: boolean;
+}
+
+interface InlineCodeSegment {
+  text: string;
+  isInlineCode: boolean;
+}
+
+/**
+ * Normalize supported math syntaxes inside markdown payloads used by LSP.
+ *
+ * The output stays markdown/HTML-compatible for the tooltip renderer while
+ * skipping fenced and inline code so examples remain literal.
+ */
+export function normalizeMarkdownMath(markdown: string): string {
+  if (!containsMathSyntax(markdown)) {
+    return markdown;
+  }
+
+  return splitByFencedCodeBlocks(markdown)
+    .map((segment) => {
+      if (segment.isFenced) {
+        return segment.text;
+      }
+
+      const withMathRolesNormalized = segment.text
+        .replaceAll(INLINE_MATH_ROLE_REGEX, (_, math) => inlineMath(math))
+        .replaceAll(INLINE_MATH_ROLE_CODE_REGEX, (_, math) => inlineMath(math));
+
+      return splitByInlineCodeSegments(withMathRolesNormalized)
+        .map((inlineSegment) => {
+          if (inlineSegment.isInlineCode) {
+            return inlineSegment.text;
+          }
+          return normalizePlainTextMath(inlineSegment.text);
+        })
+        .join("");
+    })
+    .join("");
+}
+
+/**
+ * Apply markdown math normalization across the LSP documentation union.
+ *
+ * For plaintext payloads, this only upcasts to markdown when math syntax is
+ * detected, so non-math plaintext keeps its previous behavior.
+ */
+export function normalizeLspDocumentation(
+  documentation:
+    | LSP.MarkupContent
+    | LSP.MarkedString
+    | LSP.MarkedString[]
+    | undefined,
+): LSP.MarkupContent | LSP.MarkedString | LSP.MarkedString[] | undefined {
+  if (documentation == null) {
+    return documentation;
+  }
+
+  if (Array.isArray(documentation)) {
+    return documentation.map((item) => normalizeLspMarkedString(item));
+  }
+
+  if (typeof documentation === "string") {
+    return normalizeMarkdownMath(documentation);
+  }
+
+  if (isMarkupContent(documentation)) {
+    if (documentation.kind === "markdown") {
+      return {
+        ...documentation,
+        value: normalizeMarkdownMath(documentation.value),
+      };
+    }
+
+    if (!containsMathSyntax(documentation.value)) {
+      return documentation;
+    }
+
+    return {
+      kind: "markdown",
+      value: normalizeMarkdownMath(documentation.value),
+    };
+  }
+
+  return normalizeLspMarkedString(documentation);
+}
+
+function normalizeLspMarkedString(marked: LSP.MarkedString): LSP.MarkedString {
+  if (typeof marked === "string") {
+    return normalizeMarkdownMath(marked);
+  }
+  if (marked.language !== "markdown" && marked.language !== "md") {
+    return marked;
+  }
+  return {
+    ...marked,
+    value: normalizeMarkdownMath(marked.value),
+  };
+}
+
+function isMarkupContent(
+  documentation: LSP.MarkupContent | LSP.MarkedString,
+): documentation is LSP.MarkupContent {
+  return (
+    typeof documentation === "object" &&
+    "kind" in documentation &&
+    "value" in documentation
+  );
+}
+
+function containsMathSyntax(markdown: string): boolean {
+  return (
+    markdown.includes(".. math::") ||
+    markdown.includes(":math:`") ||
+    // Detects display bracket delimiters.
+    /\\\[[\S\s]+?\\]/.test(markdown) ||
+    // Detects inline paren delimiters.
+    /\\\([\S\s]+?\\\)/.test(markdown) ||
+    // Detects display dollar delimiters.
+    /(?<!\\)\$\$[\S\s]+?(?<!\\)\$\$/.test(markdown) ||
+    // Detects inline dollar delimiters.
+    /(?<![$\\])\$(?!\$)[^\n$]+?(?<!\\)\$(?!\$)/.test(markdown) ||
+    // Detects HTML code-tag RST role variant.
+    /:math:\s*<code>[\S\s]+?<\/code>/.test(markdown)
+  );
+}
+
+function splitByFencedCodeBlocks(markdown: string): FencedSegment[] {
+  // Preserve fenced code blocks as literal text during normalization.
+  const lines = markdown.split("\n");
+  const segments: FencedSegment[] = [];
+  let current: string[] = [];
+  let inFence = false;
+  let fenceChar = "";
+  let fenceLength = 0;
+
+  const flush = (isFenced: boolean) => {
+    if (current.length === 0) {
+      return;
+    }
+    segments.push({ text: current.join("\n"), isFenced });
+    current = [];
+  };
+
+  for (const line of lines) {
+    // Matches fenced-code fence markers: ``` or ~~~ (>= 3 chars).
+    const markerMatch = line.match(/^[\t ]*(`{3,}|~{3,})/);
+    if (markerMatch) {
+      const marker = markerMatch[1];
+      const markerChar = marker[0];
+      const markerLength = marker.length;
+
+      if (!inFence) {
+        flush(false);
+        inFence = true;
+        fenceChar = markerChar;
+        fenceLength = markerLength;
+        current.push(line);
+        continue;
+      }
+
+      if (markerChar === fenceChar && markerLength >= fenceLength) {
+        current.push(line);
+        flush(true);
+        inFence = false;
+        fenceChar = "";
+        fenceLength = 0;
+        continue;
+      }
+    }
+
+    current.push(line);
+  }
+
+  flush(inFence);
+  return segments;
+}
+
+function splitByInlineCodeSegments(text: string): InlineCodeSegment[] {
+  // Preserve inline code spans (single or multi-backtick delimiters).
+  const segments: InlineCodeSegment[] = [];
+  let current = "";
+  let inInlineCode = false;
+  let delimiter = "";
+  let i = 0;
+
+  while (i < text.length) {
+    if (text[i] === "`") {
+      let j = i;
+      while (j < text.length && text[j] === "`") {
+        j += 1;
+      }
+      const ticks = text.slice(i, j);
+
+      if (inInlineCode && ticks === delimiter) {
+        current += ticks;
+        segments.push({ text: current, isInlineCode: true });
+        current = "";
+        inInlineCode = false;
+        delimiter = "";
+        i = j;
+        continue;
+      }
+
+      if (!inInlineCode) {
+        if (current) {
+          segments.push({ text: current, isInlineCode: false });
+          current = "";
+        }
+        inInlineCode = true;
+        delimiter = ticks;
+        current += ticks;
+        i = j;
+        continue;
+      }
+    }
+
+    current += text[i];
+    i += 1;
+  }
+
+  if (current) {
+    segments.push({ text: current, isInlineCode: inInlineCode });
+  }
+
+  return segments;
+}
+
+function normalizePlainTextMath(text: string): string {
+  // Convert alternate math syntaxes into marimo-tex HTML wrappers.
+  let converted = convertRstMathBlocks(text);
+  converted = converted.replaceAll(DISPLAY_BRACKET_REGEX, (_, math) =>
+    displayMath(math),
+  );
+  converted = converted.replaceAll(INLINE_PAREN_REGEX, (_, math) =>
+    inlineMath(math),
+  );
+  converted = converted.replaceAll(DISPLAY_DOLLAR_REGEX, (_, math) =>
+    displayMath(math),
+  );
+  converted = converted.replaceAll(INLINE_DOLLAR_REGEX, (_, math) =>
+    inlineMath(math),
+  );
+  return converted;
+}
+
+function countIndent(line: string): number {
+  // Matches leading whitespace used to compute visual indentation.
+  return line.match(/^[\t ]*/)?.[0].replaceAll("\t", "    ").length ?? 0;
+}
+
+function convertRstMathBlocks(text: string): string {
+  // Convert ``.. math::`` directive bodies to display math wrappers.
+  const lines = text.split("\n");
+  if (lines.length === 0) {
+    return text;
+  }
+
+  const output: string[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    // Matches RST math directive lines: ".. math:: ..."
+    const directiveMatch = line.match(/^[\t ]*\.\.\s+math::(.*)$/);
+    if (!directiveMatch) {
+      output.push(line);
+      i += 1;
+      continue;
+    }
+
+    const inlineMath = directiveMatch[1]?.trim() ?? "";
+    const baseIndent = countIndent(line);
+    i += 1;
+
+    const mathLines: string[] = [];
+    let consumeUnindentedBlock = inlineMath.includes("\\begin");
+    if (inlineMath) {
+      mathLines.push(inlineMath);
+    } else {
+      while (i < lines.length) {
+        const currentLine = lines[i];
+        if (!currentLine.trim()) {
+          i += 1;
+          continue;
+        }
+
+        const isOptionLine =
+          countIndent(currentLine) > baseIndent &&
+          currentLine.trim().startsWith(":");
+        if (!isOptionLine) {
+          break;
+        }
+        i += 1;
+      }
+
+      if (i < lines.length) {
+        const nextLine = lines[i];
+        consumeUnindentedBlock =
+          Boolean(nextLine.trim()) &&
+          countIndent(nextLine) <= baseIndent &&
+          nextLine.trimStart().startsWith("\\");
+      }
+    }
+
+    if (consumeUnindentedBlock) {
+      while (i < lines.length && lines[i].trim()) {
+        mathLines.push(lines[i]);
+        i += 1;
+      }
+    } else {
+      while (i < lines.length) {
+        const currentLine = lines[i];
+        if (!currentLine.trim()) {
+          mathLines.push("");
+          i += 1;
+          continue;
+        }
+
+        if (countIndent(currentLine) <= baseIndent) {
+          break;
+        }
+
+        mathLines.push(currentLine);
+        i += 1;
+      }
+    }
+
+    const nonEmptyMathLines = mathLines.filter((mathLine) =>
+      Boolean(mathLine.trim()),
+    );
+    if (nonEmptyMathLines.length === 0) {
+      output.push(line);
+      continue;
+    }
+
+    const minIndent = Math.min(
+      ...nonEmptyMathLines.map((mathLine) => countIndent(mathLine)),
+    );
+    const normalizedMath = mathLines
+      .map((mathLine) => {
+        if (!mathLine) {
+          return "";
+        }
+        const stripCount = Math.min(minIndent, countIndent(mathLine));
+        return mathLine.slice(stripCount);
+      })
+      .join("\n")
+      .trim();
+
+    output.push(displayMath(normalizedMath));
+  }
+
+  return output.join("\n");
+}
+
+function inlineMath(math: string): string {
+  return `<marimo-tex class="arithmatex">||(${math.trim()}||)</marimo-tex>`;
+}
+
+function displayMath(math: string): string {
+  return `<marimo-tex class="arithmatex">||[${math.trim()}||]</marimo-tex>`;
+}

package/src/core/codemirror/lsp/notebook-lsp.ts

@@ -16,6 +16,7 @@ import {
   updateEditorCodeFromPython,
 } from "../language/utils";
 import { createNotebookLens, type NotebookLens } from "./lens";
+import { normalizeLspDocumentation } from "./normalize-markdown-math";
 import {
   CellDocumentUri,
   type ILanguageServerClient,
@@ -89,6 +90,56 @@ const defaultGetNotebookEditors = () => {
   return Objects.mapValues(evs, (r) => r.current?.editorViewOrNull);
 };
 
+function normalizeTextDocumentation(
+  documentation: string | LSP.MarkupContent | undefined,
+): string | LSP.MarkupContent | undefined {
+  const normalized = normalizeLspDocumentation(
+    documentation as LSP.MarkupContent | LSP.MarkedString | undefined,
+  );
+  if (Array.isArray(normalized)) {
+    return documentation;
+  }
+  return normalized as string | LSP.MarkupContent | undefined;
+}
+
+function normalizeCompletionItem(item: LSP.CompletionItem): LSP.CompletionItem {
+  return {
+    ...item,
+    documentation: normalizeTextDocumentation(item.documentation),
+  };
+}
+
+function normalizeCompletionResponse(
+  response: LSP.CompletionList | LSP.CompletionItem[] | null,
+): LSP.CompletionList | LSP.CompletionItem[] | null {
+  if (response == null) {
+    return null;
+  }
+  if (Array.isArray(response)) {
+    return response.map((item) => normalizeCompletionItem(item));
+  }
+  return {
+    ...response,
+    items: response.items.map((item) => normalizeCompletionItem(item)),
+  };
+}
+
+function normalizeSignatureHelpResponse(
+  response: LSP.SignatureHelp,
+): LSP.SignatureHelp {
+  return {
+    ...response,
+    signatures: response.signatures.map((signature) => ({
+      ...signature,
+      documentation: normalizeTextDocumentation(signature.documentation),
+      parameters: signature.parameters?.map((parameter) => ({
+        ...parameter,
+        documentation: normalizeTextDocumentation(parameter.documentation),
+      })),
+    })),
+  };
+}
+
 export class NotebookLanguageServerClient implements ILanguageServerClient {
   public readonly documentUri: LSP.DocumentUri;
   private readonly client: ILanguageServerClient;
@@ -372,7 +423,7 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
       return null;
     }
 
-    return response;
+    return normalizeSignatureHelpResponse(response);
   }
 
   /**
@@ -569,7 +620,9 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
       return cached;
     }
 
-    const resolved = this.client.completionItemResolve(params);
+    const resolved = this.client
+      .completionItemResolve(params)
+      .then((item) => normalizeCompletionItem(item));
     this.completionItemCache.set(key, resolved);
     return resolved;
   }
@@ -626,6 +679,8 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
         value: hover.contents.value,
       };
     }
+    hover.contents =
+      normalizeLspDocumentation(hover.contents) ?? hover.contents;
 
     // Empty
     if (hover.contents === "") {
@@ -679,13 +734,14 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
 
     const transformedPosition = lens.transformPosition(params.position, cellId);
 
-    return this.client.textDocumentCompletion({
+    const response = await this.client.textDocumentCompletion({
       ...params,
       textDocument: {
         uri: this.documentUri,
       },
       position: transformedPosition,
     });
+    return normalizeCompletionResponse(response);
   }
 
   /**

package/src/core/config/feature-flag.tsx

@@ -12,6 +12,7 @@ export interface ExperimentalFeatures {
   cache_panel: boolean;
   external_agents: boolean;
   server_side_pdf_export: boolean;
+  storage_inspector: boolean;
   // Add new feature flags here
 }
 
@@ -22,6 +23,7 @@ const defaultValues: ExperimentalFeatures = {
   cache_panel: false,
   external_agents: import.meta.env.DEV,
   server_side_pdf_export: true,
+  storage_inspector: false,
 };
 
 export function getFeatureFlag<T extends keyof ExperimentalFeatures>(

package/src/core/dom/__tests__/outline.test.ts

@@ -39,6 +39,7 @@ describe("parseOutline", () => {
             "by": {
               "id": "what-is-marimo",
             },
+            "html": "What is <b>marimo</b>?",
             "level": 2,
             "name": "What is marimo?",
           },
@@ -310,6 +311,50 @@ describe("parseOutline", () => {
     `);
   });
 
+  it("preserves LaTeX HTML in headings", () => {
+    const html = `
+    <span class="markdown">
+      <h1 id="intro">Introduction</h1>
+      <h2 id="the-equation">The equation <marimo-tex class="arithmatex">||(E = mc^2||)</marimo-tex></h2>
+      <h2 id="plain">Plain heading</h2>
+    </span>
+    `;
+    const outline = parseOutline({
+      mimetype: "text/html",
+      timestamp: 0,
+      channel: "output",
+      data: html,
+    });
+    expect(outline).toMatchInlineSnapshot(`
+      {
+        "items": [
+          {
+            "by": {
+              "id": "intro",
+            },
+            "level": 1,
+            "name": "Introduction",
+          },
+          {
+            "by": {
+              "id": "the-equation",
+            },
+            "html": "The equation <marimo-tex class="arithmatex">||(E = mc^2||)</marimo-tex>",
+            "level": 2,
+            "name": "The equation ||(E = mc^2||)",
+          },
+          {
+            "by": {
+              "id": "plain",
+            },
+            "level": 2,
+            "name": "Plain heading",
+          },
+        ],
+      }
+    `);
+  });
+
   it("excludes headings within excluded tags", () => {
     const html = `
     <div>
@@ -323,6 +368,9 @@ describe("parseOutline", () => {
       <marimo-accordion>
         <h2 id="excluded-heading-accordion">Excluded Heading in Accordion</h2>
       </marimo-accordion>
+      <marimo-sidebar>
+        <h2 id="excluded-heading-sidebar">Excluded Heading in Sidebar</h2>
+      </marimo-sidebar>
       <h2 id="another-included-heading">Another Included Heading</h2>
     </div>
     `;

package/src/core/dom/outline.ts

@@ -1,12 +1,18 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import { sanitizeHtml } from "@/plugins/core/sanitize";
 import { invariant } from "@/utils/invariant";
 import { Logger } from "@/utils/Logger";
 import type { Outline, OutlineItem } from "../cells/outline";
 import type { OutputMessage } from "../kernel/messages";
 
 // Tags that we don't want to include in the outline
-const excludedTags = ["marimo-carousel", "marimo-tabs", "marimo-accordion"];
+const excludedTags = [
+  "marimo-carousel",
+  "marimo-tabs",
+  "marimo-accordion",
+  "marimo-sidebar",
+];
 
 // We go up to h6. Previously we did h3 to match Google Docs and Notion, but users have requested more levels.
 // This could be made configurable in the future.
@@ -46,7 +52,12 @@ function getOutline(html: string): Outline | null {
     }
 
     const level = Number.parseInt(heading.tagName[1], 10);
-    items.push({ name, level, by: headingToIdentifier(heading) });
+    const innerHTML = heading.innerHTML;
+    const item: OutlineItem = { name, level, by: headingToIdentifier(heading) };
+    if (innerHTML !== name) {
+      item.html = sanitizeHtml(innerHTML);
+    }
+    items.push(item);
   }
 
   return { items };

package/src/core/islands/bridge.ts

@@ -200,6 +200,8 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {
   invokeAiTool = throwNotImplemented;
   clearCache = throwNotImplemented;
   getCacheInfo = throwNotImplemented;
+  listStorageEntries = throwNotImplemented;
+  downloadStorage = throwNotImplemented;
 
   // The kernel uses msgspec to parse control requests, which requires a 'type'
   // field for discriminated union deserialization.

package/src/core/islands/main.ts

@@ -127,6 +127,8 @@ export async function initialize() {
       case "data-source-connections":
       case "validate-sql-result":
       case "storage-namespaces":
+      case "storage-entries":
+      case "storage-download-ready":
       case "secret-keys-result":
       case "startup-logs":
         // Unsupported

package/src/core/network/requests-lazy.ts

@@ -113,6 +113,8 @@ const ACTIONS: Record<keyof AllRequests, Action> = {
   previewSQLTableList: "waitForConnectionOpen",
   previewDataSourceConnection: "waitForConnectionOpen",
   validateSQL: "waitForConnectionOpen",
+  listStorageEntries: "waitForConnectionOpen",
+  downloadStorage: "waitForConnectionOpen",
 
   // Sync operations that wait for connection
   syncCellIds: "waitForConnectionOpen",

package/src/core/network/requests-network.ts

@@ -488,5 +488,21 @@ export function createNetworkRequests(): EditRequests & RunRequests {
         })
         .then(handleResponseReturnNull);
     },
+    listStorageEntries: (request) => {
+      return getClient()
+        .POST("/api/storage/list_entries", {
+          body: request,
+          params: getParams(),
+        })
+        .then(handleResponseReturnNull);
+    },
+    downloadStorage: (request) => {
+      return getClient()
+        .POST("/api/storage/download", {
+          body: request,
+          params: getParams(),
+        })
+        .then(handleResponseReturnNull);
+    },
   };
 }

package/src/core/network/requests-static.ts

@@ -90,5 +90,7 @@ export function createStaticRequests(): EditRequests & RunRequests {
     invokeAiTool: throwNotInEditMode,
     clearCache: throwNotInEditMode,
     getCacheInfo: throwNotInEditMode,
+    listStorageEntries: throwNotInEditMode,
+    downloadStorage: throwNotInEditMode,
   };
 }

package/src/core/network/requests-toasting.tsx

@@ -75,6 +75,8 @@ export function createErrorToastingRequests(
     invokeAiTool: "Failed to invoke AI tool",
     clearCache: "Failed to clear cache",
     getCacheInfo: "", // No toast
+    listStorageEntries: "Failed to list storage entries",
+    downloadStorage: "Failed to download storage entry",
   };
 
   const handlers = {} as EditRequests & RunRequests;

package/src/core/network/types.ts

@@ -105,6 +105,9 @@ export type LspRestartRequest = schemas["LspRestartRequest"];
 export type LspRestartResponse = schemas["LspRestartResponse"];
 export type LspServerHealth = schemas["LspServerHealth"];
 
+export type StorageListEntriesRequest = schemas["StorageListEntriesRequest"];
+export type StorageDownloadRequest = schemas["StorageDownloadRequest"];
+
 /**
  * Requests sent to the BE during run/edit mode.
  */
@@ -198,6 +201,9 @@ export interface EditRequests {
   // Cache requests
   clearCache: () => Promise<null>;
   getCacheInfo: () => Promise<null>;
+  // Storage requests
+  listStorageEntries: (request: StorageListEntriesRequest) => Promise<null>;
+  downloadStorage: (request: StorageDownloadRequest) => Promise<null>;
 }
 
 export type RequestKey = keyof (EditRequests & RunRequests);