@1agh/maude 0.42.0 → 0.44.0

package/apps/studio/canvas-lib.tsx

@@ -87,6 +87,7 @@ import {
   createContext,
   Fragment,
   isValidElement,
+  type MouseEvent as ReactMouseEvent,
   type ReactNode,
   type PointerEvent as ReactPointerEvent,
   type RefObject,
@@ -106,6 +107,11 @@ import {
   diffLayoutPositions,
 } from './commands/move-artboards-command.ts';
 import { scopedCdSelector, selectorIndex, shortText } from './dom-selection.ts';
+// Photo editor (feature-photo-editor) — schema.ts is DEPENDENCY-FREE (no pixi),
+// so this static import is safe and adds zero bundle cost. The WebGL compositor
+// (photo/pipeline.ts, which imports pixi.js) is loaded via a DYNAMIC import
+// inside <PhotoLayer> only when an edited photo actually mounts — see there.
+import { isDefaultEdit, type PhotoEdit } from './photo/schema.ts';
 import { AgentPresenceProvider, useAgentPresence } from './use-agent-presence.tsx';
 import { type DragState, useArtboardDrag } from './use-artboard-drag.tsx';
 import {
@@ -118,13 +124,14 @@ import { CollabProvider, canvasSlugFromPath } from './use-collab.tsx';
 import { useSelectionSetOptional } from './use-selection-set.tsx';
 import { MaybeToolProvider, useToolModeOptional } from './use-tool-mode.tsx';
 import { UndoStackProvider, useUndoSinks, useUndoStackOptional } from './use-undo-stack.tsx';
+// DDR-148 — video-comp canvas kind. Imported (not just re-exported below) so
+// DCArtboard can identity-match <VideoComp> for the header badge. Its
+// `remotion`/`@remotion/player` imports resolve through the canvas importmap
+// (RUNTIME_PACKAGES), same as react/motion.
+import { VideoComp } from './video-comp.tsx';
 
 export type { CompSnapshot, VideoCompMeta, VideoCompProps } from './video-comp.tsx';
-// DDR-148 — video-comp canvas kind. Re-exported so `@maude/canvas-lib` exposes
-// <VideoComp> (Remotion composition mounted in <Player> + the deterministic
-// seek bridge). Its `remotion`/`@remotion/player` imports resolve through the
-// canvas importmap (RUNTIME_PACKAGES), same as react/motion.
-export { VideoComp } from './video-comp.tsx';
+export { VideoComp };
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Module constants
@@ -320,6 +327,28 @@ button.dc-artboard-label {
   width: 100%;
 }
 button.dc-artboard-label:focus-visible { outline: 2px solid var(--maude-hud-accent, #d63b1f); outline-offset: -2px; }
+/* DDR-148 — video-artboard badge, overlaid top-right of the header. Opens
+   the timeline panel (same postMessage the context-menu entry sends). */
+.dc-canvas .dc-artboard-video-badge {
+  position: absolute;
+  top: 4px;
+  right: 6px;
+  z-index: 2;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  padding: 0;
+  appearance: none;
+  border: none;
+  border-radius: 3px;
+  background: var(--bg-2, #e8e3d8);
+  color: var(--fg-1, #4a3f30);
+  cursor: pointer;
+}
+.dc-canvas .dc-artboard-video-badge:hover { background: color-mix(in oklab, var(--fg-0, #2a2520) 12%, var(--bg-2, #e8e3d8)); }
+.dc-canvas .dc-artboard-video-badge:focus-visible { outline: 2px solid var(--maude-hud-accent, #d63b1f); outline-offset: 1px; }
 /* Active-artboard ring is in canvas-shell HALO_CSS (subtle 1 px tint). */
 /* Phase 4.2 — drag chrome. */
 .dc-canvas[data-active-tool="move"] .dc-artboard-label { cursor: grab; }
@@ -369,6 +398,11 @@ export interface WorldContextValue {
   rectFor: (id: string) => ArtboardRect | null;
   /** All artboards in render order, with resolved world-coord positions. */
   artboards: ArtboardRect[];
+  /** Hug-mode artboards report their measured DOM height here so the shared
+   *  ArtboardRect model (drag hit-test, marquee, fit-to-screen, culling) stays
+   *  in sync with content that grows/shrinks. Runtime-only — never persisted
+   *  to meta; a fixed-mode board never calls this. */
+  reportMeasuredHeight: (id: string, h: number) => void;
   /** Current pan/zoom state. `null` until the first useLayoutEffect runs. */
   viewport: ViewportState | null;
   /** id of the artboard closest to the viewport center (recomputed on settle). */
@@ -451,6 +485,29 @@ function harvestArtboards(children: ReactNode): ArtboardSeed[] {
   return out;
 }
 
+/**
+ * Does this artboard's subtree contain a <VideoComp>? Same identity-match +
+ * displayName-fallback walk as harvestArtboards, short-circuiting on the
+ * first hit — used to badge video artboards in DCArtboard's header.
+ */
+function subtreeHasVideoComp(children: ReactNode): boolean {
+  function visit(node: ReactNode): boolean {
+    if (node == null || typeof node === 'boolean') return false;
+    if (Array.isArray(node)) return node.some(visit);
+    if (!isValidElement(node)) return false;
+    const type = node.type;
+    if (
+      type === VideoComp ||
+      (typeof type === 'function' && (type as { displayName?: string }).displayName === 'VideoComp')
+    ) {
+      return true;
+    }
+    const childProp = (node.props as { children?: ReactNode } | null | undefined)?.children;
+    return childProp != null ? visit(childProp) : false;
+  }
+  return visit(children);
+}
+
 function synthDefaultGrid(seeds: ArtboardSeed[]): ArtboardRect[] {
   // Render order (the order DCArtboards appear in JSX), not alphabetical —
   // authors label artboards DS-01 / DS-02 / CV-01 etc. and expect that
@@ -1583,16 +1640,33 @@ function DesignCanvasInner({ children, controls }: DesignCanvasProps) {
   // useLayoutEffect writes the initial transform before first paint.
   const worldStyle: CSSProperties = { visibility: 'hidden' };
 
+  // Hug-mode height feedback (artboard "hug height" default). A hug board's
+  // CSS height is `auto` (content-driven) — the DOM is authoritative, and this
+  // just mirrors the measured height into the shared ArtboardRect model so
+  // OTHER consumers (marquee, distribute, fit-to-screen, off-screen culling)
+  // see the current box. Never touches meta/JSX — purely runtime state, unlike
+  // commitArtboardPositions/applyArtboardLayout which persist. A no-op guard
+  // on <1px delta avoids a ResizeObserver → setState → render → (stable, since
+  // CSS height never reads back rect.h in hug mode) loop.
+  const reportMeasuredHeight = useCallback((id: string, h: number) => {
+    setArtboards((prev) => {
+      const cur = prev.find((r) => r.id === id);
+      if (!cur || Math.abs(cur.h - h) < 1) return prev;
+      return prev.map((r) => (r.id === id ? { ...r, h } : r));
+    });
+  }, []);
+
   const ctxValue = useMemo<WorldContextValue>(
     () => ({
       rectFor,
       artboards,
+      reportMeasuredHeight,
       viewport: controller.viewport,
       activeArtboardId,
       hostRef,
       worldRef,
     }),
-    [rectFor, artboards, controller.viewport, activeArtboardId]
+    [rectFor, artboards, reportMeasuredHeight, controller.viewport, activeArtboardId]
   );
 
   const showMiniMap = controls?.minimap !== false;
@@ -1741,12 +1815,30 @@ export function DCArtboard({
   label,
   width,
   height,
+  fixed,
+  background,
+  padding,
+  layout,
+  gap,
   children,
 }: {
   id: string;
   label: string;
   width: number;
   height: number;
+  /** Height sizing mode. Default (omitted/false) = HUG — the board grows to
+   *  fit content; `height` becomes a min-height floor rather than an exact
+   *  size. `true` = FIXED — today's behavior, `height` is exact and overflow
+   *  clips. Width is always exact regardless of this flag. */
+  fixed?: boolean;
+  /** `.dc-artboard-body` background (CSS color/token, e.g. "var(--bg-1)"). */
+  background?: string;
+  /** `.dc-artboard-body` padding, px, all sides. */
+  padding?: number;
+  /** `.dc-artboard-body` layout mode. Default = the engine's plain block flow. */
+  layout?: 'block' | 'flex-col' | 'flex-row' | 'grid';
+  /** `.dc-artboard-body` gap, px — only visible under flex-col/flex-row/grid. */
+  gap?: number;
   children: ReactNode;
 }) {
   const ctx = useWorldContext();
@@ -1761,6 +1853,21 @@ export function DCArtboard({
   // its presence color + show its funny name instead of the generic file label.
   const agent = useAgentPresence();
   const rect = ctx ? ctx.rectFor(id) : null;
+  // DDR-148 — badge video artboards in the header; clicking the badge opens
+  // the timeline panel via the same postMessage the context-menu "Open
+  // Timeline" entry already sends (canvas-shell.tsx artboardHasVideo/handler).
+  const hasVideo = useMemo(() => subtreeHasVideoComp(children), [children]);
+  const openTimeline = useCallback(
+    (e: ReactMouseEvent<HTMLButtonElement>) => {
+      e.stopPropagation();
+      try {
+        window.parent.postMessage({ dgn: 'open-timeline-request', artboardId: id }, '*');
+      } catch {
+        /* detached / cross-origin */
+      }
+    },
+    [id]
+  );
 
   // Drag hook — always called (hook rules). Inert outside DesignCanvas
   // (allRects empty, enabled=false), so specimens / legacy uses get a plain
@@ -1793,11 +1900,67 @@ export function DCArtboard({
     }
   }, [dragHook.dragState, dragBus]);
 
+  // Hug default (artboard "hug height") — the authored `height` prop is a
+  // FLOOR (min-height), not an exact size, unless `fixed` pins it. The floor
+  // stays stable across renders (it only changes when the JSX prop itself is
+  // edited), so it never ratchets up from a previously-larger measured value
+  // the way feeding `rect.h` back as the floor would.
+  const heightFloor = typeof height === 'number' ? height : VP_GRID.h;
+  const articleRef = useRef<HTMLElement | null>(null);
+  const measured = useArtboardBounds(articleRef as RefObject<HTMLElement | null>);
+  useEffect(() => {
+    if (!ctx || fixed) return;
+    if (dragHook.dragState.kind !== 'idle') return;
+    if (measured.height <= 0) return;
+    ctx.reportMeasuredHeight(id, Math.round(measured.height));
+  }, [ctx, fixed, dragHook.dragState.kind, measured.height, id]);
+
+  // Phase 2 — background/padding/layout/gap apply to the BODY (content box),
+  // not the frame (label header stays chrome-styled). Undefined keys are
+  // simply absent from the style object — no engine-CSS default is clobbered.
+  const bodyStyle = useMemo<CSSProperties>(() => {
+    const st: CSSProperties = {};
+    if (background) st.background = background;
+    if (typeof padding === 'number') st.padding = padding;
+    if (typeof gap === 'number') st.gap = gap;
+    if (layout === 'flex-col') {
+      st.display = 'flex';
+      st.flexDirection = 'column';
+    } else if (layout === 'flex-row') {
+      st.display = 'flex';
+      st.flexDirection = 'row';
+    } else if (layout === 'grid') {
+      st.display = 'grid';
+    }
+    return st;
+  }, [background, padding, gap, layout]);
+
+  // Read-back surface for the Inspector's ArtboardKnobs panel — the SAME
+  // generic "custom HTML attributes" escape hatch dom-selection.ts already
+  // scrapes off the selected element (styleMapsFor → Selection.attrs), so the
+  // panel pre-fills current state with no new plumbing. React omits an
+  // attribute entirely when its value is `undefined`.
+  const readBackAttrs = {
+    'data-dc-fixed': fixed ? 'true' : undefined,
+    'data-dc-bg': background,
+    'data-dc-padding': typeof padding === 'number' ? String(padding) : undefined,
+    'data-dc-layout': layout,
+    'data-dc-gap': typeof gap === 'number' ? String(gap) : undefined,
+  };
+
   if (!ctx || !rect) {
     return (
-      <article className="dc-artboard" data-dc-screen={id} style={{ width, height }}>
+      <article
+        className="dc-artboard"
+        data-dc-screen={id}
+        ref={articleRef}
+        style={fixed ? { width, height } : { width, height: 'auto', minHeight: heightFloor }}
+        {...readBackAttrs}
+      >
         <header className="dc-artboard-label sku">{label}</header>
-        <div className="dc-artboard-body">{children}</div>
+        <div className="dc-artboard-body" style={bodyStyle}>
+          {children}
+        </div>
       </article>
     );
   }
@@ -1850,11 +2013,16 @@ export function DCArtboard({
         className={`dc-artboard dc-positioned${isInDrag ? ' dc-dragging' : ''}`}
         data-dc-screen={id}
         aria-current={isActive ? 'true' : undefined}
+        ref={articleRef}
+        {...readBackAttrs}
         style={{
           left: liveX,
           top: liveY,
           width: rect.w,
-          height: rect.h,
+          // Hug default: height:auto + minHeight floor, content dictates the
+          // box; the ResizeObserver above mirrors the settled size back into
+          // rect.h for other consumers. Fixed: today's exact-height behavior.
+          ...(fixed ? { height: rect.h } : { height: 'auto', minHeight: heightFloor }),
           // Off-screen artboards skip layout+paint. On a large multi-board
           // canvas (e.g. an 18-board moodboard) every board otherwise paints
           // onto one huge .dc-world plane whose device-pixel size exceeds
@@ -1872,7 +2040,36 @@ export function DCArtboard({
         <button type="button" className="dc-artboard-label sku" aria-label={`Artboard ${label}`}>
           {label}
         </button>
-        <div className="dc-artboard-body">{children}</div>
+        {hasVideo ? (
+          <button
+            type="button"
+            className="dc-artboard-video-badge"
+            aria-label={`Open timeline — ${label}`}
+            title="Video artboard — open timeline"
+            onClick={openTimeline}
+          >
+            <svg viewBox="0 0 16 16" width="12" height="12" fill="none" aria-hidden="true">
+              <rect
+                x="1.5"
+                y="4.5"
+                width="8"
+                height="7"
+                rx="1.2"
+                stroke="currentColor"
+                strokeWidth="1.3"
+              />
+              <path
+                d="M9.5 7l4-2.3v6.6l-4-2.3"
+                stroke="currentColor"
+                strokeWidth="1.3"
+                strokeLinejoin="round"
+              />
+            </svg>
+          </button>
+        ) : null}
+        <div className="dc-artboard-body" style={bodyStyle}>
+          {children}
+        </div>
       </article>
       {showActivity ? (
         <ArtboardActivityOverlay
@@ -2136,6 +2333,436 @@ export function DrawProof({
 }
 DrawProof.displayName = 'DrawProof';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// PhotoLayer (feature-photo-editor, Task 6) — the non-destructive WebGL photo
+// compositor surface. Renders a source photo (artboard `<img>` or annotation
+// `ImageStroke`) with a live `PhotoEdit` applied through pixi.js.
+//
+// LAZY-BUNDLE GUARANTEE (the plan's load-bearing acceptance criterion + BUILDER's
+// flagged top risk): an UNEDITED photo (`isDefaultEdit(edit)`) renders as the
+// plain `<img>` and NEVER touches pixi. The compositor module (photo/pipeline.ts)
+// is only reached through a DYNAMIC `import()` inside the effect, so a canvas
+// with zero edited photos pays zero pixi.js/bg-removal cost. Verified empirically
+// against `buildCanvasModule` (no eager `pixi.js` import in the default-edit
+// bundle) — see test/photo-canvas-bundle.test.ts.
+//
+// A11y: the pixi output is a `<canvas>` (a black box to AT), so it carries
+// `role="img"` + `aria-label` from `alt` (validation step 7 requirement).
+// Reduced-motion: the compositor renders statically (autoStart:false, no ticker).
+
+export interface PhotoLayerProps {
+  /** Relative `assets/<sha8>.<ext>` source (validated upstream). */
+  source: string;
+  /** Live non-destructive edit. Absent / neutral ⇒ plain `<img>`, no pixi. */
+  edit?: PhotoEdit | null;
+  width: number;
+  height: number;
+  alt?: string;
+  className?: string;
+  style?: CSSProperties;
+  /** Resolve a relative asset path to a fetchable URL (defaults to identity —
+   *  relative `assets/…` already resolves against the canvas iframe origin). */
+  resolveUrl?: (rel: string) => string;
+  /** Fired once the pixi compositor has mounted + drawn its first frame. The
+   *  preview bridge hides the original element only AFTER this, so a background
+   *  cutout never flashes the untouched original underneath (and no flicker). */
+  onReady?: () => void;
+}
+
+export function PhotoLayer({
+  source,
+  edit,
+  width,
+  height,
+  alt = '',
+  className,
+  style,
+  resolveUrl,
+  onReady,
+}: PhotoLayerProps) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const rendererRef = useRef<{ destroy(): void; update(e: PhotoEdit): void } | null>(null);
+  const active = !isDefaultEdit(edit);
+
+  // Mount / tear down the pixi compositor only while an edit is active. The
+  // compositor is DYNAMICALLY imported (lazy-bundle guarantee — see header).
+  // Re-created only when the source/box identity changes; edit-param changes are
+  // pushed via the second effect below (no teardown → smooth live scrub).
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `edit` is deliberately excluded — re-creating the pixi Application on every scrub would thrash; edit updates flow through the second effect's `update()` (mount seeds from the current edit).
+  useEffect(() => {
+    if (!active) return;
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    let disposed = false;
+    import('./photo/pipeline.ts')
+      .then(({ PhotoRenderer }) =>
+        PhotoRenderer.create({
+          canvas,
+          source,
+          edit: (edit ?? {}) as PhotoEdit,
+          width,
+          height,
+          resolveUrl,
+        })
+      )
+      .then((r) => {
+        if (disposed) {
+          r.destroy();
+          return;
+        }
+        rendererRef.current = r;
+        onReady?.();
+      })
+      .catch((err) => {
+        console.error('[PhotoLayer] compositor failed to mount', err);
+      });
+    return () => {
+      disposed = true;
+      rendererRef.current?.destroy();
+      rendererRef.current = null;
+    };
+  }, [active, source, width, height, resolveUrl, onReady]);
+
+  // Live-update the mounted compositor on edit-param change (no re-create).
+  useEffect(() => {
+    if (active && edit && rendererRef.current) rendererRef.current.update(edit);
+  }, [edit, active]);
+
+  if (!active) {
+    const src = resolveUrl ? resolveUrl(source) : source;
+    return (
+      <img src={src} width={width} height={height} alt={alt} className={className} style={style} />
+    );
+  }
+  return (
+    <canvas
+      ref={canvasRef}
+      width={width}
+      height={height}
+      role="img"
+      aria-label={alt || 'Edited photo'}
+      className={className}
+      style={{ width, height, display: 'block', ...style }}
+    />
+  );
+}
+PhotoLayer.displayName = 'PhotoLayer';
+
+// PhotoPreviewBridge (feature-photo-editor) — applies a live/persisted
+// PhotoEdit DIRECTLY to the real photo element (artboard `<img>` or
+// annotation `<image>`) by swapping its `src`/`href` to a baked data URL,
+// instead of floating a separate WebGL-rendered decoy on top of it.
+//
+// Iteration 1 of this bridge did the "decoy" version: a `position:fixed` div
+// tracked the real element's screen rect via a per-frame rAF loop and hid the
+// original underneath (`visibility:hidden`) while a live `<PhotoLayer>` pixi
+// canvas rendered on top. That broke every bit of free native DOM behavior
+// the real element used to have:
+//   - cmd+click / right-click hit-testing landed on whatever was BEHIND the
+//     now-invisible original (a hidden element isn't hit-testable), while the
+//     decoy was `pointer-events:none` so it couldn't take the click either —
+//     net result, nothing was clickable.
+//   - the decoy rendered at a STABLE "world" pixel size and was CSS-stretched
+//     to the live screen box on zoom; the stretch didn't reliably track the
+//     real box, so the visible photo grew/shrank relative to its own frame.
+//   - it needed its own z-index (originally 30 — drew over the context menu)
+//     instead of just sitting at the element's normal stacking position.
+//   - it only knew about an edit via the transient postMessage below, so any
+//     iframe remount (Cmd+R, HMR) reset it to nothing until a human reopened
+//     the Inspector and nudged a knob.
+// Swapping the REAL element's `src`/`href` sidesteps all of it: resize, zoom,
+// hit-testing, and stacking become the browser's native `<img>`/`<image>`
+// behavior, not a hand-rolled tracker. Non-destructive still holds — only the
+// LIVE DOM attribute is mutated, never the authored TSX/SVG source; the
+// on-disk `PhotoEdit` sidecar (`/_api/photo-edit`) stays the persisted source
+// of truth, re-applied by the hydration scan below on every canvas (re)mount.
+// The bake is at the source's NATIVE resolution (`renderPhotoDataUrl`), so
+// the result stays sharp across any later resize/zoom with no re-bake.
+
+/** `assets/<sha8>.<ext>` substring inside a `src`/`href`/`xlink:href`. */
+const ASSET_REF_RE = /assets\/[0-9a-f]{8}\.[a-z0-9]+/i;
+
+/** Matches a photo element by the `data-photo-asset` tag `apply()` stamps on
+ *  first touch, falling back to a literal src/href substring match for an
+ *  element this bridge hasn't touched yet. The tag is load-bearing: once
+ *  baked, the element's `src`/`href` is a `data:` URL that no longer contains
+ *  the original asset path, so the substring match alone would lose track of
+ *  it on the very next edit. */
+function findPhotoEl(asset: string): Element | null {
+  if (typeof document === 'undefined') return null;
+  // Scoped to img/image (not a bare `[data-photo-asset]` attribute selector) —
+  // the canvas iframe is untrusted content (DDR-054); an authored canvas could
+  // otherwise stamp the tag on an arbitrary element to redirect a bake.
+  for (const n of document.querySelectorAll('img[data-photo-asset], image[data-photo-asset]')) {
+    if (n.getAttribute('data-photo-asset') === asset) return n;
+  }
+  for (const n of document.querySelectorAll('img, image')) {
+    const src =
+      n.getAttribute('src') || n.getAttribute('href') || n.getAttribute('xlink:href') || '';
+    if (src.includes(asset)) return n;
+  }
+  return null;
+}
+
+function extractAssetRef(el: Element): string | null {
+  // Only trust `data-photo-asset` when it actually has the `assets/<sha8>.<ext>`
+  // shape — the tag is attacker-controllable (untrusted canvas content,
+  // DDR-054), and an unshaped value would otherwise ride unbounded into
+  // `_active.json`/the WS broadcast via inspect.ts's `enrich()`.
+  const tagged = el.getAttribute('data-photo-asset');
+  if (tagged && ASSET_REF_RE.test(tagged)) return tagged;
+  const ref =
+    el.getAttribute('src') || el.getAttribute('href') || el.getAttribute('xlink:href') || '';
+  return ref.match(ASSET_REF_RE)?.[0] ?? null;
+}
+
+function setPhotoElSrc(el: Element, url: string): void {
+  if (el.tagName.toLowerCase() === 'image') {
+    el.setAttribute(el.hasAttribute('xlink:href') ? 'xlink:href' : 'href', url);
+  } else {
+    el.setAttribute('src', url);
+  }
+}
+
+const BAKE_DEBOUNCE_MS = 80;
+
+export function PhotoPreviewBridge() {
+  // The ORIGINAL (unedited) src/href per asset, captured the first time this
+  // bridge touches that element — so turning an edit off restores exactly
+  // what the element pointed to, not a guess.
+  const originalRef = useRef<Map<string, string>>(new Map());
+  // Per-asset bake generation — guards a slow (or out-of-order) render from
+  // clobbering a NEWER edit that already resolved first.
+  const tokenRef = useRef<Map<string, number>>(new Map());
+  const bakeTimers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+
+  const bake = useCallback((asset: string, original: string, edit: PhotoEdit) => {
+    const token = (tokenRef.current.get(asset) ?? 0) + 1;
+    tokenRef.current.set(asset, token);
+    import('./photo/pipeline.ts')
+      .then(({ renderPhotoDataUrl }) => renderPhotoDataUrl({ source: original, edit }))
+      .then((dataUrl) => {
+        if (tokenRef.current.get(asset) !== token) return; // superseded by a newer edit
+        const live = findPhotoEl(asset);
+        if (live) setPhotoElSrc(live, dataUrl);
+      })
+      .catch((err) => {
+        console.error('[PhotoPreviewBridge] bake failed', err);
+      });
+  }, []);
+
+  const apply = useCallback(
+    (asset: string, edit: PhotoEdit | null) => {
+      const el = findPhotoEl(asset);
+      if (!el) return;
+      if (!el.hasAttribute('data-photo-asset')) el.setAttribute('data-photo-asset', asset);
+      if (!originalRef.current.has(asset)) {
+        const orig =
+          el.getAttribute('src') || el.getAttribute('href') || el.getAttribute('xlink:href') || '';
+        originalRef.current.set(asset, orig);
+      }
+      const original = originalRef.current.get(asset) ?? '';
+      const timers = bakeTimers.current;
+      clearTimeout(timers.get(asset));
+      if (!edit || isDefaultEdit(edit)) {
+        timers.delete(asset);
+        setPhotoElSrc(el, original);
+        return;
+      }
+      timers.set(
+        asset,
+        setTimeout(() => bake(asset, original, edit), BAKE_DEBOUNCE_MS)
+      );
+    },
+    [bake]
+  );
+
+  useEffect(() => {
+    const timers = bakeTimers.current;
+    return () => {
+      for (const t of timers.values()) clearTimeout(t);
+    };
+  }, []);
+
+  useEffect(() => {
+    const onMsg = (e: MessageEvent) => {
+      const m = e.data as { dgn?: string; asset?: unknown; edit?: unknown; busy?: unknown } | null;
+      if (!m) return;
+      // Background-removal busy shimmer (Task 12 reveal) — a `data-photo-busy`
+      // attribute toggle on the real element, styled by inspect.ts's single CSS
+      // injection point (mirrors `.dc-activity-scan`'s sweep language). No
+      // separate tracked overlay — see the header comment above `apply()`.
+      // `m.asset` must pass the same shape check `extractAssetRef` applies
+      // elsewhere in this file (fix-photo-editor-followup-debt, Task 8) —
+      // an empty string previously matched EVERY photo element via
+      // `findPhotoEl`'s substring-match fallback (`src.includes('')` is always
+      // true), so an empty/malformed `asset` is now a no-op instead of toggling
+      // the busy shimmer on every photo on the canvas.
+      if (m.dgn === 'photo-busy' && typeof m.asset === 'string' && ASSET_REF_RE.test(m.asset)) {
+        const el = findPhotoEl(m.asset);
+        el?.toggleAttribute('data-photo-busy', !!m.busy);
+        return;
+      }
+      if (m.dgn !== 'photo-preview' || typeof m.asset !== 'string') return;
+      const asset = m.asset;
+      const edit = (m.edit ?? null) as PhotoEdit | null;
+      apply(asset, edit);
+    };
+    window.addEventListener('message', onMsg);
+    return () => window.removeEventListener('message', onMsg);
+  }, [apply]);
+  // Boot-time (+ ongoing) hydration from the PERSISTED sidecar, not just the
+  // live `photo-preview` message above. Without this, a saved PhotoEdit is
+  // invisible after anything that re-mounts the canvas doc (Cmd+R, an
+  // HMR remount, or a resize that recreates the photo's DOM node) — the
+  // message-only bridge starts every fresh mount with an empty `edits` map,
+  // and nothing re-sends the already-saved edit until a human happens to
+  // reopen the Inspector Photo tab and touch a knob. A MutationObserver
+  // re-scan (not just an initial one-shot) is what makes this self-heal after
+  // those remounts, since the photo element's DOM node is often a NEW node
+  // post-remount, not the one the original message targeted.
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    let cancelled = false;
+    let raf = 0;
+    // Every asset gets AT MOST one fetch attempt for this bridge's lifetime —
+    // without this, a canvas whose DOM keeps mutating (an animation, a
+    // re-rendering component) reissues the full unfetched set on every
+    // mutation frame, forever (security review finding: unbounded fetch
+    // amplification against the dev server from a zero-gesture background
+    // scan).
+    const attempted = new Set<string>();
+    // Safety ceiling per pass — a pathological/hostile canvas DOM (thousands
+    // of img/image elements) shouldn't be able to fan out unbounded fetches
+    // in one scan; the next mutation-triggered pass picks up where this left
+    // off since `attempted` persists across passes.
+    const MAX_SCAN_PER_PASS = 500;
+    const scan = () => {
+      let scanned = 0;
+      for (const n of document.querySelectorAll('img, image')) {
+        const asset = extractAssetRef(n);
+        if (!asset || attempted.has(asset)) continue;
+        if (++scanned > MAX_SCAN_PER_PASS) break;
+        attempted.add(asset);
+        fetch(`/_api/photo-edit?asset=${encodeURIComponent(asset)}`)
+          .then((r) => (r.ok ? r.json() : null))
+          .then((edit) => {
+            if (cancelled || !edit || isDefaultEdit(edit)) return;
+            apply(asset, edit);
+          })
+          .catch(() => {});
+      }
+    };
+    scan();
+    const observer = new MutationObserver(() => {
+      cancelAnimationFrame(raf);
+      raf = requestAnimationFrame(scan);
+    });
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['src', 'href'],
+    });
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(raf);
+      observer.disconnect();
+    };
+  }, [apply]);
+  return null; // mutates the real elements directly — no visible DOM of its own.
+}
+PhotoPreviewBridge.displayName = 'PhotoPreviewBridge';
+
+// PhotoBgRemoveHarness (feature-photo-editor, Task 18) — the headless CLI proof
+// harness `photo-bg-remove.sh` mounts inside a throwaway `_photo/<slug>.bgremove.tsx`
+// canvas (mirrors DrawProof's role for the draw engine). Runs the EXACT SAME
+// client-side ML flow the interactive "Remove Background" button uses (Task 12,
+// app.jsx `onPhotoRemoveBackground`) — @imgly/background-removal, WASM/WebGPU,
+// pixels never leave the browser — then persists the result and reports back to
+// the driving CLI script via DOM attributes it polls (no return value crosses
+// the process boundary; agent-browser reads attributes off the DOM instead).
+//
+// `/_api/asset` and `/_api/photo-edit` are BOTH canvas-safe routes (see their
+// CANVAS_SAFE_API comments in http.ts), so this harness posts directly from the
+// canvas origin — no main-origin relay / cross-origin workaround needed, despite
+// the split-origin (DDR-054) boundary the rest of the canvas runs inside.
+
+export interface PhotoBgRemoveHarnessProps {
+  /** Relative `assets/<sha8>.<ext>` source to remove the background from. */
+  source: string;
+}
+
+export function PhotoBgRemoveHarness({ source }: PhotoBgRemoveHarnessProps) {
+  const [status, setStatus] = useState<'pending' | 'done' | 'error'>('pending');
+  const [result, setResult] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const ranRef = useRef(false);
+
+  useEffect(() => {
+    if (ranRef.current) return; // one ML pass per mount — a dev-mode double-effect must not double-run it
+    ranRef.current = true;
+    let cancelled = false;
+    (async () => {
+      try {
+        const srcRes = await fetch(`/${source.replace(/^\/+/, '')}`);
+        if (!srcRes.ok) throw new Error(`source fetch failed: ${srcRes.status}`);
+        const srcBlob = await srcRes.blob();
+        const { removeBackground } = await import('@imgly/background-removal');
+        const matte = await removeBackground(srcBlob);
+        const up = await fetch('/_api/asset', {
+          method: 'POST',
+          headers: { 'content-type': matte.type || 'image/png' },
+          body: matte,
+        });
+        const upJson = (await up.json().catch(() => ({}))) as { path?: string };
+        if (!up.ok || !upJson.path) throw new Error(`asset upload failed: ${up.status}`);
+        const maskAsset = upJson.path;
+
+        // Merge onto whatever's already in the sidecar (mirrors photo-adjust.sh's
+        // merge-by-default behavior) instead of clobbering unrelated fields.
+        const base: unknown = await fetch(`/_api/photo-edit?asset=${encodeURIComponent(source)}`)
+          .then((r) => (r.ok ? r.json() : {}))
+          .catch(() => ({}));
+        const nextEdit = {
+          ...(base && typeof base === 'object' ? base : {}),
+          backgroundRemoved: { enabled: true, maskAsset },
+        };
+        const put = await fetch(`/_api/photo-edit?asset=${encodeURIComponent(source)}`, {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(nextEdit),
+        });
+        if (!put.ok) throw new Error(`photo-edit save failed: ${put.status}`);
+        if (cancelled) return;
+        setResult(maskAsset);
+        setStatus('done');
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : String(err));
+        setStatus('error');
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [source]);
+
+  return (
+    <div
+      data-photo-bgremove-status={status}
+      data-photo-bgremove-result={result ?? ''}
+      data-photo-bgremove-error={error ?? ''}
+      style={{ padding: 24, font: '13px monospace' }}
+    >
+      photo-bg-remove: {status}
+      {result ? ` → ${result}` : ''}
+      {error ? ` (${error})` : ''}
+    </div>
+  );
+}
+PhotoBgRemoveHarness.displayName = 'PhotoBgRemoveHarness';
+
 // ─────────────────────────────────────────────────────────────────────────────
 // SnapGuideOverlay (Phase 4.2) — renders 1 px guide lines while a drag is in
 // flight. Mounted by canvas-shell as a chrome layer outside `.dc-world`, so