@1agh/maude 0.39.0 → 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/acp/bridge.ts

@@ -8,7 +8,7 @@
 // (env.ts): the child inherits the environment MINUS `ANTHROPIC_API_KEY`, so
 // auth precedence falls through to the user's Pro/Max subscription.
 
-import { appendFile, mkdir } from 'node:fs/promises';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 
 import {
@@ -71,6 +71,29 @@ const EFFORT_THINKING_TOKENS: Record<string, number | null> = {
 
 export type AcpEffort = keyof typeof EFFORT_THINKING_TOKENS;
 
+// Real sessionIds are adapter-generated `randomUUID()`s. A persisted value that
+// doesn't look like one (corrupt sidecar, or a tracked file a cloned repo
+// shipped despite `_chat/` being gitignored — DDR-115) is rejected rather than
+// forwarded into the privileged `loadSession` ACP call.
+const VALID_SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+// `loadSession`'s replay can, in principle, never settle if the underlying
+// transport dies mid-call (adapter crash, a concurrent `stop()` from another
+// chat sharing this bridge). Bound it so `replaying` always resets and a
+// resume attempt always falls back to `newSession` instead of wedging the
+// bridge silent forever. Mirrors the `withTimeout`/`TIMED_OUT` pattern already
+// used for network calls in `apps/studio/git/service.ts`.
+const LOAD_SESSION_TIMEOUT_MS = 15_000;
+const TIMED_OUT = Symbol('maude-acp-load-session-timeout');
+function withTimeout<T>(p: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT> {
+  p.catch(() => {});
+  let timer: ReturnType<typeof setTimeout>;
+  const t = new Promise<typeof TIMED_OUT>((res) => {
+    timer = setTimeout(() => res(TIMED_OUT), ms);
+  });
+  return Promise.race([p, t]).finally(() => clearTimeout(timer));
+}
+
 /**
  * Build the `session/new` params, carrying TWO adapter-internal `_meta` payloads
  * (both spread by the installed `claude-agent-acp@0.49.x` `newSession`):
@@ -90,6 +113,10 @@ export type AcpEffort = keyof typeof EFFORT_THINKING_TOKENS;
  * must fail the presence tests LOUDLY (acp-bootstrap-brief.test.ts +
  * acp-session-plugins.test.ts), not silently un-brief / un-plugin every session.
  * Exported for those tests.
+ *
+ * `cwd`/`mcpServers`/`_meta` are also exactly the shared fields of a
+ * `LoadSessionRequest` (schema/types.gen.d.ts) — `sessionFor`'s resume path
+ * spreads this same object and adds `sessionId` rather than duplicating it.
  */
 export function newSessionParams(
   repoRoot: string,
@@ -136,12 +163,21 @@ export class AcpBridge {
   // context. The adapter (one subprocess) holds them all; switching chats reuses
   // the session, so claude remembers that chat while the app is open.
   private sessions = new Map<string, string>(); // chatId → sessionId
+  // In-flight sessionFor() calls, keyed by chatId — lets a `warm` and a `prompt`
+  // racing for the same chat share one resume/create attempt instead of each
+  // running establishSession() and stomping the single shared `replaying` flag.
+  private sessionPromises = new Map<string, Promise<string>>();
   private currentSession: string | null = null; // the in-flight prompt's session
   /** Sessions whose bootstrap brief already hit the transcript (audit record). */
   private briefLogged = new Set<string>();
   private starting: Promise<void> | null = null;
   /** Per-chat transcript file (`_chat/<id>.jsonl`); set per prompt. */
   private transcriptPath: string | null = null;
+  /** Sidecar persisting this chat's ACP sessionId across restarts (`_chat/<id>.session.json`). */
+  private sessionStorePath: string | null = null;
+  /** True while `conn.loadSession()` is replaying a resumed session's history
+   *  back through the `sessionUpdate` client callback — see the guard in `start()`. */
+  private replaying = false;
   // Model + effort are env-at-spawn (ANTHROPIC_MODEL / MAX_THINKING_TOKENS), so a
   // change re-spawns the adapter. `desired*` is what the UI asked for; `active*`
   // is what the running session was spawned with.
@@ -165,6 +201,10 @@ export class AcpBridge {
     this.transcriptPath = path;
   }
 
+  setSessionStorePath(path: string | null): void {
+    this.sessionStorePath = path;
+  }
+
   /** Desired model (alias/id, or null for the user's default) + effort. Applied
    *  on the next prompt — re-spawning the adapter only if it actually changed. */
   setConfig(model: string | null, effort: AcpEffort): void {
@@ -187,18 +227,104 @@ export class AcpBridge {
     return this.starting;
   }
 
-  /** Get-or-create the ACP session for a chat id (one claude context per chat). */
+  /**
+   * Get-or-create the ACP session for a chat id (one claude context per chat).
+   * `warm` and `prompt` can both reach this for the same chat close together
+   * (composer autocomplete warm-up racing the user hitting send) — a second
+   * concurrent call for the same chatId shares the FIRST call's in-flight
+   * promise (mirrors `ensureStarted`'s `this.starting` pattern) rather than
+   * re-entering resume/create and stomping the single shared `replaying` flag.
+   */
   private async sessionFor(chatId: string): Promise<string> {
     const existing = this.sessions.get(chatId);
     if (existing) return existing;
+    const inFlight = this.sessionPromises.get(chatId);
+    if (inFlight) return inFlight;
+
+    const promise = this.establishSession(chatId).finally(() => {
+      this.sessionPromises.delete(chatId);
+    });
+    this.sessionPromises.set(chatId, promise);
+    return promise;
+  }
+
+  /**
+   * Resumes a session persisted from a PRIOR app/dev-server lifetime (the
+   * cross-restart memory gap tracked in DDR-125) via the adapter's `loadSession`
+   * before falling back to a brand-new `newSession` — either because this chat
+   * has never had a session, or because the resume attempt failed (e.g. the
+   * underlying claude session was pruned, `claude` was reinstalled, or the
+   * adapter's response never arrives — `loadSession` is time-boxed so a dead
+   * transport can't wedge `replaying` true forever and silently black-hole
+   * every future turn on this bridge).
+   */
+  private async establishSession(chatId: string): Promise<string> {
     if (!this.conn) throw new Error('ACP adapter not started');
-    const created = await this.conn.newSession(
-      newSessionParams(this.opts.repoRoot, this.opts.studioBrief, this.opts.plugins)
-    );
+
+    const params = newSessionParams(this.opts.repoRoot, this.opts.studioBrief, this.opts.plugins);
+    const persistedId = await this.readPersistedSessionId();
+    if (persistedId) {
+      try {
+        this.replaying = true;
+        const result = await withTimeout(
+          this.conn.loadSession({ ...params, sessionId: persistedId }),
+          LOAD_SESSION_TIMEOUT_MS
+        );
+        if (result === TIMED_OUT) {
+          throw new Error(`loadSession timed out after ${LOAD_SESSION_TIMEOUT_MS}ms`);
+        }
+        this.sessions.set(chatId, persistedId);
+        return persistedId;
+      } catch (err) {
+        await this.appendTranscript({
+          role: 'bootstrap',
+          kind: 'resume-failed',
+          error: err instanceof Error ? err.message : String(err),
+        });
+      } finally {
+        this.replaying = false;
+      }
+    }
+
+    const created = await this.conn.newSession(params);
     this.sessions.set(chatId, created.sessionId);
+    await this.writePersistedSessionId(created.sessionId);
     return created.sessionId;
   }
 
+  /** Read the sessionId persisted for this chat by a prior bridge lifetime.
+   *  Null when there's no sidecar wired (e.g. warm-up before any prompt), the
+   *  file doesn't exist yet (first-ever turn), it's unreadable/corrupt, or its
+   *  `sessionId` doesn't look like a real one (defense-in-depth — this file's
+   *  directory is per-machine/gitignored per DDR-115, but a cloned repo could
+   *  still ship a tracked file there, so bound what we'll forward into the
+   *  privileged `loadSession` ACP call rather than trusting its shape blindly). */
+  private async readPersistedSessionId(): Promise<string | null> {
+    if (!this.sessionStorePath) return null;
+    try {
+      const raw = await readFile(this.sessionStorePath, 'utf8');
+      const data = JSON.parse(raw) as { sessionId?: unknown };
+      const id = data.sessionId;
+      return typeof id === 'string' && VALID_SESSION_ID.test(id) ? id : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Persist a freshly-created sessionId so the NEXT bridge lifetime (app
+   *  restart, dev-server restart) can resume this chat instead of starting
+   *  fresh. Best-effort, like `appendTranscript` — a failed write just means
+   *  the next restart falls back to a new session. */
+  private async writePersistedSessionId(sessionId: string): Promise<void> {
+    if (!this.sessionStorePath) return;
+    try {
+      await mkdir(dirname(this.sessionStorePath), { recursive: true });
+      await writeFile(this.sessionStorePath, JSON.stringify({ sessionId, updatedAt: Date.now() }));
+    } catch {
+      /* best-effort — see doc comment above */
+    }
+  }
+
   private async start(): Promise<void> {
     const adapterEntry = resolveAdapterEntry();
     if (!adapterEntry) {
@@ -279,6 +405,12 @@ export class AcpBridge {
           this.opts.onCommands?.(params.update.availableCommands ?? []);
           return;
         }
+        // `loadSession` replays the resumed session's entire prior history back
+        // through this SAME callback (claude-agent-acp's replaySessionHistory) to
+        // prime its own in-adapter state. That history is already on disk in the
+        // transcript and already rendered client-side, so forwarding/re-appending
+        // it here would duplicate every message in the panel and the jsonl file.
+        if (this.replaying) return;
         this.opts.onUpdate(params.update);
         void this.appendTranscript({ role: 'agent', update: params.update });
       },
@@ -388,6 +520,13 @@ export class AcpBridge {
     this.proc = null;
     this.conn = null;
     this.sessions.clear();
+    // Drop any in-flight sessionFor() promises too — they were bound to the
+    // now-dead `conn`; a subsequent sessionFor() for the same chatId must
+    // establish fresh against the respawned connection, not await a stale
+    // reference (each entry's own .finally() would eventually clear it once its
+    // bounded loadSession timeout fires, but a call landing before then would
+    // otherwise get back a result tied to the connection we just tore down).
+    this.sessionPromises.clear();
     this.briefLogged.clear();
     this.currentSession = null;
   }

package/apps/studio/acp/index.ts

@@ -185,8 +185,16 @@ export function createAcp(ctx: Context, aiActivity?: AiActivity): Acp {
     const safe = id.replace(/[^a-z0-9_-]/gi, '').slice(0, 64);
     return safe || 'default';
   }
+  function chatFilePathFor(chatId: string, suffix: string): string {
+    return join(ctx.paths.designRoot, '_chat', `${sanitizeChatId(chatId)}${suffix}`);
+  }
   function transcriptPathFor(chatId: string): string {
-    return join(ctx.paths.designRoot, '_chat', `${sanitizeChatId(chatId)}.jsonl`);
+    return chatFilePathFor(chatId, '.jsonl');
+  }
+  // Sidecar persisting this chat's ACP sessionId across restarts (bridge.ts
+  // sessionFor's resume path) — the cross-restart memory gap tracked in DDR-125.
+  function sessionStorePathFor(chatId: string): string {
+    return chatFilePathFor(chatId, '.session.json');
   }
 
   async function handlePrompt(
@@ -198,6 +206,7 @@ export function createAcp(ctx: Context, aiActivity?: AiActivity): Acp {
   ): Promise<void> {
     const bridge = getOrCreateBridge(ws);
     bridge.setTranscriptPath(transcriptPathFor(chatId));
+    bridge.setSessionStorePath(sessionStorePathFor(chatId));
     bridge.setConfig(model, effort);
     try {
       await bridge.ensureStarted();
@@ -226,6 +235,7 @@ export function createAcp(ctx: Context, aiActivity?: AiActivity): Acp {
     effort: AcpEffort
   ): Promise<void> {
     const bridge = getOrCreateBridge(ws);
+    bridge.setSessionStorePath(sessionStorePathFor(chatId));
     bridge.setConfig(model, effort);
     try {
       await bridge.warmUp(sanitizeChatId(chatId));

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);