@marimo-team/islands 0.23.16-dev6 → 0.23.16-dev62

package/src/components/editor/actions/__tests__/pair-with-agent-commands.test.ts

@@ -3,6 +3,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   type ConnectionInfo,
+  getFileFromURL,
   getMarimoCommand,
   getRawPrompt,
   getTerminalCommand,
@@ -12,7 +13,11 @@ import {
 
 const CONNECTION: ConnectionInfo = {
   url: "http://localhost:8000",
-  sessionId: "s_ab12cd",
+  file: "notebooks/example.py",
+};
+
+const CONNECTION_WITHOUT_FILE: ConnectionInfo = {
+  url: "http://localhost:8000",
 };
 
 describe("shellQuote", () => {
@@ -22,7 +27,7 @@ describe("shellQuote", () => {
 
   it("leaves shell-safe values untouched", () => {
     expect(shellQuote("http://localhost:8000")).toBe("http://localhost:8000");
-    expect(shellQuote("s_ab12cd")).toBe("s_ab12cd");
+    expect(shellQuote("notebooks/example.py")).toBe("notebooks/example.py");
   });
 
   it("quotes values with shell metacharacters", () => {
@@ -37,6 +42,49 @@ describe("shellQuote", () => {
     // Closes the quote, emits a literal ' via "'", then reopens: '"'"'
     expect(shellQuote("a'b")).toBe(`'a'"'"'b'`);
   });
+
+  it.each([
+    ["/tmp/my notebook.py", "'/tmp/my notebook.py'"],
+    [
+      String.raw`C:\Users\Jane Doe\notebook.py`,
+      String.raw`'C:\Users\Jane Doe\notebook.py'`,
+    ],
+    [
+      String.raw`\\server\share\my notebook.py`,
+      String.raw`'\\server\share\my notebook.py'`,
+    ],
+  ])("quotes non-portable path %s as one argument", (path, expected) => {
+    expect(shellQuote(path)).toBe(expected);
+  });
+});
+
+describe("getFileFromURL", () => {
+  it("returns undefined when the file query parameter is absent or empty", () => {
+    expect(getFileFromURL("http://localhost:8000")).toBeUndefined();
+    expect(getFileFromURL("http://localhost:8000?file=")).toBeUndefined();
+  });
+
+  it("decodes spaces and literal plus signs", () => {
+    expect(
+      getFileFromURL(
+        "http://localhost:8000?file=relative%2Fmy%20notebook%2Bdata.py",
+      ),
+    ).toBe("relative/my notebook+data.py");
+    expect(getFileFromURL("http://localhost:8000?file=my+notebook.py")).toBe(
+      "my notebook.py",
+    );
+  });
+
+  it("preserves decoded Windows paths and uses the first duplicate value", () => {
+    expect(
+      getFileFromURL(
+        "http://localhost:8000?file=C%3A%5CUsers%5CJane%20Doe%5Cnotebook.py",
+      ),
+    ).toBe(String.raw`C:\Users\Jane Doe\notebook.py`);
+    expect(
+      getFileFromURL("http://localhost:8000?file=first.py&file=second.py"),
+    ).toBe("first.py");
+  });
 });
 
 describe("getMarimoCommand", () => {
@@ -56,30 +104,56 @@ describe("getMarimoCommand", () => {
 });
 
 describe("getTerminalCommand", () => {
-  it("includes the url and session for each agent", () => {
+  it("includes the url and file for each agent", () => {
     expect(getTerminalCommand("claude", CONNECTION, false)).toBe(
-      `claude "$(uv run marimo pair prompt --url http://localhost:8000 --session s_ab12cd --claude)"`,
+      `claude "$(uv run marimo pair prompt --url http://localhost:8000 --file notebooks/example.py --claude)"`,
     );
     expect(getTerminalCommand("codex", CONNECTION, false)).toBe(
-      `codex "$(uv run marimo pair prompt --url http://localhost:8000 --session s_ab12cd --codex)"`,
+      `codex "$(uv run marimo pair prompt --url http://localhost:8000 --file notebooks/example.py --codex)"`,
     );
     expect(getTerminalCommand("opencode", CONNECTION, false)).toBe(
-      `opencode --prompt "$(uv run marimo pair prompt --url http://localhost:8000 --session s_ab12cd --opencode)"`,
+      `opencode --prompt "$(uv run marimo pair prompt --url http://localhost:8000 --file notebooks/example.py --opencode)"`,
     );
   });
 
-  it("always targets the given session, not a random one", () => {
-    const command = getTerminalCommand("claude", CONNECTION, false);
-    expect(command).toContain("--session s_ab12cd");
+  it("omits the file flag when the page URL has no file", () => {
+    const command = getTerminalCommand(
+      "claude",
+      CONNECTION_WITHOUT_FILE,
+      false,
+    );
+    expect(command).not.toContain("--file");
+    expect(command).not.toContain("--session");
   });
 
   it("shell-escapes a url containing metacharacters", () => {
     const command = getTerminalCommand(
       "claude",
-      { url: "http://host:8000?file=a&b", sessionId: "s_ab12cd" },
+      { url: "http://host:8000?auth=a&b", file: "notebook.py" },
       false,
     );
-    expect(command).toContain("--url 'http://host:8000?file=a&b'");
+    expect(command).toContain("--url 'http://host:8000?auth=a&b'");
+  });
+
+  it.each([
+    ["relative/my notebook.py", "--file 'relative/my notebook.py'"],
+    ["/tmp/my notebook.py", "--file '/tmp/my notebook.py'"],
+    [
+      String.raw`C:\Users\Jane Doe\notebook.py`,
+      String.raw`--file 'C:\Users\Jane Doe\notebook.py'`,
+    ],
+    [
+      String.raw`\\server\share\my notebook.py`,
+      String.raw`--file '\\server\share\my notebook.py'`,
+    ],
+    ["notebooks/it's.py", `--file 'notebooks/it'"'"'s.py'`],
+  ])("shell-escapes file path %s", (file, expected) => {
+    const command = getTerminalCommand(
+      "claude",
+      { url: CONNECTION.url, file },
+      false,
+    );
+    expect(command).toContain(expected);
   });
 
   it("adds --with-token before the agent flag when requested", () => {
@@ -95,26 +169,33 @@ describe("getTerminalCommand", () => {
 });
 
 describe("getRawPrompt", () => {
-  it("references the session-scoped execute-code command", () => {
+  it("references the file-scoped execute-code command", () => {
     const prompt = getRawPrompt(CONNECTION, null);
     expect(prompt).toContain(
-      "execute-code.sh --url http://localhost:8000 --session s_ab12cd",
+      "execute-code.sh --url http://localhost:8000 --file notebooks/example.py",
     );
     expect(prompt).toContain(
-      "Connect to the notebook at: http://localhost:8000 (session s_ab12cd)",
+      "Connect to the notebook at: http://localhost:8000 (file notebooks/example.py)",
     );
   });
 
+  it("omits file targeting when the page URL has no file", () => {
+    const prompt = getRawPrompt(CONNECTION_WITHOUT_FILE, null);
+    expect(prompt).toContain("execute-code.sh --url http://localhost:8000");
+    expect(prompt).not.toContain("--file");
+    expect(prompt).not.toContain("--session");
+  });
+
   it("omits the token hint when there is no token", () => {
     const prompt = getRawPrompt(CONNECTION, null);
     expect(prompt).not.toContain("--token");
     expect(prompt).not.toContain("auth token");
   });
 
-  it("includes a session-scoped token hint when a token is present", () => {
+  it("includes a file-scoped token hint when a token is present", () => {
     const prompt = getRawPrompt(CONNECTION, "secret-token");
     expect(prompt).toContain(
-      "execute-code.sh --url http://localhost:8000 --session s_ab12cd --token secret-token",
+      "execute-code.sh --url http://localhost:8000 --file notebooks/example.py --token secret-token",
     );
   });
 
@@ -128,9 +209,9 @@ describe("getRawPrompt", () => {
     expect(prompt).toMatchInlineSnapshot(`
       "Use the /marimo-pair skill to pair-program on a running marimo notebook.
 
-      Connect to the notebook at: http://localhost:8000 (session s_ab12cd)
+      Connect to the notebook at: http://localhost:8000 (file notebooks/example.py)
 
-      Use \`execute-code.sh --url http://localhost:8000 --session s_ab12cd\` from the marimo-pair skill to execute code in the notebook.
+      Use \`execute-code.sh --url http://localhost:8000 --file notebooks/example.py\` from the marimo-pair skill to execute code in the notebook.
 
       Once you are connected, send a fun toast (mo.status.toast(...)) to the user inside marimo letting them know you're ready to pair."
     `);

package/src/components/editor/actions/__tests__/pdf-export.test.ts

@@ -4,39 +4,58 @@ import { describe, expect, it, vi } from "vitest";
 import { runServerSidePDFDownload } from "../pdf-export";
 
 describe("runServerSidePDFDownload", () => {
-  it("downloads document preset via backend PDF endpoint", async () => {
-    const downloadPDF = vi.fn().mockResolvedValue(undefined);
+  it("captures current outputs before downloading the PDF", async () => {
+    const calls: string[] = [];
+    const captureOutputs = vi.fn(async () => {
+      calls.push("capture:start");
+      await Promise.resolve();
+      calls.push("capture:end");
+    });
+    const downloadPDF = vi.fn(async () => {
+      calls.push("download");
+    });
 
     await runServerSidePDFDownload({
-      filename: "slides.py",
-      preset: "document",
+      exportOptions: {
+        webpdf: false,
+        preset: "document",
+        includeInputs: true,
+        includeOutputs: true,
+      },
+      captureOutputs,
       downloadPDF,
     });
 
+    expect(calls).toEqual(["capture:start", "capture:end", "download"]);
     expect(downloadPDF).toHaveBeenCalledWith({
-      filename: "slides.py",
       webpdf: false,
       preset: "document",
       includeInputs: true,
-      rasterServer: "static",
+      includeOutputs: true,
     });
   });
 
-  it("downloads slides preset via backend PDF endpoint", async () => {
+  it("skips browser capture when outputs are excluded", async () => {
+    const captureOutputs = vi.fn().mockResolvedValue(undefined);
     const downloadPDF = vi.fn().mockResolvedValue(undefined);
 
     await runServerSidePDFDownload({
-      filename: "slides.py",
-      preset: "slides",
+      exportOptions: {
+        webpdf: true,
+        preset: "slides",
+        includeInputs: false,
+        includeOutputs: false,
+      },
+      captureOutputs,
       downloadPDF,
     });
 
+    expect(captureOutputs).not.toHaveBeenCalled();
     expect(downloadPDF).toHaveBeenCalledWith({
-      filename: "slides.py",
-      webpdf: false,
+      webpdf: true,
       preset: "slides",
-      includeInputs: true,
-      rasterServer: "static",
+      includeInputs: false,
+      includeOutputs: false,
     });
   });
 });

package/src/components/editor/actions/pair-with-agent-commands.ts

@@ -1,6 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { assertNever } from "@/utils/assertNever";
+import { KnownQueryParams } from "@/core/constants";
 
 export type AgentTab = "claude" | "codex" | "opencode" | "prompt";
 
@@ -43,14 +44,21 @@ export function shellQuote(value: string): string {
   return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 
+/** Return the server file key from a page URL, preserving its decoded value. */
+export function getFileFromURL(href: string): string | undefined {
+  const file = new URL(href).searchParams.get(KnownQueryParams.filePath);
+  return file === null || file === "" ? undefined : file;
+}
+
+function getFileFlag(file: string | undefined): string {
+  return file ? ` --file ${shellQuote(file)}` : "";
+}
+
 /** Identifies the specific running notebook to pair on. */
 export interface ConnectionInfo {
   url: string;
-  /**
-   * The current session id, so agents connect to *this* notebook rather than
-   * guessing when multiple sessions are open on the same server.
-   */
-  sessionId: string;
+  /** The server's file key, when the page URL identifies a notebook. */
+  file?: string;
 }
 
 /**
@@ -59,11 +67,12 @@ export interface ConnectionInfo {
  */
 export function getTerminalCommand(
   agent: Exclude<AgentTab, "prompt">,
-  { url, sessionId }: ConnectionInfo,
+  { url, file }: ConnectionInfo,
   withToken: boolean,
 ): string {
+  const fileFlag = getFileFlag(file);
   const tokenFlag = withToken ? " --with-token" : "";
-  const base = `${getMarimoCommand()} pair prompt --url ${shellQuote(url)} --session ${shellQuote(sessionId)}${tokenFlag}`;
+  const base = `${getMarimoCommand()} pair prompt --url ${shellQuote(url)}${fileFlag}${tokenFlag}`;
   switch (agent) {
     case "claude":
       return `claude "$(${base} --claude)"`;
@@ -82,17 +91,19 @@ export function getTerminalCommand(
  * an agent behaves the same as the terminal commands.
  */
 export function getRawPrompt(
-  { url, sessionId }: ConnectionInfo,
+  { url, file }: ConnectionInfo,
   token: string | null,
 ): string {
-  const executeCmd = `execute-code.sh --url ${shellQuote(url)} --session ${shellQuote(sessionId)}`;
+  const fileFlag = getFileFlag(file);
+  const fileHint = file ? ` (file ${file})` : "";
+  const executeCmd = `execute-code.sh --url ${shellQuote(url)}${fileFlag}`;
   const tokenHint = token
     ? `\n\nUse this auth token when calling \`execute-code.sh\`: \`${executeCmd} --token ${shellQuote(token)}\`.`
     : "";
   return [
     "Use the /marimo-pair skill to pair-program on a running marimo notebook.",
     "",
-    `Connect to the notebook at: ${url} (session ${sessionId})`,
+    `Connect to the notebook at: ${url}${fileHint}`,
     "",
     `Use \`${executeCmd}\` from the marimo-pair skill to execute code in the notebook.${tokenHint}`,
     "",

package/src/components/editor/actions/pair-with-agent-modal.tsx

@@ -16,12 +16,12 @@ import { Events } from "@/utils/events";
 import { Tooltip } from "@/components/ui/tooltip";
 import { asRemoteURL, useRuntimeManager } from "@/core/runtime/config";
 import { API } from "@/core/network/api";
-import { getSessionId } from "@/core/kernel/session";
 import {
   AGENT_LABELS,
   AGENT_TABS,
   type AgentTab,
   type ConnectionInfo,
+  getFileFromURL,
   getRawPrompt,
   getTerminalCommand,
   maskToken,
@@ -53,7 +53,7 @@ export const PairWithAgentModal: React.FC<{
   const hasToken = Boolean(authToken);
   const connection: ConnectionInfo = {
     url: runtimeManager.httpURL.toString(),
-    sessionId: getSessionId(),
+    file: getFileFromURL(window.location.href),
   };
 
   return (

package/src/components/editor/actions/pdf-export.ts

@@ -1,26 +1,23 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 type Preset = "document" | "slides";
-type DownloadPDF = (opts: {
-  filename: string;
+interface PDFExportOptions {
   webpdf: boolean;
   preset: Preset;
   includeInputs: boolean;
-  rasterServer: "live" | "static";
-}) => Promise<void>;
+  includeOutputs: boolean;
+}
+type DownloadPDF = (opts: PDFExportOptions) => Promise<void>;
 
 export async function runServerSidePDFDownload(opts: {
-  filename: string;
-  preset: Preset;
+  exportOptions: PDFExportOptions;
+  captureOutputs: () => Promise<void>;
   downloadPDF: DownloadPDF;
 }): Promise<void> {
-  const { filename, preset, downloadPDF } = opts;
+  const { exportOptions, captureOutputs, downloadPDF } = opts;
 
-  await downloadPDF({
-    filename,
-    webpdf: false,
-    preset,
-    includeInputs: true,
-    rasterServer: "static",
-  });
+  if (exportOptions.includeOutputs) {
+    await captureOutputs();
+  }
+  await downloadPDF(exportOptions);
 }

package/src/components/editor/actions/useNotebookActions.tsx

@@ -83,6 +83,7 @@ import {
   ADD_PRINTING_CLASS,
   downloadAsPDF,
   downloadBlob,
+  downloadExportedFile,
   downloadHTMLAsImage,
   withLoadingToast,
 } from "@/utils/download";
@@ -140,6 +141,7 @@ export function useNotebookActions() {
   const {
     exportAsIPYNB,
     exportAsMarkdown,
+    exportAsScript,
     readCode,
     saveCellConfig,
     updateCellOutputs,
@@ -192,13 +194,18 @@ export function useNotebookActions() {
     }
 
     const runDownload = async (progress: ProgressState) => {
-      await updateCellOutputsWithScreenshots({
-        takeScreenshots: () => takeScreenshots({ progress }),
-        updateCellOutputs,
-      });
       await runServerSidePDFDownload({
-        filename,
-        preset,
+        exportOptions: {
+          webpdf: false,
+          preset,
+          includeInputs: true,
+          includeOutputs: true,
+        },
+        captureOutputs: () =>
+          updateCellOutputsWithScreenshots({
+            takeScreenshots: () => takeScreenshots({ progress }),
+            updateCellOutputs,
+          }),
         downloadPDF: downloadAsPDF,
       });
     };
@@ -231,11 +238,8 @@ export function useNotebookActions() {
         takeScreenshots: () => takeScreenshots({ progress }),
         updateCellOutputs,
       });
-      const ipynb = await exportAsIPYNB({ download: false });
-      downloadBlob(
-        new Blob([ipynb], { type: "application/x-ipynb+json" }),
-        Filenames.toIPYNB(document.title),
-      );
+      const exportedFile = await exportAsIPYNB({ download: false });
+      downloadExportedFile(exportedFile);
     };
 
     await withLoadingToast("Downloading IPYNB...", runDownload);
@@ -255,7 +259,7 @@ export function useNotebookActions() {
               toastNotebookMustBeNamed();
               return;
             }
-            await downloadAsHTML({ filename, includeCode: true });
+            await downloadAsHTML({ includeCode: true });
           },
         },
         {
@@ -266,7 +270,7 @@ export function useNotebookActions() {
               toastNotebookMustBeNamed();
               return;
             }
-            await downloadAsHTML({ filename, includeCode: false });
+            await downloadAsHTML({ includeCode: false });
           },
         },
         {
@@ -275,11 +279,8 @@ export function useNotebookActions() {
           ),
           label: "Download as Markdown",
           handle: async () => {
-            const md = await exportAsMarkdown({ download: false });
-            downloadBlob(
-              new Blob([md], { type: "text/plain" }),
-              Filenames.toMarkdown(document.title),
-            );
+            const exportedFile = await exportAsMarkdown({ download: false });
+            downloadExportedFile(exportedFile);
           },
         },
         {
@@ -289,7 +290,7 @@ export function useNotebookActions() {
         },
         {
           icon: <CodeIcon size={14} strokeWidth={1.5} />,
-          label: "Download Python code",
+          label: "Download notebook source",
           handle: async () => {
             const code = await readCode();
             downloadBlob(
@@ -298,6 +299,14 @@ export function useNotebookActions() {
             );
           },
         },
+        {
+          icon: <CodeIcon size={14} strokeWidth={1.5} />,
+          label: "Download flat script",
+          handle: async () => {
+            const exportedFile = await exportAsScript({ download: false });
+            downloadExportedFile(exportedFile);
+          },
+        },
         {
           divider: true,
           icon: <ImageIcon size={14} strokeWidth={1.5} />,