typst-mcp 1.1.0 → 1.3.0

package/README.md

@@ -13,42 +13,44 @@
 
 ---
 
-## Quick Start
+## Installation
 
-### Prerequisites
-
-- [**Node.js**](https://nodejs.org/) `>= 18` (for `npx` install) or [**Bun**](https://bun.sh) `>= 1.2` (for local development)
-- [**Typst CLI**](https://github.com/typst/typst) (`typst` on `PATH` for `typst_get_diagnostics` and `typst_export_pdf`)
-
-### Installation
+Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`, `claude_desktop_config.json`, or `.cursor/mcp.json`).
 
-**Recommended — no clone, no global install:**
+### Prerequisites
 
-```bash
-npx -y typst-mcp
-```
+- [**Node.js**](https://nodejs.org/) `>= 18`
+- [**Typst CLI**](https://github.com/typst/typst) (optional: `typst` on `PATH` for local CLI compilation speed; if not installed, `typst_get_diagnostics` automatically uses Typst Web cloud compiler diagnostics)
 
-Runs the published [`typst-mcp`](https://www.npmjs.com/package/typst-mcp) package (Node `>= 18`). Use the same command in MCP config below. `-y` skips the npx install prompt.
+### Option 1: Normal (Standard)
 
-**From source (development):**
+Runs the published [`typst-mcp`](https://www.npmjs.com/package/typst-mcp) package (`npx -y typst-mcp`):
 
-```bash
-git clone https://github.com/caphefalumi/typst-web-mcp.git
-cd typst-web-mcp
-bun install
-bun run dev
+```json
+{
+  "mcpServers": {
+    "typst-mcp": {
+      "command": "npx",
+      "args": ["-y", "typst-mcp"],
+      "env": {
+        "TYPST_EMAIL": "your-email@example.com",
+        "TYPST_PASSWORD": "your-password"
+      }
+    }
+  }
+}
 ```
 
-### MCP Client Configuration
+### Option 2: Always Latest
 
-Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`, `claude_desktop_config.json`, or `.cursor/mcp.json`):
+Bypasses local `npx` cache to automatically pull and run the newest release on launch (`npx -y typst-mcp@latest`):
 
 ```json
 {
   "mcpServers": {
     "typst-mcp": {
       "command": "npx",
-      "args": ["-y", "typst-mcp"],
+      "args": ["-y", "typst-mcp@latest"],
       "env": {
         "TYPST_EMAIL": "your-email@example.com",
         "TYPST_PASSWORD": "your-password"
@@ -58,8 +60,6 @@ Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`,
 }
 ```
 
-> **Session Persistence:** Once authenticated via `typst_auth_login` (or environment variables), the `__Http-typst-session` cookie is cached locally at `~/.pi/agent/typst-mcp-session.json` so subsequent tool calls authenticate automatically without re-signing in.
-
 ---
 
 ## Overview
@@ -74,21 +74,6 @@ Add `typst-mcp` to your MCP client configuration (`.pi/agent/mcp-adapter.json`,
 
 ---
 
-## Architecture
-
-```mermaid
-flowchart LR
-    Agent["AI Agent\n(Pi / Claude / Cursor)"] <-->|"JSON-RPC (stdio)"| MCP["typst-mcp\n(Node / TypeScript)"]
-    MCP <-->|"GraphQL (/v1/graphql)\n+ X-Typst-Preflight"| API["https://api.typst.app"]
-    MCP <-->|"REST Yjs & Blobs\n(/v1/files/:pid/:fid/yjs)"| API
-    MCP <-->|"Binary lib0 WebSocket\n(wss://api.typst.app/editing/v3)"| WS["typst.app Real-Time Sync"]
-    MCP -->|"Workspace Sync + Compile"| TypstCLI["Typst Compiler\n(Diagnostics & PDF)"]
-```
-
-See [`docs/PROTOCOL.md`](./docs/PROTOCOL.md) for the complete reverse-engineered protocol specification.
-
----
-
 ## MCP Tools (18 Tools)
 
 | Category | Tool Name | Description |
@@ -100,22 +85,110 @@ See [`docs/PROTOCOL.md`](./docs/PROTOCOL.md) for the complete reverse-engineered
 | **Projects** | `typst_create_project` | Create a new `typst.app` cloud project with initial `.typ`/`.bib` files and pinned compiler version. |
 | **Projects** | `typst_delete_project` | Permanently delete a `typst.app` project by ID (`DeleteProjectMutation`). |
 | **Files & CRDT** | `typst_list_files` | List all multiplayer Yjs text files and binary asset blobs in a project. |
-| **Files & CRDT** | `typst_read_file` | Read any project file with offset/limit pagination, optional line numbering, truncation limits (2,000 lines/50KB), and multimodal MCP image content blocks (`PNG`, `JPG`, `SVG`, `WebP`). |
+| **Files & CRDT** | `typst_read_file` | Read bounded source pages (200 lines/16 KiB by default), with compact metadata, whole-file content hashes, separate continuation fields, and native image blocks. |
 | **Files & CRDT** | `typst_write_file` | Create or overwrite a `.typ`/`.bib`/`.toml` file, protected by per-file mutation queue serialization, syncing Yjs state diffs over `/editing/v3` WebSocket and REST. |
-| **Files & CRDT** | `typst_edit_file` | Apply surgical `oldText -> newText` replacements directly to the `Y.Text("text")` CRDT with CRLF/BOM resilience, fuzzy quote/dash matching, unified diff & patch output, and per-file mutation serialization. |
+| **Files & CRDT** | `typst_edit_file` | Apply validated, unique edits to one snapshot with optional stale-content protection, exact matching by default, compact receipts, opt-in fuzzy fallback, and bounded diff previews. |
 | **Search & Replace** | `typst_grep_project` | Search for text or regular expressions across project files, returning file paths, line numbers, and optional surrounding context lines. |
-| **Search & Replace** | `typst_find_and_replace` | Find and replace text or regex across a single file or project-wide with regex capture groups (`$1`), dry-run preview diffs, and per-file mutation serialization. |
+| **Search & Replace** | `typst_find_and_replace` | Replace text or regex in one file or project-wide. Batch ordered replacement rules in one call with one save per changed file, compact summaries, optional diffs, and dry-run previews. |
 | **Assets & Tree** | `typst_upload_asset` | Upload or replace binary assets (`PNG`, `JPG`, `SVG`, `PDF`, fonts) from a local path or base64 payload. |
 | **Assets & Tree** | `typst_rename_file` | Rename or move a file inside a `typst.app` project (`UpdatesFileMutation`). |
 | **Assets & Tree** | `typst_delete_file` | Delete a file or binary asset from a project (`DeleteFilesMutation`). |
-| **Compiler** | `typst_get_diagnostics` | Sync all cloud files and run `typst compile` to return structured errors, warnings, line/column spans, and hints. |
+| **Compiler** | `typst_get_diagnostics` | Retrieve compiler diagnostics (errors, warnings, line/column numbers, and hints). Supports both local Typst CLI (`mode="cli"`) and Typst Web cloud compiler (`mode="web"`), with automatic fallback (`mode="auto"`). |
 | **Compiler** | `typst_export_pdf` | Sync all cloud text & binary assets, compile the project to PDF, and save to `outputPath`. |
 | **Preview** | `typst_capture_screenshot` | Capture high-DPI PNG preview screenshots (`mode="pages"` renders compiled PNG pages; `mode="browser"` screenshots the live `typst.app` web UI). |
 
 ---
 
+## Read and edit efficiently
+
+1. Use `typst_grep_project` to locate relevant text, then read just that range with `typst_read_file` (`offset` is 1-based, `limit` defaults to 200 lines, `maxBytes` defaults to 16 KiB and can be raised to 1 MiB).
+2. Keep the returned `contentHash`. It is SHA-256 of the **entire raw text file**, including BOM and line endings, even when reading a range or displaying line numbers.
+3. Send all disjoint edits in one `typst_edit_file` call, with `expectedHash` set to that hash. Prefer a short unique `oldText` anchor over repeating a whole file.
+
+```json
+{
+  "projectId": "your-project-id",
+  "filePath": "main.typ",
+  "expectedHash": "<contentHash from the read response>",
+  "edits": [
+    { "oldText": "September 2025", "newText": "September 2026" }
+  ]
+}
+```
+
+Text read responses include source only in `content`, with `totalLines`, `startLine`, `endLine`, `truncated`, and `nextOffset` when more source remains. They never repeat source in truncation metadata or append instructions to it. Complete lines and original line endings are retained, so unnumbered pages can be concatenated without losing bytes. A trailing newline does not create a phantom extra line. An empty file has `totalLines: 0`, `startLine: 1`, `endLine: 0`.
+
+Read metadata defaults to `{id, name}`. Use `output: "full"` for full file metadata; this does not increase the source range. `lineNumbers: true` adds display prefixes: remove those prefixes when constructing `oldText`. Byte budgets include those prefixes. If one line cannot fit, the tool returns an actionable error rather than an empty page that cannot advance.
+
+Edits match against the same original snapshot, not the result of previous edits. All entries must be valid, and each anchor must be unique, including overlapping occurrences. Invalid batches, overlapping ranges, and stale hashes fail before saving. `matchMode: "exact"` is the default and accepts LF/CRLF differences. Use `matchMode: "fuzzy"` to opt into Unicode quote/dash/space and NFKC fallback when no exact match exists. Fallback matching preserves characters outside the matched span. Edits retain the BOM and untouched line endings, including mixed LF/CRLF files.
+
+Successful edits return a compact receipt with file ID/name, `appliedCount`, the resulting `contentHash`, and `firstChangedLine`. This avoids returning the same changes as both a diff and a patch. Optional controls:
+
+- `output: "diff"` adds a display diff; `output: "full"` also adds a patch and full metadata.
+- Each diff/patch field is limited to 100 lines and `maxDiffBytes` bytes (default 8192, maximum 1 MiB). `diffTruncated` / `patchTruncated` explicitly flag omissions; read the affected range for complete source.
+- `dryRun: true` validates and previews without saving and defaults to diff output. Its `appliedCount` describes proposed edits; its `contentHash` still identifies the unchanged cloud text.
+
+`expectedHash` is checked on fresh text inside the shared file mutation queue, which serializes local edits, replacements, and whole-file writes to existing files. It detects changes made since the read; it is not a cloud compare-and-swap transaction and cannot prevent a collaborator from editing during the subsequent save. Yjs still merges concurrent cloud updates.
+
+**Changed defaults:** reads previously allowed 2,000 lines/50 KiB and embedded continuation hints in `content`. Read callers should follow `nextOffset` now. MCP edits previously returned full diffs/patches and used fuzzy fallback automatically; request `output: "full"` or `matchMode: "fuzzy"` explicitly when needed. The low-level `editYjsText` helper retains its legacy fuzzy default; the client/MCP edit path defaults to exact matching.
+
+## Batch replacements for agents
+
+Use one `typst_find_and_replace` call for related replacements. For example, expand abbreviated month names throughout all `.typ` files:
+
+```json
+{
+  "projectId": "your-project-id",
+  "glob": "*.typ",
+  "replacements": [
+    { "pattern": "\\bSep\\b", "replacement": "September", "regex": true },
+    { "pattern": "\\bOct\\b", "replacement": "October", "regex": true }
+  ]
+}
+```
+
+Each file is downloaded once, all rules run in order on the previous rule's result, and the file is saved once if its final text changed. All rules are validated before any files are written. File mutations remain serialized with other edits; a project-wide operation is **not atomic across files** if a network or save error occurs.
+
+Batch calls default to `output: "summary"`:
+
+```json
+{
+  "filesModified": [
+    {
+      "file": "main.typ",
+      "replacementsCount": 3,
+      "replacementCounts": [2, 1],
+      "firstChangedLine": 4
+    }
+  ],
+  "totalReplacements": 3,
+  "dryRun": false
+}
+```
+
+`replacementCounts` follows the input rule order and counts matches applied by each rule in that changed file. Unchanged files, including batches whose rules cancel each other out, are omitted and do not contribute to totals.
+
+- Set `dryRun: true` to preview without saving. Add `output: "diff"` to include a single combined display diff per file.
+- Set `output: "full"` to include both the display diff and unified patch.
+- Set `regex`, `ignoreCase`, and `limit` on each batch rule. `limit` is a non-negative integer per rule per file; `0` disables that rule.
+- Use either `replacements` or the existing `pattern`/`replacement` fields. Existing single-replacement calls still default to `output: "full"`; they can request `"summary"` too.
+- Use `filePath` to target one file by path or ID. A missing explicit file returns an error.
+
 ## Development & Verification
 
+### From Source (Development)
+
+Requires [**Bun**](https://bun.sh) `>= 1.2`:
+
+```bash
+git clone https://github.com/caphefalumi/typst-web-mcp.git
+cd typst-web-mcp
+bun install
+bun run dev
+```
+
+### Build & Test
+
 ```bash
 # Compile publishable output to dist/
 bun run build
@@ -143,36 +216,6 @@ Same flow as [Canvas-CLI](https://github.com/caphefalumi/Canvas-CLI):
 
 **Trusted publisher (maintainers):** package [`typst-mcp`](https://www.npmjs.com/package/typst-mcp) → Settings → Trusted publishing → GitHub Actions — user/org `caphefalumi`, repo `typst-web-mcp`, workflow file `npm-publish.yml`, environment `npm-publish`, allow **npm publish**.
 
-### Project Structure
-
-```text
-typst-web-mcp/
-├── docs/
-│   └── PROTOCOL.md              # Reverse-engineered typst.app REST, GraphQL, Yjs & WS v3 spec
-├── src/
-│   ├── protocol/
-│   │   ├── edit-diff.ts         # Fuzzy matching, CRLF/BOM resilience, unified diff & patch generator
-│   │   ├── ws-codec.ts          # Binary lib0 /editing/v3 WebSocket encoder & decoder
-│   │   ├── yjs-doc.ts           # Yjs CRDT text decoding, replacement & surgical patching
-│   │   └── graphql.ts           # GraphQL queries, mutations, fragments & types
-│   ├── client/
-│   │   ├── auth.ts              # Direct /v1/auth/signin login, cookie jar & Playwright fallback
-│   │   ├── compiler.ts          # Typst binary resolver, diagnostic parser, PDF & PNG preview compiler
-│   │   ├── errors.ts            # Structured TypstLoadError & error formatting helpers
-│   │   └── typst-client.ts      # TypstCloudClient (REST, GraphQL, WebSocket v3, Compiler facade)
-│   ├── tools/
-│   │   └── definitions.ts       # MCP JSON Schema definitions for all 16 tools
-│   ├── utils/
-│   │   ├── file-mutation-queue.ts # Serialized mutation mutex queue per file
-│   │   ├── mime.ts              # Image MIME type detection
-│   │   └── truncate.ts          # Dual-limit (line & byte) head/tail truncation utilities
-│   └── index.ts                 # MCP stdio server entrypoint (dev); npm bin runs dist/index.js
-├── test/
-│   └── typst-mcp.test.ts        # 7 test suites (57 assertions) covering codecs, CRDTs & E2E
-├── LICENSE                      # MIT License
-└── package.json
-```
-
 ---
 
 ## License

package/dist/client/auth.js

@@ -13,9 +13,31 @@ function extractRawSetCookies(headers) {
     }
     return [];
 }
+export function getDefaultSessionFilePath() {
+    if (process.env.TYPST_SESSION_FILE) {
+        return process.env.TYPST_SESSION_FILE;
+    }
+    const platform = process.platform;
+    if (platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ||
+            (process.env.APPDATA
+                ? join(process.env.APPDATA, "..", "Local")
+                : join(homedir(), "AppData", "Local"));
+        return join(localAppData, "typst-mcp", "session.json");
+    }
+    if (platform === "darwin") {
+        if (process.env.XDG_CACHE_HOME) {
+            return join(process.env.XDG_CACHE_HOME, "typst-mcp", "session.json");
+        }
+        return join(homedir(), "Library", "Caches", "typst-mcp", "session.json");
+    }
+    // Linux and other POSIX systems (XDG Base Directory specification)
+    const cacheDir = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+    return join(cacheDir, "typst-mcp", "session.json");
+}
 function resolveSessionFilePath(configuredPath) {
     if (configuredPath === undefined) {
-        return join(homedir(), ".pi", "agent", "typst-mcp-session.json");
+        return getDefaultSessionFilePath();
     }
     return configuredPath;
 }
@@ -92,11 +114,22 @@ export class TypstAuthManager {
         }
     }
     loadStoredSession() {
-        if (!this.sessionFilePath || !existsSync(this.sessionFilePath)) {
+        if (!this.sessionFilePath) {
             return;
         }
+        let targetPath = this.sessionFilePath;
+        if (!existsSync(targetPath)) {
+            // Legacy fallback check for seamless migration from ~/.pi/agent/typst-mcp-session.json
+            const legacyPath = join(homedir(), ".pi", "agent", "typst-mcp-session.json");
+            if (existsSync(legacyPath)) {
+                targetPath = legacyPath;
+            }
+            else {
+                return;
+            }
+        }
         try {
-            const raw = JSON.parse(readFileSync(this.sessionFilePath, "utf8"));
+            const raw = JSON.parse(readFileSync(targetPath, "utf8"));
             if (raw && typeof raw.cookies === "object" && raw.cookies) {
                 this.cookies = { ...raw.cookies };
                 this.authMethod = raw.authMethod ?? "cookie";

package/dist/client/compiler.js

@@ -29,6 +29,52 @@ export function resolveTypstBinary(explicitBin) {
     }
     return "typst";
 }
+export function hasTypstBinary(explicitBin) {
+    try {
+        const bin = resolveTypstBinary(explicitBin);
+        if (bin !== "typst" && existsSync(bin)) {
+            return true;
+        }
+        const proc = spawnSync(bin, ["--version"], {
+            stdio: "ignore",
+            encoding: "utf8",
+        });
+        return proc.status === 0 && !proc.error;
+    }
+    catch {
+        return false;
+    }
+}
+export function resolvePythonBinary() {
+    if (process.env.PYTHON_BIN) {
+        return process.env.PYTHON_BIN;
+    }
+    for (const cmd of ["python", "python3", "py"]) {
+        try {
+            const res = spawnSync(cmd, ["--version"], { stdio: "ignore" });
+            if (res.status === 0) {
+                return cmd;
+            }
+        }
+        catch { }
+    }
+    return "python";
+}
+export function offsetToPosition(text, offset) {
+    let line = 1;
+    let column = 1;
+    const target = Math.min(Math.max(0, offset), text.length);
+    for (let i = 0; i < target; i++) {
+        if (text[i] === "\n") {
+            line++;
+            column = 1;
+        }
+        else {
+            column++;
+        }
+    }
+    return { line, column };
+}
 function hasValidPngSignature(bytes) {
     return (bytes.byteLength >= 8 &&
         bytes[0] === 0x89 &&
@@ -95,6 +141,9 @@ export function compileWorkspaceDiagnostics(params) {
         cwd: params.workspaceDir,
         encoding: "utf8",
     });
+    if (proc.error) {
+        throw new TypstLoadError(["TYPST_EXECUTION_FAILED"], `Failed to execute Typst compiler binary '${params.typstBin}': ${proc.error.message}`);
+    }
     const combinedOutput = `${proc.stderr ?? ""}\n${proc.stdout ?? ""}`;
     const diagnostics = parseShortDiagnostics(combinedOutput).map((d) => ({
         ...d,
@@ -130,6 +179,9 @@ export function compileWorkspacePdf(params) {
         cwd: params.workspaceDir,
         encoding: "utf8",
     });
+    if (proc.error) {
+        throw new TypstLoadError(["TYPST_EXECUTION_FAILED"], `Failed to execute Typst compiler binary '${params.typstBin}': ${proc.error.message}`);
+    }
     const combinedOutput = `${proc.stderr ?? ""}\n${proc.stdout ?? ""}`;
     const diagnostics = parseShortDiagnostics(combinedOutput);
     if (proc.status !== 0) {
@@ -148,12 +200,169 @@ export function compileWorkspacePdf(params) {
         diagnostics,
     };
 }
+export function captureWebDiagnostics(params) {
+    const pythonBin = resolvePythonBinary();
+    const timeoutSec = ((params.timeoutMs ?? 25000) / 1000).toFixed(1);
+    const pyScript = `
+import os, sys, json, time
+from playwright.sync_api import sync_playwright
+
+app_url = os.environ.get("TYPST_APP_URL", "https://typst.app")
+proj_id = os.environ["TYPST_PROJ_ID"]
+raw_cookie = os.environ.get("TYPST_COOKIE", "")
+timeout_sec = float(os.environ.get("TYPST_TIMEOUT_SEC", "25.0"))
+
+cookies = []
+for part in raw_cookie.split(";"):
+    part = part.strip()
+    if "=" in part:
+        k, v = part.split("=", 1)
+        name = k.strip()
+        val = v.strip()
+        is_session = "__Http" in name or "session" in name
+        cookies.append({
+            "name": name,
+            "value": val,
+            "domain": ".typst.app",
+            "path": "/",
+            "httpOnly": is_session,
+            "secure": True,
+            "sameSite": "Strict" if is_session else "Lax",
+        })
+
+with sync_playwright() as p:
+    browser = None
+    for channel in ["msedge", "chrome", None]:
+        try:
+            if channel:
+                browser = p.chromium.launch(channel=channel, headless=True)
+            else:
+                browser = p.chromium.launch(headless=True)
+            break
+        except Exception:
+            continue
+
+    if browser is None:
+        sys.stderr.write("NO_BROWSER_FOUND")
+        sys.exit(2)
+
+    ctx = browser.new_context(viewport={"width": 1920, "height": 1080})
+    if cookies:
+        ctx.add_cookies(cookies)
+
+    ctx.add_init_script("""
+        window.__typst_diagnostics = null;
+        window.__typst_status = 'starting';
+        const OrigWorker = window.Worker;
+        window.Worker = function(url, opts) {
+            const w = new OrigWorker(url, opts);
+            w.addEventListener('message', (ev) => {
+                try {
+                    if (ev.data && ev.data.tag === 'notification') {
+                        if (ev.data.name === 'diagnostics') {
+                            window.__typst_diagnostics = ev.data.notification?.diagnostics || [];
+                        } else if (ev.data.name === 'status') {
+                            window.__typst_status = ev.data.notification?.status || 'idle';
+                        }
+                    }
+                } catch(e) {}
+            });
+            return w;
+        };
+    """)
+
+    page = ctx.new_page()
+    page.goto(f"{app_url}/project/{proj_id}", wait_until="commit", timeout=45000)
+
+    start_time = time.time()
+    diags = None
+    while time.time() - start_time < timeout_sec:
+        data = page.evaluate("({ diag: window.__typst_diagnostics, status: window.__typst_status, url: window.location.href })")
+        if "signin" in data.get("url", ""):
+            browser.close()
+            sys.stderr.write(f"AUTH_REQUIRED: Redirected to {data.get('url')}")
+            sys.exit(3)
+        if data.get("diag") is not None:
+            diags = data.get("diag")
+            if data.get("status") == "idle":
+                break
+        page.wait_for_timeout(300)
+
+    browser.close()
+    print(json.dumps(diags or []))
+`;
+    const proc = spawnSync(pythonBin, ["-c", pyScript], {
+        env: {
+            ...process.env,
+            TYPST_APP_URL: params.appUrl,
+            TYPST_PROJ_ID: params.projectId,
+            TYPST_COOKIE: params.cookieHeader,
+            TYPST_TIMEOUT_SEC: timeoutSec,
+        },
+        encoding: "utf8",
+        timeout: (params.timeoutMs ?? 25000) + 15000,
+    });
+    if (proc.error || proc.status !== 0) {
+        const stderr = (proc.stderr || proc.error?.message || "").trim();
+        if (stderr.includes("NO_BROWSER_FOUND")) {
+            throw new TypstLoadError(["NO_BROWSER_FOUND"], "No compatible browser (Edge, Chrome, or Chromium) found for Playwright web diagnostics.");
+        }
+        if (stderr.includes("AUTH_REQUIRED")) {
+            throw new TypstLoadError(["UNAUTHENTICATED"], `Typst Web cloud session expired or invalid: ${stderr}`);
+        }
+        throw new TypstLoadError(["WEB_DIAGNOSTICS_FAILED"], `Failed to capture Typst Web cloud diagnostics: ${stderr || "Ensure python with playwright is installed ('pip install playwright && playwright install')"}`);
+    }
+    const rawJson = (proc.stdout || "").trim();
+    let rawList = [];
+    try {
+        rawList = JSON.parse(rawJson);
+    }
+    catch (err) {
+        throw new TypstLoadError(["WEB_DIAGNOSTICS_PARSE_FAILED"], `Failed to parse Typst Web diagnostics output: ${err.message}`);
+    }
+    const mainFileName = params.mainFile ?? "main.typ";
+    const diagnostics = rawList.map((raw) => {
+        let line = 1;
+        let column = 1;
+        const filePath = raw.path || mainFileName;
+        const fileText = params.fileContents?.[filePath];
+        if (fileText && raw.range?.start !== undefined) {
+            const pos = offsetToPosition(fileText, raw.range.start);
+            line = pos.line;
+            column = pos.column;
+        }
+        return {
+            path: filePath,
+            line,
+            column,
+            severity: raw.severity === "error" ? "error" : "warning",
+            message: raw.message,
+            hints: Array.isArray(raw.hints) ? raw.hints : [],
+            package: raw.package ?? null,
+            range: raw.range
+                ? { start: raw.range.start, end: raw.range.end }
+                : undefined,
+        };
+    });
+    const errorCount = diagnostics.filter((d) => d.severity === "error").length;
+    const warningCount = diagnostics.filter((d) => d.severity === "warning").length;
+    return {
+        projectId: params.projectId,
+        mainFile: mainFileName,
+        mode: "web",
+        success: errorCount === 0,
+        errorCount,
+        warningCount,
+        diagnostics,
+    };
+}
 export function captureBrowserPreviewScreenshot(params) {
     const outputDir = resolveOutputDirectory(params.outputDir, `typst-preview-ui-${params.projectId}-`);
     mkdirSync(outputDir, { recursive: true });
     const screenshotPath = join(outputDir, `typst-app-${params.projectId}.png`);
+    const pythonBin = resolvePythonBinary();
     const pyScript = `
-import os
+import os, sys
 from playwright.sync_api import sync_playwright
 
 app_url = os.environ["TYPST_PREVIEW_APP_URL"]
@@ -166,16 +375,35 @@ for part in raw_cookie.split(";"):
     part = part.strip()
     if "=" in part:
         k, v = part.split("=", 1)
+        name = k.strip()
+        val = v.strip()
+        is_session = "__Http" in name or "session" in name
         cookies.append({
-            "name": k.strip(),
-            "value": v.strip(),
-            "domain": "typst.app",
+            "name": name,
+            "value": val,
+            "domain": ".typst.app",
             "path": "/",
+            "httpOnly": is_session,
             "secure": True,
+            "sameSite": "Strict" if is_session else "Lax",
         })
 
 with sync_playwright() as p:
-    browser = p.chromium.launch(channel="msedge", headless=True)
+    browser = None
+    for channel in ["msedge", "chrome", None]:
+        try:
+            if channel:
+                browser = p.chromium.launch(channel=channel, headless=True)
+            else:
+                browser = p.chromium.launch(headless=True)
+            break
+        except Exception:
+            continue
+
+    if browser is None:
+        sys.stderr.write("NO_BROWSER_FOUND")
+        sys.exit(2)
+
     ctx = browser.new_context(viewport={"width": 1920, "height": 1080}, device_scale_factor=2)
     if cookies:
         ctx.add_cookies(cookies)
@@ -185,7 +413,7 @@ with sync_playwright() as p:
     page.screenshot(path=out_path, full_page=False)
     browser.close()
 `;
-    const proc = spawnSync("python", ["-c", pyScript], {
+    const proc = spawnSync(pythonBin, ["-c", pyScript], {
         env: {
             ...process.env,
             TYPST_PREVIEW_APP_URL: params.appUrl,