@codellyson/framely 0.1.0

package/dist/delayRender.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Delay Render System
+ *
+ * This module manages asynchronous operations that must complete before
+ * a frame can be captured during rendering. It's essential for:
+ * - Loading images, videos, fonts
+ * - Fetching data from APIs
+ * - Any async operation that affects the visual output
+ *
+ * The renderer (Playwright) checks window.__FRAMELY_DELAY_RENDER before
+ * capturing each frame. If any handles are pending, it waits.
+ */
+/**
+ * Options for delayRender().
+ */
+export interface DelayRenderOptions {
+    /** Timeout in milliseconds before throwing a timeout error. Defaults to 30000. */
+    timeoutInMilliseconds?: number;
+    /** Number of retries on timeout. Defaults to 0. */
+    retries?: number;
+}
+/**
+ * Internal data tracked for each delay render handle.
+ */
+export interface DelayRenderHandle {
+    handle: number;
+    label: string;
+    createdAt: number;
+    timeoutInMilliseconds: number;
+    retries: number;
+    retriesRemaining: number;
+    timeoutId: ReturnType<typeof setTimeout> | null;
+}
+/**
+ * Information about a pending delay render, returned by getPendingDelayRenders().
+ */
+export interface PendingDelayRender {
+    handle: number;
+    label: string;
+    /** Age in milliseconds since the handle was created. */
+    age: number;
+}
+declare global {
+    interface Window {
+        __FRAMELY_DELAY_RENDER: {
+            pending: Map<number, DelayRenderHandle>;
+            isPending: () => boolean;
+            getPendingCount: () => number;
+            getLabels: () => string[];
+        };
+        __FRAMELY_RENDER_ERROR?: {
+            message: string;
+            stack?: string;
+            componentStack?: string | null;
+        };
+    }
+}
+/**
+ * Signals that the current frame should not be captured until
+ * continueRender() is called with the returned handle.
+ *
+ * Use this when loading assets or fetching data that must be
+ * displayed in the frame.
+ *
+ * @param {string | DelayRenderOptions} [label] - Optional label for debugging (shown in timeout errors), or an options object
+ * @param {DelayRenderOptions} [options]
+ * @param {number} [options.timeoutInMilliseconds=30000] - Timeout before throwing
+ * @param {number} [options.retries=0] - Number of retries on timeout
+ * @returns {number} Handle to pass to continueRender()
+ *
+ * Usage:
+ *   const handle = delayRender('Loading profile image');
+ *   fetch('/api/image')
+ *     .then(data => {
+ *       setImage(data);
+ *       continueRender(handle);
+ *     })
+ *     .catch(err => cancelRender(err));
+ */
+export declare function delayRender(label?: string | DelayRenderOptions, options?: DelayRenderOptions): number;
+/**
+ * Signals that the async operation for the given handle has completed.
+ * The frame can now be captured (if no other handles are pending).
+ *
+ * @param {number} handle - The handle returned by delayRender()
+ *
+ * Usage:
+ *   const handle = delayRender('Loading data');
+ *   fetchData().then(() => continueRender(handle));
+ */
+export declare function continueRender(handle: number): void;
+/**
+ * Cancels the render with an error. Use this when an unrecoverable
+ * error occurs (e.g., asset failed to load, API error).
+ *
+ * @param {Error|string} error - The error that caused the cancellation
+ *
+ * Usage:
+ *   fetch('/api/data')
+ *     .catch(err => cancelRender(err));
+ */
+export declare function cancelRender(error: Error | string): never;
+/**
+ * Check if there are any pending delay render handles.
+ *
+ * @returns {boolean}
+ */
+export declare function isDelayRenderPending(): boolean;
+/**
+ * Get information about all pending delay render handles.
+ * Useful for debugging.
+ *
+ * @returns {Array<PendingDelayRender>}
+ */
+export declare function getPendingDelayRenders(): PendingDelayRender[];
+/**
+ * Clear all pending delay render handles.
+ * Use with caution - mainly for testing/cleanup.
+ */
+export declare function clearAllDelayRenders(): void;
+declare const _default: {
+    delayRender: typeof delayRender;
+    continueRender: typeof continueRender;
+    cancelRender: typeof cancelRender;
+    isDelayRenderPending: typeof isDelayRenderPending;
+    getPendingDelayRenders: typeof getPendingDelayRenders;
+    clearAllDelayRenders: typeof clearAllDelayRenders;
+};
+export default _default;
+//# sourceMappingURL=delayRender.d.ts.map

