egaki 0.9.0 → 0.10.0

package/dist/vite/angled-screen-shader.js

@@ -11,7 +11,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *   intersection → plane-local UV → sample DOM texture
  *
  * The intersection distance gives true per-pixel depth, which drives:
- *   - bokeh blur (poisson-disc, radius grows with distance from focus)
+ *   - bokeh blur (sparse 6-blade hex iris, radius grows with distance from
+ *     focus — fewer taps so the aperture shape reads as hard disks instead
+ *     of smoothing into a gaussian)
+ *   - chromatic aberration (radial R/B split, stronger in the bokeh)
  *   - fog toward backgroundColor (like the original Three.js plugin's
  *     scene fog, unframer-private/plugin-angled-screen BokehPass setup)
  *   - film grain (from the plugin's filmGrainShader, u_time-seeded)
@@ -94,6 +97,7 @@ uniform float u_focusDist;  // focus distance in px along the ray
 uniform float u_aspect;     // width / height, for circular bokeh
 uniform float u_fog;
 uniform float u_grain;
+uniform float u_ca;         // chromatic aberration strength
 uniform vec4 u_background;
 uniform float u_debug;
 uniform float u_time;
@@ -105,21 +109,26 @@ float rand(vec2 co) {
   return fract(sin(dot(co, vec2(12.9898, 78.233))) * 43758.5453);
 }
 
-// Three.js BokehShader ring kernel (Martins Upitis lens blur):
-// 16 taps at radius 1.0, 8 at 0.9, 8 at 0.7, 8 at 0.4, plus center = 41.
-const vec2 RING1[16] = vec2[](
-  vec2(0.0, 0.4), vec2(0.15, 0.37), vec2(0.29, 0.29), vec2(-0.37, 0.15),
-  vec2(0.40, 0.0), vec2(0.37, -0.15), vec2(0.29, -0.29), vec2(-0.15, -0.37),
-  vec2(0.0, -0.4), vec2(-0.15, 0.37), vec2(-0.29, 0.29), vec2(0.37, 0.15),
-  vec2(-0.4, 0.0), vec2(-0.37, -0.15), vec2(-0.29, -0.29), vec2(0.15, -0.37)
+// Sparse 6-blade hexagonal iris. Far fewer taps than the 41-sample Martins
+// Upitis kernel so the aperture SHAPE reads as discrete hex disks instead of
+// smoothing into a gaussian. Outer ring is weighted heavier so bright points
+// form hard-edged bokeh blobs (the look of real lens DOF on the refs).
+// Unit circle coords at radius 1.0 / 0.55.
+const vec2 HEX_OUTER[6] = vec2[](
+  vec2( 1.0000,  0.0000),
+  vec2( 0.5000,  0.8660),
+  vec2(-0.5000,  0.8660),
+  vec2(-1.0000,  0.0000),
+  vec2(-0.5000, -0.8660),
+  vec2( 0.5000, -0.8660)
 );
-const vec2 RING9[8] = vec2[](
-  vec2(0.15, 0.37), vec2(-0.37, 0.15), vec2(0.37, -0.15), vec2(-0.15, -0.37),
-  vec2(-0.15, 0.37), vec2(0.37, 0.15), vec2(-0.37, -0.15), vec2(0.15, -0.37)
-);
-const vec2 RING7[8] = vec2[](
-  vec2(0.29, 0.29), vec2(0.40, 0.0), vec2(0.29, -0.29), vec2(0.0, -0.4),
-  vec2(-0.29, 0.29), vec2(-0.4, 0.0), vec2(-0.29, -0.29), vec2(0.0, 0.4)
+const vec2 HEX_MID[6] = vec2[](
+  vec2( 0.5500,  0.0000),
+  vec2( 0.2750,  0.4763),
+  vec2(-0.2750,  0.4763),
+  vec2(-0.5500,  0.0000),
+  vec2(-0.2750, -0.4763),
+  vec2( 0.2750, -0.4763)
 );
 
 // Intersect the camera ray through screen uv suv with the tilted plane.
@@ -154,6 +163,17 @@ vec4 sampleScene(vec2 suv) {
   return mix(u_background, c, coverage);
 }
 
+// Per-channel sample with chromatic aberration: R and B pull apart along
+// the radial axis from frame center (classic lens CA purple/cyan fringing).
+vec4 sampleSceneCA(vec2 suv, vec2 caOffset) {
+  float r = sampleScene(suv + caOffset).r;
+  float g = sampleScene(suv).g;
+  float b = sampleScene(suv - caOffset).b;
+  // Coverage/alpha from the green (unshifted) sample keeps silhouette stable.
+  vec4 mid = sampleScene(suv);
+  return vec4(r, g, b, mid.a);
+}
+
 void main() {
   vec4 bg = u_background;
 
@@ -178,27 +198,41 @@ void main() {
   // stays tack sharp. Background pixels (no hit) count as far away, so the
   // plane silhouette melts softly where it is out of focus.
   float factor = hit ? max(t - u_focusDist, 0.0) / u_perspective : 1.0;
-  vec2 dofblur = vec2(clamp(factor * u_aperture, 0.0, u_maxblur)) * u_bokehEnabled;
+  float blurAmt = clamp(factor * u_aperture, 0.0, u_maxblur) * u_bokehEnabled;
+  vec2 dofblur = vec2(blurAmt);
 
   vec2 aspectcorrect = vec2(1.0, u_aspect);
-  vec2 dofblur9 = dofblur * 0.9;
-  vec2 dofblur7 = dofblur * 0.7;
-  vec2 dofblur4 = dofblur * 0.4;
 
-  vec4 col = sampleScene(v_uv);
-  for (int i = 0; i < 16; i++) {
-    col += sampleScene(v_uv + RING1[i] * aspectcorrect * dofblur);
-  }
-  for (int i = 0; i < 8; i++) {
-    col += sampleScene(v_uv + RING9[i] * aspectcorrect * dofblur9);
-  }
-  for (int i = 0; i < 8; i++) {
-    col += sampleScene(v_uv + RING7[i] * aspectcorrect * dofblur7);
+  // Radial CA direction from frame center. Strength grows with local blur so
+  // sharp regions stay clean and only the bokeh fringes with purple/cyan.
+  vec2 fromCenter = v_uv - 0.5;
+  float radial = length(fromCenter);
+  vec2 caDir = radial > 1e-5 ? fromCenter / radial : vec2(1.0, 0.0);
+  // Base fringe + blur-scaled fringe. u_ca ~0.45 reads like a real lens on
+  // the reference photos without turning the whole frame into a prism.
+  float caAmt = u_ca * (0.0015 + blurAmt * 0.55);
+  vec2 caOffset = caDir * caAmt * aspectcorrect;
+
+  // Sparse hex gather. Outer ring weight 2.0 so the 6-blade iris is visible
+  // as hard bokeh disks; mid ring 1.0 fills the disk; center 1.0 anchors.
+  // Total weight = 6*2 + 6*1 + 1 = 19.
+  const float W_OUTER = 2.0;
+  const float W_MID = 1.0;
+  const float W_CENTER = 1.0;
+  vec4 col = sampleSceneCA(v_uv, caOffset) * W_CENTER;
+  for (int i = 0; i < 6; i++) {
+    col += sampleSceneCA(v_uv + HEX_OUTER[i] * aspectcorrect * dofblur, caOffset) * W_OUTER;
   }
-  for (int i = 0; i < 8; i++) {
-    col += sampleScene(v_uv + RING7[i] * aspectcorrect * dofblur4);
+  for (int i = 0; i < 6; i++) {
+    col += sampleSceneCA(v_uv + HEX_MID[i] * aspectcorrect * dofblur, caOffset) * W_MID;
   }
-  col /= 41.0;
+  col /= (6.0 * W_OUTER + 6.0 * W_MID + W_CENTER);
+
+  // Mild highlight bias: bright samples punch through more (classic optical
+  // bokeh where speculars form bright disks instead of averaging down).
+  // Applied as a soft lift so it doesn't blow whites on already-bright UI.
+  float luma = dot(col.rgb, vec3(0.299, 0.587, 0.114));
+  col.rgb += col.rgb * blurAmt * 1.8 * smoothstep(0.55, 0.95, luma);
 
   // Fog toward background with depth (plugin's THREE.Fog equivalent)
   col.rgb = mix(col.rgb, bg.rgb, u_fog * depth01 * (hit ? 1.0 : 0.0));
@@ -226,6 +260,7 @@ const UNIFORM_NAMES = [
     'u_aspect',
     'u_fog',
     'u_grain',
+    'u_ca',
     'u_background',
     'u_debug',
     'u_time',
@@ -309,12 +344,18 @@ export function AngledScreen(props) {
             step: 0.01,
         },
         fog: { value: props.fog ?? 0.35, min: 0, max: 1, step: 0.01 },
-        grainIntensity: { value: props.grainIntensity ?? 0.02, min: 0, max: 0.2, step: 0.005 },
+        grainIntensity: { value: props.grainIntensity ?? 0.02, min: 0, max: 0.3, step: 0.005 },
+        chromaticAberration: {
+            value: props.chromaticAberration ?? 0.45,
+            min: 0,
+            max: 2,
+            step: 0.01,
+        },
         backgroundColor: props.backgroundColor ?? '#000000',
         debug: props.debug ?? false,
     });
     const { perspective, rotateX, rotateY, rotateZ, translateX, translateZ } = tp;
-    const { aperture, maxBlur, focus, fog, grainIntensity } = tp;
+    const { aperture, maxBlur, focus, fog, grainIntensity, chromaticAberration } = tp;
     const { bokeh, debug, backgroundColor } = tp;
     const time = frame / fps;
     const onInit = useCallback(({ canvas }) => {
@@ -473,6 +514,8 @@ export function AngledScreen(props) {
             gl.uniform1f(locs.u_fog, fog);
         if (locs.u_grain)
             gl.uniform1f(locs.u_grain, grainIntensity);
+        if (locs.u_ca)
+            gl.uniform1f(locs.u_ca, chromaticAberration);
         if (locs.u_background)
             gl.uniform4fv(locs.u_background, parseHexColor(backgroundColor));
         if (locs.u_debug)
@@ -507,7 +550,7 @@ export function AngledScreen(props) {
         }
     }, [
         compW, compH, perspective, rotateX, rotateY, rotateZ, translateX, translateZ,
-        bokeh, aperture, maxBlur, focus, fog, grainIntensity,
+        bokeh, aperture, maxBlur, focus, fog, grainIntensity, chromaticAberration,
         backgroundColor, debug, time,
     ]);
     const supported = typeof document !== 'undefined' && HtmlInCanvas.isSupported();

package/dist/vite/vite-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../../src/vite/vite-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,MAAM,CAAA;AA4BhD,MAAM,WAAW,kBAAkB;IACjC;;wEAEoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAiDD,wBAAgB,KAAK,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,YAAY,EAAE,CAoYlE"}
+{"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../../src/vite/vite-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAU,YAAY,EAAE,MAAM,MAAM,CAAA;AAgDhD,MAAM,WAAW,kBAAkB;IACjC;;wEAEoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAiDD,wBAAgB,KAAK,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,YAAY,EAAE,CA4dlE"}

package/dist/vite/vite-plugin.js

@@ -18,6 +18,7 @@ import { fileURLToPath } from 'node:url';
 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.js";
 import { parseFrontmatter } from "./mdx-parse.js";
@@ -34,6 +35,23 @@ const RESOLVED_MDX = '\0' + VIRTUAL_MDX;
 const VIRTUAL_MODULES = 'virtual:egaki-modules';
 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');
 /** Resolve a relative MDX import source against the project root,
  *  probing common extensions. Returns the absolute path or undefined. */
 function resolveSourceToFile(root, source) {
@@ -237,7 +255,7 @@ export function video(options) {
                         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).
@@ -291,6 +309,50 @@ export function video(options) {
                 ].join('\n');
             }
         },
+        // 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) => 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
@@ -408,22 +470,29 @@ export function video(options) {
             arr.push(new RegExp(`^${PKG_NAME}`));
             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.
-            config.resolve.dedupe = mergeUnique(config.resolve.dedupe, ['motion', 'motion-dom', 'motion-utils']);
+            // 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, [...dedupePackages]);
             if (name === 'client') {
                 config.optimizeDeps ??= {};
                 config.optimizeDeps.exclude = mergeUnique(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, [
                     `${PKG_NAME} > spiceflow > @vitejs/plugin-rsc/vendor/react-server-dom/client.browser`,
                     `${PKG_NAME} > remotion`,
                     `${PKG_NAME} > @remotion/player`,
                     `${PKG_NAME} > safe-mdx`,
+                    'safe-mdx',
+                    'safe-mdx/parse',
                 ]);
             }
             if (name === 'rsc' || name === 'ssr') {
@@ -432,9 +501,39 @@ export function video(options) {
             }
         },
     };
+    // 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 = {
+        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(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "egaki",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "AI image, video, and speech generation CLI with MDX-to-video framework",
   "main": "./dist/cli/main.js",
@@ -113,18 +113,15 @@
     "zod": "^4.3.6",
     "@vitejs/plugin-react": "^6.0.2",
     "spiceflow": "1.26.0-rsc.7",
+    "vite": "^8.0.10",
     "zustand": "^5.0.14"
   },
   "peerDependencies": {
-    "vite": ">=6",
     "motion": ">=12",
     "motion-dom": ">=12",
     "motion-utils": ">=12"
   },
   "peerDependenciesMeta": {
-    "vite": {
-      "optional": true
-    },
     "motion": {
       "optional": true
     },
@@ -141,7 +138,6 @@
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/react": "^19.2.17",
-    "vite": "^8.0.10",
     "vitest": "^4.1.8"
   },
   "scripts": {

package/src/cli/cli.ts

@@ -244,6 +244,56 @@ cli
     await showUsage()
   })
 
+// ─── dev command ─────────────────────────────────────────────────────────────
+
+cli
+  .command(
+    'dev [entry]',
+    dedent`
+      Start the MDX video dev server with zero setup.
+      Pass an .mdx file (or a directory containing one) — no package.json,
+      vite.config.ts, or npm install needed. All dependencies (react,
+      remotion, vite) come from the egaki CLI's own installation.
+      Uses a random free port unless --port is given.
+    `,
+  )
+  .option(
+    '-p, --port [port]',
+    z.coerce.number().int().describe('Fixed port (default: random free port)'),
+  )
+  .option(
+    '--host [host]',
+    z.string().describe('Host to bind (default: localhost)'),
+  )
+  .option('--open', 'Open the player in the default browser')
+  .example('# Serve a single MDX file, no project setup')
+  .example('egaki dev video.mdx')
+  .example('# Serve the current directory (auto-discovers video.mdx)')
+  .example('egaki dev')
+  .example('# Fixed port + open browser')
+  .example('egaki dev intro.mdx --port 5199 --open')
+  .action(async (entry, options) => {
+    const { startDevServer } = await import('./dev-server.js')
+    const result = await startDevServer({
+      entry,
+      port: options.port,
+      host: options.host,
+    })
+    if (result instanceof Error) {
+      console.error(pc.red(result.message))
+      process.exit(1)
+    }
+    console.log()
+    console.log(`  ${pc.green('➜')}  egaki dev server running`)
+    console.log(`  ${pc.dim('root:')} ${result.root}`)
+    console.log(`  ${pc.dim('url:')}  ${pc.cyan(result.url)}`)
+    console.log()
+    if (options.open) {
+      const { openUrlInBrowser } = await import('./open-browser.js')
+      await openUrlInBrowser(result.url)
+    }
+  })
+
 // ─── image command ───────────────────────────────────────────────────────────
 
 cli

package/src/cli/dev-server.test.ts

@@ -0,0 +1,109 @@
+// Tests for the zero-config dev server (egaki dev).
+//
+// Creates a temp directory containing ONLY a video.mdx file — no
+// package.json, no vite.config.ts, no node_modules — and verifies the
+// dev server boots, serves HTML at /, and resolves all framework deps
+// from the CLI's own installation.
+
+import { describe, test, expect, afterAll } from 'vitest'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import dedent from 'string-dedent'
+import { startDevServer, findFreePort, type RunningDevServer } from './dev-server.ts'
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterAll(async () => {
+  for (const cleanup of cleanups) {
+    await cleanup()
+  }
+})
+
+function makeScratchProject(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'egaki-dev-test-'))
+  const MDX = dedent`
+    ---
+    width: 1920
+    height: 1080
+    fps: 30
+    ---
+
+    # Hello duration=2
+
+    Zero-config dev server test.
+  `
+  fs.writeFileSync(path.join(dir, 'video.mdx'), MDX)
+  cleanups.push(async () => {
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+  return dir
+}
+
+describe('findFreePort', () => {
+  test('returns a valid port number', async () => {
+    const port = await findFreePort()
+    expect(port).toBeGreaterThan(0)
+    expect(port).toBeLessThan(65536)
+  })
+})
+
+describe('startDevServer', () => {
+  test('returns Error for missing entry', async () => {
+    const result = await startDevServer({ entry: '/nonexistent/path/video.mdx' })
+    expect(result).toBeInstanceOf(Error)
+    if (result instanceof Error) {
+      expect(result.message).toContain('entry not found')
+    }
+  })
+
+  test('returns Error for directory without mdx files', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'egaki-dev-empty-'))
+    cleanups.push(async () => {
+      fs.rmSync(dir, { recursive: true, force: true })
+    })
+    const result = await startDevServer({ entry: dir })
+    expect(result).toBeInstanceOf(Error)
+    if (result instanceof Error) {
+      expect(result.message).toContain('no .mdx files found')
+    }
+  })
+
+  test('returns Error for non-mdx file entry', async () => {
+    const dir = makeScratchProject()
+    const txtPath = path.join(dir, 'notes.txt')
+    fs.writeFileSync(txtPath, 'hi')
+    const result = await startDevServer({ entry: txtPath })
+    expect(result).toBeInstanceOf(Error)
+    if (result instanceof Error) {
+      expect(result.message).toContain('must be an .mdx file')
+    }
+  })
+
+  test('serves a scratch mdx file with no package.json or node_modules', async () => {
+    const dir = makeScratchProject()
+    const result = await startDevServer({
+      entry: path.join(dir, 'video.mdx'),
+    })
+    expect(result).not.toBeInstanceOf(Error)
+    const running = result as RunningDevServer
+    cleanups.push(() => running.close())
+
+    expect(running.root).toBe(dir)
+    expect(running.url).toMatch(/^http:\/\/localhost:\d+\/$/)
+
+    const response = await fetch(running.url)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toContain('text/html')
+    const html = await response.text()
+    // RSC streaming: the doctype shell arrives in a separate flush, so
+    // assert on stable player UI markup instead of '<html'.
+    expect(html).toContain('Export MP4')
+
+    // The dependency shim was created and is CLI-owned
+    expect(fs.existsSync(path.join(dir, 'node_modules', '.egaki-shim'))).toBe(true)
+    expect(
+      fs.lstatSync(path.join(dir, 'node_modules', 'egaki')).isSymbolicLink(),
+    ).toBe(true)
+  }, 120_000)
+})