forgeframe 0.0.1

package/dist/communication/bridge.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @packageDocumentation
+ * Function bridge for cross-domain function calls.
+ *
+ * @remarks
+ * This module enables passing functions as props across domain boundaries
+ * by converting them to references that can be called via postMessage.
+ */
+import type { FunctionRef } from '../types';
+import type { Messenger } from './messenger';
+/**
+ * Generic function type for cross-domain callable functions.
+ * @internal
+ */
+type CallableFunction = (...args: unknown[]) => unknown | Promise<unknown>;
+/**
+ * Handles serialization and deserialization of functions for cross-domain calls.
+ *
+ * @remarks
+ * When you pass a function as a prop, it gets converted to a reference
+ * that can be called across domains via postMessage. The bridge maintains
+ * mappings of local and remote functions.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new FunctionBridge(messenger);
+ *
+ * // Serialize a local function
+ * const ref = bridge.serialize(() => console.log('Hello'));
+ *
+ * // Deserialize a remote reference
+ * const remoteFn = bridge.deserialize(ref, targetWin, targetDomain);
+ * await remoteFn(); // Calls the original function cross-domain
+ * ```
+ *
+ * @public
+ */
+export declare class FunctionBridge {
+    private messenger;
+    /** @internal */
+    private localFunctions;
+    /** @internal */
+    private remoteFunctions;
+    /**
+     * Tracks function IDs from the current serialization batch.
+     * Used for cleanup of stale references when props are updated.
+     * @internal
+     */
+    private currentBatchIds;
+    /**
+     * Creates a new FunctionBridge instance.
+     *
+     * @param messenger - The messenger to use for cross-domain calls
+     */
+    constructor(messenger: Messenger);
+    /**
+     * Serializes a local function to a transferable reference.
+     *
+     * @param fn - The function to serialize
+     * @param name - Optional name for debugging
+     * @returns A function reference that can be sent across domains
+     */
+    serialize(fn: CallableFunction, name?: string): FunctionRef;
+    /**
+     * Deserializes a function reference to a callable wrapper.
+     *
+     * @remarks
+     * The returned function, when called, will invoke the original function
+     * in the remote window via postMessage and return the result.
+     *
+     * @param ref - The function reference to deserialize
+     * @param targetWin - The window containing the original function
+     * @param targetDomain - The origin of the target window
+     * @returns A callable wrapper function
+     */
+    deserialize(ref: FunctionRef, targetWin: Window, targetDomain: string): CallableFunction;
+    /**
+     * Type guard to check if a value is a function reference.
+     *
+     * @param value - The value to check
+     * @returns True if the value is a FunctionRef
+     */
+    static isFunctionRef(value: unknown): value is FunctionRef;
+    /**
+     * Sets up the handler for incoming function call messages.
+     * @internal
+     */
+    private setupCallHandler;
+    /**
+     * Removes a local function reference.
+     *
+     * @param id - The function reference ID to remove
+     */
+    removeLocal(id: string): void;
+    /**
+     * Starts a new serialization batch.
+     *
+     * @remarks
+     * Call this before serializing a new set of props. After serialization,
+     * call {@link finishBatch} to clean up functions from previous batches.
+     *
+     * @example
+     * ```typescript
+     * bridge.startBatch();
+     * const serialized = serializeFunctions(props, bridge);
+     * bridge.finishBatch();
+     * ```
+     */
+    startBatch(): void;
+    /**
+     * Finishes the current batch and removes functions not in this batch.
+     *
+     * @remarks
+     * This cleans up function references from previous prop updates that
+     * are no longer needed, preventing memory leaks.
+     *
+     * @param keepPrevious - If true, keeps previous batch functions (default: false)
+     */
+    finishBatch(keepPrevious?: boolean): void;
+    /**
+     * Clears all remote function references.
+     *
+     * @remarks
+     * Call this when the remote window is no longer accessible
+     * (e.g., closed or navigated away).
+     */
+    clearRemote(): void;
+    /**
+     * Returns the current number of registered local functions.
+     * Useful for debugging and monitoring.
+     */
+    get localFunctionCount(): number;
+    /**
+     * Returns the current number of cached remote functions.
+     * Useful for debugging and monitoring.
+     */
+    get remoteFunctionCount(): number;
+    /**
+     * Cleans up all function references.
+     */
+    destroy(): void;
+}
+/**
+ * Recursively serializes all functions in an object.
+ *
+ * @param obj - The object to process
+ * @param bridge - The function bridge to use for serialization
+ * @param seen - Internal set for cycle detection (do not pass manually)
+ * @returns A new object with all functions replaced by references
+ *
+ * @public
+ */
+export declare function serializeFunctions(obj: unknown, bridge: FunctionBridge, seen?: WeakSet<object>): unknown;
+/**
+ * Recursively deserializes all function references in an object.
+ *
+ * @param obj - The object to process
+ * @param bridge - The function bridge to use for deserialization
+ * @param targetWin - The window containing the original functions
+ * @param targetDomain - The origin of the target window
+ * @param seen - Internal set for cycle detection (do not pass manually)
+ * @returns A new object with all references replaced by callable wrappers
+ *
+ * @public
+ */
+export declare function deserializeFunctions(obj: unknown, bridge: FunctionBridge, targetWin: Window, targetDomain: string, seen?: WeakSet<object>): unknown;
+export {};

