@1agh/maude 0.39.1 → 0.40.0

package/README.md

@@ -11,7 +11,7 @@ A personal marketplace of Claude Code plugins. Two plugins today, plus a `maude`
 
 | Plugin | What it does |
 | ------ | ------------ |
-| **`design`** | Canvas-first iteration on TSX/JSX mocks under `.design/` — element selection via Cmd+Click, auto-managed dev server, chained UX/DS critique. |
+| **`design`** | Canvas-first iteration on TSX/JSX mocks under `.design/` — element selection via Cmd+Click, auto-managed dev server, chained UX/DS critique. Canvases can also be **video-comps** (Remotion compositions previewed in-app, exported to MP4/GIF through Maude's own capture engine — no extra install). |
 | **`flow`** | Generic agentic workflow loop with a second-brain `.ai/` workspace. `/flow:plan`, `/flow:execute`, `/flow:utils-verify`, `/flow:validate`, `/flow:done`, `/flow:init`, `/flow:record-ddr`, `/flow:scenario`, …. Project-agnostic via `<project>` placeholders + per-repo `.ai/workflows.config.json`. |
 
 Plus the **`maude`** CLI — `maude init` scaffolds a fresh `.ai/` workspace from the flow plugin skeleton; `maude design serve` boots the design dev server. The legacy `mdcc` alias still works (prints a deprecation warning) and will be removed in v0.17.x.

package/apps/studio/annotations-context-toolbar.tsx

@@ -827,9 +827,52 @@ export function AnnotationContextToolbar({
   // fall through to the generic bar below.
   const soleMedia =
     selectedStrokes.length === 1 &&
-    (selectedStrokes[0]?.tool === 'image' || selectedStrokes[0]?.tool === 'link')
+    (selectedStrokes[0]?.tool === 'image' ||
+      selectedStrokes[0]?.tool === 'link' ||
+      selectedStrokes[0]?.tool === 'mediaref')
       ? selectedStrokes[0]
       : null;
+  if (soleMedia?.tool === 'mediaref') {
+    // DDR-150 dogfood — a media-reference chip has no color to set (the generic
+    // swatch palette was meaningless noise). Focused panel: filename + delete.
+    const mr = soleMedia;
+    return (
+      <div
+        ref={ref}
+        className="dc-annot-ctx"
+        role="toolbar"
+        aria-label="Media reference properties"
+        style={{ display: 'flex', top: -9999, left: -9999 }}
+      >
+        <span
+          className="dc-annot-ctx-label"
+          style={{
+            padding: '0 8px',
+            fontSize: 12,
+            opacity: 0.85,
+            maxWidth: 220,
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}
+          title={`${mr.mediaKind} · ${mr.src}`}
+        >
+          {mr.mediaKind === 'audio' ? '♪ ' : '▶ '}
+          {mr.title}
+        </span>
+        <div className="dc-annot-ctx-sep" />
+        <button
+          type="button"
+          className="dc-annot-ctx-ibtn dc-annot-ctx-ibtn--danger"
+          aria-label="Delete media reference"
+          title="Delete"
+          onClick={remove}
+        >
+          <IconTrash />
+        </button>
+      </div>
+    );
+  }
   if (soleMedia?.tool === 'image') {
     const img = soleMedia;
     const commitAlt = (value: string) => {

package/apps/studio/annotations-layer.tsx

@@ -93,6 +93,12 @@ import {
   linkCardLayout,
   listPrefixedBody,
   listPrefixedLine,
+  MEDIAREF_AUDIO_GLYPH,
+  MEDIAREF_DEFAULT_H,
+  MEDIAREF_DEFAULT_W,
+  MEDIAREF_VIDEO_GLYPH,
+  MEDIAREF_VIDEO_H,
+  type MediaRefStroke,
   normalizeBox,
   normalizeRect,
   normalizeSticky,
@@ -380,6 +386,19 @@ function resolveAssetHref(href: string): string {
   return /^assets\//.test(href) ? `/${canvasDesignRel()}/${href}` : href;
 }
 
+/**
+ * DDR-150 dogfood #8 — true when a pointer/click event targets the inline
+ * media player inside a mediaref chip. Every document-capture annotation
+ * handler early-returns on it, so the player's native controls (and its
+ * click-to-toggle) work instead of starting a stroke select/drag/draw.
+ * (NOT a stopPropagation guard — that would also kill React's delegated
+ * listeners, which attach later on the capture path.)
+ */
+function isMediaPlayerTarget(e: Event): boolean {
+  const t = e.target as Element | null;
+  return !!(t && typeof t.closest === 'function' && t.closest('[data-mediaref-player]'));
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Styles
 
@@ -1167,15 +1186,63 @@ export function AnnotationsLayer() {
     [commitStrokes, annotSel]
   );
 
+  // Media reference (DDR-150 P4): a video/audio file dropped on the canvas BODY
+  // becomes a versioned reference chip (NOT a source insert, NOT a played
+  // element) carrying its assets/ path — the "nahazet klipy → agent z toho udělá
+  // video" artifact. Upload to assets/, then commit a MediaRefStroke; on failure
+  // toast. No poster probe in v1 — a media glyph tile (▶/♪) + filename.
+  const createMediaReference = useCallback(
+    (file: File, mediaKind: 'video' | 'audio', world: [number, number]) => {
+      const w = MEDIAREF_DEFAULT_W;
+      // Video chips are taller — they host the inline 16:9 player (dogfood #8).
+      const h = mediaKind === 'video' ? MEDIAREF_VIDEO_H : MEDIAREF_DEFAULT_H;
+      void uploadAsset(file).then((res) => {
+        if (!('path' in res)) {
+          showCanvasToast(`Couldn't add ${mediaKind}: ${res.error}`);
+          return;
+        }
+        const id = rid();
+        const ref: MediaRefStroke = {
+          id,
+          tool: 'mediaref',
+          x: world[0] - w / 2,
+          y: world[1] - h / 2,
+          w,
+          h,
+          src: res.path,
+          mediaKind,
+          title: (file.name || res.path).slice(0, 300),
+        };
+        const before = strokesRef.current;
+        commitStrokes(before, [...before, ref], `add ${mediaKind} reference`);
+        annotSel?.replace([id]);
+        const sizeMb = file.size / (1024 * 1024);
+        showCanvasToast(
+          `Added ${mediaKind} reference · ${res.path}${sizeMb > 20 ? ' · ⚠ >20 MB rides git + sync' : ''}`
+        );
+      });
+    },
+    [commitStrokes, annotSel]
+  );
+
   const mediaCallbacks = useMemo(
-    () => ({ onImage: createImageFromFile, onLink: createLink }),
-    [createImageFromFile, createLink]
+    () => ({ onImage: createImageFromFile, onLink: createLink, onMedia: createMediaReference }),
+    [createImageFromFile, createLink, createMediaReference]
   );
   // Media intake is paste/drop only (per product steer — no toolbar buttons):
   // drop an image / URL or Cmd+V a clipboard image / link straight onto the
   // canvas. The hook owns the dragover/drop/paste wiring; the create callbacks
   // hold the commit/undo sink + screenToWorld.
-  useCanvasMediaDrop({ enabled: visible, screenToWorld, callbacks: mediaCallbacks });
+  //
+  // DDR-150 dogfood #8 — intake was gated on `visible` (annotations toggled on),
+  // so with annotations hidden (⇧P) a Finder drop silently did NOTHING. Intake
+  // now stays live whenever we're not presenting; the committed stroke simply
+  // shows once annotations are visible again.
+  useCanvasMediaDrop({
+    enabled: !(chrome?.present ?? false),
+    screenToWorld,
+    callbacks: mediaCallbacks,
+  });
 
   const eraseAt = useCallback(
     (wx: number, wy: number) => {
@@ -1636,6 +1703,7 @@ export function AnnotationsLayer() {
           t === 'sticky' ||
           t === 'image' ||
           t === 'link' ||
+          t === 'mediaref' ||
           t === 'section')
       ) {
         return id;
@@ -1644,6 +1712,7 @@ export function AnnotationsLayer() {
     };
 
     const onDown = (e: PointerEvent) => {
+      if (isMediaPlayerTarget(e)) return; // mediaref inline player owns this event
       if (e.button !== 0) return;
       if (e.metaKey || e.ctrlKey) return; // escape hatch into element-selection
       const target = e.target as Element | null;
@@ -1937,6 +2006,7 @@ export function AnnotationsLayer() {
     if (typeof document === 'undefined') return;
     if (tool !== 'move') return;
     const onDbl = (e: MouseEvent) => {
+      if (isMediaPlayerTarget(e)) return; // mediaref inline player owns this event
       const target = e.target as Element | null;
       const node = target?.closest?.('[data-id][data-tool]');
       if (!node) return;
@@ -2460,6 +2530,7 @@ export function AnnotationsLayer() {
     if (typeof document === 'undefined') return;
     if (tool !== 'move') return;
     const onDown = (e: PointerEvent) => {
+      if (isMediaPlayerTarget(e)) return; // mediaref inline player owns this event
       if (e.button !== 0) return;
       const dot = (e.target as Element | null)?.closest?.('.dc-annot-conn-dot');
       if (!dot) return;
@@ -2575,6 +2646,7 @@ export function AnnotationsLayer() {
     // propagation WITHOUT preventDefault, so the native contextmenu event
     // (which opens OUR menu above) still follows.
     const onDown = (e: PointerEvent) => {
+      if (isMediaPlayerTarget(e)) return; // mediaref inline player owns this event
       if (e.button !== 2) return;
       if (!strokeAt(e.target as Element | null)) return;
       e.stopImmediatePropagation();
@@ -2724,6 +2796,10 @@ export function AnnotationsLayer() {
           onCancelEdit={cancelEditing}
         />
       ) : null}
+      {/* DDR-150 dogfood #8 — inline players for media-reference chips (HTML
+          overlay in the world div; see MediaRefPlayers for why not
+          foreignObject). */}
+      <MediaRefPlayers worldRef={worldRef} strokes={renderStrokes} visible={visible} />
       <AnnotationContextToolbar
         editingId={
           editingTarget?.kind === 'anchored'
@@ -3110,6 +3186,92 @@ function AnnotationsSvg({
   );
 }
 
+/**
+ * DDR-150 dogfood #8 — the mediaref chips' inline players, rendered as PLAIN
+ * HTML absolutely positioned in the world div (which carries the pan/zoom CSS
+ * transform), NOT as SVG foreignObject: Chromium hit-tests foreignObject
+ * content under a transformed ancestor in the un-transformed coordinate space,
+ * so real clicks miss the player at most zoom levels. HTML children of the
+ * transformed div hit-test correctly. The [data-mediaref-player] attr keeps
+ * every document-capture annotation handler out (isMediaPlayerTarget guard).
+ */
+function MediaRefPlayers({
+  worldRef,
+  strokes,
+  visible,
+}: {
+  worldRef: React.RefObject<HTMLElement | null>;
+  strokes: readonly Stroke[];
+  visible: boolean;
+}) {
+  const target = worldRef.current;
+  if (!target || !visible) return null;
+  const HEADER = 26;
+  const refs = strokes.filter(
+    (s): s is MediaRefStroke => s.tool === 'mediaref' && !!s.src && Math.abs(s.h) > HEADER + 12
+  );
+  if (refs.length === 0) return null;
+  return createPortal(
+    <>
+      {refs.map((s) => {
+        const x = Math.min(s.x, s.x + s.w);
+        const y = Math.min(s.y, s.y + s.h);
+        const w = Math.abs(s.w);
+        const h = Math.abs(s.h);
+        const mediaUrl = resolveAssetHref(s.src);
+        const isAudio = s.mediaKind === 'audio';
+        return (
+          <div
+            key={`mrp-${s.id}`}
+            data-mediaref-player="1"
+            style={{
+              position: 'absolute',
+              left: x + 4,
+              top: y + HEADER,
+              width: Math.max(8, w - 8),
+              height: Math.max(8, h - HEADER - 4),
+              borderRadius: 6,
+              overflow: 'hidden',
+              zIndex: 4,
+            }}
+          >
+            {isAudio ? (
+              // biome-ignore lint/a11y/useMediaCaption: user-dropped reference media — there is no caption source to point a <track> at.
+              <audio
+                controls
+                preload="metadata"
+                src={mediaUrl}
+                style={{ width: '100%', height: '100%' }}
+              />
+            ) : (
+              // biome-ignore lint/a11y/useMediaCaption: user-dropped reference media — no caption source exists for an arbitrary dragged-in clip.
+              <video
+                // Chromium's native controls already toggle play/pause on a
+                // content-area click (a custom click listener would double-fire
+                // against it and cancel itself out — verified live). The router
+                // overlay-skip + the annotation-handler guards are what make
+                // these native interactions reachable.
+                controls
+                preload="metadata"
+                playsInline
+                src={mediaUrl}
+                style={{
+                  width: '100%',
+                  height: '100%',
+                  objectFit: 'contain',
+                  background: '#000',
+                  display: 'block',
+                }}
+              />
+            )}
+          </div>
+        );
+      })}
+    </>,
+    target
+  );
+}
+
 function TextEditor({
   anchorId,
   host,
@@ -3165,6 +3327,7 @@ function TextEditor({
   useEffect(() => {
     if (typeof document === 'undefined') return;
     const onDown = (e: PointerEvent) => {
+      if (isMediaPlayerTarget(e)) return; // mediaref inline player owns this event
       const el = ref.current;
       if (!el) return;
       if (el.contains(e.target as Node)) return;
@@ -3427,6 +3590,7 @@ function StandaloneTextEditor({
   useEffect(() => {
     if (typeof document === 'undefined') return;
     const onDown = (e: PointerEvent) => {
+      if (isMediaPlayerTarget(e)) return; // mediaref inline player owns this event
       const el = ref.current;
       if (!el) return;
       if (el.contains(e.target as Node)) return;
@@ -3609,6 +3773,7 @@ function AnnotationContextMenu({
     if (nx !== at.x || ny !== at.y) setAt({ x: nx, y: ny });
     el.querySelector<HTMLButtonElement>('button.dc-menu-item:not([disabled])')?.focus();
     const onDown = (e: PointerEvent) => {
+      if (isMediaPlayerTarget(e)) return; // mediaref inline player owns this event
       if (!el.contains(e.target as Node)) onClose();
     };
     const onKey = (e: KeyboardEvent) => {
@@ -4176,6 +4341,91 @@ function StrokeNodeBase({
       </g>
     );
   }
+  if (stroke.tool === 'mediaref') {
+    // DDR-150 P4 + dogfood #8 — reference chip with a REAL inline player.
+    // LIVE-RENDER ONLY: the <foreignObject> + <video>/<audio> below never
+    // persist — the model serializer still writes the sanitizer-safe data-*
+    // card (foreignObject is stripped by sanitizeAnnotationSvg by design).
+    // The 26px header strip (badge + filename) is the select/drag handle; the
+    // player area is fenced off from the annotation handlers by the
+    // [data-mediaref-player] window-capture guard.
+    const x = Math.min(stroke.x, stroke.x + stroke.w);
+    const y = Math.min(stroke.y, stroke.y + stroke.h);
+    const w = Math.abs(stroke.w);
+    const h = Math.abs(stroke.h);
+    const HEADER = 26;
+    const isAudio = stroke.mediaKind === 'audio';
+    const mediaUrl = stroke.src ? resolveAssetHref(stroke.src) : '';
+    const shownTitle = clampLinkTitle(stroke.title, Math.max(8, Math.floor((w - 40) / 7)));
+    const textFont = {
+      fontFamily: 'var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)',
+    } as const;
+    return (
+      <g
+        data-id={stroke.id}
+        data-tool="mediaref"
+        data-src={stroke.src}
+        data-media-kind={stroke.mediaKind}
+        data-title={stroke.title}
+        pointerEvents={hitMode}
+      >
+        <rect
+          x={x}
+          y={y}
+          width={w}
+          height={h}
+          rx={8}
+          ry={8}
+          fill={LINK_CARD_FILL}
+          stroke={LINK_CARD_STROKE}
+          strokeWidth={1}
+          vectorEffect="non-scaling-stroke"
+          filter="url(#dc-sticky-shadow)"
+        />
+        <svg
+          x={x + 8}
+          y={y + 5}
+          width={16}
+          height={16}
+          viewBox="0 0 24 24"
+          fill={LINK_GLYPH_STROKE}
+          stroke="none"
+          aria-hidden="true"
+        >
+          <path d={isAudio ? MEDIAREF_AUDIO_GLYPH : MEDIAREF_VIDEO_GLYPH} />
+        </svg>
+        <text
+          x={x + 30}
+          y={y + 9}
+          fontSize={11}
+          fill={LINK_TITLE_FILL}
+          fontWeight={600}
+          dominantBaseline="hanging"
+          style={textFont}
+        >
+          {shownTitle}
+        </text>
+        {/* The inline player itself is an HTML overlay portaled beside this SVG
+            (MediaRefPlayers below) — NOT a foreignObject: Chromium hit-tests
+            foreignObject content under a CSS-transformed ancestor in the WRONG
+            coordinate space (the un-panned/un-zoomed one), so real clicks miss
+            the player at most zoom levels while elementFromPoint lies that
+            they'd land. Plain HTML in the transformed world hit-tests right. */}
+        {!mediaUrl ? (
+          <text
+            x={x + 30}
+            y={y + HEADER + 10}
+            fontSize={10}
+            fill={LINK_DOMAIN_FILL}
+            dominantBaseline="hanging"
+            style={textFont}
+          >
+            (missing media reference)
+          </text>
+        ) : null}
+      </g>
+    );
+  }
   if (stroke.tool === 'section') {
     const x = Math.min(stroke.x, stroke.x + stroke.w);
     const y = Math.min(stroke.y, stroke.y + stroke.h);

package/apps/studio/annotations-model.ts

@@ -266,6 +266,30 @@ export interface LinkStroke extends StrokeBase {
   title: string;
   domain: string;
 }
+/**
+ * DDR-150 P4 — a video/audio file dropped on the canvas BODY (not the timeline)
+ * as a reference chip. It's the "nahazet klipy → agent z toho udělá video"
+ * artifact: a non-destructive, versioned pointer to an `assets/…` clip the agent
+ * can enumerate off the saved `.annotations.svg` (via `data-src`), then assemble
+ * into a comp. Distinct from a timeline drop (which INSERTS a `<Sequence>`) and
+ * from an ImageStroke (a rendered picture). Renders as a card: a media glyph
+ * (▶ video / ♪ audio) + the filename. `src` is ALWAYS a relative `assets/<sha8>`
+ * path (never seeked by the capture spine — it's a reference, excluded from
+ * export by `?hide-chrome`). Persists as an allowlisted `<g>` like LinkStroke —
+ * `data-src`/`data-media-kind`/`data-title` are the round-trip source of truth.
+ */
+export interface MediaRefStroke extends StrokeBase {
+  tool: 'mediaref';
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** Relative `assets/<sha8>.<ext>` path — the agent reads this off the SVG. */
+  src: string;
+  mediaKind: 'video' | 'audio';
+  /** Human-facing label (the dropped file's name). */
+  title: string;
+}
 /**
  * FigJam v3 — section: a labelled organizing container. Renders as a soft
  * rounded region with a name chip above the top-left corner; its INTERIOR is
@@ -294,6 +318,7 @@ export type Stroke =
   | StickyStroke
   | ImageStroke
   | LinkStroke
+  | MediaRefStroke
   | SectionStroke;
 
 /**
@@ -528,6 +553,11 @@ export const IMAGE_MIN_SIZE = 16;
 export const IMAGE_MAX_DROP_SIDE = 480;
 export const LINK_DEFAULT_W = 260;
 export const LINK_DEFAULT_H = 76;
+// DDR-150 P4 — media-reference chip (dropped video/audio → assets/ pointer).
+export const MEDIAREF_DEFAULT_W = 280;
+export const MEDIAREF_DEFAULT_H = 76;
+/** Video chips are taller: 26px header + a 16:9 inline player area (dogfood #8). */
+export const MEDIAREF_VIDEO_H = 190;
 export const LINK_CARD_FILL = '#ffffff';
 export const LINK_CARD_STROKE = '#d4d4d8';
 export const LINK_DOMAIN_FILL = '#71717a';
@@ -539,6 +569,12 @@ export const LINK_GLYPH_STROKE = '#52525b';
 // <rect> geometry), so render/serialize only need to agree visually.
 export const LINK_GLYPH_D1 = 'M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71';
 export const LINK_GLYPH_D2 = 'M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71';
+// DDR-150 P4 — media-reference chip glyphs (24×24 viewBox, filled). One source
+// for serialize + StrokeNode render, like the link glyph. Video = play triangle;
+// audio = a filled note. The parser ignores the glyph (reads data-* + geometry).
+export const MEDIAREF_VIDEO_GLYPH = 'M8 5v14l11-7z';
+export const MEDIAREF_AUDIO_GLYPH =
+  'M9 18V6l10-2v11.5a2.5 2.5 0 1 1-2-2.45V7.3L11 8.6v6.9a2.5 2.5 0 1 1-2-2.45z';
 
 /** Card text positions, derived purely from the bbox (idempotent round-trip). */
 export function linkCardLayout(x: number, y: number, w: number, h: number) {
@@ -1038,6 +1074,37 @@ function strokeToSvgElBase(s: Stroke): string {
       `</g>`
     );
   }
+  if (s.tool === 'mediaref') {
+    // DDR-150 P4 — reference chip for a dropped clip. Like the link card: the
+    // data-* are the round-trip source of truth (the agent reads data-src to
+    // enumerate refs); the inner rect/glyph/text are the inert, sanitizer-safe
+    // visual. NEVER a <Video>/<Audio> element (that would try to play/seek) —
+    // it's a pointer, drawn as a still card.
+    const nx = Math.min(s.x, s.x + s.w);
+    const ny = Math.min(s.y, s.y + s.h);
+    const nw = Math.abs(s.w);
+    const nh = Math.abs(s.h);
+    const lay = linkCardLayout(nx, ny, nw, nh);
+    const shownTitle = clampLinkTitle(s.title, lay.textMaxChars);
+    const glyph =
+      s.mediaKind === 'audio'
+        ? `<path d="${MEDIAREF_AUDIO_GLYPH}"/>`
+        : `<path d="${MEDIAREF_VIDEO_GLYPH}"/>`;
+    return (
+      `<g data-id="${esc(s.id)}" data-tool="mediaref" data-src="${escAttr(s.src)}" data-media-kind="${escAttr(
+        s.mediaKind
+      )}" data-title="${escAttr(s.title)}">` +
+      `<rect x="${nx}" y="${ny}" width="${nw}" height="${nh}" rx="8" ry="8" fill="${LINK_CARD_FILL}" stroke="${LINK_CARD_STROKE}" stroke-width="1"/>` +
+      `<svg x="${lay.glyph.x}" y="${lay.glyph.y}" width="${lay.glyph.size}" height="${lay.glyph.size}" viewBox="0 0 24 24" fill="${LINK_GLYPH_STROKE}" stroke="none">${glyph}</svg>` +
+      `<text x="${lay.textX}" y="${lay.domain.y}" font-size="${lay.domain.fontSize}" fill="${LINK_DOMAIN_FILL}" dominant-baseline="hanging">${esc(
+        `${s.mediaKind} · reference`
+      )}</text>` +
+      `<text x="${lay.textX}" y="${lay.title.y}" font-size="${lay.title.fontSize}" fill="${LINK_TITLE_FILL}" font-weight="600" dominant-baseline="hanging">${esc(
+        shownTitle
+      )}</text>` +
+      `</g>`
+    );
+  }
   if (s.tool === 'section') {
     // FigJam v3 — inert persisted form: region rect + chip label text. Colors
     // are render-time chrome; the parser reads geometry off the rect and the
@@ -1463,6 +1530,22 @@ export function svgToStrokes(svgText: string): Stroke[] {
         push({ id, tool: 'link', x, y, w, h, url, title, domain });
         continue;
       }
+      if (tool === 'mediaref') {
+        // DDR-150 P4 — geometry off the <rect> child (mirrors link/sticky);
+        // data-src is the pointer the agent enumerates. A src that fails the
+        // assets/ shape is dropped to '' (an inert chip that references nothing).
+        const rectEl = el.querySelector('rect');
+        const x = pfloat(rectEl?.getAttribute('x'));
+        const y = pfloat(rectEl?.getAttribute('y'));
+        const w = pfloat(rectEl?.getAttribute('width'), MEDIAREF_DEFAULT_W);
+        const h = pfloat(rectEl?.getAttribute('height'), MEDIAREF_DEFAULT_H);
+        const rawSrc = el.getAttribute('data-src') || '';
+        const src = ASSET_MEDIA_SRC_RE.test(rawSrc) ? rawSrc : '';
+        const mediaKind = el.getAttribute('data-media-kind') === 'audio' ? 'audio' : 'video';
+        const title = el.getAttribute('data-title') || src;
+        push({ id, tool: 'mediaref', x, y, w, h, src, mediaKind, title });
+        continue;
+      }
       if (tool === 'text') {
         const rawAnchor = el.getAttribute('data-anchor-id');
         const fontSize =
@@ -1650,8 +1733,8 @@ export function strokeHitTest(s: Stroke, wx: number, wy: number, tol: number): b
     return onEdge;
   }
   const t = Math.max(tol, 'width' in s ? s.width : 2);
-  if (s.tool === 'sticky' || s.tool === 'image' || s.tool === 'link') {
-    // Sticky / image / link are solid cards — filled-rect hit anywhere inside.
+  if (s.tool === 'sticky' || s.tool === 'image' || s.tool === 'link' || s.tool === 'mediaref') {
+    // Sticky / image / link / mediaref are solid cards — filled-rect hit inside.
     const xMin = Math.min(s.x, s.x + s.w);
     const xMax = Math.max(s.x, s.x + s.w);
     const yMin = Math.min(s.y, s.y + s.h);
@@ -1844,6 +1927,8 @@ export function isStrokeMeaningful(s: Stroke): boolean {
   // Phase 23 — an image needs real extent; a link needs a non-empty URL.
   if (s.tool === 'image') return Math.abs(s.w) >= IMAGE_MIN_SIZE && Math.abs(s.h) >= IMAGE_MIN_SIZE;
   if (s.tool === 'link') return s.url.trim().length > 0;
+  // A media-reference chip needs a non-empty assets/ src (its whole purpose).
+  if (s.tool === 'mediaref') return s.src.trim().length > 0;
   if (s.tool === 'section')
     return Math.abs(s.w) >= SECTION_MIN_SIZE && Math.abs(s.h) >= SECTION_MIN_SIZE;
   return Math.hypot(s.x2 - s.x1, s.y2 - s.y1) >= 4;
@@ -1886,9 +1971,15 @@ export function strokeBBox(
       h: Math.abs(s.y2 - s.y1),
     };
   }
-  if (s.tool === 'sticky' || s.tool === 'image' || s.tool === 'link' || s.tool === 'section') {
-    // Phase 23 — image + link are rect-shaped media, same bbox as a sticky
-    // card; FigJam v3 sections share it too.
+  if (
+    s.tool === 'sticky' ||
+    s.tool === 'image' ||
+    s.tool === 'link' ||
+    s.tool === 'mediaref' ||
+    s.tool === 'section'
+  ) {
+    // Phase 23 — image + link + mediaref are rect-shaped cards, same bbox as a
+    // sticky; FigJam v3 sections share it too.
     return {
       x: Math.min(s.x, s.x + s.w),
       y: Math.min(s.y, s.y + s.h),
@@ -1928,7 +2019,13 @@ export function translateOne(s: Stroke, dx: number, dy: number): Stroke {
   if (s.tool === 'ellipse') return { ...s, cx: s.cx + dx, cy: s.cy + dy };
   if (s.tool === 'arrow')
     return { ...s, x1: s.x1 + dx, y1: s.y1 + dy, x2: s.x2 + dx, y2: s.y2 + dy };
-  if (s.tool === 'sticky' || s.tool === 'image' || s.tool === 'link' || s.tool === 'section')
+  if (
+    s.tool === 'sticky' ||
+    s.tool === 'image' ||
+    s.tool === 'link' ||
+    s.tool === 'mediaref' ||
+    s.tool === 'section'
+  )
     return { ...s, x: s.x + dx, y: s.y + dy };
   // text — anchored inherits its host's bbox (moves with the host); standalone
   // (Phase 21) carries its own world (x, y) and translates directly.
@@ -1997,6 +2094,10 @@ export const ANNOTATION_SVG_ELEMENTS = new Set([
  * is stripped by Rule 3. Pairs with the asset-write caps (DDR Task 9).
  */
 export const ASSET_IMAGE_HREF_RE = /^assets\/[A-Za-z0-9._-]+\.(?:png|jpe?g|webp|gif)$/;
+// DDR-150 P4 — a media-reference chip's data-src: a relative assets/ path to a
+// video/audio clip (no scheme, no traversal). Same shape as the image href gate.
+export const ASSET_MEDIA_SRC_RE =
+  /^assets\/[A-Za-z0-9._-]+\.(?:mp4|webm|mov|m4v|mp3|wav|m4a|aac|ogg)$/;
 
 /**
  * A3 (DDR-060 F1 re-audit) — sanitize an annotation SVG before it is persisted /