@1agh/maude 0.58.3 → 0.59.0

package/apps/studio/test/sync-panel-surface.test.ts

@@ -0,0 +1,90 @@
+// feature-sync-progress-modal — the Sync panel + HUB SYNC chip surface.
+//
+// Source-level assertions (cloud-shell-surfaces style): what these pin is
+// exactly what would regress — someone dropping the linked-only gate (a solo
+// project would get a dock tab that opens onto nothing), rewiring the chip
+// away from the dock helpers (breaking the one-panel-per-side invariant), or
+// the panel inventing sync vocabulary / dropping the a11y live region the
+// CloudBar note established.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STUDIO = join(import.meta.dir, '..');
+const APP = readFileSync(join(STUDIO, 'client', 'app.jsx'), 'utf8');
+const PANEL = readFileSync(join(STUDIO, 'client', 'panels', 'SyncPanel.jsx'), 'utf8');
+
+describe('the Sync panel exists only where a hub link exists', () => {
+  test('sync is a dock panel with a right-side default', () => {
+    expect(APP).toContain("{ id: 'sync', label: 'Sync' }");
+    expect(APP).toMatch(/sync: 'right'/);
+  });
+
+  test('panelAvailable gates sync on a live syncStatus — solo projects get no tab', () => {
+    expect(APP).toContain("if (id === 'sync') return !!syncStatus;");
+  });
+
+  test('the chip toggles through the dock helpers, not a raw setState', () => {
+    // toggleRightPanel keeps the one-panel-per-side invariant; a bare
+    // setSyncPanelOpen(true) here would let Sync render behind an open sibling.
+    expect(APP).toMatch(/onOpenSync=\{syncStatus \? \(\) => toggleRightPanel\('sync'\)/);
+  });
+
+  test('the chip is a real button with pressed-state semantics', () => {
+    expect(APP).toContain('data-testid="open-sync"');
+    expect(APP).toMatch(/aria-pressed=\{syncOpen\}/);
+  });
+
+  test('the span fallback remains for sessions without a handler', () => {
+    // Older wiring / no-handler renders must keep the passive chip rather
+    // than a dead button.
+    expect(APP).toMatch(/onOpenSync \? \(/);
+  });
+});
+
+describe('the Sync panel speaks the presentation vocabulary, safely', () => {
+  test('the header sentence comes from syncPresentation — the one shared rule', () => {
+    expect(PANEL).toContain("from '../../sync/presentation.ts'");
+    expect(PANEL).toContain('syncPresentation(status');
+  });
+
+  test('rows map DocSyncState onto existing words, never new ones', () => {
+    expect(PANEL).toMatch(/pending: 'syncing'/);
+    expect(PANEL).toMatch(/connected: 'synced'/);
+    expect(PANEL).toMatch(/'auth-rejected': 'refused'/);
+  });
+
+  test('every name that reaches the DOM goes through safeName', () => {
+    // Slugs and asset keys are local, but the payload is read back off disk —
+    // bounded text-only rendering is the house rule (DDR-054).
+    expect(PANEL).toContain('import { safeName, syncPresentation }');
+    expect(PANEL).not.toMatch(/dangerouslySetInnerHTML/);
+  });
+
+  test('the live header is a polite status region (the CloudBar a11y pattern)', () => {
+    expect(PANEL).toMatch(/role="status" aria-live="polite"/);
+  });
+
+  test('the asset lane renders from the payload, with the retry promise', () => {
+    expect(PANEL).toContain('data-testid="sync-assets"');
+    expect(PANEL).toContain('retry on the next launch');
+  });
+});
+
+describe('the panel reads the off-disk payload fail-closed (DDR-102 discipline)', () => {
+  test('items, assets and the header counts all pass a readCounts-style gate', () => {
+    // `_sync.json` is JSON.parse with no schema — a partial write or older
+    // producer must degrade to "nothing to show", never crash or print NaN
+    // (security review 2026-08-11, defender W1).
+    expect(PANEL).toContain('function readItems(');
+    expect(PANEL).toContain('function readAssets(');
+    expect(PANEL).toContain('readItems(status?.items)');
+    expect(PANEL).toContain('readAssets(status?.assets)');
+    expect(PANEL).toMatch(/Number\.isInteger/);
+    // The header chip validates the same counts the note fails closed on.
+    expect(PANEL).toMatch(
+      /\[rawDocs\.synced, rawDocs\.pending, rawDocs\.rejected\]\.every\(isCount\)/
+    );
+  });
+});

package/apps/studio/test/sync-status.test.ts

@@ -144,3 +144,31 @@ describe('sync status store — DDR-102 additive fields', () => {
     expect(p.state).toBe('online');
   });
 });