package/dist/delayRender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delayRender.d.ts","sourceRoot":"","sources":["../src/delayRender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,sBAAsB,EAAE;YACtB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;YACxC,SAAS,EAAE,MAAM,OAAO,CAAC;YACzB,eAAe,EAAE,MAAM,MAAM,CAAC;YAC9B,SAAS,EAAE,MAAM,MAAM,EAAE,CAAC;SAC3B,CAAC;QACF,sBAAsB,CAAC,EAAE;YACvB,OAAO,EAAE,MAAM,CAAC;YAChB,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;SAChC,CAAC;KACH;CACF;AAyBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CACzB,KAAK,CAAC,EAAE,MAAM,GAAG,kBAAkB,EACnC,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAuDR;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAyBzD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,kBAAkB,EAAE,CAO7D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAO3C;;;;;;;;;AAED,wBAOE"}

package/dist/delayRender.js

@@ -0,0 +1,197 @@
+/**
+ * Delay Render System
+ *
+ * This module manages asynchronous operations that must complete before
+ * a frame can be captured during rendering. It's essential for:
+ * - Loading images, videos, fonts
+ * - Fetching data from APIs
+ * - Any async operation that affects the visual output
+ *
+ * The renderer (Playwright) checks window.__FRAMELY_DELAY_RENDER before
+ * capturing each frame. If any handles are pending, it waits.
+ */
+// Global state for tracking delay render handles
+let handleCounter = 0;
+const pendingHandles = new Map();
+const DEFAULT_TIMEOUT = 30000; // 30 seconds
+/**
+ * Initialize the global delay render state.
+ * Called automatically when the module loads.
+ */
+function initDelayRenderState() {
+    if (typeof window !== 'undefined') {
+        window.__FRAMELY_DELAY_RENDER = {
+            pending: pendingHandles,
+            isPending: () => pendingHandles.size > 0,
+            getPendingCount: () => pendingHandles.size,
+            getLabels: () => Array.from(pendingHandles.values()).map(h => h.label),
+        };
+    }
+}
+// Initialize on module load
+initDelayRenderState();
+/**
+ * Signals that the current frame should not be captured until
+ * continueRender() is called with the returned handle.
+ *
+ * Use this when loading assets or fetching data that must be
+ * displayed in the frame.
+ *
+ * @param {string | DelayRenderOptions} [label] - Optional label for debugging (shown in timeout errors), or an options object
+ * @param {DelayRenderOptions} [options]
+ * @param {number} [options.timeoutInMilliseconds=30000] - Timeout before throwing
+ * @param {number} [options.retries=0] - Number of retries on timeout
+ * @returns {number} Handle to pass to continueRender()
+ *
+ * Usage:
+ *   const handle = delayRender('Loading profile image');
+ *   fetch('/api/image')
+ *     .then(data => {
+ *       setImage(data);
+ *       continueRender(handle);
+ *     })
+ *     .catch(err => cancelRender(err));
+ */
+export function delayRender(label, options = {}) {
+    const { timeoutInMilliseconds = DEFAULT_TIMEOUT, retries = 0, } = typeof label === 'object' ? label : options;
+    const actualLabel = typeof label === 'string' ? label : 'Unnamed delay';
+    const handle = ++handleCounter;
+    const handleData = {
+        handle,
+        label: actualLabel,
+        createdAt: Date.now(),
+        timeoutInMilliseconds,
+        retries,
+        retriesRemaining: retries,
+        timeoutId: null,
+    };
+    // Set up timeout
+    if (typeof window !== 'undefined' && timeoutInMilliseconds > 0) {
+        handleData.timeoutId = setTimeout(() => {
+            if (pendingHandles.has(handle)) {
+                const error = new Error(`delayRender() timed out after ${timeoutInMilliseconds}ms.\n` +
+                    `Label: "${actualLabel}"\n` +
+                    `Handle: ${handle}\n\n` +
+                    `This usually means:\n` +
+                    `- An asset failed to load (image, video, font)\n` +
+                    `- A fetch request never completed\n` +
+                    `- continueRender() was never called\n\n` +
+                    `Make sure to call continueRender(handle) when your async operation completes.`);
+                error.name = 'DelayRenderTimeoutError';
+                // Check if we should retry
+                if (handleData.retriesRemaining > 0) {
+                    handleData.retriesRemaining--;
+                    console.warn(`delayRender retry (${retries - handleData.retriesRemaining}/${retries}): ${actualLabel}`);
+                    // Reset timeout
+                    handleData.timeoutId = setTimeout(() => {
+                        if (pendingHandles.has(handle)) {
+                            cancelRender(error);
+                        }
+                    }, timeoutInMilliseconds);
+                }
+                else {
+                    cancelRender(error);
+                }
+            }
+        }, timeoutInMilliseconds);
+    }
+    pendingHandles.set(handle, handleData);
+    return handle;
+}
+/**
+ * Signals that the async operation for the given handle has completed.
+ * The frame can now be captured (if no other handles are pending).
+ *
+ * @param {number} handle - The handle returned by delayRender()
+ *
+ * Usage:
+ *   const handle = delayRender('Loading data');
+ *   fetchData().then(() => continueRender(handle));
+ */
+export function continueRender(handle) {
+    const handleData = pendingHandles.get(handle);
+    if (!handleData) {
+        console.warn(`continueRender() called with unknown handle: ${handle}. ` +
+            `It may have already been continued or timed out.`);
+        return;
+    }
+    // Clear timeout
+    if (handleData.timeoutId) {
+        clearTimeout(handleData.timeoutId);
+    }
+    pendingHandles.delete(handle);
+}
+/**
+ * Cancels the render with an error. Use this when an unrecoverable
+ * error occurs (e.g., asset failed to load, API error).
+ *
+ * @param {Error|string} error - The error that caused the cancellation
+ *
+ * Usage:
+ *   fetch('/api/data')
+ *     .catch(err => cancelRender(err));
+ */
+export function cancelRender(error) {
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+    // Clear all pending handles
+    for (const [handle, data] of pendingHandles) {
+        if (data.timeoutId) {
+            clearTimeout(data.timeoutId);
+        }
+    }
+    pendingHandles.clear();
+    // Expose the error globally for the renderer to catch
+    if (typeof window !== 'undefined') {
+        window.__FRAMELY_RENDER_ERROR = errorObj;
+        // Also dispatch an event for any listeners
+        window.dispatchEvent(new CustomEvent('framely-render-error', {
+            detail: { error: errorObj }
+        }));
+    }
+    // In development, also throw to show in console
+    console.error('Render cancelled:', errorObj);
+    throw errorObj;
+}
+/**
+ * Check if there are any pending delay render handles.
+ *
+ * @returns {boolean}
+ */
+export function isDelayRenderPending() {
+    return pendingHandles.size > 0;
+}
+/**
+ * Get information about all pending delay render handles.
+ * Useful for debugging.
+ *
+ * @returns {Array<PendingDelayRender>}
+ */
+export function getPendingDelayRenders() {
+    const now = Date.now();
+    return Array.from(pendingHandles.values()).map(data => ({
+        handle: data.handle,
+        label: data.label,
+        age: now - data.createdAt,
+    }));
+}
+/**
+ * Clear all pending delay render handles.
+ * Use with caution - mainly for testing/cleanup.
+ */
+export function clearAllDelayRenders() {
+    for (const [handle, data] of pendingHandles) {
+        if (data.timeoutId) {
+            clearTimeout(data.timeoutId);
+        }
+    }
+    pendingHandles.clear();
+}
+export default {
+    delayRender,
+    continueRender,
+    cancelRender,
+    isDelayRenderPending,
+    getPendingDelayRenders,
+    clearAllDelayRenders,
+};
+//# sourceMappingURL=delayRender.js.map

