Merge branch 'main' into feat/typst-annotation-filename

Author: mcanouil

.claude/commands/quarto-preview-test/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: quarto-preview-test
+description: Use when testing preview functionality, verifying live reload, or validating preview fixes. Covers starting preview with port/logging, browser verification via /agent-browser, and checking logs/filesystem for artifacts.
+---
+
+# Quarto Preview Test
+
+Interactive testing of `quarto preview` with automated browser verification.
+
+## Tools
+
+| Tool | When to use |
+|------|-------------|
+| `/agent-browser` | **Preferred.** Token-efficient browser automation. Navigate, verify content, screenshot. |
+| Chrome DevTools MCP | Deep debugging: console messages, network requests, DOM inspection. |
+| `jq` / `grep` | Parse debug log output. |
+
+## Prerequisites
+
+- Quarto dev version built (`./configure.sh` or `./configure.cmd`)
+- Test environment configured (`tests/configure-test-env.sh` or `tests/configure-test-env.ps1`)
+- `/agent-browser` CLI installed (preferred), OR Chrome + Chrome DevTools MCP connected
+
+## Starting Preview
+
+Preview needs the test venv for Jupyter tests. Activate it first (`tests/.venv`), matching how `run-tests.sh` / `run-tests.ps1` do it.
+
+```bash
+# Linux/macOS
+source tests/.venv/bin/activate
+./package/dist/bin/quarto preview <file-or-dir> --no-browser --port 4444
+
+# Windows (Git Bash)
+source tests/.venv/Scripts/activate
+./package/dist/bin/quarto.cmd preview <file-or-dir> --no-browser --port 4444
+```
+
+Use `--no-browser` to control browser connection. Use `--port` for a predictable URL.
+
+### With debug logging
+
+```bash
+./package/dist/bin/quarto preview <file> --no-browser --port 4444 --log-level debug 2>&1 | tee preview.log
+```
+
+### In background
+
+```bash
+# Linux/macOS (after venv activation)
+./package/dist/bin/quarto preview <file> --no-browser --port 4444 &
+PREVIEW_PID=$!
+# ... run verification ...
+kill $PREVIEW_PID
+
+# Windows (Git Bash, after venv activation)
+./package/dist/bin/quarto.cmd preview <file> --no-browser --port 4444 &
+PREVIEW_PID=$!
+# ... run verification ...
+kill $PREVIEW_PID
+```
+
+## Edit-Verify Cycle
+
+The core test pattern:
+
+1. Start preview with `--no-browser --port 4444`
+2. Use `/agent-browser` to navigate to `http://localhost:4444/` and verify content
+3. Edit source file, wait 3-5 seconds for re-render
+4. Verify content updated in browser
+5. Check filesystem for unexpected artifacts
+6. Stop preview, verify cleanup
+
+## What to Verify
+
+**In browser** (via `/agent-browser`): Page loads, content matches source, updates reflect edits.
+
+**In terminal/logs**: No `BadResource` errors, no crashes, preview stays responsive.
+
+**On filesystem**: No orphaned temp files, cleanup happens on exit.
+
+## Windows Limitations
+
+On Windows, `kill` from Git Bash does not trigger Quarto's `onCleanup` handler (SIGINT doesn't propagate to Windows processes the same way). Cleanup-on-exit verification requires an interactive terminal with Ctrl+C. For automated testing, verify artifacts *during* preview instead.
+
+## Context Types
+
+Preview behaves differently depending on input:
+
+| Input | Code path |
+|-------|-----------|
+| Single file (no project) | `preview()` -> `renderForPreview()` |
+| File within a project | May redirect to project preview via `serveProject()` |
+| Project directory | `serveProject()` -> `watchProject()` |
+
+See `llm-docs/preview-architecture.md` for the full architecture.
+
+## When NOT to Use
+
+- Automated smoke tests — use `tests/smoke/` instead
+- Testing render output only (no live preview needed) — use `quarto render`
+- CI environments without browser access
+
+## Test Matrix
+
+The full test matrix lives in `tests/docs/manual/preview/README.md`. Test fixtures live alongside it in `tests/docs/manual/preview/`.
+
+### Running specific tests by ID
+
+When invoked with test IDs (e.g., `/quarto-preview-test T17 T18`):
+
+1. Read `tests/docs/manual/preview/README.md`
+2. Find each requested test by its ID (e.g., `#### T17:`)
+3. Parse the **Setup**, **Steps**, and **Expected** fields
+4. Execute each test following the steps, using the fixtures in `tests/docs/manual/preview/`
+5. Report PASS/FAIL for each test with the actual vs expected result
+
+### Running tests by topic
+
+When invoked with a topic description instead of IDs (e.g., `/quarto-preview-test root URL` or "run preview tests for single-file"):
+
+1. Read `tests/docs/manual/preview/README.md`
+2. Search test titles and descriptions for matches (keywords, issue numbers, feature area)
+3. Present the matched tests to the user for confirmation before running:
+   ```
+   Found these matching tests:
+   - T17: Single-file preview — root URL accessible (#14298)
+   - T18: Single-file preview — named output URL also accessible
+   Run these? [Y/n]
+   ```
+4. Only execute after user confirms
+
+### Running without arguments
+
+When invoked without test IDs or topic (e.g., `/quarto-preview-test`), use the general Edit-Verify Cycle workflow described above for ad-hoc preview testing. The test matrix is for targeted regression testing.
+
+## Baseline Comparison
+
+Compare dev build against installed release to distinguish regressions:
+
+```bash
+quarto --version                        # installed
+./package/dist/bin/quarto --version     # dev
+```
+
+If both show the same issue, it's pre-existing.

