egaki 0.8.0 → 0.10.0

package/src/vite/angled-screen.tsx

@@ -1,7 +1,11 @@
 'use client'
 
 /**
- * AngledScreen — CSS 3D perspective wrapper with fake bokeh depth-of-field.
+ * BasicAngledScreen — CSS 3D perspective wrapper with fake bokeh depth-of-field.
+ *
+ * The shader-based version (true depth-of-field via WebGL) lives in
+ * angled-screen-shader.tsx and is exported as AngledScreen. This CSS version
+ * is kept as a lightweight fallback that works without HTML-in-canvas support.
  *
  * Wraps any children (images, videos, divs) in a 3D-transformed plane using
  * CSS `perspective` + `transform: rotateX/Y/Z`. Simulates depth-of-field
@@ -23,7 +27,7 @@
 import { type CSSProperties, type ReactNode } from 'react'
 import { useTweakpane } from './tweakpane-hook.tsx'
 
-export interface AngledScreenProps {
+export interface BasicAngledScreenProps {
   children: ReactNode
 
   // --- 3D transform ---
@@ -91,7 +95,12 @@ function autoDirection(rotateX: number, rotateY: number): 'top' | 'bottom' | 'le
   return rotateX > 0 ? 'bottom' : 'top'
 }
 
-export function AngledScreen(props: AngledScreenProps) {
+/**
+ * @deprecated Use `AngledScreen` (angled-screen-shader.tsx) instead — the
+ * WebGL version with true depth-of-field. This CSS version only remains as
+ * the automatic fallback for browsers without HTML-in-canvas support.
+ */
+export function BasicAngledScreen(props: BasicAngledScreenProps) {
   const {
     children,
     transformOrigin = '50% 50%',
@@ -102,7 +111,7 @@ export function AngledScreen(props: AngledScreenProps) {
     style,
   } = props
 
-  const tp = useTweakpane('AngledScreen', {
+  const tp = useTweakpane('BasicAngledScreen', {
     perspective: { value: props.perspective ?? 1200, min: 100, max: 3000, step: 10 },
     rotateX: { value: props.rotateX ?? 8, min: -90, max: 90, step: 0.5 },
     rotateY: { value: props.rotateY ?? -12, min: -90, max: 90, step: 0.5 },

package/src/vite/mdx-video.test.tsx

@@ -27,6 +27,7 @@ describe('MDX_BUILTIN_COMPONENTS', () => {
         "Audio",
         "Background",
         "BandsShader",
+        "BasicAngledScreen",
         "Blur",
         "BlurReveal",
         "CodeBlock",

package/src/vite/mdx-video.tsx

@@ -29,7 +29,8 @@ import {
   StaggeredFadeUp,
   ShimmerSweep,
 } from './components.tsx'
-import { AngledScreen } from './angled-screen.tsx'
+import { BasicAngledScreen } from './angled-screen.tsx'
+import { AngledScreen } from './angled-screen-shader.tsx'
 import { CodeBlock, CODE_THEMES } from './code-block.tsx'
 import { BandsShader } from './bands-shader.tsx'
 import { WaveGradientShader } from './wave-gradient-shader.tsx'
@@ -924,6 +925,7 @@ export {
   StaggeredFadeUp,
   ShimmerSweep,
   AngledScreen,
+  BasicAngledScreen,
   CodeBlock,
   CODE_THEMES,
   BandsShader,
@@ -953,6 +955,7 @@ export const MDX_BUILTIN_COMPONENTS = {
   Background,
   LayoutTransition,
   AngledScreen,
+  BasicAngledScreen,
   BandsShader,
   WaveGradientShader,
   LiquidGradientShader,

package/src/vite/render-client.ts

@@ -9,32 +9,39 @@ import { ExportContext } from './mdx-video.tsx'
 import React from 'react'
 
 /**
- * Cover the web-renderer scaffold during export. The scaffold wrapper has
- * position:fixed + visibility:hidden + z-index:-9999, but allowHtmlInCanvas
- * sets visibility:visible on the inner layoutsubtree canvas, which can
- * make it peek through on the page.
+ * Wrap a composition for web-renderer entry points (export, screenshot,
+ * filmstrip). The scaffold wrapper is visibility:hidden and Chromium creates
+ * no paint records for hidden subtrees, which breaks captureElementImage()
+ * inside nested <HtmlInCanvas> (AngledScreen): onInit/onPaint silently never
+ * run and exports come out flat. visibility is overridable by descendants,
+ * so a visibility:visible div at the composition root restores paint records
+ * for the whole tree while deeper visibility:hidden ancestors (e.g.
+ * LayoutTransition's inactive instances) keep hiding their subtrees
+ * relative to this root.
  *
- * Do NOT modify the scaffold wrapper's own styles (translate, clip-path,
- * width/height, opacity). All of those break Chrome's drawElementImage
- * paint pipeline and produce black frames in the exported video. The
- * layout subtree canvas must remain at full size, in its original position,
- * with normal visibility for the capture to work.
+ * Tradeoff (accepted): the scaffold sits at z-index:-9999, painting above
+ * the page's root background but below all in-flow content — so the
+ * rendering composition can peek through wherever the page shows only the
+ * body background. Hiding it differently is not possible:
+ *   - opacity:0 / filter:opacity(0) bake into captureElementImage pixels
+ *     (verified: capture succeeds but frames come out fully transparent)
+ *   - translate/clip-path/resize on the scaffold break the drawElementImage
+ *     paint pipeline (black frames — learned June 2026, commit e501ca5)
+ *   - visibility:hidden kills paint records entirely (the original bug)
+ * An opaque page background or full-viewport player UI fully occludes it.
  *
- * Instead we place an opaque overlay on top (z-index:-9998, one above the
- * scaffold's -9999) that visually hides the rendering without touching
- * the scaffold's layout or paint properties.
+ * TODO: re-evaluate whether this wrapper is still needed once remotion
+ * fixes the HtmlInCanvas delayRender scoping / hidden-scaffold capture bug:
+ * https://github.com/remotion-dev/remotion/issues/9367
  */
-function injectScaffoldCover(): () => void {
-  const cover = document.createElement('div')
-  cover.style.cssText = [
-    'position:fixed',
-    'inset:0',
-    'z-index:-9998',
-    'background:#050505',
-    'pointer-events:none',
-  ].join(';')
-  document.body.appendChild(cover)
-  return () => cover.remove()
+export function wrapForWebRenderer(component: React.FC): React.FC {
+  const Wrapped: React.FC = () =>
+    React.createElement(
+      'div',
+      { style: { visibility: 'visible', position: 'relative', width: '100%', height: '100%' } },
+      React.createElement(component),
+    )
+  return Wrapped
 }
 
 export async function renderInBrowser(options: {
@@ -48,37 +55,31 @@ export async function renderInBrowser(options: {
   onProgress?: (progress: number) => void
   signal?: AbortSignal
 }) {
-  const removeCover = injectScaffoldCover()
-
   const ExportWrapped: React.FC = () =>
     React.createElement(ExportContext.Provider, { value: true },
       React.createElement(options.component))
 
-  try {
-    const { getBlob } = await renderMediaOnWeb({
-      composition: {
-        component: ExportWrapped,
-        durationInFrames: options.durationInFrames,
-        fps: options.fps ?? 30,
-        width: options.width ?? 1920,
-        height: options.height ?? 1080,
-        id: 'MdxVideo',
-        calculateMetadata: null,
-      },
-      inputProps: {},
-      container: 'mp4',
-      videoCodec: 'h264',
-      videoBitrate: 'high',
-      allowHtmlInCanvas: true,
-      scale: options.scale,
-      signal: options.signal,
-      onProgress: ({ progress }) => {
-        options.onProgress?.(progress)
-      },
-    })
+  const { getBlob } = await renderMediaOnWeb({
+    composition: {
+      component: wrapForWebRenderer(ExportWrapped),
+      durationInFrames: options.durationInFrames,
+      fps: options.fps ?? 30,
+      width: options.width ?? 1920,
+      height: options.height ?? 1080,
+      id: 'MdxVideo',
+      calculateMetadata: null,
+    },
+    inputProps: {},
+    container: 'mp4',
+    videoCodec: 'h264',
+    videoBitrate: 'high',
+    allowHtmlInCanvas: true,
+    scale: options.scale,
+    signal: options.signal,
+    onProgress: ({ progress }) => {
+      options.onProgress?.(progress)
+    },
+  })
 
-    return getBlob()
-  } finally {
-    removeCover()
-  }
+  return getBlob()
 }

package/src/vite/sdk.ts

@@ -13,6 +13,7 @@
 
 import React from 'react'
 import { renderStillOnWeb, renderMediaOnWeb } from '@remotion/web-renderer'
+import { wrapForWebRenderer } from './render-client.ts'
 import { ExportContext } from './mdx-video.tsx'
 import type {
   FrameRange,
@@ -403,7 +404,7 @@ class EgakiSDK {
 
     const still = await renderStillOnWeb({
       composition: {
-        component: c.component,
+        component: wrapForWebRenderer(c.component),
         durationInFrames: c.totalDuration,
         fps: c.fps,
         width: c.width,
@@ -502,7 +503,7 @@ class EgakiSDK {
     for (let i = 0; i < framesToCapture.length; i++) {
       const still = await renderStillOnWeb({
         composition: {
-          component: c.component,
+          component: wrapForWebRenderer(c.component),
           durationInFrames: c.totalDuration,
           fps: c.fps,
           width: c.width,
@@ -542,7 +543,7 @@ class EgakiSDK {
 
     const { getBlob } = await renderMediaOnWeb({
       composition: {
-        component: this.wrapForExport(c.component),
+        component: wrapForWebRenderer(this.wrapForExport(c.component)),
         durationInFrames: c.totalDuration,
         fps: c.fps,
         width: c.width,

package/src/vite/shader-renderer.tsx

@@ -71,7 +71,7 @@ export interface ShaderConfig {
 // ---------------------------------------------------------------------------
 
 /** Parse a hex color string (#RGB, #RRGGBB, #RRGGBBAA) to [r, g, b, a] in 0-1 range. */
-function parseHexColor(hex: string): [number, number, number, number] {
+export function parseHexColor(hex: string): [number, number, number, number] {
   let h = hex.replace('#', '')
   if (h.length === 3 || h.length === 4) {
     h = h
@@ -172,7 +172,7 @@ function generateFragmentSource(
 // WebGL helpers
 // ---------------------------------------------------------------------------
 
-function compileGlShader(
+export function compileGlShader(
   gl: WebGL2RenderingContext,
   type: number,
   source: string,
@@ -189,7 +189,7 @@ function compileGlShader(
   return shader
 }
 
-function linkGlProgram(
+export function linkGlProgram(
   gl: WebGL2RenderingContext,
   vs: WebGLShader,
   fs: WebGLShader,

package/src/vite/tweakpane-hook.tsx

@@ -18,6 +18,14 @@
  * Tweakpane is pure DOM (no React dependency), so there are no dual-React
  * or SSR issues. During SSR (typeof window === 'undefined') the hook
  * returns the raw default values and skips all DOM work.
+ *
+ * Live props vs user overrides: each param follows the LIVE schema value
+ * passed on every render (so animated props like translateX={interpolate(...)}
+ * work) until the user touches that control in the pane. Once touched, the
+ * user's value wins for that key until the component remounts. Untouched
+ * controls are refreshed in the pane every render so animated values are
+ * visible while playing. Programmatic refreshes are guarded so tweakpane's
+ * change events (which fire on refresh() too) don't mark keys as touched.
  */
 
 import { useCallback, useEffect, useRef, useState, useSyncExternalStore, createContext, useContext } from 'react'
@@ -129,6 +137,10 @@ interface FolderEntry {
   params: Record<string, unknown>
   /** The original default values for diffing. */
   defaults: Record<string, unknown>
+  /** Keys the user changed via the pane UI. Only these count as "changed"
+   *  in the copy prompt — untouched keys track live (possibly animated)
+   *  props, so diffing them against mount-time defaults would be noise. */
+  touched: Set<string>
 }
 const activeFolders = new Map<string, FolderEntry>()
 
@@ -146,6 +158,22 @@ function cloneValue<T>(value: T): T {
   return value
 }
 
+/** Deep-equal for param values: primitives, small arrays (bezier tuples),
+ *  and flat objects (range {min, max}). */
+function valuesEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((x, i) => x === b[i])
+  }
+  if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null) {
+    const ra = a as Record<string, unknown>
+    const rb = b as Record<string, unknown>
+    const ka = Object.keys(ra)
+    return ka.length === Object.keys(rb).length && ka.every((k) => ra[k] === rb[k])
+  }
+  return false
+}
+
 function resolveDefault(v: ParamValue): number | boolean | string | [number, number, number, number] | { min: number; max: number } {
   if (isCubicBezierParam(v)) return [...v.value]
   if (isRangeParam(v)) return { ...v.value }
@@ -279,7 +307,10 @@ function serializeTweakpanePrompt(
     const changed: string[] = []
     for (const [key, current] of Object.entries(entry.params)) {
       const def = entry.defaults[key]
-      if (current !== def) {
+      // Only user-touched keys count as changed. Untouched keys mirror live
+      // (possibly animated) props, so comparing them to mount-time defaults
+      // would produce false positives on every playing frame.
+      if (entry.touched.has(key) && !valuesEqual(current, def)) {
         changed.push(`  ${key}: ${formatValue(current)}`)
       }
     }
@@ -380,6 +411,12 @@ function CopyChangesButton() {
  * Returns a reactive object with current values. Updating a control in the
  * pane immediately triggers a React re-render with fresh values.
  *
+ * Values follow live props: each key returns the schema value from the
+ * CURRENT render until the user touches that control in the pane, so
+ * animated props (e.g. `translateX={interpolate(frame, ...)}`) flow through
+ * every frame. Once touched, the user's pane value wins for that key until
+ * the component remounts.
+ *
  * On unmount the folder is disposed and removed from the pane.
  */
 export function useTweakpane<T extends ParamSchema>(
@@ -408,6 +445,22 @@ export function useTweakpane<T extends ParamSchema>(
   const schemaRef = useRef(schema)
   schemaRef.current = schema
 
+  // Keys the user changed via the pane UI. Untouched keys follow the live
+  // schema value on every render (so animated props work); touched keys keep
+  // the user's pane value until remount.
+  const touchedRef = useRef<Set<string>>(new Set())
+  // Latest user override values, mirrored from state so the mount effect can
+  // seed rebuilt folders without re-running on every pane change.
+  const valuesRef = useRef(values)
+  valuesRef.current = values
+  // Live handles to the mounted folder + bound params, used by the per-render
+  // sync effect below to push animated prop values into the pane.
+  const liveRef = useRef<{ folder: import('tweakpane').FolderApi; params: Record<string, unknown> } | null>(null)
+  // True while we call folder.refresh() programmatically. tweakpane emits
+  // change events on refresh() too, so handlers must ignore those or every
+  // animated frame would mark keys as user-touched.
+  const refreshingRef = useRef(false)
+
   // Stable ID for this hook instance
   const idRef = useRef(`${label}-${Math.random().toString(36).slice(2, 8)}`)
 
@@ -425,7 +478,10 @@ export function useTweakpane<T extends ParamSchema>(
       const def = resolveDefault(param)
       // Clone object/array values so tweakpane's in-place mutations on params
       // don't corrupt the defaults (used by "Copy changes" diffing).
-      params[key] = cloneValue(def)
+      // Touched keys keep the user's override when the folder is rebuilt
+      // (e.g. premount → active transition re-runs this effect).
+      const touched = touchedRef.current.has(key)
+      params[key] = cloneValue(touched ? valuesRef.current[key] : def)
       defaults[key] = cloneValue(def)
     }
 
@@ -449,6 +505,7 @@ export function useTweakpane<T extends ParamSchema>(
             picker: 'inline',
           } as any)
           ;(blade as any).on('change', (ev: any) => {
+            if (refreshingRef.current) return
             const val = ev.value
             const tuple: [number, number, number, number] = [
               Math.round(val.x1 * 1000) / 1000,
@@ -457,6 +514,7 @@ export function useTweakpane<T extends ParamSchema>(
               Math.round(val.y2 * 1000) / 1000,
             ]
             params[key] = tuple
+            touchedRef.current.add(key)
             setValues((prev) => ({ ...prev, [key]: tuple }))
           })
           continue
@@ -468,7 +526,9 @@ export function useTweakpane<T extends ParamSchema>(
             max: param.max,
             step: param.step,
           }).on('change', (ev) => {
+            if (refreshingRef.current) return
             const val = ev.value as { min: number; max: number }
+            touchedRef.current.add(key)
             setValues((prev) => ({ ...prev, [key]: { min: val.min, max: val.max } }))
           })
           continue
@@ -497,17 +557,22 @@ export function useTweakpane<T extends ParamSchema>(
         }
 
         folder.addBinding(params, key, opts).on('change', (ev) => {
+          if (refreshingRef.current) return
+          touchedRef.current.add(key)
           setValues((prev) => ({ ...prev, [key]: ev.value }))
         })
       }
 
+      liveRef.current = { folder, params }
+
       // Register for copy prompt
-      activeFolders.set(id, { label, params, defaults })
+      activeFolders.set(id, { label, params, defaults, touched: touchedRef.current })
       notifyFolderListeners()
     })()
 
     return () => {
       disposed = true
+      liveRef.current = null
       if (folder) {
         folder.dispose()
         folder = null
@@ -522,7 +587,40 @@ export function useTweakpane<T extends ParamSchema>(
     }
   }, [label, skip])
 
-  return values as ResolvedValues<T>
+  // Push live (possibly animated) prop values into the pane for untouched
+  // keys. Runs after every render — during playback the component re-renders
+  // each frame, so animated values are visible moving in the pane UI.
+  // folder.refresh() emits change events; refreshingRef makes handlers
+  // ignore them so refreshes never mark keys as touched.
+  useEffect(() => {
+    const live = liveRef.current
+    if (!live) return
+    let dirty = false
+    for (const [key, param] of Object.entries(schemaRef.current)) {
+      if (touchedRef.current.has(key)) continue
+      // Bezier blades are not bindings — refresh() won't read params for
+      // them. The returned value still follows live props below.
+      if (isCubicBezierParam(param)) continue
+      const liveVal = resolveDefault(param)
+      if (!valuesEqual(live.params[key], liveVal)) {
+        live.params[key] = cloneValue(liveVal)
+        dirty = true
+      }
+    }
+    if (dirty) {
+      refreshingRef.current = true
+      live.folder.refresh()
+      refreshingRef.current = false
+    }
+  })
+
+  // Merge: user-touched keys return the pane value, untouched keys follow
+  // the live schema value so animated props work without any extra wiring.
+  const merged: Record<string, unknown> = {}
+  for (const [key, param] of Object.entries(schema)) {
+    merged[key] = touchedRef.current.has(key) ? values[key] : resolveDefault(param)
+  }
+  return merged as ResolvedValues<T>
 }
 
 // ---------------------------------------------------------------------------

package/src/vite/vite-plugin.ts

@@ -20,6 +20,7 @@ import type { Plugin, PluginOption } from 'vite'
 import { spiceflowPlugin } from 'spiceflow/vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
+import pc from 'picocolors'
 import { mdxParse } from 'safe-mdx/parse'
 import { collectServerImportSources } from './server-mdx.ts'
 import { parseFrontmatter } from './mdx-parse.ts'
@@ -44,6 +45,25 @@ const RESOLVED_MODULES = '\0' + VIRTUAL_MODULES
 
 const PKG_NAME = 'egaki'
 
+// Packages that must resolve to a single physical copy (same pattern as
+// spiceflow:dedupe-singleton). Remotion Player + useVideoConfig share React
+// context; two copies → "No video config found". Motion patches need one
+// JSAnimation class. resolve.dedupe alone fails under pnpm when the package
+// is only a transitive dep of egaki (not hoisted to the consumer root).
+const dedupePackages = new Set([
+  'remotion',
+  '@remotion/player',
+  '@remotion/media',
+  '@remotion/web-renderer',
+  'motion',
+  'motion-dom',
+  'motion-utils',
+])
+
+// Fake importer anchored inside egaki's package so this.resolve() finds the
+// same remotion/motion copy egaki itself depends on.
+const dedupeImporter = path.join(__pkgRoot, '_dedupe_importer_.js')
+
 export interface VideoPluginOptions {
   /** Path to the default MDX entry file (relative to vite root or absolute).
    *  When omitted, auto-discovers: video.mdx > index.mdx > first .mdx found.
@@ -258,7 +278,7 @@ export function video(options?: VideoPluginOptions): PluginOption[] {
             const fullPath = path.join(dir, entry.name)
             if (entry.isDirectory()) {
               walkDir(fullPath)
-            } else if (/\.(tsx?|jsx?|mdx?)$/.test(entry.name) && !/\.(test|spec|config)\./.test(entry.name)) {
+            } else if (/\.(tsx?|jsx?|mdx?)$/.test(entry.name) && !/\.(test|spec|config)\./.test(entry.name) && !/\.d\.ts$/.test(entry.name)) {
               // Entry MDX files are NOT skipped: they may be imported as
               // partials by other MDX files (e.g. `import Intro from './intro.mdx'`).
               // Self-import is a user error and harmless (safe-mdx handles it).
@@ -314,6 +334,52 @@ export function video(options?: VideoPluginOptions): PluginOption[] {
       }
     },
 
+    // Print SDK usage instructions after Vite's startup banner.
+    // Agents read terminal output to learn how to interact with the
+    // running dev server via Playwriter + window.egakiSDK.
+    configureServer(server) {
+      server.httpServer?.on('listening', () => {
+        const log = server.config.logger
+        const p = (s: string) => log.info(s)
+        // Small delay so our block prints after Vite's "ready in" + URL lines
+        setTimeout(() => {
+          const title = `  ${pc.cyan(pc.bold('egaki SDK'))} ${pc.dim('—')} ${pc.white('programmatic control via')} ${pc.yellow('window.egakiSDK')}`
+          const sep = pc.dim('  ─'.padEnd(72, '─'))
+
+          p('')
+          p(title)
+          p(sep)
+          p('')
+          p(`  ${pc.green('●')} ${pc.bold('Get info')}        ${pc.dim('composition metadata, sections, fps')}`)
+          p(`    ${pc.cyan(`playwriter -s 1 -e 'console.log(await state.page.evaluate(() => window.egakiSDK.getInfo()))'`)}`)
+          p('')
+          p(`  ${pc.green('●')} ${pc.bold('Screenshot')}      ${pc.dim('capture a single frame as PNG')}`)
+          p(`    ${pc.cyan("playwriter -s 1 -e \"$(cat <<'JS'")}`)
+          p(`    ${pc.cyan('const dataUrl = await state.page.evaluate(() => window.egakiSDK.screenshot({ frame: 60 }))')}`)
+          p(`    ${pc.cyan('const buf = Buffer.from(await (await fetch(dataUrl)).arrayBuffer())')}`)
+          p(`    ${pc.cyan('require("node:fs").writeFileSync("/tmp/frame-60.png", buf)')}`)
+          p(`    ${pc.cyan('JS')}`)
+          p(`    ${pc.cyan(')"')}`)
+          p('')
+          p(`  ${pc.green('●')} ${pc.bold('Filmstrip')}       ${pc.dim('grid of frames across scenes')}`)
+          p(`    ${pc.cyan("playwriter -s 1 -e \"$(cat <<'JS'")}`)
+          p(`    ${pc.cyan('const dataUrl = await state.page.evaluate(() =>')}`)
+          p(`    ${pc.cyan('  window.egakiSDK.filmstrip({ scenes: [0, 1, 2], framesPerScene: 3 }))')}`)
+          p(`    ${pc.cyan('const buf = Buffer.from(await (await fetch(dataUrl)).arrayBuffer())')}`)
+          p(`    ${pc.cyan('require("node:fs").writeFileSync("/tmp/filmstrip.png", buf)')}`)
+          p(`    ${pc.cyan('JS')}`)
+          p(`    ${pc.cyan(')"')}`)
+          p('')
+          p(`  ${pc.green('●')} ${pc.bold('Export video')}     ${pc.dim('render MP4 via WebCodecs')}`)
+          p(`    ${pc.cyan(`playwriter -s 1 -e 'await state.page.evaluate(() => window.egakiSDK.export({ path: "output.mp4" }))'`)}`)
+          p('')
+          p(`  ${pc.green('●')} ${pc.bold('Seek')}            ${pc.dim('jump to a specific frame')}`)
+          p(`    ${pc.cyan(`playwriter -s 1 -e 'await state.page.evaluate(() => window.egakiSDK.seekTo(120))'`)}`)
+          p('')
+        }, 50)
+      })
+    },
+
     // HMR for file changes in the project.
     //
     // Entry MDX: the source string flows server → client through the RSC
@@ -440,16 +506,13 @@ export function video(options?: VideoPluginOptions): PluginOption[] {
       arr.push(/^tweakpane/)
       config.resolve.noExternal = arr
 
-      // Deduplicate motion packages so egaki's motion-timing virtual module
-      // patches the same JSAnimation class that motion/react uses. Without
-      // this, Vite can resolve motion-dom to different instances and
-      // prototype patches won't affect the user's animations.
-      // Always applied (not gated by hasMotion) because configEnvironment
-      // runs before configResolved where hasMotion is set. Harmless when
-      // motion isn't installed — dedupe on missing packages is a no-op.
+      // Baseline hint for Vite's built-in resolver (same list as the
+      // resolveId singleton plugin below). Real enforcement is the
+      // egaki:dedupe-singleton plugin — resolve.dedupe alone is not enough
+      // under pnpm when remotion is only a transitive dep of egaki.
       config.resolve.dedupe = mergeUnique(
         config.resolve.dedupe as string[] | undefined,
-        ['motion', 'motion-dom', 'motion-utils'],
+        [...dedupePackages],
       )
 
       if (name === 'client') {
@@ -458,6 +521,14 @@ export function video(options?: VideoPluginOptions): PluginOption[] {
           config.optimizeDeps.exclude,
           [PKG_NAME],
         )
+        // Prebundle safe-mdx as a single entry so its pure-CJS leaves
+        // (format via fault/micromark) stay internalized with CJS interop.
+        // Do NOT list format/fault as separate optimizeDeps entries — that
+        // splits them into named-only ESM chunks and the browser crashes with
+        // "does not provide an export named 'default'" (same bug Holocron hit
+        // when safe-mdx leaked to the client; see holocron vite CHANGELOG).
+        // Holocron's clean fix is keep safe-mdx server-only; egaki needs it on
+        // the client for MDX-in-browser, so correct prebundling is the fix.
         config.optimizeDeps.include = mergeUnique(
           config.optimizeDeps.include,
           [
@@ -465,6 +536,8 @@ export function video(options?: VideoPluginOptions): PluginOption[] {
             `${PKG_NAME} > remotion`,
             `${PKG_NAME} > @remotion/player`,
             `${PKG_NAME} > safe-mdx`,
+            'safe-mdx',
+            'safe-mdx/parse',
           ],
         )
       }
@@ -479,9 +552,44 @@ export function video(options?: VideoPluginOptions): PluginOption[] {
     },
   }
 
+  // Force remotion / motion to a single copy across all importers, even when
+  // egaki is a transitive or file:-linked dep under pnpm. Mirrors
+  // spiceflow:dedupe-singleton (spiceflow/src/vite.tsx).
+  //
+  // Vite's resolve.dedupe sets basedir=root then walks node_modules/, but
+  // pnpm only symlinks direct deps at the root. Transitive deps stay buried
+  // in .pnpm/, so dedupe silently falls back to importer-based resolution
+  // and Player vs useVideoConfig load different remotion instances.
+  const dedupeSingletonPlugin: Plugin = {
+    name: 'egaki:dedupe-singleton',
+    enforce: 'pre',
+    async resolveId(id, _importer, options) {
+      if (
+        id.startsWith('.') ||
+        id.startsWith('/') ||
+        id.startsWith('\0') ||
+        id.includes('?')
+      ) {
+        return null
+      }
+
+      const pkgName = id.startsWith('@')
+        ? id.split('/').slice(0, 2).join('/')
+        : (id.split('/')[0] ?? id)
+
+      if (!dedupePackages.has(pkgName)) return null
+
+      return this.resolve(id, dedupeImporter, {
+        ...options,
+        skipSelf: true,
+      })
+    },
+  }
+
   return [
     videoPlugin,
     rscPackagePlugin,
+    dedupeSingletonPlugin,
     tailwindcss(),
     spiceflowPlugin({ entry: VIRTUAL_APP }),
     react(),