@codellyson/framely 0.1.0 → 0.1.1

package/src/ErrorBoundary.tsx

@@ -0,0 +1,136 @@
+import { Component, ReactNode, ErrorInfo } from 'react';
+
+/**
+ * Error boundary for catching render errors in compositions.
+ *
+ * In render mode, sets window.__FRAMELY_RENDER_ERROR so the CLI
+ * can detect and report the error.
+ *
+ * In dev/studio mode, displays the error with a stack trace.
+ */
+
+declare global {
+  interface Window {
+    __FRAMELY_RENDER_ERROR?: {
+      message: string;
+      stack?: string;
+      componentStack?: string | null;
+    };
+  }
+}
+
+export interface ErrorBoundaryProps {
+  children: ReactNode;
+  fallback?: ReactNode;
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+
+export interface ErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+    // In render mode, expose the error for CLI detection
+    if (typeof window !== 'undefined') {
+      window.__FRAMELY_RENDER_ERROR = {
+        message: error.message,
+        stack: error.stack,
+        componentStack: errorInfo?.componentStack,
+      };
+
+      // Dispatch custom event for render pipeline
+      window.dispatchEvent(
+        new CustomEvent('framely-render-error', {
+          detail: { error, errorInfo },
+        }),
+      );
+    }
+
+    if (this.props.onError) {
+      this.props.onError(error, errorInfo);
+    }
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      // Custom fallback UI
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+
+      // In render mode, show nothing (error is on window)
+      const params = new URLSearchParams(
+        typeof window !== 'undefined' ? window.location.search : '',
+      );
+      if (params.get('renderMode') === 'true') {
+        return null;
+      }
+
+      // Dev/studio mode - show error details
+      return (
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: '#1a1a1a',
+            color: '#ef4444',
+            fontFamily: 'system-ui, sans-serif',
+            padding: '24px',
+          }}
+        >
+          <div style={{ fontSize: '18px', fontWeight: 600, marginBottom: '12px' }}>
+            Composition Error
+          </div>
+          <div
+            style={{
+              fontSize: '14px',
+              color: '#fff',
+              marginBottom: '16px',
+              textAlign: 'center',
+              maxWidth: '600px',
+            }}
+          >
+            {this.state.error?.message || 'An unknown error occurred'}
+          </div>
+          {this.state.error?.stack && (
+            <pre
+              style={{
+                fontSize: '11px',
+                color: '#888',
+                background: '#111',
+                padding: '12px',
+                borderRadius: '6px',
+                maxWidth: '80%',
+                maxHeight: '200px',
+                overflow: 'auto',
+                whiteSpace: 'pre-wrap',
+                wordBreak: 'break-word',
+              }}
+            >
+              {this.state.error.stack}
+            </pre>
+          )}
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+export default ErrorBoundary;

package/src/Folder.tsx

@@ -0,0 +1,66 @@
+import { createContext, useContext, type ReactNode } from 'react';
+
+/**
+ * The folder path represented as an array of folder names from root to current.
+ */
+type FolderPath = string[];
+
+/**
+ * Props for the Folder component.
+ */
+interface FolderProps {
+  /** The folder name displayed in the sidebar */
+  name: string;
+  /** Child elements (Compositions or nested Folders) */
+  children: ReactNode;
+}
+
+/**
+ * Context for tracking folder hierarchy
+ */
+const FolderContext = createContext<FolderPath>([]);
+
+/**
+ * Hook to access the current folder path
+ *
+ * Returns:
+ *   string[] - Array of folder names from root to current
+ *
+ * Usage:
+ *   const path = useFolder();
+ *   console.log(path.join(' / ')); // "Effects / Transitions"
+ */
+export function useFolder(): FolderPath {
+  return useContext(FolderContext);
+}
+
+/**
+ * Folder organizes compositions in the Studio sidebar.
+ *
+ * Folders can be nested to create hierarchical organization.
+ * They don't affect rendering — they're purely for organization in the UI.
+ *
+ * Props:
+ *   name - The folder name displayed in the sidebar
+ *
+ * Usage:
+ *   <Folder name="Marketing">
+ *     <Composition id="promo-video" ... />
+ *     <Folder name="Social">
+ *       <Composition id="instagram-reel" ... />
+ *       <Composition id="tiktok-clip" ... />
+ *     </Folder>
+ *   </Folder>
+ */
+export function Folder({ name, children }: FolderProps): JSX.Element {
+  const parentPath: FolderPath = useContext(FolderContext);
+  const currentPath: FolderPath = [...parentPath, name];
+
+  return (
+    <FolderContext.Provider value={currentPath}>
+      {children}
+    </FolderContext.Provider>
+  );
+}
+
+export default Folder;