.claude/rules/testing/typescript-tests.md

@@ -92,3 +92,20 @@ const fixtureDir = docs("my-fixture");  // → tests/docs/my-fixture/
 - `tests/docs/<feature>/` - Test fixtures
 
 **Details:** `llm-docs/testing-patterns.md` for comprehensive patterns and examples.
+
+## Common Test Utilities
+
+**Constructing `MappedString` values:**
+```typescript
+import { asMappedString } from "../../../src/core/lib/mapped-text.ts";
+
+// Use asMappedString("") instead of casting or constructing MappedString manually
+const markdown = asMappedString("");
+const markdownWithContent = asMappedString("# Title\nSome content");
+```
+
+**Mock ProjectContext:**
+```typescript
+import { createMockProjectContext } from "./utils.ts";  // tests/unit/project/utils.ts
+const project = createMockProjectContext();  // Creates temp dir + FileInformationCacheMap
+```

.github/workflows/actions/quarto-dev/action.yml

@@ -12,17 +12,6 @@ runs:
         restore-keys: |
           ${{ runner.os }}-deno_std-2-
 
-    - name: Cache Cargo dependencies
-      uses: actions/cache@v5
-      with:
-        path: |
-          ~/.cargo/registry
-          ~/.cargo/git
-          package/typst-gather/target
-        key: ${{ runner.os }}-cargo-typst-gather-${{ hashFiles('package/typst-gather/Cargo.lock') }}
-        restore-keys: |
-          ${{ runner.os }}-cargo-typst-gather-
-
     - name: Configure Quarto (.sh)
       if: runner.os != 'Windows'
       shell: bash

.github/workflows/create-release.yml

@@ -89,7 +89,7 @@ jobs:
         run: |
           echo ${{ steps.read-version.outputs.version_full }} > version.txt
 
-      - uses: EndBug/add-and-commit@a94899bca583c204427a224a7af87c02f9b325d5
+      - uses: EndBug/add-and-commit@290ea2c423ad77ca9c62ae0f5b224379612c0321
         if: ${{ inputs.publish-release }}
         id: version_commit
         with:
@@ -677,9 +677,7 @@ jobs:
 
       - name: Create Release
         id: create_release
-        uses: softprops/action-gh-release@4634c16e79c963813287e889244c50009e7f0981
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe
         with:
           tag_name: ${{needs.configure.outputs.tag_name}}
           target_commitish: ${{ needs.configure.outputs.version_commit }}

.github/workflows/test-ff-matrix.yml

@@ -20,6 +20,7 @@ on:
       - ".github/workflows/stale-needs-repro.yml"
       - ".github/workflows/test-bundle.yml"
       - ".github/workflows/test-smokes-parallel.yml"
+      - ".github/workflows/test-install.yml"
       - ".github/workflows/test-quarto-latexmk.yml"
       - ".github/workflows/update-test-timing.yml"
   pull_request:
@@ -31,6 +32,7 @@ on:
       - ".github/workflows/performance-check.yml"
       - ".github/workflows/stale-needs-repro.yml"
       - ".github/workflows/test-bundle.yml"
+      - ".github/workflows/test-install.yml"
       - ".github/workflows/test-smokes-parallel.yml"
       - ".github/workflows/test-quarto-latexmk.yml"
       - ".github/workflows/update-test-timing.yml"

.github/workflows/test-install.yml