package/dist/communication/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @packageDocumentation
+ * Cross-domain communication module for ForgeFrame.
+ *
+ * @remarks
+ * This module provides the postMessage-based communication layer for
+ * cross-domain consumer-host component interaction. It includes message
+ * serialization, function bridging, and request/response handling.
+ */
+export { Messenger, type MessageHandler } from './messenger';
+export { FunctionBridge, serializeFunctions, deserializeFunctions, } from './bridge';
+export { PROTOCOL_PREFIX, serializeMessage, deserializeMessage, createRequestMessage, createResponseMessage, createAckMessage, } from './protocol';

package/dist/communication/messenger.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @packageDocumentation
+ * Cross-domain messenger implementation.
+ *
+ * @remarks
+ * Provides a simple request/response communication layer over postMessage,
+ * replacing post-robot with a minimal implementation.
+ */
+import type { DomainMatcher } from '../types';
+/**
+ * Handler function for incoming messages.
+ *
+ * @typeParam T - The expected data type of incoming messages
+ * @typeParam R - The return type of the handler
+ * @public
+ */
+export type MessageHandler<T = unknown, R = unknown> = (data: T, source: {
+    uid: string;
+    domain: string;
+}) => R | Promise<R>;
+/**
+ * Cross-domain messenger using postMessage.
+ *
+ * @remarks
+ * This class provides a request/response communication layer over the
+ * browser's postMessage API. It handles message serialization, timeouts,
+ * and response correlation.
+ *
+ * @example
+ * ```typescript
+ * const messenger = new Messenger('component-123', window, window.location.origin);
+ *
+ * // Register handler
+ * messenger.on('greeting', (data) => {
+ *   return { message: `Hello, ${data.name}!` };
+ * });
+ *
+ * // Send message
+ * const response = await messenger.send(targetWindow, targetOrigin, 'greeting', { name: 'World' });
+ * ```
+ *
+ * @public
+ */
+export declare class Messenger {
+    private uid;
+    private win;
+    private domain;
+    /** @internal */
+    private pending;
+    /** @internal */
+    private handlers;
+    /** @internal */
+    private listener;
+    /** @internal */
+    private destroyed;
+    /** @internal */
+    private allowedOrigins;
+    /** @internal */
+    private allowedOriginPatterns;
+    /**
+     * Creates a new Messenger instance.
+     *
+     * @param uid - Unique identifier for this messenger
+     * @param win - The window to listen for messages on
+     * @param domain - The origin domain of this messenger
+     * @param trustedDomains - Optional domains to trust for incoming messages
+     */
+    constructor(uid: string, win?: Window, domain?: string, trustedDomains?: DomainMatcher);
+    /**
+     * Adds a trusted domain that can send messages to this messenger.
+     *
+     * @param domain - Domain pattern to trust (string, RegExp, or array)
+     */
+    addTrustedDomain(domain: DomainMatcher): void;
+    /**
+     * Checks if an origin is trusted.
+     *
+     * @param origin - The origin to check
+     * @returns True if the origin is trusted
+     * @internal
+     */
+    private isOriginTrusted;
+    /**
+     * Sends a message and waits for a response.
+     *
+     * @typeParam T - The data type being sent
+     * @typeParam R - The expected response type
+     * @param targetWin - The target window to send to
+     * @param targetDomain - The target origin domain
+     * @param name - The message name/type
+     * @param data - Optional data payload
+     * @param timeout - Timeout in milliseconds (default: 10000)
+     * @returns Promise resolving to the response data
+     * @throws Error if messenger is destroyed or timeout occurs
+     */
+    send<T = unknown, R = unknown>(targetWin: Window, targetDomain: string, name: string, data?: T, timeout?: number): Promise<R>;
+    /**
+     * Sends a one-way message without waiting for a response.
+     *
+     * @typeParam T - The data type being sent
+     * @param targetWin - The target window to send to
+     * @param targetDomain - The target origin domain
+     * @param name - The message name/type
+     * @param data - Optional data payload
+     * @throws Error if messenger is destroyed
+     */
+    post<T = unknown>(targetWin: Window, targetDomain: string, name: string, data?: T): void;
+    /**
+     * Registers a handler for incoming messages of a specific type.
+     *
+     * @typeParam T - The expected data type of incoming messages
+     * @typeParam R - The return type of the handler
+     * @param name - The message name/type to handle
+     * @param handler - The handler function
+     * @returns Function to unregister the handler
+     */
+    on<T = unknown, R = unknown>(name: string, handler: MessageHandler<T, R>): () => void;
+    /**
+     * Sets up the postMessage event listener.
+     * @internal
+     */
+    private setupListener;
+    /**
+     * Processes a received message.
+     * @internal
+     */
+    private handleMessage;
+    /**
+     * Cleans up the messenger and releases resources.
+     *
+     * @remarks
+     * Removes the message listener, rejects all pending requests,
+     * and clears all handlers.
+     */
+    destroy(): void;
+    /**
+     * Checks if the messenger has been destroyed.
+     *
+     * @returns True if destroy() has been called
+     */
+    isDestroyed(): boolean;
+}