package/src/Freeze.tsx

@@ -0,0 +1,63 @@
+import { useMemo, type ReactNode } from 'react';
+import TimelineContext, { useTimeline } from './context';
+
+/**
+ * Props for the Freeze component.
+ */
+export interface FreezeProps {
+  /** The frame number children should see (required). */
+  frame: number;
+  /** Whether to freeze (default: true). If false, children see the normal frame. */
+  active?: boolean;
+  /** The content to render inside the freeze boundary. */
+  children: ReactNode;
+}
+
+/**
+ * Freeze pauses children at a specific frame.
+ *
+ * Children inside a Freeze component will always see the same frame value,
+ * regardless of the actual timeline position. This is useful for:
+ * - Pausing complex animations at a specific state
+ * - Creating "freeze frame" effects
+ * - Displaying a static frame from a video or animation
+ *
+ * Usage:
+ *   // Freeze at frame 15
+ *   <Freeze frame={15}>
+ *     <MyAnimation />
+ *   </Freeze>
+ *
+ *   // Conditional freeze
+ *   <Freeze frame={30} active={shouldFreeze}>
+ *     <MyAnimation />
+ *   </Freeze>
+ */
+export function Freeze({ frame, active = true, children }: FreezeProps): ReactNode {
+  const parent = useTimeline();
+
+  if (frame === undefined) {
+    throw new Error('Freeze requires a frame prop');
+  }
+
+  const contextValue = useMemo(
+    () => ({
+      ...parent,
+      frame: active ? frame : parent.frame,
+    }),
+    [parent, frame, active]
+  );
+
+  // If not active, just render children without context override
+  if (!active) {
+    return children;
+  }
+
+  return (
+    <TimelineContext.Provider value={contextValue}>
+      {children}
+    </TimelineContext.Provider>
+  );
+}
+
+export default Freeze;

package/src/IFrame.tsx

@@ -0,0 +1,100 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { delayRender, continueRender, cancelRender } from './delayRender';
+
+/**
+ * Props for the IFrame component.
+ *
+ * Extends standard iframe HTML attributes so all native iframe props
+ * (e.g., sandbox, allow, referrerPolicy) are supported.
+ */
+export interface IFrameProps
+  extends React.IframeHTMLAttributes<HTMLIFrameElement> {
+  /** URL to load in the iframe. */
+  src?: string;
+  /** Timeout in ms before failing the delay render. Defaults to 30000. */
+  delayRenderTimeout?: number;
+}
+
+/**
+ * IFrame component that delays rendering until the iframe content is loaded.
+ *
+ * Useful for embedding web content, charts, maps, or other external content
+ * that needs to be fully loaded before capturing the frame.
+ *
+ * Usage:
+ *   <IFrame
+ *     src="https://example.com/chart"
+ *     style={{ width: 800, height: 600 }}
+ *   />
+ */
+export function IFrame({
+  src,
+  delayRenderTimeout = 30000,
+  onLoad,
+  onError,
+  style,
+  className,
+  ...rest
+}: IFrameProps): React.ReactElement {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const handleRef = useRef<number | null>(null);
+  const [loaded, setLoaded] = useState<boolean>(false);
+
+  // Delay render until iframe is loaded
+  useEffect(() => {
+    handleRef.current = delayRender(`Loading iframe: ${src}`, {
+      timeoutInMilliseconds: delayRenderTimeout,
+    });
+
+    return () => {
+      if (handleRef.current !== null) {
+        continueRender(handleRef.current);
+        handleRef.current = null;
+      }
+    };
+  }, [src, delayRenderTimeout]);
+
+  // Handle iframe load
+  const handleLoad = (
+    event: React.SyntheticEvent<HTMLIFrameElement>,
+  ): void => {
+    setLoaded(true);
+    onLoad?.(event);
+
+    if (handleRef.current !== null) {
+      continueRender(handleRef.current);
+      handleRef.current = null;
+    }
+  };
+
+  // Handle iframe error
+  const handleError = (
+    event: React.SyntheticEvent<HTMLIFrameElement>,
+  ): void => {
+    const err = new Error(`Failed to load iframe: ${src}`);
+    onError?.(event);
+
+    if (handleRef.current !== null) {
+      cancelRender(err);
+      handleRef.current = null;
+    }
+  };
+
+  return (
+    <iframe
+      ref={iframeRef}
+      src={src}
+      onLoad={handleLoad}
+      onError={handleError}
+      style={{
+        border: 'none',
+        ...style,
+        opacity: loaded ? (style?.opacity ?? 1) : 0,
+      }}
+      className={className}
+      {...rest}
+    />
+  );
+}
+
+export default IFrame;