package/dist/delayRender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delayRender.js","sourceRoot":"","sources":["../src/delayRender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAmDH,iDAAiD;AACjD,IAAI,aAAa,GAAW,CAAC,CAAC;AAC9B,MAAM,cAAc,GAAmC,IAAI,GAAG,EAAE,CAAC;AACjE,MAAM,eAAe,GAAW,KAAK,CAAC,CAAC,aAAa;AAEpD;;;GAGG;AACH,SAAS,oBAAoB;IAC3B,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,CAAC,sBAAsB,GAAG;YAC9B,OAAO,EAAE,cAAc;YACvB,SAAS,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC;YACxC,eAAe,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,IAAI;YAC1C,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;SACvE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,4BAA4B;AAC5B,oBAAoB,EAAE,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,WAAW,CACzB,KAAmC,EACnC,UAA8B,EAAE;IAEhC,MAAM,EACJ,qBAAqB,GAAG,eAAe,EACvC,OAAO,GAAG,CAAC,GACZ,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;IAEhD,MAAM,WAAW,GAAW,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC;IAChF,MAAM,MAAM,GAAW,EAAE,aAAa,CAAC;IAEvC,MAAM,UAAU,GAAsB;QACpC,MAAM;QACN,KAAK,EAAE,WAAW;QAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,qBAAqB;QACrB,OAAO;QACP,gBAAgB,EAAE,OAAO;QACzB,SAAS,EAAE,IAAI;KAChB,CAAC;IAEF,iBAAiB;IACjB,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,qBAAqB,GAAG,CAAC,EAAE,CAAC;QAC/D,UAAU,CAAC,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;YACrC,IAAI,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC/B,MAAM,KAAK,GAAG,IAAI,KAAK,CACrB,iCAAiC,qBAAqB,OAAO;oBAC7D,WAAW,WAAW,KAAK;oBAC3B,WAAW,MAAM,MAAM;oBACvB,uBAAuB;oBACvB,kDAAkD;oBAClD,qCAAqC;oBACrC,yCAAyC;oBACzC,+EAA+E,CAChF,CAAC;gBACF,KAAK,CAAC,IAAI,GAAG,yBAAyB,CAAC;gBAEvC,2BAA2B;gBAC3B,IAAI,UAAU,CAAC,gBAAgB,GAAG,CAAC,EAAE,CAAC;oBACpC,UAAU,CAAC,gBAAgB,EAAE,CAAC;oBAC9B,OAAO,CAAC,IAAI,CAAC,sBAAsB,OAAO,GAAG,UAAU,CAAC,gBAAgB,IAAI,OAAO,MAAM,WAAW,EAAE,CAAC,CAAC;oBACxG,gBAAgB;oBAChB,UAAU,CAAC,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;wBACrC,IAAI,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;4BAC/B,YAAY,CAAC,KAAK,CAAC,CAAC;wBACtB,CAAC;oBACH,CAAC,EAAE,qBAAqB,CAAC,CAAC;gBAC5B,CAAC;qBAAM,CAAC;oBACN,YAAY,CAAC,KAAK,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC,EAAE,qBAAqB,CAAC,CAAC;IAC5B,CAAC;IAED,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAEvC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,MAAM,UAAU,GAAG,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAE9C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CACV,gDAAgD,MAAM,IAAI;YAC1D,kDAAkD,CACnD,CAAC;QACF,OAAO;IACT,CAAC;IAED,gBAAgB;IAChB,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;QACzB,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IAED,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,KAAqB;IAChD,MAAM,QAAQ,GAAU,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAElF,4BAA4B;IAC5B,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,cAAc,EAAE,CAAC;QAC5C,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,cAAc,CAAC,KAAK,EAAE,CAAC;IAEvB,sDAAsD;IACtD,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,CAAC,sBAAsB,GAAG,QAAQ,CAAC;QAEzC,2CAA2C;QAC3C,MAAM,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,sBAAsB,EAAE;YAC3D,MAAM,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE;SAC5B,CAAC,CAAC,CAAC;IACN,CAAC;IAED,gDAAgD;IAChD,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC;IAE7C,MAAM,QAAQ,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,cAAc,CAAC,IAAI,GAAG,CAAC,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,OAAO,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACtD,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,cAAc,EAAE,CAAC;QAC5C,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,cAAc,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC;AAED,eAAe;IACb,WAAW;IACX,cAAc;IACd,YAAY;IACZ,oBAAoB;IACpB,sBAAsB;IACtB,oBAAoB;CACrB,CAAC"}

