@1agh/maude 0.40.0 → 0.42.0

package/apps/studio/dom-selection.ts

@@ -146,6 +146,19 @@ export function selectorIndex(doc: Document, selector: string, el: Element | nul
   return 0;
 }
 
+/**
+ * GLOBAL occurrence index of `el` among EVERY node in the document that shares
+ * its `data-cd-id` — the DOM instance index the server-side reused-component
+ * usage resolver (`resolveUsageId`) expects, in source order. Distinct from a
+ * `Selection.index` (which counts within an artboard-SCOPED selector). Used to
+ * route a whole-instance move/resize per-occurrence (Stage H3) so it stays local
+ * to the dragged instance. Matches the reorder drag's own snapshot occurrence.
+ */
+export function globalCdOccurrence(doc: Document, cdId: string, el: Element | null): number {
+  if (!cdId || !el) return 0;
+  return selectorIndex(doc, `[data-cd-id="${cssEscape(cdId)}"]`, el);
+}
+
 /**
  * Resolve a stored Selection to its live element, artboard-scoped. Prefers the
  * id+artboardId scoped selector (the robust path), then the stored `selector`
@@ -175,6 +188,63 @@ export function resolveSelectionEl(
   return null;
 }
 
+/**
+ * Length of the trailing run `a` and `b` share, walked from the end. `domPath()`
+ * hops carry no positional (nth-child) info, so a shared suffix survives a
+ * sibling insertion/removal anywhere earlier in the tree — exactly the DDR-019
+ * `data-cd-id` renumbering case this fallback exists for.
+ */
+function matchingSuffixLength(a: string[], b: string[]): number {
+  let n = 0;
+  const max = Math.min(a.length, b.length);
+  for (let i = 1; i <= max; i++) {
+    if (a[a.length - i] !== b[b.length - i]) break;
+    n++;
+  }
+  return n;
+}
+
+/**
+ * Best-effort structural fallback for when a stored `data-cd-id` selector no
+ * longer identifies the intended element. A canvas rewrite (`/design:edit`
+ * regenerating JSX) renumbers `data-cd-id` — it's an AST-position fingerprint,
+ * not a stable identity (DDR-019) — so the id can end up on an unrelated
+ * element, or on none at all. This scores every stamped element in the
+ * artboard by how much of its live `domPath()` matches the STORED path
+ * (as a trailing run) plus authored-class overlap, and requires the leaf tag
+ * to match. Returns null when nothing scores above zero (no plausible match —
+ * the caller should treat the target as gone).
+ */
+export function resolveByDomPath(
+  doc: Document,
+  opts: { artboardId?: string | null; tag?: string; classes?: string; dom_path?: string[] }
+): Element | null {
+  const storedPath = opts.dom_path;
+  const wantTag = (opts.tag || '').toLowerCase();
+  if (!storedPath || storedPath.length === 0 || !wantTag) return null;
+  let scope: ParentNode = doc;
+  if (opts.artboardId) {
+    const artboard = doc.querySelector(`[data-dc-screen="${opts.artboardId}"]`);
+    if (artboard) scope = artboard;
+  }
+  const wantClasses = (opts.classes || '').split(/\s+/).filter(Boolean);
+  let best: Element | null = null;
+  let bestScore = 0;
+  for (const el of Array.from(scope.querySelectorAll('[data-cd-id]'))) {
+    if (el.tagName.toLowerCase() !== wantTag) continue;
+    const suffix = matchingSuffixLength(domPath(el), storedPath);
+    if (suffix === 0) continue;
+    const liveClasses = realClasses(el).split(/\s+/).filter(Boolean);
+    const overlap = wantClasses.filter((c) => liveClasses.includes(c)).length;
+    const score = suffix * 10 + overlap;
+    if (score > bestScore) {
+      bestScore = score;
+      best = el;
+    }
+  }
+  return best;
+}
+
 /**
  * Phase 12.2 — style maps for the CSS-knob properties. `authored` is what the
  * element sets INLINE (React renders `style={{padding:8}}` → `style="padding:8px"`),
@@ -193,9 +263,18 @@ const KNOB_PROPS = [
   // Layout
   'display',
   'flex-direction',
+  'flex-wrap',
   'align-items',
   'justify-content',
   'gap',
+  // Stage M — flex-CHILD props (sizing mode Fill + the Auto-layout child rows).
+  // Shown only when the PARENT is flex (Selection.parentDisplay); captured here so
+  // they round-trip. `flex` shorthand is listed for customStyles-exclusion only.
+  'flex',
+  'flex-grow',
+  'flex-shrink',
+  'flex-basis',
+  'align-self',
   // Typography
   'font-family',
   'color',
@@ -219,7 +298,10 @@ const KNOB_PROPS = [
   // Size
   'width',
   'height',
+  'min-width',
+  'min-height',
   'max-width',
+  'max-height',
   // Appearance
   'background-color',
   'border-radius',
@@ -232,6 +314,32 @@ const KNOB_PROPS = [
   'border-color',
   'box-shadow',
   'opacity',
+  // feature-element-editing-robustness Stage B — promotes DDR-104 §3's OUT-list
+  // into curated rows (superseded by the Stage-G DDR). Adding them here captures
+  // their authored/computed values for the new panel controls AND moves them out
+  // of the Advanced "customStyles" hatch (a canvas that carried one as a raw
+  // custom prop now surfaces it in its curated row instead).
+  // Position + stacking
+  'position',
+  'top',
+  'right',
+  'bottom',
+  'left',
+  'z-index',
+  // Transform
+  'transform',
+  'transform-origin',
+  // Typography (extra)
+  'font-style',
+  'text-transform',
+  'text-decoration',
+  'white-space',
+  // Overflow
+  'overflow',
+  // Media framing
+  'object-fit',
+  'aspect-ratio',
+  'object-position',
 ] as const;
 
 // Phase 12.3 — HTML attributes the custom-attribute hatch may have written, so a
@@ -245,6 +353,8 @@ function styleMapsFor(el: Element | null): {
   computed: Record<string, string>;
   customStyles: Record<string, string>;
   attrs: Record<string, string>;
+  parentDisplay?: string;
+  parentFlexDirection?: string;
 } {
   if (!el || typeof window === 'undefined' || !window.getComputedStyle) {
     return { authored: {}, computed: {}, customStyles: {}, attrs: {} };
@@ -283,7 +393,16 @@ function styleMapsFor(el: Element | null): {
       if (ATTR_SKIP.test(a.name)) continue;
       attrs[a.name] = a.value;
     }
-    return { authored, computed, customStyles, attrs };
+    // Stage M — parent's layout context (for the Fixed/Hug/Fill sizing control +
+    // flex-child row gating). Read here because the shell can't reach the
+    // cross-origin iframe to compute it after selection.
+    const parent = (el as HTMLElement).parentElement;
+    const parentDisplay = parent ? window.getComputedStyle(parent).display : '';
+    const parentFlexDirection =
+      parent && (parentDisplay === 'flex' || parentDisplay === 'inline-flex')
+        ? window.getComputedStyle(parent).flexDirection
+        : '';
+    return { authored, computed, customStyles, attrs, parentDisplay, parentFlexDirection };
   } catch {
     return { authored: {}, computed: {}, customStyles: {}, attrs: {} };
   }
@@ -336,6 +455,13 @@ export function hoverTargetToSelection(target: HoverTarget, file?: string): Sele
           h: Math.round(rect.height),
         }
       : null,
+    // WORLD-unit size — `offsetWidth`/`offsetHeight` are the element's own local
+    // pixel box, unaffected by an ancestor's `.dc-world` zoom transform (unlike
+    // `bounds`, which is the SCREEN rect and lies at any zoom other than 100%).
+    // The Inspector's artboard-resize fields (Stage D4 tail) need the true
+    // JSX-authored width/height to pre-fill correctly regardless of zoom.
+    worldW: el instanceof HTMLElement ? Math.round(el.offsetWidth) : undefined,
+    worldH: el instanceof HTMLElement ? Math.round(el.offsetHeight) : undefined,
     html: el ? (el.outerHTML ?? '').slice(0, 4000) : '',
     ...styleMapsFor(el),
   };

package/apps/studio/drag-state.ts

@@ -0,0 +1,24 @@
+/**
+ * @file       drag-state.ts
+ * @purpose    Tiny shared module-scope flag: is an in-canvas ELEMENT drag
+ *             (`ReorderDrag` — reorder or out-of-flow reposition) currently
+ *             active? Consulted by per-frame rAF overlays (`ElementResizeOverlay`,
+ *             `SpacingHandlesOverlay`) so they can skip their own
+ *             getBoundingClientRect/getComputedStyle work while the drag's OWN
+ *             live-preview chrome is what matters — avoids compounding rAF cost
+ *             during the single most DOM-churn-heavy gesture the canvas has
+ *             (dogfood 2026-07-07: "hrozně zavaší ten toolbar" during reorder).
+ *             A standalone module (not exported from canvas-shell.tsx) so the
+ *             overlay files can import it without a circular import back into
+ *             canvas-shell.tsx (which imports THEM).
+ */
+
+let active = false;
+
+export function setElementDragActive(v: boolean): void {
+  active = v;
+}
+
+export function isElementDragActive(): boolean {
+  return active;
+}

