@1agh/maude 0.60.6 → 0.60.7

package/apps/studio/sync/asset-push.ts

@@ -567,3 +567,68 @@ export async function pushAssets(opts: {
   }
   return out;
 }
+
+/**
+ * The FAST LANE — push exactly ONE just-written asset, now (2026-08-16
+ * latency fix).
+ *
+ * The sweep is the reconciler, and a good one — but it is also a spawn, a
+ * debounce, and a walk-and-probe of the whole project, so a sticker dropped
+ * on a canvas reached the hub MINUTES after its annotation stroke got there
+ * over the doc lane. The other side rendered the placeholder frame the whole
+ * time. This pushes the single file the moment the local write lands: one
+ * probe (the batch route, which survives the cloud's HEAD→GET conversion),
+ * one PUT. In-process on purpose — the out-of-process boundary exists because
+ * the FULL sweep destabilizes Bun next to the dev server; a single fetch is
+ * the same class of work `pullAssets` already does in-process on every poll.
+ *
+ * Failures are the sweep's problem: this never throws, and a miss here is
+ * retried by the very next sweep pass for free.
+ */
+export async function pushOneAsset(opts: {
+  designRoot: string;
+  /** designRoot-relative path, slash-normalised. */
+  rel: string;
+  hubUrl: string;
+  token: () => string;
+  canvasGroups?: readonly CanvasGroupLike[];
+  fetchImpl?: typeof fetch;
+  timeoutFor?: (bytes: number) => number;
+}): Promise<{ ok: boolean; skipped?: boolean; reason?: string }> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const rel = opts.rel.split('\\').join('/');
+  if (!isPushableAssetRel(rel, opts.canvasGroups)) {
+    return { ok: false, reason: 'not a pushable asset' };
+  }
+  const abs = path.join(opts.designRoot, rel);
+  try {
+    if (statSync(abs).size > MAX_PUSH_BYTES) return { ok: false, reason: 'over the size cap' };
+  } catch {
+    return { ok: false, reason: 'unreadable' };
+  }
+  const base = opts.hubUrl.replace(/\/+$/, '');
+  const headers = { authorization: `Bearer ${opts.token()}` };
+  try {
+    // One probe — mainly to skip the echo of a file we just PULLED from this
+    // very hub (the pull writes it, the watcher fires, and without this the
+    // fast lane would upload the hub's own bytes straight back at it).
+    const known = await probePresent({ fetchImpl, base, headers, paths: [rel] });
+    if (known?.has(rel)) return { ok: true, skipped: true };
+    const put = await putWithRetry({
+      fetchImpl,
+      url: `${base}${routeFor(rel).url}`,
+      headers,
+      file: abs,
+      sleep: (ms) =>
+        new Promise<void>((res) => {
+          setTimeout(res, ms);
+        }),
+      backoff: { remainingMs: 60_000 },
+      timeoutFor: opts.timeoutFor ?? putTimeoutMs,
+    });
+    if (put.ok) return { ok: true };
+    return { ok: false, reason: `HTTP ${put.status}` };
+  } catch (err) {
+    return { ok: false, reason: (err as Error).message };
+  }
+}

package/apps/studio/sync/index.ts

@@ -30,7 +30,7 @@ import { createHistory } from '../history.ts';
 import { SYNTHETIC_FS_DELAY_MS } from '../hmr-broadcast.ts';
 import { type CanvasSyncAgent, createCanvasSyncAgent } from './agent.ts';
 import { pullAssets } from './asset-pull.ts';
-import { isPushableAssetRel } from './asset-push.ts';
+import { isPushableAssetRel, pushOneAsset } from './asset-push.ts';
 import { type AssetSweepHandle, runAssetSweep } from './asset-sweep.ts';
 import { atomicWrite } from './atomic-write.ts';
 import { createAutoCommit } from './autocommit.ts';
@@ -645,6 +645,57 @@ export function createSyncRuntime(
     assetSweepTimer.unref?.();
   }
 