+
+describe('sync status store — asset lane (feature-sync-progress-modal)', () => {
+  test('updateAssets() merges progress into the payload + flushes', () => {
+    const { store, writes, broadcasts } = makeStore();
+    const progress = {
+      total: 10,
+      done: 4,
+      pushed: 3,
+      skipped: 1,
+      failedCount: 0,
+      failures: [],
+      active: 'assets/hero.png',
+      finished: false,
+    };
+    store.updateAssets(progress);
+    expect(writes[writes.length - 1].assets).toEqual(progress);
+    expect(broadcasts[broadcasts.length - 1].assets).toEqual(progress);
+    // …and a later monitor update keeps the asset lane (separate slices).
+    store.update(snap({ state: 'online' }));
+    expect(store.get().assets).toEqual(progress);
+  });
+
+  test('payloads before the first asset emit carry no assets field', () => {
+    const { store } = makeStore();
+    store.update(snap());
+    expect('assets' in store.get()).toBe(false);
+  });
+});

package/apps/studio/test/timeline-comp-target.test.ts

@@ -0,0 +1,139 @@
+// timeline-comp-target — issue #75 regression coverage.
+//
+// The Timeline draws the rows of ONE artboard's comp but drives the transport
+// through a targeted postMessage, so "which comp id" is a real decision. The
+// old rule matched the parsed row total against `durationInFrames`; two comps
+// of equal length collapsed onto the FIRST one, so Play moved artboard #1 while
+// the panel showed artboard #2. These tests pin the artboard-first rule.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  activeComp,
+  resolveCompTarget,
+  sanitizeArtboardText,
+} from '../client/panels/timeline-comp-target.js';
+
+const comp = (id: string, artboardId: string | null, durationInFrames: number) => ({
+  id,
+  artboardId,
+  durationInFrames,
+  fps: 30,
+  width: 1920,
+  height: 1080,
+  artboardLabel: artboardId,
+});
+
+describe('resolveCompTarget', () => {
+  test('empty / missing comps → null', () => {
+    expect(resolveCompTarget([], { artboardId: 'a' })).toBe(null);
+    // @ts-expect-error — defensive: the shell hands through canvas-origin data.
+    expect(resolveCompTarget(null, {})).toBe(null);
+  });
+
+  test('THE BUG — equal-duration comps resolve by artboard, not by order', () => {
+    const comps = [comp('videocomp-1', 'intro', 150), comp('videocomp-2', 'outro', 150)];
+    expect(resolveCompTarget(comps, { artboardId: 'outro', total: 150 })).toBe('videocomp-2');
+    expect(resolveCompTarget(comps, { artboardId: 'intro', total: 150 })).toBe('videocomp-1');
+  });
+
+  test('an author-set comp id equal to the artboard id also matches', () => {
+    const comps = [comp('intro', null, 150), comp('outro', null, 150)];
+    expect(resolveCompTarget(comps, { artboardId: 'outro', total: 150 })).toBe('outro');
+  });
+
+  test('no artboard known → an UNAMBIGUOUS duration still identifies the comp', () => {
+    const comps = [comp('videocomp-1', 'intro', 150), comp('videocomp-2', 'outro', 90)];
+    expect(resolveCompTarget(comps, { artboardId: null, total: 90 })).toBe('videocomp-2');
+  });
+
+  test('no artboard known + ambiguous duration → first comp (the only guess left)', () => {
+    const comps = [comp('videocomp-1', 'intro', 150), comp('videocomp-2', 'outro', 150)];
+    expect(resolveCompTarget(comps, { artboardId: null, total: 150 })).toBe('videocomp-1');
+  });
+
+  // Adversarial review 2026-08-12 — comp ids and artboard ids are separate
+  // author-chosen namespaces, so the weaker claim must never beat the real one.
+  test('an announced artboard OUTRANKS a comp that merely names itself after it', () => {
+    const comps = [comp('outro', 'intro', 150), comp('videocomp-2', 'outro', 150)];
+    expect(resolveCompTarget(comps, { artboardId: 'outro', total: 150 })).toBe('videocomp-2');
+  });
+
+  // The row parser derives the artboard lexically from the .tsx; canvas-lib
+  // reports the viewport one structurally. When the lexical claim names an
+  // artboard no comp is mounted in, the pan signal must still land the target.
+  test('candidate list — a stale first candidate falls through to the live one', () => {
+    const comps = [comp('videocomp-1', 'intro', 150), comp('videocomp-2', 'outro', 150)];
+    expect(resolveCompTarget(comps, { artboardId: ['ghost', 'outro'], total: 150 })).toBe(
+      'videocomp-2'
+    );
+    // First candidate wins whenever it DOES name a mounted comp.
+    expect(resolveCompTarget(comps, { artboardId: ['intro', 'outro'], total: 150 })).toBe(
+      'videocomp-1'
+    );
+    expect(resolveCompTarget(comps, { artboardId: [null, undefined, 'outro'] })).toBe(
+      'videocomp-2'
+    );
+  });
+
+  test('an artboard with no comp falls back rather than returning null', () => {
+    const comps = [comp('videocomp-1', 'intro', 150)];
+    expect(resolveCompTarget(comps, { artboardId: 'a-still-image-board', total: 150 })).toBe(
+      'videocomp-1'
+    );
+  });
+});
+
+// The artboard label is untrusted canvas-origin text rendered as shell chrome
+// (security-review 2026-08-12): a chip that can be made to read as a different
+// artboard than the transport is scoped to defeats its own purpose.
+describe('sanitizeArtboardText', () => {
+  test('strips bidi overrides + isolates', () => {
+    expect(sanitizeArtboardText('Intro\u202e')).toBe('Intro');
+    expect(sanitizeArtboardText('\u2066Outro\u2069')).toBe('Outro');
+    expect(sanitizeArtboardText('gnp\u202egpj.Hero')).toBe('gnpgpj.Hero');
+  });
+
+  test('strips zero-width, soft hyphen, BOM and C0/C1 controls', () => {
+    expect(sanitizeArtboardText('In\u200btro')).toBe('Intro');
+    expect(sanitizeArtboardText('\ufeffHero\u00ad')).toBe('Hero');
+    expect(sanitizeArtboardText('Line\nBreak\tTab')).toBe('LineBreakTab');
+    expect(sanitizeArtboardText('Bell\u0007')).toBe('Bell');
+  });
+
+  test('an all-invisible label reads as NO label, not as a blank chip', () => {
+    expect(sanitizeArtboardText('\u200b\u200b\u200b')).toBe(null);
+    expect(sanitizeArtboardText('   ')).toBe(null);
+    expect(sanitizeArtboardText('')).toBe(null);
+  });
+
+  test('non-strings are null, never coerced', () => {
+    expect(sanitizeArtboardText(undefined)).toBe(null);
+    expect(sanitizeArtboardText(null)).toBe(null);
+    expect(sanitizeArtboardText(42)).toBe(null);
+    expect(sanitizeArtboardText({ toString: () => 'nope' })).toBe(null);
+  });
+
+  test('caps length, and a cap that lands mid-space still trims', () => {
+    expect(sanitizeArtboardText('x'.repeat(500))).toHaveLength(120);
+    expect(sanitizeArtboardText(`${'x'.repeat(119)} yz`)).toBe('x'.repeat(119));
+  });
+
+  test('ordinary labels survive intact (accents, emoji, punctuation)', () => {
+    expect(sanitizeArtboardText('Přehled — 2. krok')).toBe('Přehled — 2. krok');
+    expect(sanitizeArtboardText('Hero 🎬')).toBe('Hero 🎬');
+  });
+});
+
+describe('activeComp', () => {
+  test('reads meta off the SAME comp the transport targets', () => {
+    const comps = [comp('videocomp-1', 'intro', 150), comp('videocomp-2', 'outro', 90)];
+    expect(activeComp(comps, 'videocomp-2')?.durationInFrames).toBe(90);
+  });
+
+  test('unknown id → first comp (panel still renders); empty → null', () => {
+    const comps = [comp('videocomp-1', 'intro', 150)];
+    expect(activeComp(comps, 'nope')?.id).toBe('videocomp-1');
+    expect(activeComp([], 'x')).toBe(null);
+  });
+});

