@framevideo/shader-transitions 0.0.3

package/dist/index.d.cts

@@ -0,0 +1,107 @@
+interface ShaderDef {
+    frag: string;
+}
+declare const shaders: Record<string, ShaderDef>;
+type ShaderName = keyof typeof shaders;
+declare const SHADER_NAMES: ShaderName[];
+
+interface GsapTimeline {
+    paused: () => boolean;
+    play: (from?: number, suppressEvents?: boolean) => GsapTimeline;
+    pause: (atTime?: number, suppressEvents?: boolean) => GsapTimeline;
+    time: {
+        (): number;
+        (value: number, suppressEvents?: boolean): GsapTimeline;
+    };
+    seek?: (position: number | string, suppressEvents?: boolean) => GsapTimeline;
+    call: (fn: () => void, args: null, position: number) => GsapTimeline;
+    to: (target: Record<string, unknown>, vars: Record<string, unknown>, position: number) => GsapTimeline;
+    set: (target: string, vars: Record<string, unknown>, position?: number) => GsapTimeline;
+    from: (target: string, vars: Record<string, unknown>, position?: number) => GsapTimeline;
+    fromTo: (target: string, from: Record<string, unknown>, to: Record<string, unknown>, position?: number) => GsapTimeline;
+    [key: string]: unknown;
+}
+interface TransitionConfig {
+    time: number;
+    /** Omit to use a CSS crossfade instead of a WebGL shader. */
+    shader?: ShaderName;
+    duration?: number;
+    ease?: string;
+}
+interface HyperShaderConfig {
+    bgColor: string;
+    accentColor?: string;
+    scenes: string[];
+    transitions: TransitionConfig[];
+    timeline?: GsapTimeline;
+    compositionId?: string;
+    previewCaptureFps?: number;
+}
+declare function init(config: HyperShaderConfig): GsapTimeline;
+
+declare function isHtmlInCanvasCaptureSupported(): boolean;
+
+interface AccentColors {
+    accent: [number, number, number];
+    dark: [number, number, number];
+    bright: [number, number, number];
+}
+
+/**
+ * engineModePageComposite — page-side WebGL compositor for engine render mode.
+ *
+ * Opt-in via `window.__FV_PAGE_SIDE_COMPOSITING__ = true` (set by the producer
+ * when `EngineConfig.enablePageSideCompositing` is true). When the flag is
+ * off, hyper-shader's engine-mode path stays on the opacity-flip-only timeline
+ * and the producer's fv#677 Node-side layered pipeline runs the shader blend.
+ *
+ * Two-phase capture protocol:
+ *
+ *  Phase 1 (seek wrapper, runs inside page.evaluate):
+ *    - Runs original GSAP seek to position the timeline
+ *    - If inside a transition window, clones FROM/TO scene elements into
+ *      layoutsubtree staging canvases
+ *    - Sets window.__fv_page_composite_pending with transition metadata
+ *    - Returns immediately (seek resolves)
+ *
+ *  Paint force (engine-side, frameCapture.ts):
+ *    - Engine detects the pending flag and fires a micro Page.captureScreenshot
+ *      to force the browser compositor to paint the staging canvas clones
+ *
+ *  Phase 2 (engine calls window.__fv_page_composite_resolve):
+ *    - drawElementImage reads the now-valid paint records from the clones
+ *    - Uploads textures to WebGL, runs the shader, shows the GL overlay
+ *    - Cleans up staging canvases
+ *
+ * This gives native-fidelity capture (identical to preview-path
+ * drawElementImage) without depending on requestAnimationFrame for paint.
+ */
+
+interface PageCompositeTransitionConfig {
+    time: number;
+    /**
+     * Shader id. Undefined entries are CSS crossfades — the page-side
+     * compositor skips them, and the GSAP timeline in `initEngineMode`
+     * schedules an actual opacity-crossfade tween for those entries so the
+     * single page screenshot contains a correct blended frame. The entry
+     * stays in the array to preserve `transitions[i]` ↔ `scenes[i]`/
+     * `scenes[i+1]` index alignment for the surrounding shader entries.
+     */
+    shader?: ShaderName;
+    duration?: number;
+}
+interface PageCompositorInstallOptions {
+    scenes: string[];
+    transitions: PageCompositeTransitionConfig[];
+    bgColor: string;
+    accentColors: AccentColors;
+    width: number;
+    height: number;
+    defaultDuration: number;
+}
+declare const PAGE_COMPOSITOR_CANVAS_ID = "__fv-page-side-compositor";
+declare const PAGE_COMPOSITOR_BUILD_CANARY = "__fv_page_compositor_v1__";
+declare function isPageSideCompositingSupported(): boolean;
+declare function installPageSideCompositor(options: PageCompositorInstallOptions): boolean;
+
+export { type HyperShaderConfig, PAGE_COMPOSITOR_BUILD_CANARY, PAGE_COMPOSITOR_CANVAS_ID, SHADER_NAMES, type ShaderName, type TransitionConfig, init, installPageSideCompositor, isHtmlInCanvasCaptureSupported, isPageSideCompositingSupported };

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+interface ShaderDef {
+    frag: string;
+}
+declare const shaders: Record<string, ShaderDef>;
+type ShaderName = keyof typeof shaders;
+declare const SHADER_NAMES: ShaderName[];
+
+interface GsapTimeline {
+    paused: () => boolean;
+    play: (from?: number, suppressEvents?: boolean) => GsapTimeline;
+    pause: (atTime?: number, suppressEvents?: boolean) => GsapTimeline;
+    time: {
+        (): number;
+        (value: number, suppressEvents?: boolean): GsapTimeline;
+    };
+    seek?: (position: number | string, suppressEvents?: boolean) => GsapTimeline;
+    call: (fn: () => void, args: null, position: number) => GsapTimeline;
+    to: (target: Record<string, unknown>, vars: Record<string, unknown>, position: number) => GsapTimeline;
+    set: (target: string, vars: Record<string, unknown>, position?: number) => GsapTimeline;
+    from: (target: string, vars: Record<string, unknown>, position?: number) => GsapTimeline;
+    fromTo: (target: string, from: Record<string, unknown>, to: Record<string, unknown>, position?: number) => GsapTimeline;
+    [key: string]: unknown;
+}
+interface TransitionConfig {
+    time: number;
+    /** Omit to use a CSS crossfade instead of a WebGL shader. */
+    shader?: ShaderName;
+    duration?: number;
+    ease?: string;
+}
+interface HyperShaderConfig {
+    bgColor: string;
+    accentColor?: string;
+    scenes: string[];
+    transitions: TransitionConfig[];
+    timeline?: GsapTimeline;
+    compositionId?: string;
+    previewCaptureFps?: number;
+}
+declare function init(config: HyperShaderConfig): GsapTimeline;
+
+declare function isHtmlInCanvasCaptureSupported(): boolean;
+
+interface AccentColors {
+    accent: [number, number, number];
+    dark: [number, number, number];
+    bright: [number, number, number];
+}
+
+/**
+ * engineModePageComposite — page-side WebGL compositor for engine render mode.
+ *
+ * Opt-in via `window.__FV_PAGE_SIDE_COMPOSITING__ = true` (set by the producer
+ * when `EngineConfig.enablePageSideCompositing` is true). When the flag is
+ * off, hyper-shader's engine-mode path stays on the opacity-flip-only timeline
+ * and the producer's fv#677 Node-side layered pipeline runs the shader blend.
+ *
+ * Two-phase capture protocol:
+ *
+ *  Phase 1 (seek wrapper, runs inside page.evaluate):
+ *    - Runs original GSAP seek to position the timeline
+ *    - If inside a transition window, clones FROM/TO scene elements into
+ *      layoutsubtree staging canvases
+ *    - Sets window.__fv_page_composite_pending with transition metadata
+ *    - Returns immediately (seek resolves)
+ *
+ *  Paint force (engine-side, frameCapture.ts):
+ *    - Engine detects the pending flag and fires a micro Page.captureScreenshot
+ *      to force the browser compositor to paint the staging canvas clones
+ *
+ *  Phase 2 (engine calls window.__fv_page_composite_resolve):
+ *    - drawElementImage reads the now-valid paint records from the clones
+ *    - Uploads textures to WebGL, runs the shader, shows the GL overlay
+ *    - Cleans up staging canvases
+ *
+ * This gives native-fidelity capture (identical to preview-path
+ * drawElementImage) without depending on requestAnimationFrame for paint.
+ */
+
+interface PageCompositeTransitionConfig {
+    time: number;
+    /**
+     * Shader id. Undefined entries are CSS crossfades — the page-side
+     * compositor skips them, and the GSAP timeline in `initEngineMode`
+     * schedules an actual opacity-crossfade tween for those entries so the
+     * single page screenshot contains a correct blended frame. The entry
+     * stays in the array to preserve `transitions[i]` ↔ `scenes[i]`/
+     * `scenes[i+1]` index alignment for the surrounding shader entries.
+     */
+    shader?: ShaderName;
+    duration?: number;
+}
+interface PageCompositorInstallOptions {
+    scenes: string[];
+    transitions: PageCompositeTransitionConfig[];
+    bgColor: string;
+    accentColors: AccentColors;
+    width: number;
+    height: number;
+    defaultDuration: number;
+}
+declare const PAGE_COMPOSITOR_CANVAS_ID = "__fv-page-side-compositor";
+declare const PAGE_COMPOSITOR_BUILD_CANARY = "__fv_page_compositor_v1__";
+declare function isPageSideCompositingSupported(): boolean;
+declare function installPageSideCompositor(options: PageCompositorInstallOptions): boolean;
+
+export { type HyperShaderConfig, PAGE_COMPOSITOR_BUILD_CANARY, PAGE_COMPOSITOR_CANVAS_ID, SHADER_NAMES, type ShaderName, type TransitionConfig, init, installPageSideCompositor, isHtmlInCanvasCaptureSupported, isPageSideCompositingSupported };