feat(preview): sync sibling assets a single-file deck references (bd-kpuweafo)

`q2 preview deck.qmd` on a bare file (no `_quarto.yml`) runs single-file mode,
which doesn't walk the directory — so `![](./sibling-image.png)` rendered broken
(the image never reached the VFS; the `<img>` request fell through to the SPA
`index.html`: `naturalWidth 0`, `content-type: text/html`). Project mode works
because the dir-walk syncs the image → automerge → VFS → blob URL.

Match project behavior *for the assets the deck actually references*, without
walking the directory (preserves the `bd-tnm3k` "don't index arbitrary siblings"
property and the VFS-only delivery model — no new disk-serving route):

- quarto-core: `transforms::collect_referenced_asset_urls(blocks)` returns the
  relative `Image` URLs a document references (reuses the ResourceCollector
  traversal; external/absolute URLs dropped).
- quarto-preview: `config::resolve_single_file_assets` parses the deck and keeps
  the referenced relative binary assets that exist and canonicalize *under* the
  deck dir (rejects `../` escapes). Injected via `HubConfig.single_file_assets`.
- quarto-hub: `ProjectFiles::with_binary_files`; the single-file branch appends
  these so `reconcile_files_with_index` syncs them like project mode.

E2E (`q2 preview page.qmd`, no `_quarto.yml`, sibling image): now a blob URL,
`naturalWidth 320` — identical to project mode. Tests: collect_referenced_asset_
urls (quarto-core), resolve_single_file_assets + `../`-escape guard
(quarto-preview), with_binary_files (quarto-hub). `cargo xtask verify` green.

v1 limits (documented in the plan): load-time resolution only (a reference added
mid-edit needs reload), direct (non-`{{< include >}}`) image references only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cscheid

claude-notes/plans/2026-06-16-single-file-preview-referenced-assets.md

@@ -0,0 +1,66 @@
+# Single-file `q2 preview`: resolve sibling assets the deck references
+
+**Strand:** bd-kpuweafo · **Found:** 2026-06-16 (follow-up to bd-y259zb57 / bd-ggvq1j68)
+
+## Problem
+
+`q2 preview deck.qmd` on a bare file (no `_quarto.yml` ancestor) runs single-file
+mode (`bd-tnm3k`), which **does not walk the directory** — only the target `.qmd`
+(plus, now, `_brand.yml` siblings) reaches the preview VFS. So an image
+`![](./sibling-image.png)` renders broken: `vfsReadBinaryFile` fails, the asset
+manifest has no entry, and the `<img>` falls through to the SPA `index.html`
+(verified E2E: `naturalWidth = 0`, response `content-type: text/html`). In
+**project mode** (`_quarto.yml` present) the dir-walk syncs the image →
+automerge → VFS → blob URL, and it works (`naturalWidth = 320`).
+
+## Constraint
+
+Single-file mode must **not** walk the whole directory (`bd-tnm3k`): a bare
+`q2 preview ~/Downloads/note.qmd` must not index all of `~/Downloads`. So
+"match project behavior" = sync the **specific sibling assets the deck
+references**, not every sibling.
+
+## Approach (reference-driven VFS sync)
+
+Mirror project mode's *mechanism* (sync into VFS → blob URL), not a new
+disk-serving HTTP route (keeps the deliberate VFS-only security posture,
+`bd-teh4hbli`; avoids a single-file↔project mechanism divergence). Mirror the
+existing `resource_files` injection pattern (resolved in the preview layer,
+injected via `HubConfig`, synced by `reconcile_files_with_index`).
+
+## Work items
+
+- [x] **A. quarto-core — extract referenced asset URLs.** `transforms::
+      collect_referenced_asset_urls(blocks) -> Vec<String>` (reuses the
+      `ResourceCollectorTransform` traversal via empty anchors, so nested images
+      in lists/Divs/figures/tables are found; external/absolute URLs dropped).
+      Test: `collect_referenced_asset_urls_returns_relative_images_only`.
+- [x] **B. quarto-preview — resolve to on-disk siblings.**
+      `config::resolve_single_file_assets(root, rel, runtime)`: parse deck via
+      `pampa::readers::qmd::read`, collect URLs, keep relative binary assets that
+      exist and canonicalize **under** `root` (no `../` escape). Returns
+      root-relative paths. Tests: `single_file_assets_resolves_referenced_image_
+      siblings_only`, `single_file_assets_rejects_parent_escape`.
+- [x] **C. config plumbing.** Resolved in `build_hub_config` (quarto-preview has
+      the parser) → new `HubConfig.single_file_assets`. No `PreviewConfig` field
+      (8 literal sites) — resolved at the mapping point instead.
+- [x] **D. quarto-hub — sync them.** `ProjectFiles::with_binary_files(...)`; the
+      single-file branch in `context.rs` appends `config.single_file_assets` to
+      `binary_files`, so `reconcile_files_with_index`'s binary loop syncs them.
+      Test: `test_single_file_with_binary_files_adds_referenced_assets`.
+- [x] **E. E2E.** `q2 preview page.qmd` (no `_quarto.yml`) with sibling
+      `./sibling-image.png`: before = broken (`naturalWidth 0`, raw HTTP url →
+      SPA index.html); after = **blob URL, `naturalWidth 320`** — identical to
+      project mode. Screenshot showed the rendered Quarto logo.
+
+## Known v1 limitations (document, don't fix now)
+
+- **Load-time only.** Assets are resolved when the session starts. An image
+  reference *added while editing* won't sync until reload (project mode catches
+  it via the dir watcher). Extending the single-file watch loop to re-extract on
+  deck change is a follow-up.
+- **Direct references only** (not transitively through `{{< include >}}`).
+- **Images only** for v1 (the dominant case); other binary refs (e.g. linked
+  PDFs/video) can extend `collect_referenced_asset_urls` later.
+- **Non-conventional brand paths** (`brand: ../shared/foo.yml`) remain
+  project-only (bd-ggvq1j68).

