forgeframe 1.0.0

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 parent-child 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,202 @@
+/**
+ * Prop type constants for defining component props.
+ *
+ * @remarks
+ * These constants define the valid types for props passed between parent and child components.
+ * Use these when defining prop definitions in your component configuration.
+ *
+ * @example
+ * ```typescript
+ * const MyComponent = ForgeFrame.create({
+ *   tag: 'my-component',
+ *   url: '/component.html',
+ *   props: {
+ *     name: { type: PROP_TYPE.STRING },
+ *     count: { type: PROP_TYPE.NUMBER },
+ *     onSubmit: { type: PROP_TYPE.FUNCTION },
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare const PROP_TYPE: {
+    /** String prop type */
+    readonly STRING: "string";
+    /** Object prop type */
+    readonly OBJECT: "object";
+    /** Function prop type - serialized for cross-domain calls */
+    readonly FUNCTION: "function";
+    /** Boolean prop type */
+    readonly BOOLEAN: "boolean";
+    /** Number prop type */
+    readonly NUMBER: "number";
+    /** Array prop type */
+    readonly ARRAY: "array";
+};
+/**
+ * Union type of all valid prop types.
+ * @public
+ */
+export type PropType = (typeof PROP_TYPE)[keyof typeof PROP_TYPE];
+/**
+ * Rendering context types for components.
+ *
+ * @remarks
+ * Components can be rendered as either iframes or popups.
+ * The context determines how the child 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 parent to child 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 parent-child 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: {
+    /** Child initialization complete */
+    readonly INIT: "forgeframe_init";
+    /** Props update from parent to child */
+    readonly PROPS: "forgeframe_props";
+    /** Close request from child */
+    readonly CLOSE: "forgeframe_close";
+    /** Resize request from child */
+    readonly RESIZE: "forgeframe_resize";
+    /** Focus request from child */
+    readonly FOCUS: "forgeframe_focus";
+    /** Show request from child */
+    readonly SHOW: "forgeframe_show";
+    /** Hide request from child */
+    readonly HIDE: "forgeframe_hide";
+    /** Error report from child */
+    readonly ERROR: "forgeframe_error";
+    /** Data export from child to parent */
+    readonly EXPORT: "forgeframe_export";
+    /** Cross-domain function call */
+    readonly CALL: "forgeframe_call";
+    /** Parent export from child context */
+    readonly PARENT_EXPORT: "forgeframe_parent_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 child 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 = "1.0.0";