[backport] Fix preview browse URL for single-file documents

.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 `.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.

news/changelog-1.9.md

@@ -4,6 +4,7 @@
 
 - ([#14267](https://github.com/quarto-dev/quarto-cli/issues/14267)): Fix Windows paths with accented characters (e.g., `C:\Users\Sébastien\`) breaking dart-sass compilation.
 - ([#14281](https://github.com/quarto-dev/quarto-cli/issues/14281)): Fix transient `.quarto_ipynb` files accumulating during `quarto preview` with Jupyter engine.
+- ([#14298](https://github.com/quarto-dev/quarto-cli/issues/14298)): Fix `quarto preview` browse URL including output filename (e.g., `hello.html`) for single-file documents, breaking Posit Workbench proxied server access.
 
 ## In previous releases
 

src/command/preview/preview.ts

@@ -143,6 +143,21 @@ interface PreviewOptions {
   presentation: boolean;
 }
 
+export function previewInitialPath(
+  outputFile: string,
+  project: ProjectContext | undefined,
+): string {
+  if (isPdfContent(outputFile)) {
+    return kPdfJsInitialPath;
+  }
+  if (project && !project.isSingleFile) {
+    return pathWithForwardSlashes(
+      relative(projectOutputDir(project), outputFile),
+    );
+  }
+  return "";
+}
+
 export async function preview(
   file: string,
   flags: RenderFlags,
@@ -230,7 +245,7 @@ export async function preview(
       changeHandler.render,
       project,
     )
-    : project
+    : project && !project.isSingleFile
     ? projectHtmlFileRequestHandler(
       project,
       normalizePath(file),
@@ -250,13 +265,7 @@ export async function preview(
     );
 
   // open browser if this is a browseable format
-  const initialPath = isPdfContent(result.outputFile)
-    ? kPdfJsInitialPath
-    : project
-    ? pathWithForwardSlashes(
-      relative(projectOutputDir(project), result.outputFile),
-    )
-    : "";
+  const initialPath = previewInitialPath(result.outputFile, project);
   if (
     options.browser &&
     !isServerSession() &&

tests/docs/manual/README.md

@@ -0,0 +1,17 @@
+# Manual Tests
+
+Tests that require interactive sessions, external services, or browser access that cannot run in automated CI.
+
+## Test Suites
+
+| Directory / File | Area | Skill | Description |
+|-----------------|------|-------|-------------|
+| `preview/` | `quarto preview` | `/quarto-preview-test` | Live preview server behavior: URL routing, file watching, live reload, transient file cleanup |
+| `publish-connect-cloud/` | `quarto publish` | — | Posit Connect Cloud publishing with OAuth flow |
+| `mermaid-svg-pdf-tooling.qmd` | `quarto render` | — | Mermaid SVG rendering to PDF with external tooling (rsvg-convert) |
+
+## Running Tests
+
+Each suite has its own README with test matrix and execution instructions. Test fixtures live alongside the README in each directory.
+
+For preview tests, use the `/quarto-preview-test` skill which automates the start-verify-cleanup cycle.