crates/quarto-core/src/transforms/mod.rs

@@ -107,7 +107,7 @@ pub use navbar_render::NavbarRenderTransform;
 pub use page_nav_generate::PageNavGenerateTransform;
 pub use page_nav_render::PageNavRenderTransform;
 pub use proof::ProofSugarTransform;
-pub use resource_collector::ResourceCollectorTransform;
+pub use resource_collector::{ResourceCollectorTransform, collect_referenced_asset_urls};
 pub use sectionize::SectionizeTransform;
 pub use shortcode_resolve::{ShortcodeResolveTransform, extract_shortcode_paths};
 pub use sidebar_generate::SidebarGenerateTransform;

crates/quarto-core/src/transforms/resource_collector.rs

@@ -424,6 +424,35 @@ impl<'a> ResourceVisitor<'a> {
     }
 }
 
+/// Collect the relative URLs of on-disk assets a document references
+/// (currently `Image` targets), in document order and deduplicated.
+///
+/// External (`http://`, `https://`, `//`, `data:`) and filesystem-root
+/// (`/...`) URLs are skipped — only document-relative paths the caller can
+/// resolve against the source directory are returned. This reuses the same
+/// AST traversal as [`ResourceCollectorTransform`] (so nested images — in
+/// lists, `Div`s, figures, tables — are found) but without the copy-intent /
+/// resolver machinery.
+///
+/// `q2 preview`'s single-file mode uses this to sync exactly the assets a deck
+/// references into the VFS, without walking the deck's directory (which the
+/// `bd-tnm3k` safety property forbids). See bd-kpuweafo.
+pub fn collect_referenced_asset_urls(blocks: &[Block]) -> Vec<String> {
+    // Empty source/dest anchors: `collect_resource` does the external/absolute
+    // filtering and dedup we want, and stores `Path::new("").join(url)` (== the
+    // relative URL) as the copy source. We read those back as the raw URLs.
+    let anchor = Path::new("");
+    let mut visitor = ResourceVisitor::new(anchor, anchor);
+    for block in blocks {
+        visitor.visit_block(block);
+    }
+    visitor
+        .copies
+        .into_iter()
+        .map(|(src, _dest)| src.to_string_lossy().into_owned())
+        .collect()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -477,6 +506,58 @@ mod tests {
         )
     }
 