package/apps/studio/test/video-comp.test.ts

@@ -11,7 +11,7 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
 import { GlobalRegistrator } from '@happy-dom/global-registrator';
 
-import { installMaudeSeekBridge } from '../video-comp.tsx';
+import { findArtboardOf, installMaudeSeekBridge } from '../video-comp.tsx';
 
 interface FakePlayer {
   seekTo: (frame: number) => void;
@@ -111,6 +111,11 @@ describe('video-comp seek bridge', () => {
       durationInFrames: 90,
       width: 640,
       height: 360,
+      // issue #75 — always present in the snapshot (null when the comp was
+      // registered outside an artboard), so the shell can key the transport
+      // target on artboard identity instead of guessing from duration.
+      artboardId: null,
+      artboardLabel: null,
     });
     // No ref/functions leak into the snapshot.
     expect(Object.keys(comps[0])).not.toContain('ref');
@@ -188,3 +193,78 @@ describe('video-comp seek bridge', () => {
     );
   });
 });
+
+// issue #75 — a comp's own id is a mount slug (`videocomp-N`) unless the author
+// set one, so the shell can only tell two comps apart by the artboard they are
+// mounted in. This is the resolution that puts that id on the wire.
+describe('findArtboardOf', () => {
+  test('resolves the enclosing artboard id + visible label', () => {
+    document.body.innerHTML = `
+      <article data-dc-screen="outro">
+        <button class="dc-artboard-label sku"><span aria-hidden="true"></span>Outro</button>
+        <div class="dc-artboard-body"><div class="dc-video-comp" data-comp-id="videocomp-2"></div></div>
+      </article>`;
+    const host = document.querySelector('.dc-video-comp');
+    expect(findArtboardOf(host)).toEqual({ artboardId: 'outro', artboardLabel: 'Outro' });
+  });
+
+  test('a comp mounted outside any artboard reports nulls, never throws', () => {
+    document.body.innerHTML = '<div class="dc-video-comp" data-comp-id="bare"></div>';
+    expect(findArtboardOf(document.querySelector('.dc-video-comp'))).toEqual({
+      artboardId: null,
+      artboardLabel: null,
+    });
+    expect(findArtboardOf(null)).toEqual({ artboardId: null, artboardLabel: null });
+  });
+
+  // Adversarial review 2026-08-12 — `.dc-artboard-label` is a class anyone can
+  // write, so the label must come from the element canvas-lib actually renders
+  // (a DIRECT header/button child), not from the first match anywhere below.
+  test('a planted label node cannot outrank the real header', () => {
+    document.body.innerHTML = `
+      <article data-dc-screen="intro">
+        <span class="dc-artboard-label" hidden>Outro</span>
+        <header class="dc-artboard-label sku">Intro</header>
+        <div class="dc-artboard-body"><div class="dc-video-comp"></div></div>
+      </article>`;
+    expect(findArtboardOf(document.querySelector('.dc-video-comp')).artboardLabel).toBe('Intro');
+  });
+
+  test('a nested artboard resolves to the NEAREST board, not the outer label', () => {
+    document.body.innerHTML = `
+      <article data-dc-screen="outer">
+        <header class="dc-artboard-label sku">Outer</header>
+        <article data-dc-screen="inner">
+          <header class="dc-artboard-label sku">Inner</header>
+          <div class="dc-video-comp"></div>
+        </article>
+      </article>`;
+    expect(findArtboardOf(document.querySelector('.dc-video-comp'))).toEqual({
+      artboardId: 'inner',
+      artboardLabel: 'Inner',
+    });
+  });
+
+  test('a label deep in the body is ignored — only a direct header/button counts', () => {
+    document.body.innerHTML = `
+      <article data-dc-screen="intro">
+        <div class="dc-artboard-body">
+          <p class="dc-artboard-label">Outro</p>
+          <div class="dc-video-comp"></div>
+        </div>
+      </article>`;
+    expect(findArtboardOf(document.querySelector('.dc-video-comp'))).toEqual({
+      artboardId: 'intro',
+      artboardLabel: null,
+    });
+  });
+
+  test('an unlabelled artboard still yields its id', () => {
+    document.body.innerHTML =
+      '<article data-dc-screen="intro"><div class="dc-video-comp"></div></article>';
+    expect(findArtboardOf(document.querySelector('.dc-video-comp'))).toEqual({
+      artboardId: 'intro',
+      artboardLabel: null,
+    });
+  });
+});