package/dist/getInputProps.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Input Props System
+ *
+ * Manages props passed to compositions from external sources:
+ * - CLI flags (--props '{"key": "value"}')
+ * - API requests (render endpoint body)
+ * - URL query parameters (?props=...)
+ *
+ * This allows dynamic, data-driven video generation.
+ */
+/** A record of string keys to unknown values, representing input props. */
+export type InputProps = Record<string, unknown>;
+/** Possible sources from which input props can originate. */
+export type InputPropsSource = 'url' | 'renderer' | 'manual' | null;
+/** Augment the global Window interface with Framely-specific properties. */
+declare global {
+    interface Window {
+        __FRAMELY_INPUT_PROPS?: InputProps;
+        __FRAMELY_SET_INPUT_PROPS?: typeof setInputProps;
+    }
+}
+/**
+ * Get the input props passed to the current render/preview.
+ *
+ * In the CLI, props are passed via --props flag:
+ *   framely render my-video --props '{"name": "John"}'
+ *
+ * In the API, props are passed in the request body:
+ *   POST /api/render { compositionId: "...", props: { name: "John" } }
+ *
+ * @returns {object} The input props object
+ *
+ * Usage:
+ *   function MyVideo() {
+ *     const { name, color } = getInputProps();
+ *     return <div style={{ color }}>{name}</div>;
+ *   }
+ */
+export declare function getInputProps<T extends InputProps = InputProps>(): T;
+/**
+ * Set input props programmatically.
+ *
+ * This is primarily used by the renderer to inject props before
+ * the composition is rendered.
+ *
+ * @param {object} props - Props to set
+ * @param {string} [source] - Source identifier (for debugging)
+ */
+export declare function setInputProps(props: InputProps, source?: InputPropsSource): void;
+/**
+ * Merge additional props into the existing input props.
+ *
+ * @param {object} props - Props to merge
+ */
+export declare function mergeInputProps(props: InputProps): void;
+/**
+ * Get a specific input prop by key.
+ *
+ * @param {string} key - Prop key
+ * @param {*} [defaultValue] - Default value if prop doesn't exist
+ * @returns {*} The prop value or default
+ *
+ * Usage:
+ *   const name = getInputProp('name', 'Anonymous');
+ */
+export declare function getInputProp<T = unknown>(key: string, defaultValue?: T): T;
+/**
+ * Check if input props were provided.
+ *
+ * @returns {boolean}
+ */
+export declare function hasInputProps(): boolean;
+/**
+ * Get the source of the current input props.
+ *
+ * @returns {string|null} 'url', 'renderer', 'manual', or null
+ */
+export declare function getInputPropsSource(): InputPropsSource;
+/**
+ * Clear all input props (mainly for testing).
+ */
+export declare function clearInputProps(): void;
+/**
+ * Parse props from a JSON string or file path.
+ *
+ * @param {string} input - JSON string or path to JSON file
+ * @returns {object} Parsed props
+ */
+export declare function parsePropsInput(input: string): InputProps;
+/**
+ * Serialize props to a URL-safe string.
+ *
+ * @param {object} props - Props to serialize
+ * @returns {string} URL-encoded JSON string
+ */
+export declare function serializeProps(props: InputProps): string;
+/**
+ * Create a URL with props embedded as query parameter.
+ *
+ * @param {string} baseUrl - Base URL
+ * @param {object} props - Props to embed
+ * @returns {string} URL with props
+ */
+export declare function createUrlWithProps(baseUrl: string, props: InputProps): string;
+declare const _default: {
+    getInputProps: typeof getInputProps;
+    setInputProps: typeof setInputProps;
+    mergeInputProps: typeof mergeInputProps;
+    getInputProp: typeof getInputProp;
+    hasInputProps: typeof hasInputProps;
+    getInputPropsSource: typeof getInputPropsSource;
+    clearInputProps: typeof clearInputProps;
+    parsePropsInput: typeof parsePropsInput;
+    serializeProps: typeof serializeProps;
+    createUrlWithProps: typeof createUrlWithProps;
+};
+export default _default;
+//# sourceMappingURL=getInputProps.d.ts.map

