From ee45aa9726d1adbad56c123bde52341f8b903b44 Mon Sep 17 00:00:00 2001
From: Angus Bezzina <37071175+angusbezzina@users.noreply.github.com>
Date: Fri, 28 Aug 2026 15:40:13 -0500
Subject: [PATCH 01/10] A text= click lands on the thing you would have clicked
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

scripts/test-e2e.sh has been exiting 1 on two Suite 2 assertions. Neither was
the app and neither was quite the test.

__resolve matches every element whose trimmed text equals the target, which
for one sidebar row is the <li>, the <button> inside it, and the <span> inside
that. Click took els[0] — document order — so it clicked the <li>, an element
with no handler. The interaction reported ok and the document never moved.
That is every text= click in the tree, not just this suite's.

It also explains why only one of the two navigation cases failed. Neither
click was working; the second case happened to assert the heading of a file
that was already open, so it passed vacuously. Fixing the targeting is what
makes it a real assertion.

Click now prefers the innermost INTERACTIVE match, falling back to the
innermost match of any kind, whose click still bubbles to whatever handler sits
above it.

The breadcrumb case asserted a control the native app does not have.
web/src/lib/PathBreadcrumb.svelte is imported by nothing — only a stale rule in
the hosted stylesheet mentions it — and a live window reports zero matches for
[class*=breadcrumb], nav[aria-label] and [data-slot*=breadcrumb]. The selector
could only ever find nothing, so the case asserted the absence of a control
rather than any behaviour. It now asserts what it was reaching for, against
something that exists: the sidebar marks the open row data-active="true" and
carries its full path.

Both navigations now wait for the heading to BECOME what they expect. Waiting
for `h1` cannot do that — the previous document's h1 already satisfies it, so
the wait returned instantly and the fixed sleep after it raced the navigation.

Fixes attn-537h.
---
 scripts/test-e2e.sh | 79 ++++++++++++++++++++++++++++++---------------
 src/daemon.rs       | 31 +++++++++++++++++-
 2 files changed, 83 insertions(+), 27 deletions(-)

diff --git a/scripts/test-e2e.sh b/scripts/test-e2e.sh
index 4db1029a..e82667a3 100755
--- a/scripts/test-e2e.sh
+++ b/scripts/test-e2e.sh
@@ -77,6 +77,35 @@ assert_truthy() {
     fi
 }
 
+# Poll `--eval` until it returns something truthy, or give up after ~4s.
+# Defined up here rather than beside its first use so every suite can reach it.
+poll_eval() {
+    local js="$1"
+    local tries=0
+    local out=""
+    while [ "$tries" -lt 40 ]; do
+        out=$("$ATTN" --eval "$js" 2>/dev/null || echo "")
+        case "$out" in
+            ''|null|'""'|false|0) ;;
+            *) echo "$out"; return 0 ;;
+        esac
+        sleep 0.1
+        tries=$((tries + 1))
+    done
+    echo "$out"
+}
+
+# Wait for the document heading to actually BECOME `$1`.
+#
+# `--wait-for h1` cannot do this: an h1 from the previously-open document
+# already satisfies it, so it returns instantly and whatever fixed sleep
+# follows is racing the navigation. Losing that race made "Navigate to
+# basic.md" read the previous file's heading (attn-537h).
+wait_for_heading() {
+    local expected="$1"
+    poll_eval "(document.querySelector('h1')?.textContent || '').includes('$expected') ? 'yes' : null" >/dev/null
+}
+
 screenshot() {
     local name="$1"
     local path
@@ -233,10 +262,8 @@ echo "--- Navigate Between Files ---"
 # Click basic.md in the sidebar
 "$ATTN" --click 'text=basic.md'
 
-# Wait for navigation to complete — h1 should contain "Project Status"
-"$ATTN" --wait-for 'h1' --timeout 5000 >/dev/null 2>&1
-# Give rendering a moment to settle after navigation
-sleep 0.3
+# Wait for the heading to become basic.md's, not merely for AN h1 to exist.
+wait_for_heading "Project Status"
 result=$("$ATTN" --query 'h1' | jq -r '.elements[0].text' 2>/dev/null || echo "")
 assert_contains "Navigate to basic.md" "$result" "Project Status"
 screenshot "05-navigate-basic"
@@ -255,15 +282,31 @@ sleep 0.3
 # and the row text contains the filename — `text=` matches text content.
 "$ATTN" --click 'text=child.md'
 
-# Wait for navigation to complete
-"$ATTN" --wait-for 'h1' --timeout 5000 >/dev/null 2>&1
-sleep 0.3
+wait_for_heading "Nested Document"
 result=$("$ATTN" --query 'h1' | jq -r '.elements[0].text' 2>/dev/null || echo "")
 assert_contains "Navigate to nested child.md" "$result" "Nested Document"
 
-# Verify breadcrumb shows nested path
-result=$("$ATTN" --query '[class*="breadcrumb"], nav[aria-label]' | jq -r '.elements[0].text // ""' 2>/dev/null || echo "")
-assert_contains "Breadcrumb shows nested path" "$result" "child.md"
+# The nested file is the one the app considers open.
+#
+# This replaces an assertion on a breadcrumb. The native app has no breadcrumb
+# and has not had one for some time: `web/src/lib/PathBreadcrumb.svelte` is
+# imported by nothing, and a live window reports zero matches for
+# `[class*=breadcrumb]`, `nav[aria-label]` and `[data-slot*=breadcrumb]`. The
+# old selector could only ever find nothing, so the case was asserting the
+# absence of a control rather than any behaviour (attn-537h).
+#
+# What it was reaching for — "the app is showing the nested file" — is real and
+# observable: the sidebar marks the open row `data-active="true"` and carries
+# its full path in `data-path`.
+# `--eval` hands back a JSON-encoded string, which escapes the separators —
+# the path arrives as `...\/nested\/child.md`, so a bare `nested/child.md`
+# never appears in it. Strip the escaping rather than assert on the escaped
+# spelling, so the message still shows a readable path when this fails.
+result=$(poll_eval "(() => {
+    const row = document.querySelector('[data-path][data-active=\"true\"]');
+    return row ? row.getAttribute('data-path') : null;
+})()" | tr -d '\\')
+assert_contains "Nested file is the active sidebar row" "$result" "nested/child.md"
 screenshot "06-nested-file"
 
 # ===================================================================
@@ -276,22 +319,6 @@ echo "=== Test Suite 3: Relative Images (images.md) ==="
 # Poll a synchronous eval until it stops returning `null`/empty. `--eval` hands
 # back whatever the expression evaluates to, JSON-encoded, and does NOT await a
 # Promise — so waiting has to happen out here, not in the page.
-poll_eval() {
-    local js="$1"
-    local tries=0
-    local out=""
-    while [ "$tries" -lt 40 ]; do
-        out=$("$ATTN" --eval "$js" 2>/dev/null || echo "")
-        case "$out" in
-            ''|null|'""'|false|0) ;;
-            *) echo "$out"; return 0 ;;
-        esac
-        sleep 0.1
-        tries=$((tries + 1))
-    done
-    echo "$out"
-}
-
 start_daemon "$FIXTURES/images.md"
 
 # Single-file mode, so directory ordering in tests/fixtures/ is irrelevant here.
diff --git a/src/daemon.rs b/src/daemon.rs
index eb089c37..2287e9dc 100644
--- a/src/daemon.rs
+++ b/src/daemon.rs
@@ -1361,6 +1361,35 @@ function __resolve(sel) {
     }
     return Array.from(document.querySelectorAll(sel));
 }
+
+// Which of several `text=` matches should a CLICK land on.
+//
+// A text match is satisfied by every element whose trimmed text equals the
+// target, which for one sidebar row is the <li>, the <button> inside it, and
+// the <span> inside that. Taking the first in document order takes the <li> —
+// an element with no click handler — so the click reported success and nothing
+// happened. That is how "Navigate to basic.md" failed while its sibling case
+// passed vacuously: the document had not moved for either, and the sibling
+// happened to already be open (attn-537h).
+//
+// Prefer the innermost INTERACTIVE match, since that is the thing a person
+// would have clicked. Fall back to the innermost match of any kind, whose
+// click still bubbles to whatever handler is above it.
+function __best(els) {
+    if (els.length < 2) return els[0];
+    var interactive = els.filter(function (el) {
+        return el.matches('button, a, [role=button], input, select, textarea, label, [data-sidebar="menu-button"]');
+    });
+    var pool = interactive.length > 0 ? interactive : els;
+    // Innermost = the one containing no other candidate.
+    for (var i = 0; i < pool.length; i++) {
+        var containsAnother = pool.some(function (other) {
+            return other !== pool[i] && pool[i].contains(other);
+        });
+        if (!containsAnother) return pool[i];
+    }
+    return pool[0];
+}
 "#;
 
     match action {
@@ -1371,7 +1400,7 @@ function __resolve(sel) {
 {resolve_fn}
 var els = __resolve({sel_json});
 if (els.length === 0) return JSON.stringify({{status:'not_found',selector:{sel_json}}});
-els[0].click();
+__best(els).click();
 return JSON.stringify({{status:'ok'}});
 }})()"#,
             )

From 8991adb921c11b4864b2f9885b8c41bf27be5038 Mon Sep 17 00:00:00 2001
From: Angus Bezzina <37071175+angusbezzina@users.noreply.github.com>
Date: Fri, 28 Aug 2026 15:44:25 -0500
Subject: [PATCH 02/10] A share without a curated file list still carries its
 images
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

attn-udu8 publishes the images a document references, but only for a share
carrying an explicit selection. Without one, selected_share_wire_path returned
None, publish_asset_snapshot failed for want of a portable name, and every
image was scanned, approved, and then dropped with a log line. The reviewer
saw placeholder cards and no frontend change could have helped — the bytes
were never sent.

That is the CLI path: `attn review share <path>`, and the legacy share(path)
wrapper that passes an empty selection. It stayed invisible because the native
Share dialog always sends a selection, so every live verification of attn-udu8
went through the one path that worked.

A share with no curated list still has a root, and every file it publishes
still needs a portable name. Wire paths now derive from that root — the shared
directory, or a shared file's own parent — with membership of the curated list
authorising the name when there is one, and containment in the root when there
is not. Nothing outside the root becomes nameable either way.

Verified against a live relay: `attn review share tests/fixtures/images.md`
publishes all three assets where it previously published none.

Fixes attn-x2zq.
---
 src/review/bootstrap.rs | 107 ++++++++++++++++++++++++++++++++++------
 1 file changed, 92 insertions(+), 15 deletions(-)

diff --git a/src/review/bootstrap.rs b/src/review/bootstrap.rs
index 3d29e2e0..5152bc77 100644
--- a/src/review/bootstrap.rs
+++ b/src/review/bootstrap.rs
@@ -4703,27 +4703,46 @@ fn selected_share_wire_path(
     let Some(record) = all.get(room_id.as_str()) else {
         return Ok(None);
     };
-    if record.selected_paths.is_empty() {
-        return Ok(None);
-    }
-    let canonical_root = std::path::Path::new(&record.path)
-        .canonicalize()
-        .map_err(|error| {
-            BootstrapError::Store(format!(
-                "canonicalize selected share root {}: {error}",
-                record.path
-            ))
-        })?;
+    // A share with no curated file list still has a root, and every file it
+    // publishes still needs a portable name (attn-x2zq).
+    //
+    // Returning None here meant `attn review share <path>` — and the legacy
+    // share(path) wrapper, which passes an empty selection — produced a share
+    // whose images could not travel at all: publish_asset_snapshot fails
+    // without a wire path, so the bytes were scanned, approved, and then
+    // dropped with only a per-image log line. It was invisible in testing
+    // because the native Share dialog always sends a selection.
+    //
+    // The root is the shared directory, or a shared file's own parent. Files
+    // outside it are still refused, by normalized_relative_share_path below.
+    let record_root = std::path::Path::new(&record.path);
+    let root_for_wire = if record.is_dir {
+        record_root.to_path_buf()
+    } else {
+        record_root
+            .parent()
+            .map(std::path::Path::to_path_buf)
+            .unwrap_or_else(|| record_root.to_path_buf())
+    };
+    let canonical_root = root_for_wire.canonicalize().map_err(|error| {
+        BootstrapError::Store(format!(
+            "canonicalize selected share root {}: {error}",
+            root_for_wire.display()
+        ))
+    })?;
     let canonical_path = path.canonicalize().map_err(|error| {
         BootstrapError::Store(format!(
             "canonicalize shared file {}: {error}",
             path.display()
         ))
     })?;
-    if !record
-        .selected_paths
-        .iter()
-        .any(|selected| std::path::Path::new(selected) == canonical_path)
+    // With a curated list, membership of it is what authorises a wire path.
+    // Without one, containment in the share root is.
+    if !record.selected_paths.is_empty()
+        && !record
+            .selected_paths
+            .iter()
+            .any(|selected| std::path::Path::new(selected) == canonical_path)
     {
         return Ok(None);
     }
@@ -5727,6 +5746,64 @@ mod tests {
         }
     }
 
+    #[test]
+    fn a_share_without_a_curated_list_still_mints_wire_paths() {
+        // attn-x2zq. Returning None here meant `attn review share <path>` and
+        // the legacy share(path) wrapper published a share whose images could
+        // not travel: publish_asset_snapshot needs a portable name, so the
+        // bytes were scanned, approved, and then dropped. Invisible in testing
+        // because the native Share dialog always sends a selection.
+        let root = TempDir::new().expect("tmp");
+        let store_root = root.path().join("store");
+        std::fs::create_dir_all(&store_root).expect("store dir");
+        let docs = root.path().join("docs");
+        std::fs::create_dir_all(docs.join("nested")).expect("docs dir");
+        std::fs::write(docs.join("notes.md"), b"# hi").expect("doc");
+        std::fs::write(docs.join("chart.svg"), b"<svg/>").expect("asset");
+        std::fs::write(docs.join("nested/diagram.png"), b"\x89PNG").expect("nested asset");
+
+        let room: RoomId =
+            serde_json::from_value(serde_json::Value::String("room-no-selection".into())).unwrap();
+
+        // A FOLDER share: the root is the folder itself.
+        record_local_share(&store_root, &room, &docs, true).expect("record dir share");
+        assert_eq!(
+            selected_share_wire_path(&store_root, &room, &docs.join("chart.svg"))
+                .expect("wire path")
+                .as_deref(),
+            Some("chart.svg"),
+            "an asset beside the document gets a portable name"
+        );
+        assert_eq!(
+            selected_share_wire_path(&store_root, &room, &docs.join("nested/diagram.png"))
+                .expect("wire path")
+                .as_deref(),
+            Some("nested/diagram.png"),
+            "and keeps its subdirectory"
+        );
+
+        // A SINGLE-FILE share: the root is that file's own parent, so its
+        // siblings are still nameable.
+        let file_room: RoomId =
+            serde_json::from_value(serde_json::Value::String("room-single-file".into())).unwrap();
+        record_local_share(&store_root, &file_room, &docs.join("notes.md"), false)
+            .expect("record file share");
+        assert_eq!(
+            selected_share_wire_path(&store_root, &file_room, &docs.join("chart.svg"))
+                .expect("wire path")
+                .as_deref(),
+            Some("chart.svg"),
+            "a single-file share roots at the file's directory"
+        );
+
+        // Containment still holds: nothing above the root is nameable.
+        std::fs::write(root.path().join("outside.svg"), b"<svg/>").expect("outside");
+        assert!(
+            selected_share_wire_path(&store_root, &room, &root.path().join("outside.svg")).is_err(),
+            "a file outside the share root has no wire path"
+        );
+    }
+
     #[test]
     fn v3_fragment_without_an_owner_key_still_parses() {
         // Backward skew: an invite minted before attn-lb7p has no owner key.

From 38d9a7e6710a98a4188c632416b266e4202b84d8 Mon Sep 17 00:00:00 2001
From: Angus Bezzina <37071175+angusbezzina@users.noreply.github.com>
Date: Fri, 28 Aug 2026 15:50:02 -0500
Subject: [PATCH 03/10] Every snapshot has to say who published it, not just
 the manifest
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

attn-lb7p made workspace manifests prove authorship. Doing it exposed that the
manifest was the only place in the snapshot path where authorship was checked
at all.

Every other snapshot — the documents a reviewer reads, and the image assets
attn-udu8 added — was accepted on a signature from ANY device in the room
directory, because that is all InboundPipeline establishes. A reviewer holding
a comment- or suggest-tier grant is such a device. Nothing stopped one minting
a SnapshotCreated for an arbitrary fileId and having every other reviewer
render it as the owner's document, or as an image inside it.

Snapshots are structurally owner-published: both republish paths go through
find_room_for_path, which needs a local share record that only the sharing
machine has. A reviewer cannot legitimately publish one, so requiring the
owner's signature refuses exactly the events that had no business existing.
Establishing that first is why this is safe — a wrong tightening here does not
degrade an image, it stops the shared document rendering.

The pinned-key verification is now one helper shared with the manifest path
rather than two copies of the same crypto. Rooms with no pinned key — v2, and
v3 rooms joined before invites carried one — keep behaving exactly as they did:
they have no way to establish authorship and must not lose their documents to a
check they cannot satisfy.

Verified live: a real share still renders all four images with zero hydration
rejections. The two forgery tests are mutation-checked — neutering the check
kills them and nothing else.

Fixes attn-1n67.
---
 src/review/manager.rs | 219 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 196 insertions(+), 23 deletions(-)

diff --git a/src/review/manager.rs b/src/review/manager.rs
index fe93bc26..70a4c135 100644
--- a/src/review/manager.rs
+++ b/src/review/manager.rs
@@ -4267,6 +4267,49 @@ fn asset_snapshot_update(
     })
 }
 
+/// Whether a room could establish who signed a snapshot.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum OwnerSignature {
+    /// The room pins an owner key and this event verified against it.
+    Verified,
+    /// No key is pinned — a v2 room, or a v3 room joined before invites
+    /// carried one. The caller decides what to do instead.
+    NoPinnedKey,
+}
+
+/// Verify that the room owner signed `event`, against the key pinned at join
+/// (attn-lb7p, generalised by attn-1n67).
+///
+/// A full `verify_event` rather than a `signing_key_id` comparison: replay
+/// re-verifies nothing of its own, so a check that merely trusted what the
+/// live import recorded would evaporate on restart.
+fn verify_snapshot_owner_signature(
+    store: &crate::review::store::ReviewStore,
+    room_id: &RoomId,
+    event: &crate::review::model::ReviewEvent,
+) -> Result<OwnerSignature, String> {
+    use base64::Engine as _;
+
+    let Some(encoded) = crate::review::bootstrap::load_room_access_v3(store.root(), room_id)
+        .map_err(|err| format!("load room access for snapshot authorship: {err}"))?
+        .and_then(|access| access.owner_public_signing_key)
+    else {
+        return Ok(OwnerSignature::NoPinnedKey);
+    };
+    let bytes = base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(encoded.as_bytes())
+        .map_err(|err| format!("pinned owner key base64url decode: {err}"))?;
+    let bytes: [u8; 32] = bytes
+        .as_slice()
+        .try_into()
+        .map_err(|_| "pinned owner key must decode to 32 bytes".to_string())?;
+    let owner = crate::review::crypto::signing::DeviceVerifyingKey::from_bytes(&bytes)
+        .map_err(|err| format!("pinned owner key: {err}"))?;
+    crate::review::crypto::signing::verify_event(&owner, &event.meta, &event.body, &event.auth)
+        .map_err(|err| format!("not signed by the room owner: {err}"))?;
+    Ok(OwnerSignature::Verified)
+}
+
 fn rehydrate_snapshot_event(
     store: &crate::review::store::ReviewStore,
     room_id: &RoomId,
@@ -4292,6 +4335,34 @@ fn rehydrate_snapshot_event(
             return;
         }
     };