package/apps/studio/test/video-encode-lib.test.ts

@@ -0,0 +1,63 @@
+// video-encode-lib — frame-clearing contract (feature-fast-video-export Task 6e).
+//
+// `addVideoFrame`/`addGifFrame` run INSIDE the capture Chromium (real
+// OffscreenCanvas + WebCodecs), so the actual pixel behavior needs a live
+// browser — not a `bun:test` concern, mirroring video-render-bridge.test.ts's
+// split between pure routing (tested here at the source level) and live
+// canvas/codec work (manual/agent-browser verification).
+//
+// What IS worth pinning: the DECISION itself. `drawImage` is called with no
+// preceding `clearRect`/`fillRect` reset, so a transparent frame draws OVER
+// whatever the encoder canvas already held — a transparent artboard would
+// ghost the previous frame's pixels through. This was flagged as a "decide
+// deliberately, don't let it drift" item rather than a bug: every capture
+// path today feeds `page.screenshot()` output, which Chromium always
+// composites onto an opaque background (no `omitBackground` capture exists in
+// this codebase), so the ghost case cannot currently occur in practice. If
+// that stops being true — a future capture path starts passing genuinely
+// transparent frames — this test must be touched, which is the point: an
+// accidental `clearRect` add/removal should force a conscious look at this
+// comment, not slip through unnoticed.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SRC = readFileSync(join(import.meta.dir, '..', 'exporters', 'video-encode-lib.ts'), 'utf8');
+
+function body(fnName: string): string {
+  const start = SRC.indexOf(`async ${fnName}(`);
+  const openBrace = SRC.indexOf('{', start);
+  // Cheap brace match — good enough for this file's flat function bodies.
+  let depth = 0;
+  let end = openBrace;
+  for (let i = openBrace; i < SRC.length; i += 1) {
+    if (SRC[i] === '{') depth += 1;
+    else if (SRC[i] === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        end = i;
+        break;
+      }
+    }
+  }
+  return SRC.slice(start, end + 1);
+}
+
+describe('video-encode-lib — frame-clearing decision (pinned, not a bug)', () => {
+  test('addVideoFrame draws without clearing the encoder canvas first', () => {
+    const fn = body('addVideoFrame');
+    expect(fn).toMatch(
+      /ctx\.drawImage\(bmp, 0, 0, vstate\.canvas\.width, vstate\.canvas\.height\)/
+    );
+    expect(fn).not.toMatch(/clearRect|fillRect/);
+  });
+
+  test('addGifFrame draws without clearing the gif canvas first', () => {
+    const fn = body('addGifFrame');
+    expect(fn).toMatch(
+      /ctx\.drawImage\(bmp, 0, 0, gstate\.canvas\.width, gstate\.canvas\.height\)/
+    );
+    expect(fn).not.toMatch(/clearRect|fillRect/);
+  });
+});