package/src/Img.tsx

@@ -0,0 +1,146 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { delayRender, continueRender, cancelRender } from './delayRender';
+
+/**
+ * Props for the Img component.
+ *
+ * Extends standard HTML img attributes with additional props
+ * for controlling image loading behavior during rendering.
+ */
+export interface ImgProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+  /** Image source URL. Use staticFile() for local assets. */
+  src: string;
+  /** Callback when the image fails to load after all retries. */
+  onError?: React.ReactEventHandler<HTMLImageElement>;
+  /** Number of retry attempts on load failure. Defaults to 2. */
+  maxRetries?: number;
+  /** Pause playback while loading in preview mode. Defaults to false. */
+  pauseWhenLoading?: boolean;
+  /** Custom timeout in milliseconds for delayRender. Defaults to 30000. */
+  delayRenderTimeout?: number;
+  /** Number of retries for delay render timeout. Defaults to 0. */
+  delayRenderRetries?: number;
+}
+
+/**
+ * Image component that delays rendering until the image is loaded.
+ *
+ * This ensures that images are always visible in rendered frames,
+ * preventing blank spaces or loading states in the final video.
+ *
+ * Usage:
+ *   import { Img, staticFile } from './lib';
+ *
+ *   <Img src={staticFile('images/hero.png')} alt="Hero" />
+ *   <Img src="https://example.com/image.jpg" style={{ width: 200 }} />
+ */
+export const Img = React.forwardRef<HTMLImageElement, ImgProps>(
+  (
+    {
+      src,
+      onError,
+      maxRetries = 2,
+      pauseWhenLoading = false,
+      delayRenderTimeout = 30000,
+      delayRenderRetries = 0,
+      ...rest
+    },
+    forwardedRef,
+  ) => {
+    const [loaded, setLoaded] = useState<boolean>(false);
+    const [error, setError] = useState<Error | null>(null);
+    const [retryCount, setRetryCount] = useState<number>(0);
+    const handleRef = useRef<number | null>(null);
+    const imgRef = useRef<HTMLImageElement | null>(null);
+
+    // Merge forwarded ref and internal ref
+    const setRefs = React.useCallback(
+      (node: HTMLImageElement | null) => {
+        imgRef.current = node;
+        if (typeof forwardedRef === 'function') {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          (forwardedRef as React.MutableRefObject<HTMLImageElement | null>).current = node;
+        }
+      },
+      [forwardedRef],
+    );
+
+    // Initialize delay render on mount
+    useEffect(() => {
+      handleRef.current = delayRender(`Loading image: ${src}`, {
+        timeoutInMilliseconds: delayRenderTimeout,
+        retries: delayRenderRetries,
+      });
+
+      return () => {
+        // Cleanup if component unmounts before load
+        if (handleRef.current !== null) {
+          continueRender(handleRef.current);
+          handleRef.current = null;
+        }
+      };
+    }, [src, delayRenderTimeout, delayRenderRetries]);
+
+    // Handle image load
+    const handleLoad = (): void => {
+      setLoaded(true);
+      setError(null);
+
+      if (handleRef.current !== null) {
+        continueRender(handleRef.current);
+        handleRef.current = null;
+      }
+    };
+
+    // Handle image error
+    const handleError = (event: React.SyntheticEvent<HTMLImageElement, Event>): void => {
+      if (retryCount < maxRetries) {
+        // Retry by forcing a new request
+        setRetryCount((c) => c + 1);
+        if (imgRef.current) {
+          // Add cache-busting query param
+          const separator = src.includes('?') ? '&' : '?';
+          imgRef.current.src = `${src}${separator}_retry=${retryCount + 1}`;
+        }
+        return;
+      }
+
+      const err = new Error(`Failed to load image: ${src}`);
+      setError(err);
+      onError?.(event);
+
+      // Cancel the render - image is required
+      if (handleRef.current !== null) {
+        cancelRender(err);
+        handleRef.current = null;
+      }
+    };
+
+    // Check if image is already cached (loads synchronously)
+    useEffect(() => {
+      if (imgRef.current?.complete && imgRef.current?.naturalWidth > 0) {
+        handleLoad();
+      }
+    }, [src]);
+
+    return (
+      <img
+        ref={setRefs}
+        src={src}
+        onLoad={handleLoad}
+        onError={handleError}
+        {...rest}
+        // Hide image until loaded to prevent flash of broken image
+        style={{
+          ...rest.style,
+          opacity: loaded ? (rest.style?.opacity ?? 1) : 0,
+        }}
+      />
+    );
+  },
+);
+
+Img.displayName = 'Img';
+
+export default Img;

