@1agh/maude 0.42.0 → 0.43.0

package/apps/studio/photo/schema.ts

@@ -0,0 +1,367 @@
+/**
+ * @file       photo/schema.ts — PhotoEdit sidecar data model (Stage A, Task 1)
+ * @scope      apps/studio/photo/schema.ts
+ * @purpose    The single source of truth for the non-destructive photo-edit
+ *             object persisted next to a source asset as `assets/<sha8>.photo.json`
+ *             (DDR-115 taxonomy: VERSIONED, alongside the asset it edits).
+ *
+ *             A `PhotoEdit` is *parameters only* — never pixels. The live
+ *             compositor (`photo/pipeline.ts` → canvas-lib `<PhotoLayer>`) and
+ *             the headless CLI (`bin/photo-*.sh`) both read this shape and
+ *             reproduce the identical WebGL render. An absent sidecar, or one
+ *             that `isDefaultEdit()` reports as neutral, renders as the plain
+ *             untouched `<img>` / `<image>` with ZERO pixi.js cost.
+ *
+ * @invariant  DEPENDENCY-FREE. This module is imported by BOTH the server
+ *             (`photo-store.ts`, the `/_api/photo-edit` route) and the client
+ *             WebGL compositor. It MUST NOT `import 'pixi.js'` or any browser /
+ *             native lib — the server bundle must never pull in a WebGL runtime.
+ *             Pure TS types + plain-object helpers + a hand-rolled structural
+ *             validator (no Ajv) only.
+ *
+ *             Field naming/style mirrors `annotations-model.ts`'s flat explicit
+ *             per-type interfaces (`ImageStroke`, :245-260).
+ */
+
+/**
+ * Schema version. Bumped when the shape changes incompatibly so a stored
+ * sidecar authored by an older Studio can be detected + migrated rather than
+ * mis-rendered. (BREAKER's flagged risk: a new versioned data-model type needs
+ * an explicit version marker — this is it.)
+ */
+export const PHOTO_EDIT_VERSION = 1 as const;
+
+/** Pattern-overlay texture families (built via `PIXI.TilingSprite`, Task 4). */
+export type PatternType = 'dots' | 'grid' | 'lines' | 'diagonal' | 'crosshatch';
+export const PATTERN_TYPES: readonly PatternType[] = [
+  'dots',
+  'grid',
+  'lines',
+  'diagonal',
+  'crosshatch',
+];
+
+/** Blend modes the pattern overlay may composite with (pixi v8 BLEND_MODES subset). */
+export type PatternBlend = 'normal' | 'multiply' | 'screen' | 'overlay' | 'soft-light';
+export const PATTERN_BLENDS: readonly PatternBlend[] = [
+  'normal',
+  'multiply',
+  'screen',
+  'overlay',
+  'soft-light',
+];
+
+/** Preset alpha masks (built via `PIXI.Graphics`, Task 4). */
+export type MaskPreset = 'none' | 'vignette' | 'radial-reveal' | 'edge-fade';
+export const MASK_PRESETS: readonly MaskPreset[] = [
+  'none',
+  'vignette',
+  'radial-reveal',
+  'edge-fade',
+];
+
+/**
+ * Basic tonal adjustments. Every field is a NORMALIZED delta with a neutral
+ * origin so an all-zero object is a no-op (renders identical to the source):
+ *   - brightness / contrast / saturation / exposure: −1 … +1, 0 = neutral.
+ *   - hue: −180 … +180 degrees, 0 = neutral.
+ *   - sepia / grayscale / invert: 0 … 1 amount, 0 = off.
+ * `filters.ts` maps these onto `PIXI.ColorMatrixFilter`'s convenience methods.
+ */
+export interface PhotoAdjustments {
+  brightness?: number;
+  contrast?: number;
+  saturation?: number;
+  exposure?: number;
+  hue?: number;
+  sepia?: number;
+  grayscale?: number;
+  invert?: number;
+}
+
+/**
+ * Duotone remap — luminance → two-color gradient-map lerp. Needs a hand-authored
+ * GLSL fragment shader (`DuotoneFilter`, Task 4) because a two-point gradient map
+ * is a per-pixel remap that `ColorMatrixFilter`'s linear affine transform cannot
+ * express. `colorA`/`colorB` are `#rrggbb` hex (shadow → highlight).
+ */
+export interface PhotoDuotone {
+  enabled?: boolean;
+  colorA?: string;
+  colorB?: string;
+  /** 0 … 1 — crossfade between original and full duotone. */
+  intensity?: number;
+}
+
+/** Film grain via `PIXI.NoiseFilter`. `amount` 0…1, `size` a px grain scale ≥ 1. */
+export interface PhotoGrain {
+  enabled?: boolean;
+  amount?: number;
+  size?: number;
+}
+
+/** Repeating pattern overlay via `PIXI.TilingSprite` + blend mode. */
+export interface PhotoPattern {
+  enabled?: boolean;
+  type?: PatternType;
+  /** Tile scale multiplier (1 = native). */
+  scale?: number;
+  /** 0 … 1 overlay opacity. */
+  opacity?: number;
+  blend?: PatternBlend;
+  /** `#rrggbb` ink color the pattern is drawn in (default white). Load-bearing
+   *  for the blend modes: a WHITE pattern under `multiply` is a no-op (white ×
+   *  base = base) so the pattern "vanishes" — a dark color makes multiply darken. */
+  color?: string;
+}
+
+/** Preset alpha mask + its strength (0 … 1). */
+export interface PhotoMask {
+  preset?: MaskPreset;
+  strength?: number;
+}
+
+/**
+ * Non-destructive background removal. When `enabled`, `maskAsset` is the
+ * content-addressed `assets/<sha8>.png` cutout/alpha-matte produced client-side
+ * by `@imgly/background-removal` and uploaded through the existing
+ * `POST /_api/asset` route (Task 10). Turning `enabled` off restores the
+ * original — the matte asset is retained, never deleted.
+ */
+export interface PhotoBackgroundRemoved {
+  enabled?: boolean;
+  /** `assets/<sha8>.png` — absent until the removal has actually run. */
+  maskAsset?: string;
+}
+
+/**
+ * The full non-destructive edit for one source photo. Every field is optional;
+ * an empty object is a valid "unedited" sidecar. `source` is the
+ * `assets/<sha8>.<ext>` the edit applies to (redundant with the sidecar's own
+ * filename, but self-describing for the CLI + audit).
+ */
+export interface PhotoEdit {
+  /** Schema version of THIS object (defaults to PHOTO_EDIT_VERSION on write). */
+  version?: number;
+  /** `assets/<sha8>.<ext>` — the source the edit targets. */
+  source?: string;
+  adjustments?: PhotoAdjustments;
+  duotone?: PhotoDuotone;
+  grain?: PhotoGrain;
+  pattern?: PhotoPattern;
+  mask?: PhotoMask;
+  backgroundRemoved?: PhotoBackgroundRemoved;
+}
+
+/**
+ * Pipeline order is FIXED and load-bearing — filters are not commutative.
+ * `filters.ts` MUST build its graph in exactly this sequence. Exported so the
+ * compositor + tests share one source of truth.
+ */
+export const PHOTO_PIPELINE_ORDER = ['adjustments', 'duotone', 'grain', 'pattern', 'mask'] as const;
+
+const EPS = 1e-6;
+const near = (v: number | undefined, origin: number): boolean =>
+  v == null || Math.abs(v - origin) < EPS;
+
+/** True when the adjustments block has no visible effect. */
+function adjustmentsAreNeutral(a?: PhotoAdjustments): boolean {
+  if (!a) return true;
+  return (
+    near(a.brightness, 0) &&
+    near(a.contrast, 0) &&
+    near(a.saturation, 0) &&
+    near(a.exposure, 0) &&
+    near(a.hue, 0) &&
+    near(a.sepia, 0) &&
+    near(a.grayscale, 0) &&
+    near(a.invert, 0)
+  );
+}
+
+/**
+ * True when the edit produces a render identical to the untouched source, so
+ * `<PhotoLayer>` can skip mounting pixi.js entirely (the lazy-bundle guarantee).
+ * "Neutral" = every section either absent, disabled, or at its no-op value.
+ */
+export function isDefaultEdit(edit?: PhotoEdit | null): boolean {
+  if (!edit) return true;
+  if (!adjustmentsAreNeutral(edit.adjustments)) return false;
+  if (edit.duotone?.enabled && (edit.duotone.intensity ?? 1) > EPS) return false;
+  if (edit.grain?.enabled && (edit.grain.amount ?? 1) > EPS) return false;
+  if (edit.pattern?.enabled && (edit.pattern.opacity ?? 1) > EPS) return false;
+  if (edit.mask?.preset && edit.mask.preset !== 'none' && (edit.mask.strength ?? 1) > EPS)
+    return false;
+  if (edit.backgroundRemoved?.enabled && edit.backgroundRemoved.maskAsset) return false;
+  return true;
+}
+
+/** A fresh, fully-neutral edit for `source` (used when opening the Photo tab). */
+export function emptyPhotoEdit(source?: string): PhotoEdit {
+  return { version: PHOTO_EDIT_VERSION, ...(source ? { source } : {}) };
+}
+
+// ── Structural validation (dependency-free — no Ajv) ─────────────────────────
+// The `/_api/photo-edit` route (Task 8) validates untrusted JSON with this
+// before persisting. Reject anything unexpected: unknown top-level keys, wrong
+// types, out-of-range numbers, non-hex colors, non-relative asset paths. This
+// is a security surface (DDR-088) — a crafted field must not round-trip to disk.
+
+export interface ValidationResult {
+  ok: boolean;
+  errors: string[];
+}
+
+const HEX_RE = /^#[0-9a-fA-F]{6}$/;
+// Relative content-addressed asset path only — mirrors the annotation-layer
+// `<image>` href allowlist; NEVER a data:/blob:/absolute/traversing path.
+const ASSET_REL_RE = /^assets\/[0-9a-f]{8,}[A-Za-z0-9._-]*$/;
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+
+function num(errors: string[], obj: Record<string, unknown>, key: string, lo: number, hi: number) {
+  if (!(key in obj) || obj[key] == null) return;
+  const v = obj[key];
+  if (typeof v !== 'number' || !Number.isFinite(v)) {
+    errors.push(`${key}: must be a finite number`);
+    return;
+  }
+  if (v < lo || v > hi) errors.push(`${key}: ${v} out of range [${lo}, ${hi}]`);
+}
+
+function bool(errors: string[], obj: Record<string, unknown>, key: string) {
+  if (key in obj && obj[key] != null && typeof obj[key] !== 'boolean')
+    errors.push(`${key}: must be a boolean`);
+}
+
+function assertKeys(
+  errors: string[],
+  obj: Record<string, unknown>,
+  allowed: string[],
+  where: string
+) {
+  for (const k of Object.keys(obj))
+    if (!allowed.includes(k)) errors.push(`${where}: unknown key "${k}"`);
+}
+
+/**
+ * Structurally validate an untrusted value as a `PhotoEdit`. Returns collected
+ * errors (empty ⇒ valid). Unknown keys, wrong types, out-of-range numbers,
+ * malformed colors, and non-relative asset paths all fail.
+ */
+export function validatePhotoEdit(input: unknown): ValidationResult {
+  const errors: string[] = [];
+  if (!isPlainObject(input)) return { ok: false, errors: ['root: must be an object'] };
+
+  assertKeys(
+    errors,
+    input,
+    [
+      'version',
+      'source',
+      'adjustments',
+      'duotone',
+      'grain',
+      'pattern',
+      'mask',
+      'backgroundRemoved',
+    ],
+    'root'
+  );
+
+  if ('version' in input && input.version != null && typeof input.version !== 'number')
+    errors.push('version: must be a number');
+  if ('source' in input && input.source != null) {
+    if (typeof input.source !== 'string' || !ASSET_REL_RE.test(input.source))
+      errors.push('source: must be a relative assets/<sha8>.<ext> path');
+  }
+
+  if (input.adjustments != null) {
+    const a = input.adjustments;
+    if (!isPlainObject(a)) errors.push('adjustments: must be an object');
+    else {
+      assertKeys(
+        errors,
+        a,
+        ['brightness', 'contrast', 'saturation', 'exposure', 'hue', 'sepia', 'grayscale', 'invert'],
+        'adjustments'
+      );
+      num(errors, a, 'brightness', -1, 1);
+      num(errors, a, 'contrast', -1, 1);
+      num(errors, a, 'saturation', -1, 1);
+      num(errors, a, 'exposure', -1, 1);
+      num(errors, a, 'hue', -180, 180);
+      num(errors, a, 'sepia', 0, 1);
+      num(errors, a, 'grayscale', 0, 1);
+      num(errors, a, 'invert', 0, 1);
+    }
+  }
+
+  if (input.duotone != null) {
+    const d = input.duotone;
+    if (!isPlainObject(d)) errors.push('duotone: must be an object');
+    else {
+      assertKeys(errors, d, ['enabled', 'colorA', 'colorB', 'intensity'], 'duotone');
+      bool(errors, d, 'enabled');
+      for (const c of ['colorA', 'colorB'] as const)
+        if (c in d && d[c] != null && (typeof d[c] !== 'string' || !HEX_RE.test(d[c] as string)))
+          errors.push(`duotone.${c}: must be a #rrggbb hex color`);
+      num(errors, d, 'intensity', 0, 1);
+    }
+  }
+
+  if (input.grain != null) {
+    const g = input.grain;
+    if (!isPlainObject(g)) errors.push('grain: must be an object');
+    else {
+      assertKeys(errors, g, ['enabled', 'amount', 'size'], 'grain');
+      bool(errors, g, 'enabled');
+      num(errors, g, 'amount', 0, 1);
+      num(errors, g, 'size', 1, 32);
+    }
+  }
+
+  if (input.pattern != null) {
+    const p = input.pattern;
+    if (!isPlainObject(p)) errors.push('pattern: must be an object');
+    else {
+      assertKeys(errors, p, ['enabled', 'type', 'scale', 'opacity', 'blend', 'color'], 'pattern');
+      bool(errors, p, 'enabled');
+      if ('type' in p && p.type != null && !PATTERN_TYPES.includes(p.type as PatternType))
+        errors.push(`pattern.type: must be one of ${PATTERN_TYPES.join(', ')}`);
+      if ('blend' in p && p.blend != null && !PATTERN_BLENDS.includes(p.blend as PatternBlend))
+        errors.push(`pattern.blend: must be one of ${PATTERN_BLENDS.join(', ')}`);
+      if ('color' in p && p.color != null && (typeof p.color !== 'string' || !HEX_RE.test(p.color)))
+        errors.push('pattern.color: must be a #rrggbb hex color');
+      num(errors, p, 'scale', 0.1, 16);
+      num(errors, p, 'opacity', 0, 1);
+    }
+  }
+
+  if (input.mask != null) {
+    const m = input.mask;
+    if (!isPlainObject(m)) errors.push('mask: must be an object');
+    else {
+      assertKeys(errors, m, ['preset', 'strength'], 'mask');
+      if ('preset' in m && m.preset != null && !MASK_PRESETS.includes(m.preset as MaskPreset))
+        errors.push(`mask.preset: must be one of ${MASK_PRESETS.join(', ')}`);
+      num(errors, m, 'strength', 0, 1);
+    }
+  }
+
+  if (input.backgroundRemoved != null) {
+    const b = input.backgroundRemoved;
+    if (!isPlainObject(b)) errors.push('backgroundRemoved: must be an object');
+    else {
+      assertKeys(errors, b, ['enabled', 'maskAsset'], 'backgroundRemoved');
+      bool(errors, b, 'enabled');
+      if ('maskAsset' in b && b.maskAsset != null) {
+        if (typeof b.maskAsset !== 'string' || !ASSET_REL_RE.test(b.maskAsset))
+          errors.push('backgroundRemoved.maskAsset: must be a relative assets/<sha8>.png path');
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/apps/studio/photo-store.ts

@@ -0,0 +1,154 @@
+/**
+ * @file       photo-store.ts — PhotoEdit sidecar persistence (Stage C, Task 8)
+ * @scope      apps/studio/photo-store.ts
+ * @purpose    Read / write the non-destructive `assets/<sha8>.photo.json` sidecar
+ *             that backs the photo editor. Mirrors `inspect.ts`'s `createX(ctx)`
+ *             factory + `Bun.write`/`Bun.file` shape. Server-side only — imports
+ *             the DEPENDENCY-FREE `photo/schema.ts` (never `pixi.js`).
+ *
+ * @security   The `/_api/photo-edit` route is CANVAS-SAFE (reachable from the
+ *             untrusted canvas iframe — DDR-054), and its write PATH is derived
+ *             from an attacker-controllable `asset` param. Unlike `/_api/asset`
+ *             (content-addressed → path not attacker-chosen), this route's path
+ *             comes from the caller, so the DDR-088 cap stack is load-bearing:
+ *               1. strict sha8 extraction/validation (hex only, bounded length) —
+ *                  rejects `..`, `/`, `%2f`, absolute paths by construction;
+ *               2. explicit containment assert (belt-and-braces vs a poisoned
+ *                  designRoot — mirrors api.ts saveAssetFromStream);
+ *               3. structural `validatePhotoEdit` (unknown keys / bad types /
+ *                  out-of-range numbers / non-hex colors / non-relative asset
+ *                  paths all rejected — no crafted field round-trips to disk);
+ *               4. body/file size cap (64 KB — generous for parameters).
+ *             Threat-table (DDR-088): path-traversal → (1)+(2); stored-XSS via a
+ *             crafted field → (3), the JSON is only ever re-read by the schema-
+ *             typed compositor, never eval'd/HTML-injected; oversized-body DoS →
+ *             (4). No `sameOriginWrite` (would block the legit canvas origin, e.g.
+ *             the headless bg-remove harness) — `isLoopbackHost` on the route is
+ *             the DNS-rebinding guard. Residual (accepted, DDR-054 baseline): an
+ *             already-untrusted canvas can write a WELL-FORMED sidecar for any
+ *             sha8 — a low-severity integrity nuisance, bounded by (3), same class
+ *             as its existing ability to write arbitrary images via /_api/asset.
+ */
+
+import path from 'node:path';
+
+import type { Context } from './context.ts';
+import { PHOTO_EDIT_VERSION, type PhotoEdit, validatePhotoEdit } from './photo/schema.ts';
+
+/** Max bytes for a sidecar (read + write). Parameters are tiny; this is slack. */
+export const PHOTO_EDIT_MAX_BYTES = 64 * 1024;
+
+const SHA_RE = /^[0-9a-f]{8,64}$/;
+
+/**
+ * Extract + validate the content-address sha8 from an `asset` param. Accepts the
+ * source in any of the forms a caller might hold — `assets/<sha8>.<ext>`,
+ * `/assets/<sha8>.png`, `<sha8>.png`, or bare `<sha8>` — and returns the bare,
+ * validated sha8, or null if it isn't clean hex. The hex regex is the primary
+ * traversal defense: `..`, `/`, `%2f`, backslashes, and absolute paths can never
+ * match, so no path segment survives extraction.
+ */
+export function assetSha8(param: string | null | undefined): string | null {
+  if (typeof param !== 'string') return null;
+  let s = param.trim();
+  if (!s) return null;
+  s = s.replace(/^\/+/, ''); // drop leading slashes
+  s = s.replace(/^assets\//, ''); // drop the assets/ prefix
+  s = s.replace(/\.[A-Za-z0-9]+$/, ''); // drop a single trailing extension
+  return SHA_RE.test(s) ? s : null;
+}
+
+export interface PhotoStore {
+  /** Absolute path of the sidecar for a validated sha8 (throws if it escapes). */
+  editPathForSha8(sha8: string): string;
+  /** Read the sidecar → PhotoEdit, or null if absent / unreadable / oversized. */
+  getPhotoEdit(assetParam: string | null | undefined): Promise<PhotoEdit | null>;
+  /** Validate + persist. Returns a discriminated result (never throws on bad input). */
+  savePhotoEdit(
+    assetParam: string | null | undefined,
+    edit: unknown
+  ): Promise<
+    { ok: true; path: string; edit: PhotoEdit } | { ok: false; status: number; error: string }
+  >;
+}
+
+export function createPhotoStore(ctx: Context): PhotoStore {
+  const assetsDir = path.join(ctx.paths.designRoot, 'assets');
+
+  function editPathForSha8(sha8: string): string {
+    if (!SHA_RE.test(sha8)) throw new Error(`invalid sha8: ${sha8}`);
+    const abs = path.join(assetsDir, `${sha8}.photo.json`);
+    // Belt-and-braces containment (defense in depth vs a poisoned designRoot —
+    // sha8 is already validated hex, so this can only fail pathologically).
+    const rel = path.relative(assetsDir, abs);
+    if (rel !== `${sha8}.photo.json` || rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`photo-edit path escaped assets/: ${abs}`);
+    }
+    return abs;
+  }
+
+  async function getPhotoEdit(assetParam: string | null | undefined): Promise<PhotoEdit | null> {
+    const sha8 = assetSha8(assetParam);
+    if (!sha8) return null;
+    try {
+      const file = Bun.file(editPathForSha8(sha8));
+      if (!(await file.exists())) return null;
+      if (file.size > PHOTO_EDIT_MAX_BYTES) return null; // corrupt / oversized — ignore
+      const raw = await file.text();
+      const parsed = JSON.parse(raw);
+      // A stored sidecar is trusted-ish (we wrote it validated), but re-validate
+      // so a hand-edited / corrupt file never reaches the compositor malformed.
+      return validatePhotoEdit(parsed).ok ? (parsed as PhotoEdit) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function savePhotoEdit(
+    assetParam: string | null | undefined,
+    edit: unknown
+  ): Promise<
+    { ok: true; path: string; edit: PhotoEdit } | { ok: false; status: number; error: string }
+  > {
+    const sha8 = assetSha8(assetParam);
+    if (!sha8) return { ok: false, status: 400, error: 'invalid or missing asset (expected sha8)' };
+
+    // Size cap BEFORE validation (a giant blob shouldn't be walked field-by-field).
+    let serialized: string;
+    try {
+      serialized = JSON.stringify(edit ?? {});
+    } catch {
+      return { ok: false, status: 400, error: 'body is not serializable JSON' };
+    }
+    if (Buffer.byteLength(serialized, 'utf8') > PHOTO_EDIT_MAX_BYTES) {
+      return { ok: false, status: 413, error: `photo edit exceeds ${PHOTO_EDIT_MAX_BYTES} bytes` };
+    }
+
+    const check = validatePhotoEdit(edit);
+    if (!check.ok) {
+      return { ok: false, status: 400, error: `invalid PhotoEdit: ${check.errors.join('; ')}` };
+    }
+
+    // Stamp the schema version + canonical source on write (never trust the
+    // client's version claim; the sidecar's own filename is the source of truth).
+    const toWrite: PhotoEdit = {
+      ...(edit as PhotoEdit),
+      version: PHOTO_EDIT_VERSION,
+    };
+    let abs: string;
+    try {
+      abs = editPathForSha8(sha8);
+    } catch (e) {
+      return { ok: false, status: 400, error: e instanceof Error ? e.message : 'bad path' };
+    }
+    try {
+      // Bun.write creates the assets/ dir if absent.
+      await Bun.write(abs, JSON.stringify(toWrite, null, 2));
+    } catch (e) {
+      return { ok: false, status: 500, error: e instanceof Error ? e.message : 'write failed' };
+    }
+    return { ok: true, path: path.posix.join('assets', `${sha8}.photo.json`), edit: toWrite };
+  }
+
+  return { editPathForSha8, getPhotoEdit, savePhotoEdit };
+}

package/apps/studio/runtime-bundle.ts

@@ -47,12 +47,26 @@ export const RUNTIME_PACKAGES = [
   'react-dom/client',
   'react/jsx-runtime',
   'react/jsx-dev-runtime',
-  // Phase 4 — Pixi.js v8 available as a per-iframe runtime bundle. Lazy-built
-  // on first request; canvases that don't `import 'pixi.js'` never pay the
-  // ~500 KB bundle cost. Reserved for future snapshot-to-texture rendering
-  // (DDR-024 deferred path) and any high-end designer-tool overlays a canvas
-  // wants to draw via WebGL.
+  // Pixi.js v8 — per-iframe runtime bundle for the non-destructive photo editor
+  // (feature-photo-editor). The canvas-lib `<PhotoLayer>` reaches the WebGL
+  // compositor (`photo/pipeline.ts`) through a LAZY runtime `import('pixi.js')`,
+  // so a canvas with no edited photo never pays the ~500 KB bundle cost (the
+  // lazy-bundle guarantee — regression-tested in test/photo-canvas-bundle.test.ts).
+  // Pre-built into dist/runtime/pixi-js.js + floored in .min-sizes.json.
+  // (Originally parked by DDR-024 for snapshot-to-texture rendering; the photo
+  // editor is the first real activation — see the photo-editor architecture DDR.)
   'pixi.js',
+  // @imgly/background-removal (feature-photo-editor) — client-side ML background
+  // removal (WASM/WebGPU via onnxruntime-web, ZERO native deps; the Node/native
+  // `-node` variant is NEVER imported — bun-compile-hostile, DDR-070 sharp-class
+  // exclusion). Externalised for the same lazy per-iframe bundling as pixi: the
+  // bg-remove harness (PhotoBgRemoveHarness) reaches it through a runtime
+  // `import('@imgly/background-removal')`, so a canvas that never removes a
+  // background pays zero cost. Model weights (~11–44 MB isnet) are fetched at
+  // first use (IMG.LY CDN by default; `publicPath` self-hosts for air-gapped —
+  // a documented follow-up, see the photo-editor DDR). Pre-built into
+  // dist/runtime + floored in .min-sizes.json.
+  '@imgly/background-removal',
   // Phase 3.7 / DDR-049 — Motion One (motion/react) is the canonical motion
   // library for the canvas-lib + handoff pipeline. Externalised here so the
   // canvas-lib motion helpers (<MotionDemo>, etc.) resolve through the same
@@ -220,7 +234,16 @@ export async function getRuntimeBundle(
   // The `as any` cast tolerates names like `__INTERNAL_DO_NOT_USE_OR_WARN`
   // that aren't declared in the package's .d.ts; the destructure still
   // succeeds at runtime, which is what matters.
-  const entryContent = `import * as __mod__ from ${JSON.stringify(pkg)};\n${
+  // pixi.js compiles shaders with `new Function()` — which the split-origin
+  // canvas iframe's strict CSP (DDR-054) forbids (no `unsafe-eval`), so the
+  // photo compositor threw "Current environment does not allow unsafe-eval" and
+  // the live preview silently failed in the DEFAULT mode (only same-origin, the
+  // opt-out, had no CSP to trip). pixi ships `pixi.js/unsafe-eval` — a
+  // side-effect module that swaps the eval-based shader/uniform sync for
+  // eval-free polyfills. Baking it into the runtime bundle here makes EVERY
+  // canvas's `import('pixi.js')` CSP-safe transparently (feature-photo-editor).
+  const sideEffects = pkg === 'pixi.js' ? `import "pixi.js/unsafe-eval";\n` : '';
+  const entryContent = `${sideEffects}import * as __mod__ from ${JSON.stringify(pkg)};\n${
     exportNames.length > 0
       ? `const {\n${namedLines}\n} = __mod__ as any;\n` + `export {\n${namedLines}\n};\n`
       : ''

package/apps/studio/server.ts

@@ -242,12 +242,16 @@ function startCanvasServer(port: number): BunServer {
       '/_api/git-user': http.routes['/_api/git-user'],
       '/_api/canvas-meta': http.routes['/_api/canvas-meta'],
       '/_api/annotations': http.routes['/_api/annotations'],
-      // Phase 23 — capped binary image upload (magic-byte sniff + 10 MB +
+      // Phase 23 — capped binary image upload (magic-byte sniff + category cap +
       // content-addressed name + traversal guard + no-SVG, in api.saveAsset).
       // Bun matches `routes` BEFORE `fetch`, so the route must be listed here
       // explicitly — the CANVAS_SAFE_API entry alone only opens the fetch
       // fall-through (which serves files, not route handlers). See DDR (Task 9).
       '/_api/asset': http.routes['/_api/asset'],
+      // feature-photo-editor — PhotoEdit sidecar GET/PUT. MUST be here AND in
+      // CANVAS_SAFE_API (http.ts): Bun matches `routes` before `fetch`, so a
+      // one-list entry 404s from the canvas iframe (the DDR-088 rollout bug).
+      '/_api/photo-edit': http.routes['/_api/photo-edit'],
       '/_api/git-committers': http.routes['/_api/git-committers'],
       '/_api/ai': http.routes['/_api/ai'],
       '/_comments': http.routes['/_comments'],