package/dist/getInputProps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getInputProps.d.ts","sourceRoot":"","sources":["../src/getInputProps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,UAAU,GAAG,QAAQ,GAAG,IAAI,CAAC;AAEpE,4EAA4E;AAC5E,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,qBAAqB,CAAC,EAAE,UAAU,CAAC;QACnC,yBAAyB,CAAC,EAAE,OAAO,aAAa,CAAC;KAClD;CACF;AAuCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,KAAK,CAAC,CAEpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,MAAM,GAAE,gBAA2B,GAClC,IAAI,CAQN;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAMvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAEtD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAOtC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAYzD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAI7E;;;;;;;;;;;;;AAED,wBAWE"}

package/dist/getInputProps.js

@@ -0,0 +1,181 @@
+/**
+ * Input Props System
+ *
+ * Manages props passed to compositions from external sources:
+ * - CLI flags (--props '{"key": "value"}')
+ * - API requests (render endpoint body)
+ * - URL query parameters (?props=...)
+ *
+ * This allows dynamic, data-driven video generation.
+ */
+// Global storage for input props
+let inputProps = {};
+let inputPropsSource = null;
+/**
+ * Initialize input props from various sources.
+ * Called automatically on module load.
+ */
+function initInputProps() {
+    if (typeof window === 'undefined')
+        return;
+    // Check URL query params first
+    const urlParams = new URLSearchParams(window.location.search);
+    const propsParam = urlParams.get('props');
+    if (propsParam) {
+        try {
+            inputProps = JSON.parse(decodeURIComponent(propsParam));
+            inputPropsSource = 'url';
+        }
+        catch (err) {
+            console.warn('Failed to parse props from URL:', err);
+        }
+    }
+    // Check for props injected by renderer
+    if (window.__FRAMELY_INPUT_PROPS) {
+        inputProps = { ...inputProps, ...window.__FRAMELY_INPUT_PROPS };
+        inputPropsSource = 'renderer';
+    }
+    // Expose setter for external use
+    window.__FRAMELY_SET_INPUT_PROPS = setInputProps;
+}
+// Initialize on module load
+initInputProps();
+/**
+ * Get the input props passed to the current render/preview.
+ *
+ * In the CLI, props are passed via --props flag:
+ *   framely render my-video --props '{"name": "John"}'
+ *
+ * In the API, props are passed in the request body:
+ *   POST /api/render { compositionId: "...", props: { name: "John" } }
+ *
+ * @returns {object} The input props object
+ *
+ * Usage:
+ *   function MyVideo() {
+ *     const { name, color } = getInputProps();
+ *     return <div style={{ color }}>{name}</div>;
+ *   }
+ */
+export function getInputProps() {
+    return { ...inputProps };
+}
+/**
+ * Set input props programmatically.
+ *
+ * This is primarily used by the renderer to inject props before
+ * the composition is rendered.
+ *
+ * @param {object} props - Props to set
+ * @param {string} [source] - Source identifier (for debugging)
+ */
+export function setInputProps(props, source = 'manual') {
+    inputProps = { ...props };
+    inputPropsSource = source;
+    // Update global reference
+    if (typeof window !== 'undefined') {
+        window.__FRAMELY_INPUT_PROPS = inputProps;
+    }
+}
+/**
+ * Merge additional props into the existing input props.
+ *
+ * @param {object} props - Props to merge
+ */
+export function mergeInputProps(props) {
+    inputProps = { ...inputProps, ...props };
+    if (typeof window !== 'undefined') {
+        window.__FRAMELY_INPUT_PROPS = inputProps;
+    }
+}
+/**
+ * Get a specific input prop by key.
+ *
+ * @param {string} key - Prop key
+ * @param {*} [defaultValue] - Default value if prop doesn't exist
+ * @returns {*} The prop value or default
+ *
+ * Usage:
+ *   const name = getInputProp('name', 'Anonymous');
+ */
+export function getInputProp(key, defaultValue) {
+    return (key in inputProps ? inputProps[key] : defaultValue);
+}
+/**
+ * Check if input props were provided.
+ *
+ * @returns {boolean}
+ */
+export function hasInputProps() {
+    return Object.keys(inputProps).length > 0;
+}
+/**
+ * Get the source of the current input props.
+ *
+ * @returns {string|null} 'url', 'renderer', 'manual', or null
+ */
+export function getInputPropsSource() {
+    return inputPropsSource;
+}
+/**
+ * Clear all input props (mainly for testing).
+ */
+export function clearInputProps() {
+    inputProps = {};
+    inputPropsSource = null;
+    if (typeof window !== 'undefined') {
+        delete window.__FRAMELY_INPUT_PROPS;
+    }
+}
+/**
+ * Parse props from a JSON string or file path.
+ *
+ * @param {string} input - JSON string or path to JSON file
+ * @returns {object} Parsed props
+ */
+export function parsePropsInput(input) {
+    if (!input)
+        return {};
+    // Try parsing as JSON directly
+    try {
+        return JSON.parse(input);
+    }
+    catch {
+        // Not valid JSON, might be a file path (handled by CLI)
+        throw new Error(`Invalid props input. Expected JSON string, got: ${input.slice(0, 50)}...`);
+    }
+}
+/**
+ * Serialize props to a URL-safe string.
+ *
+ * @param {object} props - Props to serialize
+ * @returns {string} URL-encoded JSON string
+ */
+export function serializeProps(props) {
+    return encodeURIComponent(JSON.stringify(props));
+}
+/**
+ * Create a URL with props embedded as query parameter.
+ *
+ * @param {string} baseUrl - Base URL
+ * @param {object} props - Props to embed
+ * @returns {string} URL with props
+ */
+export function createUrlWithProps(baseUrl, props) {
+    const url = new URL(baseUrl);
+    url.searchParams.set('props', serializeProps(props));
+    return url.toString();
+}
+export default {
+    getInputProps,
+    setInputProps,
+    mergeInputProps,
+    getInputProp,
+    hasInputProps,
+    getInputPropsSource,
+    clearInputProps,
+    parsePropsInput,
+    serializeProps,
+    createUrlWithProps,
+};
+//# sourceMappingURL=getInputProps.js.map

package/dist/getInputProps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getInputProps.js","sourceRoot":"","sources":["../src/getInputProps.ts"],"names":[],"mappings":"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"}