package/apps/studio/equal-spacing-detector.ts

@@ -96,3 +96,208 @@ export function detectEqualSpacing(
 
   return { axis, gapPx: median, midpoints };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Task L7 — Alt-hover distance measurement between exactly TWO rects (the
+// selected element + whatever's hovered). Same pairwise-gap formula as
+// `detectEqualSpacing`'s loop body, but without its 3-rect / equal-tolerance
+// preconditions, and shaped for line-painting rather than midpoint dots.
+
+export interface PairGap {
+  axis: SpacingAxis;
+  /** The gap between the two rects' facing edges, in the caller's coord space. */
+  gap: number;
+  /** Leading edge of the gap span — `left` for an x-axis line, `top` for y. */
+  from: number;
+  /** Perpendicular-axis center of the pair — `top` for an x-axis line
+   *  (vertically centers it between the two rects), `left` for y. */
+  cross: number;
+}
+
+/**
+ * Distance between two rects along one axis. Returns `null` when they
+ * overlap on that axis (no meaningful gap — e.g. two rects stacked only on
+ * y have no x-axis gap to show).
+ */
+export function computePairGap(a: Rect, b: Rect, axis: SpacingAxis): PairGap | null {
+  const [first, second] =
+    axis === 'x' ? (a.x <= b.x ? [a, b] : [b, a]) : a.y <= b.y ? [a, b] : [b, a];
+  if (axis === 'x') {
+    const gap = second.x - (first.x + first.w);
+    if (gap <= 0) return null;
+    return {
+      axis,
+      gap,
+      from: first.x + first.w,
+      cross: (first.y + first.h / 2 + second.y + second.h / 2) / 2,
+    };
+  }
+  const gap = second.y - (first.y + first.h);
+  if (gap <= 0) return null;
+  return {
+    axis,
+    gap,
+    from: first.y + first.h,
+    cross: (first.x + first.w / 2 + second.x + second.w / 2) / 2,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Task L5 — distribute / align / tidy-up for a multi-selection of ELEMENTS.
+//
+// These mirror the artboard `distributeArtboards`/`alignArtboards` algorithms
+// in canvas-shell.tsx verbatim, generalized from `ArtboardRect` to any rect
+// set. Kept pure/DOM-free like `detectEqualSpacing` above — the caller
+// resolves DOM rects, calls these, then posts one `reposition-request` per
+// moved rect through the existing element-drag write lane (no new endpoint).
+//
+// `key` is an OPAQUE caller-supplied correlation token (not a `data-cd-id`) —
+// a shared-component instance's cd-id can repeat across selections
+// (disambiguated only by occurrence index), so matching results back to the
+// caller's own bookkeeping by `id` would collide. Callers pass e.g. the
+// selection's array index as `key` and zip the result back themselves.
+
+export interface KeyedRect extends Rect {
+  key: string;
+}
+
+export type AlignAxisMode = 'left' | 'right' | 'center-x' | 'top' | 'bottom' | 'center-y';
+
+export interface MovedRect {
+  key: string;
+  x: number;
+  y: number;
+}
+
+/**
+ * Align 2+ rects to a common edge/midline of their union bbox. Returns only
+ * the rects whose position actually changes (rounded-equal = no-op, skipped).
+ */
+export function computeAlign(rects: KeyedRect[], mode: AlignAxisMode): MovedRect[] {
+  if (rects.length < 2) return [];
+  let xMin = Number.POSITIVE_INFINITY;
+  let yMin = Number.POSITIVE_INFINITY;
+  let xMax = Number.NEGATIVE_INFINITY;
+  let yMax = Number.NEGATIVE_INFINITY;
+  for (const r of rects) {
+    if (r.x < xMin) xMin = r.x;
+    if (r.y < yMin) yMin = r.y;
+    if (r.x + r.w > xMax) xMax = r.x + r.w;
+    if (r.y + r.h > yMax) yMax = r.y + r.h;
+  }
+  const cx = (xMin + xMax) / 2;
+  const cy = (yMin + yMax) / 2;
+  const moved: MovedRect[] = [];
+  for (const r of rects) {
+    let nx = r.x;
+    let ny = r.y;
+    switch (mode) {
+      case 'left':
+        nx = xMin;
+        break;
+      case 'right':
+        nx = xMax - r.w;
+        break;
+      case 'center-x':
+        nx = cx - r.w / 2;
+        break;
+      case 'top':
+        ny = yMin;
+        break;
+      case 'bottom':
+        ny = yMax - r.h;
+        break;
+      case 'center-y':
+        ny = cy - r.h / 2;
+        break;
+    }
+    if (Math.round(nx) === Math.round(r.x) && Math.round(ny) === Math.round(r.y)) continue;
+    moved.push({ key: r.key, x: Math.round(nx), y: Math.round(ny) });
+  }
+  return moved;
+}
+
+/**
+ * Distribute 3+ rects with equal gaps on one axis. Sorts by leading edge,
+ * holds the first + last fixed, redistributes the middle ones so the trailing
+ * → next-leading gap is equal everywhere.
+ */
+export function computeDistribute(rects: KeyedRect[], axis: SpacingAxis): MovedRect[] {
+  if (rects.length < 3) return [];
+  const sorted = [...rects].sort((a, b) => (axis === 'x' ? a.x - b.x : a.y - b.y));
+  const first = sorted[0];
+  const last = sorted[sorted.length - 1];
+  if (!first || !last) return [];
+  const sideLen = (r: KeyedRect) => (axis === 'x' ? r.w : r.h);
+  const totalSides = sorted.reduce((acc, r) => acc + sideLen(r), 0);
+  const span = (axis === 'x' ? last.x + last.w - first.x : last.y + last.h - first.y) - totalSides;
+  const gap = span / (sorted.length - 1);
+  const moved: MovedRect[] = [];
+  let cursor = axis === 'x' ? first.x + first.w + gap : first.y + first.h + gap;
+  for (let i = 1; i < sorted.length - 1; i++) {
+    const r = sorted[i];
+    if (!r) continue;
+    if (axis === 'x') {
+      moved.push({ key: r.key, x: Math.round(cursor), y: Math.round(r.y) });
+      cursor += r.w + gap;
+    } else {
+      moved.push({ key: r.key, x: Math.round(r.x), y: Math.round(cursor) });
+      cursor += r.h + gap;
+    }
+  }
+  return moved;
+}
+
+export interface TidyOptions {
+  /** Pixel gap between grid cells, both axes. Default 16. */
+  gap?: number;
+  /** Column count. Default: near-square (`round(sqrt(n))`). */
+  columns?: number;
+}
+
+/**
+ * Snap 2+ rects into a clean grid: reading-order sort (top-to-bottom, then
+ * left-to-right), laid out at a fixed gap from the union bbox's top-left,
+ * each column/row sized to its widest/tallest member so nothing overlaps.
+ */
+export function computeTidyGrid(rects: KeyedRect[], opts: TidyOptions = {}): MovedRect[] {
+  const n = rects.length;
+  if (n < 2) return [];
+  const gap = opts.gap ?? 16;
+  const columns = Math.max(1, Math.min(n, opts.columns ?? Math.round(Math.sqrt(n))));
+  const sorted = [...rects].sort((a, b) => a.y - b.y || a.x - b.x);
+  const originX = Math.min(...rects.map((r) => r.x));
+  const originY = Math.min(...rects.map((r) => r.y));
+  const rows = Math.ceil(n / columns);
+  const colWidths: number[] = new Array(columns).fill(0);
+  const rowHeights: number[] = new Array(rows).fill(0);
+  sorted.forEach((r, i) => {
+    const row = Math.floor(i / columns);
+    const col = i % columns;
+    colWidths[col] = Math.max(colWidths[col] ?? 0, r.w);
+    rowHeights[row] = Math.max(rowHeights[row] ?? 0, r.h);
+  });
+  const colX: number[] = [];
+  {
+    let cursor = originX;
+    for (let c = 0; c < columns; c++) {
+      colX.push(cursor);
+      cursor += (colWidths[c] ?? 0) + gap;
+    }
+  }
+  const rowY: number[] = [];
+  {
+    let cursor = originY;
+    for (let r = 0; r < rows; r++) {
+      rowY.push(cursor);
+      cursor += (rowHeights[r] ?? 0) + gap;
+    }
+  }
+  return sorted.map((r, i) => {
+    const row = Math.floor(i / columns);
+    const col = i % columns;
+    const nx = colX[col] ?? r.x;
+    const ny = rowY[row] ?? r.y;
+    return { key: r.key, x: Math.round(nx), y: Math.round(ny) };
+  });
+}

package/apps/studio/export-dialog.tsx

@@ -3,8 +3,10 @@
  * @scope      apps/studio/export-dialog.tsx
  * @purpose    Native `<dialog>`-based export modal. Three controls — format,
  *             scope, per-format options — plus a Recent tab populated by
- *             `/_api/export-history`. Submit fires `POST /_api/export`, the
- *             response is piped to a Blob URL anchor download. `⌘E` opens
+ *             `/_api/export-history`. Submit POSTs `/_api/export-jobs` and
+ *             closes immediately (feature-background-export-notification-
+ *             center) — the main-shell notification center owns status/
+ *             progress/completion from there, not this dialog. `⌘E` opens
  *             the dialog from anywhere inside the canvas; `⌘⇧E` re-runs the
  *             most recent export without opening (T10 fast path).
  *
@@ -271,7 +273,7 @@ const DIALOG_CSS = `
 .dc-export-dialog footer button.dc-ed-primary { background: var(--maude-hud-accent, #1a1a1a); color: var(--maude-hud-accent-fg, #fff); border-color: transparent; }
 .dc-export-dialog footer button:disabled { opacity: 0.4; cursor: not-allowed; }
 .dc-export-dialog .dc-ed-status { padding: 8px 20px; font-size: 12px; color: var(--maude-chrome-fg-1, rgba(40,30,20,0.65)); border-top: 1px solid var(--maude-chrome-border, rgba(0,0,0,0.08)); }
-.dc-export-dialog .dc-ed-status.is-error { color: var(--status-error, #c0392b); }
+.dc-export-dialog .dc-ed-status.is-error { color: #c0392b; }
 `;
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -293,7 +295,9 @@ export function ExportDialogProvider({ children }: { children: ReactNode }): Rea
     dialogRef.current?.close();
   }, []);
 
-  // Pre-load history when the dialog opens; refresh after each export.
+  // Loaded when the dialog opens. Submit now closes the dialog immediately
+  // (the job runs in the background) instead of refreshing this in place —
+  // the next open picks up whatever's finished by then.
   const loadHistory = useCallback(async () => {
     try {
       if (isCrossOriginFramed()) {
@@ -364,10 +368,13 @@ export function ExportDialogProvider({ children }: { children: ReactNode }): Rea
       setStatus(null);
       try {
         if (isCrossOriginFramed()) {
-          // Bridge through the main shell — the iframe can't reach /_api/export
-          // (canvas origin 403s it). The parent runs the export + triggers the
-          // download, then replies with the saved filename or an error string.
-          const res = await bridgeRequest<{ ok?: boolean; filename?: string; error?: string }>(
+          // Bridge through the main shell — the iframe can't reach
+          // /_api/export-jobs (canvas origin 403s it, DDR-060). The parent
+          // enqueues the job and replies with the id immediately; the
+          // trusted main-shell notification center (which already owns the
+          // WS connection) is the single place status/progress/completion
+          // live from here — this dialog no longer polls or receives bytes.
+          const res = await bridgeRequest<{ ok?: boolean; jobId?: string; error?: string }>(
             'export-request',
             'export-result',
             { payload: { format, scope, options } }
@@ -376,11 +383,10 @@ export function ExportDialogProvider({ children }: { children: ReactNode }): Rea
             setStatus({ text: `Export failed: ${res.error || 'unknown'}`, isError: true });
             return;
           }
-          setStatus({ text: `Saved ${res.filename ?? 'export'}`, isError: false });
-          void loadHistory();
+          close();
           return;
         }
-        const r = await fetch('/_api/export', {
+        const r = await fetch('/_api/export-jobs', {
           method: 'POST',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ format, scope, options }),
@@ -390,20 +396,7 @@ export function ExportDialogProvider({ children }: { children: ReactNode }): Rea
           setStatus({ text: `Export failed: ${text || r.status}`, isError: true });
           return;
         }
-        const disp = r.headers.get('Content-Disposition') ?? '';
-        const filename =
-          /filename="([^"]+)"/.exec(disp)?.[1] ?? `export${FORMAT_META[format].defaultExt}`;
-        const blob = await r.blob();
-        const url = URL.createObjectURL(blob);
-        const a = document.createElement('a');
-        a.href = url;
-        a.download = filename;
-        document.body.appendChild(a);
-        a.click();
-        a.remove();
-        URL.revokeObjectURL(url);
-        setStatus({ text: `Saved ${filename}`, isError: false });
-        void loadHistory();
+        close();
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         setStatus({ text: `Export failed: ${msg}`, isError: true });
@@ -411,7 +404,7 @@ export function ExportDialogProvider({ children }: { children: ReactNode }): Rea
         setSubmitting(false);
       }
     },
-    [loadHistory]
+    [close]
   );
 
   const rerunLast = useCallback(async () => {

package/apps/studio/exporters/_runtime.ts

@@ -67,3 +67,107 @@ export function resolveExportRuntime(): string {
   }
   return runtime;
 }
+
+export interface SpawnShimOptions {
+  /** cwd for the spawned shim — callers pass `path.dirname(<SHIM>)`. */
+  cwd: string;
+  /** Aborts the render — kills the child process. */
+  signal?: AbortSignal;
+  /** Fired for each `MAUDE_PROGRESS {"current":N,"total":M}` stdout line. */
+  onProgress?: (update: { current: number; total: number }) => void;
+}
+
+export interface SpawnShimResult {
+  code: number;
+  /** stdout lines with `MAUDE_PROGRESS` lines filtered out (written-file paths etc.). */
+  stdoutLines: string[];
+  stderr: string;
+}
+
+const PROGRESS_LINE = /^MAUDE_PROGRESS (.+)$/;
+
+/**
+ * Spawn a render shim (`bin/_{png,pdf,svg,html,pptx,video}-playwright.mjs`)
+ * via a resolved node/bun runtime, reading stdout INCREMENTALLY (not
+ * buffered via `new Response(proc.stdout).text()`) so a `MAUDE_PROGRESS`
+ * line written mid-render reaches `onProgress` as soon as it's flushed,
+ * instead of only after the whole process exits. Non-progress lines
+ * (written-file paths, the existing per-adapter contract) collect into
+ * `stdoutLines` in the order they arrived. Exit-code handling stays with the
+ * caller — this returns the same shape the old `Promise.all([...text()])`
+ * block did, so adapters keep their existing `if (code !== 0) throw …`.
+ */
+export async function spawnShim(args: string[], opts: SpawnShimOptions): Promise<SpawnShimResult> {
+  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
+    cwd: opts.cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    signal: opts.signal,
+  });
+  // Bun.spawn's `signal` option kills the child on abort; this listener is a
+  // defensive fallback in case a given Bun build ignores it — cheap and
+  // idempotent (killing an already-exited process is a no-op).
+  const onAbort = () => {
+    try {
+      proc.kill();
+    } catch {
+      /* already exited */
+    }
+  };
+  opts.signal?.addEventListener('abort', onAbort);
+
+  const stderrPromise = new Response(proc.stderr).text();
+  const stdoutLines: string[] = [];
+  let buffer = '';
+  const consumeLine = (line: string) => {
+    if (!line) return;
+    const match = PROGRESS_LINE.exec(line);
+    if (!match) {
+      stdoutLines.push(line);
+      return;
+    }
+    try {
+      const update = JSON.parse(match[1]) as { current: number; total: number };
+      opts.onProgress?.(update);
+    } catch {
+      /* malformed progress line — drop it rather than treat it as a file path */
+    }
+  };
+
+  try {
+    const reader = proc.stdout.pipeThrough(new TextDecoderStream()).getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += value;
+      let newlineIdx = buffer.indexOf('\n');
+      while (newlineIdx !== -1) {
+        consumeLine(buffer.slice(0, newlineIdx).trim());
+        buffer = buffer.slice(newlineIdx + 1);
+        newlineIdx = buffer.indexOf('\n');
+      }
+    }
+    if (buffer.trim()) consumeLine(buffer.trim());
+  } finally {
+    opts.signal?.removeEventListener('abort', onAbort);
+  }
+
+  const [stderr, code] = await Promise.all([stderrPromise, proc.exited]);
+  return { code, stdoutLines, stderr };
+}
+
+/**
+ * `spawnShim()` + the exit-code check every adapter did identically
+ * (`if (code !== 0) throw new Error(...)`; `code review, /flow:done` — six
+ * near-copies collapsed into one). `args[0]` is the shim path by convention
+ * (every adapter builds it that way), used only for the error message.
+ */
+export async function runShim(args: string[], opts: SpawnShimOptions): Promise<string[]> {
+  const { code, stdoutLines, stderr } = await spawnShim(args, opts);
+  if (code !== 0) {
+    throw new Error(
+      `${path.basename(args[0])} exited ${code}: ${stderr.trim() || stdoutLines.join('\n').trim()}`
+    );
+  }
+  return stdoutLines;
+}