+  // ---- FAST LANES (2026-08-16 latency fix) --------------------------------
+  // The sweep reconciles; these make the COMMON case instant. A sticker
+  // dropped on a canvas syncs its stroke over the doc lane in milliseconds,
+  // while its bytes waited for a debounced, spawned, walk-everything sweep
+  // (minutes) — and the other direction waited for the next 20 s poll. The
+  // fast push sends the ONE just-written file now; the fast pull runs the
+  // (missing-only, idempotent) asset pull the moment a reference-bearing
+  // file lands, instead of at the next tick.
+  const fastPushTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  /** Serialize fast pushes — assets run to videos; two at once starve sync. */
+  let fastPushChain: Promise<void> = Promise.resolve();
+  /** Let the write settle (atomic tmp+rename bursts) before reading it. */
+  const FAST_PUSH_DEBOUNCE_MS = 400;
+  /** Debounced trigger for an off-schedule pullAssetsOnce — set in start(). */
+  let requestFastPull: (() => void) | null = null;
+  /** Files whose annotations/tsx/css/meta content can reference assets —
+   *  mirrors asset-pull's SCANNED_EXT. */
+  const REFERENCE_FILE_RE = /\.(?:annotations\.svg|tsx|jsx|css|meta\.json)$/i;
+
+  function queueFastPush(rel: string, hubUrl: string): void {
+    if (stopped || cellPairing) return; // the cell never pushes (same as the sweep)
+    const prev = fastPushTimers.get(rel);
+    if (prev) clearTimeout(prev);
+    const timer = setTimeout(() => {
+      fastPushTimers.delete(rel);
+      if (stopped) return;
+      fastPushChain = fastPushChain.then(async () => {
+        if (stopped) return;
+        try {
+          const r = await pushOneAsset({
+            designRoot: ctx.paths.designRoot,
+            rel,
+            hubUrl,
+            token: () => token,
+            canvasGroups: ctx.cfg.canvasGroups,
+          });
+          if (r.ok && !r.skipped) {
+            console.log(`[sync/assets] fast-pushed ${rel}`);
+          } else if (!r.ok) {
+            // Not an error surface — the sweep is the reconciler and retries.
+            console.warn(`[sync/assets] fast push ${rel}: ${r.reason} — the sweep will retry.`);
+          }
+        } catch {
+          /* the sweep reconciles */
+        }
+      });
+    }, FAST_PUSH_DEBOUNCE_MS);
+    timer.unref?.();
+    fastPushTimers.set(rel, timer);
+  }
+
   // Task 8 — offline-mode status surface, initialized in start() once the
   // canvas count is known. The store writes `_sync.json` + broadcasts
   // 'sync:status' on the bus; the monitor aggregates provider WS status into
