animot-presenter 0.5.5 → 0.5.7

package/dist/engine/utils.d.ts

@@ -15,13 +15,22 @@ export declare function computeFloatSpeed(cfg: {
     speed: number;
     speedRandomness?: number;
 }, seed: string): number;
-export declare function getBackgroundStyle(bg: {
+interface GradientStop {
+    color: string;
+    position: number;
+}
+interface BgInput {
     type: string;
     color?: string;
     gradient?: {
         type: string;
         angle?: number;
         colors: string[];
+        stops?: GradientStop[];
+        radialShape?: 'circle' | 'ellipse';
+        radialPosition?: string;
     };
     image?: string;
-}): string;
+}
+export declare function getBackgroundStyle(bg: BgInput): string;
+export {};

package/dist/engine/utils.js

@@ -73,16 +73,28 @@ export function computeFloatSpeed(cfg, seed) {
         return cfg.speed;
     return cfg.speed * (1 - r + r * hashFraction(seed, 2));
 }
+function buildStops(colors, stops) {
+    if (stops && stops.length > 0) {
+        const sorted = [...stops].sort((a, b) => a.position - b.position);
+        return sorted.map((s) => `${s.color} ${s.position}%`).join(', ');
+    }
+    if (colors.length <= 1)
+        return colors[0] ?? '#000';
+    return colors.map((c, i) => `${c} ${(i / (colors.length - 1)) * 100}%`).join(', ');
+}
 export function getBackgroundStyle(bg) {
     if (bg.type === 'transparent')
         return 'background: transparent';
     if (bg.type === 'solid')
         return `background-color: ${bg.color ?? 'transparent'}`;
     if (bg.type === 'gradient' && bg.gradient) {
-        const { type, angle = 135, colors } = bg.gradient;
-        if (type === 'linear')
-            return `background: linear-gradient(${angle}deg, ${colors.join(', ')})`;
-        return `background: radial-gradient(circle, ${colors.join(', ')})`;
+        const { type, angle = 135, colors, stops, radialShape = 'circle', radialPosition = 'center' } = bg.gradient;
+        const stopList = buildStops(colors, stops);
+        if (type === 'conic')
+            return `background: conic-gradient(from ${angle}deg at ${radialPosition}, ${stopList})`;
+        if (type === 'radial')
+            return `background: radial-gradient(${radialShape} at ${radialPosition}, ${stopList})`;
+        return `background: linear-gradient(${angle}deg, ${stopList})`;
     }
     if (bg.type === 'image' && bg.image)
         return `background-image: url(${bg.image}); background-size: cover; background-position: center`;

package/dist/types.d.ts

@@ -71,6 +71,8 @@ export interface BaseElement {
     backfaceVisibility?: 'visible' | 'hidden';
     animationConfig?: ElementAnimationConfig;
     floatingAnimation?: FloatingAnimationConfig;
+    decorations?: DecorationsConfig;
+    depth?: number;
     motionPathId?: string;
     motionPathConfig?: MotionPathConfig;
     blur?: number;
@@ -107,10 +109,13 @@ export interface CodeElement extends BaseElement {
     headerRadius?: number;
     tabRadius?: number;
 }
-export type TextAnimationMode = 'instant' | 'typewriter' | 'fade-words';
+export type TextAnimationMode = 'instant' | 'typewriter' | 'fade-words' | 'fade-letters' | 'handwriting' | 'bounce-in';
 export interface TextAnimationConfig {
     mode: TextAnimationMode;
     typewriterSpeed: number;
+    duration?: number;
+    stagger?: number;
+    loop?: boolean;
 }
 export interface TextElement extends BaseElement {
     type: 'text';
@@ -198,6 +203,55 @@ export interface ImageElement extends BaseElement {
         borderRadius?: number;
     };
 }
+export interface CameraViewport {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+}
+export interface DecorationsConfig {
+    glow?: {
+        enabled: boolean;
+        color: string;
+        intensity?: number;
+        speedMs?: number;
+    };
+    shimmer?: {
+        enabled: boolean;
+        color?: string;
+        angle?: number;
+        speedMs?: number;
+        widthPct?: number;
+    };
+    gradientShift?: {
+        enabled: boolean;
+        colors?: string[];
+        speedMs?: number;
+        angle?: number;
+    };
+    rgbSplit?: {
+        enabled: boolean;
+        offset?: number;
+        speedMs?: number;
+    };
+}
+export interface VideoElement extends BaseElement {
+    type: 'video';
+    src: string;
+    posterImage?: string;
+    startTime?: number;
+    endTime?: number;
+    volume: number;
+    muted: boolean;
+    autoplay: boolean;
+    loop: boolean;
+    playbackRate: number;
+    objectFit: 'cover' | 'contain' | 'fill';
+    borderRadius: number;
+    opacity: number;
+    showControls?: boolean;
+}
 export type StrokeStyle = 'solid' | 'dashed' | 'dotted';
 export interface ShapeElement extends BaseElement {
     type: 'shape';
@@ -290,7 +344,7 @@ export interface MotionPathElement extends BaseElement {
     pathWidth: number;
     showInPresentation: boolean;
 }
-export type CanvasElement = CodeElement | TextElement | ArrowElement | ImageElement | ShapeElement | CounterElement | ChartElement | IconElement | SvgElement | MotionPathElement;
+export type CanvasElement = CodeElement | TextElement | ArrowElement | ImageElement | VideoElement | ShapeElement | CounterElement | ChartElement | IconElement | SvgElement | MotionPathElement;
 export type ParticleShape = 'circle' | 'square' | 'star' | 'triangle';
 export interface ParticlesConfig {
     enabled: boolean;
@@ -316,13 +370,20 @@ export interface ConfettiConfig {
     startVelocity: number;
     scalar: number;
 }
+export interface GradientStop {
+    color: string;
+    position: number;
+}
 export interface CanvasBackground {
     type: 'solid' | 'gradient' | 'image' | 'transparent';
     color?: string;
     gradient?: {
-        type: 'linear' | 'radial';
+        type: 'linear' | 'radial' | 'conic';
         angle?: number;
         colors: string[];
+        stops?: GradientStop[];
+        radialShape?: 'circle' | 'ellipse';
+        radialPosition?: string;
     };
     image?: string;
     particles?: ParticlesConfig;
@@ -346,6 +407,7 @@ export interface Slide {
     canvas: SlideCanvas;
     transition: TransitionConfig;
     duration: number;
+    camera?: CameraViewport;
 }
 export interface ProjectSettings {
     defaultCanvasWidth: number;

package/dist/utils/animated-image.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Decode an animated image (GIF / APNG / animated WebP / animated AVIF) into
+ * a list of frames with cumulative timing using the browser's ImageDecoder
+ * API. Used by the server-side export pipeline so that animated <img> elements
+ * can be rendered frame-accurately under our virtual clock — native <img>
+ * playback ignores virtual time, so without this every captured frame would
+ * show the GIF stuck at frame 0.
+ *
+ * Live `/present` keeps using <img> directly; only the export pipeline opts
+ * into the canvas-from-decoded-frames path.
+ */
+export interface DecodedFrame {
+    bitmap: ImageBitmap;
+    /** Frame display duration in ms. */
+    durationMs: number;
+}
+export interface DecodedAnimatedImage {
+    frames: DecodedFrame[];
+    totalMs: number;
+    width: number;
+    height: number;
+}
+/** True if the URL/data-URL looks like an animated container we can decode.
+ * We don't try to detect "animated PNG" vs "static PNG" upfront — the decoder
+ * call below will return one frame for static images and that's fine. */
+export declare function isLikelyAnimated(src: string): boolean;
+/** Decode every frame of an animated image. Falls back to a single-frame
+ * result for static images. Returns null when ImageDecoder is unavailable
+ * (e.g. older browsers) so callers can degrade gracefully. */
+export declare function decodeAnimatedImage(src: string): Promise<DecodedAnimatedImage | null>;
+/** Pick the frame that should be visible at `elapsedMs` for a looping animation
+ * of total `totalMs`. Returns the index. */
+export declare function frameIndexAt(decoded: DecodedAnimatedImage, elapsedMs: number): number;
+/** Draw the frame visible at `elapsedMs` into the given canvas. */
+export declare function drawFrameAt(canvas: HTMLCanvasElement, decoded: DecodedAnimatedImage, elapsedMs: number): void;

package/dist/utils/animated-image.js

@@ -0,0 +1,100 @@
+/**
+ * Decode an animated image (GIF / APNG / animated WebP / animated AVIF) into
+ * a list of frames with cumulative timing using the browser's ImageDecoder
+ * API. Used by the server-side export pipeline so that animated <img> elements
+ * can be rendered frame-accurately under our virtual clock — native <img>
+ * playback ignores virtual time, so without this every captured frame would
+ * show the GIF stuck at frame 0.
+ *
+ * Live `/present` keeps using <img> directly; only the export pipeline opts
+ * into the canvas-from-decoded-frames path.
+ */
+/** True if the URL/data-URL looks like an animated container we can decode.
+ * We don't try to detect "animated PNG" vs "static PNG" upfront — the decoder
+ * call below will return one frame for static images and that's fine. */
+export function isLikelyAnimated(src) {
+    if (!src)
+        return false;
+    // Data URL — sniff the MIME.
+    if (src.startsWith('data:')) {
+        const mime = src.slice(5).split(';')[0].toLowerCase();
+        return mime === 'image/gif' || mime === 'image/apng' || mime === 'image/webp' || mime === 'image/avif' || mime === 'image/png';
+    }
+    // Otherwise look at the path extension.
+    const lower = src.toLowerCase().split('?')[0];
+    return lower.endsWith('.gif') || lower.endsWith('.apng') || lower.endsWith('.webp') || lower.endsWith('.avif');
+}
+async function srcToBlob(src) {
+    const res = await fetch(src);
+    return await res.blob();
+}
+/** Decode every frame of an animated image. Falls back to a single-frame
+ * result for static images. Returns null when ImageDecoder is unavailable
+ * (e.g. older browsers) so callers can degrade gracefully. */
+export async function decodeAnimatedImage(src) {
+    if (typeof globalThis.ImageDecoder === 'undefined')
+        return null;
+    try {
+        const blob = await srcToBlob(src);
+        const decoder = new globalThis.ImageDecoder({ data: blob.stream(), type: blob.type || 'image/gif' });
+        await decoder.tracks.ready;
+        await decoder.completed;
+        const frameCount = decoder.tracks.selectedTrack?.frameCount ?? 1;
+        const frames = [];
+        let totalMs = 0;
+        let width = 0;
+        let height = 0;
+        for (let i = 0; i < frameCount; i++) {
+            const result = await decoder.decode({ frameIndex: i });
+            const vf = result.image;
+            width = vf.displayWidth || vf.codedWidth || width;
+            height = vf.displayHeight || vf.codedHeight || height;
+            // duration is in microseconds when present; some decoders return null
+            // for the last frame — fall back to a sensible 100ms (~10fps) so we
+            // don't divide by zero when seeking.
+            const durMs = vf.duration != null ? vf.duration / 1000 : 100;
+            const bitmap = await createImageBitmap(vf);
+            vf.close?.();
+            frames.push({ bitmap, durationMs: durMs });
+            totalMs += durMs;
+        }
+        decoder.close?.();
+        return { frames, totalMs, width, height };
+    }
+    catch (err) {
+        console.warn('Failed to decode animated image:', err);
+        return null;
+    }
+}
+/** Pick the frame that should be visible at `elapsedMs` for a looping animation
+ * of total `totalMs`. Returns the index. */
+export function frameIndexAt(decoded, elapsedMs) {
+    if (decoded.totalMs <= 0 || decoded.frames.length === 0)
+        return 0;
+    const t = ((elapsedMs % decoded.totalMs) + decoded.totalMs) % decoded.totalMs;
+    let acc = 0;
+    for (let i = 0; i < decoded.frames.length; i++) {
+        acc += decoded.frames[i].durationMs;
+        if (t < acc)
+            return i;
+    }
+    return decoded.frames.length - 1;
+}
+/** Draw the frame visible at `elapsedMs` into the given canvas. */
+export function drawFrameAt(canvas, decoded, elapsedMs) {
+    const idx = frameIndexAt(decoded, elapsedMs);
+    const frame = decoded.frames[idx];
+    if (!frame)
+        return;
+    // Resize the canvas backing-store to the natural frame size only once;
+    // the wrapping CSS scales it to the element box.
+    if (canvas.width !== decoded.width)
+        canvas.width = decoded.width;
+    if (canvas.height !== decoded.height)
+        canvas.height = decoded.height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        return;
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    ctx.drawImage(frame.bitmap, 0, 0);
+}

package/dist/utils/camera.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Cinema-mode camera math.
+ *
+ * Concept: in cinema mode every slide shares one large "world canvas" (defined
+ * by Project.settings.worldWidth/Height). Each slide has a `camera` viewport —
+ * a rect in world coordinates that we want to fill the visible canvas. The
+ * transition between two slides = animating the camera (pan + zoom + roll).
+ *
+ * To render: we wrap all elements in a transform that maps the camera rect to
+ * the visible canvas dimensions. Element positions stay in world coordinates;
+ * only the wrapper transforms.
+ *
+ * Parallax: each element can declare a `depth` in [-1, +1]. Elements behind
+ * the camera (negative depth) appear to move less; elements in front move
+ * more. Implemented as an additional translate proportional to camera offset.
+ */
+import type { CameraViewport } from '../types';
+export interface CameraTransformInput {
+    camera: CameraViewport;
+    /** Output viewport — typically the slide canvas dims. */
+    viewportWidth: number;
+    viewportHeight: number;
+}
+/** Build the CSS transform that maps a camera rect over the world to fill the
+ * given output viewport. Returned as a single transform string ready for
+ * `style:transform="..."`. */
+export declare function cameraTransform({ camera, viewportWidth, viewportHeight }: CameraTransformInput): string;
+/** Lerp between two camera viewports for transitions. */
+export declare function lerpCamera(a: CameraViewport, b: CameraViewport, t: number): CameraViewport;
+/** Default camera = full world (no zoom, no pan). Used when a slide is in
+ * cinema mode but its camera is unset. */
+export declare function defaultCamera(worldWidth: number, worldHeight: number): CameraViewport;
+/** Per-element parallax offset. Elements with depth = 0 move 1:1 with the
+ * camera; depth > 0 moves more (closer); depth < 0 moves less (farther). The
+ * factor maps depth → multiplier such that depth=1 doubles motion, depth=-1
+ * halves it. We compute the offset from the *delta between the camera's
+ * current position and a neutral world center* — gives a plausible parallax
+ * without needing a separate reference camera per element.
+ */
+export declare function parallaxOffset(camera: CameraViewport, depth: number, worldWidth: number, worldHeight: number): {
+    x: number;
+    y: number;
+};

package/dist/utils/camera.js

@@ -0,0 +1,66 @@
+/**
+ * Cinema-mode camera math.
+ *
+ * Concept: in cinema mode every slide shares one large "world canvas" (defined
+ * by Project.settings.worldWidth/Height). Each slide has a `camera` viewport —
+ * a rect in world coordinates that we want to fill the visible canvas. The
+ * transition between two slides = animating the camera (pan + zoom + roll).
+ *
+ * To render: we wrap all elements in a transform that maps the camera rect to
+ * the visible canvas dimensions. Element positions stay in world coordinates;
+ * only the wrapper transforms.
+ *
+ * Parallax: each element can declare a `depth` in [-1, +1]. Elements behind
+ * the camera (negative depth) appear to move less; elements in front move
+ * more. Implemented as an additional translate proportional to camera offset.
+ */
+/** Build the CSS transform that maps a camera rect over the world to fill the
+ * given output viewport. Returned as a single transform string ready for
+ * `style:transform="..."`. */
+export function cameraTransform({ camera, viewportWidth, viewportHeight }) {
+    const sx = viewportWidth / Math.max(1, camera.width);
+    const sy = viewportHeight / Math.max(1, camera.height);
+    // Uniform scale so circles stay circles. We pick the smaller axis so the
+    // camera rect fully fits the viewport (letterboxes the rest); use Math.max
+    // instead if "cover" semantics are wanted.
+    const s = Math.min(sx, sy);
+    const rotation = camera.rotation ?? 0;
+    // Order: translate world → camera origin, then scale, then rotate. Reads
+    // right-to-left in CSS so we write it scale → translate.
+    return `scale(${s}) rotate(${-rotation}deg) translate(${-camera.x}px, ${-camera.y}px)`;
+}
+/** Lerp between two camera viewports for transitions. */
+export function lerpCamera(a, b, t) {
+    const lerp = (x, y) => x + (y - x) * t;
+    return {
+        x: lerp(a.x, b.x),
+        y: lerp(a.y, b.y),
+        width: lerp(a.width, b.width),
+        height: lerp(a.height, b.height),
+        rotation: lerp(a.rotation ?? 0, b.rotation ?? 0)
+    };
+}
+/** Default camera = full world (no zoom, no pan). Used when a slide is in
+ * cinema mode but its camera is unset. */
+export function defaultCamera(worldWidth, worldHeight) {
+    return { x: 0, y: 0, width: worldWidth, height: worldHeight, rotation: 0 };
+}
+/** Per-element parallax offset. Elements with depth = 0 move 1:1 with the
+ * camera; depth > 0 moves more (closer); depth < 0 moves less (farther). The
+ * factor maps depth → multiplier such that depth=1 doubles motion, depth=-1
+ * halves it. We compute the offset from the *delta between the camera's
+ * current position and a neutral world center* — gives a plausible parallax
+ * without needing a separate reference camera per element.
+ */
+export function parallaxOffset(camera, depth, worldWidth, worldHeight) {
+    if (!depth)
+        return { x: 0, y: 0 };
+    const cx = camera.x + camera.width / 2;
+    const cy = camera.y + camera.height / 2;
+    const wx = worldWidth / 2;
+    const wy = worldHeight / 2;
+    // Tame the multiplier — full ±1 doubling is too much in practice; use 0.4
+    // so depth = +1 means 40% extra parallax, depth = -1 means 40% damped.
+    const factor = depth * 0.4;
+    return { x: -(cx - wx) * factor, y: -(cy - wy) * factor };
+}

package/dist/utils/decorations.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Svelte action: applies ambient decorative animations to an element. These
+ * sit on top of the morph/transition system — they're continuous loops driven
+ * by the same virtual-clock restart registry (__svgAnimRestart) so they reset
+ * cleanly on slide enter and align in Flow-mode GIF exports.
+ *
+ * Effects:
+ *   • glow         — pulsing colored box-shadow halo
+ *   • shimmer      — diagonal highlight stripe sweeping across the element
+ *   • gradientShift — animates background-position on a multi-color gradient
+ *   • rgbSplit     — chromatic-aberration-style R/B channel offset (drop-shadow)
+ */
+import type { DecorationsConfig } from '../types';
+export interface DecorationsParams {
+    config?: DecorationsConfig;
+    /** Slide loop duration; when present, each effect's cycle is rounded so an
+     * integer number fits in slide_duration — guarantees seamless GIF loop. */
+    slideDuration?: number;
+    /** Bumped by the host when ANY decoration prop changes. Without it the
+     * action would silently keep running with stale params. */
+    key?: unknown;
+}
+export declare function decorations(node: HTMLElement, params: DecorationsParams): {
+    update(p: DecorationsParams): void;
+    destroy(): void;
+};

package/dist/utils/decorations.js

@@ -0,0 +1,168 @@
+/**
+ * Svelte action: applies ambient decorative animations to an element. These
+ * sit on top of the morph/transition system — they're continuous loops driven
+ * by the same virtual-clock restart registry (__svgAnimRestart) so they reset
+ * cleanly on slide enter and align in Flow-mode GIF exports.
+ *
+ * Effects:
+ *   • glow         — pulsing colored box-shadow halo
+ *   • shimmer      — diagonal highlight stripe sweeping across the element
+ *   • gradientShift — animates background-position on a multi-color gradient
+ *   • rgbSplit     — chromatic-aberration-style R/B channel offset (drop-shadow)
+ */
+function effectiveCycle(requested, slideDuration) {
+    if (slideDuration && slideDuration > 0) {
+        return slideDuration / Math.max(1, Math.round(slideDuration / requested));
+    }
+    return requested;
+}
+export function decorations(node, params) {
+    let raf = 0;
+    let shimmerEl = null;
+    let originalBoxShadow = '';
+    let originalFilter = '';
+    let originalBackgroundImage = '';
+    let originalBackgroundSize = '';
+    let originalBackgroundPosition = '';
+    let savedOriginal = false;
+    function saveOriginalStyles() {
+        if (savedOriginal)
+            return;
+        originalBoxShadow = node.style.boxShadow;
+        originalFilter = node.style.filter;
+        originalBackgroundImage = node.style.backgroundImage;
+        originalBackgroundSize = node.style.backgroundSize;
+        originalBackgroundPosition = node.style.backgroundPosition;
+        savedOriginal = true;
+    }
+    function restoreOriginalStyles() {
+        node.style.boxShadow = originalBoxShadow;
+        node.style.filter = originalFilter;
+        node.style.backgroundImage = originalBackgroundImage;
+        node.style.backgroundSize = originalBackgroundSize;
+        node.style.backgroundPosition = originalBackgroundPosition;
+        if (shimmerEl) {
+            shimmerEl.remove();
+            shimmerEl = null;
+        }
+    }
+    function reset() {
+        if (raf)
+            cancelAnimationFrame(raf);
+        raf = 0;
+        restoreOriginalStyles();
+    }
+    function run() {
+        reset();
+        const cfg = params.config;
+        if (!cfg)
+            return;
+        const anyEnabled = cfg.glow?.enabled || cfg.shimmer?.enabled || cfg.gradientShift?.enabled || cfg.rgbSplit?.enabled;
+        if (!anyEnabled)
+            return;
+        saveOriginalStyles();
+        // Shimmer needs a positioned overlay — we inject it as a child. The
+        // element must already be `position: relative` (or non-static) to clip
+        // the overlay correctly; we coerce it here without mutating user state
+        // permanently (restoreOriginalStyles puts back any inline style).
+        if (cfg.shimmer?.enabled) {
+            if (getComputedStyle(node).position === 'static') {
+                node.style.position = 'relative';
+            }
+            shimmerEl = document.createElement('div');
+            shimmerEl.className = 'animot-shimmer';
+            const angle = cfg.shimmer.angle ?? 110;
+            const widthPct = cfg.shimmer.widthPct ?? 25;
+            const color = cfg.shimmer.color ?? 'rgba(255, 255, 255, 0.4)';
+            Object.assign(shimmerEl.style, {
+                position: 'absolute',
+                inset: '0',
+                pointerEvents: 'none',
+                overflow: 'hidden',
+                borderRadius: 'inherit',
+                background: `linear-gradient(${angle}deg, transparent 0%, transparent ${50 - widthPct / 2}%, ${color} 50%, transparent ${50 + widthPct / 2}%, transparent 100%)`,
+                backgroundSize: '300% 300%',
+                backgroundPosition: '-100% -100%'
+            });
+            node.appendChild(shimmerEl);
+        }
+        // Initial styles for the static parts of each effect.
+        if (cfg.gradientShift?.enabled) {
+            const colors = cfg.gradientShift.colors ?? ['#7c3aed', '#06b6d4', '#ec4899', '#7c3aed'];
+            const angle = cfg.gradientShift.angle ?? 135;
+            node.style.backgroundImage = `linear-gradient(${angle}deg, ${colors.join(', ')})`;
+            node.style.backgroundSize = '300% 300%';
+        }
+        const start = performance.now();
+        function tick(now) {
+            const elapsed = now - start;
+            // GLOW — pulsing box-shadow.
+            if (cfg.glow?.enabled) {
+                const cycle = effectiveCycle(cfg.glow.speedMs ?? 2400, params.slideDuration);
+                const phase = (elapsed % cycle) / cycle; // 0–1
+                const wave = (Math.sin(phase * Math.PI * 2) + 1) / 2; // 0–1
+                const intensity = cfg.glow.intensity ?? 0.6;
+                const blur = 12 + wave * 36 * intensity;
+                const spread = 2 + wave * 8 * intensity;
+                node.style.boxShadow = `0 0 ${blur}px ${spread}px ${cfg.glow.color}`;
+            }
+            // SHIMMER — sweep the gradient overlay diagonally across the element.
+            if (cfg.shimmer?.enabled && shimmerEl) {
+                const cycle = effectiveCycle(cfg.shimmer.speedMs ?? 3000, params.slideDuration);
+                const phase = (elapsed % cycle) / cycle;
+                // Sweep -100% → 200% so the highlight enters from the top-left, leaves bottom-right.
+                const pos = -100 + phase * 300;
+                shimmerEl.style.backgroundPosition = `${pos}% ${pos}%`;
+            }
+            // GRADIENT SHIFT — animate background-position on the multi-stop gradient.
+            if (cfg.gradientShift?.enabled) {
+                const cycle = effectiveCycle(cfg.gradientShift.speedMs ?? 6000, params.slideDuration);
+                const phase = (elapsed % cycle) / cycle;
+                const pos = phase * 300; // 0% → 300% creates a smooth loop with backgroundSize 300%
+                node.style.backgroundPosition = `${pos}% 50%`;
+            }
+            // RGB SPLIT — chromatic aberration via stacked drop-shadows.
+            if (cfg.rgbSplit?.enabled) {
+                const offset = cfg.rgbSplit.offset ?? 3;
+                let dx = offset;
+                if ((cfg.rgbSplit.speedMs ?? 0) > 0) {
+                    const cycle = effectiveCycle(cfg.rgbSplit.speedMs, params.slideDuration);
+                    const phase = (elapsed % cycle) / cycle;
+                    dx = offset * Math.sin(phase * Math.PI * 2);
+                }
+                node.style.filter = `${originalFilter} drop-shadow(${dx}px 0 0 rgba(255, 0, 64, 0.7)) drop-shadow(${-dx}px 0 0 rgba(0, 200, 255, 0.7))`;
+            }
+            raf = requestAnimationFrame(tick);
+        }
+        raf = requestAnimationFrame(tick);
+    }
+    queueMicrotask(run);
+    if (typeof window !== 'undefined') {
+        const reg = (window.__svgAnimRestart ||= []);
+        reg.push(run);
+        node.__decorationsRestart = run;
+    }
+    let lastKey = params.key;
+    return {
+        update(p) {
+            const keyChanged = p.key !== lastKey;
+            params = p;
+            if (keyChanged) {
+                lastKey = p.key;
+                queueMicrotask(run);
+            }
+        },
+        destroy() {
+            reset();
+            if (typeof window !== 'undefined') {
+                const reg = window.__svgAnimRestart;
+                const fn = node.__decorationsRestart;
+                if (reg && fn) {
+                    const idx = reg.indexOf(fn);
+                    if (idx >= 0)
+                        reg.splice(idx, 1);
+                }
+            }
+        }
+    };
+}

package/dist/utils/text-animate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Svelte action: animates a text element's content via JS RAF.
+ *
+ * Implemented modes:
+ *   • fade-letters — wraps each character in a <span> and fades them in with stagger
+ *   • bounce-in    — same wrapping, scale+translate pop per character
+ *   • handwriting  — re-renders the text inside an <svg><text> with stroke + transparent
+ *                    fill and animates `stroke-dashoffset` so the text appears to be
+ *                    drawn left-to-right (works best with cursive/script fonts)
+ *
+ * Other modes (instant, typewriter, fade-words) are handled elsewhere by the
+ * /present render path — this action no-ops for those.
+ *
+ * The action registers a restart fn into `window.__svgAnimRestart` so the
+ * server-side video export pipeline can reset all animations under the
+ * virtual clock at the start of the slide hold (same pattern as FlowMarkers
+ * and arrowClipDraw).
+ */
+export type TextAnimateMode = 'instant' | 'typewriter' | 'fade-words' | 'fade-letters' | 'handwriting' | 'bounce-in';
+export interface TextAnimateParams {
+    enabled: boolean;
+    mode: TextAnimateMode;
+    content: string;
+    /** Total duration in ms for handwriting; for stagger modes it's the per-letter
+     * delay budget — actual total = stagger * letterCount + perLetterDuration. */
+    duration: number;
+    stagger?: number;
+    loop?: boolean;
+    /** Cosmetic: applied to the inner SVG text in handwriting mode. */
+    color?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: number | string;
+    fontStyle?: string;
+    textAlign?: 'left' | 'center' | 'right';
+    /** Slide loop duration; when present the effective duration aligns to a
+     * cycle that fits an integer number of times into slide_duration so GIF
+     * loops are seamless in Flow mode. */
+    slideDuration?: number;
+    /** Bumped by the host component when ANY meaningful prop changes — without
+     * this the action would silently keep running with stale values. */
+    key?: unknown;
+}
+export declare function textAnimate(node: HTMLElement, params: TextAnimateParams): {
+    update(p: TextAnimateParams): void;
+    destroy(): void;
+};