@1agh/maude 0.60.2 → 0.60.4

package/apps/studio/sync/remote-docs.ts

@@ -32,6 +32,29 @@ export interface RemoteDoc {
   bytes: number;
 }
 
+/** One deletion the project has stated — see the hub's `tombstones.mjs`. */
+export interface RemoteTombstone {
+  name: string;
+  deletedAt: number;
+}
+
+/**
+ * The whole listing: what the project HAS, and what it has DELETED.
+ *
+ * Both halves are needed, and for symmetric reasons. Presence alone made a
+ * hub-only document authority to create a local file — correct, and the reason
+ * a project arrives in full. Absence alone was un-representable, so a delete was
+ * indistinguishable from "this peer has not discovered it yet" and got refilled
+ * on the next tick. One request carries both.
+ */
+export interface RemoteListing {
+  documents: RemoteDoc[];
+  /** Empty against a hub older than the tombstone route — never null, because
+   *  "this hub cannot say" and "nothing was deleted" call for the same
+   *  behaviour: change nothing on disk. */
+  tombstones: RemoteTombstone[];
+}
+
 export interface RemoteDocDiff {
   /** Documents on both sides — the ones actually syncing. */
   shared: string[];
@@ -54,11 +77,11 @@ const LIST_TIMEOUT_MS = 6000;
  * reporting improvement, and making it load-bearing would trade a real feature
  * for a nicer message.
  */
-export async function fetchRemoteDocs(
+export async function fetchRemoteListing(
   hubUrl: string,
   token: string,
   fetchImpl: typeof fetch = fetch
-): Promise<RemoteDoc[] | null> {
+): Promise<RemoteListing | null> {
   try {
     const base = hubUrl.replace(/\/+$/, '');
     const res = await fetchImpl(`${base}/api/documents`, {
@@ -66,19 +89,64 @@ export async function fetchRemoteDocs(
       signal: AbortSignal.timeout(LIST_TIMEOUT_MS),
     });
     if (!res.ok) return null;
-    const body = (await res.json()) as { documents?: unknown };
+    const body = (await res.json()) as { documents?: unknown; tombstones?: unknown };
     if (!Array.isArray(body?.documents)) return null;
-    return body.documents
+    const documents = body.documents
       .filter(
         (d): d is RemoteDoc =>
           !!d && typeof (d as RemoteDoc).name === 'string' && (d as RemoteDoc).name.length > 0
       )
       .map((d) => ({ name: d.name, bytes: Number(d.bytes) || 0 }));
+    // A hub without the route omits the field entirely; a hostile one could send
+    // anything. Both land on "no deletions", which changes nothing on disk — the
+    // safe direction for a signal whose only effect is to REMOVE local files.
+    const tombstones = Array.isArray(body?.tombstones)
+      ? (body.tombstones as unknown[])
+          .filter(
+            (t): t is RemoteTombstone =>
+              !!t &&
+              typeof (t as RemoteTombstone).name === 'string' &&
+              (t as RemoteTombstone).name.length > 0
+          )
+          .map((t) => ({ name: t.name, deletedAt: Number(t.deletedAt) || 0 }))
+      : [];
+    return { documents, tombstones };
   } catch {
     return null;
   }
 }
 
+/**
+ * Tell the hub a document is gone (`DELETE`) or exists again (`POST`).
+ *
+ * BEST-EFFORT, LIKE EVERY OTHER HUB CALL HERE. A hub that is old, offline or
+ * refusing means the local delete still happened — the canvas is in `_trash/`
+ * and this peer has released it. What is lost is only the PROPAGATION, and the
+ * peer retries the statement on its next poll for anything it still sees on the
+ * hub but no longer has on disk. Returning false rather than throwing keeps a
+ * failed network call from turning a successful local delete into an error the
+ * user has to interpret.
+ */
+export async function stateDocumentGone(
+  hubUrl: string,
+  token: string,
+  docName: string,
+  opts: { revive?: boolean; fetchImpl?: typeof fetch } = {}
+): Promise<boolean> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  try {
+    const base = hubUrl.replace(/\/+$/, '');
+    const res = await fetchImpl(`${base}/api/documents/${encodeURIComponent(docName)}`, {
+      method: opts.revive ? 'POST' : 'DELETE',
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(LIST_TIMEOUT_MS),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Diff the hub's documents against the ones this peer syncs.
  *
@@ -146,6 +214,32 @@ export function slugFromDocName(docName: string): string | null {
   return ns ? ns[1].toLowerCase() : null;
 }
 
+/**
+ * The local slugs a tombstone set names — validated, deduplicated, safe.
+ *
+ * A tombstone is the one hub-supplied signal whose effect is to REMOVE work from
+ * a person's disk, so it runs through exactly the same name gate a pull does
+ * (`slugFromDocName`: whole-name match, no dots, no traversal, no extension
+ * smuggling) and anything that does not survive is dropped silently. A hub
+ * cannot name a file this way that it could not already have created.
+ *
+ * `known` is the set of slugs this peer actually holds; a tombstone for anything
+ * else is not an error, just nothing to do — that is the normal steady state
+ * once both sides have converged.
+ */
+export function tombstonedSlugs(
+  tombstones: readonly RemoteTombstone[],
+  known: Iterable<string>
+): string[] {
+  const have = new Set(known);
+  const out = new Set<string>();
+  for (const t of tombstones) {
+    const slug = slugFromDocName(t.name);
+    if (slug && have.has(slug)) out.add(slug);
+  }
+  return [...out].sort();
+}
+
 export interface PullTarget {
   slug: string;
   docName: string;

package/apps/studio/sync/status.ts

@@ -53,6 +53,22 @@ export interface SyncStatusPayload extends SyncStatusSnapshot {
    * payload as the doc counts so the Sync panel has one source, not two.
    */
   assets?: AssetPushProgress;
+  /**
+   * feature-sync-file-plane — Plane B's counts (additive; absent until the
+   * first flag-on file pull of a boot). `conflicts` names losers parked in
+   * `_trash/<rel>-conflict-<ts>` — the panel line points there, because a
+   * conflict a person cannot find is silent loss with extra steps.
+   */
+  files?: FilePlaneStatus;
+}
+
+export interface FilePlaneStatus {
+  /** Plane files present and equal after the last pass — the steady state. */
+  synced: number;
+  /** Cumulative files landed this boot. */
+  pulled: number;
+  /** Cumulative conflicts this boot (either winner); losers are in _trash/. */
+  conflicts: number;
 }
 
 export interface SyncStatusStoreOptions {
@@ -78,6 +94,9 @@ export interface SyncStatusStore {
    *  broadcast. Kept in the store (not the monitor): assets are a push lane,
    *  not a connection, and the monitor's state machine must not learn them. */
   updateAssets(progress: AssetPushProgress): void;
+  /** feature-sync-file-plane — merge Plane B counts + persist + broadcast.
+   *  Same reasoning as `updateAssets`: a lane, not a connection. */
+  updateFiles(files: FilePlaneStatus): void;
   /** Current payload (defensive copy). */
   get(): SyncStatusPayload;
 }
@@ -102,6 +121,7 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
   };
 
   let assets: AssetPushProgress | undefined;
+  let files: FilePlaneStatus | undefined;
 
   function payload(): SyncStatusPayload {
     return {
@@ -111,6 +131,7 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
       conflicts: conflicts.slice(),
       ...(opts.sharedDoc ? { sharedDoc: true } : {}),
       ...(assets ? { assets } : {}),
+      ...(files ? { files } : {}),
     };
   }
 
@@ -142,6 +163,10 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
       assets = progress;
       flush();
     },
+    updateFiles(next) {
+      files = next;
+      flush();
+    },
     get: payload,
   };
 }

package/apps/studio/sync/tombstone-apply.ts

@@ -0,0 +1,131 @@
+// Acting on a tombstone — the peer-side half of the delete lane.
+//
+// The hub states that a canvas is gone (`tombstones.mjs`); this is what a peer
+// does about it. One rule governs the whole file:
+//
+//   QUARANTINE, NEVER DELETE.
+//
+// This is the only code path where a HUB-SUPPLIED signal removes work from a
+// person's disk, and the hub is untrusted to peers (DDR-054). Moving the bundle
+// to `_trash/<slug>-deleted-<ts>/` is what makes that acceptable: a hub that is
+// hostile, buggy, or simply confused about which project it is costs the user a
+// trip to `_trash/`, never their work. The same posture, and the same directory,
+// `migrate-flat-fallback.ts` already established for a peer-driven move.
+//
+// WHY THE SIDECARS TRAVEL AND THE HISTORY DOES NOT. The lanes that ARE the
+// canvas — body, `.meta.json`, `.css`, `.annotations.svg` — move together, so
+// what lands in `_trash/` is a restorable canvas rather than a body stripped of
+// its annotations. `_history/<slug>/`, `_comments/`, `_canvas-state/` stay: they
+// are per-machine runtime state (DDR-115), regenerated or irrelevant, and
+// sweeping them would make a recoverable delete quietly lossy.
+
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Park ONE file in `_trash/<rel>-conflict-<ts>` — the file plane's LWW
+ * loser's parking spot (feature-sync-file-plane), generalized out of
+ * `quarantineCanvas` below: same posture (quarantine, never delete; never
+ * throw — a failed quarantine costs the overwrite, not the sync runtime),
+ * scoped to a single file rather than a canvas's lane bundle.
+ *
+ * Returns the design-root-relative destination, or null when nothing moved —
+ * and the CALLER must treat null as "do not overwrite": a conflict loser
+ * that could not be parked is a conflict loser that stays.
+ */
+export function quarantineFile(opts: {
+  designRoot: string;
+  /** Design-root-relative path of the file to park. */
+  rel: string;
+  now?: number;
+  log?: (line: string) => void;
+}): string | null {
+  const { designRoot, rel } = opts;
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const abs = path.join(designRoot, rel);
+  if (!existsSync(abs)) return null;
+  const trashedTo = `_trash/${rel}-conflict-${opts.now ?? Date.now()}`;
+  const trashAbs = path.join(designRoot, trashedTo);
+  try {
+    mkdirSync(path.dirname(trashAbs), { recursive: true });
+    renameSync(abs, trashAbs);
+  } catch (err) {
+    log(
+      `[sync/files] could not park ${rel} in _trash/: ${(err as Error).message} — keeping the local copy`
+    );
+    return null;
+  }
+  log(`[sync/files] conflict on ${rel} — the local copy moved to ${trashedTo}`);
+  return trashedTo;
+}
+
+export interface TombstoneMove {
+  slug: string;
+  /** Design-root-relative quarantine dir the canvas landed in. */
+  trashedTo: string;
+  /** Design-root-relative lanes that actually moved. */
+  moved: string[];
+}
+
+/** The absolute paths that make up one canvas on disk. */
+export interface CanvasLanes {
+  html: string;
+  meta?: string;
+  css?: string;
+  annotations?: string;
+}
+
+/**
+ * Move one canvas's lanes into `_trash/`, best-effort.
+ *
+ * Returns the move, or null when there was nothing on disk to move (already
+ * gone — the idempotent steady state once both peers have converged) or when the
+ * quarantine directory could not be made. NEVER THROWS: a failed quarantine must
+ * cost the deletion, not the sync runtime that called it.
+ *
+ * `now` is injectable so a test does not have to reason about wall-clock.
+ */
+export function quarantineCanvas(opts: {
+  designRoot: string;
+  slug: string;
+  lanes: CanvasLanes;
+  now?: number;
+  log?: (line: string) => void;
+}): TombstoneMove | null {
+  const { designRoot, slug, lanes } = opts;
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const present = [lanes.html, lanes.meta, lanes.css, lanes.annotations].filter(
+    (p): p is string => !!p && existsSync(p)
+  );
+  if (present.length === 0) return null;
+
+  const trashedTo = `_trash/${slug}-deleted-${opts.now ?? Date.now()}`;
+  const trashAbs = path.join(designRoot, trashedTo);
+  try {
+    mkdirSync(trashAbs, { recursive: true });
+  } catch (err) {
+    log(
+      `[sync/tombstone] could not quarantine ${slug}: ${(err as Error).message} — leaving it in place`
+    );
+    return null;
+  }
+
+  const moved: string[] = [];
+  for (const abs of present) {
+    try {
+      renameSync(abs, path.join(trashAbs, path.basename(abs)));
+      moved.push(path.relative(designRoot, abs));
+    } catch (err) {
+      // One stuck lane (an open handle on Windows, a permission quirk) must not
+      // abandon the lanes that CAN move — a half-moved canvas is still gone from
+      // the tree, and the remainder is named here so it can be found by hand.
+      log(
+        `[sync/tombstone] could not move ${path.basename(abs)} for ${slug}: ${(err as Error).message}`
+      );
+    }
+  }
+  if (moved.length === 0) return null;
+
+  log(`[sync/tombstone] ${slug} was deleted in the project — moved to ${trashedTo}/`);
+  return { slug, trashedTo, moved };
+}

package/apps/studio/test/cloud-managed-save-surfaces.test.ts

@@ -0,0 +1,90 @@
+// DDR-218's withdrawal, applied to EVERY surface that reports a save state.
+//
+// The decision withdrew the working-tree half of the Changes surface whenever
+// somebody else commits this project — a cloud cell (`historyOnly`, `cfg.cloud`)
+// or the cell behind a linked+credentialed desktop repo (`cloudManaged`). It
+// landed in GitPanel only. `app.jsx` went on computing the dirty count a second
+// time, ungated, and handing it to the toolbar menu and the status-bar chip, so
+// both shells kept rendering "N unsaved" — the exact claim the withdrawal exists
+// to delete. Reported again 2026-08-14 ("89 unsaved changes on the cloud, 36 on
+// the desktop"), which is what these assertions are here to stop.
+//
+// Source-level (sync-panel-surface style): what they pin is what would regress —
+// someone re-deriving the posture at a call site, or adding a THIRD surface that
+// reads `gitStatus.files.length` directly.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STUDIO = join(import.meta.dir, '..');
+const APP = readFileSync(join(STUDIO, 'client', 'app.jsx'), 'utf8');
+const PANEL = readFileSync(join(STUDIO, 'client', 'panels', 'GitPanel.jsx'), 'utf8');
+
+describe('one expression owns "who is saving this project"', () => {
+  test('both postures are named once, at the top level', () => {
+    expect(APP).toContain('const cellManaged = !!cfg.cloud;');
+    expect(APP).toContain('const cloudManaged = !cfg.cloud && !!cloudLinkedHub?.credentialed;');
+    expect(APP).toContain('const savingIsManaged = cellManaged || cloudManaged;');
+  });
+
+  test('the GitPanel call site consumes those names rather than re-deriving them', () => {
+    // Re-deriving is how the two halves drift apart in the first place.
+    expect(APP).toContain('historyOnly={cellManaged}');
+    expect(APP).toContain('cloudManaged={cloudManaged}');
+  });
+});
+
+describe('the dirty COUNT is withheld wherever saving is managed', () => {
+  test('unsavedCount is gated, not raw', () => {
+    expect(APP).toContain(
+      'const unsavedCount = savingIsManaged ? 0 : gitStatus?.files?.length || 0;'
+    );
+  });
+
+  test('no surface reads the raw file count for display', () => {
+    // Exactly one `gitStatus?.files?.length` may exist, and it is the gated one
+    // above. A second occurrence is a new leak by construction.
+    const raw = APP.match(/gitStatus\?\.files\?\.length/g) ?? [];
+    expect(raw.length).toBe(1);
+  });
+
+  test('every changesCount consumer is fed the gated value', () => {
+    const feeds = APP.match(/changesCount=\{[^}]+\}/g) ?? [];
+    expect(feeds.length).toBeGreaterThan(0);
+    for (const feed of feeds) expect(feed).toBe('changesCount={unsavedCount}');
+  });
+});
+
+describe('the status-bar chip names the mechanism instead of a count', () => {
+  test('it receives the posture', () => {
+    expect(APP).toContain('savingIsManaged={savingIsManaged}');
+    expect(APP).toMatch(/savingIsManaged = false,/);
+  });
+
+  test('managed saving short-circuits the whole unsaved / to-publish ladder', () => {
+    expect(APP).toMatch(/\{savingIsManaged\s*\?/);
+    expect(APP).toContain("'cloud saving'");
+  });
+
+  test('"N to publish" is withheld too — Publish is withdrawn in that posture', () => {
+    // A gated count alone would fall through to the unpushed branch, which is
+    // the same local-git offer wearing a different label.
+    expect(APP).toContain('unpushed={savingIsManaged ? 0 : gitStatus?.unpushed || 0}');
+  });
+});
+
+describe('the panel half of DDR-218 is still intact', () => {
+  test('withdrawal covers both postures', () => {
+    expect(PANEL).toContain('const withdrawn = historyOnly || cloudManaged;');
+  });
+
+  test('the panel badge stays gated on it', () => {
+    expect(PANEL).toMatch(/!withdrawn && count > 0/);
+  });
+
+  test('the cloud-managed note keeps its testid and names the live mechanism', () => {
+    expect(PANEL).toContain('data-testid="git-cloud-managed"');
+    expect(PANEL).toMatch(/Cloud is saving/);
+  });
+});

package/apps/studio/test/exporters/jobs.test.ts

@@ -53,7 +53,11 @@ describe('exporters/jobs — concurrency gate', () => {
       let sawThirdQueued = false;
       let maxRunningObserved = 0;
       let allDone = false;
-      const deadline = Date.now() + 4000;
+      // Generous: the assertion below is "the queue drains at all", not "it
+      // drains fast". The budget only has to outlast DEFLATE over the seeded
+      // sandbox on the slowest machine we run on — a budget tuned to one
+      // machine's disk speed fails there while the queue is working fine.
+      const deadline = Date.now() + 20_000;
       while (Date.now() < deadline && !allDone) {
         const jobs = await listJobs(port);
         const byId = new Map(jobs.map((j) => [j.id, j]));
@@ -74,7 +78,7 @@ describe('exporters/jobs — concurrency gate', () => {
     } finally {
       await killProc(proc);
     }
-  });
+  }, 30_000);
 });
 
 describe('exporters/jobs — pending-queue cap (security fan-out, /flow:done)', () => {
@@ -109,7 +113,9 @@ describe('exporters/jobs — pending-queue cap (security fan-out, /flow:done)',
       // Once jobs drain below the cap, enqueue works again — this is a
       // capacity limit, not a permanent lockout.
       let drained = false;
-      const deadline = Date.now() + 5000;
+      // Same reasoning as the concurrency gate above — budget for the slowest
+      // machine, since what's under test is that the cap lifts, not latency.
+      const deadline = Date.now() + 20_000;
       while (Date.now() < deadline && !drained) {
         const jobs = await listJobs(port);
         drained = jobs.every((j) => j.status === 'done' || j.status === 'failed');
@@ -121,7 +127,7 @@ describe('exporters/jobs — pending-queue cap (security fan-out, /flow:done)',
     } finally {
       await killProc(proc);
     }
-  });
+  }, 30_000);
 });
 
 describe('exporters/jobs — list() + history under concurrency', () => {

package/apps/studio/test/git-cloud-posture.test.ts

@@ -37,8 +37,17 @@ describe('a cloud-linked repo shows ONE save mechanism (DDR-218)', () => {
   });
 
   test('the app gate is the CORROBORATED link, and the cell posture is untouched', () => {
-    expect(APP).toContain('cloudManaged={!cfg.cloud && !!cloudLinkedHub?.credentialed}');
-    expect(APP).toContain('historyOnly={!!cfg.cloud}');
+    // Hoisted to a single top-level definition (2026-08-14) so the toolbar and
+    // status bar read the SAME posture the panel does — see
+    // cloud-managed-save-surfaces.test.ts. The gate itself is unchanged, and
+    // `credentialed` is the load-bearing half: config.json alone is
+    // attacker-authorable (B2), so a link claim without corroboration must
+    // never reach this posture.
+    expect(APP).toContain('const cloudManaged = !cfg.cloud && !!cloudLinkedHub?.credentialed;');
+    expect(APP).toContain('const cellManaged = !!cfg.cloud;');
+    // …and the panel is fed from those names, not a re-derivation.
+    expect(APP).toContain('cloudManaged={cloudManaged}');
+    expect(APP).toContain('historyOnly={cellManaged}');
   });
 
   test('CloudBar lifts every link change the posture depends on', () => {

package/apps/studio/test/sync-asset-pull.test.ts

@@ -0,0 +1,161 @@
+// The downward asset lane — see sync/asset-pull.ts.
+//
+// Regression cover for the reported "obrázky v annotations se nevykreslí":
+// `<slug>.annotations.svg` synced, its `assets/<sha8>.png` did not, and the
+// canvas rendered a broken-image glyph on every peer but the one that made it.
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { pullAssets, referencedAssets } from '../sync/asset-pull.ts';
+
+function project(files: Record<string, string>): string {
+  const root = mkdtempSync(path.join(tmpdir(), 'maude-asset-pull-'));
+  for (const [rel, body] of Object.entries(files)) {
+    const abs = path.join(root, rel);
+    mkdirSync(path.dirname(abs), { recursive: true });
+    writeFileSync(abs, body);
+  }
+  return root;
+}
+
+const annotation = (name: string) =>
+  `<svg xmlns="http://www.w3.org/2000/svg"><image data-tool="image" href="assets/${name}"/></svg>`;
+
+/** A hub that serves every asset as three bytes. */
+const servingFetch = (seen: string[] = []) =>
+  (async (url: string) => {
+    seen.push(String(url));
+    return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+  }) as unknown as typeof fetch;
+
+describe('referencedAssets', () => {
+  test('finds the image an annotation references', () => {
+    const root = project({ 'ui-board.annotations.svg': annotation('c0fa9c7f.png') });
+    expect(referencedAssets(root)).toEqual(['c0fa9c7f.png']);
+  });
+
+  test('reads canvas bodies and sidecars too, deduplicating', () => {
+    const root = project({
+      'ui-board.annotations.svg': annotation('a.png'),
+      'ui/card.tsx': `<img src="assets/b.jpg" /><img src="assets/a.png" />`,
+      'ui/card.css': `.x { background: url(assets/c.webp) }`,
+    });
+    expect(referencedAssets(root)).toEqual(['a.png', 'b.jpg', 'c.webp']);
+  });
+
+  test('refuses a reference that could place a file outside assets/', () => {
+    // An annotation can itself have arrived from the hub, so a name found in
+    // one is untrusted input.
+    const root = project({
+      'ui-board.annotations.svg': [
+        '<svg>',
+        '<image href="assets/../../etc/passwd"/>',
+        '<image href="assets/ok.png"/>',
+        '</svg>',
+      ].join(''),
+    });
+    expect(referencedAssets(root)).toEqual(['ok.png']);
+  });
+
+  test('refuses an extension outside the asset allowlist', () => {
+    const root = project({
+      'ui/card.tsx': `"assets/payload.sh" "assets/x.tsx" "assets/real.png"`,
+    });
+    expect(referencedAssets(root)).toEqual(['real.png']);
+  });
+
+  test('ignores runtime directories — a trashed canvas wants nothing', () => {
+    const root = project({
+      '_trash/old-deleted-1/old.annotations.svg': annotation('ghost.png'),
+      '_history/ui-board/1.tsx': `"assets/older.png"`,
+      'ui-board.annotations.svg': annotation('live.png'),
+    });
+    expect(referencedAssets(root)).toEqual(['live.png']);
+  });
+});
+
+describe('pullAssets', () => {
+  const opts = (root: string, fetchImpl: typeof fetch) => ({
+    designRoot: root,
+    hubUrl: 'https://hub.example/',
+    token: () => 'tok',
+    fetchImpl,
+    log: { log: () => {}, warn: () => {} },
+  });
+
+  test('fetches a referenced asset this machine does not have', async () => {
+    const root = project({ 'ui-board.annotations.svg': annotation('c0fa9c7f.png') });
+    const seen: string[] = [];
+    const res = await pullAssets(opts(root, servingFetch(seen)));
+
+    expect(res.pulled).toEqual(['c0fa9c7f.png']);
+    expect(seen).toEqual(['https://hub.example/assets/c0fa9c7f.png']);
+    expect(readFileSync(path.join(root, 'assets/c0fa9c7f.png'))).toEqual(Buffer.from([1, 2, 3]));
+  });
+
+  test('asks for nothing when every reference is already on disk', async () => {
+    const root = project({
+      'ui-board.annotations.svg': annotation('have.png'),
+      'assets/have.png': 'bytes',
+    });
+    let called = 0;
+    const counting = (async () => {
+      called += 1;
+      return new Response('x', { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const res = await pullAssets(opts(root, counting));
+    expect(called).toBe(0);
+    expect(res.present).toBe(1);
+    expect(res.pulled).toEqual([]);
+  });
+
+  test('is idempotent — a second pass costs no requests', async () => {
+    const root = project({ 'ui-board.annotations.svg': annotation('x.png') });
+    await pullAssets(opts(root, servingFetch()));
+    const seen: string[] = [];
+    const second = await pullAssets(opts(root, servingFetch(seen)));
+    expect(seen).toEqual([]);
+    expect(second.pulled).toEqual([]);
+  });
+
+  test('a 404 is recorded and retried, never fatal', async () => {
+    // Ordinary: the peer that owns the bytes has not pushed them yet.
+    const root = project({ 'ui-board.annotations.svg': annotation('later.png') });
+    const missing = (async () => new Response('nope', { status: 404 })) as unknown as typeof fetch;
+    const res = await pullAssets(opts(root, missing));
+    expect(res.pulled).toEqual([]);
+    expect(res.failed).toEqual([{ name: 'later.png', reason: 'HTTP 404' }]);
+    expect(existsSync(path.join(root, 'assets/later.png'))).toBe(false);
+  });
+
+  test('a throwing hub is not fatal either', async () => {
+    const root = project({ 'ui-board.annotations.svg': annotation('x.png') });
+    const boom = (async () => {
+      throw new Error('offline');
+    }) as unknown as typeof fetch;
+    const res = await pullAssets(opts(root, boom));
+    expect(res.pulled).toEqual([]);
+    expect(res.failed[0]?.reason).toBe('offline');
+  });
+
+  test('refuses an empty body rather than writing a zero-byte image', async () => {
+    const root = project({ 'ui-board.annotations.svg': annotation('x.png') });
+    const empty = (async () =>
+      new Response(new Uint8Array([]), { status: 200 })) as unknown as typeof fetch;
+    const res = await pullAssets(opts(root, empty));
+    expect(res.pulled).toEqual([]);
+    expect(existsSync(path.join(root, 'assets/x.png'))).toBe(false);
+  });
+
+  test('leaves no .part file behind on success', async () => {
+    // The write is temp-then-rename so the dev server serving this very path
+    // never reads a half-written image.
+    const root = project({ 'ui-board.annotations.svg': annotation('x.png') });
+    await pullAssets(opts(root, servingFetch()));
+    expect(existsSync(path.join(root, 'assets/x.png.part'))).toBe(false);
+  });
+});