@1agh/maude 0.39.1 → 0.41.0

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

@@ -0,0 +1,168 @@
+// video-comp — DDR-148 seek-bridge unit coverage.
+//
+// The Remotion Player's actual frame render needs a real browser (rAF, layout,
+// media) — that determinism ("two seeks to frame N → identical pixels") is an
+// agent-browser live check (Task 11). What IS pure + testable here is the seek
+// BRIDGE the capture spine + Timeline panel drive: the comp registry, the
+// clamped seek routing to each Player, and the serializable snapshot. We stand
+// up happy-dom, install the bridge without mounting a Player, register a fake
+// Player handle (a seekTo/pause spy), and assert the routing contract.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+
+import { installMaudeSeekBridge } from '../video-comp.tsx';
+
+interface FakePlayer {
+  seekTo: (frame: number) => void;
+  pause: () => void;
+  seeks: number[];
+  pauses: number;
+}
+
+interface SeekWindow {
+  __maudeVideoComps?: Map<
+    string,
+    {
+      id: string;
+      fps: number;
+      durationInFrames: number;
+      width: number;
+      height: number;
+      ref: { current: FakePlayer | null };
+    }
+  >;
+  __maude_seek__?: (frame: number, opts?: { fps?: number }) => Promise<void>;
+  __maude_comps__?: () => Array<{
+    id: string;
+    fps: number;
+    durationInFrames: number;
+    width: number;
+    height: number;
+  }>;
+}
+
+function makeFakePlayer(): FakePlayer {
+  const p: FakePlayer = {
+    seeks: [],
+    pauses: 0,
+    seekTo(frame) {
+      p.seeks.push(frame);
+    },
+    pause() {
+      p.pauses += 1;
+    },
+  };
+  return p;
+}
+
+function registerComp(
+  id: string,
+  meta: { fps: number; durationInFrames: number; width: number; height: number },
+  player: FakePlayer
+): void {
+  const w = window as unknown as SeekWindow;
+  if (!w.__maudeVideoComps) w.__maudeVideoComps = new Map();
+  w.__maudeVideoComps.set(id, { id, ...meta, ref: { current: player } });
+}
+
+beforeAll(() => {
+  GlobalRegistrator.register();
+});
+
+afterAll(async () => {
+  await GlobalRegistrator.unregister();
+});
+
+beforeEach(() => {
+  const w = window as unknown as SeekWindow;
+  w.__maudeVideoComps = undefined;
+  w.__maude_seek__ = undefined;
+  w.__maude_comps__ = undefined;
+});
+
+describe('video-comp seek bridge', () => {
+  test('installs window.__maude_seek__ + __maude_comps__ idempotently', () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    const seek1 = w.__maude_seek__;
+    const comps1 = w.__maude_comps__;
+    expect(typeof seek1).toBe('function');
+    expect(typeof comps1).toBe('function');
+    installMaudeSeekBridge();
+    // Second install must NOT replace the functions (idempotent).
+    expect(w.__maude_seek__).toBe(seek1);
+    expect(w.__maude_comps__).toBe(comps1);
+  });
+
+  test('__maude_comps__ reflects the live registry (serializable, no functions)', () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    registerComp(
+      'intro',
+      { fps: 30, durationInFrames: 90, width: 640, height: 360 },
+      makeFakePlayer()
+    );
+    const comps = w.__maude_comps__?.() ?? [];
+    expect(comps).toHaveLength(1);
+    expect(comps[0]).toEqual({
+      id: 'intro',
+      fps: 30,
+      durationInFrames: 90,
+      width: 640,
+      height: 360,
+    });
+    // No ref/functions leak into the snapshot.
+    expect(Object.keys(comps[0])).not.toContain('ref');
+  });
+
+  test('seek routes to every registered Player, paused first', async () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    const a = makeFakePlayer();
+    const b = makeFakePlayer();
+    registerComp('a', { fps: 30, durationInFrames: 90, width: 640, height: 360 }, a);
+    registerComp('b', { fps: 24, durationInFrames: 48, width: 320, height: 240 }, b);
+    await w.__maude_seek__?.(30);
+    expect(a.seeks).toEqual([30]);
+    expect(b.seeks).toEqual([30]);
+    expect(a.pauses).toBe(1);
+    expect(b.pauses).toBe(1);
+  });
+
+  test('seek clamps into [0, durationInFrames-1] per comp + rounds', async () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    const a = makeFakePlayer();
+    registerComp('a', { fps: 30, durationInFrames: 90, width: 640, height: 360 }, a);
+    await w.__maude_seek__?.(999); // past the end → clamp to 89
+    await w.__maude_seek__?.(-5); // before the start → clamp to 0
+    await w.__maude_seek__?.(12.6); // fractional → round to 13
+    expect(a.seeks).toEqual([89, 0, 13]);
+  });
+
+  test('two seeks to the same frame issue identical Player calls (determinism contract)', async () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    const a = makeFakePlayer();
+    registerComp('a', { fps: 30, durationInFrames: 90, width: 640, height: 360 }, a);
+    await w.__maude_seek__?.(42);
+    await w.__maude_seek__?.(42);
+    expect(a.seeks).toEqual([42, 42]);
+  });
+
+  test('a Player ref that is not yet ready (null) does not throw', async () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    if (!w.__maudeVideoComps) w.__maudeVideoComps = new Map();
+    w.__maudeVideoComps.set('pending', {
+      id: 'pending',
+      fps: 30,
+      durationInFrames: 90,
+      width: 640,
+      height: 360,
+      ref: { current: null },
+    });
+    await expect(w.__maude_seek__?.(10)).resolves.toBeUndefined();
+  });
+});