+    /// Build an `Image` inline with the given target URL.
+    fn image(url: &str) -> Inline {
+        Inline::Image(Image {
+            attr: (String::new(), vec![], hashlink::LinkedHashMap::new()),
+            content: vec![],
+            target: (url.to_string(), String::new()),
+            source_info: dummy_source_info(),
+            attr_source: AttrSourceInfo::empty(),
+            target_source: TargetSourceInfo::empty(),
+        })
+    }
+
+    fn para(inlines: Vec<Inline>) -> Block {
+        Block::Paragraph(Paragraph {
+            content: inlines,
+            source_info: dummy_source_info(),
+        })
+    }
+
+    /// bd-kpuweafo: `collect_referenced_asset_urls` returns document-relative
+    /// image URLs (including nested ones), in order, deduped; external and
+    /// absolute URLs are dropped. The single-file preview uses this to sync
+    /// exactly the assets a deck references into the VFS.
+    #[test]
+    fn collect_referenced_asset_urls_returns_relative_images_only() {
+        let blocks = vec![
+            para(vec![image("./sibling-image.png")]),
+            // Nested in a bullet list — must still be found.
+            Block::BulletList(quarto_pandoc_types::block::BulletList {
+                content: vec![vec![para(vec![image("sub/diagram.svg")])]],
+                source_info: dummy_source_info(),
+            }),
+            // External / absolute / duplicate — all dropped or deduped.
+            para(vec![
+                image("https://example.com/remote.png"),
+                image("/etc/passwd"),
+                image("data:image/png;base64,AAAA"),
+                image("./sibling-image.png"),
+            ]),
+        ];
+
+        let urls = collect_referenced_asset_urls(&blocks);
+        assert_eq!(
+            urls,
+            vec![
+                "./sibling-image.png".to_string(),
+                "sub/diagram.svg".to_string()
+            ],
+            "only relative image URLs, in order, deduped; external/absolute dropped"
+        );
+    }
+
     /// R5 (bd-cfl67): the collector pushes a `(src, dest)` pair
     /// into `ctx.resource_copies`, where `src` is the source-tree
     /// path the qmd points at and `dest` is the matching position

crates/quarto-hub/src/context.rs

