@1agh/maude 0.41.0 → 0.43.0

package/apps/studio/test/photo-canvas-bundle.test.ts

@@ -0,0 +1,61 @@
+// photo-canvas-bundle.test.ts — the automated guard for the lazy-bundle
+// acceptance criterion + BUILDER's flagged top risk (feature-photo-editor).
+//
+// A canvas that uses <PhotoLayer> with a NEUTRAL edit must pay ZERO pixi.js cost:
+// the ~500 KB pixi runtime must stay behind a LAZY runtime `import("pixi.js")`,
+// never an eager top-level `import ... from "pixi.js"`. Canvas builds run with
+// `splitting: false`, so this is fragile — a future refactor that turns the
+// compositor's pixi import back into a static import (or statically imports
+// pipeline.ts from canvas-lib) would silently re-break it. This test bundles a
+// real canvas via the actual dev-server pipeline and inspects the output.
+
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { buildCanvasModule } from '../canvas-build.ts';
+
+const CANVAS = `
+import { DesignCanvas, DCArtboard, PhotoLayer } from '@maude/canvas-lib';
+export default function C() {
+  return (
+    <DesignCanvas>
+      <DCArtboard id="a" width={200} height={200}>
+        <PhotoLayer source="assets/aaaa1111.png" edit={{}} width={120} height={120} alt="photo" />
+      </DCArtboard>
+    </DesignCanvas>
+  );
+}
+`;
+
+async function buildCanvas(source: string): Promise<string> {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-photo-bundle-'));
+  const abs = join(dir, 'probe.tsx');
+  writeFileSync(abs, source);
+  try {
+    const { js } = await buildCanvasModule(abs, source, {});
+    return js;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe('lazy-bundle guarantee — <PhotoLayer> keeps pixi out of the eager graph', () => {
+  test('an unedited PhotoLayer canvas has NO eager `from "pixi.js"` import', async () => {
+    const js = await buildCanvas(CANVAS);
+    const eager = [...js.matchAll(/import\s[^;]*?from\s*["']pixi\.js["']/g)];
+    expect(eager.length).toBe(0);
+  });
+
+  test('pixi is reachable only via a lazy runtime import("pixi.js")', async () => {
+    const js = await buildCanvas(CANVAS);
+    expect(/import\(\s*["']pixi\.js["']\s*\)/.test(js)).toBe(true);
+  });
+
+  test('the canvas still bundles PhotoLayer itself (sanity — the import resolved)', async () => {
+    const js = await buildCanvas(CANVAS);
+    // isDefaultEdit is the schema helper <PhotoLayer> calls on the render path.
+    expect(js.includes('isDefaultEdit') || js.includes('PhotoLayer')).toBe(true);
+  });
+});

package/apps/studio/test/photo-edit-api.test.ts

@@ -0,0 +1,201 @@
+// photo-edit-api.test.ts — the /_api/photo-edit route + photo-store cap stack
+// (feature-photo-editor, Task 23; pairs with Stage C). Mirrors asset-api.test.ts
+// (real-server round-trip) + canvas-origin-gate.test.ts (dual-allowlist proof).
+//
+// Coverage per the plan: schema validation rejects malformed PhotoEdit JSON, the
+// size cap is enforced, path containment holds against a crafted `asset` param,
+// GET/PUT both work, and the route's presence in BOTH allowlists is asserted
+// (reachable + method-gated from the segregated canvas origin — the DDR-088
+// one-list-only 404 bug this test exists to prevent).
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { assetSha8 } from '../photo-store.ts';
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+const VALID_SHA = 'ab12cd34ef56';
+const VALID_ASSET = `assets/${VALID_SHA}.png`;
+
+// ── Pure: sha8 extraction is the primary traversal defense ───────────────────
+describe('assetSha8 — extraction + traversal rejection (pure)', () => {
+  test('accepts the forms a caller might hold', () => {
+    expect(assetSha8(VALID_ASSET)).toBe(VALID_SHA);
+    expect(assetSha8(`/assets/${VALID_SHA}.png`)).toBe(VALID_SHA);
+    expect(assetSha8(`${VALID_SHA}.jpg`)).toBe(VALID_SHA);
+    expect(assetSha8(VALID_SHA)).toBe(VALID_SHA);
+  });
+  test('rejects traversal / non-hex / empty', () => {
+    for (const bad of [
+      null,
+      undefined,
+      '',
+      '../../etc/passwd',
+      'assets/../../secret',
+      'assets/..%2f..%2fx', // query-decoded to `../../x` before we see it
+      '/etc/passwd',
+      'not-hex-zzz',
+      'ab12cd34/../x',
+      '../ab12cd34',
+    ]) {
+      expect(assetSha8(bad)).toBeNull();
+    }
+  });
+});
+
+// ── Real-server round-trip ───────────────────────────────────────────────────
+async function withServer(
+  fn: (port: number, designRoot: string) => Promise<void>,
+  extraEnv?: Record<string, string>
+) {
+  const sandbox = makeSandbox();
+  const port = nextPort();
+  const proc = await bootServer(sandbox.root, port, extraEnv);
+  try {
+    await fn(port, sandbox.designRoot);
+  } finally {
+    await killProc(proc);
+  }
+}
+
+const put = (port: number, asset: string, body: unknown) =>
+  fetch(`http://localhost:${port}/_api/photo-edit?asset=${encodeURIComponent(asset)}`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+const get = (port: number, asset: string) =>
+  fetch(`http://localhost:${port}/_api/photo-edit?asset=${encodeURIComponent(asset)}`);
+
+describe('/_api/photo-edit — GET/PUT round-trip + cap stack (main origin)', () => {
+  test('PUT a valid edit persists it; GET reads it back; sidecar lands on disk', async () => {
+    await withServer(async (port, designRoot) => {
+      const edit = {
+        adjustments: { contrast: 0.3, brightness: -0.1 },
+        duotone: { enabled: true, colorA: '#1a1a2e', colorB: '#e94560', intensity: 0.8 },
+      };
+      const res = await put(port, VALID_ASSET, edit);
+      expect(res.status).toBe(200);
+      const j = await res.json();
+      expect(j.ok).toBe(true);
+      expect(j.path).toBe(`assets/${VALID_SHA}.photo.json`);
+      expect(j.edit.version).toBe(1); // stamped on write
+
+      // GET round-trips the same params.
+      const got = await (await get(port, VALID_ASSET)).json();
+      expect(got.adjustments.contrast).toBe(0.3);
+      expect(got.duotone.colorB).toBe('#e94560');
+
+      // The sidecar actually exists at the content-addressed path.
+      const disk = join(designRoot, 'assets', `${VALID_SHA}.photo.json`);
+      expect(existsSync(disk)).toBe(true);
+      expect(JSON.parse(readFileSync(disk, 'utf8')).version).toBe(1);
+    });
+  });
+
+  test('GET of an unedited asset returns {}', async () => {
+    await withServer(async (port) => {
+      const got = await (await get(port, 'assets/00ff00ff.png')).json();
+      expect(got).toEqual({});
+    });
+  });
+
+  test('PUT malformed JSON is rejected (unknown key / bad type / out-of-range)', async () => {
+    await withServer(async (port) => {
+      expect((await put(port, VALID_ASSET, { bogusKey: 1 })).status).toBe(400);
+      expect((await put(port, VALID_ASSET, { adjustments: { contrast: 'high' } })).status).toBe(
+        400
+      );
+      expect((await put(port, VALID_ASSET, { adjustments: { contrast: 5 } })).status).toBe(400);
+      expect((await put(port, VALID_ASSET, { duotone: { colorA: 'red' } })).status).toBe(400);
+      // A crafted non-relative asset path in the body is rejected too.
+      expect((await put(port, VALID_ASSET, { source: '/etc/passwd' })).status).toBe(400);
+    });
+  });
+
+  test('PUT with a crafted asset param (traversal) is rejected 400', async () => {
+    await withServer(async (port) => {
+      expect((await put(port, '../../etc/passwd', { adjustments: { contrast: 0.1 } })).status).toBe(
+        400
+      );
+      expect((await get(port, 'assets/../../secret')).status).toBe(200); // GET → {} (null-safe), never leaks
+      const leaked = await (await get(port, 'assets/../../secret')).json();
+      expect(leaked).toEqual({});
+    });
+  });
+
+  test('PUT an oversized body is rejected (size cap)', async () => {
+    await withServer(async (port) => {
+      // `source` is a valid relative asset path with no length cap in the schema,
+      // so it's the field that can legally exceed the 64 KB byte cap. Sits just
+      // above the store cap but below the route's readJson ceiling.
+      const big = { source: `assets/${'a'.repeat(66000)}` };
+      const res = await put(port, VALID_ASSET, big);
+      expect(res.status).toBe(413);
+    });
+  });
+
+  test('method gate — DELETE is 405', async () => {
+    await withServer(async (port) => {
+      const res = await fetch(`http://localhost:${port}/_api/photo-edit?asset=${VALID_ASSET}`, {
+        method: 'DELETE',
+      });
+      expect(res.status).toBe(405);
+    });
+  });
+});
+
+// ── Dual-allowlist: reachable + method-gated from the canvas origin ──────────
+async function readCanvasOrigin(designRoot: string): Promise<string> {
+  for (let i = 0; i < 40; i++) {
+    try {
+      const info = JSON.parse(readFileSync(join(designRoot, '_server.json'), 'utf8'));
+      if (info.canvasOrigin) return info.canvasOrigin as string;
+    } catch {
+      /* not written yet */
+    }
+    await Bun.sleep(50);
+  }
+  throw new Error('canvasOrigin never appeared in _server.json');
+}
+
+describe('/_api/photo-edit — dual-allowlist (canvas origin reachable, DDR-088)', () => {
+  test('canvas origin: GET is reachable (200, not 404) and DELETE is method-gated (405)', async () => {
+    await withServer(
+      async (_port, designRoot) => {
+        const canvas = await readCanvasOrigin(designRoot);
+        // If the route were in CANVAS_SAFE_API only (missing from server.ts's
+        // `routes` map), Bun's fetch fall-through would serve it as a FILE → 404.
+        // 200 here proves the handler runs → it's in the server.ts routes map too.
+        const gRes = await fetch(`${canvas}/_api/photo-edit?asset=${VALID_ASSET}`, {
+          signal: AbortSignal.timeout(3000),
+        });
+        expect(gRes.status).toBe(200);
+        // DELETE reaches the handler (405), not the file fall-through (404).
+        const dRes = await fetch(`${canvas}/_api/photo-edit?asset=${VALID_ASSET}`, {
+          method: 'DELETE',
+          signal: AbortSignal.timeout(3000),
+        });
+        expect(dRes.status).toBe(405);
+      },
+      { MAUDE_CANVAS_ORIGIN_SPLIT: '1' }
+    );
+  });
+
+  test('canvas origin: PUT succeeds (no sameOriginWrite block — the headless harness needs this)', async () => {
+    await withServer(
+      async (_port, designRoot) => {
+        const canvas = await readCanvasOrigin(designRoot);
+        const res = await fetch(`${canvas}/_api/photo-edit?asset=${VALID_ASSET}`, {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ adjustments: { saturation: 0.5 } }),
+          signal: AbortSignal.timeout(3000),
+        });
+        expect(res.status).toBe(200);
+      },
+      { MAUDE_CANVAS_ORIGIN_SPLIT: '1' }
+    );
+  });
+});

package/apps/studio/test/photo-filters.test.ts

@@ -0,0 +1,149 @@
+// photo-filters.test.ts — Stage B, Task 4. Unit-tests the PURE pipeline planner
+// (`planPhotoPipeline`) — filter/step COUNT + ORDER + params, never pixel output
+// (pixel realization is browser-only, in pipeline.ts). No pixi import here: the
+// whole point of the planner split is that this suite runs headlessly.
+
+import { describe, expect, test } from 'bun:test';
+
+import type { PhotoPipelineStep } from '../photo/filters.ts';
+import { DUOTONE_FRAG_SOURCE, hexToRgb01, planPhotoPipeline } from '../photo/filters.ts';
+import type { PhotoEdit } from '../photo/schema.ts';
+import { PHOTO_PIPELINE_ORDER } from '../photo/schema.ts';
+
+const stages = (steps: PhotoPipelineStep[]) => steps.map((s) => s.stage);
+
+describe('planPhotoPipeline — neutrality', () => {
+  test('null / empty / all-neutral edits produce no steps', () => {
+    expect(planPhotoPipeline(null)).toEqual([]);
+    expect(planPhotoPipeline(undefined)).toEqual([]);
+    expect(planPhotoPipeline({})).toEqual([]);
+    expect(planPhotoPipeline({ adjustments: { brightness: 0, contrast: 0 } })).toEqual([]);
+    // Disabled sections never emit, regardless of their params.
+    expect(
+      planPhotoPipeline({
+        duotone: { enabled: false, colorA: '#000000', colorB: '#ffffff', intensity: 1 },
+        grain: { enabled: false, amount: 1 },
+        pattern: { enabled: false, opacity: 1 },
+        mask: { preset: 'none', strength: 1 },
+      })
+    ).toEqual([]);
+  });
+});
+
+describe('planPhotoPipeline — ordering', () => {
+  test('a fully-loaded edit emits every stage in PHOTO_PIPELINE_ORDER', () => {
+    const edit: PhotoEdit = {
+      // Deliberately author the object with keys OUT of pipeline order to prove
+      // the planner re-orders rather than echoing insertion order.
+      mask: { preset: 'vignette', strength: 0.5 },
+      pattern: { enabled: true, type: 'grid', scale: 2, opacity: 0.4, blend: 'multiply' },
+      grain: { enabled: true, amount: 0.3, size: 2 },
+      duotone: { enabled: true, colorA: '#1a1a2e', colorB: '#e94560', intensity: 0.8 },
+      adjustments: { contrast: 0.2, brightness: -0.1 },
+    };
+    const steps = planPhotoPipeline(edit);
+    expect(stages(steps)).toEqual([...PHOTO_PIPELINE_ORDER]);
+    // Exactly one step per stage.
+    expect(steps.length).toBe(5);
+  });
+
+  test('partial edits keep relative order and skip absent stages', () => {
+    const steps = planPhotoPipeline({
+      mask: { preset: 'edge-fade', strength: 0.7 },
+      adjustments: { hue: 40 },
+    });
+    expect(stages(steps)).toEqual(['adjustments', 'mask']);
+  });
+});
+
+describe('planPhotoPipeline — adjustments sub-order + params', () => {
+  test('color-matrix ops follow the fixed sub-order and carry normalized values', () => {
+    const steps = planPhotoPipeline({
+      // authored out of order:
+      adjustments: {
+        invert: 1,
+        brightness: 0.5,
+        hue: 90,
+        contrast: -0.3,
+        grayscale: 0.4,
+        saturation: 0.2,
+        sepia: 0.1,
+        exposure: 0.6,
+      },
+    });
+    expect(steps.length).toBe(1);
+    const adj = steps[0];
+    expect(adj.stage).toBe('adjustments');
+    if (adj.stage !== 'adjustments') throw new Error('unreachable');
+    expect(adj.ops.map((o) => o.op)).toEqual([
+      'brightness',
+      'exposure',
+      'contrast',
+      'saturation',
+      'hue',
+      'sepia',
+      'grayscale',
+      'invert',
+    ]);
+    // Values pass through untouched (normalization/mapping is a realizer concern).
+    const byOp = Object.fromEntries(adj.ops.map((o) => [o.op, o.value]));
+    expect(byOp.brightness).toBe(0.5);
+    expect(byOp.hue).toBe(90);
+    expect(byOp.contrast).toBe(-0.3);
+  });
+
+  test('only non-neutral adjustment fields become ops', () => {
+    const steps = planPhotoPipeline({
+      adjustments: { contrast: 0.5, brightness: 0, saturation: 0 },
+    });
+    const adj = steps[0];
+    if (adj.stage !== 'adjustments') throw new Error('expected adjustments');
+    expect(adj.ops.map((o) => o.op)).toEqual(['contrast']);
+  });
+});
+
+describe('planPhotoPipeline — section defaults when enabled-but-unset', () => {
+  test('enabled duotone/grain/pattern fill sensible defaults', () => {
+    const steps = planPhotoPipeline({
+      duotone: { enabled: true },
+      grain: { enabled: true },
+      pattern: { enabled: true },
+    });
+    const duo = steps.find((s) => s.stage === 'duotone');
+    const grain = steps.find((s) => s.stage === 'grain');
+    const pat = steps.find((s) => s.stage === 'pattern');
+    expect(duo).toBeTruthy();
+    expect(grain).toBeTruthy();
+    expect(pat).toBeTruthy();
+    if (duo?.stage === 'duotone') {
+      expect(duo.colorA).toMatch(/^#[0-9a-f]{6}$/);
+      expect(duo.colorB).toMatch(/^#[0-9a-f]{6}$/);
+      expect(duo.intensity).toBeGreaterThan(0);
+    }
+    if (pat?.stage === 'pattern') expect(pat.type).toBe('dots');
+  });
+});
+
+describe('hexToRgb01', () => {
+  test('parses to normalized rgb', () => {
+    expect(hexToRgb01('#000000')).toEqual([0, 0, 0]);
+    expect(hexToRgb01('#ffffff')).toEqual([1, 1, 1]);
+    const [r, g, b] = hexToRgb01('#804020');
+    expect(r).toBeCloseTo(128 / 255, 5);
+    expect(g).toBeCloseTo(64 / 255, 5);
+    expect(b).toBeCloseTo(32 / 255, 5);
+  });
+  test('throws on malformed input', () => {
+    expect(() => hexToRgb01('nope')).toThrow();
+    expect(() => hexToRgb01('#fff')).toThrow();
+  });
+});
+
+describe('duotone shader source', () => {
+  test('is a non-empty GLSL string with the expected uniforms', () => {
+    expect(DUOTONE_FRAG_SOURCE).toContain('uColorA');
+    expect(DUOTONE_FRAG_SOURCE).toContain('uColorB');
+    expect(DUOTONE_FRAG_SOURCE).toContain('uIntensity');
+    expect(DUOTONE_FRAG_SOURCE).toContain('uTexture');
+  });
+});

package/apps/studio/test/photo-pipeline.test.ts

@@ -0,0 +1,106 @@
+// photo-pipeline.test.ts — Stage B, Task 5. Exercises ONLY the pure decision
+// logic in pipeline.ts (`adjustmentCalls`, `resolveSourceUrl`, `needsCompositor`)
+// — no pixi filter is constructed, so this runs headlessly. The actual WebGL
+// render is verified via `maude design screenshot` (Task 6) + desktop dogfood
+// (Task 25). This suite ALSO proves importing pipeline.ts (which statically
+// imports pixi.js) does no construction at load time.
+
+import { describe, expect, test } from 'bun:test';
+
+import type { AdjustmentsStep } from '../photo/filters.ts';
+import { adjustmentCalls, needsCompositor, resolveSourceUrl } from '../photo/pipeline.ts';
+
+const adj = (ops: AdjustmentsStep['ops']): AdjustmentsStep => ({
+  stage: 'adjustments',
+  kind: 'colorMatrix',
+  ops,
+});
+
+describe('adjustmentCalls — normalized → pixi mapping + neutral references', () => {
+  test('brightness delta maps to pixi multiplier (neutral 1)', () => {
+    expect(adjustmentCalls(adj([{ op: 'brightness', value: 0 }]))[0]).toEqual({
+      method: 'brightness',
+      args: [1],
+    });
+    expect(adjustmentCalls(adj([{ op: 'brightness', value: 0.5 }]))[0].args).toEqual([1.5]);
+    expect(adjustmentCalls(adj([{ op: 'brightness', value: -1 }]))[0].args).toEqual([0]);
+  });
+
+  test('exposure maps to a 2^stop brightness', () => {
+    expect(adjustmentCalls(adj([{ op: 'exposure', value: 0 }]))[0]).toEqual({
+      method: 'brightness',
+      args: [1],
+    });
+    expect(adjustmentCalls(adj([{ op: 'exposure', value: 1 }]))[0].args).toEqual([2]);
+  });
+
+  test('contrast maps into pixi 0..1 with 0.5 neutral', () => {
+    expect(adjustmentCalls(adj([{ op: 'contrast', value: 0 }]))[0].args).toEqual([0.5]);
+    expect(adjustmentCalls(adj([{ op: 'contrast', value: 1 }]))[0].args).toEqual([1]);
+    expect(adjustmentCalls(adj([{ op: 'contrast', value: -1 }]))[0].args).toEqual([0]);
+  });
+
+  test('saturation and hue pass through', () => {
+    expect(adjustmentCalls(adj([{ op: 'saturation', value: -0.5 }]))[0]).toEqual({
+      method: 'saturate',
+      args: [-0.5],
+    });
+    expect(adjustmentCalls(adj([{ op: 'hue', value: 120 }]))[0]).toEqual({
+      method: 'hue',
+      args: [120],
+    });
+  });
+
+  test('sepia and invert become isolate-alpha toggles (amount honored)', () => {
+    const sepia = adjustmentCalls(adj([{ op: 'sepia', value: 0.7 }]))[0];
+    expect(sepia.method).toBe('sepia');
+    expect(sepia.args).toEqual([]);
+    expect(sepia.isolateAlpha).toBeCloseTo(0.7, 5);
+    const invert = adjustmentCalls(adj([{ op: 'invert', value: 1 }]))[0];
+    expect(invert.method).toBe('negative');
+    expect(invert.isolateAlpha).toBe(1);
+  });
+
+  test('order is preserved end-to-end', () => {
+    const calls = adjustmentCalls(
+      adj([
+        { op: 'brightness', value: 0.2 },
+        { op: 'contrast', value: 0.1 },
+        { op: 'sepia', value: 0.5 },
+        { op: 'invert', value: 0.3 },
+      ])
+    );
+    expect(calls.map((c) => c.method)).toEqual(['brightness', 'contrast', 'sepia', 'negative']);
+  });
+});
+
+describe('resolveSourceUrl — background-removal cutout replaces original', () => {
+  const SRC = 'assets/aaaa1111.jpg';
+  const MATTE = 'assets/bbbb2222.png';
+  test('unedited → original source', () => {
+    expect(resolveSourceUrl(null, SRC)).toBe(SRC);
+    expect(resolveSourceUrl({}, SRC)).toBe(SRC);
+  });
+  test('bg-removed enabled with a matte → the matte', () => {
+    expect(resolveSourceUrl({ backgroundRemoved: { enabled: true, maskAsset: MATTE } }, SRC)).toBe(
+      MATTE
+    );
+  });
+  test('bg-removed disabled OR no matte → original (non-destructive toggle)', () => {
+    expect(resolveSourceUrl({ backgroundRemoved: { enabled: false, maskAsset: MATTE } }, SRC)).toBe(
+      SRC
+    );
+    expect(resolveSourceUrl({ backgroundRemoved: { enabled: true } }, SRC)).toBe(SRC);
+  });
+});
+
+describe('needsCompositor — lazy-bundle gate', () => {
+  test('mirrors isDefaultEdit inverse', () => {
+    expect(needsCompositor(null)).toBe(false);
+    expect(needsCompositor({})).toBe(false);
+    expect(needsCompositor({ adjustments: { contrast: 0.4 } })).toBe(true);
+    expect(
+      needsCompositor({ backgroundRemoved: { enabled: true, maskAsset: 'assets/cc33.png' } })
+    ).toBe(true);
+  });
+});

package/apps/studio/test/photo-taxonomy.test.ts

@@ -0,0 +1,96 @@
+// photo-taxonomy.test.ts — regression guard for the DDR-115 "three lists must
+// agree" invariant, extended to the new `assets/<sha8>.photo.json` PhotoEdit
+// sidecar (feature-photo-editor, Task 3).
+//
+// The invariant: a VERSIONED path must be classified VERSIONED by ALL THREE
+// lists that encode the taxonomy —
+//   (1) apps/studio/git/service.ts  → `isMaudeRuntimeState` (panel backstop),
+//   (2) cli/lib/gitignore-block.mjs → `buildBlock` (the `maude init` template),
+//   (3) the repo root `.gitignore`  → tested via `git check-ignore` ground truth.
+// `assets/**` (binaries AND `.photo.json` sidecars) is VERSIONED, so none of the
+// three may hide it. This is the automated form of DDR-115 §3's manual claim.
+
+import { describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+
+import { buildBlock } from '../../../cli/lib/gitignore-block.mjs';
+import { __testing } from '../git/service.ts';
+
+const { isMaudeRuntimeState } = __testing;
+
+// Representative content-addressed paths under `assets/`.
+const PHOTO_SIDECAR_REL = 'assets/ab12cd34.photo.json';
+const PHOTO_SIDECAR_DESIGN = '.design/assets/ab12cd34.photo.json';
+const ASSET_BINARY_DESIGN = '.design/assets/ab12cd34.png';
+const MATTE_ASSET_DESIGN = '.design/assets/ff00aa99.png';
+
+describe('DDR-115 taxonomy — assets/<sha8>.photo.json is VERSIONED', () => {
+  test('isMaudeRuntimeState does NOT classify photo sidecars/assets as runtime', () => {
+    expect(isMaudeRuntimeState(PHOTO_SIDECAR_REL)).toBe(false);
+    expect(isMaudeRuntimeState(PHOTO_SIDECAR_DESIGN)).toBe(false);
+    expect(isMaudeRuntimeState(ASSET_BINARY_DESIGN)).toBe(false);
+    expect(isMaudeRuntimeState(MATTE_ASSET_DESIGN)).toBe(false);
+  });
+
+  // Positive control — proves the classifier's mechanism actually fires, so the
+  // negatives above aren't passing for a trivial reason (e.g. a broken regex).
+  test('isMaudeRuntimeState still classifies real runtime state as IGNORED', () => {
+    expect(isMaudeRuntimeState('.design/_server.json')).toBe(true);
+    expect(isMaudeRuntimeState('.design/_history/foo/bar.png')).toBe(true);
+    expect(isMaudeRuntimeState('.design/_canvas-state/x.view.json')).toBe(true);
+  });
+
+  // `_photo/` (Task 18/20's headless bg-remove proof canvases, mirroring
+  // `_draw/`'s draw-proof canvases) must agree as IGNORED across all three lists.
+  test('_photo/ (headless bg-remove proof canvases) is IGNORED across all three lists', () => {
+    expect(isMaudeRuntimeState('.design/_photo/smoke-tsx.bgremove.tsx')).toBe(true);
+
+    const block = buildBlock('.design');
+    expect(block).toContain('.design/_photo/');
+
+    const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+    if (top.status !== 0) {
+      console.warn('git rev-parse failed; skipping root .gitignore ground-truth check');
+      return;
+    }
+    const root = top.stdout.trim();
+    const r = spawnSync('git', ['check-ignore', '-q', '--', '.design/_photo/x.bgremove.tsx'], {
+      cwd: root,
+    });
+    expect(r.status).toBe(0);
+  });
+
+  test('the gitignore-block template ignores no assets/ path', () => {
+    for (const root of ['.design', 'design', 'mock']) {
+      const block = buildBlock(root);
+      // buildBlock only lists `${root}/_*` runtime prefixes — VERSIONED content
+      // (assets, canvases, meta) is deliberately absent. A future editor adding
+      // an `assets`/`.photo.json` ignore line trips this.
+      expect(block).not.toContain('assets');
+      expect(block).not.toContain('.photo.json');
+    }
+  });
+
+  test('root .gitignore (git check-ignore ground truth) does not ignore photo assets', () => {
+    const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+    if (top.status !== 0) {
+      // Not in a git checkout (unexpected in CI/dev) — skip rather than false-fail.
+      console.warn('git rev-parse failed; skipping root .gitignore ground-truth check');
+      return;
+    }
+    const root = top.stdout.trim();
+
+    const isIgnored = (relPath: string): boolean => {
+      const r = spawnSync('git', ['check-ignore', '-q', '--', relPath], { cwd: root });
+      // exit 0 = ignored, 1 = not ignored, other = error.
+      return r.status === 0;
+    };
+
+    // VERSIONED assets must NOT be ignored by the repo's own .gitignore.
+    expect(isIgnored(PHOTO_SIDECAR_DESIGN)).toBe(false);
+    expect(isIgnored(ASSET_BINARY_DESIGN)).toBe(false);
+
+    // Positive control — a known runtime path IS ignored, proving check-ignore works here.
+    expect(isIgnored('.design/_server.json')).toBe(true);
+  });
+});