@1agh/maude 0.41.0 → 0.42.0

package/apps/studio/exporters/pdf.ts

@@ -13,10 +13,11 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import { PDFDocument } from 'pdf-lib';
-import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
+import { exportShimPath, runShim } from './_runtime.ts';
 import {
   canvasShellUrl,
   type ExportContext,
+  type ExportHooks,
   type ExportOptions,
   type ExportResult,
 } from './index.ts';
@@ -29,7 +30,8 @@ async function capturePdf(
   target: Extract<Target, { kind: 'element' }>,
   ctx: ExportContext,
   outDir: string,
-  timeoutSec: number
+  timeoutSec: number,
+  hooks?: ExportHooks
 ): Promise<string[]> {
   const args = [
     PDF_PLAYWRIGHT,
@@ -49,29 +51,18 @@ async function capturePdf(
     args.push('--out', path.join(outDir, `${target.canvasSlug}.pdf`));
   }
 
-  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
+  return runShim(args, {
     cwd: path.dirname(PDF_PLAYWRIGHT),
-    stdout: 'pipe',
-    stderr: 'pipe',
+    signal: hooks?.signal,
+    onProgress: hooks?.onProgress,
   });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-  const code = await proc.exited;
-  if (code !== 0) {
-    throw new Error(`_pdf-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
-  }
-  return stdout
-    .split('\n')
-    .map((s) => s.trim())
-    .filter(Boolean);
 }
 
 export async function run(
   targets: Target[],
   options: ExportOptions,
-  ctx: ExportContext
+  ctx: ExportContext,
+  hooks?: ExportHooks
 ): Promise<ExportResult> {
   if (!targets.length) {
     return { filename: 'export.pdf', contentType: 'application/pdf', body: new Uint8Array(0) };
@@ -86,9 +77,14 @@ export async function run(
   const tmp = mkdtempSync(path.join(tmpdir(), 'maude-pdf-'));
   try {
     const written: string[] = [];
-    for (const t of elementTargets) {
-      const paths = await capturePdf(t, ctx, tmp, timeoutSec);
+    for (let i = 0; i < elementTargets.length; i += 1) {
+      const paths = await capturePdf(elementTargets[i], ctx, tmp, timeoutSec, hooks);
       written.push(...paths);
+      // Outer-loop tick (N separate top-level Targets — rare). The granular
+      // "K of M artboards" signal for canvas-as-separate comes from the
+      // shim's own MAUDE_PROGRESS lines via spawnShim's onProgress inside
+      // capturePdf, above — both funnel into the same hooks.onProgress.
+      hooks?.onProgress?.({ current: i + 1, total: elementTargets.length });
     }
     if (!written.length) {
       return { filename: 'export.pdf', contentType: 'application/pdf', body: new Uint8Array(0) };

package/apps/studio/exporters/png.ts

@@ -12,10 +12,11 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import JSZip from 'jszip';
-import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
+import { exportShimPath, runShim } from './_runtime.ts';
 import {
   canvasShellUrl,
   type ExportContext,
+  type ExportHooks,
   type ExportOptions,
   type ExportResult,
 } from './index.ts';
@@ -45,7 +46,8 @@ async function captureElement(
   target: Extract<Target, { kind: 'element' }>,
   ctx: ExportContext,
   outDir: string,
-  options: CaptureOptions
+  options: CaptureOptions,
+  hooks?: ExportHooks
 ): Promise<string[]> {
   const args = [
     PNG_PLAYWRIGHT,
@@ -68,23 +70,11 @@ async function captureElement(
     if (target.widen) args.push('--widen-to-artboard', '1');
     args.push('--out', path.join(outDir, `${target.canvasSlug}.png`));
   }
-  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
+  return runShim(args, {
     cwd: path.dirname(PNG_PLAYWRIGHT),
-    stdout: 'pipe',
-    stderr: 'pipe',
+    signal: hooks?.signal,
+    onProgress: hooks?.onProgress,
   });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-  const code = await proc.exited;
-  if (code !== 0) {
-    throw new Error(`_png-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
-  }
-  return stdout
-    .split('\n')
-    .map((s) => s.trim())
-    .filter(Boolean);
 }
 
 function readBytes(paths: string[]): Array<{ name: string; bytes: Uint8Array }> {
@@ -105,7 +95,8 @@ async function bundleZip(entries: Array<{ name: string; bytes: Uint8Array }>): P
 export async function run(
   targets: Target[],
   options: ExportOptions,
-  ctx: ExportContext
+  ctx: ExportContext,
+  hooks?: ExportHooks
 ): Promise<ExportResult> {
   if (!targets.length) {
     return { filename: 'export.png', contentType: 'image/png', body: new Uint8Array(0) };
@@ -128,9 +119,10 @@ export async function run(
 
   try {
     const written: string[] = [];
-    for (const t of elementTargets) {
-      const paths = await captureElement(t, ctx, tmp, captureOpts);
+    for (let i = 0; i < elementTargets.length; i += 1) {
+      const paths = await captureElement(elementTargets[i], ctx, tmp, captureOpts, hooks);
       written.push(...paths);
+      hooks?.onProgress?.({ current: i + 1, total: elementTargets.length });
     }
     const entries = readBytes(written);
 

package/apps/studio/exporters/pptx.ts

@@ -27,10 +27,11 @@ import path from 'node:path';
 import PptxGenJS from 'pptxgenjs';
 
 import { getBrowserBundle } from './_browser-bundles.ts';
-import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
+import { exportShimPath, runShim } from './_runtime.ts';
 import {
   canvasShellUrl,
   type ExportContext,
+  type ExportHooks,
   type ExportOptions,
   type ExportResult,
 } from './index.ts';
@@ -51,25 +52,13 @@ function isElementTarget(t: Target): t is ElementTarget {
   return t.kind === 'element';
 }
 
-/** Spawn a playwright shim via a resolved runtime, returning the written file paths (stdout). */
-async function spawnShim(args: string[]): Promise<string[]> {
-  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
+/** Spawn a playwright shim via the shared runtime, returning the written file paths (stdout). */
+function spawnPlaywrightShim(args: string[], hooks?: ExportHooks): Promise<string[]> {
+  return runShim(args, {
     cwd: path.dirname(args[0]),
-    stdout: 'pipe',
-    stderr: 'pipe',
+    signal: hooks?.signal,
+    onProgress: hooks?.onProgress,
   });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-  const code = await proc.exited;
-  if (code !== 0) {
-    throw new Error(`${path.basename(args[0])} exited ${code}: ${stderr.trim() || stdout.trim()}`);
-  }
-  return stdout
-    .split('\n')
-    .map((s) => s.trim())
-    .filter(Boolean);
 }
 
 // ─── SVG pre-processing (the fix that makes svg2pptx faithful) ────────────────
@@ -324,7 +313,8 @@ async function buildPngDeck(pngPaths: string[]): Promise<Uint8Array> {
 export async function run(
   targets: Target[],
   options: ExportOptions,
-  ctx: ExportContext
+  ctx: ExportContext,
+  hooks?: ExportHooks
 ): Promise<ExportResult> {
   const empty: ExportResult = {
     filename: 'export.pptx',
@@ -352,10 +342,15 @@ export async function run(
       try {
         const bundle = await getBrowserBundle('dom-to-svg', 'domToSvg');
         const svgFiles: string[] = [];
-        for (const t of elementTargets) {
+        for (let i = 0; i < elementTargets.length; i += 1) {
+          const t = elementTargets[i];
           svgFiles.push(
-            ...(await spawnShim(svgArgsFor(t, canvasShellUrl(ctx, t.file), svgDir, bundle)))
+            ...(await spawnPlaywrightShim(
+              svgArgsFor(t, canvasShellUrl(ctx, t.file), svgDir, bundle),
+              hooks
+            ))
           );
+          hooks?.onProgress?.({ current: i + 1, total: elementTargets.length });
         }
         if (!svgFiles.length) return empty;
         const deckBuffers: Uint8Array[] = [];
@@ -382,8 +377,12 @@ export async function run(
 
     // PNG fallback (faithful, universal, Canva-safe, not editable).
     const pngFiles: string[] = [];
-    for (const t of elementTargets) {
-      pngFiles.push(...(await spawnShim(pngArgsFor(t, canvasShellUrl(ctx, t.file), pngDir))));
+    for (let i = 0; i < elementTargets.length; i += 1) {
+      const t = elementTargets[i];
+      pngFiles.push(
+        ...(await spawnPlaywrightShim(pngArgsFor(t, canvasShellUrl(ctx, t.file), pngDir), hooks))
+      );
+      hooks?.onProgress?.({ current: i + 1, total: elementTargets.length });
     }
     if (!pngFiles.length) return empty;
     const body = await buildPngDeck(pngFiles);

package/apps/studio/exporters/scope.ts

@@ -115,6 +115,7 @@ const RAW_EXCLUDES = new Set([
   '_server.json',
   '_active.json',
   '_export-history.json',
+  '_export-jobs',
   '_history',
   '_comments',
   '_canvas-state',

package/apps/studio/exporters/svg.ts

@@ -13,10 +13,11 @@ import path from 'node:path';
 import JSZip from 'jszip';
 
 import { getBrowserBundle } from './_browser-bundles.ts';
-import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
+import { exportShimPath, runShim } from './_runtime.ts';
 import {
   canvasShellUrl,
   type ExportContext,
+  type ExportHooks,
   type ExportOptions,
   type ExportResult,
 } from './index.ts';
@@ -30,7 +31,8 @@ async function captureSvg(
   ctx: ExportContext,
   outDir: string,
   timeoutSec: number,
-  bundlePath: string
+  bundlePath: string,
+  hooks?: ExportHooks
 ): Promise<string[]> {
   const args = [
     SVG_PLAYWRIGHT,
@@ -55,31 +57,20 @@ async function captureSvg(
   // Run via a resolved node/bun runtime so the shim's `import 'playwright'`
   // resolves against dev-server/node_modules (playwright is a devDep). `npm exec`
   // doesn't bridge the module path for ESM imports — confirmed against npm 10.x.
-  // resolveExportRuntime() replaces a hardcoded `'node'` so a compiled binary
-  // without `node` on PATH surfaces an actionable error, not `posix_spawn 'node'`.
-  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
+  // runShim resolves the runtime internally so a compiled binary without
+  // `node` on PATH surfaces an actionable error, not `posix_spawn 'node'`.
+  return runShim(args, {
     cwd: path.dirname(SVG_PLAYWRIGHT),
-    stdout: 'pipe',
-    stderr: 'pipe',
+    signal: hooks?.signal,
+    onProgress: hooks?.onProgress,
   });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-  const code = await proc.exited;
-  if (code !== 0) {
-    throw new Error(`_svg-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
-  }
-  return stdout
-    .split('\n')
-    .map((s) => s.trim())
-    .filter(Boolean);
 }
 
 export async function run(
   targets: Target[],
   options: ExportOptions,
-  ctx: ExportContext
+  ctx: ExportContext,
+  hooks?: ExportHooks
 ): Promise<ExportResult> {
   if (!targets.length) {
     return { filename: 'export.svg', contentType: 'image/svg+xml', body: new Uint8Array(0) };
@@ -96,9 +87,10 @@ export async function run(
 
   try {
     const written: string[] = [];
-    for (const t of elementTargets) {
-      const paths = await captureSvg(t, ctx, tmp, timeoutSec, bundlePath);
+    for (let i = 0; i < elementTargets.length; i += 1) {
+      const paths = await captureSvg(elementTargets[i], ctx, tmp, timeoutSec, bundlePath, hooks);
       written.push(...paths);
+      hooks?.onProgress?.({ current: i + 1, total: elementTargets.length });
     }
     if (!written.length) {
       return { filename: 'export.svg', contentType: 'image/svg+xml', body: new Uint8Array(0) };

package/apps/studio/exporters/video.ts

@@ -20,10 +20,11 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import { getEncodeLibBundle, getWebRendererBundle } from './_browser-bundles.ts';
-import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
+import { exportShimPath, runShim } from './_runtime.ts';
 import {
   canvasShellUrl,
   type ExportContext,
+  type ExportHooks,
   type ExportOptions,
   type ExportResult,
 } from './index.ts';
@@ -47,7 +48,8 @@ async function runVideo(
   format: VideoFormat,
   targets: Target[],
   options: ExportOptions,
-  ctx: ExportContext
+  ctx: ExportContext,
+  hooks?: ExportHooks
 ): Promise<ExportResult> {
   const el = targets.find((t): t is Extract<Target, { kind: 'element' }> => t.kind === 'element');
   if (!el) {
@@ -119,25 +121,18 @@ async function runVideo(
   }
 
   try {
-    const proc = Bun.spawn([resolveExportRuntime(), ...args], {
+    const stdoutLines = await runShim(args, {
       cwd: path.dirname(VIDEO_PLAYWRIGHT),
-      stdout: 'pipe',
-      stderr: 'pipe',
+      signal: hooks?.signal,
+      // No MAUDE_PROGRESS line from this shim yet — frame-count progress is a
+      // follow-up (video scope is always a single artboard, never multi).
     });
-    const [stdout, stderr] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-    ]);
-    const code = await proc.exited;
-    if (code !== 0) {
-      throw new Error(`_video-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
-    }
     const body = new Uint8Array(readFileSync(outPath));
     // The container can differ from the request (mp4 → webm fallback when the
     // browser has no H.264 encoder). Read the summary line for the real ext.
     let ext: string = format;
     try {
-      const lastLine = stdout.trim().split('\n').filter(Boolean).pop() ?? '{}';
+      const lastLine = stdoutLines.at(-1) ?? '{}';
       const summary = JSON.parse(lastLine) as { container?: string };
       if (summary.container) ext = summary.container;
     } catch {
@@ -174,11 +169,14 @@ function resolveFrames(options: ExportOptions, fps: number | undefined): number
 }
 
 export const mp4 = {
-  run: (t: Target[], o: ExportOptions, c: ExportContext) => runVideo('mp4', t, o, c),
+  run: (t: Target[], o: ExportOptions, c: ExportContext, h?: ExportHooks) =>
+    runVideo('mp4', t, o, c, h),
 };
 export const webm = {
-  run: (t: Target[], o: ExportOptions, c: ExportContext) => runVideo('webm', t, o, c),
+  run: (t: Target[], o: ExportOptions, c: ExportContext, h?: ExportHooks) =>
+    runVideo('webm', t, o, c, h),
 };
 export const gif = {
-  run: (t: Target[], o: ExportOptions, c: ExportContext) => runVideo('gif', t, o, c),
+  run: (t: Target[], o: ExportOptions, c: ExportContext, h?: ExportHooks) =>
+    runVideo('gif', t, o, c, h),
 };

package/apps/studio/git/service.ts

@@ -211,7 +211,9 @@ function isMaudeRuntimeState(p: string): boolean {
   return (
     /(^|\/)_(?:server|active|sync|preflight|locator|export-history)\.json$/.test(p) ||
     /(^|\/)_server\.(?:lock|log)$/.test(p) ||
-    /(^|\/)_(?:history|trash|draw|smoke|canvas-state|state|chat|comments|untrusted)(?:\/|$)/.test(p)
+    /(^|\/)_(?:history|trash|draw|smoke|canvas-state|state|chat|comments|untrusted|export-jobs)(?:\/|$)/.test(
+      p
+    )
   );
 }
 

package/apps/studio/http.ts

@@ -16,7 +16,8 @@ import { canvasLibPath } from './canvas-lib-resolver.ts';
 import { TranspileError } from './canvas-pipeline.ts';
 import type { AiActivity } from './collab/ai-activity.ts';
 import type { Context } from './context.ts';
-import { isFormat, isScope, runExport } from './exporters/index.ts';
+import { type Format, isFormat, isScope, type Scope } from './exporters/index.ts';
+import { type ExportJobQueue, ExportQueueFullError } from './exporters/jobs.ts';
 import type { ActiveJsonShape } from './exporters/scope.ts';
 import { createGitEndpoints } from './git/endpoints.ts';
 import { gitShowFile } from './git/service.ts';
@@ -594,7 +595,13 @@ export interface Http {
   isCanvasSafeRoute(pathname: string): boolean;
 }
 
-export function createHttp(ctx: Context, api: Api, inspect: Inspect, ai: AiActivity): Http {
+export function createHttp(
+  ctx: Context,
+  api: Api,
+  inspect: Inspect,
+  ai: AiActivity,
+  exportJobs: ExportJobQueue
+): Http {
   // Cache invalidation — when canvas-lib changes, every cached canvas bundle
   // is stale because canvas-lib is inlined into each one via the resolver
   // plugin. Drop the whole cache so the next request rebuilds with the fresh
@@ -722,6 +729,38 @@ export function createHttp(ctx: Context, api: Api, inspect: Inspect, ai: AiActiv
   const gitJson = (r: { status: number; json: unknown }) =>
     Response.json(r.json, { status: r.status, headers: { 'Cache-Control': 'no-store' } });
 
+  // Shared by /_api/export and /_api/export-jobs — build the exportJobs.enqueue()
+  // args from a validated request body. `inspect.state` is the live `_active.json`;
+  // readers narrow to the resolver's subset locally so the export pipeline doesn't
+  // pin the wider ActiveState interface.
+  function buildExportArgs(
+    req: Request,
+    body: { format: Format; scope: Scope; options?: Record<string, unknown> }
+  ) {
+    const activeJson = inspect.state as unknown as ActiveJsonShape;
+    return {
+      format: body.format,
+      scope: body.scope,
+      options: body.options ?? {},
+      resolve: { activeJson, designRoot: ctx.paths.designRoot, repoRoot: ctx.paths.repoRoot },
+      ctx: {
+        designRoot: ctx.paths.designRoot,
+        repoRoot: ctx.paths.repoRoot,
+        // Adapters reach back into the server via this origin only when they
+        // need Playwright rendering (PNG / PDF / SVG / HTML). The host that
+        // received this request is, by definition, the one serving the canvas.
+        serverOrigin: new URL(req.url).origin,
+        // Mirror `client/app.jsx:85` — the per-DS tokensCssRel wins over the
+        // legacy top-level default (which still points at the pre-multi-DS
+        // layout `system/colors_and_type.css`). Without the per-DS path, the
+        // standalone `_canvas-shell.html` 404s on the tokens link and the
+        // rendered DOM uses `var(--bg-0)` unresolved → screenshots come out
+        // blank. See canvasShellUrl().
+        tokensCssRel: ctx.cfg.designSystems?.[0]?.tokensCssRel ?? ctx.cfg.tokensCssRel,
+      },
+    };
+  }
+
   const routes = {
     '/_health': () =>
       Response.json({
@@ -2041,17 +2080,28 @@ export function createHttp(ctx: Context, api: Api, inspect: Inspect, ai: AiActiv
 
     '/_api/export-history': async (req: Request) => {
       // Phase 6.5 T10 — read-only recent-exports feed for the dialog's
-      // Recent tab. Writes happen as a side-effect of `/_api/export`.
+      // Recent tab. Writes happen as a side-effect of job completion
+      // (exporters/jobs.ts persistAndEvict) rather than this handler.
       if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
-      const history = await api.loadExportHistory();
+      const history = exportJobs.loadHistory();
       return Response.json({ history }, { headers: { 'Cache-Control': 'no-store' } });
     },
 
     '/_api/export': async (req: Request) => {
-      // Phase 6.5 — single dispatch endpoint for the export pipeline.
-      // POST body { format, scope, options? } → binary stream with
-      // Content-Disposition + Content-Type set by the adapter.
+      // feature-background-export-notification-center — thin wrapper over the
+      // job queue: enqueue() then await the SAME job's result. Byte-for-byte
+      // identical external contract to the old synchronous handler, so
+      // `/design:export` (CLI) and any other blocking caller need zero changes.
+      // sameOriginWrite CSRF + loopback-Host (DNS-rebinding) gated, matching
+      // the write-route convention elsewhere in this file (e.g.
+      // /_api/delete-element) — closed as part of the /flow:done security
+      // fan-out (defender finding: this POST now has a disk-write + queue-
+      // growth consequence a bare cross-origin form-POST could trigger).
       if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
       const body = await readJson<{
         format?: unknown;
         scope?: unknown;
@@ -2060,63 +2110,108 @@ export function createHttp(ctx: Context, api: Api, inspect: Inspect, ai: AiActiv
       if (!body) return new Response('body required', { status: 400 });
       if (!isFormat(body.format)) return new Response('unknown or missing format', { status: 400 });
       if (!isScope(body.scope)) return new Response('unknown or missing scope', { status: 400 });
-      // `inspect.state` is the live `_active.json` — readers narrow to the
-      // resolver's subset locally so the export pipeline doesn't pin the
-      // wider ActiveState interface.
-      const activeJson = inspect.state as unknown as ActiveJsonShape;
+      const format = body.format;
+      const scope = body.scope;
       try {
-        const result = await runExport({
-          format: body.format,
-          scope: body.scope,
-          options: body.options ?? {},
-          resolve: { activeJson, designRoot: ctx.paths.designRoot, repoRoot: ctx.paths.repoRoot },
-          ctx: {
-            designRoot: ctx.paths.designRoot,
-            repoRoot: ctx.paths.repoRoot,
-            // Adapters reach back into the server via this origin only when
-            // they need Playwright rendering (PNG / PDF / SVG / HTML). The
-            // host that received this request is, by definition, the one
-            // serving the canvas.
-            serverOrigin: new URL(req.url).origin,
-            // Mirror `client/app.jsx:85` — the per-DS tokensCssRel wins over
-            // the legacy top-level default (which still points at the pre-
-            // multi-DS layout `system/colors_and_type.css`). Without the
-            // per-DS path, the standalone `_canvas-shell.html` 404s on the
-            // tokens link and the rendered DOM uses `var(--bg-0)` unresolved
-            // → screenshots come out blank. See canvasShellUrl().
-            tokensCssRel: ctx.cfg.designSystems?.[0]?.tokensCssRel ?? ctx.cfg.tokensCssRel,
-          },
-        });
-        // Fire-and-forget history append — failure here doesn't block the
-        // download. Synchronous await keeps the order: history reflects the
-        // export the moment the client sees a 200.
-        try {
-          await api.appendExportHistory({
-            format: body.format,
-            scope: body.scope,
-            options: body.options ?? {},
-            filename: result.filename,
-            at: new Date().toISOString(),
-          });
-        } catch {
-          /* ignore — history is best-effort */
-        }
+        const { result } = exportJobs.enqueue(
+          buildExportArgs(req, { format, scope, options: body.options })
+        );
+        const finished = await result;
         // Bun.serve accepts Uint8Array directly; the cast satisfies the
         // SharedArrayBuffer-strict BodyInit narrowing on @types/bun.
-        return new Response(result.body as unknown as BodyInit, {
+        return new Response(finished.body as unknown as BodyInit, {
           status: 200,
           headers: {
-            'Content-Type': result.contentType,
-            'Content-Disposition': `attachment; filename="${result.filename}"`,
+            'Content-Type': finished.contentType,
+            'Content-Disposition': `attachment; filename="${finished.filename}"`,
             'Cache-Control': 'no-store',
           },
         });
       } catch (err) {
+        if (err instanceof ExportQueueFullError) {
+          return new Response(err.message, { status: 429 });
+        }
         const msg = err instanceof Error ? err.message : String(err);
         return new Response(`export failed: ${msg}`, { status: 500 });
       }
     },
 
+    '/_api/export-jobs': async (req: Request) => {
+      // feature-background-export-notification-center — the non-blocking
+      // sibling of /_api/export: same body, returns 202 { jobId } immediately
+      // without awaiting the render. MAIN-ORIGIN ONLY (absent from
+      // CANVAS_SAFE_API + startCanvasServer routes, same trust boundary as
+      // /_api/export today — DDR-060). loopback-Host gated on every method;
+      // the mutating POST is additionally sameOriginWrite CSRF gated (same
+      // /flow:done security fan-out fix as /_api/export above).
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      if (req.method === 'GET') {
+        return Response.json(
+          { jobs: exportJobs.list() },
+          { headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const body = await readJson<{
+        format?: unknown;
+        scope?: unknown;
+        options?: Record<string, unknown>;
+      }>(req, 64 * 1024);
+      if (!body) return new Response('body required', { status: 400 });
+      if (!isFormat(body.format)) return new Response('unknown or missing format', { status: 400 });
+      if (!isScope(body.scope)) return new Response('unknown or missing scope', { status: 400 });
+      try {
+        const { id, result } = exportJobs.enqueue(
+          buildExportArgs(req, { format: body.format, scope: body.scope, options: body.options })
+        );
+        // This route deliberately doesn't await the render — the job's own
+        // status (surfaced via GET /_api/export-jobs + the export:job WS
+        // push) is the completion signal. A render failure still needs a
+        // handler here or it's an unhandled rejection on every failed/timed-
+        // out background job (security fan-out finding, /flow:done) — the
+        // failure is already recorded on the job record, so this is a no-op.
+        result.catch(() => {});
+        return Response.json(
+          { jobId: id },
+          { status: 202, headers: { 'Cache-Control': 'no-store' } }
+        );
+      } catch (err) {
+        if (err instanceof ExportQueueFullError) {
+          return new Response(err.message, { status: 429 });
+        }
+        throw err;
+      }
+    },
+
+    '/_api/export-jobs/download': async (req: Request) => {
+      // MAIN-ORIGIN ONLY, same boundary as /_api/export-jobs above.
+      // loopback-Host gated (read-only — no sameOriginWrite needed — but an
+      // unguessable job-scoped UUID plus this guard closes the DNS-rebinding
+      // angle the /flow:done security fan-out checked for).
+      if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
+      if (!isLoopbackHost(req.headers.get('host')))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const id = new URL(req.url).searchParams.get('id');
+      if (!id) return new Response('id query param required', { status: 400 });
+      const dl = await exportJobs.getBytes(id);
+      if (!dl.ok) {
+        return new Response(dl.reason === 'not-done' ? 'job not finished' : 'Not found', {
+          status: dl.reason === 'not-done' ? 409 : 404,
+        });
+      }
+      return new Response(dl.bytes as unknown as BodyInit, {
+        status: 200,
+        headers: {
+          'Content-Type': dl.contentType,
+          'Content-Disposition': `attachment; filename="${dl.filename}"`,
+          'Cache-Control': 'no-store',
+        },
+      });
+    },
+
     '/_canvas-state': async (req: Request) => {
       const url = new URL(req.url);
       if (req.method === 'GET') {

package/apps/studio/server.ts

@@ -25,6 +25,7 @@ import { type AiActivityEntry, createAiActivity } from './collab/ai-activity.ts'
 import { createGitLifecycle } from './collab/git-lifecycle.ts';
 import { createCollab } from './collab/index.ts';
 import { createContext, reloadConfig } from './context.ts';
+import { createExportJobQueue } from './exporters/jobs.ts';
 import { createFsWatch } from './fs-watch.ts';
 import { createGitWatch } from './git/watch.ts';
 import { createHttp } from './http.ts';
@@ -105,7 +106,8 @@ const activity = createActivity(ctx);
 // rca/issue-canvas-hmr-optimistic-update-consistency).
 const acp = createAcp(ctx, aiActivity);
 const ws = createWs(ctx, api, inspect, collab, activity, acp);
-const http = createHttp(ctx, api, inspect, aiActivity);
+const exportJobs = createExportJobQueue(ctx.bus, ctx.paths.designRoot);
+const http = createHttp(ctx, api, inspect, aiActivity, exportJobs);
 const fsWatch = createFsWatch(ctx);
 
 // Port: --port arg > $PORT > $MDCC_DEV_PORT > 4399.