@@ -0,0 +1,170 @@
+# Integration test for `quarto install` on platforms not covered by smoke tests.
+# Smoke tests (test-smokes.yml) cover x86_64 Linux and Windows.
+# This workflow fills the gap for arm64 Linux and macOS.
+name: Test Tool Install
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - "v1.*"
+    paths:
+      - "src/tools/**"
+      - ".github/workflows/test-install.yml"
+  pull_request:
+    paths:
+      - "src/tools/**"
+      - ".github/workflows/test-install.yml"
+  schedule:
+    # Weekly Monday 9am UTC — detect upstream CDN/API breakage
+    - cron: "0 9 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  test-install:
+    name: Install tools (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04-arm, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v6
+
+      - uses: ./.github/workflows/actions/quarto-dev
+
+      - name: Install TinyTeX
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          quarto install tinytex
+
+      - name: Install Chrome Headless Shell
+        run: |
+          quarto install chrome-headless-shell --no-prompt
+
+      - name: Verify tools with quarto check
+        run: |
+          quarto check install
+
+  test-chromium-deprecation:
+    name: Chromium deprecation redirect (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v6
+
+      - uses: ./.github/workflows/actions/quarto-dev
+
+      - name: Make quarto available in bash (Windows)
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          quarto_cmd=$(command -v quarto.cmd)
+          dir=$(dirname "$quarto_cmd")
+          printf '#!/bin/bash\nexec "%s" "$@"\n' "$quarto_cmd" > "$dir/quarto"
+          chmod +x "$dir/quarto"
+
+      - name: Install chromium (should redirect to chrome-headless-shell)
+        id: install-chromium
+        shell: bash
+        run: |
+          set +e
+          output=$(quarto install chromium --no-prompt 2>&1)
+          exit_code=$?
+          set -e
+          echo "$output"
+          if echo "$output" | grep -Fq "is deprecated"; then
+            echo "deprecation-warning=true" >> "$GITHUB_OUTPUT"
+          fi
+          if [ "$exit_code" -eq 0 ]; then
+            echo "install-successful=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Assert deprecation warning was shown
+        shell: bash
+        run: |
+          if [ "${{ steps.install-chromium.outputs.deprecation-warning }}" != "true" ]; then
+            echo "::error::Deprecation warning missing from 'quarto install chromium' output"
+            exit 1
+          fi
+          echo "Install deprecation warning found"
+
+      - name: Assert installation succeeded (via redirect)
+        shell: bash
+        run: |
+          if [ "${{ steps.install-chromium.outputs.install-successful }}" != "true" ]; then
+            echo "::error::Installation did not succeed — redirect to chrome-headless-shell may have failed"
+            exit 1
+          fi
+          echo "Installation succeeded via redirect"
+
+      - name: Verify quarto check shows Chrome Headless Shell
+        shell: bash
+        run: |
+          output=$(quarto check install 2>&1)
+          echo "$output"
+          if ! echo "$output" | grep -Fq "Chrome Headless Shell"; then
+            echo "::error::Chrome Headless Shell not detected by quarto check after redirect install"
+            exit 1
+          fi
+          if echo "$output" | grep -Fq 'chrome-headless-shell" to replace'; then
+            echo "::error::Legacy Chromium still installed — afterInstall should have removed it"
+            exit 1
+          fi
+
+      - name: Verify quarto list tools does not show chromium
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set +e
+          output=$(quarto list tools 2>&1)
+          exit_code=$?
+          set -e
+          echo "$output"
+          if [ "$exit_code" -ne 0 ]; then
+            echo "::error::'quarto list tools' exited with code $exit_code (see output above)"
+            exit 1
+          fi
+          if echo "$output" | grep -iq "chromium"; then
+            echo "::error::Deprecated chromium should not appear in 'quarto list tools' when not installed"
+            exit 1
+          fi
+
+      - name: Update chromium (should redirect) and capture result
+        id: update-chromium
+        shell: bash
+        run: |
+          set +e
+          output=$(quarto update tool chromium --no-prompt 2>&1)
+          exit_code=$?
+          set -e
+          echo "$output"
+          if echo "$output" | grep -Fq "is deprecated"; then
+            echo "deprecation-warning=true" >> "$GITHUB_OUTPUT"
+          fi
+          if [ "$exit_code" -eq 0 ]; then
+            echo "update-successful=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Assert update deprecation warning was shown and succeeded
+        shell: bash
+        run: |
+          if [ "${{ steps.update-chromium.outputs.deprecation-warning }}" != "true" ]; then
+            echo "::error::Deprecation warning missing from 'quarto update tool chromium' output"
+            exit 1
+          fi
+          echo "Update deprecation warning found"
+          if [ "${{ steps.update-chromium.outputs.update-successful }}" != "true" ]; then
+            echo "::error::Update command failed — redirect to chrome-headless-shell may have failed"
+            exit 1
+          fi
+          echo "Update succeeded via redirect"

.github/workflows/test-smokes-parallel.yml

@@ -29,6 +29,7 @@ on:
       - ".github/workflows/stale-needs-repro.yml"
       - ".github/workflows/test-bundle.yml"
       - ".github/workflows/test-ff-matrix.yml"
+      - ".github/workflows/test-install.yml"
       - ".github/workflows/test-quarto-latexmk.yml"
       - ".github/workflows/update-test-timing.yml"
   push: