egaki 0.8.0 → 0.9.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>
 }
 
 // ---------------------------------------------------------------------------