package/dist/communication/protocol.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @packageDocumentation
+ * Message protocol for ForgeFrame communication.
+ *
+ * @remarks
+ * This module defines the message format and serialization for cross-domain
+ * communication. Messages are prefixed to identify ForgeFrame traffic.
+ */
+import type { Message } from '../types';
+/**
+ * Protocol prefix to identify ForgeFrame messages.
+ * @public
+ */
+export declare const PROTOCOL_PREFIX = "forgeframe:";
+/**
+ * Serializes a message for postMessage transmission.
+ *
+ * @param message - The message to serialize
+ * @returns JSON string prefixed with the protocol identifier
+ *
+ * @public
+ */
+export declare function serializeMessage(message: Message): string;
+/**
+ * Deserializes a message from postMessage data.
+ *
+ * @param data - The raw data received from postMessage
+ * @returns The parsed message, or null if not a valid ForgeFrame message
+ *
+ * @public
+ */
+export declare function deserializeMessage(data: unknown): Message | null;
+/**
+ * Creates a request message.
+ *
+ * @param id - Unique message identifier
+ * @param name - Message name/type
+ * @param data - Message payload
+ * @param source - Sender identification
+ * @returns A formatted request message
+ *
+ * @public
+ */
+export declare function createRequestMessage(id: string, name: string, data: unknown, source: {
+    uid: string;
+    domain: string;
+}): Message;
+/**
+ * Creates a response message.
+ *
+ * @param requestId - The ID of the request being responded to
+ * @param data - Response payload
+ * @param source - Sender identification
+ * @param error - Optional error if the request failed
+ * @returns A formatted response message
+ *
+ * @public
+ */
+export declare function createResponseMessage(requestId: string, data: unknown, source: {
+    uid: string;
+    domain: string;
+}, error?: Error): Message;
+/**
+ * Creates an acknowledgement message.
+ *
+ * @param requestId - The ID of the request being acknowledged
+ * @param source - Sender identification
+ * @returns A formatted acknowledgement message
+ *
+ * @public
+ */
+export declare function createAckMessage(requestId: string, source: {
+    uid: string;
+    domain: string;
+}): Message;