package/apps/studio/test/video-render-bridge.test.ts

@@ -0,0 +1,149 @@
+// video-render-bridge — DDR-148 addendum (audio export) unit coverage.
+//
+// The actual renderMediaOnWeb call needs a real browser (WebCodecs, canvas
+// decode) — that's a manual/agent-browser verification (see the DDR-148
+// addendum § Manual verification recipe), not a unit test, mirroring
+// video-comp.test.ts's own split between the pure seek-bridge routing (tested
+// here) and live Player rendering (not). What IS pure + testable: `findCompIdIn`
+// (DOM containment resolution) and the `__maude_render_video__` bridge's
+// routing contract — it must merge the registered comp's component/meta with
+// the caller's opts and delegate to the injected `__maudeRenderVideo__`, and
+// fail clearly when either the comp or the render-lib injection is missing.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+
+import { findCompIdIn, installMaudeSeekBridge } from '../video-comp.tsx';
+
+interface RenderCall {
+  component: unknown;
+  inputProps: unknown;
+  width: number;
+  height: number;
+  fps: number;
+  durationInFrames: number;
+  [k: string]: unknown;
+}
+
+interface RenderWindow {
+  __maudeVideoComps?: Map<
+    string,
+    {
+      id: string;
+      fps: number;
+      durationInFrames: number;
+      width: number;
+      height: number;
+      ref: { current: null };
+      component: unknown;
+      inputProps: Record<string, unknown>;
+    }
+  >;
+  __maude_render_video__?: (compId: string, opts: Record<string, unknown>) => Promise<unknown>;
+  __maudeRenderVideo__?: (opts: RenderCall) => Promise<unknown>;
+}
+
+function registerComp(
+  id: string,
+  meta: { fps: number; durationInFrames: number; width: number; height: number },
+  component: unknown,
+  inputProps: Record<string, unknown> = {}
+): void {
+  const w = window as unknown as RenderWindow;
+  if (!w.__maudeVideoComps) w.__maudeVideoComps = new Map();
+  w.__maudeVideoComps.set(id, { id, ...meta, ref: { current: null }, component, inputProps });
+}
+
+beforeAll(() => {
+  GlobalRegistrator.register();
+});
+
+afterAll(async () => {
+  await GlobalRegistrator.unregister();
+});
+
+beforeEach(() => {
+  const w = window as unknown as RenderWindow;
+  w.__maudeVideoComps = undefined;
+  w.__maudeRenderVideo__ = undefined;
+  (w as unknown as { __maude_render_video__?: unknown }).__maude_render_video__ = undefined;
+  (w as unknown as { __maude_seek__?: unknown }).__maude_seek__ = undefined;
+  (w as unknown as { __maude_comps__?: unknown }).__maude_comps__ = undefined;
+});
+
+describe('findCompIdIn', () => {
+  test('resolves the nearest [data-comp-id] descendant', () => {
+    document.body.innerHTML =
+      '<div data-dc-screen="reel"><div data-comp-id="videocomp-2"><span>x</span></div></div>';
+    const artboard = document.querySelector('[data-dc-screen="reel"]');
+    expect(artboard).not.toBeNull();
+    expect(findCompIdIn(artboard as Element)).toBe('videocomp-2');
+  });
+
+  test('returns null for an artboard with no registered comp (ordinary/CSS artboard)', () => {
+    document.body.innerHTML = '<div data-dc-screen="static"><p>just a div</p></div>';
+    const artboard = document.querySelector('[data-dc-screen="static"]');
+    expect(findCompIdIn(artboard as Element)).toBeNull();
+  });
+});
+
+describe('__maude_render_video__ bridge', () => {
+  test('merges the registered component + meta with caller opts, delegates to __maudeRenderVideo__', async () => {
+    const w = window as unknown as RenderWindow;
+    installMaudeSeekBridge();
+    const FakeComp = () => null;
+    registerComp('reel', { fps: 30, durationInFrames: 228, width: 960, height: 540 }, FakeComp, {
+      title: 'Showreel',
+    });
+    let received: RenderCall | null = null;
+    w.__maudeRenderVideo__ = async (opts) => {
+      received = opts;
+      return { b64: 'AA==', bytes: 2, container: 'mp4', videoCodec: 'h264', audioCodec: 'aac' };
+    };
+    const result = await w.__maude_render_video__?.('reel', {
+      container: 'mp4',
+      scale: 2,
+      muted: false,
+      frameRange: [0, 30],
+    });
+    expect(result).toEqual({
+      b64: 'AA==',
+      bytes: 2,
+      container: 'mp4',
+      videoCodec: 'h264',
+      audioCodec: 'aac',
+    });
+    expect(received).not.toBeNull();
+    const call = received as unknown as RenderCall;
+    expect(call.component).toBe(FakeComp);
+    expect(call.inputProps).toEqual({ title: 'Showreel' });
+    expect(call.width).toBe(960);
+    expect(call.height).toBe(540);
+    expect(call.fps).toBe(30);
+    expect(call.durationInFrames).toBe(228);
+    // Caller opts pass through alongside the merged meta.
+    expect(call.container).toBe('mp4');
+    expect(call.scale).toBe(2);
+    expect(call.muted).toBe(false);
+    expect(call.frameRange).toEqual([0, 30]);
+  });
+
+  test('throws a clear error for an unregistered compId', async () => {
+    const w = window as unknown as RenderWindow;
+    installMaudeSeekBridge();
+    await expect(w.__maude_render_video__?.('nope', { container: 'mp4' })).rejects.toThrow(
+      /no registered video-comp/i
+    );
+  });
+
+  test('throws a clear error when the render-lib bundle was never injected', async () => {
+    const w = window as unknown as RenderWindow;
+    installMaudeSeekBridge();
+    registerComp('reel', { fps: 30, durationInFrames: 90, width: 960, height: 540 }, () => null);
+    // __maudeRenderVideo__ intentionally left unset (simulates a capture that
+    // skipped addScriptTag — e.g. gif/ordinary-artboard export never injects it).
+    await expect(w.__maude_render_video__?.('reel', { container: 'mp4' })).rejects.toThrow(
+      /render-lib bundle not injected/i
+    );
+  });
+});