package/src/Loop.tsx

@@ -0,0 +1,139 @@
+import React, { useMemo, createContext, useContext, CSSProperties, ReactNode } from 'react';
+import TimelineContext, { useTimeline } from './context';
+
+/**
+ * Metadata exposed by the Loop component via LoopContext.
+ */
+export interface LoopContextValue {
+  /** Current iteration index (0-based) */
+  iteration: number;
+  /** Duration of each loop iteration in frames */
+  durationInFrames: number;
+}
+
+/**
+ * Props for the Loop component.
+ */
+export interface LoopProps {
+  /** Number of frames per iteration (required, must be positive) */
+  durationInFrames: number;
+  /** Number of repetitions (default: Infinity) */
+  times?: number;
+  /** Layout mode: 'absolute-fill' applies absolute positioning, 'none' applies no layout */
+  layout?: 'absolute-fill' | 'none';
+  /** Additional CSS styles applied to the container div */
+  style?: CSSProperties;
+  /** Optional label for debugging */
+  name?: string;
+  /** Child elements rendered inside the loop */
+  children: ReactNode;
+}
+
+/**
+ * Context for accessing loop metadata
+ */
+const LoopContext = createContext<LoopContextValue | null>(null);
+
+/**
+ * Hook to access loop metadata when inside a Loop component.
+ *
+ * Returns:
+ *   { iteration, durationInFrames } - Current iteration (0-indexed) and loop duration
+ *   null - If not inside a Loop
+ *
+ * Usage:
+ *   const loop = Loop.useLoop();
+ *   if (loop) {
+ *     console.log(`Iteration ${loop.iteration + 1}`);
+ *   }
+ */
+function useLoop(): LoopContextValue | null {
+  return useContext(LoopContext);
+}
+
+/**
+ * Loop repeats its children for a specified number of iterations.
+ *
+ * The frame counter resets at the start of each iteration, so children
+ * always see frames 0 to durationInFrames-1.
+ *
+ * Props:
+ *   durationInFrames - Frames per iteration (required)
+ *   times            - Number of repetitions (default: Infinity)
+ *   layout           - 'absolute-fill' (default) or 'none'
+ *   style            - Additional CSS styles
+ *   name             - Optional label for debugging
+ *
+ * Usage:
+ *   <Loop durationInFrames={30} times={3}>
+ *     <PulseAnimation />
+ *   </Loop>
+ */
+export function Loop({
+  durationInFrames,
+  times = Infinity,
+  layout = 'absolute-fill',
+  style,
+  name,
+  children,
+}: LoopProps): React.ReactElement | null {
+  const parent = useTimeline();
+
+  if (durationInFrames === undefined || durationInFrames <= 0) {
+    throw new Error('Loop requires a positive durationInFrames');
+  }
+
+  // Calculate which iteration we're on and the local frame within that iteration
+  const iteration: number = Math.floor(parent.frame / durationInFrames);
+  const localFrame: number = parent.frame % durationInFrames;
+
+  const contextValue = useMemo(
+    () => ({
+      ...parent,
+      frame: localFrame,
+      durationInFrames,
+    }),
+    [parent, localFrame, durationInFrames]
+  );
+
+  const loopValue: LoopContextValue = useMemo(
+    () => ({
+      iteration,
+      durationInFrames,
+    }),
+    [iteration, durationInFrames]
+  );
+
+  const containerStyle: CSSProperties | undefined =
+    layout === 'absolute-fill'
+      ? {
+          position: 'absolute' as const,
+          top: 0,
+          left: 0,
+          right: 0,
+          bottom: 0,
+          ...style,
+        }
+      : style;
+
+  // Check if we've exceeded the number of loops
+  if (times !== Infinity && iteration >= times) {
+    return null;
+  }
+
+  return (
+    <LoopContext.Provider value={loopValue}>
+      <TimelineContext.Provider value={contextValue}>
+        <div style={containerStyle} data-loop-name={name} data-loop-iteration={iteration}>
+          {children}
+        </div>
+      </TimelineContext.Provider>
+    </LoopContext.Provider>
+  );
+}
+
+// Attach the hook to the Loop component for convenient access
+Loop.useLoop = useLoop;
+
+export { useLoop };
+export default Loop;