package/dist/constants.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Rendering context types for components.
+ *
+ * @remarks
+ * Components can be rendered as either iframes or popups.
+ * The context determines how the host window is created and managed.
+ *
+ * @public
+ */
+export declare const CONTEXT: {
+    /** Render component in an iframe */
+    readonly IFRAME: "iframe";
+    /** Render component in a popup window */
+    readonly POPUP: "popup";
+};
+/**
+ * Union type of valid rendering contexts.
+ * @public
+ */
+export type ContextType = (typeof CONTEXT)[keyof typeof CONTEXT];
+/**
+ * Component lifecycle event names.
+ *
+ * @remarks
+ * These events are emitted during the component lifecycle and can be
+ * listened to via `instance.event.on(EVENT.RENDERED, handler)`.
+ *
+ * @example
+ * ```typescript
+ * const instance = MyComponent({ prop: 'value' });
+ * instance.event.on(EVENT.RENDERED, () => {
+ *   console.log('Component is ready!');
+ * });
+ * instance.render('#container');
+ * ```
+ *
+ * @public
+ */
+export declare const EVENT: {
+    /** Emitted when rendering starts */
+    readonly RENDER: "render";
+    /** Emitted when component is fully rendered and initialized */
+    readonly RENDERED: "rendered";
+    /** Emitted when prerender (loading) phase starts */
+    readonly PRERENDER: "prerender";
+    /** Emitted when prerender phase completes */
+    readonly PRERENDERED: "prerendered";
+    /** Emitted when component becomes visible */
+    readonly DISPLAY: "display";
+    /** Emitted when an error occurs */
+    readonly ERROR: "error";
+    /** Emitted when component is closing */
+    readonly CLOSE: "close";
+    /** Emitted when component is destroyed */
+    readonly DESTROY: "destroy";
+    /** Emitted when props are updated */
+    readonly PROPS: "props";
+    /** Emitted when component is resized */
+    readonly RESIZE: "resize";
+    /** Emitted when component receives focus */
+    readonly FOCUS: "focus";
+};
+/**
+ * Union type of valid event names.
+ * @public
+ */
+export type EventType = (typeof EVENT)[keyof typeof EVENT];
+/**
+ * Prop serialization strategies for cross-domain transfer.
+ *
+ * @remarks
+ * When props are passed from consumer to host across domains, they need to be
+ * serialized. Different strategies offer different trade-offs.
+ *
+ * @public
+ */
+export declare const PROP_SERIALIZATION: {
+    /** Default JSON serialization */
+    readonly JSON: "json";
+    /** Base64 encoding for binary or large data */
+    readonly BASE64: "base64";
+    /** Dot notation for nested objects (e.g., "a.b.c=value") */
+    readonly DOTIFY: "dotify";
+};
+/**
+ * Union type of valid serialization strategies.
+ * @public
+ */
+export type SerializationType = (typeof PROP_SERIALIZATION)[keyof typeof PROP_SERIALIZATION];
+/**
+ * Internal message types for the cross-domain communication protocol.
+ * @internal
+ */
+export declare const MESSAGE_TYPE: {
+    /** Request message expecting a response */
+    readonly REQUEST: "request";
+    /** Response to a previous request */
+    readonly RESPONSE: "response";
+    /** Acknowledgment message */
+    readonly ACK: "ack";
+};
+/**
+ * Union type of valid message types.
+ * @internal
+ */
+export type MessageType = (typeof MESSAGE_TYPE)[keyof typeof MESSAGE_TYPE];
+/**
+ * Message names for the consumer-host communication protocol.
+ *
+ * @remarks
+ * These are the internal message identifiers used by the postMessage protocol.
+ * Each message type corresponds to a specific action in the component lifecycle.
+ *
+ * @internal
+ */
+export declare const MESSAGE_NAME: {
+    /** Host initialization complete */
+    readonly INIT: "forgeframe_init";
+    /** Props update from consumer to host */
+    readonly PROPS: "forgeframe_props";
+    /** Close request from host */
+    readonly CLOSE: "forgeframe_close";
+    /** Resize request from host */
+    readonly RESIZE: "forgeframe_resize";
+    /** Focus request from host */
+    readonly FOCUS: "forgeframe_focus";
+    /** Show request from host */
+    readonly SHOW: "forgeframe_show";
+    /** Hide request from host */
+    readonly HIDE: "forgeframe_hide";
+    /** Error report from host */
+    readonly ERROR: "forgeframe_error";
+    /** Data export from host to consumer */
+    readonly EXPORT: "forgeframe_export";
+    /** Cross-domain function call */
+    readonly CALL: "forgeframe_call";
+    /** Consumer export from host context */
+    readonly CONSUMER_EXPORT: "forgeframe_consumer_export";
+    /** Get sibling components request */
+    readonly GET_SIBLINGS: "forgeframe_get_siblings";
+};
+/**
+ * Union type of valid message names.
+ * @internal
+ */
+export type MessageName = (typeof MESSAGE_NAME)[keyof typeof MESSAGE_NAME];
+/**
+ * Window name prefix for identifying ForgeFrame host windows.
+ *
+ * @remarks
+ * This prefix is prepended to the base64-encoded payload in `window.name`
+ * to identify windows created by ForgeFrame.
+ *
+ * @internal
+ */
+export declare const WINDOW_NAME_PREFIX = "__forgeframe__";
+/**
+ * Current library version.
+ * @public
+ */
+export declare const VERSION = "0.0.1";