package/apps/studio/tool-palette.tsx

@@ -16,7 +16,9 @@ import { useEffect, useRef, useState } from 'react';
 
 import {
   IconChevronDown,
+  IconLetterA,
   IconPresentation,
+  IconSquare,
   SHAPE_KIND_ICONS,
   TOOL_ICONS,
 } from './canvas-icons.tsx';
@@ -214,6 +216,35 @@ const PALETTE_CSS = `
   background: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 14%, transparent);
   color: var(--maude-hud-accent, #d63b1f);
 }
+/* Stage I3 tail — "+ Element" insert popover. A vertical labeled list (not the
+   shape popover's icon grid): Div/Text/Image have no recognizable glyph on
+   their own, and this is a rare, must-be-legible action, not a recalled tool. */
+.dc-tool-palette .dc-tp-insert { position: relative; display: inline-flex; }
+.dc-tp-insert-popover {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 4px;
+  min-width: 128px;
+  background: var(--maude-chrome-bg-0, #ffffff);
+  border: 1px solid var(--maude-chrome-fg-0, #1c1917);
+  border-radius: 8px;
+  box-shadow: 0 6px 24px var(--maude-chrome-shadow, color-mix(in oklab, #1c1917 10%, transparent));
+  z-index: 8;
+}
+.dc-tp-insert-popover button {
+  width: auto;
+  height: auto;
+  justify-content: flex-start;
+  gap: 8px;
+  padding: 6px 8px;
+  border-radius: 4px;
+}
+.dc-tp-insert-popover button span.dc-tp-insert-label { font-size: 12px; }
 `.trim();
 
 function ensurePaletteStyles(): void {
@@ -250,6 +281,34 @@ const SHAPE_KINDS: ReadonlyArray<{ kind: ShapeKind; label: string }> = [
   { kind: 'triangle-down', label: 'Triangle down' },
 ];
 
+/**
+ * Stage I3 tail — resolve the insert anchor for the tool-palette "+ Element"
+ * affordance's "or appends to the active artboard" mode (the plan's fallback
+ * when the user hasn't right-clicked a specific element). Growth-only: an
+ * artboard's `<article data-dc-screen>` carries NO `data-cd-id` of its own
+ * (`DCArtboard` doesn't forward it to the DOM — only its SOURCE JSX tag is
+ * stamped, unresolvable from here), so `applyInsertElement`'s `refId` can't
+ * target the artboard directly. Anchor on the artboard's LAST direct child
+ * that DOES carry a `data-cd-id` and insert `position:'after'` it — the exact
+ * relation the context-menu's element-relative insert already uses. Returns
+ * `null` for an empty (or artboard-less) canvas — a documented v1 limit; the
+ * per-element context-menu "Insert ▸ …" still works there once a first
+ * element exists. `doc` is injectable for testing without a real iframe.
+ */
+export function resolveInsertAnchor(
+  doc: Document = document
+): { refId: string; position: 'after' } | null {
+  const current = doc.querySelector('[data-dc-screen][aria-current="true"]');
+  const artboardEl = current ?? doc.querySelector('[data-dc-screen]');
+  if (!artboardEl) return null;
+  const body = artboardEl.querySelector(':scope > .dc-artboard-body');
+  if (!body) return null;
+  const kids = Array.from(body.children).reverse();
+  const last = kids.find((el) => el.hasAttribute('data-cd-id'));
+  const refId = last?.getAttribute('data-cd-id');
+  return refId ? { refId, position: 'after' } : null;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Component
 
@@ -259,19 +318,22 @@ export function ToolPalette() {
   const chrome = useChromeVisibility();
   const [mounted, setMounted] = useState(false);
   const [shapeOpen, setShapeOpen] = useState(false);
+  const [insertOpen, setInsertOpen] = useState(false);
   const containerRef = useRef<HTMLDivElement | null>(null);
 
   useEffect(() => setMounted(true), []);
   useEffect(() => {
-    if (!shapeOpen) return;
+    if (!shapeOpen && !insertOpen) return;
     const onDown = (e: PointerEvent) => {
       if (!containerRef.current?.contains(e.target as Node)) {
         setShapeOpen(false);
+        setInsertOpen(false);
       }
     };
     const onKey = (e: KeyboardEvent) => {
       if (e.key === 'Escape') {
         setShapeOpen(false);
+        setInsertOpen(false);
       }
     };
     document.addEventListener('pointerdown', onDown, true);
@@ -280,12 +342,38 @@ export function ToolPalette() {
       document.removeEventListener('pointerdown', onDown, true);
       document.removeEventListener('keydown', onKey, true);
     };
-  }, [shapeOpen]);
+  }, [shapeOpen, insertOpen]);
   // Close the shape popover whenever the tool changes away from Shape.
   useEffect(() => {
     if (tool !== 'shape') setShapeOpen(false);
   }, [tool]);
 
+  // Stage I3 tail — insert a Div/Text/Image relative to the active artboard's
+  // last existing element (`resolveInsertAnchor`). Same request verbs the
+  // context-menu's per-element "Insert ▸ …" already posts (`insert-request` /
+  // `insert-image-request`, main-origin shell WRITES — DDR-054); a null anchor
+  // (empty/artboard-less canvas) is a silent no-op — a documented v1 limit.
+  const insertViaPalette = (kind: 'div' | 'text' | 'image') => {
+    setInsertOpen(false);
+    const anchor = resolveInsertAnchor();
+    if (!anchor) return;
+    try {
+      if (kind === 'image') {
+        window.parent.postMessage(
+          { dgn: 'insert-image-request', refId: anchor.refId, position: anchor.position },
+          '*'
+        );
+      } else {
+        window.parent.postMessage(
+          { dgn: 'insert-request', refId: anchor.refId, position: anchor.position, kind },
+          '*'
+        );
+      }
+    } catch {
+      /* detached / cross-origin teardown */
+    }
+  };
+
   if (!mounted) return null;
   // Presentation Mode hides the whole tool palette (clean artboards-only view).
   if (chrome?.present) return null;
@@ -393,6 +481,38 @@ export function ToolPalette() {
       </div>
       <div className="dc-tp-sep" />
       <div className="dc-tp-group">
+        <span className="dc-tp-insert">
+          <button
+            type="button"
+            aria-label="Insert element — Div, Text, or Image"
+            aria-haspopup="menu"
+            aria-expanded={insertOpen}
+            title="Insert element (appends to the active artboard)"
+            onClick={() => setInsertOpen((o) => !o)}
+          >
+            <span aria-hidden="true" style={{ fontSize: 16, lineHeight: 1 }}>
+              +
+            </span>
+          </button>
+          {insertOpen ? (
+            <div className="dc-tp-insert-popover" role="menu" aria-label="Insert element">
+              <button type="button" role="menuitem" onClick={() => insertViaPalette('div')}>
+                <IconSquare />
+                <span className="dc-tp-insert-label">Div</span>
+              </button>
+              <button type="button" role="menuitem" onClick={() => insertViaPalette('text')}>
+                <IconLetterA />
+                <span className="dc-tp-insert-label">Text</span>
+              </button>
+              <button type="button" role="menuitem" onClick={() => insertViaPalette('image')}>
+                <span aria-hidden="true" style={{ fontSize: 13, lineHeight: 1 }}>
+                  ▧
+                </span>
+                <span className="dc-tp-insert-label">Image</span>
+              </button>
+            </div>
+          ) : null}
+        </span>
         <button
           type="button"
           aria-label="Export (⌘E)"

package/apps/studio/undo-hud.tsx

@@ -32,12 +32,12 @@ const HUD_CSS = `
   user-select: none;
   opacity: 0;
   transform: translateY(-4px);
-  transition: opacity var(--dur-base, 200ms) linear, transform var(--dur-base, 200ms) ease-out;
+  transition: opacity 200ms linear, transform 200ms ease-out;
 }
 .dc-undo-hud[data-visible="true"] {
   opacity: 1;
   transform: translateY(0);
-  transition-duration: var(--dur-fast, 120ms);
+  transition-duration: 120ms;
 }
 @media (prefers-reduced-motion: reduce) {
   .dc-undo-hud {

package/apps/studio/use-annotation-resize.tsx

@@ -159,6 +159,7 @@ function isResizable(
     s.tool === 'sticky' ||
     s.tool === 'image' ||
     s.tool === 'link' ||
+    s.tool === 'mediaref' ||
     s.tool === 'section'
   );
 }
@@ -374,11 +375,13 @@ export function resizeStroke(
     start.tool === 'sticky' ||
     start.tool === 'polygon' ||
     start.tool === 'link' ||
+    start.tool === 'mediaref' ||
     start.tool === 'section'
   ) {
-    // Rect / polygon / sticky / link all resize via their shared x / y / w / h
-    // bbox. Text re-wraps inside the foreignObject automatically. Sticky stays
-    // 1:1; the link card free-resizes (Shift still locks its current ratio).
+    // Rect / polygon / sticky / link / mediaref all resize via their shared
+    // x / y / w / h bbox. Sticky stays 1:1; the link + media-ref cards
+    // free-resize (Shift still locks their current ratio) so the user can size
+    // the inline player up (DDR-150 dogfood — "video annotation nejde zvětšit").
     const b0 = { x: start.x, y: start.y, w: start.w, h: start.h };
     const box = bboxResizeRotAware(start, b0, corner, wx, wy, mods, start.tool === 'sticky');
     return box as Partial<RectStroke | StickyStroke | PolygonStroke | LinkStroke>;

package/apps/studio/use-canvas-media-drop.tsx

@@ -1,10 +1,14 @@
 /**
  * @file       use-canvas-media-drop.tsx — Phase 23 canvas media intake
  * @scope      apps/studio/use-canvas-media-drop.tsx
- * @purpose    OS-level drag-and-drop + clipboard paste of images and URLs onto
- *             the canvas. Routes each gesture to a create callback owned by
- *             AnnotationsLayer (which holds the commit/undo sink + screenToWorld):
+ * @purpose    OS-level drag-and-drop + clipboard paste of images, video/audio,
+ *             and URLs onto the canvas. Routes each gesture to a create callback
+ *             owned by AnnotationsLayer (which holds the commit/undo sink +
+ *             screenToWorld):
  *               • image file → `onImage(file, world)`  → optimistic stroke + upload
+ *               • video/audio → `onMedia?(file, kind, world)` → upload to assets/
+ *                 + toast the `<Video>`/`<Audio>` snippet (DDR-148; auto-insert
+ *                 into the comp TSX is a documented follow-up)
  *               • http(s) URL → `onLink(url, title, world)` → client-only link chip
  *
  *             The classification + URL helpers are PURE + exported so the unit
@@ -35,6 +39,7 @@ export interface MediaPayload {
 
 export type MediaIntent =
   | { kind: 'image'; file: File }
+  | { kind: 'media'; file: File; mediaKind: 'video' | 'audio' }
   | { kind: 'link'; url: string; title: string };
 
 /** True only for an absolute http(s) URL — the one scheme a link chip accepts. */
@@ -136,6 +141,19 @@ export function anchorTextFromHtml(html: string): string | null {
 export function classifyMediaPayload(p: MediaPayload): MediaIntent | null {
   const imageFile = p.files.find((f) => typeof f.type === 'string' && f.type.startsWith('image/'));
   if (imageFile) return { kind: 'image', file: imageFile };
+  // DDR-148 — video/audio files land in the project's assets/ (the widened asset
+  // route, DDR-088) so a comp can reference them as <Video>/<Audio src="assets/…">.
+  const mediaFile = p.files.find(
+    (f) =>
+      typeof f.type === 'string' && (f.type.startsWith('video/') || f.type.startsWith('audio/'))
+  );
+  if (mediaFile) {
+    return {
+      kind: 'media',
+      file: mediaFile,
+      mediaKind: mediaFile.type.startsWith('video/') ? 'video' : 'audio',
+    };
+  }
   const url = firstHttpUrl(p.uriList) ?? firstHttpUrl(p.plain);
   if (url) {
     const title = anchorTextFromHtml(p.html) ?? prettifyUrl(url);
@@ -242,6 +260,45 @@ export function showCanvasToast(message: string): void {
 export interface MediaDropCallbacks {
   onImage: (file: File, world: [number, number]) => void;
   onLink: (url: string, title: string, world: [number, number]) => void;
+  /**
+   * DDR-148 — a video/audio file was dropped. Optional: when omitted, the hook
+   * uploads it to `assets/` and toasts a ready-to-use `<Video>`/`<Audio>`
+   * snippet (the drop-then-reference flow). A future host can provide this to
+   * auto-insert the element into the composition TSX (the deferred slice — the
+   * comp-placement question, see DDR-148 open items).
+   */
+  onMedia?: (file: File, mediaKind: 'video' | 'audio', world: [number, number]) => void;
+}
+
+/** The snippet the toast surfaces so the dropped clip is one paste away. */
+export function mediaSnippet(mediaKind: 'video' | 'audio', assetPath: string): string {
+  if (mediaKind === 'audio') return `<Audio src="${assetPath}" />`;
+  return `<Video src="${assetPath}" />`;
+}
+
+/**
+ * Default media-drop handler: upload the file to the widened asset route, then
+ * toast the `assets/…` path + the snippet to paste into the comp. Copies the
+ * snippet to the clipboard when available. Exported for reuse/testing.
+ */
+export async function uploadAndAnnounceMedia(
+  file: File,
+  mediaKind: 'video' | 'audio'
+): Promise<void> {
+  const sizeMb = file.size / (1024 * 1024);
+  const res = await uploadAsset(file);
+  if ('error' in res) {
+    showCanvasToast(`Couldn't add ${mediaKind}: ${res.error}`);
+    return;
+  }
+  const snippet = mediaSnippet(mediaKind, res.path);
+  try {
+    await navigator.clipboard?.writeText(snippet);
+  } catch {
+    /* clipboard unavailable — the toast still shows the snippet */
+  }
+  const warn = sizeMb > 20 ? ' · ⚠ >20 MB rides git + sync' : '';
+  showCanvasToast(`Added ${res.path}${warn} — snippet copied: ${snippet}`);
 }
 
 export function useCanvasMediaDrop(opts: {
@@ -317,7 +374,12 @@ export function useCanvasMediaDrop(opts: {
 
     const dispatchIntent = (intent: MediaIntent, world: [number, number]) => {
       if (intent.kind === 'image') callbacks.onImage(intent.file, world);
-      else if (isHttpUrl(intent.url)) callbacks.onLink(intent.url, intent.title, world);
+      else if (intent.kind === 'media') {
+        if (callbacks.onMedia) callbacks.onMedia(intent.file, intent.mediaKind, world);
+        else void uploadAndAnnounceMedia(intent.file, intent.mediaKind);
+      } else if (intent.kind === 'link' && isHttpUrl(intent.url)) {
+        callbacks.onLink(intent.url, intent.title, world);
+      }
     };
 
     document.addEventListener('dragover', onDragOver);