@@ -1222,7 +1273,17 @@ export function createSyncRuntime(
       // nobody had sent: a permanent empty frame that looked like a broken path.
       // Reported three times in one day on alligators, each time with a
       // different asset, which is what finally named it.
-      if (isPushableAssetRel(rel, ctx.cfg.canvasGroups)) scheduleAssetSweep(linkedHub.url);
+      if (isPushableAssetRel(rel, ctx.cfg.canvasGroups)) {
+        // Fast lane first (this ONE file, now — seconds, not minutes), sweep
+        // second (the reconciler that catches anything the fast lane missed).
+        queueFastPush(rel.split('\\').join('/'), linkedHub.url);
+        scheduleAssetSweep(linkedHub.url);
+      }
+      // The DOWNWARD fast lane: a reference-bearing file just landed (a peer's
+      // annotation/body materialized through the doc lane, or a local edit).
+      // Run the missing-only asset pull now instead of at the next 20 s tick,
+      // so the other side's freshly dropped image renders in seconds.
+      if (REFERENCE_FILE_RE.test(rel)) requestFastPull?.();
     });
 
     /**
@@ -2316,6 +2377,39 @@ export function createSyncRuntime(
         token: () => token,
       });
     };
+    // The downward fast lane's trigger (2026-08-16 latency fix): debounced,
+    // single-flight, and a no-op in the steady state (the pull is missing-only
+    // — every referenced asset present costs one directory scan and zero
+    // requests). Fired from the fs:any listener when a reference-bearing file
+    // lands; the 20 s poll stays as the schedule-driven reconciler.
+    {
+      let fastPullTimer: ReturnType<typeof setTimeout> | null = null;
+      let fastPullRunning = false;
+      let fastPullAgain = false;
+      const runFastPull = (): void => {
+        if (stopped) return;
+        if (fastPullRunning) {
+          fastPullAgain = true;
+          return;
+        }
+        fastPullRunning = true;
+        void pullAssetsOnce().finally(() => {
+          fastPullRunning = false;
+          if (fastPullAgain && !stopped) {
+            fastPullAgain = false;
+            runFastPull();
+          }
+        });
+      };
+      requestFastPull = () => {
+        if (stopped || fastPullTimer !== null) return;
+        fastPullTimer = setTimeout(() => {
+          fastPullTimer = null;
+          runFastPull();
+        }, 750);
+        fastPullTimer.unref?.();
+      };
+    }
     // Cumulative per boot — the Sync panel's one line. `synced` is the last
     // pass's converged count; `pulled`/`conflicts` accumulate.
     const fileTotals = { synced: 0, pulled: 0, conflicts: 0 };
@@ -2372,6 +2466,10 @@ export function createSyncRuntime(
   async function stop(): Promise<void> {
     if (stopped) return;
     stopped = true;
+    // Fast lanes down first — no push/pull may fire into a dying runtime.
+    for (const t of fastPushTimers.values()) clearTimeout(t);
+    fastPushTimers.clear();
+    requestFastPull = null;
     // Nothing may be adopted into a runtime that is going away.
     attachOne = null;
     discoveryUnsub?.();

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

@@ -14,6 +14,7 @@ import {
   isPushableAssetRel,
   listPushableAssets,
   pushAssets,
+  pushOneAsset,
   putTimeoutMs,
 } from '../sync/asset-push.ts';
 
@@ -837,10 +838,11 @@ describe('the runtime sweeps on change, not only at boot', () => {
   test('the fs watcher decides with isPushableAssetRel and schedules a sweep', () => {
     // The predicate gets the project's OWN canvas groups — with the default
     // set a custom-group project's shared module would answer canvas-owned
-    // and silently never schedule the sweep that uploads it.
-    expect(SYNC).toContain(
-      'if (isPushableAssetRel(rel, ctx.cfg.canvasGroups)) scheduleAssetSweep('
-    );
+    // and silently never schedule the sweep that uploads it. (Since the
+    // 2026-08-16 latency fix the same gate also feeds the fast lane; the
+    // sweep stays the reconciler.)
+    expect(SYNC).toContain('if (isPushableAssetRel(rel, ctx.cfg.canvasGroups)) {');
+    expect(SYNC).toContain('scheduleAssetSweep(linkedHub.url);');
   });
 
   test('bursts coalesce, and a change DURING a sweep is not lost', () => {
@@ -855,3 +857,112 @@ describe('the runtime sweeps on change, not only at boot', () => {
     expect(SYNC).toContain('if (assetSweepTimer !== null) clearTimeout(assetSweepTimer);');
   });
 });
+
+describe('pushOneAsset — the fast lane (2026-08-16 latency fix)', () => {
+  test('probes once via /_asset-probe, then PUTs the single file', async () => {
+    const designRoot = scratchDesignRoot();
+    mkdirSync(join(designRoot, 'assets'), { recursive: true });
+    writeFileSync(join(designRoot, 'assets/aaaaaaaa.png'), 'fresh sticker');
+
+    const calls: Array<{ method: string; url: string }> = [];
+    const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      const method = init?.method ?? 'GET';
+      calls.push({ method, url });
+      if (url.endsWith('/_asset-probe')) return Response.json({ present: [] });
+      return new Response('{"ok":true}', { status: 200 });
+    }) as typeof fetch;
+
+    const r = await pushOneAsset({
+      designRoot,
+      rel: 'assets/aaaaaaaa.png',
+      hubUrl: 'https://alligators.cloud.maude.sh/',
+      token: () => 'mau_tok',
+      fetchImpl,
+    });
+    expect(r).toEqual({ ok: true });
+    expect(calls.map((c) => `${c.method} ${c.url}`)).toEqual([
+      'POST https://alligators.cloud.maude.sh/_asset-probe',
+      'PUT https://alligators.cloud.maude.sh/assets/aaaaaaaa.png',
+    ]);
+  });
+
+  test('a file the hub already holds is skipped — the pull-echo guard', async () => {
+    // The fast lane fires off fs:any, and the asset PULL writes into assets/
+    // too — without this skip the lane would upload the hub's own bytes back.
+    const designRoot = scratchDesignRoot();
+    mkdirSync(join(designRoot, 'assets'), { recursive: true });
+    writeFileSync(join(designRoot, 'assets/aaaaaaaa.png'), 'pulled bytes');
+
+    let puts = 0;
+    const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (url.endsWith('/_asset-probe')) return Response.json({ present: ['assets/aaaaaaaa.png'] });
+      if (init?.method === 'PUT') puts += 1;
+      return new Response('{"ok":true}', { status: 200 });
+    }) as typeof fetch;
+
+    const r = await pushOneAsset({
+      designRoot,
+      rel: 'assets/aaaaaaaa.png',
+      hubUrl: 'https://alligators.cloud.maude.sh',
+      token: () => 'mau_tok',
+      fetchImpl,
+    });
+    expect(r).toEqual({ ok: true, skipped: true });
+    expect(puts).toBe(0);
+  });
+
+  test('DS-tree asset routes to /_asset-file/; non-pushable rels refuse; failures report', async () => {
+    const designRoot = scratchDesignRoot();
+    mkdirSync(join(designRoot, 'system/ds/assets'), { recursive: true });
+    writeFileSync(join(designRoot, 'system/ds/assets/mark.svg'), 'brand');
+
+    const urls: string[] = [];
+    const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      if (url.endsWith('/_asset-probe')) return Response.json({ present: [] });
+      if (init?.method === 'PUT') {
+        urls.push(url);
+        return new Response('refused', { status: 403 });
+      }
+      return new Response(null, { status: 404 });
+    }) as typeof fetch;
+
+    const r = await pushOneAsset({
+      designRoot,
+      rel: 'system/ds/assets/mark.svg',
+      hubUrl: 'https://hub.example.com',
+      token: () => 't',
+      fetchImpl,
+    });
+    expect(urls).toEqual(['https://hub.example.com/_asset-file/system/ds/assets/mark.svg']);
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain('403');
+
+    // Runtime state / config never enter the fast lane.
+    const refused = await pushOneAsset({
+      designRoot,
+      rel: '_history/x/old.png',
+      hubUrl: 'https://hub.example.com',
+      token: () => 't',
+      fetchImpl,
+    });
+    expect(refused.ok).toBe(false);
+    expect(refused.reason).toBe('not a pushable asset');
+  });
+
+  test('the runtime wires the fast lanes: push off fs:any, pull off reference files', () => {
+    // Same source-pin style as the sweep-trigger suite above.
+    expect(SYNC2).toContain('queueFastPush(rel');
+    expect(SYNC2).toMatch(/REFERENCE_FILE_RE\.test\(rel\)/);
+    expect(SYNC2).toContain('requestFastPull');
+    // stop() tears the lanes down.
+    expect(SYNC2).toContain('for (const t of fastPushTimers.values()) clearTimeout(t);');
+    expect(SYNC2).toContain('requestFastPull = null;');
+    // The cell never pushes — same guard as the sweep.
+    expect(SYNC2).toMatch(/if \(stopped \|\| cellPairing\) return; \/\/ the cell never pushes/);
+  });
+});
+
+const SYNC2 = readFileSync(join(import.meta.dir, '..', 'sync', 'index.ts'), 'utf8');

package/apps/studio/whats-new.json

@@ -1,6 +1,15 @@
 {
   "$schema": "./whats-new.schema.json",
   "entries": [
+    {
+      "id": "instant-asset-sync",
+      "version": "0.60.7",
+      "date": "2026-08-16",
+      "kind": "improvement",
+      "title": "Pictures sync in seconds",
+      "summary": "A picture you drop on a canvas is pushed by itself the moment it lands, and the other side fetches it the moment the reference arrives — seconds end to end, instead of waiting for the next full sweep or polling tick.",
+      "surface": "design-ui"
+    },
     {
       "id": "assets-arrive-and-heal",
       "version": "0.60.6",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.60.6",
+  "version": "0.60.7",
   "description": "Marketplace of Claude Code plugins by Michal Dovrtěl: `design` (canvas-first design iteration) + `flow` (generic agentic workflow loop with .ai second brain). Ships the `maude` CLI (with `mdcc` legacy alias) to scaffold workspace, run the design dev server, and manage configs.",
   "type": "module",
   "engines": {
@@ -54,13 +54,13 @@
     "test:e2e:desktop:parity:cloud": "pnpm --filter @maude/desktop-e2e e2e:parity:cloud"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.60.6",
-    "@1agh/maude-darwin-x64": "0.60.6",
-    "@1agh/maude-linux-arm64": "0.60.6",
-    "@1agh/maude-linux-arm64-musl": "0.60.6",
-    "@1agh/maude-linux-x64": "0.60.6",
-    "@1agh/maude-linux-x64-musl": "0.60.6",
-    "@1agh/maude-win32-x64": "0.60.6"
+    "@1agh/maude-darwin-arm64": "0.60.7",
+    "@1agh/maude-darwin-x64": "0.60.7",
+    "@1agh/maude-linux-arm64": "0.60.7",
+    "@1agh/maude-linux-arm64-musl": "0.60.7",
+    "@1agh/maude-linux-x64": "0.60.7",
+    "@1agh/maude-linux-x64-musl": "0.60.7",
+    "@1agh/maude-win32-x64": "0.60.7"
   },
   "files": [
     "cli",