@@ -83,6 +83,18 @@ pub struct HubConfig {
     /// Empty for the standalone `quarto hub` server.
     pub resource_files: Vec<PathBuf>,
 
+    /// Single-file mode (bd-kpuweafo): binary **asset** siblings the deck
+    /// references (project-root-relative paths), e.g. `![](./img.png)`.
+    ///
+    /// Single-file mode does not walk the directory (the `bd-tnm3k` safety
+    /// property), so the bare `single_file` discovery never finds these.
+    /// `q2 preview` resolves them upstream in `quarto-preview` (which has the
+    /// qmd parser) via `config::resolve_single_file_assets` and injects them
+    /// here so they reach [`ProjectFiles::with_binary_files`] and flow through
+    /// the same automerge → VFS → blob-URL path project mode uses. Empty for
+    /// project mode (the dir walk finds binaries) and the `quarto hub` server.
+    pub single_file_assets: Vec<PathBuf>,
+
     /// OAuth2 auth configuration. None = auth disabled.
     pub auth_config: Option<AuthConfig>,
 
@@ -121,6 +133,7 @@ impl Default for HubConfig {
             watch_filter: WatchFilter::default(),
             single_file: None,
             resource_files: Vec::new(),
+            single_file_assets: Vec::new(),
             auth_config: None,
             allow_insecure_auth: false,
             register_root_ws: true,
@@ -213,9 +226,12 @@ impl HubContext {
                 // that references `brand: _brand.yml` needs that sibling in the
                 // VFS. Pick up the conventionally-named brand file next to the
                 // target without walking the directory (stays narrow).
-                Some(rel) => {
-                    ProjectFiles::single_file(rel.clone()).with_config_siblings(project_root, rel)
-                }
+                Some(rel) => ProjectFiles::single_file(rel.clone())
+                    .with_config_siblings(project_root, rel)
+                    // bd-kpuweafo: sync the sibling images the deck references
+                    // (resolved upstream by quarto-preview) so they reach the
+                    // VFS like project mode, without walking the directory.
+                    .with_binary_files(config.single_file_assets.clone()),
                 // bd-kjrpya2d: the bare walk can't see resources-scoped
                 // `.html` (it falls through every category), so the
                 // caller-resolved set is injected here to ride the text

crates/quarto-hub/src/discovery.rs

@@ -188,6 +188,18 @@ impl ProjectFiles {
         self
     }
 
+    /// Attach binary asset files (project-root-relative) to be synced into the
+    /// VFS, in addition to whatever discovery found. Used by single-file mode
+    /// (bd-kpuweafo) to add the sibling images a deck references — resolved
+    /// upstream in `quarto-preview` — without walking the directory. Sorted +
+    /// deduped against any already-present binaries for deterministic ordering.
+    pub fn with_binary_files(mut self, mut binary_files: Vec<PathBuf>) -> Self {
+        self.binary_files.append(&mut binary_files);
+        self.binary_files.sort();
+        self.binary_files.dedup();
+        self
+    }
+
     /// Attach resources-scoped `.html` files (resolved by the caller
     /// from `project.resources:`) to be synced into the VFS as text.
     /// Deduplicates and sorts for deterministic ordering. See
@@ -393,6 +405,25 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_single_file_with_binary_files_adds_referenced_assets() {
+        // bd-kpuweafo: single-file mode syncs the deck's referenced image
+        // siblings (resolved upstream) via `with_binary_files`, keeping the
+        // qmd as the only text file (no directory walk).
+        let files = ProjectFiles::single_file(PathBuf::from("deck.qmd")).with_binary_files(vec![
+            PathBuf::from("img.png"),
+            PathBuf::from("sub/diagram.svg"),
+        ]);
+
+        assert_eq!(files.qmd_files, vec![PathBuf::from("deck.qmd")]);
+        let mut bins = files.binary_files.clone();
+        bins.sort();
+        assert_eq!(
+            bins,
+            vec![PathBuf::from("img.png"), PathBuf::from("sub/diagram.svg")]
+        );
+    }
+
     #[test]
     fn test_single_file_no_brand_sibling_stays_narrow() {
         // Without a `_brand.yml` next to the deck, single-file mode must NOT

crates/quarto-hub/src/main.rs

@@ -222,6 +222,8 @@ async fn main() -> anyhow::Result<()> {
         // Standalone `hub` server: resources-scoped `.html` sync is a
         // preview-only concern (bd-kjrpya2d).
         resource_files: Vec::new(),
+        // Single-file asset sync is a preview-only concern (bd-kpuweafo).
+        single_file_assets: Vec::new(),
         auth_config,
         allow_insecure_auth: args.allow_insecure_auth,
         register_root_ws: true,

crates/quarto-hub/tests/auth_bearer.rs

@@ -361,6 +361,7 @@ impl TestHub {
             watch_filter: Default::default(),
             single_file: None,
             resource_files: Vec::new(),
+            single_file_assets: Vec::new(),
             auth_config: Some(auth_config),
             allow_insecure_auth: true,
             register_root_ws: false,
@@ -481,6 +482,7 @@ async fn allowlist_setup() -> &'static (MockOidcProvider, TestHub) {
                 watch_filter: Default::default(),
                 single_file: None,
                 resource_files: Vec::new(),
+                single_file_assets: Vec::new(),
                 auth_config: Some(auth_config),
                 allow_insecure_auth: true,
                 register_root_ws: false,
@@ -945,6 +947,7 @@ async fn secure_setup() -> &'static (MockOidcProvider, TestHub) {
                 watch_filter: Default::default(),
                 single_file: None,
                 resource_files: Vec::new(),
+                single_file_assets: Vec::new(),
                 auth_config: Some(auth_config),
                 allow_insecure_auth: false, // <-- the key difference
                 register_root_ws: false,