package/dist/core/component.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @packageDocumentation
+ * Component factory and registry module.
+ *
+ * @remarks
+ * This module provides the main entry point for creating ForgeFrame components.
+ * It manages a global registry of all defined components and handles component
+ * creation, validation, and lifecycle management.
+ */
+import type { ComponentOptions, ForgeFrameComponent, ForgeFrameComponentInstance } from '../types';
+/**
+ * Creates a new ForgeFrame component definition.
+ *
+ * @remarks
+ * This is the main entry point for defining components. It creates a factory
+ * function that can be called with props to create component instances.
+ * Equivalent to zoid.create() for migration purposes.
+ *
+ * @typeParam P - The props type for the component
+ * @typeParam X - The exports type that the host can expose
+ * @param options - Component configuration options
+ * @returns A component factory function
+ *
+ * @example
+ * ```typescript
+ * import ForgeFrame, { prop } from 'forgeframe';
+ *
+ * const LoginComponent = ForgeFrame.create({
+ *   tag: 'login-component',
+ *   url: 'https://auth.example.com/login',
+ *   props: {
+ *     email: prop.string(),
+ *     onLogin: prop.function<(user: { id: string }) => void>(),
+ *   },
+ * });
+ *
+ * const instance = LoginComponent({ email: 'user@example.com', onLogin: () => {} });
+ * await instance.render('#container');
+ * ```
+ *
+ * @public
+ */
+export declare function create<P extends Record<string, unknown> = Record<string, unknown>, X = unknown>(options: ComponentOptions<P>): ForgeFrameComponent<P, X>;
+/**
+ * Retrieves a registered component by its tag name.
+ *
+ * @typeParam P - The props type for the component
+ * @typeParam X - The exports type that the host can expose
+ * @param tag - The unique tag identifier of the component
+ * @returns The component factory function, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const LoginComponent = getComponent('login-component');
+ * if (LoginComponent) {
+ *   LoginComponent({ email: 'user@example.com' }).render('#container');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getComponent<P extends Record<string, unknown> = Record<string, unknown>, X = unknown>(tag: string): ForgeFrameComponent<P, X> | undefined;
+/**
+ * Destroys a single component instance.
+ *
+ * @remarks
+ * This closes the component and cleans up all associated resources.
+ *
+ * @typeParam P - The props type for the component
+ * @param instance - The component instance to destroy
+ *
+ * @example
+ * ```typescript
+ * const instance = MyComponent({ prop: 'value' });
+ * await instance.render('#container');
+ * // Later...
+ * await destroy(instance);
+ * ```
+ *
+ * @public
+ */
+export declare function destroy<P extends Record<string, unknown>>(instance: ForgeFrameComponentInstance<P>): Promise<void>;
+/**
+ * Destroys all instances of a specific component by its tag name.
+ *
+ * @remarks
+ * Useful for cleanup when a component type is no longer needed.
+ * This destroys all active instances of the component with the given tag.
+ *
+ * @param tag - The component tag name to destroy all instances of
+ *
+ * @example
+ * ```typescript
+ * // Destroy all login component instances
+ * await destroyByTag('login-component');
+ * ```
+ *
+ * @public
+ */
+export declare function destroyByTag(tag: string): Promise<void>;
+/**
+ * Destroys all ForgeFrame component instances.
+ *
+ * @remarks
+ * This is a global cleanup function that destroys every component
+ * instance across all component types.
+ *
+ * @example
+ * ```typescript
+ * // Clean up everything on page unload
+ * window.addEventListener('beforeunload', () => {
+ *   destroyAll();
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function destroyAll(): Promise<void>;
+/**
+ * Removes a component from the registry.
+ *
+ * @remarks
+ * Primarily used for testing and cleanup. Does not destroy active instances.
+ *
+ * @param tag - The component tag to unregister
+ * @internal
+ */
+export declare function unregisterComponent(tag: string): void;
+/**
+ * Clears all components from the registry.
+ *
+ * @remarks
+ * Primarily used for testing and cleanup. Does not destroy active instances.
+ *
+ * @internal
+ */
+export declare function clearComponents(): void;