egaki 0.6.0 → 0.7.0

package/dist/vite/tweakpane-hook.js

@@ -0,0 +1,450 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Tweakpane integration for the egaki video player.
+ *
+ * Provides useTweakpane() — a React hook that registers a folder of
+ * parameters in a shared tweakpane Pane singleton. Each component gets
+ * its own folder; when the component unmounts the folder is disposed and
+ * removed from the UI. This means only currently-visible components show
+ * their parameters.
+ *
+ * The Pane is mounted into a sidebar container managed by <TweakpaneRoot />,
+ * rendered once in player-page.tsx. The sidebar is always visible on the
+ * right side of the page and takes its own space in the layout (no floating
+ * overlay). A single "Copy changes" button at the top of the pane serializes
+ * all active component parameters as a structured prompt for AI agents.
+ *
+ * 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.
+ */
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore, createContext, useContext } from 'react';
+import { LayoutContainerContext, useIsPremounting } from "./mdx-video.js";
+export const TweakpaneContext = createContext(null);
+// ---------------------------------------------------------------------------
+// Global disable switch
+// ---------------------------------------------------------------------------
+/**
+ * Set to `true` to completely disable tweakpane across all components.
+ * useTweakpane() will return raw default values without mounting any UI.
+ */
+export let TWEAKPANE_DISABLED = false;
+// ---------------------------------------------------------------------------
+// Singleton pane state (module-level, not React state)
+// ---------------------------------------------------------------------------
+/** Lazily imported tweakpane Pane class and essentials plugin module. */
+let PaneClass = null;
+let EssentialsPlugin = null;
+let paneInstance = null;
+/** External container element set by TweakpaneRoot. The Pane mounts into
+ *  this DOM node instead of creating its own floating div. */
+let externalContainer = null;
+/** Persisted expanded state for the root pane across destroy/recreate cycles. */
+let paneExpandedState = true;
+const activeFolders = new Map();
+/** Listeners notified when activeFolders changes (for copy button visibility). */
+const folderListeners = new Set();
+function notifyFolderListeners() {
+    folderListeners.forEach((fn) => fn());
+}
+/** Shallow-clone arrays and plain objects so tweakpane's in-place mutations
+ *  don't leak between params and defaults references. */
+function cloneValue(value) {
+    if (Array.isArray(value))
+        return [...value];
+    if (typeof value === 'object' && value !== null)
+        return { ...value };
+    return value;
+}
+function resolveDefault(v) {
+    if (isCubicBezierParam(v))
+        return [...v.value];
+    if (isRangeParam(v))
+        return { ...v.value };
+    if (typeof v === 'object' && v !== null && 'value' in v)
+        return v.value;
+    return v;
+}
+function isSliderParam(v) {
+    return typeof v === 'object' && v !== null && 'value' in v && !('options' in v) && !('type' in v);
+}
+function isSelectParam(v) {
+    return typeof v === 'object' && v !== null && 'options' in v;
+}
+function isCubicBezierParam(v) {
+    return typeof v === 'object' && v !== null && 'type' in v && v.type === 'cubicBezier';
+}
+function isRangeParam(v) {
+    return typeof v === 'object' && v !== null && 'type' in v && v.type === 'range';
+}
+/** Guard against concurrent ensurePane() calls during the async import. */
+let panePromise = null;
+async function ensurePane() {
+    if (paneInstance)
+        return paneInstance;
+    if (panePromise)
+        return panePromise;
+    panePromise = (async () => {
+        if (!PaneClass) {
+            // Load tweakpane and the essentials plugin (cubic bezier blade) together.
+            // Both are cached at module level so subsequent pane re-creations (after
+            // disposePane on scene change) register the plugin synchronously, avoiding
+            // a race where concurrent ensurePane() callers get a pane without the
+            // plugin registered.
+            const [mod, essentials] = await Promise.all([
+                import('tweakpane'),
+                import('@tweakpane/plugin-essentials').catch(() => null),
+            ]);
+            PaneClass = mod.Pane;
+            EssentialsPlugin = essentials;
+        }
+        if (!externalContainer) {
+            console.warn('[egaki] TweakpaneRoot not mounted — tweakpane has no container');
+            return null;
+        }
+        paneInstance = new PaneClass({ container: externalContainer, title: 'Parameters', expanded: paneExpandedState });
+        if (EssentialsPlugin)
+            paneInstance.registerPlugin(EssentialsPlugin);
+        paneInstance.on('fold', (ev) => {
+            paneExpandedState = ev.expanded;
+        });
+        return paneInstance;
+    })();
+    const pane = await panePromise;
+    panePromise = null;
+    return pane;
+}
+function disposePane() {
+    if (paneInstance) {
+        paneInstance.dispose();
+        paneInstance = null;
+    }
+    // Don't remove the container — it's owned by TweakpaneRoot (React).
+    // The Pane's dispose() already removes its own element from the container.
+}
+// ---------------------------------------------------------------------------
+// Copy prompt serialization
+// ---------------------------------------------------------------------------
+function getCurrentSection(frame, sections) {
+    let acc = 0;
+    for (const s of sections) {
+        if (frame < acc + s.durationInFrames)
+            return s;
+        acc += s.durationInFrames;
+    }
+    return sections.length > 0 ? sections[sections.length - 1] : null;
+}
+function formatValue(v) {
+    if (Array.isArray(v) && v.length === 4 && v.every((x) => typeof x === 'number')) {
+        // Cubic bezier control points — format as cubicBezier() call so agents
+        // can paste it directly as an easing prop value.
+        return `cubicBezier(${v.join(', ')})`;
+    }
+    if (typeof v === 'object' && v !== null && 'min' in v && 'max' in v) {
+        const r = v;
+        const fmtNum = (n) => Number.isInteger(n) ? String(n) : n.toFixed(4).replace(/0+$/, '').replace(/\.$/, '');
+        return `{ min: ${fmtNum(r.min)}, max: ${fmtNum(r.max)} }`;
+    }
+    if (typeof v === 'number') {
+        return Number.isInteger(v) ? String(v) : v.toFixed(4).replace(/0+$/, '').replace(/\.$/, '');
+    }
+    return JSON.stringify(v);
+}
+function serializeTweakpanePrompt(ctx) {
+    if (activeFolders.size === 0)
+        return '';
+    const parts = ['## Parameter changes\n'];
+    if (ctx?.entryPath) {
+        parts.push(`File: ${ctx.entryPath}`);
+    }
+    // Frame + section context
+    if (ctx) {
+        const currentFrame = ctx.playerRef.current?.getCurrentFrame() ?? null;
+        if (currentFrame !== null) {
+            const seconds = (currentFrame / ctx.fps).toFixed(1);
+            parts.push(`Current frame: ${currentFrame} (${seconds}s at ${ctx.fps}fps)`);
+            const section = getCurrentSection(currentFrame, ctx.sections);
+            if (section?.heading) {
+                parts.push(`Section: "${section.heading}"`);
+            }
+            parts.push('');
+        }
+    }
+    let hasAnyChanges = false;
+    for (const [id, entry] of activeFolders) {
+        const changed = [];
+        for (const [key, current] of Object.entries(entry.params)) {
+            const def = entry.defaults[key];
+            if (current !== def) {
+                changed.push(`  ${key}: ${formatValue(current)}`);
+            }
+        }
+        if (changed.length > 0) {
+            hasAnyChanges = true;
+            parts.push(`**${entry.label}**`);
+            parts.push(changed.join('\n'));
+            parts.push('');
+        }
+    }
+    // If nothing changed from defaults, still show all current values
+    if (!hasAnyChanges) {
+        parts.push('No parameters changed from defaults.\n');
+        for (const [id, entry] of activeFolders) {
+            parts.push(`**${entry.label}** (current values)`);
+            for (const [key, current] of Object.entries(entry.params)) {
+                parts.push(`  ${key}: ${formatValue(current)}`);
+            }
+            parts.push('');
+        }
+    }
+    parts.push('Apply these values as the new props in the component code.');
+    return parts.join('\n');
+}
+// Module-level ref for the context value (set by TweakpaneRoot, read by the
+// copy button handler). Avoids threading React context into the imperative
+// tweakpane button click handler.
+let contextRef = null;
+// Stable module-level callbacks for useSyncExternalStore in CopyChangesButton.
+function subscribeFolders(cb) {
+    folderListeners.add(cb);
+    return () => { folderListeners.delete(cb); };
+}
+const getHasActiveFolders = () => activeFolders.size > 0;
+const getServerHasActiveFolders = () => false;
+/** React component: copy button rendered above the tweakpane pane. */
+function CopyChangesButton() {
+    const [copied, setCopied] = useState(false);
+    const hasActiveFolders = useSyncExternalStore(subscribeFolders, getHasActiveFolders, getServerHasActiveFolders);
+    if (!hasActiveFolders)
+        return null;
+    return (_jsx("button", { onClick: () => {
+            const text = serializeTweakpanePrompt(contextRef);
+            if (!text)
+                return;
+            navigator.clipboard.writeText(text).catch(() => { });
+            setCopied(true);
+            setTimeout(() => setCopied(false), 1500);
+        }, style: {
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: 6,
+            margin: '8px 8px 4px',
+            width: 'calc(100% - 16px)',
+            padding: '7px 12px',
+            background: copied ? 'rgba(34,197,94,0.15)' : 'rgba(255,255,255,0.06)',
+            border: '1px solid rgba(255,255,255,0.08)',
+            borderRadius: 6,
+            color: copied ? '#4ade80' : '#a1a1aa',
+            fontSize: 12,
+            fontWeight: 500,
+            fontFamily: '-apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", sans-serif',
+            cursor: 'pointer',
+            transition: 'background 0.15s, color 0.15s',
+        }, children: copied ? '✓ Copied prompt' : '📋 Copy changes' }));
+}
+// ---------------------------------------------------------------------------
+// useTweakpane hook
+// ---------------------------------------------------------------------------
+/**
+ * Register a folder of tweakable parameters for the current component.
+ *
+ * @param label  Folder title shown in the pane UI. Also set as
+ *               `data-tweakpane="label"` on a wrapper div for agent inspection.
+ * @param schema Parameter definitions. Each key maps to either:
+ *   - a bare `number`, `boolean`, or `string` (auto-inferred control)
+ *   - a `{ value, min?, max?, step? }` object for explicit slider range
+ *
+ * Returns a reactive object with current values. Updating a control in the
+ * pane immediately triggers a React re-render with fresh values.
+ *
+ * On unmount the folder is disposed and removed from the pane.
+ */
+export function useTweakpane(label, schema) {
+    // Skip registration inside layout-transition ghost renders (the previous
+    // section is re-rendered hidden for FLIP measurement; we don't want its
+    // components polluting the tweakpane UI) and premounted sequences
+    // (premountFor renders the next section early but invisible for preloading;
+    // Remotion freezes useCurrentFrame() at 0 and sets opacity: 0).
+    const container = useContext(LayoutContainerContext);
+    const isGhost = container === 'ghost';
+    const isPremounting = useIsPremounting();
+    const skip = isGhost || isPremounting;
+    const [values, setValues] = useState(() => {
+        const v = {};
+        for (const [key, param] of Object.entries(schema)) {
+            v[key] = resolveDefault(param);
+        }
+        return v;
+    });
+    // Track the schema for updates
+    const schemaRef = useRef(schema);
+    schemaRef.current = schema;
+    // Stable ID for this hook instance
+    const idRef = useRef(`${label}-${Math.random().toString(36).slice(2, 8)}`);
+    useEffect(() => {
+        // SSR guard, ghost/premount render, or globally disabled — skip all pane work.
+        // `skip` is in the dep array so the effect re-runs when premounting ends and
+        // the section becomes active (registers tweakpane) or vice versa (tears down).
+        if (typeof window === 'undefined' || skip || TWEAKPANE_DISABLED)
+            return;
+        const id = idRef.current;
+        // Mutable params object that tweakpane binds to
+        const params = {};
+        const defaults = {};
+        for (const [key, param] of Object.entries(schemaRef.current)) {
+            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);
+            defaults[key] = cloneValue(def);
+        }
+        let folder = null;
+        let disposed = false;
+        void (async () => {
+            const pane = await ensurePane();
+            if (disposed || !pane)
+                return;
+            folder = pane.addFolder({ title: label, expanded: true });
+            for (const [key, param] of Object.entries(schemaRef.current)) {
+                if (isCubicBezierParam(param)) {
+                    // Cubic bezier blade — visual curve editor
+                    const blade = folder.addBlade({
+                        view: 'cubicbezier',
+                        value: param.value,
+                        expanded: true,
+                        label: key,
+                        picker: 'inline',
+                    });
+                    blade.on('change', (ev) => {
+                        const val = ev.value;
+                        const tuple = [
+                            Math.round(val.x1 * 1000) / 1000,
+                            Math.round(val.y1 * 1000) / 1000,
+                            Math.round(val.x2 * 1000) / 1000,
+                            Math.round(val.y2 * 1000) / 1000,
+                        ];
+                        params[key] = tuple;
+                        setValues((prev) => ({ ...prev, [key]: tuple }));
+                    });
+                    continue;
+                }
+                if (isRangeParam(param)) {
+                    // Range slider from plugin-essentials — min/max pair as one control
+                    folder.addBinding(params, key, {
+                        min: param.min,
+                        max: param.max,
+                        step: param.step,
+                    }).on('change', (ev) => {
+                        const val = ev.value;
+                        setValues((prev) => ({ ...prev, [key]: { min: val.min, max: val.max } }));
+                    });
+                    continue;
+                }
+                const opts = {};
+                if (isSelectParam(param)) {
+                    // Build { Label: value } map for tweakpane list binding
+                    const optionsMap = {};
+                    for (const opt of param.options)
+                        optionsMap[opt] = opt;
+                    opts.options = optionsMap;
+                }
+                else if (isSliderParam(param)) {
+                    if (param.min !== undefined)
+                        opts.min = param.min;
+                    if (param.max !== undefined)
+                        opts.max = param.max;
+                    if (param.step !== undefined)
+                        opts.step = param.step;
+                }
+                else if (typeof param === 'number') {
+                    // Auto-infer range for bare numbers
+                    if (param >= 0 && param <= 1) {
+                        opts.min = 0;
+                        opts.max = 1;
+                        opts.step = 0.01;
+                    }
+                    else if (param >= 0 && param <= 10) {
+                        opts.min = 0;
+                        opts.max = param * 3 || 10;
+                        opts.step = 0.1;
+                    }
+                    else if (param >= 0 && param <= 100) {
+                        opts.min = 0;
+                        opts.max = param * 3 || 100;
+                        opts.step = 1;
+                    }
+                    else if (param >= 0) {
+                        opts.min = 0;
+                        opts.max = param * 3 || 1000;
+                        opts.step = 10;
+                    }
+                }
+                folder.addBinding(params, key, opts).on('change', (ev) => {
+                    setValues((prev) => ({ ...prev, [key]: ev.value }));
+                });
+            }
+            // Register for copy prompt
+            activeFolders.set(id, { label, params, defaults });
+            notifyFolderListeners();
+        })();
+        return () => {
+            disposed = true;
+            if (folder) {
+                folder.dispose();
+                folder = null;
+            }
+            activeFolders.delete(id);
+            notifyFolderListeners();
+            // If no more folders, tear down the pane entirely
+            if (activeFolders.size === 0) {
+                disposePane();
+            }
+        };
+    }, [label, skip]);
+    return values;
+}
+// ---------------------------------------------------------------------------
+// TweakpaneRoot — sidebar container for the tweakpane pane
+// ---------------------------------------------------------------------------
+/** Sidebar width constant shared with player-page layout. */
+export const SIDEBAR_WIDTH = 280;
+/**
+ * Right sidebar that hosts the tweakpane Pane. Always visible in the page
+ * layout; the Pane mounts into the scrollable inner div. Also provides
+ * player metadata (frame, fps, sections) to the copy prompt button.
+ */
+export function TweakpaneRoot({ playerRef, fps, sections, entryPath, }) {
+    // Ref callback sets the container synchronously when the DOM node mounts,
+    // before any child useEffect (where useTweakpane calls ensurePane). On
+    // unmount the callback receives null, so we clean up the pane.
+    const containerRefCallback = useCallback((node) => {
+        if (node) {
+            externalContainer = node;
+        }
+        else {
+            disposePane();
+            externalContainer = null;
+        }
+    }, []);
+    // Keep module-level ref in sync for the copy button handler
+    useEffect(() => {
+        contextRef = { playerRef, fps, sections, entryPath };
+        return () => {
+            contextRef = null;
+        };
+    }, [playerRef, fps, sections, entryPath]);
+    return (_jsxs("div", { className: 'egaki-sidebar', style: {
+            width: SIDEBAR_WIDTH,
+            minWidth: SIDEBAR_WIDTH,
+            height: '100vh',
+            position: 'sticky',
+            top: 0,
+            overflowY: 'auto',
+            overflowX: 'hidden',
+            background: '#111',
+            borderLeft: '1px solid rgba(255,255,255,0.08)',
+            flexShrink: 0,
+        }, children: [_jsx(CopyChangesButton, {}), _jsx("div", { ref: containerRefCallback, id: 'egaki-tweakpane', style: { width: '100%' } })] }));
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Vite plugin for the video framework.
+ *
+ * Discovers MDX files in the project root and serves each as a page route.
+ * The default entry (video.mdx or index.mdx) is served at /; others at
+ * /<relative-path-without-extension>. Auto-injects spiceflow + react plugins.
+ *
+ * Usage in vite.config.ts:
+ *   import { video } from 'egaki/vite'
+ *   export default defineConfig({ plugins: [video()] })
+ *   // or with explicit default entry:
+ *   export default defineConfig({ plugins: [video({ entry: './video.mdx' })] })
+ */
+import type { PluginOption } from 'vite';
+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.
+     *  All other .mdx files in the project become additional routes. */
+    entry?: string;
+}
+/**
+ * Compare old and new MDX sources section-by-section. Returns the index
+ * of the first added or edited section, or null if nothing changed (or
+ * only deletions occurred, which we skip per design).
+ */
+export declare function findChangedSectionIndex(oldSource: string, newSource: string): number | null;
+export declare function video(options?: VideoPluginOptions): PluginOption[];
+//# sourceMappingURL=vite-plugin.d.ts.map

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

@@ -0,0 +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;AA2BhD,MAAM,WAAW,kBAAkB;IACjC;;wEAEoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAuCD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuB3F;AAoCD,wBAAgB,KAAK,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,YAAY,EAAE,CAwalE"}