+    // Who published this? (attn-1n67)
+    //
+    // Until now the manifest was the ONLY snapshot whose authorship was ever
+    // checked. Every other one — the documents a reviewer reads, and the image
+    // assets attn-udu8 added — was accepted on a signature from ANY device in
+    // the room directory, because that is all InboundPipeline establishes. A
+    // reviewer holding a comment- or suggest-tier grant is such a device, so
+    // nothing stopped one minting a SnapshotCreated for an arbitrary fileId
+    // and having every other reviewer render it as the owner's document.
+    //
+    // Snapshots are structurally owner-published: both republish paths go
+    // through `find_room_for_path`, which needs a local share record that only
+    // the sharing machine has. So requiring the owner's signature refuses
+    // exactly the events that had no business existing.
+    if plaintext.doc_type != crate::review::model::DocType::WorkspaceManifest {
+        match verify_snapshot_owner_signature(store, room_id, event) {
+            Ok(OwnerSignature::Verified) => {}
+            // No pinned key: a v2 room, or a v3 room joined before invites
+            // carried one. Unchanged from before this check existed — those
+            // rooms have no way to establish authorship and must not lose
+            // their documents over it.
+            Ok(OwnerSignature::NoPinnedKey) => {}
+            Err(err) => {
+                tracing::warn!("snapshot hydration rejected: {err}");
+                return;
+            }
+        }
+    }
     if plaintext.doc_type == crate::review::model::DocType::WorkspaceManifest
         && let Err(err) = validate_workspace_manifest_binding(store, room_id, event, &plaintext)
     {
@@ -4453,34 +4524,14 @@ fn validate_workspace_manifest_binding(
     // whatever the import decided. That matters because replay
     // (`replay_room_to_webview`) re-verifies nothing of its own — an identity
     // check that only held on the live path would evaporate on restart.
-    let pinned_owner_key = crate::review::bootstrap::load_room_access_v3(store.root(), room_id)
-        .map_err(|err| format!("load room access for manifest authorship: {err}"))?
-        .and_then(|access| access.owner_public_signing_key);
-    match pinned_owner_key {
-        Some(encoded) => {
-            use base64::Engine as _;
-            let bytes = base64::engine::general_purpose::URL_SAFE_NO_PAD
-                .decode(encoded.as_bytes())
-                .map_err(|err| format!("pinned owner key base64url decode: {err}"))?;
-            let bytes: [u8; 32] = bytes
-                .as_slice()
-                .try_into()
-                .map_err(|_| "pinned owner key must decode to 32 bytes".to_string())?;
-            let owner = crate::review::crypto::signing::DeviceVerifyingKey::from_bytes(&bytes)
-                .map_err(|err| format!("pinned owner key: {err}"))?;
-            crate::review::crypto::signing::verify_event(
-                &owner,
-                &manifest_event.meta,
-                &manifest_event.body,
-                &manifest_event.auth,
-            )
-            .map_err(|err| format!("workspace manifest was not signed by the room owner: {err}"))?;
+    match verify_snapshot_owner_signature(store, room_id, manifest_event)? {
+        OwnerSignature::Verified => {
             // The synthetic FileId is deliberately NOT compared here. It is
             // the manifest's name — reviewers match snapshots to entries by
             // it — and a name a reviewer cannot compute, and could replay if
             // it could, is not a credential.
         }
-        None => {
+        OwnerSignature::NoPinnedKey => {
             // No pinned key: a v2 room, or a v3 room joined before the invite
             // carried one. Fall back to the original check, which still works
             // for the parties that can satisfy it (owners, v2 joiners) and
@@ -5531,6 +5582,128 @@ mod tests {
         )
     }
 
+    /// A store + room holding one persisted markdown snapshot, for the
+    /// authorship cases below. Deliberately NOT bound_manifest_case: that one
+    /// builds a manifest, and the point here is the ORDINARY document path
+    /// that had no authorship check at all (attn-1n67).
+    fn document_snapshot_case() -> (
+        TempDir,
+        ReviewStore,
+        RoomId,
+        crate::review::model::ReviewEvent,
+    ) {
+        use crate::review::crypto::ids::derive_room_id;
+        use crate::review::model::{DocType, SnapshotPlaintext};
+
+        let tmp = TempDir::new().expect("tempdir");
+        let store = ReviewStore::open_at(tmp.path().join("reviews")).expect("open store");
+        let room_id = derive_room_id(&[0x44; 32]);
+        let payload = SnapshotPlaintext {
+            doc_type: DocType::Markdown,
+            content: Some("# Shared\n\nHello.\n".to_string()),
+            anchor_index: None,
+            media_type: None,
+            encoding: None,
+            manifest: None,
+            annotation: None,
+        };
+        let event = persist_snapshot_event(
+            &store,
+            &room_id,
+            "document",
+            dummy_id("CQkJCQkJCQkJCQkJCQkJCQ"),
+            dummy_id("CgoKCgoKCgoKCgoKCgoKCg"),
+            "shared.md",
+            &payload,
+        );
+        assert!(
+            store
+                .append_event(&room_id, &event)
+                .expect("append document event")
+        );
+        (tmp, store, room_id, event)
+    }
+
+    #[test]
+    fn a_document_snapshot_signed_by_the_owner_hydrates() {
+        let (_tmp, store, room_id, mut event) = document_snapshot_case();
+        let owner = signing_key(0x11);
+        pin_owner_key(&store, &room_id, &owner);
+        sign_manifest_as(&mut event, &owner);
+        assert!(
+            hydrated(&store, &room_id, &mut event),
+            "the owner's own document must still render"
+        );
+    }
+
+    #[test]
+    fn a_document_snapshot_signed_by_a_reviewer_is_rejected() {
+        // The hole attn-1n67 closes. Before this, ANY device in the room
+        // directory could mint a SnapshotCreated for an arbitrary fileId and
+        // every other reviewer would render it as the owner's document — a
+        // valid signature from a registered participant was the whole check.
+        let (_tmp, store, room_id, mut event) = document_snapshot_case();
+        let owner = signing_key(0x11);
+        let reviewer = signing_key(0x22);
+        pin_owner_key(&store, &room_id, &owner);
+        sign_manifest_as(&mut event, &reviewer);
+        assert!(
+            !hydrated(&store, &room_id, &mut event),
+            "a document signed by a non-owner must not render"
+        );
+    }
+
+    #[test]
+    fn an_asset_snapshot_signed_by_a_reviewer_is_rejected() {
+        // Same hole, reached through the images attn-udu8 added: a forged
+        // asset would otherwise be rendered inside the owner's document.
+        use crate::review::crypto::ids::derive_room_id;
+        use crate::review::model::{DocType, SnapshotAssetEncoding, SnapshotPlaintext};
+
+        let tmp = TempDir::new().expect("tempdir");
+        let store = ReviewStore::open_at(tmp.path().join("reviews")).expect("open store");
+        let room_id = derive_room_id(&[0x55; 32]);
+        let payload = SnapshotPlaintext {
+            doc_type: DocType::Asset,
+            content: Some("PHN2Zy8-".to_string()),
+            anchor_index: None,
+            media_type: Some("image/svg+xml".to_string()),
+            encoding: Some(SnapshotAssetEncoding::Base64url),
+            manifest: None,
+            annotation: None,
+        };
+        let mut event = persist_snapshot_event(
+            &store,
+            &room_id,
+            "asset",
+            dummy_id("CwsLCwsLCwsLCwsLCwsLCw"),
+            dummy_id("DAwMDAwMDAwMDAwMDAwMDA"),
+            "chart.svg",
+            &payload,
+        );
+        assert!(store.append_event(&room_id, &event).expect("append asset"));
+        let owner = signing_key(0x11);
+        pin_owner_key(&store, &room_id, &owner);
+        sign_manifest_as(&mut event, &signing_key(0x22));
+        assert!(
+            !hydrated(&store, &room_id, &mut event),
+            "a forged asset must not render inside the owner's document"
+        );
+        drop(tmp);
+    }
+
+    #[test]
+    fn a_document_snapshot_in_a_room_with_no_pinned_key_is_unchanged() {
+        // v2 rooms and v3 rooms joined before invites carried an owner key
+        // have no way to establish authorship. They must keep working rather
+        // than lose their documents to a check they cannot satisfy.
+        let (_tmp, store, room_id, mut event) = document_snapshot_case();
+        assert!(
+            hydrated(&store, &room_id, &mut event),
+            "a room with no pinned key must behave as it did before"
+        );
+    }
+
     #[test]
     fn asset_snapshot_update_forwards_only_authenticated_assets() {
         use crate::review::model::{DocType, ReviewEventBody, SnapshotAssetEncoding};

From 4447f632aa073937f22ba8429f567fbe6c753395 Mon Sep 17 00:00:00 2001
From: Angus Bezzina <37071175+angusbezzina@users.noreply.github.com>
Date: Tue, 1 Sep 2026 20:58:46 -0500
Subject: [PATCH 04/10] Render document images in hosted shares

---
 src/review/assets.rs                          |   5 +-
 src/review/model.rs                           |  58 +++++-
 web/src/BrowserReviewApp.svelte               |  13 ++
 web/src/hosted/app/EditorShell.svelte         |  89 ++++++++
 web/src/lib/HtmlViewer.svelte                 |  12 +-
 web/src/lib/review/asset-resolution.test.ts   |  16 ++
 web/src/lib/review/asset-resolution.ts        |  13 +-
 .../lib/review/browser-asset-registry.test.ts |  77 +++++++
 web/src/lib/review/browser-asset-registry.ts  | 196 ++++++++++++++++++
 web/src/lib/review/browser-session.test.ts    |   6 +-
 web/src/lib/review/browser-session.ts         |  21 +-
 web/src/lib/review/browser-share-owner.ts     |   4 +-
 .../review/browser-share-production.test.ts   |  26 ++-
 .../lib/review/browser-share-production.ts    | 125 +++++++++--
 web/src/lib/review/browser-share-resolver.ts  |   8 +-
 .../review/browser-workspace-manifest.test.ts |  13 +-
 .../lib/review/browser-workspace-manifest.ts  |  10 +-
 .../review/browser-workspace-sharing.test.ts  |  26 +++
 .../lib/review/browser-workspace-sharing.ts   | 148 +++++++++++--
 .../lib/review/document-image-sources.test.ts |  13 ++
 web/src/lib/review/document-image-sources.ts  |  39 ++++
 web/src/lib/review/html-shared-assets.test.ts |  20 ++
 web/src/lib/review/html-shared-assets.ts      |  34 +++
 .../lib/review/shared-image-policy.test.ts    |  31 +++
 web/src/lib/review/shared-image-policy.ts     | 166 +++++++++++++++
 25 files changed, 1110 insertions(+), 59 deletions(-)
 create mode 100644 web/src/lib/review/browser-asset-registry.test.ts
 create mode 100644 web/src/lib/review/browser-asset-registry.ts
 create mode 100644 web/src/lib/review/document-image-sources.test.ts
 create mode 100644 web/src/lib/review/document-image-sources.ts
 create mode 100644 web/src/lib/review/html-shared-assets.test.ts
 create mode 100644 web/src/lib/review/html-shared-assets.ts
 create mode 100644 web/src/lib/review/shared-image-policy.test.ts
 create mode 100644 web/src/lib/review/shared-image-policy.ts

diff --git a/src/review/assets.rs b/src/review/assets.rs
index b57ad5dc..7cf152d4 100644
--- a/src/review/assets.rs
+++ b/src/review/assets.rs
@@ -35,6 +35,7 @@ const IMAGE_EXTENSIONS: &[(&str, &str)] = &[
     ("jpeg", "image/jpeg"),
     ("gif", "image/gif"),
     ("webp", "image/webp"),
+    ("avif", "image/avif"),
     ("bmp", "image/bmp"),
     ("ico", "image/x-icon"),
     ("svg", "image/svg+xml"),
@@ -42,11 +43,11 @@ const IMAGE_EXTENSIONS: &[(&str, &str)] = &[
 
 /// Largest single asset that may be published. Generous for a screenshot or a
 /// diagram, small enough that one pathological file cannot dominate a share.
-pub const MAX_ASSET_BYTES: u64 = 8 * 1024 * 1024;
+pub const MAX_ASSET_BYTES: u64 = 3 * 1024 * 1024;
 
 /// Ceiling on everything one document contributes. A snapshot is base64url'd
 /// into an encrypted envelope, so the wire cost is ~4/3 of this.
-pub const MAX_TOTAL_BYTES: u64 = 32 * 1024 * 1024;
+pub const MAX_TOTAL_BYTES: u64 = 16 * 1024 * 1024;
 
 /// Ceiling on how many assets one document contributes, so a generated file
 /// with a thousand thumbnails cannot stall a share.
diff --git a/src/review/model.rs b/src/review/model.rs
index 8b09886e..196f3c1c 100644
--- a/src/review/model.rs
+++ b/src/review/model.rs
@@ -511,9 +511,25 @@ impl WorkspaceSnapshotManifest {
                 "workspace manifest entries must not be empty",
             ));
         }
-        if self.scope == WorkspaceManifestScope::File && self.entries.len() != 1 {
+        // A file-scoped share contains one primary document plus its declared
+        // image dependencies. The document count, rather than total entries,
+        // remains the scope boundary so reviewers can resolve `./image.png`
+        // without turning a current-file share into a multi-document share.
+        if self.scope == WorkspaceManifestScope::File
+            && self
+                .entries
+                .iter()
+                .filter(|entry| {
+                    matches!(
+                        entry.kind,
+                        WorkspaceManifestEntryKind::Markdown | WorkspaceManifestEntryKind::Html
+                    )
+                })
+                .count()
+                != 1
+        {
             return Err(SnapshotValidationError::new(
-                "file-scoped manifest must contain exactly one entry",
+                "file-scoped manifest must contain exactly one document",
             ));
         }
 
@@ -1890,6 +1906,44 @@ mod tests {
         assert!(payload.validate().is_err());
     }
 
+    #[test]
+    fn file_scoped_manifest_allows_one_document_with_image_dependencies() {
+        let document = WorkspaceManifestEntry {
+            file_id: id("AQEBAQEBAQEBAQEBAQEBAQ"),
+            snapshot_id: id("AgICAgICAgICAgICAgICAg"),
+            path: "notes/readme.md".to_string(),
+            kind: WorkspaceManifestEntryKind::Markdown,
+            media_type: None,
+            byte_length: 7,
+            content_hash: content_hash(b"# note\n"),
+        };
+        let image = WorkspaceManifestEntry {
+            file_id: id("AwMDAwMDAwMDAwMDAwMDAw"),
+            snapshot_id: id("BAQEBAQEBAQEBAQEBAQEBA"),
+            path: "notes/chart.png".to_string(),
+            kind: WorkspaceManifestEntryKind::Asset,
+            media_type: Some("image/png".to_string()),
+            byte_length: 4,
+            content_hash: content_hash(&[0x89, 0x50, 0x4e, 0x47]),
+        };
+        let manifest = WorkspaceSnapshotManifest {
+            v: 1,
+            kind: WorkspaceManifestKind::AttnWorkspaceSnapshot,
+            scope: WorkspaceManifestScope::File,
+            // Canonical UTF-8 path ordering, not declaration ordering.
+            entries: vec![document, image],
+        };
+        assert!(
+            manifest.validate().is_err(),
+            "entries must remain canonically sorted"
+        );
+        let mut manifest = manifest;
+        manifest
+            .entries
+            .sort_by(|left, right| left.path.as_bytes().cmp(right.path.as_bytes()));
+        manifest.validate().unwrap();
+    }
+
     #[test]
     fn workspace_snapshot_corpus_pins_canonical_bytes_and_valid_payloads() {
         let corpus: Value = serde_json::from_str(include_str!(
diff --git a/web/src/BrowserReviewApp.svelte b/web/src/BrowserReviewApp.svelte
index 21f8ec0e..81513a11 100644
--- a/web/src/BrowserReviewApp.svelte
+++ b/web/src/BrowserReviewApp.svelte
@@ -60,6 +60,7 @@
   import SelectionToolbar from './lib/SelectionToolbar.svelte';
   import { deriveFileEntries, latestRenderableSnapshotId } from './lib/review/file-nav';
   import { reviewerStatusPresentation } from './lib/review/reviewer-status-model';
+  import { buildSharedAssetResolver } from './lib/review/asset-resolution';
   import { reviewStore } from './lib/review/store.svelte';
   import {
     applyReviewHoverHighlight,
@@ -643,6 +644,16 @@
       ? sessionState.snapshotDocType
       : 'markdown';
   });
+  // The session only puts verified asset metadata in reviewStore; the
+  // tab-local asset registry behind this resolver owns the decrypted bytes and
+  // their Blob URL lifetime. Read dependencies eagerly so a newly activated
+  // manifest rebuilds image NodeViews instead of leaving their fallback cards.
+  const resolveReviewAssetUrl = $derived.by(() => {
+    const snapshots = reviewStore.snapshots;
+    const roomId = sessionState.roomId;
+    const docWirePath = displayedSnapshot?.ownerDisplayPath;
+    return buildSharedAssetResolver(snapshots, roomId, docWirePath);
+  });
 
   $effect(() => {
     void sessionState.roomId;
@@ -1695,6 +1706,7 @@
                 <HtmlViewer
                   content={displayedContent ?? ''}
                   allowScripts={false}
+                  resolveAssetUrl={resolveReviewAssetUrl}
                   annotate={htmlAnnotatable}
                   annotationEvents={htmlAnnotationEvents}
                   onBridge={(bridge) => (htmlBridge = bridge)}
@@ -1703,6 +1715,7 @@
                 <Editor
                   markdown={reviewerCollabSeed?.markdown ?? displayedContent ?? ''}
                   editable={false}
+                  resolveAssetUrl={resolveReviewAssetUrl}
                   plugins={editorPlugins}
                   onReady={handleEditorReady}
                   collabClientId={reviewerAvailability.collabReady
diff --git a/web/src/hosted/app/EditorShell.svelte b/web/src/hosted/app/EditorShell.svelte
index 8929b00e..88b2ff30 100644
--- a/web/src/hosted/app/EditorShell.svelte
+++ b/web/src/hosted/app/EditorShell.svelte
@@ -56,6 +56,9 @@
   import { scrollViewToPos } from '../../lib/scroll-viewport';
   import { peerJumpPosition } from '../../lib/peer-strip-format';
   import { attachCollabPresenceSinks } from '../../lib/prosemirror/collab-presence-sinks';
+  import { sharedAssetPathFor } from '../../lib/review/asset-resolution';
+  import { htmlImageSources, markdownImageSources } from '../../lib/review/document-image-sources';
+  import { isSupportedSharedImageMediaType } from '../../lib/review/shared-image-policy';
   import LoadingLine from './LoadingLine.svelte';
   import HtmlViewer from '../../lib/HtmlViewer.svelte';
   import HtmlCommentComposer from '../../lib/HtmlCommentComposer.svelte';
@@ -373,6 +376,21 @@
   let assetInput = $state<HTMLInputElement | undefined>();
   let assetFolderInput = $state<HTMLInputElement | undefined>();
   let previewUrl = $state<string | null>(null);
+  // Blob URLs stay only in this tab's live component state. Neither the
+  // document nor the workspace store is rewritten: authored relative srcs
+  // remain the source of truth and a missing/rejected asset keeps the normal
+  // image fallback.
+  let localAssetUrls = $state<Record<string, string>>({});
+  let ownedAssetUrls = new Map<string, string>();
+  const resolveLocalAssetUrl = $derived.by(() => {
+    const documentPath = activeEntry?.path;
+    const urls = localAssetUrls;
+    if (!documentPath) return () => null;
+    return (src: string): string | null => {
+      const path = sharedAssetPathFor(documentPath, src);
+      return path === null ? null : urls[path] ?? null;
+    };
+  });
 
   /* The empty-canvas invitation (attn-mkmz.5). A brand-new workspace lands on a
      blank untitled.md, and the only standing offer to bring a real document in
@@ -815,6 +833,75 @@
     };
   });
 
+  // Resolve local image dependencies through OPFS into short-lived Blob URLs
+  // for the hosted owner surface. This is intentionally separate from the
+  // encrypted-share registry: local images are never staged as share
+  // snapshots, and share viewers never receive an OPFS-derived URL.
+  $effect(() => {
+    const entry = activeEntry;
+    const content = bodyText ?? displayText ?? '';
+    const liveAssets = new Map(workspace.entries.map((candidate) => [candidate.path, candidate]));
+    if (!entry || (entry.kind !== 'markdown' && entry.kind !== 'html')) {
+      for (const url of ownedAssetUrls.values()) URL.revokeObjectURL(url);
+      ownedAssetUrls = new Map();
+      localAssetUrls = {};
+      return;
+    }
+    const sources = entry.kind === 'markdown' ? markdownImageSources(content) : htmlImageSources(content);
+    const paths = new Set<string>();
+    for (const src of sources) {
+      const path = sharedAssetPathFor(entry.path, src);
+      const asset = path === null ? undefined : liveAssets.get(path);
+      if (path !== null && asset?.kind === 'asset' && isSupportedSharedImageMediaType(asset.mediaType)) {
+        paths.add(path);
+      }
+    }
+    let cancelled = false;
+    void (async () => {
+      const next = new Map<string, string>();
+      const created: string[] = [];
+      try {
+        for (const path of paths) {
+          const retained = ownedAssetUrls.get(path);
+          if (retained) {
+            next.set(path, retained);
+            continue;
+          }
+          const result = await service.readEntryBytes(workspace.id, path);
+          if (!result) continue;
+          const bytes = new Uint8Array(result.bytes);
+          try {
+            const mediaType = result.mediaType;
+            if (!isSupportedSharedImageMediaType(mediaType)) continue;
+            const blob = new Blob([bytes.buffer as ArrayBuffer], { type: mediaType });
+            const url = URL.createObjectURL(blob);
+            created.push(url);
+            next.set(path, url);
+          } finally {
+            bytes.fill(0);
+          }
+        }
+        if (cancelled) {
+          for (const url of created) URL.revokeObjectURL(url);
+          return;
+        }
+        for (const [path, url] of ownedAssetUrls) {
+          if (!next.has(path)) URL.revokeObjectURL(url);
+        }
+        ownedAssetUrls = next;
+        localAssetUrls = Object.fromEntries(next);
+      } catch {
+        for (const url of created) URL.revokeObjectURL(url);
+      }
+    })();
+    return () => { cancelled = true; };
+  });
+
+  $effect(() => () => {
+    for (const url of ownedAssetUrls.values()) URL.revokeObjectURL(url);
+    ownedAssetUrls.clear();
+  });
+
   async function createMarkdownFile(): Promise<void> {
     const raw = newMarkdownPath.trim();
     if (raw.length === 0) return;
@@ -3226,6 +3313,7 @@
             onCollabDocChange={handleCollabDocChange}
             onCollabSelectionChange={handleCollabSelectionChange}
             onCollabViewportChange={handleCollabViewportChange}
+            resolveAssetUrl={resolveLocalAssetUrl}
           />
         {/key}
       </div>
@@ -3242,6 +3330,7 @@
         <HtmlViewer
           content={bodyText ?? displayText ?? ''}
           allowScripts={false}
+          resolveAssetUrl={resolveLocalAssetUrl}
           annotate={htmlAnnotatable}
           annotationEvents={htmlAnnotationEvents}
           onBridge={(bridge) => (htmlBridge = bridge)}
diff --git a/web/src/lib/HtmlViewer.svelte b/web/src/lib/HtmlViewer.svelte
index 21c1b265..e518a065 100644
--- a/web/src/lib/HtmlViewer.svelte
+++ b/web/src/lib/HtmlViewer.svelte
@@ -6,6 +6,7 @@
     HtmlAnnotationBridge,
     injectDocRuntime,
   } from './review/html-annotation-bridge';
+  import { rewriteSharedHtmlImageSources } from './review/html-shared-assets';
   import type { AnnotationBridgeEvents } from './review/html-annotation-bridge';
 
   interface Props {
@@ -30,6 +31,8 @@
     mtime?: number;
     /** Native/local pages retain script support; hosted snapshots disable it. */
     allowScripts?: boolean;
+    /** Resolves a share-bound HTML image src to an in-memory Blob URL. */
+    resolveAssetUrl?: (src: string) => string | null;
     /** Turn on commenting for either a shared source or a local path. */
     annotate?: boolean;
     /** Wired up once the frame exists, so a parent can drive the rail. */
@@ -43,6 +46,7 @@
     content,
     mtime,
     allowScripts = true,
+    resolveAssetUrl,
     annotate = false,
     annotationEvents,
     onBridge,
@@ -90,9 +94,11 @@
   // is why the trust boundary sits in the shell and not in the frame.
   // @see planning/collab/html-annotation.md §3, §4
   let sandbox = $derived(htmlViewerSandbox(allowScripts || annotating));
-  let renderedContent = $derived(
-    annotating && content !== undefined ? injectDocRuntime(content) : content,
-  );
+  let renderedContent = $derived.by(() => {
+    if (content === undefined) return content;
+    const withSharedAssets = rewriteSharedHtmlImageSources(content, resolveAssetUrl);
+    return annotating ? injectDocRuntime(withSharedAssets) : withSharedAssets;
+  });
   let src = $derived.by(() => {
     if (isContentMode || path === undefined) return undefined;
     const params = new URLSearchParams();
diff --git a/web/src/lib/review/asset-resolution.test.ts b/web/src/lib/review/asset-resolution.test.ts
index e2924ec6..eadd1c49 100644
--- a/web/src/lib/review/asset-resolution.test.ts
+++ b/web/src/lib/review/asset-resolution.test.ts
@@ -4,6 +4,7 @@
 // web/scripts/run-tests.mjs, not vitest.
 
 import { sharedAssetPathFor, assetDataUrl, buildSharedAssetResolver } from './asset-resolution';
+import type { BrowserAssetRegistry } from './browser-asset-registry';
 import type { ReviewSnapshot } from '../types';
 
 interface CaseResult {
@@ -166,6 +167,21 @@ defineCase('an asset that travelled with the document resolves to its bytes', ()
   assertEq(resolve('./diagram.png'), 'data:image/png;base64,AAAA', 'resolved');
 });
 
+defineCase('a verified browser asset resolves through its tab-local Blob URL', () => {
+  const registry = {
+    urlFor: (roomId: string, snapshotId: string) => roomId === 'room-1' && snapshotId === 'snap-diagram.png'
+      ? 'blob:verified-image'
+      : null,
+  } as BrowserAssetRegistry;
+  const resolve = buildSharedAssetResolver(
+    [assetSnapshot('diagram.png', { assetContent: undefined })],
+    'room-1',
+    'images.md',
+    registry,
+  );
+  assertEq(resolve('./diagram.png'), 'blob:verified-image', 'verified Blob URL wins over serialized fallback');
+});
+
 defineCase('a src with no matching asset resolves to null, not a guess', () => {
   // Policy-skipped images (remote, symlink, oversized, budget-exhausted) and
   // not-yet-arrived ones are indistinguishable here, and the honest answer for
diff --git a/web/src/lib/review/asset-resolution.ts b/web/src/lib/review/asset-resolution.ts
index 9c0969b4..412dcd16 100644
--- a/web/src/lib/review/asset-resolution.ts
+++ b/web/src/lib/review/asset-resolution.ts
@@ -13,10 +13,12 @@
 // strips the share root, admits only `Component::Normal` segments, joins with
 // `/`, and NFC-normalises. So they live in one root-relative space and a src
 // resolved against the document's own path lands on the asset's key. The
-// manifest is NOT consulted: it is a binding artifact, and the asset snapshot
-// already carries the only key needed.
+// Browser asset bytes are activated only after their snapshot metadata matches
+// the signed manifest, then live as tab-local Blob URLs. Native keeps its
+// existing base64 bridge as a backwards-compatible rendering fallback.
 
 import type { ReviewSnapshot } from '../types';
+import { browserAssetRegistry, type BrowserAssetRegistry } from './browser-asset-registry';
 
 /** `scheme:` — 2+ chars so a `C:` drive letter is not mistaken for one.
  *  Mirrors `is_non_local` in src/review/assets.rs. */
@@ -125,6 +127,7 @@ export function buildSharedAssetResolver(
   snapshots: readonly ReviewSnapshot[],
   roomId: string | null,
   docWirePath: string | null | undefined,
+  registry: BrowserAssetRegistry = browserAssetRegistry,
 ): (src: string) => string | null {
   if (!roomId || !docWirePath) return () => null;
 
@@ -151,7 +154,11 @@ export function buildSharedAssetResolver(
     if (!snapshot) return null;
     const cached = urls.get(snapshot.snapshotId);
     if (cached !== undefined) return cached;
-    const url = assetDataUrl(snapshot.mediaType, snapshot.assetContent);
+    // Browser sessions intentionally do not put asset payloads on a
+    // ReviewSnapshot. Their hash- and manifest-bound bytes live only in the
+    // tab-local registry; native keeps its existing `assetContent` bridge.
+    const url = registry.urlFor(roomId, snapshot.snapshotId)
+      ?? assetDataUrl(snapshot.mediaType, snapshot.assetContent);
     urls.set(snapshot.snapshotId, url);
     return url;
   };
diff --git a/web/src/lib/review/browser-asset-registry.test.ts b/web/src/lib/review/browser-asset-registry.test.ts
new file mode 100644
index 00000000..5937d81d
--- /dev/null
+++ b/web/src/lib/review/browser-asset-registry.test.ts
@@ -0,0 +1,77 @@
+import { BrowserAssetRegistry, type BrowserObjectUrlApi } from './browser-asset-registry';
+import type { WorkspaceManifestEntry } from '../types';
+
+function assert(value: unknown, message: string): asserts value {
+  if (!value) throw new Error(message);
+}
+
+function assetEntry(overrides: Partial<WorkspaceManifestEntry> = {}): WorkspaceManifestEntry {
+  return {
+    fileId: 'file-a',
+    snapshotId: 'snapshot-a',
+    path: 'images/chart.png',
+    kind: 'asset',
+    mediaType: 'image/png',
+    byteLength: 24,
+    contentHash: 'hash-a',
+    ...overrides,
+  };
+}
+
+function pngBytes(): Uint8Array {
+  const bytes = new Uint8Array(24);
+  bytes.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  bytes.set([0, 0, 0, 2, 0, 0, 0, 2], 16);
+  return bytes;
+}
+
+const revoked: string[] = [];
+let serial = 0;
+const objectUrls: BrowserObjectUrlApi = {
+  createObjectURL: () => `blob:test-${++serial}`,
+  revokeObjectURL: (url) => revoked.push(url),
+};
+const registry = new BrowserAssetRegistry(objectUrls);
+const source = pngBytes();
+
+registry.stage({
+  roomId: 'room-a', fileId: 'file-a', snapshotId: 'snapshot-a', path: 'images/chart.png',
+  mediaType: 'image/png', bytes: source,
+});
+registry.activateManifest('room-a', [assetEntry()]);
+assert(registry.urlFor('room-a', 'snapshot-a') === 'blob:test-1', 'bound asset receives a Blob URL');
+assert(source.every((byte) => byte === 0), 'source bytes are zeroed after the Blob takes a copy');
+
+const unbound = pngBytes();
+registry.stage({
+  roomId: 'room-a', fileId: 'file-b', snapshotId: 'snapshot-b', path: 'images/other.png',
+  mediaType: 'image/png', bytes: unbound,
+});
+registry.activateManifest('room-a', [assetEntry({ snapshotId: 'snapshot-b', path: 'images/forged.png' })]);
+assert(registry.urlFor('room-a', 'snapshot-b') === null, 'a manifest path mismatch cannot mint a Blob URL');
+assert(unbound.some((byte) => byte !== 0), 'unbound data remains pending for a later authentic manifest');
+
+const rejected = new Uint8Array([0, 1, 2, 3]);
+registry.stage({
+  roomId: 'room-a', fileId: 'file-rejected', snapshotId: 'snapshot-rejected', path: 'images/not-an-image',
+  mediaType: 'application/octet-stream', bytes: rejected,
+});
+assert(rejected.every((byte) => byte === 0), 'unsupported payloads are zeroed before they enter the registry');
+assert(registry.urlFor('room-a', 'snapshot-rejected') === null, 'unsupported payloads cannot activate');
+
+const replacement = pngBytes();
+registry.stage({
+  roomId: 'room-a', fileId: 'file-c', snapshotId: 'snapshot-c', path: 'images/chart.png',
+  mediaType: 'image/png', bytes: replacement,
+});
+registry.activateManifest('room-a', [assetEntry({ fileId: 'file-c', snapshotId: 'snapshot-c' })]);
+assert(registry.urlFor('room-a', 'snapshot-a') === null, 'a replacement releases the old snapshot URL');
+assert(registry.urlFor('room-a', 'snapshot-c') === 'blob:test-2', 'a replacement activates the latest verified asset');
+assert(revoked.includes('blob:test-1'), 'replaced URLs are revoked');
+
+registry.clearRoom('room-a');
+assert(registry.urlFor('room-a', 'snapshot-c') === null, 'room teardown clears active URLs');
+assert(revoked.includes('blob:test-2'), 'room teardown revokes active URLs');
+assert(unbound.every((byte) => byte === 0), 'room teardown zeroes pending bytes');
+
+console.log('browser-asset-registry: 10 passed, 0 failed');
diff --git a/web/src/lib/review/browser-asset-registry.ts b/web/src/lib/review/browser-asset-registry.ts
new file mode 100644
index 00000000..b1c96384
--- /dev/null
+++ b/web/src/lib/review/browser-asset-registry.ts
@@ -0,0 +1,196 @@
+// Per-tab runtime for verified shared image bytes.
+//
+// Snapshot plaintext and the Svelte review store deliberately never retain an
+// asset payload. A session stages a hash-verified byte buffer here, then the
+// signed workspace manifest activates the exact matching entry as a Blob URL.
+// That keeps encrypted document bytes out of persisted app state while still
+// giving ProseMirror a synchronous URL resolver.
+
+import type { WorkspaceManifestEntry } from '../types';
+import {
+  bytesMatchSharedImageMediaType,
+  hasSafeSharedImageDimensions,
+  isSupportedSharedImageMediaType,
+  MAX_SHARED_IMAGE_BYTES,
+  MAX_SHARED_IMAGE_COUNT,
+  MAX_SHARED_IMAGE_TOTAL_BYTES,
+} from './shared-image-policy';
+
+export interface VerifiedBrowserAsset {
+  roomId: string;
+  fileId: string;
+  snapshotId: string;
+  path: string;
+  mediaType: string;
+  bytes: Uint8Array;
+}
+
+interface ActiveAsset {
+  roomId: string;
+  snapshotId: string;
+  path: string;
+  url: string;
+  byteLength: number;
+}
+
+export interface BrowserObjectUrlApi {
+  createObjectURL(blob: Blob): string;
+  revokeObjectURL(url: string): void;
+}
+
+function defaultObjectUrls(): BrowserObjectUrlApi | null {
+  if (typeof URL === 'undefined' || typeof Blob === 'undefined') return null;
+  if (typeof URL.createObjectURL !== 'function' || typeof URL.revokeObjectURL !== 'function') return null;
+  return URL;
+}
+
+function snapshotKey(roomId: string, snapshotId: string): string {
+  return `${roomId}\u0000${snapshotId}`;
+}
+
+function pathKey(roomId: string, path: string): string {
+  return `${roomId}\u0000${path}`;
+}
+
+/**
+ * A room-scoped, tab-local registry. Ownership of `bytes` moves to `stage`;
+ * callers must not read or retain that buffer afterwards.
+ */
+export class BrowserAssetRegistry {
+  private readonly pending = new Map<string, VerifiedBrowserAsset>();
+  private readonly activeBySnapshot = new Map<string, ActiveAsset>();
+  private readonly activeByPath = new Map<string, ActiveAsset>();
+
+  constructor(private readonly objectUrls: BrowserObjectUrlApi | null = defaultObjectUrls()) {}
+
+  stage(asset: VerifiedBrowserAsset): void {
+    const key = snapshotKey(asset.roomId, asset.snapshotId);
+    if (this.activeBySnapshot.has(key)) {
+      // Replay may repeat a snapshot that is already bound and rendered. Keep
+      // the known-good URL rather than allocating a second plaintext Blob.
+      asset.bytes.fill(0);
+      return;
+    }
+    const previous = this.pending.get(key);
+    previous?.bytes.fill(0);
+    this.pending.delete(key);
+    if (!isAllowedAsset(asset) || !this.canStage(asset)) {
+      asset.bytes.fill(0);
+      return;
+    }
+    this.pending.set(key, asset);
+  }
+
+  /**
+   * Activate the assets whose complete metadata exactly matches this signed
+   * manifest. A missing/stale asset remains unavailable instead of becoming a
+   * plausible URL from an unbound snapshot.
+   */
+  activateManifest(roomId: string, entries: readonly WorkspaceManifestEntry[]): void {
+    for (const entry of entries) {
+      if (entry.kind !== 'asset') continue;
+      const key = snapshotKey(roomId, entry.snapshotId);
+      const pending = this.pending.get(key);
+      if (!pending || !matches(entry, pending)) continue;
+      this.pending.delete(key);
+      if (!this.objectUrls) {
+        pending.bytes.fill(0);
+        continue;
+      }
+      const replaced = this.activeByPath.get(pathKey(roomId, entry.path));
+      if (replaced) this.revoke(replaced);
+      let url: string | null = null;
+      let blobBytes: Uint8Array | null = null;
+      try {
+        // Blob's DOM typing requires an ArrayBuffer-backed view; copy out of
+        // a possibly SharedArrayBuffer-backed wire buffer, then zero both
+        // mutable buffers as soon as the Blob has taken its immutable copy.
+        blobBytes = new Uint8Array(pending.bytes);
+        const blob = new Blob([blobBytes.buffer as ArrayBuffer], { type: pending.mediaType });
+        url = this.objectUrls.createObjectURL(blob);
+        const active: ActiveAsset = {
+          roomId,
+          snapshotId: pending.snapshotId,
+          path: pending.path,
+          url,
+          byteLength: pending.bytes.length,
+        };
+        this.activeBySnapshot.set(key, active);
+        this.activeByPath.set(pathKey(roomId, pending.path), active);
+      } finally {
+        blobBytes?.fill(0);
+        pending.bytes.fill(0);
+        // A malformed platform implementation must not leak an inactive URL.
+        if (url !== null && !this.activeBySnapshot.has(key)) this.objectUrls.revokeObjectURL(url);
+      }
+    }
+  }
+
+  urlFor(roomId: string, snapshotId: string): string | null {
+    return this.activeBySnapshot.get(snapshotKey(roomId, snapshotId))?.url ?? null;
+  }
+
+  clearRoom(roomId: string): void {
+    for (const [key, asset] of this.pending) {
+      if (asset.roomId !== roomId) continue;
+      asset.bytes.fill(0);
+      this.pending.delete(key);
+    }
+    for (const asset of [...this.activeBySnapshot.values()]) {
+      if (asset.roomId === roomId) this.revoke(asset);
+    }
+  }
+
+  close(): void {
+    for (const asset of this.pending.values()) asset.bytes.fill(0);
+    this.pending.clear();
+    for (const asset of [...this.activeBySnapshot.values()]) this.revoke(asset);
+  }
+
+  private revoke(asset: ActiveAsset): void {
+    this.activeBySnapshot.delete(snapshotKey(asset.roomId, asset.snapshotId));
+    const key = pathKey(asset.roomId, asset.path);
+    if (this.activeByPath.get(key) === asset) this.activeByPath.delete(key);
+    this.objectUrls?.revokeObjectURL(asset.url);
+  }
+
+  private canStage(asset: VerifiedBrowserAsset): boolean {
+    let count = 1;
+    let bytes = asset.bytes.length;
+    for (const pending of this.pending.values()) {
+      if (pending.roomId !== asset.roomId) continue;
+      count += 1;
+      bytes += pending.bytes.length;
+    }
+    for (const active of this.activeBySnapshot.values()) {
+      if (active.roomId !== asset.roomId) continue;
+      count += 1;
+      bytes += active.byteLength;
+    }
+    return count <= MAX_SHARED_IMAGE_COUNT && bytes <= MAX_SHARED_IMAGE_TOTAL_BYTES;
+  }
+}
+
+function matches(entry: WorkspaceManifestEntry, asset: VerifiedBrowserAsset): boolean {
+  return (
+    entry.fileId === asset.fileId
+    && entry.snapshotId === asset.snapshotId
+    && entry.path === asset.path
+    && entry.mediaType === asset.mediaType
+    && entry.byteLength === asset.bytes.length
+  );
+}
+
+function isAllowedAsset(asset: VerifiedBrowserAsset): boolean {
+  return (
+    isSupportedSharedImageMediaType(asset.mediaType)
+    && asset.bytes.length <= MAX_SHARED_IMAGE_BYTES
+    && bytesMatchSharedImageMediaType(asset.bytes, asset.mediaType)
+    && hasSafeSharedImageDimensions(asset.bytes, asset.mediaType)
+  );
+}
+
+// A module instance belongs to one browser tab. Keeping it here rather than in
+// a Svelte singleton avoids serializing Blob URLs or plaintext through app
+// state, while callers still share one resolver view of a room in that tab.
+export const browserAssetRegistry = new BrowserAssetRegistry();
diff --git a/web/src/lib/review/browser-session.test.ts b/web/src/lib/review/browser-session.test.ts
index 40ef127b..f90a4329 100644
--- a/web/src/lib/review/browser-session.test.ts
+++ b/web/src/lib/review/browser-session.test.ts
@@ -2745,7 +2745,7 @@ defineCase('snapshot parser accepts inert binary/manifest metadata and rejects a
   const manifest = parseBrowserSnapshotPlaintext(toCanonicalBytes({
     docType: 'workspace_manifest',
     manifest: {
-      v: 1, kind: 'attn_workspace_snapshot', scope: 'file',
+      v: 1, kind: 'attn_workspace_snapshot', scope: 'entries',
       entries: [{
         fileId: id(16, 1), snapshotId: id(16, 2), path: 'safe/file.bin', kind: 'asset',
         mediaType: 'application/octet-stream', byteLength: 5, contentHash: id(32, 3),
@@ -2839,7 +2839,7 @@ defineCase('manifest waits for an out-of-order recovered R2 entry, then validate
     manifest: {
       v: 1,
       kind: 'attn_workspace_snapshot',
-      scope: 'file',
+      scope: 'entries',
       entries: [{
         fileId: assetFileId,
         snapshotId: assetSnapshotId,
@@ -2908,7 +2908,7 @@ defineCase('manifest rejects a hydrated entry whose signed binding differs', asy
   const manifest: Extract<SnapshotPlaintext, { docType: 'workspace_manifest' }> = {
     docType: 'workspace_manifest',
     manifest: {
-      v: 1, kind: 'attn_workspace_snapshot', scope: 'file', entries: [{
+      v: 1, kind: 'attn_workspace_snapshot', scope: 'entries', entries: [{
         fileId: assetFileId, snapshotId: assetSnapshotId, path: 'forged.png', kind: 'asset',
         mediaType: 'image/png', byteLength: raw.length, contentHash: contentHash(raw),
       }],
diff --git a/web/src/lib/review/browser-session.ts b/web/src/lib/review/browser-session.ts
index 519d661c..25ac485e 100644
--- a/web/src/lib/review/browser-session.ts
+++ b/web/src/lib/review/browser-session.ts
@@ -55,6 +55,7 @@ import {
   decodeCanonicalBase64Url,
   validateSnapshotPlaintext,
 } from './browser-workspace-manifest';
+import { browserAssetRegistry, type BrowserAssetRegistry } from './browser-asset-registry';
 import { assembleBrowserEvent, type AssembledBrowserEvent } from './browser-envelope';
 import {
   BrowserOutbox,
@@ -376,6 +377,8 @@ export interface BrowserSessionOptions {
   storage?: BrowserStorage;
   /** Override the production IndexedDB opener. */
   storageFactory?: (createIfMissing: boolean) => Promise<BrowserStorage | null>;
+  /** Per-tab verified-asset runtime. Never persisted with the review store. */
+  assetRegistry?: BrowserAssetRegistry;
 }
 
 /** Minimal fetch shape — avoids depending on lib.dom.d.ts in TS tests. */
@@ -920,6 +923,7 @@ export function admissionHeaderValue(
  */
 export class BrowserSession {
   private readonly opts: BrowserSessionOptions;
+  private readonly assetRegistry: BrowserAssetRegistry;
   private state: BrowserSessionState = {
     principal: 'reviewer',
     ownerOnline: false,
@@ -984,6 +988,7 @@ export class BrowserSession {
 
   constructor(opts: BrowserSessionOptions = {}) {
     this.opts = opts;
+    this.assetRegistry = opts.assetRegistry ?? browserAssetRegistry;
     this.principal = opts.owner ? 'owner' : 'reviewer';
     this.state = { ...this.state, principal: this.principal };
     this.store = opts.store ?? null;
@@ -1668,6 +1673,7 @@ export class BrowserSession {
 
   /** Tear down transports and clobber in-memory keys. Safe to call repeatedly. */
   close(): void {
+    const roomId = this.state.roomId;
     this.detachPagehide();
     this.stopTransport();
     this.reviewInboundDoorbell?.close();
@@ -1680,6 +1686,7 @@ export class BrowserSession {
     this.pendingSnapshots.clear();
     this.hydratedEntries.clear();
     this.pendingWorkspaceManifests.clear();
+    if (roomId) this.assetRegistry.clearRoom(roomId);
     this.signerRefreshAttempts.clear();
     this.volatileInbound.clear();
     this.clearStorePlaintext();
@@ -2206,6 +2213,7 @@ export class BrowserSession {
   }
 
   private fail(kind: BrowserSessionError['kind'], message: string): void {
+    const roomId = this.state.roomId;
     this.detachPagehide();
     this.stopTransport();
     this.storage?.close();
@@ -2216,6 +2224,7 @@ export class BrowserSession {
     this.pendingSnapshots.clear();
     this.hydratedEntries.clear();
     this.pendingWorkspaceManifests.clear();
+    if (roomId) this.assetRegistry.clearRoom(roomId);
     this.signerRefreshAttempts.clear();
     this.volatileInbound.clear();
     this.clearStorePlaintext();
@@ -3120,7 +3129,16 @@ export class BrowserSession {
       }
       snapshot.byteLength = raw.length;
       snapshot.mediaType = inline.mediaType;
-      raw.fill(0);
+      // Move the verified buffer into the tab-local registry. It stays inert
+      // until the signed workspace manifest binds every field below.
+      this.assetRegistry.stage({
+        roomId: meta.roomId,
+        fileId: body.fileId,
+        snapshotId: body.snapshotId,
+        path: body.ownerDisplayPath ?? '',
+        mediaType: inline.mediaType,
+        bytes: raw,
+      });
     } else {
       const canonical = toCanonicalBytes(inline.manifest);
       if (contentHash(canonical) !== body.baseHash) {
@@ -3144,6 +3162,7 @@ export class BrowserSession {
       }
       this.pendingWorkspaceManifests.delete(body.snapshotId);
       snapshot.workspaceManifest = inline.manifest;
+      this.assetRegistry.activateManifest(meta.roomId, inline.manifest.entries);
     }
     store.applySnapshot(snapshot);
     if (inline.docType !== 'workspace_manifest') {
diff --git a/web/src/lib/review/browser-share-owner.ts b/web/src/lib/review/browser-share-owner.ts
index 19907664..a7738c9e 100644
--- a/web/src/lib/review/browser-share-owner.ts
+++ b/web/src/lib/review/browser-share-owner.ts
@@ -203,8 +203,9 @@ export interface SealDurableSnapshotInput {
   epoch: number;
   fileId: string;
   snapshotId: string;
-  docType: 'markdown' | 'html';
+  docType: 'markdown' | 'html' | 'asset';
   content: string;
+  mediaType?: string;
   metadata?: unknown;
   snapshotKey: Uint8Array;
   nonce?: Uint8Array;
@@ -233,6 +234,7 @@ export async function sealDurableShareSnapshot(input: SealDurableSnapshotInput):
     snapshotId: input.snapshotId,
     docType: input.docType,
     content: input.content,
+    ...(input.mediaType === undefined ? {} : { mediaType: input.mediaType }),
     ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
   });
   let ciphertext: Uint8Array | null = null;
diff --git a/web/src/lib/review/browser-share-production.test.ts b/web/src/lib/review/browser-share-production.test.ts
index f5d0b1eb..f060a706 100644
--- a/web/src/lib/review/browser-share-production.test.ts
+++ b/web/src/lib/review/browser-share-production.test.ts
@@ -1,11 +1,12 @@
-import { base64UrlEncode, deriveShareLinkKeys, expandShareLinkKeys } from './browser-crypto';
+import { base64UrlEncode, contentHash, deriveShareLinkKeys, expandShareLinkKeys } from './browser-crypto';
 import { deriveReadKeysV3, toCanonicalBytes } from './browser-crypto';
 import { buildShareBundleMutations, EMPTY_SHARE_MANIFEST_DIGEST } from './browser-share-owner';
 import { parseAndStripShareInvite } from './browser-share';
 import { createBrowserDurableShareResolver, createShareMailboxTransport, decryptDurableShareSnapshot,
   DurableShareBrowserSessionFacade, reviewSnapshotFromDurable, subscribeToDurableShareChanges,
-  RememberedPushShareSessionFacade,
+  RememberedPushShareSessionFacade, stageDurableAsset,
   type BrowserDurableSharePersistence } from './browser-share-production';
+import { browserAssetRegistry } from './browser-asset-registry';
 import { indexedDB as fakeIndexedDB } from 'fake-indexeddb';
 import { StaleShareEpochError } from './browser-share-session';
 import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
@@ -138,6 +139,27 @@ const inviteUrl = `https://attn.sh/s/${shareId}#key=${base64UrlEncode(secret)}`;
   console.log('PASS durable snapshot installation binds resolved room before state patch');
 }
 
+{
+  const raw = new Uint8Array(24);
+  raw.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  raw.set([0, 0, 0, 2, 0, 0, 0, 2], 16);
+  const fileId = 'durable-image-file'; const snapshotId = 'durable-image-snapshot';
+  const hash = contentHash(raw);
+  stageDurableAsset({
+    fileId, snapshotId, docType: 'asset', content: base64UrlEncode(raw), mediaType: 'image/png',
+    metadata: { baseHash: hash, manifestEntry: {
+      fileId, snapshotId, path: 'assets/diagram.png', kind: 'asset', mediaType: 'image/png',
+      byteLength: raw.length, contentHash: hash,
+    } },
+  }, 'durable-image-room');
+  assert(browserAssetRegistry.urlFor('durable-image-room', snapshotId)?.startsWith('blob:'),
+    'offline durable image did not activate a verified Blob URL');
+  const mapped = reviewSnapshotFromDurable({ fileId, snapshotId, docType: 'asset', content: base64UrlEncode(raw), mediaType: 'image/png' }, 'durable-image-room');
+  assert(mapped.assetContent === undefined && mapped.content === undefined, 'durable raw image entered review store');
+  browserAssetRegistry.clearRoom('durable-image-room'); raw.fill(0);
+  console.log('PASS durable image snapshot activates Blob-only renderer state');
+}
+
 {
   const invite = { shareId, linkSecret: new Uint8Array(secret) };
   const persistence = { atomicMax: async ({ candidate }: { candidate: { epoch: number; revision: number; manifestDigest: string } }) => candidate,
diff --git a/web/src/lib/review/browser-share-production.ts b/web/src/lib/review/browser-share-production.ts
index 27def550..0d84cca3 100644
--- a/web/src/lib/review/browser-share-production.ts
+++ b/web/src/lib/review/browser-share-production.ts
@@ -2,6 +2,8 @@ import { sanitizeParticipantColor } from '../participant-color';
 import { decompressSnapshotIfNeeded } from './snapshot-compression';
 import { boundFetch } from './bound-fetch';
 import { compareManifestPathsUtf8 } from './browser-workspace-manifest';
+import { decodeCanonicalBase64Url, isValidSnapshotMediaType } from './browser-workspace-manifest';
+import { browserAssetRegistry } from './browser-asset-registry';
 import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
 import { sha256 } from '@noble/hashes/sha2.js';
 import {
@@ -62,7 +64,15 @@ import {
   replacePushBinding,
   type PushBindingRecord,
 } from './browser-push-worker';
-import type { Anchor, Capability, ReviewEvent, ReviewEventBody, ReviewSnapshot, SuggestionDraft } from '../types';
+import type {
+  Anchor,
+  Capability,
+  ReviewEvent,
+  ReviewEventBody,
+  ReviewSnapshot,
+  SuggestionDraft,
+  WorkspaceManifestEntry,
+} from '../types';
 
 const DB_NAME = 'attn-browser-durable-shares';
 const DB_VERSION = 1;
@@ -448,7 +458,10 @@ export class DurableShareBrowserSessionFacade {
   }
   close(): void { if (this.closed) return; this.closed = true; ++this.generation; this.startAbort?.abort(); this.startAbort = null;
     this.options.invite.linkSecret.fill(0); this.linkSecretForRemember.fill(0);
-    this.session?.pushConsent.close(); this.session?.close(); this.session = null; }
+    const roomId = this.state.roomId;
+    this.session?.pushConsent.close(); this.session?.close(); this.session = null;
+    if (roomId) browserAssetRegistry.clearRoom(roomId);
+  }
   async createComment(anchor: Anchor, body: string, threadId?: string): Promise<ReviewEvent> {
     const event = await this.requireSession().createComment(anchor, body, threadId);
     if (!event) throw new Error('comment was queued without an optimistic event');
@@ -530,7 +543,7 @@ export class DurableShareBrowserSessionFacade {
       this.observer?.(this.state);
       return;
     }
-    const snapshot = next.snapshots[0];
+    const snapshot = next.snapshots.find((candidate) => candidate.docType !== 'asset');
     this.state = { ...this.state,
       status: next.status === 'ready' ? 'connected' : next.status === 'error' ? 'error' : 'connecting',
       ownerOnline: next.ownerOnline, liveEditingAvailable: false,
@@ -548,6 +561,7 @@ export class DurableShareBrowserSessionFacade {
     const { reviewStore } = await import('./store.svelte.js'); reviewStore.applyEvent(event);
   }
   private async installSnapshot(snapshot: DurableShareSnapshot, roomId: string): Promise<void> {
+    if (snapshot.docType === 'asset') stageDurableAsset(snapshot, roomId);
     const value = reviewSnapshotFromDurable(snapshot, roomId);
     const { reviewStore } = await import('./store.svelte.js');
     reviewStore.currentRoomId = value.roomId; reviewStore.applySnapshot(value);
@@ -555,6 +569,7 @@ export class DurableShareBrowserSessionFacade {
     // so unconditionally selecting made the LAST restored file win on every
     // reload (and clobbered the URL-requested file). Claim only an empty
     // selection; refresh the snapshot pick when the restored file IS selected.
+    if (value.docType === 'asset') return;
     if (reviewStore.currentFileId === null) {
       reviewStore.setCurrentFile(value.fileId); reviewStore.setCurrentSnapshot(value.snapshotId);
     } else if (reviewStore.currentFileId === value.fileId) {
@@ -563,6 +578,51 @@ export class DurableShareBrowserSessionFacade {
   }
 }
 
+/** Activate one authenticated durable image only when its sealed metadata
+ * restates an exact manifest entry. The outer ShareDO manifest authenticates
+ * the ciphertext ref; this second check pins the plaintext's path/type/size
+ * before a Blob URL is ever minted. */
+export function stageDurableAsset(snapshot: DurableShareSnapshot, roomId: string): void {
+  const metadata = isRecord(snapshot.metadata) ? snapshot.metadata : null;
+  const rawEntry = metadata?.manifestEntry;
+  if (!isRecord(rawEntry) || !isValidDurableAssetEntry(rawEntry, snapshot)) {
+    throw new Error('durable image snapshot is missing its manifest binding');
+  }
+  const entry = rawEntry as unknown as WorkspaceManifestEntry;
+  const bytes = decodeCanonicalBase64Url(snapshot.content);
+  if (
+    digest(bytes) !== entry.contentHash
+    || metadata?.baseHash !== entry.contentHash
+    || bytes.length !== entry.byteLength
+  ) {
+    bytes.fill(0);
+    throw new Error('durable image snapshot does not match its manifest binding');
+  }
+  browserAssetRegistry.stage({
+    roomId,
+    fileId: snapshot.fileId,
+    snapshotId: snapshot.snapshotId,
+    path: entry.path,
+    mediaType: snapshot.mediaType!,
+    bytes,
+  });
+  browserAssetRegistry.activateManifest(roomId, [entry]);
+}
+
+function isValidDurableAssetEntry(value: Record<string, unknown>, snapshot: DurableShareSnapshot): boolean {
+  return (
+    value.fileId === snapshot.fileId
+    && value.snapshotId === snapshot.snapshotId
+    && typeof value.path === 'string'
+    && value.kind === 'asset'
+    && value.mediaType === snapshot.mediaType
+    && isValidSnapshotMediaType(value.mediaType)
+    && Number.isSafeInteger(value.byteLength)
+    && (value.byteLength as number) >= 0
+    && typeof value.contentHash === 'string'
+  );
+}
+
 /** Fragmentless notification-click recovery from a locally remembered, non-extractable binding. */
 export class RememberedPushShareSessionFacade {
   readonly closeOnDestroy = true;
@@ -591,25 +651,33 @@ export class RememberedPushShareSessionFacade {
       }
       const snapshots = await this.loadSnapshots(binding, abort.signal);
       if (this.closed) return;
-      const first = snapshots[0];
       const store = this.options.store ?? (await import('./store.svelte.js')).reviewStore;
       store.currentRoomId = binding.roomId;
-      for (const snapshot of snapshots) store.applySnapshot(reviewSnapshotFromDurable(snapshot, binding.roomId));
-      if (first && store.currentFileId === null) {
-        store.setCurrentFile(first.fileId); store.setCurrentSnapshot(first.snapshotId);
+      for (const snapshot of snapshots) {
+        if (snapshot.docType === 'asset') stageDurableAsset(snapshot, binding.roomId);
+        store.applySnapshot(reviewSnapshotFromDurable(snapshot, binding.roomId));
+      }
+      const firstDocument = snapshots.find((snapshot) => snapshot.docType !== 'asset');
+      if (firstDocument && store.currentFileId === null) {
+        store.setCurrentFile(firstDocument.fileId); store.setCurrentSnapshot(firstDocument.snapshotId);
       }
       await consumePendingPushEvents(binding.bindingId, event => store.applyEvent(event), {
         indexedDB: this.options.indexedDB,
       });
       if (this.closed) return;
       this.patch({ status: 'connected', connection: 'mailbox', roomId: binding.roomId,
-        snapshotContent: first?.content ?? null, snapshotDocType: first?.docType ?? 'markdown',
-        snapshotId: first?.snapshotId ?? null, fileId: first?.fileId ?? null });
+        snapshotContent: firstDocument?.content ?? null, snapshotDocType: firstDocument?.docType ?? 'markdown',
+        snapshotId: firstDocument?.snapshotId ?? null, fileId: firstDocument?.fileId ?? null });
     } catch (error) {
       if (!this.closed) this.patch({ status: 'error', error: { kind: 'invite_invalid', message: safeProductionMessage(error) } });
     } finally { if (this.abort === abort) this.abort = null; }
   }
-  close(): void { this.closed = true; this.abort?.abort(); this.abort = null; }
+  close(): void {
+    this.closed = true;
+    this.abort?.abort();
+    this.abort = null;
+    if (this.state.roomId) browserAssetRegistry.clearRoom(this.state.roomId);
+  }
   async createComment(): Promise<ReviewEvent> { throw new Error('reopen the original share link to author'); }
   async replyToComment(): Promise<ReviewEvent> { throw new Error('reopen the original share link to author'); }
   async resolveComment(): Promise<ReviewEvent> { throw new Error('reopen the original share link to author'); }
@@ -673,11 +741,24 @@ export class RememberedPushShareSessionFacade {
 
 export function reviewSnapshotFromDurable(snapshot: DurableShareSnapshot, roomId: string): ReviewSnapshot {
     const metadata = isRecord(snapshot.metadata) ? snapshot.metadata : {};
-    const baseHash = typeof metadata.baseHash === 'string' ? metadata.baseHash : digest(new TextEncoder().encode(snapshot.content));
+    let byteLength: number;
+    if (snapshot.docType === 'asset') {
+      const bytes = decodeCanonicalBase64Url(snapshot.content);
+      byteLength = bytes.length;
+      bytes.fill(0);
+    } else {
+      byteLength = new TextEncoder().encode(snapshot.content).length;
+    }
+    const baseHash = typeof metadata.baseHash === 'string'
+      ? metadata.baseHash
+      : digest(new TextEncoder().encode(snapshot.content));
     return { roomId, fileId: snapshot.fileId, snapshotId: snapshot.snapshotId,
       createdAt: Number.isSafeInteger(metadata.createdAt) ? metadata.createdAt as number : Date.now(),
       createdBy: typeof metadata.createdBy === 'string' ? metadata.createdBy : 'share-owner', baseHash,
-      byteLength: new TextEncoder().encode(snapshot.content).length, docType: snapshot.docType, content: snapshot.content,
+      byteLength, docType: snapshot.docType,
+      ...(snapshot.docType === 'asset'
+        ? { mediaType: snapshot.mediaType }
+        : { content: snapshot.content }),
       ...(isRecord(metadata.anchorIndex) ? { anchorIndex: metadata.anchorIndex as unknown as ReviewSnapshot['anchorIndex'] } : {}),
       ...(typeof metadata.ownerDisplayPath === 'string' ? { ownerDisplayPath: metadata.ownerDisplayPath } : {}) };
 }
@@ -978,12 +1059,18 @@ export async function decryptDurableShareSnapshot(shareId: string, epoch: number
     plaintext = xchacha20poly1305(capability.roomKeys.snapshotKey, sealed.subarray(0, 24), aad).decrypt(sealed.subarray(24));
     inflated = await decompressSnapshotIfNeeded(plaintext);
     const value = JSON.parse(new TextDecoder().decode(inflated)) as unknown;
-    if (!isRecord(value) || Object.keys(value).some(key => !['v','fileId','snapshotId','docType','content','metadata'].includes(key)) ||
+    if (!isRecord(value) || Object.keys(value).some(key => !['v','fileId','snapshotId','docType','content','mediaType','metadata'].includes(key)) ||
       value.v !== 3 || value.fileId !== fileId || value.snapshotId !== snapshotId ||
-      (value.docType !== 'markdown' && value.docType !== 'html') || typeof value.content !== 'string') {
+      (value.docType !== 'markdown' && value.docType !== 'html' && value.docType !== 'asset') || typeof value.content !== 'string' ||
+      (value.docType === 'asset' && !isValidSnapshotMediaType(value.mediaType))) {
       throw new Error('durable share snapshot plaintext is invalid');
     }
+    if (value.docType === 'asset') {
+      const bytes = decodeCanonicalBase64Url(value.content);
+      bytes.fill(0);
+    }
     return { fileId, snapshotId, docType: value.docType, content: value.content,
+      ...(value.docType === 'asset' ? { mediaType: value.mediaType as string } : {}),
       ...(value.metadata === undefined ? {} : { metadata: structuredClone(value.metadata) }) };
   } finally { aad.fill(0); if (inflated !== plaintext) inflated?.fill(0); plaintext?.fill(0); }
 }
@@ -996,7 +1083,7 @@ function disposeBundle(bundle: DecodedDurableShareBundle): void {
 function disposeLinkKeys(keys: ShareLinkKeys): void {
   keys.linkSecret.fill(0); keys.bundleKey.fill(0); keys.readAdmissionKey.fill(0); keys.writeAdmissionKey?.fill(0);
 }
-function disposeSnapshot(snapshot: DurableShareSnapshot): void { snapshot.content = ''; snapshot.metadata = undefined; }
+function disposeSnapshot(snapshot: DurableShareSnapshot): void { snapshot.content = ''; snapshot.metadata = undefined; snapshot.mediaType = undefined; }
 function parseRememberedSnapshotRef(value: unknown): { fileId: string; snapshotId: string; ciphertextBytes: number; ciphertextSha256: string; uploadedAt: number } {
   if (!isRecord(value) || typeof value.fileId !== 'string' || typeof value.snapshotId !== 'string' ||
     !Number.isSafeInteger(value.ciphertextBytes) || (value.ciphertextBytes as number) < 41 ||
@@ -1019,10 +1106,16 @@ async function decryptRememberedSnapshot(shareId: string, epoch: number, _roomId
     inflated = await decompressSnapshotIfNeeded(plaintext);
     const value = JSON.parse(new TextDecoder().decode(inflated)) as unknown;
     if (!isRecord(value) || value.v !== 3 || value.fileId !== fileId || value.snapshotId !== snapshotId ||
-      (value.docType !== 'markdown' && value.docType !== 'html') || typeof value.content !== 'string') {
+      (value.docType !== 'markdown' && value.docType !== 'html' && value.docType !== 'asset') || typeof value.content !== 'string' ||
+      (value.docType === 'asset' && !isValidSnapshotMediaType(value.mediaType))) {
       throw new Error('remembered snapshot plaintext is invalid');
     }
+    if (value.docType === 'asset') {
+      const bytes = decodeCanonicalBase64Url(value.content);
+      bytes.fill(0);
+    }
     return { fileId, snapshotId, docType: value.docType, content: value.content,
+      ...(value.docType === 'asset' ? { mediaType: value.mediaType as string } : {}),
       ...(value.metadata === undefined ? {} : { metadata: structuredClone(value.metadata) }) };
   } finally { aad.fill(0); if (inflated !== plaintext) inflated?.fill(0); plaintext?.fill(0); }
 }
diff --git a/web/src/lib/review/browser-share-resolver.ts b/web/src/lib/review/browser-share-resolver.ts
index 8f397c30..c12bbf43 100644
--- a/web/src/lib/review/browser-share-resolver.ts
+++ b/web/src/lib/review/browser-share-resolver.ts
@@ -1,7 +1,7 @@
 /** Crypto-agnostic durable-share resolution with persistent rollback fencing. */
 
 export type DurableShareTier = 'view' | 'comment' | 'suggest';
-export type DurableShareDocType = 'markdown' | 'html';
+export type DurableShareDocType = 'markdown' | 'html' | 'asset';
 
 const PROTOCOL_ID = /^[A-Za-z0-9_-]{1,128}$/u;
 const BUNDLE_ID = /^[A-Za-z0-9_-]{22}$/u;
@@ -53,6 +53,7 @@ export interface DurableShareSnapshot {
   snapshotId: string;
   docType: DurableShareDocType;
   content: string;
+  mediaType?: string;
   metadata?: unknown;
 }
 
@@ -330,8 +331,9 @@ export class BrowserShareResolver<TCapability = unknown> {
       try {
         if (
           snapshot.fileId !== ref.fileId || snapshot.snapshotId !== ref.snapshotId ||
-          (snapshot.docType !== 'markdown' && snapshot.docType !== 'html') ||
-          typeof snapshot.content !== 'string'
+          (snapshot.docType !== 'markdown' && snapshot.docType !== 'html' && snapshot.docType !== 'asset') ||
+          typeof snapshot.content !== 'string' ||
+          (snapshot.docType === 'asset' && typeof snapshot.mediaType !== 'string')
         ) {
           throw new BrowserShareResolutionError(
             'snapshot_invalid',
diff --git a/web/src/lib/review/browser-workspace-manifest.test.ts b/web/src/lib/review/browser-workspace-manifest.test.ts
index 24b4b7aa..b37b7ae0 100644
--- a/web/src/lib/review/browser-workspace-manifest.test.ts
+++ b/web/src/lib/review/browser-workspace-manifest.test.ts
@@ -83,8 +83,17 @@ rejects(() => validateSnapshotPlaintext({ docType: 'html', content: '<b>x</b>',
 rejects(() => validateSnapshotPlaintext({ docType: 'markdown', content: 'x', annotation: 'html_selectors_v1' }), 'annotation on markdown');
 rejects(() => validateWorkspaceManifest({ ...built, entries: [built.entries[0], built.entries[0]] }), 'duplicate paths/ids');
 rejects(() => validateWorkspaceManifest({ ...built, entries: [...built.entries].reverse() }), 'unsorted paths');
-rejects(() => validateWorkspaceManifest({ ...built, scope: 'file' }), 'file scope with many entries');
+equal(
+  validateWorkspaceManifest({ ...built, scope: 'file' }).entries.length,
+  2,
+  'file scope permits a document plus its image dependencies',
+);
+rejects(() => validateWorkspaceManifest({
+  ...built,
+  scope: 'file',
+  entries: [...built.entries, { ...markdown, path: 'z/second.md', fileId: base64UrlEncode(new Uint8Array(16).fill(9)), snapshotId: base64UrlEncode(new Uint8Array(16).fill(10)) }],
+}), 'file scope rejects a second document');
 rejects(() => validateWorkspaceManifest({ ...built, entries: [{ ...built.entries[0], path: '../raw.bin' }] }), 'escaping path');
 rejects(() => validateWorkspaceManifest({ ...built, entries: [{ ...built.entries[0], contentHash: 'AA' }] }), 'short hash');
 
-console.log(`browser-workspace-manifest: ${vector.cases.length + 14} passed, 0 failed`);
+console.log(`browser-workspace-manifest: ${vector.cases.length + 15} passed, 0 failed`);
diff --git a/web/src/lib/review/browser-workspace-manifest.ts b/web/src/lib/review/browser-workspace-manifest.ts
index 3f27431b..e000c86a 100644
--- a/web/src/lib/review/browser-workspace-manifest.ts
+++ b/web/src/lib/review/browser-workspace-manifest.ts
@@ -61,9 +61,6 @@ export function validateWorkspaceManifest(value: unknown): WorkspaceSnapshotMani
   if (!Array.isArray(value.entries) || value.entries.length === 0) {
     throw new Error('workspace manifest must contain at least one entry');
   }
-  if (value.scope === 'file' && value.entries.length !== 1) {
-    throw new Error('file-scoped workspace manifest must contain exactly one entry');
-  }
   const entries: WorkspaceManifestEntry[] = [];
   let previousPath: string | undefined;
   const fileIds = new Set<string>();
@@ -86,6 +83,13 @@ export function validateWorkspaceManifest(value: unknown): WorkspaceSnapshotMani
     previousPath = entry.path;
     entries.push(entry);
   }
+  if (
+    value.scope === 'file'
+    && (entries.filter((entry) => entry.kind === 'markdown' || entry.kind === 'html').length !== 1
+      || entries.some((entry) => entry.kind === 'asset' && !isValidSnapshotMediaType(entry.mediaType)))
+  ) {
+    throw new Error('file-scoped workspace manifest must contain one document and its asset dependencies');
+  }
   return {
     v: 1,
     kind: 'attn_workspace_snapshot',
diff --git a/web/src/lib/review/browser-workspace-sharing.test.ts b/web/src/lib/review/browser-workspace-sharing.test.ts
index 432b95ac..96954da9 100644
--- a/web/src/lib/review/browser-workspace-sharing.test.ts
+++ b/web/src/lib/review/browser-workspace-sharing.test.ts
@@ -253,6 +253,32 @@ test('publishes one dark ShareDO projection, retained snapshot, then stable tier
   } finally { storage.close(); }
 });
 
+test('a current-file share closes over a verified local image and retains it for offline review', async () => {
+  const storage = await openStorage();
+  try {
+    const workspaceId = 'ws-v3-file-image'; await seedWorkspace(storage, workspaceId);
+    const png = new Uint8Array(24);
+    png.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    png.set([0, 0, 0, 2, 0, 0, 0, 2], 16);
+    await storage.workspaces.commitRevision({ workspaceId, path: 'assets/image.png', body: png });
+    await storage.workspaces.commitRevision({ workspaceId, path: 'notes/main.md',
+      body: new TextEncoder().encode('# Main\n\n![Diagram](../assets/image.png)\n') });
+    const fence = await acquireFence(storage, workspaceId); let relay: MemoryShareRelay | null = null;
+    const coordinator = new BrowserWorkspaceSharingCoordinator(storage, workspaceId, fence, {
+      now: () => NOW, randomBytes: deterministicRandom(), createRoom: async options => bootstrapFromOptions(options),
+      publish: options => publishBrowserSnapshots({ ...options, indexBuilder }), indexBuilder,
+      outboxFactory: ({ storage: db, credentials }) => new AckingOutbox(db, credentials.roomId),
+      shareRelayFactory: options => (relay ??= new MemoryShareRelay(options.shareId)),
+    });
+    const view = await coordinator.ensurePublished(request('file', ['notes/main.md']));
+    const rootKey = await storage.getWorkspaceRootKey(workspaceId); assert(rootKey, 'workspace key');
+    const capability = await storage.shares.openShare(rootKey, workspaceId, view.capId);
+    equal(capability.sharePaths, ['assets/image.png', 'notes/main.md'], 'file scope contains its image dependency');
+    assert(required<MemoryShareRelay>(relay, 'share relay').record?.snapshots.length === 2,
+      'durable projection retains both document and image');
+  } finally { storage.close(); }
+});
+
 test('commits on the first attempt when a deployed relay advances snapshot upload revisions', async () => {
   const storage = await openStorage();
   try {
diff --git a/web/src/lib/review/browser-workspace-sharing.ts b/web/src/lib/review/browser-workspace-sharing.ts
index 99c01b6c..fc724919 100644
--- a/web/src/lib/review/browser-workspace-sharing.ts
+++ b/web/src/lib/review/browser-workspace-sharing.ts
@@ -74,6 +74,16 @@ import {
   type ShareRecordView,
 } from './browser-workspace-share';
 import { compareManifestPathsUtf8 } from './browser-workspace-manifest';
+import { sharedAssetPathFor } from './asset-resolution';
+import { htmlImageSources, markdownImageSources } from './document-image-sources';
+import {
+  bytesMatchSharedImageMediaType,
+  hasSafeSharedImageDimensions,
+  isSupportedSharedImageMediaType,
+  MAX_SHARED_IMAGE_BYTES,
+  MAX_SHARED_IMAGE_COUNT,
+  MAX_SHARED_IMAGE_TOTAL_BYTES,
+} from './shared-image-policy';
 import { normalizeEntryPath, type ShareScopeKind, type WorkspaceEntryRecord } from './browser-workspace-schema';
 import type { LeaseHandle } from './browser-workspace-lease';
 import type { MailboxEnvelope } from './browser-ws';
@@ -533,15 +543,15 @@ export class BrowserWorkspaceSharingCoordinator {
     const sources = await this.loadSources(capability.sharePaths ?? []);
     const nextManifest: ManagedShareSnapshotRef[] = [];
     try {
-      const desired = new Map<string, { snapshotId: string; source: BrowserSnapshotEntry }>();
+      const desired = new Map<string, {
+        snapshotId: string;
+        source: BrowserSnapshotEntry;
+        entry: (typeof manifest.entries)[number];
+      }>();
       for (const entry of manifest.entries) {
         const source = sources.find((candidate) => candidate.path === entry.path);
         if (!source) throw new StorageConflictError('durable share source path disappeared');
-        // The current retained-snapshot plaintext format is text-bearing.
-        // Assets remain available through the live ordinary room; a later
-        // resolver extension may retain inert binary snapshots as well.
-        if (source.docType === 'asset') continue;
-        desired.set(entry.fileId, { snapshotId: entry.snapshotId, source });
+        desired.set(entry.fileId, { snapshotId: entry.snapshotId, source, entry });
       }
       for (const [fileId, wanted] of desired) {
         const retained = remote.snapshots.find(
@@ -551,17 +561,35 @@ export class BrowserWorkspaceSharingCoordinator {
           nextManifest.push(retained);
           continue;
         }
-        const content = new TextDecoder('utf-8', { fatal: true }).decode(wanted.source.bytes);
-        if (wanted.source.docType === 'asset') {
-          throw new StorageConflictError('durable text projection selected an asset');
-        }
-        const metadata = wanted.source.docType === 'markdown'
+        const content = wanted.source.docType === 'asset'
+          ? base64UrlEncode(wanted.source.bytes)
+          : new TextDecoder('utf-8', { fatal: true }).decode(wanted.source.bytes);
+        const anchorIndex = wanted.source.docType === 'markdown'
           ? await (this.dependencies.indexBuilder
               ?? (await import('./browser-anchor-index')).buildCanonicalAnchorIndex)(
                 wanted.source.bytes,
                 wanted.snapshotId,
               )
           : undefined;
+        const durableMetadata = {
+          ...(anchorIndex === undefined ? {} : { anchorIndex }),
+          baseHash: wanted.entry.contentHash,
+          ownerDisplayPath: wanted.entry.path,
+          createdAt: this.timestamp(),
+          ...(wanted.source.docType === 'asset'
+            ? {
+                manifestEntry: {
+                  fileId: wanted.entry.fileId,
+                  snapshotId: wanted.entry.snapshotId,
+                  path: wanted.entry.path,
+                  kind: 'asset',
+                  mediaType: wanted.source.mediaType,
+                  byteLength: wanted.source.bytes.length,
+                  contentHash: wanted.entry.contentHash,
+                },
+              }
+            : {}),
+        };
         const sealed = await sealDurableShareSnapshot({
           shareId: credentials.shareId,
           epoch: credentials.epoch,
@@ -569,7 +597,8 @@ export class BrowserWorkspaceSharingCoordinator {
           snapshotId: wanted.snapshotId,
           docType: wanted.source.docType,
           content,
-          metadata,
+          ...(wanted.source.docType === 'asset' ? { mediaType: wanted.source.mediaType } : {}),
+          metadata: durableMetadata,
           snapshotKey: credentials.keys.snapshotKey,
         });
         try {
@@ -772,31 +801,114 @@ export class BrowserWorkspaceSharingCoordinator {
   private async resolvePaths(scopeKind: ShareScopeKind, requested: readonly string[]): Promise<string[]> {
     const entries = await this.storage.workspaces.listEntries(this.workspaceId);
     const live = new Map(entries.map((entry) => [entry.path, entry]));
-    const paths = scopeKind === 'workspace'
+    const requestedPaths = scopeKind === 'workspace'
       ? entries.map((entry) => entry.path)
       : requested.map((path) => normalizeEntryPath(path));
-    if (scopeKind === 'file' && paths.length !== 1) {
+    if (scopeKind === 'file' && requestedPaths.length !== 1) {
       throw new BrowserStorageError('current-file share requires exactly one path');
     }
-    if (paths.length === 0) throw new BrowserStorageError('share scope cannot be empty');
-    if (new Set(paths).size !== paths.length) throw new BrowserStorageError('share scope contains duplicate paths');
-    for (const path of paths) if (!live.has(path)) throw new StorageConflictError('share scope contains a stale path');
-    if (!paths.some((path) => {
+    if (requestedPaths.length === 0) throw new BrowserStorageError('share scope cannot be empty');
+    if (new Set(requestedPaths).size !== requestedPaths.length) throw new BrowserStorageError('share scope contains duplicate paths');
+    for (const path of requestedPaths) if (!live.has(path)) throw new StorageConflictError('share scope contains a stale path');
+    if (!requestedPaths.some((path) => {
       const entry = live.get(path);
       return entry?.kind === 'markdown' || (entry !== undefined && entryIsHtml(entry));
     })) {
       throw new BrowserStorageError('share scope must contain at least one Markdown or HTML document');
     }
+    // A document scope is a dependency closure, not a hand-maintained file
+    // list. Only local, supported image assets that its document actually
+    // names are added; remote/missing/non-image srcs remain honest fallbacks.
+    const paths = new Set(requestedPaths);
+    const documentPaths = requestedPaths.filter((path) => {
+      const entry = live.get(path);
+      return entry?.kind === 'markdown' || (entry !== undefined && entryIsHtml(entry));
+    });
+    const images = await this.referencedImages(documentPaths, live);
+    for (const image of images) paths.add(image);
     return [...paths].sort(compareManifestPathsUtf8);
   }
 
+  private async referencedImages(
+    documentPaths: readonly string[],
+    live: ReadonlyMap<string, WorkspaceEntryRecord>,
+  ): Promise<string[]> {
+    if (documentPaths.length === 0) return [];
+    const candidates = new Set<string>();
+    let totalBytes = 0;
+    for (const documentPath of documentPaths) {
+      const entry = live.get(documentPath);
+      if (!entry) continue;
+      const body = await this.storage.workspaces.getRevisionBody(
+        this.workspaceId,
+        documentPath,
+        entry.headRevisionId,
+      );
+      let sources: string[];
+      try {
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(body);
+        sources = entry.kind === 'markdown' ? markdownImageSources(text) : htmlImageSources(text);
+      } catch {
+        sources = [];
+      } finally {
+        body.fill(0);
+      }
+      for (const src of sources) {
+        const path = sharedAssetPathFor(documentPath, src);
+        if (path === null || candidates.has(path)) continue;
+        const asset = live.get(path);
+        if (!asset || asset.kind !== 'asset' || !isSupportedSharedImageMediaType(asset.mediaType)) continue;
+        candidates.add(path);
+      }
+    }
+    const paths: string[] = [];
+    for (const path of candidates) {
+      if (paths.length >= MAX_SHARED_IMAGE_COUNT) break;
+      const entry = live.get(path);
+      if (!entry || entry.kind !== 'asset' || !entry.mediaType) continue;
+      const bytes = await this.storage.workspaces.getRevisionBody(this.workspaceId, path, entry.headRevisionId);
+      try {
+        if (
+          bytes.length > MAX_SHARED_IMAGE_BYTES
+          || totalBytes + bytes.length > MAX_SHARED_IMAGE_TOTAL_BYTES
+          || !bytesMatchSharedImageMediaType(bytes, entry.mediaType)
+          || !hasSafeSharedImageDimensions(bytes, entry.mediaType)
+        ) continue;
+        paths.push(path);
+        totalBytes += bytes.length;
+      } finally {
+        bytes.fill(0);
+      }
+    }
+    return paths;
+  }
+
   private async loadSources(paths: readonly string[]): Promise<BrowserSnapshotEntry[]> {
     const sources: BrowserSnapshotEntry[] = [];
+    let sharedImageCount = 0;
+    let sharedImageBytes = 0;
     try {
       for (const path of paths) {
         const entry = await this.storage.workspaces.getEntry(this.workspaceId, path);
         if (!entry) throw new StorageConflictError('share scope changed before publication');
         const bytes = await this.storage.workspaces.getRevisionBody(this.workspaceId, path, entry.headRevisionId);
+        if (entry.kind === 'asset' && isSupportedSharedImageMediaType(entry.mediaType)) {
+          if (
+            bytes.length > MAX_SHARED_IMAGE_BYTES
+            || sharedImageCount >= MAX_SHARED_IMAGE_COUNT
+            || sharedImageBytes + bytes.length > MAX_SHARED_IMAGE_TOTAL_BYTES
+            || !bytesMatchSharedImageMediaType(bytes, entry.mediaType!)
+            || !hasSafeSharedImageDimensions(bytes, entry.mediaType!)
+          ) {
+            // A stale or deliberately oversized local image must not make the
+            // whole document unshareable. Leave its authored src untouched;
+            // the reviewer gets the normal unavailable-image fallback instead.
+            bytes.fill(0);
+            continue;
+          }
+          sharedImageCount += 1;
+          sharedImageBytes += bytes.length;
+        }
         sources.push(entry.kind === 'markdown'
           ? { path, docType: 'markdown', bytes, revisionId: entry.headRevisionId }
           : entryIsHtml(entry)
diff --git a/web/src/lib/review/document-image-sources.test.ts b/web/src/lib/review/document-image-sources.test.ts
new file mode 100644
index 00000000..2ceb966b
--- /dev/null
+++ b/web/src/lib/review/document-image-sources.test.ts
@@ -0,0 +1,13 @@
+import { markdownImageSources, srcsetSources } from './document-image-sources';
+
+function equal(actual: readonly string[], expected: readonly string[], message: string): void {
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(`${message}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+equal(markdownImageSources('![Chart](assets/chart.png)\n![Chart](assets/chart.png)'), ['assets/chart.png'], 'Markdown dependencies are unique');
+equal(markdownImageSources('remote ![Chart](https://example.test/chart.png)'), ['https://example.test/chart.png'], 'discovery leaves policy to its caller');
+equal(srcsetSources('./chart.png 1x, ./chart@2x.png 2x'), ['./chart.png', './chart@2x.png'], 'srcset candidates retain URL tokens');
+
+console.log('document-image-sources: 3 passed, 0 failed');
diff --git a/web/src/lib/review/document-image-sources.ts b/web/src/lib/review/document-image-sources.ts
new file mode 100644
index 00000000..32693703
--- /dev/null
+++ b/web/src/lib/review/document-image-sources.ts
@@ -0,0 +1,39 @@
+import { markdownParser } from '../schema';
+
+/** Authored image URLs only; callers decide whether each may cross a boundary. */
+export function markdownImageSources(content: string): string[] {
+  const sources = new Set<string>();
+  try {
+    markdownParser.parse(content).descendants((node) => {
+      if (node.type.name === 'image' && typeof node.attrs.src === 'string') sources.add(node.attrs.src);
+    });
+  } catch {
+    // An invalid draft must not block editing or publishing the document; it
+    // simply has no discoverable local-image dependencies until it parses.
+  }
+  return [...sources];
+}
+
+/** HTML snapshots use the same relative-path rules as Markdown images. */
+export function htmlImageSources(content: string): string[] {
+  if (typeof DOMParser === 'undefined') return [];
+  const sources = new Set<string>();
+  const document = new DOMParser().parseFromString(content, 'text/html');
+  for (const image of document.querySelectorAll<HTMLImageElement>('img[src]')) {
+    const src = image.getAttribute('src');
+    if (src) sources.add(src);
+  }
+  for (const source of document.querySelectorAll<HTMLSourceElement>('img[srcset], source[srcset]')) {
+    const srcset = source.getAttribute('srcset');
+    if (!srcset) continue;
+    for (const src of srcsetSources(srcset)) sources.add(src);
+  }
+  return [...sources];
+}
+
+export function srcsetSources(srcset: string): string[] {
+  return srcset.split(',').flatMap((candidate) => {
+    const match = /^\s*(\S+)/u.exec(candidate);
+    return match ? [match[1]!] : [];
+  });
+}
diff --git a/web/src/lib/review/html-shared-assets.test.ts b/web/src/lib/review/html-shared-assets.test.ts
new file mode 100644
index 00000000..cac60fca
--- /dev/null
+++ b/web/src/lib/review/html-shared-assets.test.ts
@@ -0,0 +1,20 @@
+import { rewriteSrcset } from './html-shared-assets';
+
+function assertEqual(actual: string, expected: string, message: string): void {
+  if (actual !== expected) throw new Error(`${message}: expected ${expected}, got ${actual}`);
+}
+
+const resolve = (src: string): string | null => src === './chart.png' ? 'blob:verified-chart' : null;
+
+assertEqual(
+  rewriteSrcset('./chart.png 1x, remote.png 2x', resolve),
+  'blob:verified-chart 1x, remote.png 2x',
+  'srcset replaces only a verified local candidate',
+);
+assertEqual(
+  rewriteSrcset(' data:image/png;base64,AAAA 1x', resolve),
+  ' data:image/png;base64,AAAA 1x',
+  'unresolved data source stays byte-for-byte intact',
+);
+
+console.log('html-shared-assets: 2 passed, 0 failed');
diff --git a/web/src/lib/review/html-shared-assets.ts b/web/src/lib/review/html-shared-assets.ts
new file mode 100644
index 00000000..13d2aac2
--- /dev/null
+++ b/web/src/lib/review/html-shared-assets.ts
@@ -0,0 +1,34 @@
+/**
+ * Rewrites only share-bound HTML image URLs. The source remains inside a
+ * sandboxed opaque-origin iframe; remote, data, and absent local references
+ * remain untouched so no new network capability is introduced here.
+ */
+export function rewriteSharedHtmlImageSources(
+  content: string,
+  resolveAssetUrl: ((src: string) => string | null) | undefined,
+): string {
+  if (!resolveAssetUrl || typeof DOMParser === 'undefined') return content;
+  const document = new DOMParser().parseFromString(content, 'text/html');
+  for (const image of document.querySelectorAll<HTMLImageElement>('img[src]')) {
+    const resolved = resolveAssetUrl(image.getAttribute('src') ?? '');
+    if (resolved !== null) image.setAttribute('src', resolved);
+  }
+  for (const source of document.querySelectorAll<HTMLSourceElement>('img[srcset], source[srcset]')) {
+    const srcset = source.getAttribute('srcset');
+    if (srcset !== null) source.setAttribute('srcset', rewriteSrcset(srcset, resolveAssetUrl));
+  }
+  return `<!doctype html>\n${document.documentElement.outerHTML}`;
+}
+
+/** Keep each candidate descriptor intact while replacing its URL token. */
+export function rewriteSrcset(
+  srcset: string,
+  resolveAssetUrl: (src: string) => string | null,
+): string {
+  return srcset.split(',').map((candidate) => {
+    const match = /^(\s*)(\S+)([\s\S]*)$/u.exec(candidate);
+    if (!match) return candidate;
+    const resolved = resolveAssetUrl(match[2]!);
+    return resolved === null ? candidate : `${match[1]}${resolved}${match[3]}`;
+  }).join(',');
+}
diff --git a/web/src/lib/review/shared-image-policy.test.ts b/web/src/lib/review/shared-image-policy.test.ts
new file mode 100644
index 00000000..432a666a
--- /dev/null
+++ b/web/src/lib/review/shared-image-policy.test.ts
@@ -0,0 +1,31 @@
+import {
+  bytesMatchSharedImageMediaType,
+  hasSafeSharedImageDimensions,
+  isSupportedSharedImageMediaType,
+  MAX_SHARED_IMAGE_BYTES,
+  MAX_SHARED_IMAGE_COUNT,
+  MAX_SHARED_IMAGE_TOTAL_BYTES,
+} from './shared-image-policy';
+
+function assert(value: unknown, message: string): asserts value {
+  if (!value) throw new Error(message);
+}
+
+assert(isSupportedSharedImageMediaType('image/png'), 'PNG is allowlisted');
+assert(isSupportedSharedImageMediaType('IMAGE/AVIF'), 'media type comparison is case-insensitive');
+assert(!isSupportedSharedImageMediaType('image/tiff'), 'unsupported image types cannot enter a share');
+assert(!isSupportedSharedImageMediaType('text/html'), 'document media cannot enter a share as an image');
+assert(bytesMatchSharedImageMediaType(new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), 'image/png'), 'PNG signature is checked');
+assert(!bytesMatchSharedImageMediaType(new Uint8Array([0, 1, 2, 3]), 'image/png'), 'mismatched bytes are rejected');
+assert(bytesMatchSharedImageMediaType(new TextEncoder().encode('  <svg viewBox="0 0 1 1"/>'), 'image/svg+xml'), 'SVG accepts leading whitespace');
+const png = new Uint8Array(24);
+png.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+png.set([0, 0, 0, 100, 0, 0, 0, 200], 16);
+assert(hasSafeSharedImageDimensions(png, 'image/png'), 'bounded PNG dimensions are accepted');
+png.set([0, 0, 0x27, 0x10, 0, 0, 0x27, 0x10], 16);
+assert(!hasSafeSharedImageDimensions(png, 'image/png'), 'oversized raster dimensions are refused before decoding');
+assert(!hasSafeSharedImageDimensions(new Uint8Array(8), 'image/png'), 'unknown raster dimensions fail closed');
+assert(MAX_SHARED_IMAGE_BYTES === 3 * 1024 * 1024, 'single-image cap preserves encrypted-envelope headroom');
+assert(MAX_SHARED_IMAGE_COUNT === 64 && MAX_SHARED_IMAGE_TOTAL_BYTES === 16 * 1024 * 1024, 'aggregate image budgets are bounded');
+
+console.log('shared-image-policy: 12 passed, 0 failed');
diff --git a/web/src/lib/review/shared-image-policy.ts b/web/src/lib/review/shared-image-policy.ts
new file mode 100644
index 00000000..42a5f940
--- /dev/null
+++ b/web/src/lib/review/shared-image-policy.ts
@@ -0,0 +1,166 @@
+// Shared-image policy kept deliberately below the encrypted transport limits.
+// Assets are represented as canonical base64url inside snapshot JSON, so the
+// 5 MiB relay ciphertext ceiling cannot safely admit an 8 MiB raw image.
+
+export const MAX_SHARED_IMAGE_BYTES = 3 * 1024 * 1024;
+export const MAX_SHARED_IMAGE_COUNT = 64;
+export const MAX_SHARED_IMAGE_TOTAL_BYTES = 16 * 1024 * 1024;
+export const MAX_SHARED_IMAGE_PIXELS = 40_000_000;
+
+const IMAGE_MEDIA_TYPES = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/avif',
+  'image/bmp',
+  'image/x-icon',
+  'image/svg+xml',
+]);
+
+export function isSupportedSharedImageMediaType(mediaType: string | undefined): boolean {
+  return mediaType !== undefined && IMAGE_MEDIA_TYPES.has(mediaType.toLowerCase());
+}
+
+/** Lightweight content checks before encrypted publication. Rendering remains
+ * in an image context; SVG never receives a script-capable document context. */
+export function bytesMatchSharedImageMediaType(bytes: Uint8Array, mediaType: string): boolean {
+  switch (mediaType.toLowerCase()) {
+    case 'image/png':
+      return startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    case 'image/jpeg':
+      return startsWith(bytes, [0xff, 0xd8, 0xff]);
+    case 'image/gif':
+      return startsWith(bytes, text('GIF87a')) || startsWith(bytes, text('GIF89a'));
+    case 'image/webp':
+      return startsWith(bytes, text('RIFF')) && startsWith(bytes.subarray(8), text('WEBP'));
+    case 'image/avif':
+      return bytes.length >= 12 && startsWith(bytes.subarray(4), text('ftyp'))
+        && ['avif', 'avis'].includes(new TextDecoder().decode(bytes.subarray(8, 12)));
+    case 'image/bmp':
+      return startsWith(bytes, text('BM'));
+    case 'image/x-icon':
+      return startsWith(bytes, [0, 0, 1, 0]);
+    case 'image/svg+xml':
+      return new TextDecoder('utf-8', { fatal: false }).decode(bytes.subarray(0, 1024))
+        .replace(/^\uFEFF?\s*/u, '').startsWith('<svg');
+    default:
+      return false;
+  }
+}
+
+/** Refuse a tiny decompression bomb before it can reach an image decoder. SVG
+ * remains a vector image in a sandboxed image context, so the byte cap is its
+ * relevant resource bound. Unknown raster dimensions fail closed. */
+export function hasSafeSharedImageDimensions(bytes: Uint8Array, mediaType: string): boolean {
+  if (mediaType.toLowerCase() === 'image/svg+xml') return true;
+  const dimensions = rasterDimensions(bytes, mediaType.toLowerCase());
+  return dimensions !== null
+    && dimensions[0] > 0
+    && dimensions[1] > 0
+    && dimensions[0] * dimensions[1] <= MAX_SHARED_IMAGE_PIXELS;
+}
+
+function rasterDimensions(bytes: Uint8Array, mediaType: string): [number, number] | null {
+  switch (mediaType) {
+    case 'image/png':
+      return bytes.length >= 24 ? [u32be(bytes, 16), u32be(bytes, 20)] : null;
+    case 'image/gif':
+      return bytes.length >= 10 ? [u16le(bytes, 6), u16le(bytes, 8)] : null;
+    case 'image/jpeg':
+      return jpegDimensions(bytes);
+    case 'image/webp':
+      return webpDimensions(bytes);
+    case 'image/avif':
+      return ispeDimensions(bytes);
+    case 'image/bmp':
+      return bytes.length >= 26 ? [i32le(bytes, 18), Math.abs(i32le(bytes, 22))] : null;
+    case 'image/x-icon':
+      return bytes.length >= 8
+        ? [bytes[6] === 0 ? 256 : bytes[6]!, bytes[7] === 0 ? 256 : bytes[7]!]
+        : null;
+    default:
+      return null;
+  }
+}
+
+function jpegDimensions(bytes: Uint8Array): [number, number] | null {
+  let offset = 2;
+  while (offset + 9 < bytes.length) {
+    if (bytes[offset] !== 0xff) return null;
+    while (bytes[offset] === 0xff) offset += 1;
+    const marker = bytes[offset++]!;
+    if (marker === 0xd8 || marker === 0xd9) continue;
+    if (offset + 1 >= bytes.length) return null;
+    const length = u16be(bytes, offset);
+    if (length < 2 || offset + length > bytes.length) return null;
+    // Start-of-frame markers except the non-frame DHT/DAC/JPG markers.
+    if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+      return offset + 7 < bytes.length ? [u16be(bytes, offset + 5), u16be(bytes, offset + 3)] : null;
+    }
+    offset += length;
+  }
+  return null;
+}
+
+function webpDimensions(bytes: Uint8Array): [number, number] | null {
+  if (bytes.length < 30) return null;
+  const chunk = decodeAscii(bytes.subarray(12, 16));
+  if (chunk === 'VP8X') {
+    return [u24le(bytes, 24) + 1, u24le(bytes, 27) + 1];
+  }
+  if (chunk === 'VP8 ') {
+    return [u16le(bytes, 26) & 0x3fff, u16le(bytes, 28) & 0x3fff];
+  }
+  if (chunk === 'VP8L' && bytes.length >= 25 && bytes[20] === 0x2f) {
+    const packed = bytes[21]! | (bytes[22]! << 8) | (bytes[23]! << 16) | (bytes[24]! << 24);
+    return [(packed & 0x3fff) + 1, ((packed >>> 14) & 0x3fff) + 1];
+  }
+  return null;
+}
+
+function ispeDimensions(bytes: Uint8Array): [number, number] | null {
+  // `ispe` carries a FullBox (version+flags) followed by width and height.
+  for (let index = 4; index + 16 <= bytes.length && index < 64 * 1024; index += 1) {
+    if (decodeAscii(bytes.subarray(index, index + 4)) === 'ispe') {
+      return [u32be(bytes, index + 8), u32be(bytes, index + 12)];
+    }
+  }
+  return null;
+}
+
+function u16be(bytes: Uint8Array, offset: number): number {
+  return (bytes[offset]! << 8) | bytes[offset + 1]!;
+}
+
+function u16le(bytes: Uint8Array, offset: number): number {
+  return bytes[offset]! | (bytes[offset + 1]! << 8);
+}
+
+function u24le(bytes: Uint8Array, offset: number): number {
+  return bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16);
+}
+
+function i32le(bytes: Uint8Array, offset: number): number {
+  return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24));
+}
+
+function u32be(bytes: Uint8Array, offset: number): number {
+  return ((bytes[offset]! * 0x1_0000_00) + (bytes[offset + 1]! << 16) + (bytes[offset + 2]! << 8) + bytes[offset + 3]!) >>> 0;
+}
+
+function decodeAscii(bytes: Uint8Array): string {
+  return String.fromCharCode(...bytes);
+}
+
+function startsWith(bytes: Uint8Array, prefix: ArrayLike<number>): boolean {
+  if (bytes.length < prefix.length) return false;
+  for (let index = 0; index < prefix.length; index += 1) {
+    if (bytes[index] !== prefix[index]) return false;
+  }
+  return true;
+}
+
+function text(value: string): Uint8Array {
+  return new TextEncoder().encode(value);
+}

From 055e73f4df25514ffd04beee1a2a3d900d1c5546 Mon Sep 17 00:00:00 2001
From: Angus Bezzina <37071175+angusbezzina@users.noreply.github.com>
Date: Tue, 1 Sep 2026 21:43:15 -0500
Subject: [PATCH 05/10] Harden hosted share image rendering

---
 web/scripts/test-hosted-local-share-ui.ts     | 207 +++++++++++++++++-
 web/src/BrowserReviewApp.svelte               |  12 +-
 web/src/hosted/app/EditorShell.svelte         |  66 ++++--
 web/src/lib/HtmlViewer.svelte                 |  26 ++-
 .../lib/prosemirror/image-nodeview.test.ts    |   4 +-
 web/src/lib/prosemirror/image-nodeview.ts     |  11 +-
 web/src/lib/review/asset-resolution.test.ts   |  22 +-
 web/src/lib/review/asset-resolution.ts        |  15 +-
 .../lib/review/browser-asset-registry.test.ts |   7 +-
 web/src/lib/review/browser-asset-registry.ts  |  11 +
 web/src/lib/review/html-shared-assets.test.ts |   9 +-
 web/src/lib/review/html-shared-assets.ts      |  33 ++-
 web/src/lib/review/image-data-url.ts          |  32 +++
 .../lib/review/shared-image-policy.test.ts    |   2 +
 web/src/lib/review/shared-image-policy.ts     |   6 +
 15 files changed, 404 insertions(+), 59 deletions(-)
 create mode 100644 web/src/lib/review/image-data-url.ts

diff --git a/web/scripts/test-hosted-local-share-ui.ts b/web/scripts/test-hosted-local-share-ui.ts
index 764669ec..1de38c2a 100644
--- a/web/scripts/test-hosted-local-share-ui.ts
+++ b/web/scripts/test-hosted-local-share-ui.ts
@@ -21,7 +21,7 @@ import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { once } from 'node:events';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { chromium, type BrowserContext, type Page } from '@playwright/test';
+import { chromium, expect, type BrowserContext, type Page } from '@playwright/test';
 
 const webRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const relayRoot = path.resolve(webRoot, '..', 'relay');
@@ -31,12 +31,20 @@ const relayUrl = `http://127.0.0.1:${relayPort}`;
 const appUrl = `http://127.0.0.1:${appPort}`;
 const commentMarker = 'LOCAL-OWNER-REVIEW-COMMENT-9173';
 const suggestionMarker = 'LOCAL-OWNER-REVIEW-SUGGESTION-9173';
+const sharedImageSource = '../images/pixel.png';
+const remoteImageSource = 'https://images.attn.invalid/remote-share-image.png';
+const unresolvedImageSource = 'data:;base64,';
+const sharedPng = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==',
+  'base64',
+);
 const useExternalServers = process.env.ATTN_SHARE_UI_EXTERNAL === '1';
 
 let relay: ChildProcessWithoutNullStreams | null = null;
 let app: ChildProcessWithoutNullStreams | null = null;
 let ownerContext: BrowserContext | null = null;
 let reviewerContext: BrowserContext | null = null;
+let offlineReviewerContext: BrowserContext | null = null;
 let browser: Awaited<ReturnType<typeof chromium.launch>> | null = null;
 const diagnostics: string[] = [];
 // Playwright's locator waits use unref'd timers. Keep a real handle while the
@@ -99,6 +107,13 @@ function captureBrowserFailures(page: Page, label: string): void {
   });
 }
 
+function seedProfileDisplayName({ displayName }: { displayName: string }): void {
+  // Playwright init scripts also run inside `srcdoc` frames. Those frames are
+  // intentionally opaque-origin, where touching localStorage throws.
+  if (window.location.protocol !== 'http:' && window.location.protocol !== 'https:') return;
+  localStorage.setItem('attn.profile.displayName', displayName);
+}
+
 async function selectText(page: Page, needle: string): Promise<void> {
   const result = await page.evaluate((text) => {
     const view = (window as unknown as { __attnPmView?: { dom: HTMLElement } }).__attnPmView;
@@ -126,6 +141,69 @@ async function selectText(page: Page, needle: string): Promise<void> {
   await page.locator('[data-slot="selection-toolbar"]').waitFor({ state: 'visible' });
 }
 
+async function expectResolvedSharedImage(page: Page, label: string): Promise<void> {
+  const wrapper = page.locator(`.md-image[data-src="${sharedImageSource}"]`);
+  await wrapper.waitFor({ state: 'attached', timeout: 60_000 });
+  await page.waitForFunction(
+    (source) => document.querySelector(`.md-image[data-src="${source}"]`)?.getAttribute('data-loaded') === 'true',
+    sharedImageSource,
+    { timeout: 60_000 },
+  );
+  const image = wrapper.locator('img');
+  await image.waitFor({ state: 'visible', timeout: 60_000 });
+  const detail = await image.evaluate((element) => {
+    const imageElement = element as HTMLImageElement;
+    return {
+      src: imageElement.getAttribute('src'),
+      width: imageElement.naturalWidth,
+      height: imageElement.naturalHeight,
+      loaded: imageElement.parentElement?.getAttribute('data-loaded'),
+    };
+  });
+  if (detail.loaded !== 'true' || detail.width !== 1 || detail.height !== 1 || !detail.src?.startsWith('blob:')) {
+    throw new Error(`${label} did not render the verified local image: ${JSON.stringify(detail)}`);
+  }
+}
+
+async function expectBlockedRemoteImage(page: Page, label: string): Promise<void> {
+  const image = page.locator(`.md-image[data-src="${remoteImageSource}"] img`);
+  await image.waitFor({ state: 'attached', timeout: 60_000 });
+  await image.waitFor({ state: 'hidden', timeout: 60_000 });
+  const detail = await image.evaluate((element) => ({
+    src: element.getAttribute('src'),
+    broken: element.parentElement?.getAttribute('data-broken'),
+  }));
+  if (detail.src !== unresolvedImageSource || detail.broken !== 'true') {
+    throw new Error(`${label} did not retain a no-network remote-image fallback: ${JSON.stringify(detail)}`);
+  }
+}
+
+async function expectResolvedSharedHtmlImages(page: Page, label: string): Promise<void> {
+  const frame = page.frameLocator('[data-slot="html-viewer"] iframe');
+  const verified = frame.locator('#verified-html-image');
+  await expect(verified).toBeVisible({ timeout: 60_000 });
+  await expect(verified).toHaveJSProperty('naturalWidth', 1, { timeout: 60_000 });
+  await expect(verified).toHaveJSProperty('naturalHeight', 1, { timeout: 60_000 });
+  await expect(verified).toHaveAttribute('src', /^data:image\/png;base64,/u);
+
+  const pictureImage = frame.locator('#picture-html-image');
+  await expect(pictureImage).toBeVisible({ timeout: 60_000 });
+  await expect(pictureImage).toHaveJSProperty('naturalWidth', 1, { timeout: 60_000 });
+  const source = frame.locator('#verified-html-source');
+  const srcset = await source.getAttribute('srcset');
+  if (!srcset?.includes('data:image/png;base64,') || !srcset.includes(unresolvedImageSource)) {
+    throw new Error(`${label} did not rewrite picture srcset safely: ${JSON.stringify(srcset)}`);
+  }
+
+  const remote = frame.locator('#remote-html-image');
+  await expect(remote).toHaveAttribute('src', unresolvedImageSource, { timeout: 60_000 });
+  await expect(remote).toHaveJSProperty('naturalWidth', 0, { timeout: 60_000 });
+  const sandbox = await page.locator('[data-slot="html-viewer"] iframe').getAttribute('sandbox');
+  if (sandbox?.includes('allow-same-origin')) {
+    throw new Error(`${label} weakened the opaque-origin HTML sandbox: ${sandbox}`);
+  }
+}
+
 async function waitForOwnerTextRebase(
   page: Page,
   replacement: string,
@@ -157,10 +235,11 @@ async function currentWorkspaceId(page: Page): Promise<string> {
   return id;
 }
 
-async function createInvite(owner: Page): Promise<string> {
+async function createInvite(owner: Page, options: { selectAll?: boolean } = {}): Promise<string> {
   await owner.locator('[data-slot="owner-header-share"]').click();
   const dialog = owner.getByRole('dialog', { name: 'Share files for review' });
   await dialog.waitFor({ state: 'visible' });
+  if (options.selectAll) await dialog.getByRole('button', { name: 'Select all' }).click();
   await dialog.getByRole('button', { name: /Create review link/u }).click();
   await dialog.locator('select[aria-label="What this link allows"]').selectOption('suggest');
   const chip = dialog.locator('.share-link-chip');
@@ -216,9 +295,7 @@ async function main(): Promise<void> {
   // The product correctly asks a first-time owner to choose a display name
   // after a room becomes active. This lifecycle gate is about durable review
   // convergence, so provide that ordinary prerequisite before navigation.
-  await ownerContext.addInitScript(() => {
-    localStorage.setItem('attn.profile.displayName', 'Owner agent');
-  });
+  await ownerContext.addInitScript(seedProfileDisplayName, { displayName: 'Owner agent' });
   const owner = await ownerContext.newPage();
   captureBrowserFailures(owner, 'owner');
   await owner.goto(`${appUrl}/app#new`, { waitUntil: 'domcontentloaded' });
@@ -252,9 +329,7 @@ async function main(): Promise<void> {
   step('owner passive tab and Desk opened before review activity');
 
   reviewerContext = await browser.newContext({ viewport: { width: 1440, height: 900 } });
-  await reviewerContext.addInitScript(() => {
-    localStorage.setItem('attn.profile.displayName', 'Review agent');
-  });
+  await reviewerContext.addInitScript(seedProfileDisplayName, { displayName: 'Review agent' });
   const reviewer = await reviewerContext.newPage();
   captureBrowserFailures(reviewer, 'reviewer');
   await reviewer.goto(invite, { waitUntil: 'domcontentloaded' });
@@ -363,10 +438,123 @@ async function main(): Promise<void> {
   });
   step('resolved history survived reviewer disconnect and reload');
 
+  // Run image behavior in a fresh one-document workspace so the established
+  // comment/suggestion lifecycle above remains an independent baseline.
+  const imageOwner = await ownerContext.newPage();
+  captureBrowserFailures(imageOwner, 'image owner');
+  const remoteRequests: string[] = [];
+  imageOwner.on('request', (request) => {
+    if (request.url().startsWith(remoteImageSource)) remoteRequests.push(request.url());
+  });
+  await imageOwner.goto(`${appUrl}/app#new`, { waitUntil: 'domcontentloaded' });
+  await imageOwner.locator('input[type="file"][multiple][accept*="image"]').setInputFiles([
+    {
+      name: 'docs/review.md',
+      mimeType: 'text/markdown',
+      buffer: Buffer.from(
+        `# Hosted image share\n\n![Verified chart](${sharedImageSource})\n\n![Remote fallback](${remoteImageSource})\n\n`,
+      ),
+    },
+    {
+      name: 'docs/preview.html',
+      mimeType: 'text/html',
+      buffer: Buffer.from(
+        `<!doctype html><html><body>
+          <img id="verified-html-image" src="${sharedImageSource}" alt="Verified chart">
+          <picture>
+            <source id="verified-html-source" srcset="${sharedImageSource} 1x, ${remoteImageSource} 2x">
+            <img id="picture-html-image" src="${sharedImageSource}" alt="Picture chart">
+          </picture>
+          <img id="remote-html-image" src="${remoteImageSource}" alt="Remote fallback">
+        </body></html>`,
+      ),
+    },
+    { name: 'images/pixel.png', mimeType: 'image/png', buffer: sharedPng },
+  ]);
+  await imageOwner.getByRole('button', { name: 'review.md', exact: true }).waitFor({ state: 'visible' });
+  await expectResolvedSharedImage(imageOwner, 'local owner');
+  await expectBlockedRemoteImage(imageOwner, 'local owner');
+  await imageOwner.getByRole('button', { name: 'preview.html', exact: true }).click();
+  await expectResolvedSharedHtmlImages(imageOwner, 'local owner HTML document');
+  await imageOwner.getByRole('button', { name: 'review.md', exact: true }).click();
+  if (remoteRequests.length > 0) {
+    throw new Error(`local owner fetched a blocked remote image: ${JSON.stringify(remoteRequests)}`);
+  }
+  const imageInvite = await createInvite(imageOwner, { selectAll: true });
+
+  reviewerContext = await browser.newContext({ viewport: { width: 1440, height: 900 } });
+  await reviewerContext.addInitScript(seedProfileDisplayName, { displayName: 'Image review agent' });
+  const imageReviewer = await reviewerContext.newPage();
+  captureBrowserFailures(imageReviewer, 'image reviewer');
+  await imageReviewer.goto(imageInvite, { waitUntil: 'domcontentloaded' });
+  await imageReviewer.locator('[data-slot="browser-review"]').waitFor({ state: 'visible' });
+  await imageReviewer.waitForFunction(() => document.querySelector('[data-slot="browser-review"]')?.getAttribute('data-authoring-ready') === 'true');
+  await imageReviewer.getByRole('button', { name: /review\.md/u }).click();
+  await expectResolvedSharedImage(imageReviewer, 'live invited reviewer');
+  await expectBlockedRemoteImage(imageReviewer, 'live invited reviewer');
+  await imageReviewer.getByRole('button', { name: /preview\.html/u }).click();
+  await expectResolvedSharedHtmlImages(imageReviewer, 'live invited reviewer HTML document');
+
+  // A second reviewer tab owns a distinct in-memory Blob registry.
+  const follower = await reviewerContext.newPage();
+  captureBrowserFailures(follower, 'image follower');
+  await follower.goto(imageInvite, { waitUntil: 'domcontentloaded' });
+  await follower.locator('[data-slot="browser-review"]').waitFor({ state: 'visible' });
+  await follower.getByRole('button', { name: /review\.md/u }).click();
+  await expectResolvedSharedImage(follower, 'follower reviewer tab');
+  await expectBlockedRemoteImage(follower, 'follower reviewer tab');
+  await follower.close();
+
+  // Reload destroys the reviewer surface and its Blob URLs. The fresh page
+  // must hydrate and bind the asset again from the retained durable share.
+  await imageReviewer.reload({ waitUntil: 'domcontentloaded' });
+  await imageReviewer.locator('[data-slot="browser-review"]').waitFor({ state: 'visible' });
+  await imageReviewer.waitForFunction(() => document.querySelector('[data-slot="browser-review"]')?.getAttribute('data-authoring-ready') === 'true');
+  await expectResolvedSharedHtmlImages(imageReviewer, 'reloaded invited reviewer HTML document');
+  await imageReviewer.getByRole('button', { name: /review\.md/u }).click();
+  await expectResolvedSharedImage(imageReviewer, 'reloaded invited reviewer');
+  await expectBlockedRemoteImage(imageReviewer, 'reloaded invited reviewer');
+  await reviewerContext.close();
+  reviewerContext = null;
+
+  // Once every owner page is gone, a fresh reviewer has no ordinary live
+  // owner connection to borrow. The stable share must restore its document
+  // and image from the retained durable projection, then do it again after a
+  // browser reload with an empty in-memory Blob registry.
+  await ownerContext.close();
+  ownerContext = null;
+  offlineReviewerContext = await browser.newContext({ viewport: { width: 1440, height: 900 } });
+  await offlineReviewerContext.addInitScript(seedProfileDisplayName, { displayName: 'Offline review agent' });
+  const offlineReviewer = await offlineReviewerContext.newPage();
+  captureBrowserFailures(offlineReviewer, 'offline reviewer');
+  await offlineReviewer.goto(imageInvite, { waitUntil: 'domcontentloaded' });
+  const offlineShell = offlineReviewer.locator('[data-slot="browser-review"]');
+  await offlineShell.waitFor({ state: 'visible' });
+  await offlineShell.waitFor({ state: 'attached' });
+  await offlineReviewer.waitForFunction(() => document.querySelector('[data-slot="browser-review"]')?.getAttribute('data-owner-online') === 'false');
+  await offlineReviewer.getByRole('button', { name: /preview\.html/u }).click();
+  await expectResolvedSharedHtmlImages(offlineReviewer, 'owner-offline durable reviewer HTML document');
+  await offlineReviewer.getByRole('button', { name: /review\.md/u }).click();
+  await expectResolvedSharedImage(offlineReviewer, 'owner-offline durable reviewer');
+  await expectBlockedRemoteImage(offlineReviewer, 'owner-offline durable reviewer');
+  await offlineReviewer.reload({ waitUntil: 'domcontentloaded' });
+  await offlineReviewer.locator('[data-slot="browser-review"]').waitFor({ state: 'visible' });
+  await offlineReviewer.waitForFunction(() => document.querySelector('[data-slot="browser-review"]')?.getAttribute('data-owner-online') === 'false');
+  await expectResolvedSharedImage(offlineReviewer, 'reloaded owner-offline durable reviewer');
+  await expectBlockedRemoteImage(offlineReviewer, 'reloaded owner-offline durable reviewer');
+  step('hosted image share survived follower, reload, and owner-offline durable review');
+
   if (diagnostics.some((line) => /\[attn drift\]/u.test(line))) {
     throw new Error(`projection drift detected:\n${diagnostics.filter((line) => /\[attn drift\]/u.test(line)).join('\n')}`);
   }
-  const browserErrors = diagnostics.filter((line) => /(?:page error:|console error:)/u.test(line));
+  // The blocked image source intentionally uses a malformed local data URL so
+  // the existing image fallback card appears without issuing a network fetch.
+  // Chromium reports that parse failure on the console; the DOM assertions
+  // above prove it is exactly this policy fallback, not a failed shared asset.
+  const browserErrors = diagnostics.filter((line) => (
+    /(?:page error:|console error:)/u.test(line)
+    && !/console error: Failed to load resource: net::ERR_(?:INVALID_URL|FILE_NOT_FOUND)/u.test(line)
+  ));
   if (browserErrors.length > 0) {
     throw new Error(`browser errors detected:\n${browserErrors.join('\n')}`);
   }
@@ -381,6 +569,7 @@ try {
   if (relevant.length > 0) console.error(relevant.join(''));
   process.exitCode = 1;
 } finally {
+  await offlineReviewerContext?.close();
   await reviewerContext?.close();
   await ownerContext?.close();
   await browser?.close();
diff --git a/web/src/BrowserReviewApp.svelte b/web/src/BrowserReviewApp.svelte
index 81513a11..de870176 100644
--- a/web/src/BrowserReviewApp.svelte
+++ b/web/src/BrowserReviewApp.svelte
@@ -61,6 +61,7 @@
   import { deriveFileEntries, latestRenderableSnapshotId } from './lib/review/file-nav';
   import { reviewerStatusPresentation } from './lib/review/reviewer-status-model';
   import { buildSharedAssetResolver } from './lib/review/asset-resolution';
+  import { browserAssetRegistry } from './lib/review/browser-asset-registry';
   import { reviewStore } from './lib/review/store.svelte';
   import {
     applyReviewHoverHighlight,
@@ -654,6 +655,15 @@
     const docWirePath = displayedSnapshot?.ownerDisplayPath;
     return buildSharedAssetResolver(snapshots, roomId, docWirePath);
   });
+  const resolveReviewHtmlAssetUrl = $derived.by(() => {
+    return buildSharedAssetResolver(
+      reviewStore.snapshots,
+      sessionState.roomId,
+      displayedSnapshot?.ownerDisplayPath,
+      browserAssetRegistry,
+      'opaque-sandbox',
+    );
+  });
 
   $effect(() => {
     void sessionState.roomId;
@@ -1706,7 +1716,7 @@
                 <HtmlViewer
                   content={displayedContent ?? ''}
                   allowScripts={false}
-                  resolveAssetUrl={resolveReviewAssetUrl}
+                  resolveAssetUrl={resolveReviewHtmlAssetUrl}
                   annotate={htmlAnnotatable}
                   annotationEvents={htmlAnnotationEvents}
                   onBridge={(bridge) => (htmlBridge = bridge)}
diff --git a/web/src/hosted/app/EditorShell.svelte b/web/src/hosted/app/EditorShell.svelte
index 88b2ff30..fdf614e4 100644
--- a/web/src/hosted/app/EditorShell.svelte
+++ b/web/src/hosted/app/EditorShell.svelte
@@ -57,6 +57,7 @@
   import { peerJumpPosition } from '../../lib/peer-strip-format';
   import { attachCollabPresenceSinks } from '../../lib/prosemirror/collab-presence-sinks';
   import { sharedAssetPathFor } from '../../lib/review/asset-resolution';
+  import { sharedImageDataUrl } from '../../lib/review/image-data-url';
   import { htmlImageSources, markdownImageSources } from '../../lib/review/document-image-sources';
   import { isSupportedSharedImageMediaType } from '../../lib/review/shared-image-policy';
   import LoadingLine from './LoadingLine.svelte';
@@ -381,7 +382,12 @@
   // remain the source of truth and a missing/rejected asset keeps the normal
   // image fallback.
   let localAssetUrls = $state<Record<string, string>>({});
-  let ownedAssetUrls = new Map<string, string>();
+  let localHtmlAssetUrls = $state<Record<string, string>>({});
+  interface LocalAssetUrl {
+    blobUrl: string;
+    htmlDataUrl: string;
+  }
+  let ownedAssetUrls = new Map<string, LocalAssetUrl>();
   const resolveLocalAssetUrl = $derived.by(() => {
     const documentPath = activeEntry?.path;
     const urls = localAssetUrls;
@@ -391,6 +397,15 @@
       return path === null ? null : urls[path] ?? null;
     };
   });
+  const resolveLocalHtmlAssetUrl = $derived.by(() => {
+    const documentPath = activeEntry?.path;
+    const urls = localHtmlAssetUrls;
+    if (!documentPath) return () => null;
+    return (src: string): string | null => {
+      const path = sharedAssetPathFor(documentPath, src);
+      return path === null ? null : urls[path] ?? null;
+    };
+  });
 
   /* The empty-canvas invitation (attn-mkmz.5). A brand-new workspace lands on a
      blank untitled.md, and the only standing offer to bring a real document in
@@ -834,17 +849,22 @@
   });
 
   // Resolve local image dependencies through OPFS into short-lived Blob URLs
-  // for the hosted owner surface. This is intentionally separate from the
-  // encrypted-share registry: local images are never staged as share
-  // snapshots, and share viewers never receive an OPFS-derived URL.
+  // for Markdown and data URLs for the opaque HTML sandbox. This is
+  // intentionally separate from the encrypted-share registry: local images
+  // are never staged as share snapshots, and share viewers never receive an
+  // OPFS-derived URL.
   $effect(() => {
     const entry = activeEntry;
-    const content = bodyText ?? displayText ?? '';
+    // `displayText` is the editor's current buffer while `bodyText` is the
+    // last route/load snapshot. Prefer the live value so a newly authored
+    // relative image resolves before the debounce commits and reloads it.
+    const content = displayText ?? bodyText ?? '';
     const liveAssets = new Map(workspace.entries.map((candidate) => [candidate.path, candidate]));
     if (!entry || (entry.kind !== 'markdown' && entry.kind !== 'html')) {
-      for (const url of ownedAssetUrls.values()) URL.revokeObjectURL(url);
+      for (const asset of ownedAssetUrls.values()) URL.revokeObjectURL(asset.blobUrl);
       ownedAssetUrls = new Map();
       localAssetUrls = {};
+      localHtmlAssetUrls = {};
       return;
     }
     const sources = entry.kind === 'markdown' ? markdownImageSources(content) : htmlImageSources(content);
@@ -858,8 +878,8 @@
     }
     let cancelled = false;
     void (async () => {
-      const next = new Map<string, string>();
-      const created: string[] = [];
+      const next = new Map<string, LocalAssetUrl>();
+      const created: LocalAssetUrl[] = [];
       try {
         for (const path of paths) {
           const retained = ownedAssetUrls.get(path);
@@ -872,33 +892,41 @@
           const bytes = new Uint8Array(result.bytes);
           try {
             const mediaType = result.mediaType;
-            if (!isSupportedSharedImageMediaType(mediaType)) continue;
+            if (!mediaType || !isSupportedSharedImageMediaType(mediaType)) continue;
             const blob = new Blob([bytes.buffer as ArrayBuffer], { type: mediaType });
-            const url = URL.createObjectURL(blob);
-            created.push(url);
-            next.set(path, url);
+            const asset = {
+              blobUrl: URL.createObjectURL(blob),
+              htmlDataUrl: sharedImageDataUrl(mediaType, bytes),
+            };
+            created.push(asset);
+            next.set(path, asset);
           } finally {
             bytes.fill(0);
           }
         }
         if (cancelled) {
-          for (const url of created) URL.revokeObjectURL(url);
+          for (const asset of created) URL.revokeObjectURL(asset.blobUrl);
           return;
         }
-        for (const [path, url] of ownedAssetUrls) {
-          if (!next.has(path)) URL.revokeObjectURL(url);
+        for (const [path, asset] of ownedAssetUrls) {
+          if (!next.has(path)) URL.revokeObjectURL(asset.blobUrl);
         }
         ownedAssetUrls = next;
-        localAssetUrls = Object.fromEntries(next);
+        localAssetUrls = Object.fromEntries(
+          [...next].map(([path, asset]) => [path, asset.blobUrl]),
+        );
+        localHtmlAssetUrls = Object.fromEntries(
+          [...next].map(([path, asset]) => [path, asset.htmlDataUrl]),
+        );
       } catch {
-        for (const url of created) URL.revokeObjectURL(url);
+        for (const asset of created) URL.revokeObjectURL(asset.blobUrl);
       }
     })();
     return () => { cancelled = true; };
   });
 
   $effect(() => () => {
-    for (const url of ownedAssetUrls.values()) URL.revokeObjectURL(url);
+    for (const asset of ownedAssetUrls.values()) URL.revokeObjectURL(asset.blobUrl);
     ownedAssetUrls.clear();
   });
 
@@ -3330,7 +3358,7 @@
         <HtmlViewer
           content={bodyText ?? displayText ?? ''}
           allowScripts={false}
-          resolveAssetUrl={resolveLocalAssetUrl}
+          resolveAssetUrl={resolveLocalHtmlAssetUrl}
           annotate={htmlAnnotatable}
           annotationEvents={htmlAnnotationEvents}
           onBridge={(bridge) => (htmlBridge = bridge)}
diff --git a/web/src/lib/HtmlViewer.svelte b/web/src/lib/HtmlViewer.svelte
index e518a065..5ca21974 100644
--- a/web/src/lib/HtmlViewer.svelte
+++ b/web/src/lib/HtmlViewer.svelte
@@ -172,16 +172,22 @@
     <!-- Reviewer mode: the hosted app passes allowScripts=false, producing an
          empty sandbox token list. Native callers retain the historical
          allow-scripts opaque-origin behavior by default. -->
-    <iframe
-      bind:this={frameEl}
-      srcdoc={renderedContent}
-      title={fileName}
-      class="block h-full border-0 bg-white"
-      style="width: calc(100% + {scrollbarWidth}px);"
-      {sandbox}
-      referrerpolicy="no-referrer"
-      onload={() => (loading = false)}
-    ></iframe>
+    <!-- An annotation transition changes both the sandbox token and srcdoc.
+         Recreate the frame so its sandbox is installed before a newly injected
+         runtime can execute; updating srcdoc first would make Chrome reject
+         that runtime against the old empty sandbox. -->
+    {#key sandbox}
+      <iframe
+        bind:this={frameEl}
+        {sandbox}
+        srcdoc={renderedContent}
+        title={fileName}
+        class="block h-full border-0 bg-white"
+        style="width: calc(100% + {scrollbarWidth}px);"
+        referrerpolicy="no-referrer"
+        onload={() => (loading = false)}
+      ></iframe>
+    {/key}
   {:else}
     <!--
       `bind:this` matters as much here as in the srcdoc branch: without it the
diff --git a/web/src/lib/prosemirror/image-nodeview.test.ts b/web/src/lib/prosemirror/image-nodeview.test.ts
index e5ae6a49..acbe678d 100644
--- a/web/src/lib/prosemirror/image-nodeview.test.ts
+++ b/web/src/lib/prosemirror/image-nodeview.test.ts
@@ -142,10 +142,10 @@ defineCase('3. with no resolver the authored src is used verbatim', () =>
   }),
 );
 
-defineCase('4. a src the resolver declines falls back to the authored string', () =>
+defineCase('4. a src the resolver declines becomes a no-network fallback', () =>
   withFakeDocument(() => {
     const { img } = mount(imageNode('![a](./diagram.png)'), () => null);
-    assertEq(img.getAttribute('src'), './diagram.png', 'null means "leave it alone"');
+    assertEq(img.getAttribute('src'), 'data:;base64,', 'blocked source');
   }),
 );
 
diff --git a/web/src/lib/prosemirror/image-nodeview.ts b/web/src/lib/prosemirror/image-nodeview.ts
index 1314c0bf..50980bec 100644
--- a/web/src/lib/prosemirror/image-nodeview.ts
+++ b/web/src/lib/prosemirror/image-nodeview.ts
@@ -43,6 +43,7 @@
 
 import type { Node as PmNode } from 'prosemirror-model';
 import type { NodeView } from 'prosemirror-view';
+import { UNRESOLVED_SHARED_IMAGE_SRC } from '../review/shared-image-policy';
 
 /** Last path segment of an authored src, decoded for display. Used only in the
  *  placeholder — a reader recognises `diagram.png`, not the whole URL. */
@@ -145,10 +146,12 @@ export function imageNodeView(
     const title = typeof current.attrs.title === 'string' ? current.attrs.title : '';
 
     const resolved = resolveAssetUrl ? resolveAssetUrl(src) : null;
-    // A src the resolver declines stays as authored: it may still be a URL the
-    // webview understands, and a wrong-but-plausible attn:// URL would be a
-    // worse answer than the authored one.
-    const display = resolved ?? src;
+    // A share resolver declining a source is a policy decision, not an
+    // invitation for the browser to try the authored URL. In particular,
+    // remote/data URLs and missing local assets must retain the image fallback
+    // without receiving an ambient network fetch capability. Editors with no
+    // resolver retain the historical authored-src behavior.
+    const display = resolveAssetUrl ? (resolved ?? UNRESOLVED_SHARED_IMAGE_SRC) : src;
 
     // Set only when there is one, matching the `title` handling below and the
     // stock spec: prosemirror-markdown declares `alt: { default: null }` and
diff --git a/web/src/lib/review/asset-resolution.test.ts b/web/src/lib/review/asset-resolution.test.ts
index eadd1c49..5fa1a9d0 100644
--- a/web/src/lib/review/asset-resolution.test.ts
+++ b/web/src/lib/review/asset-resolution.test.ts
@@ -4,7 +4,7 @@
 // web/scripts/run-tests.mjs, not vitest.
 
 import { sharedAssetPathFor, assetDataUrl, buildSharedAssetResolver } from './asset-resolution';
-import type { BrowserAssetRegistry } from './browser-asset-registry';
+import type { SharedAssetUrlRegistry } from './asset-resolution';
 import type { ReviewSnapshot } from '../types';
 
 interface CaseResult {
@@ -172,7 +172,8 @@ defineCase('a verified browser asset resolves through its tab-local Blob URL', (
     urlFor: (roomId: string, snapshotId: string) => roomId === 'room-1' && snapshotId === 'snap-diagram.png'
       ? 'blob:verified-image'
       : null,
-  } as BrowserAssetRegistry;
+    dataUrlFor: () => null,
+  } satisfies SharedAssetUrlRegistry;
   const resolve = buildSharedAssetResolver(
     [assetSnapshot('diagram.png', { assetContent: undefined })],
     'room-1',
@@ -182,6 +183,23 @@ defineCase('a verified browser asset resolves through its tab-local Blob URL', (
   assertEq(resolve('./diagram.png'), 'blob:verified-image', 'verified Blob URL wins over serialized fallback');
 });
 
+defineCase('an opaque sandbox resolves the same verified asset through a data URL', () => {
+  const registry = {
+    urlFor: () => 'blob:parent-origin-image',
+    dataUrlFor: (roomId: string, snapshotId: string) => roomId === 'room-1' && snapshotId === 'snap-diagram.png'
+      ? 'data:image/png;base64,AAAA'
+      : null,
+  } satisfies SharedAssetUrlRegistry;
+  const resolve = buildSharedAssetResolver(
+    [assetSnapshot('diagram.png', { assetContent: undefined })],
+    'room-1',
+    'images.md',
+    registry,
+    'opaque-sandbox',
+  );
+  assertEq(resolve('./diagram.png'), 'data:image/png;base64,AAAA', 'sandbox-safe data URL wins');
+});
+
 defineCase('a src with no matching asset resolves to null, not a guess', () => {
   // Policy-skipped images (remote, symlink, oversized, budget-exhausted) and
   // not-yet-arrived ones are indistinguishable here, and the honest answer for
diff --git a/web/src/lib/review/asset-resolution.ts b/web/src/lib/review/asset-resolution.ts
index 412dcd16..e138f27e 100644
--- a/web/src/lib/review/asset-resolution.ts
+++ b/web/src/lib/review/asset-resolution.ts
@@ -18,7 +18,13 @@
 // existing base64 bridge as a backwards-compatible rendering fallback.
 
 import type { ReviewSnapshot } from '../types';
-import { browserAssetRegistry, type BrowserAssetRegistry } from './browser-asset-registry';
+import { browserAssetRegistry } from './browser-asset-registry';
+
+/** The narrow runtime capability a shared-image resolver needs from a tab. */
+export interface SharedAssetUrlRegistry {
+  urlFor(roomId: string, snapshotId: string): string | null;
+  dataUrlFor(roomId: string, snapshotId: string): string | null;
+}
 
 /** `scheme:` — 2+ chars so a `C:` drive letter is not mistaken for one.
  *  Mirrors `is_non_local` in src/review/assets.rs. */
@@ -127,7 +133,8 @@ export function buildSharedAssetResolver(
   snapshots: readonly ReviewSnapshot[],
   roomId: string | null,
   docWirePath: string | null | undefined,
-  registry: BrowserAssetRegistry = browserAssetRegistry,
+  registry: SharedAssetUrlRegistry = browserAssetRegistry,
+  renderTarget: 'document' | 'opaque-sandbox' = 'document',
 ): (src: string) => string | null {
   if (!roomId || !docWirePath) return () => null;
 
@@ -157,7 +164,9 @@ export function buildSharedAssetResolver(
     // Browser sessions intentionally do not put asset payloads on a
     // ReviewSnapshot. Their hash- and manifest-bound bytes live only in the
     // tab-local registry; native keeps its existing `assetContent` bridge.
-    const url = registry.urlFor(roomId, snapshot.snapshotId)
+    const url = (renderTarget === 'opaque-sandbox'
+      ? registry.dataUrlFor(roomId, snapshot.snapshotId)
+      : registry.urlFor(roomId, snapshot.snapshotId))
       ?? assetDataUrl(snapshot.mediaType, snapshot.assetContent);
     urls.set(snapshot.snapshotId, url);
     return url;
diff --git a/web/src/lib/review/browser-asset-registry.test.ts b/web/src/lib/review/browser-asset-registry.test.ts
index 5937d81d..edd6341a 100644
--- a/web/src/lib/review/browser-asset-registry.test.ts
+++ b/web/src/lib/review/browser-asset-registry.test.ts
@@ -40,6 +40,10 @@ registry.stage({
 });
 registry.activateManifest('room-a', [assetEntry()]);
 assert(registry.urlFor('room-a', 'snapshot-a') === 'blob:test-1', 'bound asset receives a Blob URL');
+assert(
+  registry.dataUrlFor('room-a', 'snapshot-a')?.startsWith('data:image/png;base64,iVBORw0KGgo') === true,
+  'bound asset also has a sandbox-safe data URL',
+);
 assert(source.every((byte) => byte === 0), 'source bytes are zeroed after the Blob takes a copy');
 
 const unbound = pngBytes();
@@ -71,7 +75,8 @@ assert(revoked.includes('blob:test-1'), 'replaced URLs are revoked');
 
 registry.clearRoom('room-a');
 assert(registry.urlFor('room-a', 'snapshot-c') === null, 'room teardown clears active URLs');
+assert(registry.dataUrlFor('room-a', 'snapshot-c') === null, 'room teardown clears active data URLs');
 assert(revoked.includes('blob:test-2'), 'room teardown revokes active URLs');
 assert(unbound.every((byte) => byte === 0), 'room teardown zeroes pending bytes');
 
-console.log('browser-asset-registry: 10 passed, 0 failed');
+console.log('browser-asset-registry: 12 passed, 0 failed');
diff --git a/web/src/lib/review/browser-asset-registry.ts b/web/src/lib/review/browser-asset-registry.ts
index b1c96384..24648350 100644
--- a/web/src/lib/review/browser-asset-registry.ts
+++ b/web/src/lib/review/browser-asset-registry.ts
@@ -15,6 +15,7 @@ import {
   MAX_SHARED_IMAGE_COUNT,
   MAX_SHARED_IMAGE_TOTAL_BYTES,
 } from './shared-image-policy';
+import { sharedImageDataUrl } from './image-data-url';
 
 export interface VerifiedBrowserAsset {
   roomId: string;
@@ -30,6 +31,10 @@ interface ActiveAsset {
   snapshotId: string;
   path: string;
   url: string;
+  // Opaque sandboxed HTML frames cannot fetch a parent-origin Blob URL. This
+  // transient representation is therefore only used by HtmlViewer; Markdown
+  // continues to use `url` and gets Blob lifetime management.
+  htmlDataUrl: string;
   byteLength: number;
 }
 
@@ -113,6 +118,7 @@ export class BrowserAssetRegistry {
           snapshotId: pending.snapshotId,
           path: pending.path,
           url,
+          htmlDataUrl: sharedImageDataUrl(pending.mediaType, pending.bytes),
           byteLength: pending.bytes.length,
         };
         this.activeBySnapshot.set(key, active);
@@ -130,6 +136,11 @@ export class BrowserAssetRegistry {
     return this.activeBySnapshot.get(snapshotKey(roomId, snapshotId))?.url ?? null;
   }
 
+  /** A runtime-only data URL for an image inside an opaque sandboxed iframe. */
+  dataUrlFor(roomId: string, snapshotId: string): string | null {
+    return this.activeBySnapshot.get(snapshotKey(roomId, snapshotId))?.htmlDataUrl ?? null;
+  }
+
   clearRoom(roomId: string): void {
     for (const [key, asset] of this.pending) {
       if (asset.roomId !== roomId) continue;
diff --git a/web/src/lib/review/html-shared-assets.test.ts b/web/src/lib/review/html-shared-assets.test.ts
index cac60fca..ce80a039 100644
--- a/web/src/lib/review/html-shared-assets.test.ts
+++ b/web/src/lib/review/html-shared-assets.test.ts
@@ -1,4 +1,5 @@
 import { rewriteSrcset } from './html-shared-assets';
+import { UNRESOLVED_SHARED_IMAGE_SRC } from './shared-image-policy';
 
 function assertEqual(actual: string, expected: string, message: string): void {
   if (actual !== expected) throw new Error(`${message}: expected ${expected}, got ${actual}`);
@@ -8,13 +9,13 @@ const resolve = (src: string): string | null => src === './chart.png' ? 'blob:ve
 
 assertEqual(
   rewriteSrcset('./chart.png 1x, remote.png 2x', resolve),
-  'blob:verified-chart 1x, remote.png 2x',
-  'srcset replaces only a verified local candidate',
+  `blob:verified-chart 1x, ${UNRESOLVED_SHARED_IMAGE_SRC} 2x`,
+  'srcset blocks every candidate without a verified local binding',
 );
 assertEqual(
   rewriteSrcset(' data:image/png;base64,AAAA 1x', resolve),
-  ' data:image/png;base64,AAAA 1x',
-  'unresolved data source stays byte-for-byte intact',
+  ` ${UNRESOLVED_SHARED_IMAGE_SRC} 1x`,
+  'unresolved data source becomes a no-network fallback',
 );
 
 console.log('html-shared-assets: 2 passed, 0 failed');
diff --git a/web/src/lib/review/html-shared-assets.ts b/web/src/lib/review/html-shared-assets.ts
index 13d2aac2..f629dead 100644
--- a/web/src/lib/review/html-shared-assets.ts
+++ b/web/src/lib/review/html-shared-assets.ts
@@ -1,7 +1,9 @@
+import { UNRESOLVED_SHARED_IMAGE_SRC } from './shared-image-policy';
+
 /**
  * Rewrites only share-bound HTML image URLs. The source remains inside a
  * sandboxed opaque-origin iframe; remote, data, and absent local references
- * remain untouched so no new network capability is introduced here.
+ * become a non-decodable local fallback, so they cannot create a network path.
  */
 export function rewriteSharedHtmlImageSources(
   content: string,
@@ -11,7 +13,7 @@ export function rewriteSharedHtmlImageSources(
   const document = new DOMParser().parseFromString(content, 'text/html');
   for (const image of document.querySelectorAll<HTMLImageElement>('img[src]')) {
     const resolved = resolveAssetUrl(image.getAttribute('src') ?? '');
-    if (resolved !== null) image.setAttribute('src', resolved);
+    image.setAttribute('src', resolved ?? UNRESOLVED_SHARED_IMAGE_SRC);
   }
   for (const source of document.querySelectorAll<HTMLSourceElement>('img[srcset], source[srcset]')) {
     const srcset = source.getAttribute('srcset');
@@ -25,10 +27,33 @@ export function rewriteSrcset(
   srcset: string,
   resolveAssetUrl: (src: string) => string | null,
 ): string {
-  return srcset.split(',').map((candidate) => {
+  return splitSrcsetCandidates(srcset).map((candidate) => {
     const match = /^(\s*)(\S+)([\s\S]*)$/u.exec(candidate);
     if (!match) return candidate;
     const resolved = resolveAssetUrl(match[2]!);
-    return resolved === null ? candidate : `${match[1]}${resolved}${match[3]}`;
+    return `${match[1]}${resolved ?? UNRESOLVED_SHARED_IMAGE_SRC}${match[3]}`;
   }).join(',');
 }
+
+/** A comma separates srcset candidates, except for the one literal comma in
+ * a data URL's metadata/payload boundary. We reject data URLs during rewrite,
+ * but must keep that boundary intact long enough to replace it as one source
+ * rather than accidentally minting two fallback candidates. */
+function splitSrcsetCandidates(srcset: string): string[] {
+  const candidates: string[] = [];
+  let start = 0;
+  let dataBoundarySeen = false;
+  for (let index = 0; index < srcset.length; index += 1) {
+    if (srcset[index] !== ',') continue;
+    const isData = srcset.slice(start).trimStart().toLowerCase().startsWith('data:');
+    if (isData && !dataBoundarySeen) {
+      dataBoundarySeen = true;
+      continue;
+    }
+    candidates.push(srcset.slice(start, index));
+    start = index + 1;
+    dataBoundarySeen = false;
+  }
+  candidates.push(srcset.slice(start));
+  return candidates;
+}
diff --git a/web/src/lib/review/image-data-url.ts b/web/src/lib/review/image-data-url.ts
new file mode 100644
index 00000000..94fd0924
--- /dev/null
+++ b/web/src/lib/review/image-data-url.ts
@@ -0,0 +1,32 @@
+// A safe, in-memory rendering URL for verified image bytes.
+//
+// Blob URLs are preferable for normal document rendering: they avoid holding a
+// second encoded copy of an image and can be revoked deterministically. An
+// opaque sandboxed iframe is the exception. It has a unique origin and cannot
+// read a Blob URL minted by its parent, so verified images need a data URL
+// there. This helper is deliberately small and dependency-free so the hosted
+// owner surface does not pull the browser cryptography bundle just to render a
+// local HTML preview.
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = '';
+  // Avoid applying a multi-megabyte typed array as one function call.
+  const chunkSize = 0x8000;
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Build an image `data:` URL without retaining the caller's mutable bytes.
+ *
+ * The caller must still zero its buffer once it has created any Blob it needs.
+ * This string is runtime-only: it never enters a workspace or review snapshot.
+ */
+export function sharedImageDataUrl(mediaType: string, bytes: Uint8Array): string {
+  const base64url = base64UrlEncode(bytes);
+  const standard = base64url.replace(/-/g, '+').replace(/_/g, '/');
+  const padding = standard.length % 4 === 0 ? '' : '='.repeat(4 - (standard.length % 4));
+  return `data:${mediaType};base64,${standard}${padding}`;
+}
diff --git a/web/src/lib/review/shared-image-policy.test.ts b/web/src/lib/review/shared-image-policy.test.ts
index 432a666a..1d960226 100644
--- a/web/src/lib/review/shared-image-policy.test.ts
+++ b/web/src/lib/review/shared-image-policy.test.ts
@@ -5,6 +5,7 @@ import {
   MAX_SHARED_IMAGE_BYTES,
   MAX_SHARED_IMAGE_COUNT,
   MAX_SHARED_IMAGE_TOTAL_BYTES,
+  UNRESOLVED_SHARED_IMAGE_SRC,
 } from './shared-image-policy';
 
 function assert(value: unknown, message: string): asserts value {
@@ -27,5 +28,6 @@ assert(!hasSafeSharedImageDimensions(png, 'image/png'), 'oversized raster dimens
 assert(!hasSafeSharedImageDimensions(new Uint8Array(8), 'image/png'), 'unknown raster dimensions fail closed');
 assert(MAX_SHARED_IMAGE_BYTES === 3 * 1024 * 1024, 'single-image cap preserves encrypted-envelope headroom');
 assert(MAX_SHARED_IMAGE_COUNT === 64 && MAX_SHARED_IMAGE_TOTAL_BYTES === 16 * 1024 * 1024, 'aggregate image budgets are bounded');
+assert(UNRESOLVED_SHARED_IMAGE_SRC === 'data:;base64,', 'rejected image sources remain local and non-decodable');
 
 console.log('shared-image-policy: 12 passed, 0 failed');
diff --git a/web/src/lib/review/shared-image-policy.ts b/web/src/lib/review/shared-image-policy.ts
index 42a5f940..ebc49582 100644
--- a/web/src/lib/review/shared-image-policy.ts
+++ b/web/src/lib/review/shared-image-policy.ts
@@ -7,6 +7,12 @@ export const MAX_SHARED_IMAGE_COUNT = 64;
 export const MAX_SHARED_IMAGE_TOTAL_BYTES = 16 * 1024 * 1024;
 export const MAX_SHARED_IMAGE_PIXELS = 40_000_000;
 
+/** A local, deliberately non-decodable image source. Renderers use this when
+ * a share resolver cannot bind an authored src to verified asset bytes: it
+ * produces the existing image fallback without giving untrusted HTML or
+ * Markdown an ambient network request capability. */
+export const UNRESOLVED_SHARED_IMAGE_SRC = 'data:;base64,';
+
 const IMAGE_MEDIA_TYPES = new Set([
   'image/png',
   'image/jpeg',

From d3ca3f5335347d50f852beb5bba700075797ab40 Mon Sep 17 00:00:00 2001
From: Angus Bezzina <37071175+angusbezzina@users.noreply.github.com>
Date: Wed, 2 Sep 2026 11:37:23 -0500
Subject: [PATCH 06/10] Polish hosted image and file states

---
 tests/fixtures/images.md              |  22 ++---
 web/src/hosted/app/AppShell.svelte    |  19 ++--
 web/src/hosted/app/EditorShell.svelte | 115 ++++++++++++++++------
 web/src/hosted/app/app-shell.css      | 136 +++++++++++++++++++++++++-
 4 files changed, 239 insertions(+), 53 deletions(-)

diff --git a/tests/fixtures/images.md b/tests/fixtures/images.md
index 4ef9a7b6..42b35ad3 100644
--- a/tests/fixtures/images.md
+++ b/tests/fixtures/images.md
@@ -1,9 +1,10 @@
 # Images
 
-A fixture for relative image resolution in the native viewer (attn-cgev).
-Every src below is authored the way a human or an agent actually writes one;
-the viewer resolves each against **this file's own directory** and serves it
-through the `attn://` protocol handler.
+A fixture for relative image resolution in attn. Every src below is authored
+the way a human or an agent actually writes one; the viewer resolves each
+against **this file's own directory**. Native attn serves local files through
+the `attn://` protocol handler, while a browser workspace resolves the files
+that were imported with it.
 
 ## Sibling, dot-slash
 
@@ -25,15 +26,14 @@ blocks written inline in the markdown source.
 
 ![A bar chart](./chart.svg)
 
-## Absolute URL
+## Remote source
 
-Anything with a scheme passes through untouched, so remote images keep working.
+Imported workspaces and encrypted shares resolve only files that arrived with
+the workspace. A remote URL is not fetched by a reader&rsquo;s browser, so it cannot
+silently contact an address chosen by the document author.
 
-The src below is deliberately unresolvable: the E2E suite asserts the exact
-string survives the resolver, and anchoring that on a live host would make the
-run fail offline and in CI. **Expect a placeholder card here** — what is being
-tested is the `src` attribute, not the pixels. To see a remote image actually
-render, swap in any live URL by hand; it will load, because nothing rewrites it.
+This source is deliberately unavailable. **Expect a placeholder card here** —
+the test is the safe fallback, not remote pixels.
 
 ![A remote pixel](https://example.com/pixel.png)
 
diff --git a/web/src/hosted/app/AppShell.svelte b/web/src/hosted/app/AppShell.svelte
index 7eafd32c..fa27160e 100644
--- a/web/src/hosted/app/AppShell.svelte
+++ b/web/src/hosted/app/AppShell.svelte
@@ -607,14 +607,18 @@
 </script>
 
 {#if phase === 'loading'}
-  <!-- attn-mkmz.7. Both loading branches used to render `main.desk` with a
-       left-aligned eyebrow at the top of the page — so opening a DOCUMENT drew
-       a desk-shaped page first, then snapped to a three-column editor, and the
-       indicator itself sat in the top-left corner of a region it was standing
-       in for. One centred surface for every wait, and the editor route names
-       the same thing at every stage (see EditorShell's own loading text). -->
+  <!-- Keep the desk's masthead and content region in place while its data is
+       loading. Removing the header here made the whole page jump down when the
+       ready desk mounted; only the content of that region should change. -->
   <div class="app-shell" data-app-view="loading">
-    <div class="app-loading" role="status"><LoadingLine text="Opening your desk" /></div>
+    <AppHeader mode={health.mode}>
+      {#snippet actions()}
+        <a class="button" href="/app/storage">Storage</a>
+      {/snippet}
+    </AppHeader>
+    <main class="desk desk-loading" aria-busy="true">
+      <div class="desk-loading-status" role="status"><LoadingLine text="Opening your desk" /></div>
+    </main>
   </div>
 {:else if phase === 'error'}
   <!-- The moment of real fear had the least design in the app (attn-a9f7.1.3):
@@ -766,4 +770,3 @@
     {/if}
   </div>
 {/if}
-
diff --git a/web/src/hosted/app/EditorShell.svelte b/web/src/hosted/app/EditorShell.svelte
index fdf614e4..ea2ca3d1 100644
--- a/web/src/hosted/app/EditorShell.svelte
+++ b/web/src/hosted/app/EditorShell.svelte
@@ -374,6 +374,8 @@
   // no-op instead of renaming/deleting whichever file became active.
   let entryActionPath = $state<string | null>(null);
   let railError = $state<string | null>(null);
+  let downloadingActiveEntry = $state(false);
+  let activeEntryDownloadError = $state<string | null>(null);
   let assetInput = $state<HTMLInputElement | undefined>();
   let assetFolderInput = $state<HTMLInputElement | undefined>();
   let previewUrl = $state<string | null>(null);
@@ -1067,11 +1069,22 @@
 
   async function downloadActiveEntry(): Promise<void> {
     const entry = activeEntry;
-    if (!entry) return;
-    const result = await service.readEntryBytes(workspace.id, entry.path);
-    if (!result) return;
-    const basename = entry.path.split('/').pop() ?? entry.path;
-    triggerDownload(document, basename, result.bytes, result.mediaType);
+    if (!entry || downloadingActiveEntry) return;
+    downloadingActiveEntry = true;
+    activeEntryDownloadError = null;
+    try {
+      const result = await service.readEntryBytes(workspace.id, entry.path);
+      if (!result) {
+        activeEntryDownloadError = 'The file could not be read. Please try downloading it again.';
+        return;
+      }
+      const basename = entry.path.split('/').pop() ?? entry.path;
+      triggerDownload(document, basename, result.bytes, result.mediaType);
+    } catch {
+      activeEntryDownloadError = 'The download could not be prepared. Please try again.';
+    } finally {
+      downloadingActiveEntry = false;
+    }
   }
 
   async function exportZip(): Promise<void> {
@@ -2773,6 +2786,19 @@
   function entryBasename(entry: WorkspaceEntry): string {
     return entry.path.split('/').pop() ?? entry.path;
   }
+  function downloadOnlyFormat(entry: WorkspaceEntry): string {
+    const extension = entryBasename(entry).split('.').pop()?.toLowerCase();
+    const names: Record<string, string> = {
+      csv: 'Comma-separated data',
+      json: 'JSON data',
+      pdf: 'PDF document',
+      rs: 'Rust source',
+      zip: 'ZIP archive',
+    };
+    if (extension && names[extension]) return names[extension];
+    if (extension) return `${extension.toUpperCase()} file`;
+    return 'File';
+  }
   function entrySubtitle(entry: WorkspaceEntry): string {
     if (entry.presentation === 'preview') return 'Preview inline';
     if (entry.presentation === 'download-only') return 'Download only';
@@ -3371,34 +3397,61 @@
         <p class="placeholder">Tap to start writing…</p>
       {/if}
     {:else if activeEntry && activeEntry.presentation !== 'editable'}
-      <div class="eyebrow">
-        {activeEntry.presentation === 'preview' ? 'Asset preview' : 'Download only'}
-      </div>
-      <h1>{activeEntry.path}</h1>
-      {#if activeEntry.presentation === 'preview' && previewUrl}
-        <button
-          class="asset-image-button"
-          type="button"
-          aria-label={`View ${activeEntry.path} full screen`}
-          onclick={openLightbox}
-        >
-          <img class="asset-image" src={previewUrl} alt={activeEntry.path} />
-        </button>
-      {:else}
-        <div class="asset-preview">
-          <strong>{activeEntry.path}</strong>
-          {#if activeEntry.presentation === 'preview'}
-            Decrypting preview… · {activeEntry.sizeLabel}
-          {:else}
-            This format is never executed here. Download it or open it in native attn ·
-            {activeEntry.sizeLabel}
+      {#if activeEntry.presentation === 'download-only'}
+        <div class="eyebrow">Download only</div>
+        <h1>{entryBasename(activeEntry)}</h1>
+        <p class="download-only-path">{activeEntry.path}</p>
+        <section class="download-only-card" aria-labelledby="download-only-heading">
+          <div class="download-only-intro">
+            <span class="download-only-mark" aria-hidden="true">↓</span>
+            <div>
+              <h2 id="download-only-heading">Ready for a local copy</h2>
+              <p>This file stays inert in the browser. Download it to use it in the right tool.</p>
+            </div>
+          </div>
+          <dl class="download-only-meta">
+            <div>
+              <dt>Format</dt>
+              <dd>{downloadOnlyFormat(activeEntry)}</dd>
+            </div>
+            <div>
+              <dt>Size</dt>
+              <dd>{activeEntry.sizeLabel}</dd>
+            </div>
+          </dl>
+          <div class="download-only-actions">
+            <button
+              class="button primary"
+              type="button"
+              disabled={downloadingActiveEntry}
+              onclick={() => void downloadActiveEntry()}
+            >
+              {downloadingActiveEntry ? 'Preparing download…' : 'Download file'}
+            </button>
+            <a class="download-native-link" href="/#native">Open in native attn <span aria-hidden="true">↗</span></a>
+          </div>
+          {#if activeEntryDownloadError}
+            <p class="download-only-error" role="alert">{activeEntryDownloadError}</p>
           {/if}
-        </div>
-        <div class="storage-actions">
-          <button class="button" type="button" onclick={() => void downloadActiveEntry()}>
-            Download
+        </section>
+      {:else}
+        <div class="eyebrow">Asset preview</div>
+        <h1>{activeEntry.path}</h1>
+        {#if previewUrl}
+          <button
+            class="asset-image-button"
+            type="button"
+            aria-label={`View ${activeEntry.path} full screen`}
+            onclick={openLightbox}
+          >
+            <img class="asset-image" src={previewUrl} alt={activeEntry.path} />
           </button>
-        </div>
+        {:else}
+          <div class="asset-preview">
+            <strong>{activeEntry.path}</strong>
+            Decrypting preview… · {activeEntry.sizeLabel}
+          </div>
+        {/if}
       {/if}
     {:else}
       <div class="eyebrow">Working draft</div>
diff --git a/web/src/hosted/app/app-shell.css b/web/src/hosted/app/app-shell.css
index da85d225..9dc0de98 100644
--- a/web/src/hosted/app/app-shell.css
+++ b/web/src/hosted/app/app-shell.css
@@ -216,6 +216,22 @@
   padding: clamp(2rem, 6vw, 6rem) clamp(1rem, 4vw, 6rem);
 }
 
+/* The loading desk reserves the exact same masthead and content region as the
+   ready desk. Only its content changes, which keeps the first paint still
+   instead of dropping the page when the header arrives. */
+.desk-loading {
+  display: grid;
+  min-height: 0;
+  place-items: center;
+}
+
+.desk-loading-status {
+  color: var(--foreground);
+  font: 600 1.5rem/1.35 var(--serif);
+  letter-spacing: -0.02em;
+  text-align: center;
+}
+
 /* No rule under the title. The eyebrow above it and the whitespace below it
    already separate the head from the page, and a hairline stretched the full
    1300px desk was the loudest line on a page whose own content carries none. */
@@ -958,6 +974,120 @@
   overflow-wrap: anywhere;
 }
 
+/* A download-only file is a real document, not a failed preview. Its card
+   states the boundary plainly, names the file metadata, and makes the one
+   useful action dominant without turning the entire reading sheet into an
+   empty dashed drop zone. */
+.download-only-path {
+  margin: -0.75rem 0 0;
+  color: var(--hosted-muted);
+  font: 0.78rem/1.45 var(--mono);
+  overflow-wrap: anywhere;
+}
+
+.download-only-card {
+  margin-top: 2.25rem;
+  overflow: hidden;
+  border: 1px solid var(--rule);
+  border-radius: var(--radius-lg);
+  background: var(--sheet-raised);
+  box-shadow: var(--shadow-soft);
+  font-family: var(--sans);
+}
+
+.download-only-intro {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  gap: 1rem;
+  align-items: start;
+  padding: 1.5rem;
+  border-bottom: 1px solid var(--rule);
+}
+
+.download-only-mark {
+  display: grid;
+  width: 2.75rem;
+  height: 2.75rem;
+  place-items: center;
+  border: 1px solid var(--rule);
+  border-radius: var(--radius-md);
+  background: var(--sheet);
+  color: var(--rust);
+  font: 600 1.25rem/1 var(--serif);
+}
+
+.download-only-card h2 {
+  margin: 0;
+  font-size: 1.25rem;
+  line-height: 1.2;
+  letter-spacing: -0.015em;
+}
+
+.download-only-intro p {
+  margin: 0.45rem 0 0;
+  color: var(--hosted-muted);
+  font-size: 0.95rem;
+  line-height: 1.55;
+}
+
+.download-only-meta {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  margin: 0;
+  border-bottom: 1px solid var(--rule);
+}
+
+.download-only-meta > div {
+  min-width: 0;
+  padding: 1rem 1.5rem;
+}
+
+.download-only-meta > div + div {
+  border-left: 1px solid var(--rule);
+}
+
+.download-only-meta dt {
+  color: var(--hosted-muted);
+  font: 600 0.7rem/1.2 var(--sans);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.download-only-meta dd {
+  margin: 0.38rem 0 0;
+  color: var(--ink);
+  font: 0.85rem/1.35 var(--mono);
+  overflow-wrap: anywhere;
+}
+
+.download-only-actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 1rem;
+  padding: 1.25rem 1.5rem;
+  background: color-mix(in oklch, var(--sheet) 58%, transparent);
+}
+
+.download-native-link {
+  color: var(--ink);
+  font: 650 0.85rem var(--sans);
+  text-underline-offset: 0.2em;
+}
+
+.download-native-link:hover {
+  color: var(--rust);
+}
+
+.download-only-error {
+  margin: 0;
+  padding: 0.85rem 1.5rem;
+  border-top: 1px solid var(--rule);
+  color: var(--danger-ink);
+  background: color-mix(in oklch, var(--danger-ink) 10%, var(--sheet-raised));
+  font: 0.85rem/1.45 var(--sans);
+}
+
 .review-rail {
   border-left: 1px solid var(--rule);
   background: var(--paper);
@@ -1075,9 +1205,9 @@
   text-align: center;
 }
 
-/* The shell's two loading views have no header row to reserve, so the single
-   centred child owns the whole viewport rather than the 64px masthead band. */
-.app-shell[data-app-view='loading'],
+/* A document-shell chunk still has no header of its own to reserve. The desk
+   loader above deliberately does reserve its masthead, so it uses the normal
+   two-row shell. */
 .app-shell[data-app-view='editor-loading'] {
   grid-template-rows: 1fr;
 }

From b2b5375134c13f500f3e3a040771ac547d6f9486 Mon Sep 17 00:00:00 2001
From: Angus Bezzina <37071175+angusbezzina@users.noreply.github.com>
Date: Wed, 2 Sep 2026 12:29:57 -0500
Subject: [PATCH 07/10] Allow approved remote document images

---
 tests/fixtures/images.md                      |  8 +-
 web/scripts/test-hosted-local-share-ui.ts     | 88 ++++++++++++++++---
 .../BrowserReviewApp.external-images.test.ts  | 33 +++++++
 web/src/BrowserReviewApp.svelte               | 45 +++++++++-
 web/src/hosted/app/EditorShell.svelte         |  9 +-
 web/src/lib/Editor.svelte                     | 10 +--
 web/src/lib/hosted/csp.test.ts                |  5 ++
 web/src/lib/hosted/csp.ts                     |  5 +-
 .../lib/prosemirror/image-nodeview.test.ts    |  1 +
 web/src/lib/prosemirror/image-nodeview.ts     | 13 +--
 .../lib/review/external-image-policy.test.ts  | 21 +++++
 web/src/lib/review/external-image-policy.ts   | 19 ++++
 web/src/lib/review/html-shared-assets.test.ts |  7 +-
 web/src/lib/review/html-shared-assets.ts      | 17 ++--
 14 files changed, 238 insertions(+), 43 deletions(-)
 create mode 100644 web/src/BrowserReviewApp.external-images.test.ts
 create mode 100644 web/src/lib/review/external-image-policy.test.ts
 create mode 100644 web/src/lib/review/external-image-policy.ts

diff --git a/tests/fixtures/images.md b/tests/fixtures/images.md
index 42b35ad3..b5b05b45 100644
--- a/tests/fixtures/images.md
+++ b/tests/fixtures/images.md
@@ -28,12 +28,12 @@ blocks written inline in the markdown source.
 
 ## Remote source
 
-Imported workspaces and encrypted shares resolve only files that arrived with
-the workspace. A remote URL is not fetched by a reader&rsquo;s browser, so it cannot
-silently contact an address chosen by the document author.
+An HTTPS image is a normal Markdown source. The workspace owner may load one
+directly; an invited reader chooses whether to load external images for that
+review session, so the image host cannot silently observe a reader&rsquo;s request.
 
 This source is deliberately unavailable. **Expect a placeholder card here** —
-the test is the safe fallback, not remote pixels.
+that proves a network failure, not a blocked remote-image policy.
 
 ![A remote pixel](https://example.com/pixel.png)
 
diff --git a/web/scripts/test-hosted-local-share-ui.ts b/web/scripts/test-hosted-local-share-ui.ts
index 1de38c2a..90223d65 100644
--- a/web/scripts/test-hosted-local-share-ui.ts
+++ b/web/scripts/test-hosted-local-share-ui.ts
@@ -178,7 +178,37 @@ async function expectBlockedRemoteImage(page: Page, label: string): Promise<void
   }
 }
 
-async function expectResolvedSharedHtmlImages(page: Page, label: string): Promise<void> {
+async function expectAttemptedExternalImage(page: Page, label: string): Promise<void> {
+  const image = page.locator(`.md-image[data-src="${remoteImageSource}"] img`);
+  await image.waitFor({ state: 'attached', timeout: 60_000 });
+  await page.waitForFunction(
+    (source) => {
+      const imageElement = document.querySelector(`.md-image[data-src="${source}"] img`);
+      return imageElement?.getAttribute('src') === source
+        && imageElement.parentElement?.getAttribute('data-broken') === 'true';
+    },
+    remoteImageSource,
+    { timeout: 60_000 },
+  );
+  const detail = await image.evaluate((element) => ({
+    src: element.getAttribute('src'),
+    referrerPolicy: element.getAttribute('referrerpolicy'),
+    broken: element.parentElement?.getAttribute('data-broken'),
+  }));
+  if (
+    detail.src !== remoteImageSource
+    || detail.referrerPolicy !== 'no-referrer'
+    || detail.broken !== 'true'
+  ) {
+    throw new Error(`${label} did not attempt the approved HTTPS image safely: ${JSON.stringify(detail)}`);
+  }
+}
+
+async function expectResolvedSharedHtmlImages(
+  page: Page,
+  label: string,
+  externalImagesEnabled = false,
+): Promise<void> {
   const frame = page.frameLocator('[data-slot="html-viewer"] iframe');
   const verified = frame.locator('#verified-html-image');
   await expect(verified).toBeVisible({ timeout: 60_000 });
@@ -191,13 +221,19 @@ async function expectResolvedSharedHtmlImages(page: Page, label: string): Promis
   await expect(pictureImage).toHaveJSProperty('naturalWidth', 1, { timeout: 60_000 });
   const source = frame.locator('#verified-html-source');
   const srcset = await source.getAttribute('srcset');
-  if (!srcset?.includes('data:image/png;base64,') || !srcset.includes(unresolvedImageSource)) {
+  const expectedRemoteSrcset = externalImagesEnabled ? remoteImageSource : unresolvedImageSource;
+  if (!srcset?.includes('data:image/png;base64,') || !srcset.includes(expectedRemoteSrcset)) {
     throw new Error(`${label} did not rewrite picture srcset safely: ${JSON.stringify(srcset)}`);
   }
 
   const remote = frame.locator('#remote-html-image');
-  await expect(remote).toHaveAttribute('src', unresolvedImageSource, { timeout: 60_000 });
+  await expect(remote).toHaveAttribute(
+    'src',
+    externalImagesEnabled ? remoteImageSource : unresolvedImageSource,
+    { timeout: 60_000 },
+  );
   await expect(remote).toHaveJSProperty('naturalWidth', 0, { timeout: 60_000 });
+  await expect(remote).toHaveAttribute('referrerpolicy', 'no-referrer');
   const sandbox = await page.locator('[data-slot="html-viewer"] iframe').getAttribute('sandbox');
   if (sandbox?.includes('allow-same-origin')) {
     throw new Error(`${label} weakened the opaque-origin HTML sandbox: ${sandbox}`);
@@ -241,7 +277,28 @@ async function createInvite(owner: Page, options: { selectAll?: boolean } = {}):
   await dialog.waitFor({ state: 'visible' });
   if (options.selectAll) await dialog.getByRole('button', { name: 'Select all' }).click();
   await dialog.getByRole('button', { name: /Create review link/u }).click();
-  await dialog.locator('select[aria-label="What this link allows"]').selectOption('suggest');
+  const tierPicker = dialog.locator('select[aria-label="What this link allows"]');
+  try {
+    await tierPicker.selectOption('suggest', { timeout: 30_000 });
+  } catch (error) {
+    const resume = dialog.getByRole('button', { name: 'Resume publishing' });
+    if (await resume.isVisible().catch(() => false)) {
+      // A fresh browser workspace can race its writer lease on the first
+      // publish. Exercise the product's recoverable resume action rather
+      // than turning that transient fence into a false image-test failure.
+      await resume.click();
+      await tierPicker.selectOption('suggest', { timeout: 60_000 });
+      return finishInvite(owner, dialog);
+    }
+    throw new Error(
+      `review link did not become ready: ${JSON.stringify((await dialog.textContent() ?? '').trim())}`,
+      { cause: error },
+    );
+  }
+  return finishInvite(owner, dialog);
+}
+
+async function finishInvite(owner: Page, dialog: ReturnType<Page['getByRole']>): Promise<string> {
   const chip = dialog.locator('.share-link-chip');
   await chip.click();
   const invite = await chip.locator('code').textContent();
@@ -473,12 +530,12 @@ async function main(): Promise<void> {
   ]);
   await imageOwner.getByRole('button', { name: 'review.md', exact: true }).waitFor({ state: 'visible' });
   await expectResolvedSharedImage(imageOwner, 'local owner');
-  await expectBlockedRemoteImage(imageOwner, 'local owner');
+  await expectAttemptedExternalImage(imageOwner, 'local owner');
   await imageOwner.getByRole('button', { name: 'preview.html', exact: true }).click();
-  await expectResolvedSharedHtmlImages(imageOwner, 'local owner HTML document');
+  await expectResolvedSharedHtmlImages(imageOwner, 'local owner HTML document', true);
   await imageOwner.getByRole('button', { name: 'review.md', exact: true }).click();
-  if (remoteRequests.length > 0) {
-    throw new Error(`local owner fetched a blocked remote image: ${JSON.stringify(remoteRequests)}`);
+  if (remoteRequests.length === 0) {
+    throw new Error('local owner did not request the approved remote image');
   }
   const imageInvite = await createInvite(imageOwner, { selectAll: true });
 
@@ -492,8 +549,12 @@ async function main(): Promise<void> {
   await imageReviewer.getByRole('button', { name: /review\.md/u }).click();
   await expectResolvedSharedImage(imageReviewer, 'live invited reviewer');
   await expectBlockedRemoteImage(imageReviewer, 'live invited reviewer');
+  const loadExternalImages = imageReviewer.getByRole('button', { name: 'Load external images for this review' });
+  await loadExternalImages.waitFor({ state: 'visible' });
+  await loadExternalImages.click();
+  await expectAttemptedExternalImage(imageReviewer, 'opted-in invited reviewer');
   await imageReviewer.getByRole('button', { name: /preview\.html/u }).click();
-  await expectResolvedSharedHtmlImages(imageReviewer, 'live invited reviewer HTML document');
+  await expectResolvedSharedHtmlImages(imageReviewer, 'opted-in invited reviewer HTML document', true);
 
   // A second reviewer tab owns a distinct in-memory Blob registry.
   const follower = await reviewerContext.newPage();
@@ -547,13 +608,12 @@ async function main(): Promise<void> {
   if (diagnostics.some((line) => /\[attn drift\]/u.test(line))) {
     throw new Error(`projection drift detected:\n${diagnostics.filter((line) => /\[attn drift\]/u.test(line)).join('\n')}`);
   }
-  // The blocked image source intentionally uses a malformed local data URL so
-  // the existing image fallback card appears without issuing a network fetch.
-  // Chromium reports that parse failure on the console; the DOM assertions
-  // above prove it is exactly this policy fallback, not a failed shared asset.
+  // The blocked sources use a malformed local data URL, while the approved
+  // HTTPS fixture intentionally cannot resolve. The DOM assertions above
+  // distinguish a local policy fallback from an attempted external request.
   const browserErrors = diagnostics.filter((line) => (
     /(?:page error:|console error:)/u.test(line)
-    && !/console error: Failed to load resource: net::ERR_(?:INVALID_URL|FILE_NOT_FOUND)/u.test(line)
+    && !/console error: Failed to load resource: net::ERR_(?:INVALID_URL|FILE_NOT_FOUND|NAME_NOT_RESOLVED)/u.test(line)
   ));
   if (browserErrors.length > 0) {
     throw new Error(`browser errors detected:\n${browserErrors.join('\n')}`);
diff --git a/web/src/BrowserReviewApp.external-images.test.ts b/web/src/BrowserReviewApp.external-images.test.ts
new file mode 100644
index 00000000..201f876e
--- /dev/null
+++ b/web/src/BrowserReviewApp.external-images.test.ts
@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const source = fs.readFileSync(path.join(here, 'BrowserReviewApp.svelte'), 'utf8');
+
+assert(
+  source.includes('let externalImagesEnabled = $state(false);'),
+  'external image consent must start off for every reviewer tab',
+);
+assert(
+  (source.match(/const allowExternalImages = externalImagesEnabled;/g) ?? []).length === 2,
+  'Markdown and HTML share resolvers must both react to reviewer consent',
+);
+assert(
+  (source.match(/if \(allowExternalImages && external !== null\) return external;/g) ?? []).length === 2,
+  'only an explicitly enabled HTTPS image may bypass the verified-asset resolver',
+);
+assert(
+  source.includes('data-slot="browser-review-external-images"'),
+  'a document with external images must expose a reviewer control',
+);
+assert(
+  source.includes('Those hosts may see your IP address.'),
+  'the reviewer control must state the privacy consequence before it loads an external image',
+);
+
+console.log('browser-review external images: all assertions passed');
diff --git a/web/src/BrowserReviewApp.svelte b/web/src/BrowserReviewApp.svelte
index de870176..cbe4de0d 100644
--- a/web/src/BrowserReviewApp.svelte
+++ b/web/src/BrowserReviewApp.svelte
@@ -61,7 +61,9 @@
   import { deriveFileEntries, latestRenderableSnapshotId } from './lib/review/file-nav';
   import { reviewerStatusPresentation } from './lib/review/reviewer-status-model';
   import { buildSharedAssetResolver } from './lib/review/asset-resolution';
+  import { approvedExternalImageUrl } from './lib/review/external-image-policy';
   import { browserAssetRegistry } from './lib/review/browser-asset-registry';
+  import { htmlImageSources, markdownImageSources } from './lib/review/document-image-sources';
   import { reviewStore } from './lib/review/store.svelte';
   import {
     applyReviewHoverHighlight,
@@ -163,6 +165,9 @@
     canRemember: true,
   });
   let collabSetupError = $state<string | null>(null);
+  // This consent is deliberately tab/session-only. A shared document must not
+  // retain a choice that makes a later reader contact a third-party host.
+  let externalImagesEnabled = $state(false);
   const authenticatedOwnerDeviceIds = new Set<string>();
   const reviewerCollabGate = new BrowserReviewerCollabGate((error) => {
     collabSetupError = error.message;
@@ -645,6 +650,13 @@
       ? sessionState.snapshotDocType
       : 'markdown';
   });
+  const reviewHasExternalImages = $derived.by(() => {
+    const content = displayedContent ?? '';
+    const sources = displayedDocType === 'html'
+      ? htmlImageSources(content)
+      : markdownImageSources(content);
+    return sources.some((src) => approvedExternalImageUrl(src) !== null);
+  });
   // The session only puts verified asset metadata in reviewStore; the
   // tab-local asset registry behind this resolver owns the decrypted bytes and
   // their Blob URL lifetime. Read dependencies eagerly so a newly activated
@@ -653,16 +665,28 @@
     const snapshots = reviewStore.snapshots;
     const roomId = sessionState.roomId;
     const docWirePath = displayedSnapshot?.ownerDisplayPath;
-    return buildSharedAssetResolver(snapshots, roomId, docWirePath);
+    const local = buildSharedAssetResolver(snapshots, roomId, docWirePath);
+    const allowExternalImages = externalImagesEnabled;
+    return (src: string): string | null => {
+      const external = approvedExternalImageUrl(src);
+      if (allowExternalImages && external !== null) return external;
+      return local(src);
+    };
   });
   const resolveReviewHtmlAssetUrl = $derived.by(() => {
-    return buildSharedAssetResolver(
+    const local = buildSharedAssetResolver(
       reviewStore.snapshots,
       sessionState.roomId,
       displayedSnapshot?.ownerDisplayPath,
       browserAssetRegistry,
       'opaque-sandbox',
     );
+    const allowExternalImages = externalImagesEnabled;
+    return (src: string): string | null => {
+      const external = approvedExternalImageUrl(src);
+      if (allowExternalImages && external !== null) return external;
+      return local(src);
+    };
   });
 
   $effect(() => {
@@ -1627,6 +1651,23 @@
             {currentFileName}
           </span>
           <div class="ml-auto flex shrink-0 items-center gap-1.5">
+            {#if reviewHasExternalImages}
+              <button
+                type="button"
+                class="inline-flex h-7 items-center rounded-md border px-1.5 font-sans text-label font-semibold transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 {externalImagesEnabled
+                  ? 'border-primary/35 bg-primary/10 text-primary hover:bg-primary/15'
+                  : 'border-transparent text-muted-foreground hover:bg-accent hover:text-foreground'}"
+                data-slot="browser-review-external-images"
+                aria-pressed={externalImagesEnabled}
+                aria-label={externalImagesEnabled ? 'External images are on for this review' : 'Load external images for this review'}
+                title={externalImagesEnabled
+                  ? 'External images are on for this review session'
+                  : 'Load HTTPS images directly from their hosts. Those hosts may see your IP address.'}
+                onclick={() => (externalImagesEnabled = !externalImagesEnabled)}
+              >
+                {externalImagesEnabled ? 'External images on' : 'Load images'}
+              </button>
+            {/if}
             <PeerStrip {localParticipantId} onJumpTo={handleJumpToPeer} />
             <ReviewerStatusChip
               presentation={statusPresentation}
diff --git a/web/src/hosted/app/EditorShell.svelte b/web/src/hosted/app/EditorShell.svelte
index ea2ca3d1..94a4059b 100644
--- a/web/src/hosted/app/EditorShell.svelte
+++ b/web/src/hosted/app/EditorShell.svelte
@@ -57,6 +57,7 @@
   import { peerJumpPosition } from '../../lib/peer-strip-format';
   import { attachCollabPresenceSinks } from '../../lib/prosemirror/collab-presence-sinks';
   import { sharedAssetPathFor } from '../../lib/review/asset-resolution';
+  import { approvedExternalImageUrl } from '../../lib/review/external-image-policy';
   import { sharedImageDataUrl } from '../../lib/review/image-data-url';
   import { htmlImageSources, markdownImageSources } from '../../lib/review/document-image-sources';
   import { isSupportedSharedImageMediaType } from '../../lib/review/shared-image-policy';
@@ -393,8 +394,10 @@
   const resolveLocalAssetUrl = $derived.by(() => {
     const documentPath = activeEntry?.path;
     const urls = localAssetUrls;
-    if (!documentPath) return () => null;
     return (src: string): string | null => {
+      const external = approvedExternalImageUrl(src);
+      if (external !== null) return external;
+      if (!documentPath) return null;
       const path = sharedAssetPathFor(documentPath, src);
       return path === null ? null : urls[path] ?? null;
     };
@@ -402,8 +405,10 @@
   const resolveLocalHtmlAssetUrl = $derived.by(() => {
     const documentPath = activeEntry?.path;
     const urls = localHtmlAssetUrls;
-    if (!documentPath) return () => null;
     return (src: string): string | null => {
+      const external = approvedExternalImageUrl(src);
+      if (external !== null) return external;
+      if (!documentPath) return null;
       const path = sharedAssetPathFor(documentPath, src);
       return path === null ? null : urls[path] ?? null;
     };
diff --git a/web/src/lib/Editor.svelte b/web/src/lib/Editor.svelte
index 5eb2cc48..a05124c1 100644
--- a/web/src/lib/Editor.svelte
+++ b/web/src/lib/Editor.svelte
@@ -500,13 +500,9 @@
       // renders the authored src verbatim — the same bytes the stock `toDOM`
       // emits — and the src fails exactly as it did before.
       //
-      // What changes for those surfaces is only the FAILURE state, and that is
-      // the point: hosted has no filesystem behind `./diagram.png` and its CSP
-      // has no `https:` in `img-src`, so those images cannot load there and
-      // will not until workspace-relative assets land. Until then the honest
-      // answer is the same card native shows — alt text and a filename in the
-      // document's voice — not the platform's broken-image glyph. Shipping the
-      // graceful state on one of two surfaces is a half-landed feature.
+      // Resolver-owning surfaces distinguish workspace-relative files from
+      // approved HTTPS images. A declined source stays behind this view's
+      // explicit fallback rather than receiving a surprise network request.
       image: (node: PmNode) => imageNodeView(node, resolveAssetUrl),
       code_block(node, editorView, getPos) {
         const mermaid = mermaidNodeView(node, editorView, getPos);
diff --git a/web/src/lib/hosted/csp.test.ts b/web/src/lib/hosted/csp.test.ts
index 2c391fc7..53901669 100644
--- a/web/src/lib/hosted/csp.test.ts
+++ b/web/src/lib/hosted/csp.test.ts
@@ -29,6 +29,11 @@ assertEq(
   true,
   'script-src permits only WebAssembly compilation',
 );
+assertEq(
+  staging.includes("img-src 'self' blob: data: https:"),
+  true,
+  'HTTPS images are the only remote render capability',
+);
 
 // The theme-preflight hash and the script it admits must never drift. If they
 // do, the browser silently blocks the inline stamp and the ~1.2s paper-white
diff --git a/web/src/lib/hosted/csp.ts b/web/src/lib/hosted/csp.ts
index 9891a904..af290c1e 100644
--- a/web/src/lib/hosted/csp.ts
+++ b/web/src/lib/hosted/csp.ts
@@ -3,7 +3,8 @@
 // The policy is pinned except for the relay origin, which differs between
 // staging (relay-staging.attn.sh) and production (relay.attn.sh) and is
 // injected via the worker's RELAY_ORIGIN var. Everything else stays
-// deliberately closed: no third-party scripts, analytics, or remote assets.
+// deliberately closed: no third-party scripts or analytics. HTTPS images are
+// the one explicit remote-content capability, gated by the renderer policy.
 
 import { THEME_PREFLIGHT_SHA256 } from './theme-preflight';
 
@@ -25,7 +26,7 @@ export function buildContentSecurityPolicy(
     "form-action 'none'",
     `frame-ancestors ${frameAncestors}`,
     "frame-src 'self' blob: data:",
-    "img-src 'self' blob: data:",
+    "img-src 'self' blob: data: https:",
     "manifest-src 'self'",
     "media-src 'self' blob: data:",
     "object-src 'none'",
diff --git a/web/src/lib/prosemirror/image-nodeview.test.ts b/web/src/lib/prosemirror/image-nodeview.test.ts
index acbe678d..8335e753 100644
--- a/web/src/lib/prosemirror/image-nodeview.test.ts
+++ b/web/src/lib/prosemirror/image-nodeview.test.ts
@@ -115,6 +115,7 @@ defineCase('1. the DOM gets the resolved src', () =>
       'displayed src',
     );
     assertEq(img.getAttribute('alt'), 'A diagram', 'alt is carried through');
+    assertEq(img.getAttribute('referrerpolicy'), 'no-referrer', 'image requests send no referrer');
   }),
 );
 
diff --git a/web/src/lib/prosemirror/image-nodeview.ts b/web/src/lib/prosemirror/image-nodeview.ts
index 50980bec..c0216506 100644
--- a/web/src/lib/prosemirror/image-nodeview.ts
+++ b/web/src/lib/prosemirror/image-nodeview.ts
@@ -79,6 +79,10 @@ export function imageNodeView(
   dom.className = 'md-image';
 
   const img = document.createElement('img');
+  // The owner workspace may render an authored HTTPS image, and a reviewer
+  // can explicitly enable one for this tab. Either way, the image host must
+  // not learn which document or share URL sent the reader there.
+  img.setAttribute('referrerpolicy', 'no-referrer');
 
   // Built once and only ever re-texted, so `update()` never has to remove
   // children — and so the placeholder occupies no space until it is needed.
@@ -146,11 +150,10 @@ export function imageNodeView(
     const title = typeof current.attrs.title === 'string' ? current.attrs.title : '';
 
     const resolved = resolveAssetUrl ? resolveAssetUrl(src) : null;
-    // A share resolver declining a source is a policy decision, not an
-    // invitation for the browser to try the authored URL. In particular,
-    // remote/data URLs and missing local assets must retain the image fallback
-    // without receiving an ambient network fetch capability. Editors with no
-    // resolver retain the historical authored-src behavior.
+    // A resolver declining a source is a policy decision, not an invitation
+    // for the browser to try the authored URL. Missing local assets and every
+    // non-HTTPS remote shape retain the fallback; a caller can return an
+    // approved HTTPS URL only after applying its own owner/reviewer policy.
     const display = resolveAssetUrl ? (resolved ?? UNRESOLVED_SHARED_IMAGE_SRC) : src;
 
     // Set only when there is one, matching the `title` handling below and the
diff --git a/web/src/lib/review/external-image-policy.test.ts b/web/src/lib/review/external-image-policy.test.ts
new file mode 100644
index 00000000..25684e47
--- /dev/null
+++ b/web/src/lib/review/external-image-policy.test.ts
@@ -0,0 +1,21 @@
+import { approvedExternalImageUrl } from './external-image-policy';
+
+function assertEq(actual: unknown, expected: unknown, label: string): void {
+  if (actual !== expected) {
+    throw new Error(`${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+assertEq(
+  approvedExternalImageUrl('https://images.example.test/charts/q3.png?theme=dark'),
+  'https://images.example.test/charts/q3.png?theme=dark',
+  'HTTPS image is accepted',
+);
+assertEq(approvedExternalImageUrl('http://images.example.test/chart.png'), null, 'HTTP is rejected');
+assertEq(approvedExternalImageUrl('//images.example.test/chart.png'), null, 'protocol-relative URL is rejected');
+assertEq(approvedExternalImageUrl('data:image/png;base64,AAAA'), null, 'data URL is rejected');
+assertEq(approvedExternalImageUrl('javascript:alert(1)'), null, 'script URL is rejected');
+assertEq(approvedExternalImageUrl('https://reader:secret@images.example.test/chart.png'), null, 'URL credentials are rejected');
+assertEq(approvedExternalImageUrl('./chart.png'), null, 'workspace-relative URL is not external');
+
+console.log('external-image-policy: 7 passed');
diff --git a/web/src/lib/review/external-image-policy.ts b/web/src/lib/review/external-image-policy.ts
new file mode 100644
index 00000000..835a5f2c
--- /dev/null
+++ b/web/src/lib/review/external-image-policy.ts
@@ -0,0 +1,19 @@
+/**
+ * A remote image is an ordinary Markdown affordance, but it is also a direct
+ * request from the reader's browser to an author-selected host. Keep the
+ * accepted surface deliberately narrow: HTTPS, no embedded credentials, and
+ * no protocol-relative or locally-resolved lookalikes.
+ *
+ * Callers decide *when* this capability is spent. The owner workspace permits
+ * it while a reviewer share requires an explicit, session-only choice.
+ */
+export function approvedExternalImageUrl(src: string): string | null {
+  if (!/^https:\/\//iu.test(src)) return null;
+  try {
+    const url = new URL(src);
+    if (url.protocol !== 'https:' || url.username !== '' || url.password !== '') return null;
+    return url.href;
+  } catch {
+    return null;
+  }
+}
diff --git a/web/src/lib/review/html-shared-assets.test.ts b/web/src/lib/review/html-shared-assets.test.ts
index ce80a039..52c0ec82 100644
--- a/web/src/lib/review/html-shared-assets.test.ts
+++ b/web/src/lib/review/html-shared-assets.test.ts
@@ -17,5 +17,10 @@ assertEqual(
   ` ${UNRESOLVED_SHARED_IMAGE_SRC} 1x`,
   'unresolved data source becomes a no-network fallback',
 );
+assertEqual(
+  rewriteSrcset('https://images.example.test/chart.png 1x', (src) => src.startsWith('https://') ? src : null),
+  'https://images.example.test/chart.png 1x',
+  'a caller-approved HTTPS source stays intact',
+);
 
-console.log('html-shared-assets: 2 passed, 0 failed');
+console.log('html-shared-assets: 3 passed, 0 failed');
diff --git a/web/src/lib/review/html-shared-assets.ts b/web/src/lib/review/html-shared-assets.ts
index f629dead..3b9f0dd1 100644
--- a/web/src/lib/review/html-shared-assets.ts
+++ b/web/src/lib/review/html-shared-assets.ts
@@ -1,9 +1,10 @@
 import { UNRESOLVED_SHARED_IMAGE_SRC } from './shared-image-policy';
 
 /**
- * Rewrites only share-bound HTML image URLs. The source remains inside a
- * sandboxed opaque-origin iframe; remote, data, and absent local references
- * become a non-decodable local fallback, so they cannot create a network path.
+ * Rewrites HTML image URLs through the caller's policy. The source remains
+ * inside a sandboxed opaque-origin iframe; rejected sources become a
+ * non-decodable local fallback. Reviewers may explicitly approve HTTPS images
+ * for a session, but that must never make data or unsafe schemes fetchable.
  */
 export function rewriteSharedHtmlImageSources(
   content: string,
@@ -11,9 +12,13 @@ export function rewriteSharedHtmlImageSources(
 ): string {
   if (!resolveAssetUrl || typeof DOMParser === 'undefined') return content;
   const document = new DOMParser().parseFromString(content, 'text/html');
-  for (const image of document.querySelectorAll<HTMLImageElement>('img[src]')) {
-    const resolved = resolveAssetUrl(image.getAttribute('src') ?? '');
-    image.setAttribute('src', resolved ?? UNRESOLVED_SHARED_IMAGE_SRC);
+  for (const image of document.querySelectorAll<HTMLImageElement>('img')) {
+    const src = image.getAttribute('src');
+    if (src !== null) {
+      const resolved = resolveAssetUrl(src);
+      image.setAttribute('src', resolved ?? UNRESOLVED_SHARED_IMAGE_SRC);
+    }
+    image.setAttribute('referrerpolicy', 'no-referrer');
   }
   for (const source of document.querySelectorAll<HTMLSourceElement>('img[srcset], source[srcset]')) {
     const srcset = source.getAttribute('srcset');

From b682ddbce8034972b9a58d63826e4eb5d5c5d895 Mon Sep 17 00:00:00 2001
From: Angus Bezzina <37071175+angusbezzina@users.noreply.github.com>
Date: Wed, 2 Sep 2026 13:47:03 -0500
Subject: [PATCH 08/10] Refine remote image fixture and download-only header

---
 tests/fixtures/images.md              |  6 +++---
 web/e2e/hosted-shells.spec.ts         |  7 +++++--
 web/src/hosted/app/EditorShell.svelte |  6 ++----
 web/src/hosted/app/app-shell.css      | 12 ++++++++++--
 4 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/tests/fixtures/images.md b/tests/fixtures/images.md
index b5b05b45..42a9414f 100644
--- a/tests/fixtures/images.md
+++ b/tests/fixtures/images.md
@@ -32,10 +32,10 @@ An HTTPS image is a normal Markdown source. The workspace owner may load one
 directly; an invited reader chooses whether to load external images for that
 review session, so the image host cannot silently observe a reader&rsquo;s request.
 
-This source is deliberately unavailable. **Expect a placeholder card here** —
-that proves a network failure, not a blocked remote-image policy.
+This image is hosted remotely. The owner workspace should request it directly;
+an invited reader should see the placeholder until they choose **Load images**.
 
-![A remote pixel](https://example.com/pixel.png)
+![A remote landscape](https://images.pexels.com/photos/35227957/pexels-photo-35227957.jpeg)
 
 ## Missing file
 
diff --git a/web/e2e/hosted-shells.spec.ts b/web/e2e/hosted-shells.spec.ts
index 5c15ec32..608053bd 100644
--- a/web/e2e/hosted-shells.spec.ts
+++ b/web/e2e/hosted-shells.spec.ts
@@ -403,8 +403,11 @@ test('asset entries render inline previews and download-only placeholders', asyn
   // Safe rasters render inline from (mock-)decrypted bytes.
   await expect(page.locator('.asset-image')).toBeVisible();
   await page.goto('/app/w/ws-product/data/notes.json?shell=demo');
-  await expect(page.locator('.hosted-native-document .eyebrow')).toHaveText('Download only');
-  await expect(page.locator('.asset-preview')).toContainText('never executed');
+  await expect(page.locator('.hosted-native-document > .eyebrow')).toHaveCount(0);
+  await expect(page.locator('.download-only-card h1')).toHaveText('notes.json');
+  await expect(page.locator('.download-only-path')).toHaveText('data/notes.json');
+  await expect(page.locator('.download-only-card h2')).toHaveCount(0);
+  await expect(page.locator('.download-only-card')).toContainText('This file stays inert in the browser');
   await expect(page.locator('.hosted-native-document').getByRole('button', { name: 'Download' })).toBeVisible();
 });
 
diff --git a/web/src/hosted/app/EditorShell.svelte b/web/src/hosted/app/EditorShell.svelte
index 94a4059b..52da2c80 100644
--- a/web/src/hosted/app/EditorShell.svelte
+++ b/web/src/hosted/app/EditorShell.svelte
@@ -3403,14 +3403,12 @@
       {/if}
     {:else if activeEntry && activeEntry.presentation !== 'editable'}
       {#if activeEntry.presentation === 'download-only'}
-        <div class="eyebrow">Download only</div>
-        <h1>{entryBasename(activeEntry)}</h1>
-        <p class="download-only-path">{activeEntry.path}</p>
         <section class="download-only-card" aria-labelledby="download-only-heading">
           <div class="download-only-intro">
             <span class="download-only-mark" aria-hidden="true">↓</span>
             <div>
-              <h2 id="download-only-heading">Ready for a local copy</h2>
+              <h1 id="download-only-heading" class="download-only-title">{entryBasename(activeEntry)}</h1>
+              <p class="download-only-path">{activeEntry.path}</p>
               <p>This file stays inert in the browser. Download it to use it in the right tool.</p>
             </div>
           </div>
diff --git a/web/src/hosted/app/app-shell.css b/web/src/hosted/app/app-shell.css
index 9dc0de98..e2030a37 100644
--- a/web/src/hosted/app/app-shell.css
+++ b/web/src/hosted/app/app-shell.css
@@ -979,7 +979,7 @@
    useful action dominant without turning the entire reading sheet into an
    empty dashed drop zone. */
 .download-only-path {
-  margin: -0.75rem 0 0;
+  margin: 0.35rem 0 0;
   color: var(--hosted-muted);
   font: 0.78rem/1.45 var(--mono);
   overflow-wrap: anywhere;
@@ -1016,13 +1016,21 @@
   font: 600 1.25rem/1 var(--serif);
 }
 
-.download-only-card h2 {
+.download-only-card h1 {
   margin: 0;
   font-size: 1.25rem;
   line-height: 1.2;
   letter-spacing: -0.015em;
 }
 
+.download-only-title {
+  overflow-wrap: anywhere;
+}
+
+.download-only-intro .download-only-path {
+  margin-top: 0.35rem;
+}
+
 .download-only-intro p {
   margin: 0.45rem 0 0;
   color: var(--hosted-muted);

From 9f49ab3d4ea51746d7034e3e90a996b262d2d87e Mon Sep 17 00:00:00 2001
From: Angus Bezzina <37071175+angusbezzina@users.noreply.github.com>
Date: Wed, 2 Sep 2026 13:58:42 -0500
Subject: [PATCH 09/10] Add folder picker and refine download note

---
 web/e2e/hosted-shells.spec.ts         |  6 ++--
 web/src/hosted/app/EditorShell.svelte | 40 ++++++++++++++++++---------
 web/src/hosted/app/app-shell.css      | 23 +++++++++++++++
 3 files changed, 54 insertions(+), 15 deletions(-)

diff --git a/web/e2e/hosted-shells.spec.ts b/web/e2e/hosted-shells.spec.ts
index 608053bd..4bd13671 100644
--- a/web/e2e/hosted-shells.spec.ts
+++ b/web/e2e/hosted-shells.spec.ts
@@ -161,7 +161,8 @@ test('a blank untitled.md opens the ordinary editor, rail and all', async ({ pag
   await expect(page.locator('[data-slot="canvas-invite"]')).toHaveCount(0);
   await expect(page.getByRole('textbox', { name: 'Filter files' })).toBeVisible();
   await expect(page.locator('[data-path][data-active="true"]')).toContainText('untitled.md');
-  await expect(page.locator('.hosted-sidebar-add')).toContainText('Add files');
+  await expect(page.locator('[data-action="add-assets"]')).toContainText('Add files');
+  await expect(page.locator('[data-action="add-folder"]')).toContainText('Add folder');
 
   // The invitation must not arrive late — the autosave commit that follows the
   // first keystroke refreshes the workspace, and that refresh used to clear the
@@ -407,7 +408,8 @@ test('asset entries render inline previews and download-only placeholders', asyn
   await expect(page.locator('.download-only-card h1')).toHaveText('notes.json');
   await expect(page.locator('.download-only-path')).toHaveText('data/notes.json');
   await expect(page.locator('.download-only-card h2')).toHaveCount(0);
-  await expect(page.locator('.download-only-card')).toContainText('This file stays inert in the browser');
+  await expect(page.locator('.download-only-note')).toHaveText('Note: This file stays inert in the browser. Download it to use it in the right tool.');
+  await expect(page.locator('.download-only-note')).toHaveCSS('font-style', 'italic');
   await expect(page.locator('.hosted-native-document').getByRole('button', { name: 'Download' })).toBeVisible();
 });
 
diff --git a/web/src/hosted/app/EditorShell.svelte b/web/src/hosted/app/EditorShell.svelte
index 52da2c80..d3fdf6ce 100644
--- a/web/src/hosted/app/EditorShell.svelte
+++ b/web/src/hosted/app/EditorShell.svelte
@@ -3409,7 +3409,7 @@
             <div>
               <h1 id="download-only-heading" class="download-only-title">{entryBasename(activeEntry)}</h1>
               <p class="download-only-path">{activeEntry.path}</p>
-              <p>This file stays inert in the browser. Download it to use it in the right tool.</p>
+              <p class="download-only-note"><strong>Note:</strong> This file stays inert in the browser. Download it to use it in the right tool.</p>
             </div>
           </div>
           <dl class="download-only-meta">
@@ -3696,18 +3696,32 @@
            thing a drag is actually aimed at — you cannot drop onto a word.
            It is still one real <button>, so the keyboard and pointer paths are
            unchanged; the button is simply the size and shape of the target. -->
-      <button
-        class="hosted-sidebar-add"
-        type="button"
-        data-action="add-assets"
-        onclick={() => assetInput?.click()}
-      >
-        <svg class="hosted-sidebar-add-glyph" viewBox="0 0 24 24" aria-hidden="true">
-          <path d="M12 5v14M5 12h14" />
-        </svg>
-        <span class="hosted-sidebar-add-label">Add files</span>
-        <span class="hosted-sidebar-add-hint">or drop them here</span>
-      </button>
+      <div class="hosted-sidebar-add-group">
+        <button
+          class="hosted-sidebar-add"
+          type="button"
+          data-action="add-assets"
+          onclick={() => assetInput?.click()}
+        >
+          <svg class="hosted-sidebar-add-glyph" viewBox="0 0 24 24" aria-hidden="true">
+            <path d="M12 5v14M5 12h14" />
+          </svg>
+          <span class="hosted-sidebar-add-label">Add files</span>
+          <span class="hosted-sidebar-add-hint">or drop them here</span>
+        </button>
+        <button
+          class="hosted-sidebar-add hosted-sidebar-add-folder"
+          type="button"
+          data-action="add-folder"
+          onclick={() => assetFolderInput?.click()}
+        >
+          <svg class="hosted-sidebar-add-glyph" viewBox="0 0 24 24" aria-hidden="true">
+            <path d="M3.75 7.25h6l1.6 1.8h8.9v8.7a1 1 0 0 1-1 1h-14.5a1 1 0 0 1-1-1z" />
+          </svg>
+          <span class="hosted-sidebar-add-label">Add folder</span>
+          <span class="hosted-sidebar-add-hint">choose a folder</span>
+        </button>
+      </div>
     {/if}
     {#if railError}
       <p class="hosted-sidebar-error" role="alert">{railError}</p>
diff --git a/web/src/hosted/app/app-shell.css b/web/src/hosted/app/app-shell.css
index e2030a37..1813bdc5 100644
--- a/web/src/hosted/app/app-shell.css
+++ b/web/src/hosted/app/app-shell.css
@@ -1038,6 +1038,18 @@
   line-height: 1.55;
 }
 
+.download-only-intro .download-only-note {
+  margin-top: 0.6rem;
+  color: var(--rust);
+  font-size: 0.85rem;
+  font-style: italic;
+  line-height: 1.45;
+}
+
+.download-only-note strong {
+  font-weight: 700;
+}
+
 .download-only-meta {
   display: grid;
   grid-template-columns: repeat(2, minmax(0, 1fr));
@@ -1723,6 +1735,17 @@
   transition: background-color 120ms ease, border-color 120ms ease;
 }
 
+.hosted-sidebar-add-group {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0.4rem;
+  width: 100%;
+}
+
+.hosted-sidebar-add-folder {
+  color: color-mix(in oklch, var(--sidebar-foreground) 82%, transparent);
+}
+
 .hosted-sidebar-add-label {
   font-weight: 550;
 }

From 3f2da4b71d9d8211ff1c60fb78d68591394118cb Mon Sep 17 00:00:00 2001
From: Angus Bezzina <37071175+angusbezzina@users.noreply.github.com>
Date: Wed, 2 Sep 2026 17:47:38 -0500
Subject: [PATCH 10/10] Fix hosted images, imports, and tree affordances

---
 .../fixtures/chooser-folder/chooser-folder.md |   3 +
 tests/fixtures/chooser-folder/deep/deep.md    |   3 +
 web/hosted-share-smoke.md                     |  25 +++
 web/scripts/test-hosted-local-share-ui.ts     | 149 +++++++++++++++++-
 web/src/app.css                               |  30 +++-
 web/src/hosted/app/EditorShell.svelte         |  74 +++++----
 web/src/hosted/app/ImportChooser.svelte       |  66 ++++++++
 web/src/hosted/app/OpenPage.svelte            |  26 ++-
 web/src/hosted/app/app-shell.css              | 114 +++++++++++++-
 web/src/lib/FileTree.svelte                   |   5 +-
 web/src/lib/ReviewFileTree.svelte             |  10 +-
 .../lib/review/external-image-policy.test.ts  |   7 +-
 web/src/lib/shell.test.ts                     |  65 ++++++++
 13 files changed, 526 insertions(+), 51 deletions(-)
 create mode 100644 tests/fixtures/chooser-folder/chooser-folder.md
 create mode 100644 tests/fixtures/chooser-folder/deep/deep.md
 create mode 100644 web/hosted-share-smoke.md
 create mode 100644 web/src/hosted/app/ImportChooser.svelte

diff --git a/tests/fixtures/chooser-folder/chooser-folder.md b/tests/fixtures/chooser-folder/chooser-folder.md
new file mode 100644
index 00000000..ea939118
--- /dev/null
+++ b/tests/fixtures/chooser-folder/chooser-folder.md
@@ -0,0 +1,3 @@
+# Folder chooser fixture
+
+This file verifies that a directory picker preserves its relative path.
diff --git a/tests/fixtures/chooser-folder/deep/deep.md b/tests/fixtures/chooser-folder/deep/deep.md
new file mode 100644
index 00000000..6a5f1ee0
--- /dev/null
+++ b/tests/fixtures/chooser-folder/deep/deep.md
@@ -0,0 +1,3 @@
+# Nested folder chooser fixture
+
+This nested file verifies independent disclosure state.
diff --git a/web/hosted-share-smoke.md b/web/hosted-share-smoke.md
new file mode 100644
index 00000000..78429921
--- /dev/null
+++ b/web/hosted-share-smoke.md
@@ -0,0 +1,25 @@
+# Hosted image and import smoke test
+
+Run the app with `task dev:app`, then open `http://127.0.0.1:5173/open`.
+
+1. Choose **Files or folder** → **Folder**, select `tests/fixtures`, and open
+   `images.md` in the new workspace. The Pexels image should render for the
+   owner; `./gone.png` should remain a truthful missing-file placeholder.
+2. Open the share control, create a review link, and visit it in a private
+   second browser context. The Pexels image remains blocked until **Load
+   external images** is chosen; after opting in it renders, and a reload resets
+   the choice.
+3. In the sidebar, use the single **Add files** well. Its menu must offer
+   **Files** and **Folder**; folder imports retain nested paths. Expand and
+   collapse nested folders: closed chevrons point right, open chevrons point
+   down, and row hover/active fills stay inside the vertical folder guide.
+
+Use `/open` for a fresh import when an existing workspace already contains the
+same path. Hosted workspaces deliberately reject duplicate paths rather than
+silently overwriting durable content; the editor exposes an **Open fresh
+import** link after that conflict.
+
+The deterministic lifecycle gate is `npm run test:share-ui:live` (or
+`ATTN_SHARE_UI_EXTERNAL=1 npm run test:share-ui:live` with externally managed
+local relay and Vite servers). It covers the exact Pexels URL, reviewer consent,
+reload/offline durability, and the existing unsafe/missing-image fallbacks.
diff --git a/web/scripts/test-hosted-local-share-ui.ts b/web/scripts/test-hosted-local-share-ui.ts
index 90223d65..c0704889 100644
--- a/web/scripts/test-hosted-local-share-ui.ts
+++ b/web/scripts/test-hosted-local-share-ui.ts
@@ -32,6 +32,7 @@ const appUrl = `http://127.0.0.1:${appPort}`;
 const commentMarker = 'LOCAL-OWNER-REVIEW-COMMENT-9173';
 const suggestionMarker = 'LOCAL-OWNER-REVIEW-SUGGESTION-9173';
 const sharedImageSource = '../images/pixel.png';
+const workingRemoteImageSource = 'https://images.pexels.com/photos/35227957/pexels-photo-35227957.jpeg';
 const remoteImageSource = 'https://images.attn.invalid/remote-share-image.png';
 const unresolvedImageSource = 'data:;base64,';
 const sharedPng = Buffer.from(
@@ -178,6 +179,75 @@ async function expectBlockedRemoteImage(page: Page, label: string): Promise<void
   }
 }
 
+async function expectBlockedApprovedImage(page: Page, label: string): Promise<void> {
+  const image = page.locator(`.md-image[data-src="${workingRemoteImageSource}"] img`);
+  await image.waitFor({ state: 'attached', timeout: 60_000 });
+  await image.waitFor({ state: 'hidden', timeout: 60_000 });
+  const detail = await image.evaluate((element) => ({
+    src: element.getAttribute('src'),
+    broken: element.parentElement?.getAttribute('data-broken'),
+  }));
+  if (detail.src !== unresolvedImageSource || detail.broken !== 'true') {
+    throw new Error(`${label} did not gate the approved remote image before opt-in: ${JSON.stringify(detail)}`);
+  }
+}
+
+async function expectResolvedExternalImage(page: Page, label: string): Promise<void> {
+  const wrapper = page.locator(`.md-image[data-src="${workingRemoteImageSource}"]`);
+  await wrapper.waitFor({ state: 'attached', timeout: 60_000 });
+  await page.waitForFunction(
+    (source) => document.querySelector(`.md-image[data-src="${source}"]`)?.getAttribute('data-loaded') === 'true',
+    workingRemoteImageSource,
+    { timeout: 60_000 },
+  );
+  const image = wrapper.locator('img');
+  const detail = await image.evaluate((element) => {
+    const imageElement = element as HTMLImageElement;
+    return {
+      src: imageElement.getAttribute('src'),
+      width: imageElement.naturalWidth,
+      height: imageElement.naturalHeight,
+      referrerPolicy: imageElement.getAttribute('referrerpolicy'),
+      loaded: imageElement.parentElement?.getAttribute('data-loaded'),
+    };
+  });
+  if (
+    detail.loaded !== 'true'
+    || detail.width !== 1
+    || detail.height !== 1
+    || detail.src !== workingRemoteImageSource
+    || detail.referrerPolicy !== 'no-referrer'
+  ) {
+    throw new Error(`${label} did not render the approved remote image: ${JSON.stringify(detail)}`);
+  }
+}
+
+async function chooseVisibleImport(
+  page: Page,
+  choice: 'Files' | 'Folder',
+  files: { name: string; mimeType: string; buffer: Buffer }[] | string,
+): Promise<void> {
+  await page.getByRole('button', { name: 'Add files', exact: true }).click();
+  const menuItem = page.getByRole('menuitem', { name: new RegExp(`^${choice}\\b`, 'u') });
+  await menuItem.waitFor({ state: 'visible' });
+  const fileChooser = page.waitForEvent('filechooser');
+  await menuItem.click();
+  await (await fileChooser).setFiles(files);
+}
+
+async function routeWorkingRemoteImage(context: BrowserContext): Promise<void> {
+  // Keep the success assertion deterministic in CI while preserving the exact
+  // authored HTTPS URL in the DOM. A manual smoke run against the app itself
+  // still exercises the real Pexels response; this route only avoids making the
+  // lifecycle gate depend on a third-party CDN.
+  await context.route(`${workingRemoteImageSource}**`, (route) => route.fulfill({
+    status: 200,
+    contentType: 'image/png',
+    body: sharedPng,
+    headers: { 'cache-control': 'no-store' },
+  }));
+}
+
 async function expectAttemptedExternalImage(page: Page, label: string): Promise<void> {
   const image = page.locator(`.md-image[data-src="${remoteImageSource}"] img`);
   await image.waitFor({ state: 'attached', timeout: 60_000 });
@@ -234,6 +304,18 @@ async function expectResolvedSharedHtmlImages(
   );
   await expect(remote).toHaveJSProperty('naturalWidth', 0, { timeout: 60_000 });
   await expect(remote).toHaveAttribute('referrerpolicy', 'no-referrer');
+  const approvedRemote = frame.locator('#working-remote-html-image');
+  await expect(approvedRemote).toHaveAttribute(
+    'src',
+    externalImagesEnabled ? workingRemoteImageSource : unresolvedImageSource,
+    { timeout: 60_000 },
+  );
+  if (externalImagesEnabled) {
+    await expect(approvedRemote).toHaveJSProperty('naturalWidth', 1, { timeout: 60_000 });
+    await expect(approvedRemote).toHaveJSProperty('naturalHeight', 1, { timeout: 60_000 });
+  } else {
+    await expect(approvedRemote).toHaveJSProperty('naturalWidth', 0, { timeout: 60_000 });
+  }
   const sandbox = await page.locator('[data-slot="html-viewer"] iframe').getAttribute('sandbox');
   if (sandbox?.includes('allow-same-origin')) {
     throw new Error(`${label} weakened the opaque-origin HTML sandbox: ${sandbox}`);
@@ -349,6 +431,7 @@ async function main(): Promise<void> {
 
   browser = await chromium.launch({ headless: true });
   ownerContext = await browser.newContext({ viewport: { width: 1440, height: 900 } });
+  await routeWorkingRemoteImage(ownerContext);
   // The product correctly asks a first-time owner to choose a display name
   // after a room becomes active. This lifecycle gate is about durable review
   // convergence, so provide that ordinary prerequisite before navigation.
@@ -509,7 +592,7 @@ async function main(): Promise<void> {
       name: 'docs/review.md',
       mimeType: 'text/markdown',
       buffer: Buffer.from(
-        `# Hosted image share\n\n![Verified chart](${sharedImageSource})\n\n![Remote fallback](${remoteImageSource})\n\n`,
+        `# Hosted image share\n\n![Verified chart](${sharedImageSource})\n\n![Remote landscape](${workingRemoteImageSource})\n\n![Remote fallback](${remoteImageSource})\n\n`,
       ),
     },
     {
@@ -522,6 +605,7 @@ async function main(): Promise<void> {
             <source id="verified-html-source" srcset="${sharedImageSource} 1x, ${remoteImageSource} 2x">
             <img id="picture-html-image" src="${sharedImageSource}" alt="Picture chart">
           </picture>
+          <img id="working-remote-html-image" src="${workingRemoteImageSource}" alt="Remote landscape">
           <img id="remote-html-image" src="${remoteImageSource}" alt="Remote fallback">
         </body></html>`,
       ),
@@ -530,7 +614,62 @@ async function main(): Promise<void> {
   ]);
   await imageOwner.getByRole('button', { name: 'review.md', exact: true }).waitFor({ state: 'visible' });
   await expectResolvedSharedImage(imageOwner, 'local owner');
+  await expectResolvedExternalImage(imageOwner, 'local owner');
   await expectAttemptedExternalImage(imageOwner, 'local owner');
+
+  // The visible rail affordance is one trigger with two explicit picker
+  // branches. Exercise both native inputs and retain a nested folder path so
+  // the tree geometry assertion below has a real branch to measure.
+  await chooseVisibleImport(imageOwner, 'Files', [{
+    name: 'chooser-file.md',
+    mimeType: 'text/markdown',
+    buffer: Buffer.from('# Files chooser\n'),
+  }]);
+  try {
+    await imageOwner.locator('[data-path$="/chooser-file.md"]').waitFor({ state: 'visible', timeout: 60_000 });
+  } catch (error) {
+    const debug = await imageOwner.evaluate(() => ({
+      paths: [...document.querySelectorAll('[data-path]')].map((element) => element.getAttribute('data-path')),
+      rail: document.querySelector('.hosted-sidebar-error')?.textContent ?? null,
+      inputs: [...document.querySelectorAll('input[type="file"]')].map((element) => ({
+        multiple: element.hasAttribute('multiple'),
+        directory: element.hasAttribute('webkitdirectory'),
+        files: (element as HTMLInputElement).files?.length ?? 0,
+      })),
+    }));
+    throw new Error(`files chooser import did not land: ${JSON.stringify(debug)}`, { cause: error });
+  }
+  await chooseVisibleImport(
+    imageOwner,
+    'Folder',
+    path.resolve(webRoot, '..', 'tests', 'fixtures', 'chooser-folder'),
+  );
+  const nestedRow = imageOwner.locator('[data-path$="/chooser-folder/chooser-folder.md"]');
+  await nestedRow.waitFor({ state: 'visible', timeout: 60_000 });
+  const folderRow = imageOwner.locator('[data-path$="/chooser-folder"]');
+  await folderRow.waitFor({ state: 'visible', timeout: 60_000 });
+  const deepFolderRow = imageOwner.locator('[data-path$="/chooser-folder/deep"]');
+  await deepFolderRow.waitFor({ state: 'visible', timeout: 60_000 });
+  await expect(deepFolderRow).toHaveAttribute('aria-expanded', 'false');
+  await expect(deepFolderRow.locator('.sidebar-tree-chevron')).not.toHaveClass(/sidebar-tree-chevron--open/u);
+  await expect(folderRow).toHaveAttribute('aria-expanded', 'true');
+  await expect(folderRow.locator('.sidebar-tree-chevron')).toHaveClass(/sidebar-tree-chevron--open/u);
+  const nestedGeometry = await nestedRow.evaluate((element) => {
+    const style = getComputedStyle(element);
+    return { marginInlineStart: style.marginInlineStart, width: style.width };
+  });
+  if (nestedGeometry.marginInlineStart === '0px' || nestedGeometry.width === '100%') {
+    throw new Error(`nested file row was not inset from its folder guide: ${JSON.stringify(nestedGeometry)}`);
+  }
+  await folderRow.click();
+  await expect(folderRow).toHaveAttribute('aria-expanded', 'false');
+  await expect(folderRow.locator('.sidebar-tree-chevron')).not.toHaveClass(/sidebar-tree-chevron--open/u);
+  await folderRow.click();
+  await expect(folderRow).toHaveAttribute('aria-expanded', 'true');
+  await deepFolderRow.click();
+  await expect(deepFolderRow).toHaveAttribute('aria-expanded', 'true');
+  await expect(deepFolderRow.locator('.sidebar-tree-chevron')).toHaveClass(/sidebar-tree-chevron--open/u);
+  await expect(folderRow).toHaveAttribute('aria-expanded', 'true');
   await imageOwner.getByRole('button', { name: 'preview.html', exact: true }).click();
   await expectResolvedSharedHtmlImages(imageOwner, 'local owner HTML document', true);
   await imageOwner.getByRole('button', { name: 'review.md', exact: true }).click();
@@ -540,6 +679,7 @@ async function main(): Promise<void> {
   const imageInvite = await createInvite(imageOwner, { selectAll: true });
 
   reviewerContext = await browser.newContext({ viewport: { width: 1440, height: 900 } });
+  await routeWorkingRemoteImage(reviewerContext);
   await reviewerContext.addInitScript(seedProfileDisplayName, { displayName: 'Image review agent' });
   const imageReviewer = await reviewerContext.newPage();
   captureBrowserFailures(imageReviewer, 'image reviewer');
@@ -548,10 +688,12 @@ async function main(): Promise<void> {
   await imageReviewer.waitForFunction(() => document.querySelector('[data-slot="browser-review"]')?.getAttribute('data-authoring-ready') === 'true');
   await imageReviewer.getByRole('button', { name: /review\.md/u }).click();
   await expectResolvedSharedImage(imageReviewer, 'live invited reviewer');
+  await expectBlockedApprovedImage(imageReviewer, 'live invited reviewer');
   await expectBlockedRemoteImage(imageReviewer, 'live invited reviewer');
   const loadExternalImages = imageReviewer.getByRole('button', { name: 'Load external images for this review' });
   await loadExternalImages.waitFor({ state: 'visible' });
   await loadExternalImages.click();
+  await expectResolvedExternalImage(imageReviewer, 'opted-in invited reviewer');
   await expectAttemptedExternalImage(imageReviewer, 'opted-in invited reviewer');
   await imageReviewer.getByRole('button', { name: /preview\.html/u }).click();
   await expectResolvedSharedHtmlImages(imageReviewer, 'opted-in invited reviewer HTML document', true);
@@ -563,6 +705,7 @@ async function main(): Promise<void> {
   await follower.locator('[data-slot="browser-review"]').waitFor({ state: 'visible' });
   await follower.getByRole('button', { name: /review\.md/u }).click();
   await expectResolvedSharedImage(follower, 'follower reviewer tab');
+  await expectBlockedApprovedImage(follower, 'follower reviewer tab');
   await expectBlockedRemoteImage(follower, 'follower reviewer tab');
   await follower.close();
 
@@ -574,6 +717,7 @@ async function main(): Promise<void> {
   await expectResolvedSharedHtmlImages(imageReviewer, 'reloaded invited reviewer HTML document');
   await imageReviewer.getByRole('button', { name: /review\.md/u }).click();
   await expectResolvedSharedImage(imageReviewer, 'reloaded invited reviewer');
+  await expectBlockedApprovedImage(imageReviewer, 'reloaded invited reviewer');
   await expectBlockedRemoteImage(imageReviewer, 'reloaded invited reviewer');
   await reviewerContext.close();
   reviewerContext = null;
@@ -585,6 +729,7 @@ async function main(): Promise<void> {
   await ownerContext.close();
   ownerContext = null;
   offlineReviewerContext = await browser.newContext({ viewport: { width: 1440, height: 900 } });
+  await routeWorkingRemoteImage(offlineReviewerContext);
   await offlineReviewerContext.addInitScript(seedProfileDisplayName, { displayName: 'Offline review agent' });
   const offlineReviewer = await offlineReviewerContext.newPage();
   captureBrowserFailures(offlineReviewer, 'offline reviewer');
@@ -597,11 +742,13 @@ async function main(): Promise<void> {
   await expectResolvedSharedHtmlImages(offlineReviewer, 'owner-offline durable reviewer HTML document');
   await offlineReviewer.getByRole('button', { name: /review\.md/u }).click();
   await expectResolvedSharedImage(offlineReviewer, 'owner-offline durable reviewer');
+  await expectBlockedApprovedImage(offlineReviewer, 'owner-offline durable reviewer');
   await expectBlockedRemoteImage(offlineReviewer, 'owner-offline durable reviewer');
   await offlineReviewer.reload({ waitUntil: 'domcontentloaded' });
   await offlineReviewer.locator('[data-slot="browser-review"]').waitFor({ state: 'visible' });
   await offlineReviewer.waitForFunction(() => document.querySelector('[data-slot="browser-review"]')?.getAttribute('data-owner-online') === 'false');
   await expectResolvedSharedImage(offlineReviewer, 'reloaded owner-offline durable reviewer');
+  await expectBlockedApprovedImage(offlineReviewer, 'reloaded owner-offline durable reviewer');
   await expectBlockedRemoteImage(offlineReviewer, 'reloaded owner-offline durable reviewer');
   step('hosted image share survived follower, reload, and owner-offline durable review');
 
diff --git a/web/src/app.css b/web/src/app.css
index 20a80818..905e2d4e 100644
--- a/web/src/app.css
+++ b/web/src/app.css
@@ -286,8 +286,10 @@ ul.sidebar-tree-menu[data-sidebar] {
     min-height: 34px;
     max-height: 34px;
     margin-bottom: 2px;
+    margin-inline-start: calc(var(--tree-depth, 0) * 20px);
+    width: calc(100% - var(--tree-depth, 0) * 20px);
     padding-right: 10px;
-    padding-left: calc(var(--tree-depth, 0) * 20px + 10px);
+    padding-left: 10px;
     border: 1px solid transparent;
     border-radius: 8px;
     background: color-mix(in oklch, var(--foreground) 19%, transparent);
@@ -923,8 +925,12 @@ ul.sidebar-tree-menu[data-sidebar] {
     min-height: 34px;
     max-height: 34px;
     margin-bottom: 2px;
+    /* Nested disclosure guides belong to the parent branch. Keep the row's
+       fill and active tick inside that guide instead of painting over it. */
+    margin-inline-start: calc(var(--tree-depth, 0) * 20px);
+    width: calc(100% - var(--tree-depth, 0) * 20px);
     padding-right: 10px !important;
-    padding-left: calc(var(--tree-depth, 0) * 20px + 10px) !important;
+    padding-left: 10px !important;
     font-size: 0.875rem;
     line-height: 1;
     border: 1px solid transparent;
@@ -1009,6 +1015,26 @@ ul.sidebar-tree-menu[data-sidebar] {
 
   .sidebar-tree-chevron {
     color: color-mix(in oklch, var(--sidebar-foreground) 72%, transparent);
+    transition: transform var(--t) var(--ease);
+  }
+
+  .sidebar-tree-chevron--open {
+    transform: rotate(90deg);
+  }
+
+  .review-tree-chevron {
+    transition: transform var(--t) var(--ease);
+  }
+
+  .review-tree-chevron--open {
+    transform: rotate(90deg);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .sidebar-tree-chevron,
+    .review-tree-chevron {
+      transition: none;
+    }
   }
 
   .sidebar-tree-icon {
diff --git a/web/src/hosted/app/EditorShell.svelte b/web/src/hosted/app/EditorShell.svelte
index d3fdf6ce..b9c3b485 100644
--- a/web/src/hosted/app/EditorShell.svelte
+++ b/web/src/hosted/app/EditorShell.svelte
@@ -62,6 +62,7 @@
   import { htmlImageSources, markdownImageSources } from '../../lib/review/document-image-sources';
   import { isSupportedSharedImageMediaType } from '../../lib/review/shared-image-policy';
   import LoadingLine from './LoadingLine.svelte';
+  import ImportChooser from './ImportChooser.svelte';
   import HtmlViewer from '../../lib/HtmlViewer.svelte';
   import HtmlCommentComposer from '../../lib/HtmlCommentComposer.svelte';
   import type {
@@ -375,6 +376,7 @@
   // no-op instead of renaming/deleting whichever file became active.
   let entryActionPath = $state<string | null>(null);
   let railError = $state<string | null>(null);
+  let importConflict = $state(false);
   let downloadingActiveEntry = $state(false);
   let activeEntryDownloadError = $state<string | null>(null);
   let assetInput = $state<HTMLInputElement | undefined>();
@@ -1004,6 +1006,7 @@
     const wsId = workspace.id;
     const onScreen = (): boolean => workspace.id === wsId;
     railError = null;
+    importConflict = false;
     try {
       await importIntoWorkspace({
         workspaceId: wsId,
@@ -1023,7 +1026,13 @@
     } catch (error) {
       // The rail belongs to whatever is on screen now; an error about a
       // workspace the user has left would read as a failure of this one.
-      if (onScreen()) railError = error instanceof Error ? error.message : String(error);
+      if (onScreen()) {
+        const message = error instanceof Error ? error.message : String(error);
+        importConflict = /entry already exists/iu.test(message);
+        railError = importConflict
+          ? 'That path already exists in this workspace. Open a fresh import to use the current folder contents.'
+          : message;
+      }
     } finally {
       if (assetInput) assetInput.value = '';
     }
@@ -3468,10 +3477,10 @@
       {/if}
     {/if}
       {#if showCanvasInvite}
-        <!-- Not aria-hidden. It holds two buttons and the only visible route
-             back to the desk, and aria-hidden over focusable controls is the
-             "hidden but tabbable" defect, not a fix — assistive tech would be
-             handed a page whose every control it must not describe. -->
+        <!-- Not aria-hidden. It holds the import trigger and the only visible
+             route back to the desk, and aria-hidden over focusable controls is
+             the "hidden but tabbable" defect, not a fix — assistive tech would
+             be handed a page whose controls it must not describe. -->
         <div class="canvas-invite" data-slot="canvas-invite">
           <div class="canvas-invite-card">
             <BrandMark size={40} />
@@ -3485,12 +3494,12 @@
                 : 'Drop a Markdown file or a folder here, or choose one.'}
             </p>
             <div class="canvas-invite-actions">
-              <button class="button primary" type="button" onclick={() => assetInput?.click()}>
-                Choose files
-              </button>
-              <button class="button" type="button" onclick={() => assetFolderInput?.click()}>
-                Choose folder
-              </button>
+              <ImportChooser
+                variant="canvas"
+                label="Choose files or folder"
+                onChooseFiles={() => assetInput?.click()}
+                onChooseFolder={() => assetFolderInput?.click()}
+              />
             </div>
             <p class="canvas-invite-privacy">
               Files stay in this browser profile — nothing is uploaded.
@@ -3697,34 +3706,20 @@
            It is still one real <button>, so the keyboard and pointer paths are
            unchanged; the button is simply the size and shape of the target. -->
       <div class="hosted-sidebar-add-group">
-        <button
-          class="hosted-sidebar-add"
-          type="button"
-          data-action="add-assets"
-          onclick={() => assetInput?.click()}
-        >
-          <svg class="hosted-sidebar-add-glyph" viewBox="0 0 24 24" aria-hidden="true">
-            <path d="M12 5v14M5 12h14" />
-          </svg>
-          <span class="hosted-sidebar-add-label">Add files</span>
-          <span class="hosted-sidebar-add-hint">or drop them here</span>
-        </button>
-        <button
-          class="hosted-sidebar-add hosted-sidebar-add-folder"
-          type="button"
-          data-action="add-folder"
-          onclick={() => assetFolderInput?.click()}
-        >
-          <svg class="hosted-sidebar-add-glyph" viewBox="0 0 24 24" aria-hidden="true">
-            <path d="M3.75 7.25h6l1.6 1.8h8.9v8.7a1 1 0 0 1-1 1h-14.5a1 1 0 0 1-1-1z" />
-          </svg>
-          <span class="hosted-sidebar-add-label">Add folder</span>
-          <span class="hosted-sidebar-add-hint">choose a folder</span>
-        </button>
+        <ImportChooser
+          variant="sidebar"
+          label="Add files"
+          hint="or drop them here"
+          onChooseFiles={() => assetInput?.click()}
+          onChooseFolder={() => assetFolderInput?.click()}
+        />
       </div>
     {/if}
     {#if railError}
       <p class="hosted-sidebar-error" role="alert">{railError}</p>
+      {#if importConflict}
+        <a class="hosted-sidebar-error-action" href="/open">Open fresh import</a>
+      {/if}
     {/if}
   </div>
 {/snippet}
@@ -4123,9 +4118,12 @@
         </div>
       {/if}
     {/each}
-    <button class="file-add-row" type="button" onclick={() => assetInput?.click()}>
-      ＋ Add file or asset
-    </button>
+    <ImportChooser
+      variant="sheet"
+      label="＋ Add file or asset"
+      onChooseFiles={() => assetInput?.click()}
+      onChooseFolder={() => assetFolderInput?.click()}
+    />
   </BottomSheet>
 {/if}
 
diff --git a/web/src/hosted/app/ImportChooser.svelte b/web/src/hosted/app/ImportChooser.svelte
new file mode 100644
index 00000000..5c3b6221
--- /dev/null
+++ b/web/src/hosted/app/ImportChooser.svelte
@@ -0,0 +1,66 @@
+<script lang="ts">
+  import Files from '@lucide/svelte/icons/files';
+  import FolderOpen from '@lucide/svelte/icons/folder-open';
+  import * as DropdownMenu from '$lib/components/ui/dropdown-menu';
+
+  interface Props {
+    label?: string;
+    hint?: string;
+    variant?: 'sidebar' | 'canvas' | 'sheet';
+    onChooseFiles?: () => void;
+    onChooseFolder?: () => void;
+  }
+
+  let {
+    label = 'Add files',
+    hint = 'or drop them here',
+    variant = 'sidebar',
+    onChooseFiles,
+    onChooseFolder,
+  }: Props = $props();
+
+  let open = $state(false);
+
+  function choose(callback: (() => void) | undefined): void {
+    open = false;
+    callback?.();
+  }
+</script>
+
+<DropdownMenu.Root bind:open>
+  <DropdownMenu.Trigger
+    class={`import-chooser-trigger import-chooser-trigger--${variant}`}
+    data-slot="import-chooser"
+    data-action={variant === 'sidebar' ? 'add-assets' : undefined}
+    aria-label={label}
+    aria-haspopup="menu"
+    aria-expanded={open}
+  >
+    {#if variant === 'sidebar'}
+      <svg class="hosted-sidebar-add-glyph" viewBox="0 0 24 24" aria-hidden="true">
+        <path d="M12 5v14M5 12h14" />
+      </svg>
+      <span class="hosted-sidebar-add-label">{label}</span>
+      {#if hint}<span class="hosted-sidebar-add-hint">{hint}</span>{/if}
+    {:else}
+      <span class="import-chooser-trigger-copy">{label}</span>
+    {/if}
+  </DropdownMenu.Trigger>
+  <DropdownMenu.Content align={variant === 'sidebar' ? 'start' : 'center'} class="import-chooser-menu">
+    <DropdownMenu.Label>Bring in</DropdownMenu.Label>
+    <DropdownMenu.Item onSelect={() => choose(onChooseFiles)}>
+      <Files class="size-4" aria-hidden="true" />
+      <span class="import-chooser-item-copy">
+        <strong>Files</strong>
+        <small>Choose one or more files</small>
+      </span>
+    </DropdownMenu.Item>
+    <DropdownMenu.Item onSelect={() => choose(onChooseFolder)}>
+      <FolderOpen class="size-4" aria-hidden="true" />
+      <span class="import-chooser-item-copy">
+        <strong>Folder</strong>
+        <small>Keep the folder structure</small>
+      </span>
+    </DropdownMenu.Item>
+  </DropdownMenu.Content>
+</DropdownMenu.Root>
diff --git a/web/src/hosted/app/OpenPage.svelte b/web/src/hosted/app/OpenPage.svelte
index f83632a4..399bb5f1 100644
--- a/web/src/hosted/app/OpenPage.svelte
+++ b/web/src/hosted/app/OpenPage.svelte
@@ -3,6 +3,7 @@
   import { expandPicked, prepareImport } from './import-files';
   import { fileDrop, filesToPicked, type DroppedFile } from './file-drop';
   import type { ImportFileInput, StorageHealth } from './types';
+  import ImportChooser from './ImportChooser.svelte';
 
   interface Props {
     health: StorageHealth;
@@ -12,6 +13,7 @@
   const { health, onImport }: Props = $props();
 
   let fileInput = $state<HTMLInputElement | undefined>();
+  let folderInput = $state<HTMLInputElement | undefined>();
   let importError = $state<string | null>(null);
 
   async function importFiles(files: Iterable<File | DroppedFile>): Promise<void> {
@@ -30,6 +32,12 @@
     const files = fileInput?.files;
     if (files && files.length > 0) void importFiles(Array.from(files));
   }
+
+  function onFolderPicked(): void {
+    const files = folderInput?.files;
+    if (files && files.length > 0) void importFiles(Array.from(files));
+    if (folderInput) folderInput.value = '';
+  }
 </script>
 
 <main class="desk">
@@ -76,9 +84,12 @@
       <li><code>.zip</code></li>
     </ul>
     <div class="storage-actions drop-zone-actions">
-      <button class="button primary" type="button" onclick={() => fileInput?.click()}>
-        Choose files
-      </button>
+      <ImportChooser
+        variant="canvas"
+        label="Choose files or folder"
+        onChooseFiles={() => fileInput?.click()}
+        onChooseFolder={() => folderInput?.click()}
+      />
     </div>
     <input
       bind:this={fileInput}
@@ -90,6 +101,15 @@
       tabindex="-1"
       onchange={onFilesPicked}
     />
+    <input
+      bind:this={folderInput}
+      type="file"
+      webkitdirectory
+      class="visually-removed"
+      aria-hidden="true"
+      tabindex="-1"
+      onchange={onFolderPicked}
+    />
     {#if importError}
       <!-- Title, next step, then the raw message as evidence — the same shape
            the storage page and reviewer-lifecycle use (attn-08fa.8). It read
diff --git a/web/src/hosted/app/app-shell.css b/web/src/hosted/app/app-shell.css
index 1813bdc5..eeaece0c 100644
--- a/web/src/hosted/app/app-shell.css
+++ b/web/src/hosted/app/app-shell.css
@@ -1354,6 +1354,107 @@
   pointer-events: auto;
 }
 
+/* One import affordance, two explicit choices. The trigger keeps the existing
+   drop-well footprint in the rail while the menu prevents "files" and
+   "folder" from reading as competing actions. */
+.import-chooser-trigger {
+  cursor: pointer;
+}
+
+.import-chooser-trigger--sidebar {
+  display: grid;
+  width: 100%;
+  justify-items: center;
+  align-content: center;
+  gap: 0.15rem;
+  min-height: 74px;
+  padding: 0.7rem 0.55rem;
+  border: 1px dashed color-mix(in oklch, var(--sidebar-foreground) 18%, transparent);
+  border-radius: 8px;
+  background: transparent;
+  color: var(--sidebar-foreground);
+  font: 500 0.7rem var(--sans);
+  text-align: center;
+  transition: background-color 120ms var(--ease), border-color 120ms var(--ease);
+}
+
+.import-chooser-trigger--sidebar:hover {
+  border-color: color-mix(in oklch, var(--sidebar-foreground) 14%, transparent);
+  background: var(--sidebar-accent);
+}
+
+.import-chooser-trigger--sidebar:focus-visible {
+  outline: 2px solid var(--sidebar-ring);
+  outline-offset: 1px;
+}
+
+.import-chooser-trigger--canvas {
+  min-height: 2.25rem;
+  padding: 0.55rem 0.85rem;
+  border: 1px solid color-mix(in oklch, var(--ink) 24%, transparent);
+  border-radius: var(--radius-md);
+  background: var(--sheet-raised);
+  color: var(--ink);
+  font: 650 0.85rem var(--sans);
+  transition: background-color var(--t) var(--ease), border-color var(--t) var(--ease);
+}
+
+.import-chooser-trigger--canvas:hover,
+.import-chooser-trigger--canvas:focus-visible {
+  border-color: var(--rust);
+  background: color-mix(in oklch, var(--sheet-raised) 76%, var(--rust));
+}
+
+.import-chooser-trigger--sheet {
+  width: 100%;
+  min-height: 48px;
+  margin-top: 0.5rem;
+  border: 1px dashed var(--rule);
+  border-radius: var(--radius-md);
+  background: transparent;
+  color: var(--hosted-muted);
+  font: 650 0.85rem var(--sans);
+  transition: border-color var(--t) var(--ease), color var(--t) var(--ease);
+}
+
+.import-chooser-trigger--sheet:hover {
+  border-color: var(--rust);
+  color: var(--ink);
+}
+
+.import-chooser-trigger:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+
+.import-chooser-menu {
+  min-width: 15rem;
+}
+
+.import-chooser-item-copy {
+  display: grid;
+  gap: 0.12rem;
+  min-width: 0;
+}
+
+.import-chooser-item-copy strong {
+  font-weight: 650;
+}
+
+.import-chooser-item-copy small {
+  color: var(--muted-foreground);
+  font-size: 0.7rem;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .import-chooser-trigger,
+  .import-chooser-trigger--sidebar,
+  .import-chooser-trigger--canvas,
+  .import-chooser-trigger--sheet {
+    transition: none;
+  }
+}
+
 /* One hint, not two. The invitation's own lede already says "or just start
    typing", so the ProseMirror placeholder underneath would say it again — two
    sentences of first-run copy stacked on one empty page. */
@@ -1736,12 +1837,19 @@
 }
 
 .hosted-sidebar-add-group {
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-  gap: 0.4rem;
+  display: block;
   width: 100%;
 }
 
+.hosted-sidebar-error-action {
+  display: inline-block;
+  margin-top: 0.2rem;
+  color: var(--sidebar-primary);
+  font: 650 0.7rem var(--sans);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
 .hosted-sidebar-add-folder {
   color: color-mix(in oklch, var(--sidebar-foreground) 82%, transparent);
 }
diff --git a/web/src/lib/FileTree.svelte b/web/src/lib/FileTree.svelte
index e80c9cfd..ed42f962 100644
--- a/web/src/lib/FileTree.svelte
+++ b/web/src/lib/FileTree.svelte
@@ -281,7 +281,10 @@
                     data-path={node.path}
                     style={`--tree-depth: ${depth};`}
                   >
-                    <ChevronRight class="sidebar-tree-chevron size-3.5 shrink-0 transition-transform duration-150 group-data-[state=open]/collapsible:rotate-90" />
+                    <ChevronRight
+                      class={`sidebar-tree-chevron size-3.5 shrink-0${exp ? ' sidebar-tree-chevron--open' : ''}`}
+                      aria-hidden="true"
+                    />
                     {#if folderIcon}
                       <img src={folderIcon} alt="" aria-hidden="true" class="sidebar-tree-icon-image size-3.5 shrink-0" />
                     {:else}
diff --git a/web/src/lib/ReviewFileTree.svelte b/web/src/lib/ReviewFileTree.svelte
index f77676d6..391018b6 100644
--- a/web/src/lib/ReviewFileTree.svelte
+++ b/web/src/lib/ReviewFileTree.svelte
@@ -45,7 +45,7 @@
         onclick={() => toggle(node.path)}
       >
         <ChevronRight
-          class="review-tree-chevron size-3.5 shrink-0 transition-transform {collapsed.has(node.path) ? '' : 'rotate-90'}"
+          class={`review-tree-chevron size-3.5 shrink-0${collapsed.has(node.path) ? '' : ' review-tree-chevron--open'}`}
           aria-hidden="true"
         />
         <span class="truncate">{node.name}</span>
@@ -105,7 +105,7 @@
     line-height: 1.1;
     text-align: left;
     color: var(--muted-foreground);
-    transition: background-color 0.12s ease, color 0.12s ease;
+    transition: background-color var(--t) var(--ease), color var(--t) var(--ease);
   }
 
   .review-tree-row:hover {
@@ -123,4 +123,10 @@
     font-weight: 500;
     color: var(--foreground, inherit);
   }
+
+  @media (prefers-reduced-motion: reduce) {
+    .review-tree-row {
+      transition: none;
+    }
+  }
 </style>
diff --git a/web/src/lib/review/external-image-policy.test.ts b/web/src/lib/review/external-image-policy.test.ts
index 25684e47..efb4991e 100644
--- a/web/src/lib/review/external-image-policy.test.ts
+++ b/web/src/lib/review/external-image-policy.test.ts
@@ -11,6 +11,11 @@ assertEq(
   'https://images.example.test/charts/q3.png?theme=dark',
   'HTTPS image is accepted',
 );
+assertEq(
+  approvedExternalImageUrl('https://images.pexels.com/photos/35227957/pexels-photo-35227957.jpeg'),
+  'https://images.pexels.com/photos/35227957/pexels-photo-35227957.jpeg',
+  'the hosted fixture URL is accepted as an ordinary HTTPS image',
+);
 assertEq(approvedExternalImageUrl('http://images.example.test/chart.png'), null, 'HTTP is rejected');
 assertEq(approvedExternalImageUrl('//images.example.test/chart.png'), null, 'protocol-relative URL is rejected');
 assertEq(approvedExternalImageUrl('data:image/png;base64,AAAA'), null, 'data URL is rejected');
@@ -18,4 +23,4 @@ assertEq(approvedExternalImageUrl('javascript:alert(1)'), null, 'script URL is r
 assertEq(approvedExternalImageUrl('https://reader:secret@images.example.test/chart.png'), null, 'URL credentials are rejected');
 assertEq(approvedExternalImageUrl('./chart.png'), null, 'workspace-relative URL is not external');
 
-console.log('external-image-policy: 7 passed');
+console.log('external-image-policy: 8 passed');
diff --git a/web/src/lib/shell.test.ts b/web/src/lib/shell.test.ts
index 6109b309..8b604ca9 100644
--- a/web/src/lib/shell.test.ts
+++ b/web/src/lib/shell.test.ts
@@ -388,6 +388,71 @@ defineCase('renaming a file edits its row, not a field at the foot of the rail',
   );
 });
 
+defineCase('file-tree disclosure and selection stay inside the branch guide', () => {
+  const tree = read('FileTree.svelte');
+  const reviewTree = read('ReviewFileTree.svelte');
+  const css = read('../app.css');
+
+  assert(
+    tree.includes("sidebar-tree-chevron--open") && tree.includes('exp ?'),
+    'the owner tree chevron must derive its direction from the folder open state',
+  );
+  assert(
+    reviewTree.includes('review-tree-chevron--open') && reviewTree.includes('collapsed.has(node.path)'),
+    'the review tree chevron must derive its direction from the folder collapsed state',
+  );
+  assert(
+    css.includes('transition: transform var(--t) var(--ease)')
+      && css.includes('.sidebar-tree-chevron--open')
+      && css.includes('.review-tree-chevron--open'),
+    'both trees need the shared eased disclosure motion',
+  );
+  assert(
+    css.includes('margin-inline-start: calc(var(--tree-depth, 0) * 20px)')
+      && css.includes('width: calc(100% - var(--tree-depth, 0) * 20px)')
+      && css.includes('padding-left: 10px !important'),
+    'nested row fills must be inset from the containing guide while preserving label spacing',
+  );
+  assert(
+    css.includes('@media (prefers-reduced-motion: reduce)')
+      && css.includes('.sidebar-tree-chevron,\n    .review-tree-chevron'),
+    'disclosure motion must respect reduced-motion preferences',
+  );
+});
+
+defineCase('hosted import uses one files-or-folder chooser', () => {
+  const shell = read('../hosted/app/EditorShell.svelte');
+  const openPage = read('../hosted/app/OpenPage.svelte');
+  const chooser = read('../hosted/app/ImportChooser.svelte');
+
+  assert(
+    chooser.includes('Choose one or more files') && chooser.includes('Keep the folder structure'),
+    'the chooser must expose files and folders as explicit menu choices',
+  );
+  assert(
+    (shell.match(/<ImportChooser/g) ?? []).length >= 3,
+    'sidebar, empty canvas, and mobile sheet must share the chooser',
+  );
+  assert(
+    shell.includes('webkitdirectory') && shell.includes('bind:this={assetFolderInput}'),
+    'the folder input must remain available behind the shared chooser',
+  );
+  assert(
+    openPage.includes('<ImportChooser') && openPage.includes('bind:this={folderInput}')
+      && openPage.includes('webkitdirectory'),
+    'the desk import route must offer the same folder choice',
+  );
+  assert(
+    !shell.includes('data-action="add-folder"'),
+    'the sidebar must not expose a second competing folder button',
+  );
+  assert(
+    shell.includes('Open a fresh import to use the current folder contents.')
+      && shell.includes('href="/open"'),
+    'duplicate imports must explain the stale-workspace path and link to a fresh import',
+  );
+});
+
 let failed = 0;
 for (const run of cases) {
   const result = run();