package/apps/studio/use-artboard-drag.tsx

@@ -268,8 +268,16 @@ export interface UseArtboardDragOptions {
   rectFor: (id: string) => Rect | null;
   /** Every artboard's rect in render order. */
   allRects: Rect[];
-  /** Live viewport — `null` before first layout. */
+  /** Published viewport — `null` before first layout. Settle-cadence. */
   viewport: { zoom: number } | null;
+  /**
+   * Current zoom, read imperatively at event time. Supplied by the canvas so
+   * this hook never imports canvas-lib (which imports it — that would be a
+   * cycle). Load-bearing: `viewport` above only updates when a gesture settles,
+   * so a drag started inside the settle window would divide its deltas by the
+   * pre-gesture zoom and track the cursor at the wrong speed.
+   */
+  liveZoom?: () => number;
   /** False short-circuits all event handling (e.g. activeTool !== "move"). */
   enabled: boolean;
   /** Called on drop with final positions for leader + followers. */
@@ -293,6 +301,7 @@ export function useArtboardDrag(opts: UseArtboardDragOptions): UseArtboardDragHa
     rectFor,
     allRects,
     viewport,
+    liveZoom,
     enabled,
     onCommit,
     gridSize = DEFAULT_GRID_SIZE,
@@ -304,8 +313,28 @@ export function useArtboardDrag(opts: UseArtboardDragOptions): UseArtboardDragHa
   // Keep stable refs for callbacks that close over fast-changing inputs.
   const stateRef = useRef<DragState>(dragState);
   stateRef.current = dragState;
-  const zoomRef = useRef<number>(viewport?.zoom ?? 1);
-  zoomRef.current = viewport?.zoom ?? 1;
+  // The zoom a drag divides by must be the CURRENT one. `viewport` here is the
+  // published (settle-cadence) value, so mirroring it alone would leave this
+  // ref a gesture behind: pan, then grab an artboard within the settle window,
+  // and every delta would be divided by the pre-pan zoom — the board would
+  // track the cursor at the wrong speed. getLiveViewport() is the imperative
+  // mirror the viewport controller writes every frame; the prop is the fallback
+  // for mounts that have no controller (bare DS specimens).
+  // Stable identity across renders (useMemo, empty deps): recreating the object
+  // every render would make it look like a changing dependency to anything that
+  // closed over it. It reads through refs, so it never goes stale.
+  const liveZoomRef = useRef(liveZoom);
+  liveZoomRef.current = liveZoom;
+  const viewportRef = useRef(viewport);
+  viewportRef.current = viewport;
+  const zoomRef = useMemo(
+    () => ({
+      get current(): number {
+        return liveZoomRef.current?.() ?? viewportRef.current?.zoom ?? 1;
+      },
+    }),
+    []
+  );
   const onCommitRef = useRef(onCommit);
   onCommitRef.current = onCommit;
   const enabledRef = useRef(enabled);
@@ -392,6 +421,11 @@ export function useArtboardDrag(opts: UseArtboardDragOptions): UseArtboardDragHa
 
   // Global pointermove / pointerup while a drag is in flight. Bound at the
   // window level so a fast drag past any element still feeds the reducer.
+  //
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `zoomRef` is a live
+  // getter (stable identity, reads through refs), not state — the handlers must
+  // read the CURRENT zoom at event time. Listing it would re-subscribe these
+  // listeners whenever zoom changed, tearing the pointer stream down mid-drag.
   useEffect(() => {
     if (dragState.kind === 'idle') return;
     if (typeof window === 'undefined') return;

package/apps/studio/video-comp.tsx

@@ -41,6 +41,16 @@ export interface VideoCompMeta {
 /** A live registration — the Player handle + its meta, keyed by artboard id. */
 interface CompEntry extends VideoCompMeta {
   id: string;
+  /** The enclosing DCArtboard's id (`data-dc-screen`), resolved by DOM
+   *  containment at mount. The VideoComp's own `compId` is usually an
+   *  author-omitted `videocomp-N` mount slug, so this is the ONLY reliable way
+   *  for the shell to map "the artboard the user is looking at" → "the comp the
+   *  transport must drive" (rca/issue-timeline-drives-wrong-artboard). Null on a
+   *  comp mounted outside an artboard (bare preview / test harness). */
+  artboardId: string | null;
+  /** The artboard's visible label — shown in the Timeline head so the user can
+   *  see WHICH artboard the rows + transport belong to. */
+  artboardLabel: string | null;
   ref: React.RefObject<PlayerRef | null>;
   /** The Remotion composition component + its props — carried so the export
    *  capture's renderMediaOnWeb path (DDR-148 addendum, audio export) can
@@ -55,6 +65,9 @@ interface CompEntry extends VideoCompMeta {
 /** Serializable meta the capture shim + Timeline panel read (no functions). */
 export interface CompSnapshot extends VideoCompMeta {
   id: string;
+  /** Enclosing DCArtboard id + label — see CompEntry. */
+  artboardId: string | null;
+  artboardLabel: string | null;
 }
 
 /** Result contract for `__maude_render_video__` — see exporters/video-render-lib.ts. */
@@ -255,6 +268,8 @@ export function installMaudeSeekBridge(): void {
       durationInFrames: e.durationInFrames,
       width: e.width,
       height: e.height,
+      artboardId: e.artboardId ?? null,
+      artboardLabel: e.artboardLabel ?? null,
     }));
 
   w.__maude_render_video__ = async (compId, opts) => {
@@ -288,6 +303,35 @@ export function findCompIdIn(container: Element): string | null {
   return container.querySelector('[data-comp-id]')?.getAttribute('data-comp-id') ?? null;
 }
 
+/** The inverse of `findCompIdIn` — walk UP from a mounted comp to the artboard
+ *  that contains it, and read its id + visible label. Same rationale (the two
+ *  ids are independent), used at registration time so every announced comp
+ *  carries the artboard the user actually sees it on. */
+export function findArtboardOf(el: Element | null): {
+  artboardId: string | null;
+  artboardLabel: string | null;
+} {
+  const board = el?.closest?.('[data-dc-screen]') ?? null;
+  if (!board) return { artboardId: null, artboardLabel: null };
+  // DIRECT children only, and only the two tags canvas-lib actually renders the
+  // label as (`<header>` unpositioned / `<button>` positioned). A subtree-wide
+  // `querySelector('.dc-artboard-label')` would take the first match in document
+  // order anywhere below the artboard — including a hidden node planted ahead of
+  // the real header, or one belonging to a nested artboard — and `textContent`
+  // reads hidden nodes happily. The label is shell chrome the user reads to know
+  // which artboard the transport moves, so it must come from the element
+  // canvas-lib owns, not from whatever matches the class first.
+  const header = Array.from(board.children).find(
+    (c) =>
+      (c.tagName === 'HEADER' || c.tagName === 'BUTTON') &&
+      c.classList.contains('dc-artboard-label')
+  );
+  return {
+    artboardId: board.getAttribute('data-dc-screen'),
+    artboardLabel: header?.textContent?.trim() || null,
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // VideoComp — the canvas-lib wrapper
 
@@ -361,6 +405,7 @@ export function VideoComp({
   autoPlay,
 }: VideoCompProps) {
   const ref = useRef<PlayerRef | null>(null);
+  const hostRef = useRef<HTMLDivElement | null>(null);
   // Stable id across re-renders; unique per mount when the author omits one.
   const [autoId] = useState(() => id ?? `videocomp-${++mountCounter}`);
   const compId = id ?? autoId;
@@ -390,8 +435,13 @@ export function VideoComp({
   // Register with the seek bridge for the lifetime of this mount.
   useEffect(() => {
     installMaudeSeekBridge();
+    // Resolved here (not at render) because the wrapper is only in the DOM once
+    // the effect runs — that's also when the enclosing DCArtboard exists.
+    const { artboardId, artboardLabel } = findArtboardOf(hostRef.current);
     const entry: CompEntry = {
       id: compId,
+      artboardId,
+      artboardLabel,
       fps,
       durationInFrames,
       width,
@@ -507,6 +557,7 @@ export function VideoComp({
   return (
     <div
       className="dc-video-comp"
+      ref={hostRef}
       data-comp-id={compId}
       style={{ width, height, maxWidth: '100%' }}
     >