@1agh/maude 0.58.1 → 0.58.3

package/apps/studio/test/cloud-renew.test.ts

@@ -0,0 +1,205 @@
+// Silent hub-credential renewal (cloud/renew.ts) — the lane that keeps a
+// cloud link alive past the 12 h cell-session cap without a person pressing
+// Connect again. Every network hop is injected; nothing here talks to a real
+// host.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { renewHubCredential } from '../cloud/renew.ts';
+
+const HUB_URL = 'https://alligators.cloud.test';
+
+let dir: string;
+let envBackup: Record<string, string | undefined>;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'maude-renew-'));
+  envBackup = {
+    MAUDE_CLOUD_CONFIG: process.env.MAUDE_CLOUD_CONFIG,
+    HUBS_CONFIG_PATH: process.env.HUBS_CONFIG_PATH,
+    MAUDE_CLOUD_URL: process.env.MAUDE_CLOUD_URL,
+  };
+  process.env.MAUDE_CLOUD_CONFIG = join(dir, 'cloud.json');
+  process.env.HUBS_CONFIG_PATH = join(dir, 'hubs.json');
+  process.env.MAUDE_CLOUD_URL = 'https://cloud.test';
+});
+
+afterEach(() => {
+  for (const [k, v] of Object.entries(envBackup)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function signIn(token = 'mpt_account'): void {
+  writeFileSync(
+    join(dir, 'cloud.json'),
+    JSON.stringify({ url: 'https://cloud.test', token, connectedAt: 1 })
+  );
+}
+
+function writeHubRecord(record: Record<string, unknown>): void {
+  writeFileSync(join(dir, 'hubs.json'), JSON.stringify({ hubs: { [HUB_URL]: record } }));
+}
+
+function readHubRecord(): Record<string, unknown> | undefined {
+  try {
+    return JSON.parse(readFileSync(join(dir, 'hubs.json'), 'utf8')).hubs[HUB_URL];
+  } catch {
+    return undefined;
+  }
+}
+
+/** Route-keyed fetch stub; records every URL it was asked for. */
+function fakeFetch(routes: Record<string, { status: number; body: unknown }>) {
+  const calls: string[] = [];
+  const doFetch = (async (input: string | URL | Request) => {
+    const url = String(input);
+    calls.push(url);
+    for (const [prefix, r] of Object.entries(routes)) {
+      if (url.startsWith(prefix)) {
+        return new Response(JSON.stringify(r.body), { status: r.status });
+      }
+    }
+    return new Response('{}', { status: 404 });
+  }) as typeof fetch;
+  return { doFetch, calls };
+}
+
+const HAPPY_ROUTES = {
+  'https://cloud.test/api/projects': {
+    status: 200,
+    body: { projects: [{ id: 'alligators', url: HUB_URL, role: 'owner' }] },
+  },
+  'https://cloud.test/projects/open': {
+    status: 200,
+    body: { token: 'proj_tok', url: HUB_URL, role: 'owner', expiresAt: 111 },
+  },
+  [`${HUB_URL}/auth/login`]: {
+    status: 200,
+    body: { token: 'mau_new', expiresAt: 12345, user: { email: 'm@x.cz', role: 'member' } },
+  },
+};
+
+describe('renewHubCredential', () => {
+  test('signed out → not-signed-in, and no network is touched', async () => {
+    const { doFetch, calls } = fakeFetch(HAPPY_ROUTES);
+    const r = await renewHubCredential(HUB_URL, doFetch);
+    expect(r).toEqual({ ok: false, reason: 'not-signed-in' });
+    expect(calls).toHaveLength(0);
+  });
+
+  test('happy path: projects → open → cell login → hubs.json updated, role preserved', async () => {
+    signIn();
+    writeHubRecord({ token: 'mau_stale', linkedAt: 1, role: 'member', expiresAt: 2 });
+    const { doFetch, calls } = fakeFetch(HAPPY_ROUTES);
+
+    const r = await renewHubCredential(HUB_URL, doFetch);
+    expect(r).toEqual({ ok: true, token: 'mau_new', expiresAt: 12345 });
+
+    const stored = readHubRecord();
+    expect(stored?.token).toBe('mau_new');
+    expect(stored?.expiresAt).toBe(12345);
+    // The upsert replaces the record — the vouched role must survive renewal.
+    expect(stored?.role).toBe('member');
+
+    // The cell login went to the STORED hub address, not anything the cloud named.
+    expect(calls[2]).toBe(`${HUB_URL}/auth/login`);
+  });
+
+  test('F5: the FRESH role from the cell login wins over the stale stored one', async () => {
+    signIn();
+    writeHubRecord({ token: 'mau_stale', linkedAt: 1, role: 'member' });
+    const { doFetch } = fakeFetch({
+      ...HAPPY_ROUTES,
+      [`${HUB_URL}/auth/login`]: {
+        status: 200,
+        body: { token: 'mau_new', expiresAt: 12345, user: { email: 'm@x.cz', role: 'owner' } },
+      },
+    });
+    const r = await renewHubCredential(HUB_URL, doFetch);
+    expect(r.ok).toBe(true);
+    expect(readHubRecord()?.role).toBe('owner'); // not the stale 'member'
+  });
+
+  test('F5: an older cell that omits the role falls back to the stored one', async () => {
+    signIn();
+    writeHubRecord({ token: 'mau_stale', linkedAt: 1, role: 'member' });
+    const { doFetch } = fakeFetch({
+      ...HAPPY_ROUTES,
+      [`${HUB_URL}/auth/login`]: { status: 200, body: { token: 'mau_new', expiresAt: 12345 } },
+    });
+    await renewHubCredential(HUB_URL, doFetch);
+    expect(readHubRecord()?.role).toBe('member');
+  });
+
+  test('claim-a: an embedded-credential hubUrl is refused, no network touched', async () => {
+    signIn();
+    const { doFetch, calls } = fakeFetch(HAPPY_ROUTES);
+    const r = await renewHubCredential('https://evil@alligators.cloud.test', doFetch);
+    expect(r).toEqual({ ok: false, reason: 'no-matching-project' });
+    expect(calls).toHaveLength(0);
+  });
+
+  test('account token revoked (401 on projects) → account-revoked, store untouched', async () => {
+    signIn();
+    writeHubRecord({ token: 'mau_stale', linkedAt: 1 });
+    const { doFetch } = fakeFetch({
+      'https://cloud.test/api/projects': { status: 401, body: {} },
+    });
+    const r = await renewHubCredential(HUB_URL, doFetch);
+    expect(r).toEqual({ ok: false, reason: 'account-revoked' });
+    expect(readHubRecord()?.token).toBe('mau_stale');
+  });
+
+  test('hub not among the account projects → no-matching-project', async () => {
+    signIn();
+    const { doFetch } = fakeFetch({
+      'https://cloud.test/api/projects': {
+        status: 200,
+        body: { projects: [{ id: 'other', url: 'https://other.cloud.test', role: 'owner' }] },
+      },
+    });
+    const r = await renewHubCredential(HUB_URL, doFetch);
+    expect(r).toEqual({ ok: false, reason: 'no-matching-project' });
+  });
+
+  test('a viewer role never renews an editor credential', async () => {
+    signIn();
+    const { doFetch } = fakeFetch({
+      'https://cloud.test/api/projects': {
+        status: 200,
+        body: { projects: [{ id: 'alligators', url: HUB_URL, role: 'viewer' }] },
+      },
+    });
+    const r = await renewHubCredential(HUB_URL, doFetch);
+    expect(r).toEqual({ ok: false, reason: 'no-matching-project' });
+  });
+
+  test('removed member: /projects/open refuses → open-refused (the right place to die)', async () => {
+    signIn();
+    const { doFetch } = fakeFetch({
+      'https://cloud.test/api/projects': HAPPY_ROUTES['https://cloud.test/api/projects'],
+      'https://cloud.test/projects/open': { status: 404, body: {} },
+    });
+    const r = await renewHubCredential(HUB_URL, doFetch);
+    expect(r).toEqual({ ok: false, reason: 'open-refused' });
+  });
+
+  test('cell refuses the exchange → cell-refused, store untouched', async () => {
+    signIn();
+    writeHubRecord({ token: 'mau_stale', linkedAt: 1 });
+    const { doFetch } = fakeFetch({
+      'https://cloud.test/api/projects': HAPPY_ROUTES['https://cloud.test/api/projects'],
+      'https://cloud.test/projects/open': HAPPY_ROUTES['https://cloud.test/projects/open'],
+      [`${HUB_URL}/auth/login`]: { status: 401, body: {} },
+    });
+    const r = await renewHubCredential(HUB_URL, doFetch);
+    expect(r).toEqual({ ok: false, reason: 'cell-refused' });
+    expect(readHubRecord()?.token).toBe('mau_stale');
+  });
+});

package/apps/studio/test/cloud-shell-surfaces.test.ts

@@ -36,11 +36,20 @@ const APP = readFileSync(join(STUDIO, 'client', 'app.jsx'), 'utf8');
 const SETTINGS = readFileSync(join(STUDIO, 'client', 'panels', 'SettingsPanel.jsx'), 'utf8');
 
 describe('the cloud shell offers nothing it cannot honour', () => {
-  test('the local-machine settings tabs are flagged, and only those three', () => {
+  test('the local-machine settings tabs are flagged — and the list is exact', () => {
+    // An exact list, not a `toContain`: the failure this guards is a tab that
+    // configures machine-local state shipping to the cloud shell UNFLAGGED,
+    // where its routes are refused by design (DDR-209 D1) and it renders as a
+    // wall of 404s. A new tab has to be classified deliberately, which means
+    // this assertion is SUPPOSED to fail when one is added.
+    //
+    // `figma` (DDR-216) is local-machine for the same reason `ai-generation`
+    // is: the credential lives in `~/.config/maude/keys.json` on this machine,
+    // and the import writes into this machine's design root.
     const flagged = [
       ...SETTINGS.matchAll(/\{ id: '([a-z-]+)', label: '[^']+', local: true \}/g),
     ].map((m) => m[1]);
-    expect(flagged.sort()).toEqual(['ai-generation', 'subtitles', 'video']);
+    expect(flagged.sort()).toEqual(['ai-generation', 'figma', 'subtitles', 'video']);
   });
 
   test('the tab rail renders the FILTERED list, not the raw table', () => {

package/apps/studio/test/comment-relay-origin-gate.test.ts

@@ -0,0 +1,117 @@
+// The shell's inbound-postMessage comment relays must stay scoped to the
+// ACTIVE canvas.
+//
+// Threat: the origin check at the top of app.jsx's `onMessage` compares against
+// the single shared `canvasOrigin`, so EVERY open canvas iframe passes it —
+// including ones in background tabs. `comment-submit` / `comment-patch` /
+// `comment-delete` relay straight onto the privileged WS, so without a
+// per-message `e.source === activeWin` gate a background canvas can write
+// comments onto a file it names itself, with no user gesture. That mattered
+// little while comments were an inert store; the ACP panel's one-click
+// "Implement N comments" action turns open comments into a feed the agent acts
+// on, which is what promoted the seam to worth-closing.
+//
+// This is a SOURCE-STRUCTURE test, not a behavioural one: `App()` is a
+// 14k-line component that cannot be mounted in isolation, and the twenty other
+// `e.source === activeWin` gates in the same handler have no coverage at all.
+// Asserting on the source keeps the guard cheap and honest about its reach —
+// it catches a gate being deleted, a `file:` pin regressing to the
+// caller-supplied value, and (the last test) a gate that is written but cannot
+// execute. It claims nothing beyond that: it does not prove the relay behaves
+// correctly, only that the control is present and reachable.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SRC = readFileSync(join(import.meta.dir, '..', 'client', 'app.jsx'), 'utf8');
+
+/** The body of one `else if (m.dgn === '<name>' …)` branch, up to the next one. */
+function branch(name: string): string {
+  const start = SRC.indexOf(`m.dgn === '${name}'`);
+  expect(start, `branch for ${name} not found in app.jsx`).toBeGreaterThan(-1);
+  const rest = SRC.slice(start + name.length);
+  const end = rest.indexOf('} else if (m.dgn ===');
+  return rest.slice(0, end === -1 ? 2000 : end);
+}
+
+describe('canvas → shell comment relays are scoped to the active canvas', () => {
+  // The comment relays, plus the three shell-control branches that were
+  // ungated alongside them: `shell-shortcut` (reload / panel toggles /
+  // Export + Handoff dialogs), and `open-export` / `open-timeline-request`,
+  // which reach the same dialogs from the in-canvas toolbar and context menu.
+  // All five are actions a user takes INSIDE the canvas in view; none has a
+  // reason to be honoured from a background frame.
+  for (const name of [
+    'comment-submit',
+    'comment-patch',
+    'comment-delete',
+    'shell-shortcut',
+    'open-export',
+    'open-timeline-request',
+  ]) {
+    test(`${name} is gated on e.source === activeWin`, () => {
+      expect(branch(name)).toContain('e.source === activeWin');
+    });
+  }
+
+  test('comment-submit pins the target file to activePath, never the payload', () => {
+    const body = branch('comment-submit');
+    // The file the comment lands on is the one the user is looking at.
+    expect(body).toContain('file: activePath');
+    // A canvas-supplied target would let a background iframe pick the victim.
+    expect(body).not.toContain('file: p.file');
+  });
+
+  test('comment-patch / comment-delete only accept ids owned by the active canvas', () => {
+    // A bare id would otherwise reach any comment in the project — and these
+    // two verbs change or remove somebody else's note (ws.ts refuses both for a
+    // viewer session for exactly that reason).
+    expect(branch('comment-patch')).toContain('ownsActiveComment(m.id)');
+    expect(branch('comment-delete')).toContain('ownsActiveComment(m.id)');
+  });
+
+  // The above only prove the gate is WRITTEN. This proves it can RUN.
+  //
+  // House style declares `const activeWin` block-locally inside each `else if`
+  // branch, so a branch that compares against `activeWin` without declaring it
+  // reads exactly like a working gate while throwing `ReferenceError` at
+  // runtime — fail-closed, but it takes the legitimate path down with it and
+  // silently reopens the moment anything introduces an outer binding. That is
+  // not hypothetical: the first cut of this fix shipped it, and every
+  // string-matching assertion above stayed green.
+  test('every activeWin comparison has a declaration, derived from activePath', () => {
+    // Line comments are blanked first — the prose in this handler quotes the
+    // gate expression, and a comment is not a use.
+    const CODE = SRC.split('\n')
+      .map((l) => l.replace(/^\s*\/\/.*$/, ''))
+      .join('\n');
+    const BRANCH_START = /\b(?:else )?if \(m\.dgn ===/g;
+    const starts = [...CODE.matchAll(BRANCH_START)].map((m) => m.index ?? 0);
+    const undeclared: string[] = [];
+
+    // Both idioms count: the `===` gate used by the comment relays and the
+    // `!== … return` early-exit form five other branches use. Checking only
+    // one lets a branch convert to the other and slip the check.
+    for (const use of [...CODE.matchAll(/e\.source [!=]== activeWin/g)].map((m) => m.index ?? 0)) {
+      // Nearest branch boundary at or before this usage.
+      const open = starts.filter((s) => s < use).pop() ?? 0;
+      // `= activePath` is the load-bearing half: a declaration that derives the
+      // window from the MESSAGE (`iframesRef.current.get(m.file)`) instead of
+      // from app state satisfies a bare `const activeWin` check while handing
+      // the attacker the very comparison the gate exists to make.
+      if (!/const activeWin =\s*\n?\s*activePath/.test(CODE.slice(open, use))) {
+        undeclared.push(
+          CODE.slice(open, open + 60)
+            .split('\n')[0]!
+            .trim()
+        );
+      }
+    }
+
+    expect(
+      undeclared,
+      `activeWin used without a block-local declaration in: ${undeclared.join(' | ')}`
+    ).toEqual([]);
+  });
+});

package/apps/studio/test/comments-fs-rebroadcast.test.ts

@@ -0,0 +1,155 @@
+// Issue #74 — `_comments/<slug>.json` written DIRECTLY on disk must reach
+// already-open shells over WS.
+//
+// This pins EXISTING behaviour rather than covering a fix. `/design:edit`
+// resolves comments with a plain jq-rewrite of the comments file (edit.md §3's
+// documented recipe), which bypasses api.commentsPatch and so never fires the
+// `onCommentsChanged` re-broadcast in server.ts. The broadcast happens anyway,
+// from collab/index.ts's `fs:any` re-seed ("the sidebar still needs the
+// 'comments' bus emit, so keep that unconditionally") — a non-obvious owner
+// that a reader of server.ts alone would conclude was missing.
+//
+// It is worth locking down because the chat panel's "Implement N comments"
+// quick action (issue #74) is built on it: the agent resolves comments by
+// direct write, and if that stopped reaching open shells the button would keep
+// counting comments that are already done, with nothing else failing.
+
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+const FILE = '.design/ui/Foo.tsx';
+const SLUG = 'ui-foo';
+
+async function openWs(port: number): Promise<WebSocket> {
+  const ws = new WebSocket(`ws://localhost:${port}/_ws`);
+  await new Promise<void>((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error('ws open timeout')), 2000);
+    ws.addEventListener('open', () => {
+      clearTimeout(t);
+      resolve();
+    });
+    ws.addEventListener('error', (e) => {
+      clearTimeout(t);
+      reject(e);
+    });
+  });
+  return ws;
+}
+
+/** Resolve on the first `comments` frame for `file`, or null after `ms`. */
+function nextCommentsFrame(
+  ws: WebSocket,
+  file: string,
+  ms = 5000
+): Promise<{ file: string; comments: Array<{ id: string; status: string }> } | null> {
+  return new Promise((resolve) => {
+    const done = (v: never | null) => {
+      clearTimeout(timer);
+      ws.removeEventListener('message', onMsg);
+      resolve(v);
+    };
+    const timer = setTimeout(() => done(null), ms);
+    const onMsg = (ev: MessageEvent) => {
+      try {
+        const m = JSON.parse(String(ev.data));
+        if (m && m.type === 'comments' && m.file === file) done(m);
+      } catch {
+        /* non-JSON frame — ignore */
+      }
+    };
+    ws.addEventListener('message', onMsg);
+  });
+}
+
+function seedCanvas(designRoot: string) {
+  mkdirSync(join(designRoot, 'ui'), { recursive: true });
+  writeFileSync(join(designRoot, 'ui', 'Foo.tsx'), 'export default function P(){return <main/>}\n');
+  mkdirSync(join(designRoot, '_comments'), { recursive: true });
+}
+
+function commentsJson(status: 'open' | 'resolved') {
+  return JSON.stringify(
+    [
+      {
+        id: 'c_one',
+        file: FILE,
+        selector: 'main',
+        dom_path: ['main'],
+        tag: 'main',
+        classes: '',
+        bounds: null,
+        html_excerpt: '',
+        text: 'tighten the padding',
+        status,
+        created: '2026-01-01T00:00:00.000Z',
+        resolved_at: status === 'resolved' ? '2026-01-02T00:00:00.000Z' : null,
+        author: 'Test User',
+        thread: [],
+        mentions: [],
+      },
+    ],
+    null,
+    2
+  );
+}
+
+describe('issue #74 — comments file-watch re-broadcast', () => {
+  test('a direct resolve-write broadcasts the updated list to open shells', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      seedCanvas(designRoot);
+      const commentsFile = join(designRoot, '_comments', `${SLUG}.json`);
+      writeFileSync(commentsFile, commentsJson('open'));
+
+      const ws = await openWs(port);
+      // Clear the fs-watch per-path debounce window (50 ms) so the resolve
+      // write below is seen as its own event rather than folded into the seed.
+      await Bun.sleep(150);
+
+      const frame = nextCommentsFrame(ws, FILE);
+      // Exactly what edit.md §3's resolve recipe does: rewrite the file in
+      // place, never touching the API.
+      writeFileSync(commentsFile, commentsJson('resolved'));
+
+      const got = await frame;
+      ws.close();
+
+      expect(got).not.toBeNull();
+      expect(got!.comments).toHaveLength(1);
+      expect(got!.comments[0]!.id).toBe('c_one');
+      expect(got!.comments[0]!.status).toBe('resolved');
+    } finally {
+      await killProc(proc);
+    }
+  }, 20000);
+
+  test('a comments file for an unknown slug is ignored, not fatal', async () => {
+    const { root, designRoot } = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      seedCanvas(designRoot);
+      const ws = await openWs(port);
+      await Bun.sleep(150);
+
+      // No canvas resolves to this slug — the handler must bail quietly and
+      // leave the server healthy.
+      writeFileSync(
+        join(designRoot, '_comments', 'ui-does-not-exist.json'),
+        JSON.stringify([], null, 2)
+      );
+      await Bun.sleep(400);
+      ws.close();
+
+      const health = await fetch(`http://localhost:${port}/_health`);
+      expect(health.ok).toBe(true);
+    } finally {
+      await killProc(proc);
+    }
+  }, 20000);
+});

package/apps/studio/test/exporters/degraded-propagation.test.ts

@@ -0,0 +1,123 @@
+// RCA issue-mp4-audio-export-html5audio-silent-degrade — the silence gate.
+//
+// The bug was not that the export degraded; degrading to a video-only capture
+// when the audio renderer refuses is DDR-157's deliberate design. The bug was
+// that the degradation reached nothing a human or an agent reads: `video.ts`
+// parsed the shim's `{degraded, audioDropped, fallbackReason}` summary, wrote ONE
+// console.error, and returned an ExportResult without it — so the job said
+// `done`, `_export-history.json` looked clean, `GET /_api/export-jobs` had no
+// field for it, and the Exports panel showed a success row. The user shipped a
+// muted file four times before anyone dug through the desktop app's stderr.
+//
+// The real regression gate for the artifact itself is an integration test that
+// exports a fixture comp and asserts an audio stream exists (RCA Testing
+// Requirements). That one needs a browser, and CI has none — so, matching the
+// house style of `export-shim-multi-capture.test.ts`, the propagation CHAIN is
+// guarded at the source-shape level here, plus a real unit test of the one piece
+// that is pure.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { hasAudioStream, remedyFor } from '../../exporters/degraded.ts';
+
+const STUDIO = join(import.meta.dir, '..', '..');
+const read = (rel: string) => readFileSync(join(STUDIO, rel), 'utf8');
+
+describe('remedyFor — a fixable cause must carry its one-line fix', () => {
+  test('names @remotion/media for the Html5Audio rejection', () => {
+    const reason =
+      'page.evaluate: Error: <Html5Audio> is not supported in @remotion/web-renderer. ' +
+      'Use <Audio> from @remotion/media instead.';
+    const remedy = remedyFor(reason);
+    expect(remedy).toBeDefined();
+    expect(remedy).toContain('@remotion/media');
+    // The remedy has to say what to STOP doing too, or it reads as advice
+    // rather than a diagnosis of this file.
+    expect(remedy).toContain('remotion');
+  });
+
+  test('names the Video swap for the OffthreadVideo rejection', () => {
+    const remedy = remedyFor('<OffthreadVideo> is not supported in @remotion/web-renderer');
+    expect(remedy).toBeDefined();
+    expect(remedy).toContain('@remotion/media');
+  });
+
+  test('returns nothing for a cause the author cannot fix by hand', () => {
+    // The DDR-157 recursion overflow is data-dependent and has no one-liner —
+    // inventing a remedy for it would be worse than silence.
+    expect(remedyFor('RangeError: Maximum call stack size exceeded')).toBeUndefined();
+  });
+});
+
+describe('hasAudioStream — the artifact has the last word', () => {
+  const bytes = (s: string) => new TextEncoder().encode(s);
+
+  test('mp4 with a `soun` handler counts as having audio', () => {
+    expect(hasAudioStream(bytes('....hdlrsoun....'), 'mp4')).toBe(true);
+  });
+
+  test('mp4 with only a video handler does not', () => {
+    expect(hasAudioStream(bytes('....hdlrvide....'), 'mp4')).toBe(false);
+  });
+
+  test('webm is recognised by its audio CodecID', () => {
+    expect(hasAudioStream(bytes('\x00\x00A_OPUS\x00'), 'webm')).toBe(true);
+    expect(hasAudioStream(bytes('\x00\x00V_VP9\x00'), 'webm')).toBe(false);
+  });
+
+  test('an unrecognised container is assumed fine — never invent a degradation', () => {
+    expect(hasAudioStream(bytes('anything'), 'mov')).toBe(true);
+  });
+
+  test('an empty body does not crash the check', () => {
+    expect(hasAudioStream(new Uint8Array(0), 'mp4')).toBe(false);
+  });
+});
+
+describe('degraded propagation chain (source-shape — the browser half runs manually)', () => {
+  test('video.ts returns the degradation instead of only logging it', () => {
+    const src = read('exporters/video.ts');
+    // The precise regression: a console.error with no accompanying assignment.
+    expect(src).toContain('degraded = {');
+    expect(src).toMatch(/audioDropped:/);
+    expect(src).toMatch(/return\s*{[\s\S]*?degraded,[\s\S]*?}/);
+  });
+
+  test('ExportResult carries a degraded field', () => {
+    const src = read('exporters/index.ts');
+    expect(src).toContain('ExportDegradation');
+    expect(src).toMatch(/degraded\?:\s*ExportDegradation/);
+  });
+
+  test('the job record, the WS emit and the history entry all carry it', () => {
+    const src = read('exporters/jobs.ts');
+    // Job type + assignment on the done path.
+    expect(src).toMatch(/degraded\?:\s*ExportDegradation/);
+    expect(src).toContain('if (res.degraded) job.degraded = res.degraded;');
+    // deriveHistory() writes `_export-history.json` — the ledger a later
+    // session reads back. It must not look clean either.
+    expect(src).toMatch(/degraded:\s*j\.degraded/);
+    // The WS emit spreads the whole job, which is how `degraded` reaches
+    // subscribers — assert the spread rather than a field list that could drift.
+    expect(src).toContain("bus.emit('export:job', { ...job })");
+  });
+
+  test('status stays `done` — the file is real, the flag is what differs', () => {
+    const src = read('exporters/jobs.ts');
+    expect(src).toContain("job.status = 'done';");
+  });
+
+  test('the panel and the toast both surface it', () => {
+    const src = read('client/export-center.jsx');
+    expect(src).toContain('DegradedNote');
+    expect(src).toContain('export-degraded-note');
+    // The pill must not read "Ready" on a muted file.
+    expect(src).toContain('Ready · no audio');
+    // Both surfaces, because the toast is what the user sees without opening
+    // the panel, and the panel is what they revisit afterwards.
+    const noteUses = src.match(/<DegradedNote/g) ?? [];
+    expect(noteUses.length).toBeGreaterThanOrEqual(2);
+  });
+});