forgeframe 0.0.10 → 0.0.13

package/dist/core/host/security.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @packageDocumentation
+ * Host-side consumer window and origin verification helpers.
+ *
+ * @remarks
+ * This internal module resolves the consumer window, derives browser-verifiable
+ * origins, and applies allowlist checks so host bootstrap and reconfiguration
+ * can share one security policy.
+ */
+import type { DomainMatcher } from '../../types';
+import type { HostSecurityContext } from './types';
+export declare const CONSUMER_WINDOW_RESOLUTION_ERROR = "Could not resolve consumer window";
+export declare const CONSUMER_ORIGIN_VERIFICATION_ERROR = "Could not verify consumer origin";
+export declare function resolveConsumerWindow(hostWindow?: Window): Window;
+export declare function getReferrerOrigin(hostDocument?: Document, hostWindow?: Window): string | null;
+export declare function getAccessibleConsumerOrigin(consumerWindow: Window): string | null;
+export declare function getVerifiedConsumerOrigin(consumerWindow: Window, hostDocument?: Document, hostWindow?: Window): string | null;
+export declare function resolveConsumerSecurityContext(options: {
+    consumerWindow: Window;
+    claimedConsumerDomain: string;
+    allowedConsumerDomains?: DomainMatcher;
+    tag: string;
+}): HostSecurityContext;
+export declare function reassertAllowedConsumerDomain(options: {
+    consumerWindow: Window;
+    consumerDomain: string;
+    consumerDomainVerified: boolean;
+    allowedConsumerDomains: DomainMatcher;
+    tag: string;
+    onConsumerDomainChange?: (previousDomain: string, nextDomain: string) => void;
+}): HostSecurityContext;

package/dist/core/host/transport.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @packageDocumentation
+ * Host runtime messaging and handshake helpers.
+ *
+ * @remarks
+ * This internal module owns the host messenger/function bridge pair, deferred
+ * INIT scheduling, outbound control messages, and inbound PROPS message
+ * registration for the host runtime.
+ */
+import { FunctionBridge } from '../../communication/bridge';
+import { Messenger } from '../../communication/messenger';
+import type { GetPeerInstancesOptions, SiblingInfo } from '../../types';
+import type { HostTransportOptions, HostTransportPropsHandler } from './types';
+export declare class HostTransport {
+    private options;
+    messenger: Messenger;
+    bridge: FunctionBridge;
+    private destroyed;
+    private initSent;
+    private initError;
+    private deferredInitFlushScheduled;
+    constructor(options: HostTransportOptions);
+    registerPropsHandler(handler: HostTransportPropsHandler): void;
+    handleHostPropsAccess(): void;
+    flushInit(): void;
+    getInitError(): Error | null;
+    updateTrustedConsumerDomain(previousDomain: string, nextDomain: string): void;
+    close(): Promise<void>;
+    focus(): Promise<void>;
+    resize(dimensions: {
+        width?: string | number;
+        height?: string | number;
+    }): Promise<void>;
+    show(): Promise<void>;
+    hide(): Promise<void>;
+    onError(error: Error): Promise<void>;
+    exportData<T>(exports: T): Promise<void>;
+    consumerExport<T>(data: T): Promise<void>;
+    getPeerInstances(options?: GetPeerInstancesOptions): Promise<SiblingInfo[]>;
+    destroy(): void;
+    private scheduleDeferredInitFlush;
+    private sendInit;
+    private sendMessage;
+}

package/dist/core/host/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @packageDocumentation
+ * Shared internal host runtime types.
+ *
+ * @remarks
+ * This internal module defines the collaboration contracts used by the host
+ * bootstrap, transport, security, and props runtime modules so they can share
+ * explicit state without reaching through each other's implementations.
+ */
+import type { FunctionBridge } from '../../communication/bridge';
+import type { MessageHandler, Messenger } from '../../communication/messenger';
+import type { EventEmitter } from '../../events/emitter';
+import type { Dimensions, DomainMatcher, GetPeerInstancesOptions, HostProps, PropsDefinition, SerializedProps, SiblingInfo } from '../../types';
+export type VerifiedMessageSource = Parameters<MessageHandler>[1];
+export interface HostSecurityContext {
+    consumerDomain: string;
+    consumerDomainVerified: boolean;
+}
+export interface HostPropsRuntimeControls {
+    close(): Promise<void>;
+    focus(): Promise<void>;
+    resize(dimensions: Dimensions): Promise<void>;
+    show(): Promise<void>;
+    hide(): Promise<void>;
+    onError(error: Error): Promise<void>;
+    exportData<T>(exports: T): Promise<void>;
+    consumerExport<T>(data: T): Promise<void>;
+    getPeerInstances(options?: GetPeerInstancesOptions): Promise<SiblingInfo[]>;
+}
+export interface HostPropsRuntimeOptions {
+    uid: string;
+    tag: string;
+    event: EventEmitter;
+    controls: HostPropsRuntimeControls;
+    getConsumerWindow(): Window;
+    getConsumerDomain(): string;
+    isConsumerDomainVerified(): boolean;
+    getMessenger(): Messenger;
+    getBridge(): FunctionBridge;
+    onFirstHostPropsAccess(): void;
+}
+export interface HostTransportOptions {
+    uid: string;
+    tag: string;
+    event: EventEmitter;
+    consumerWindow: Window;
+    consumerDomain: string;
+    getConsumerDomain(): string;
+    deferInit: boolean;
+}
+export interface HostTransportPropsHandler {
+    isConsumerSource(source: VerifiedMessageSource): boolean;
+    applySerializedProps(serializedProps: SerializedProps): {
+        success: true;
+    };
+}
+export interface HostHostConfiguration<P extends Record<string, unknown>> {
+    propDefinitions?: PropsDefinition<P>;
+    allowedConsumerDomains?: DomainMatcher;
+}
+export interface WindowWithHostProps<P extends Record<string, unknown>> extends Window {
+    hostProps?: HostProps<P>;
+}

package/dist/core/host.d.ts

@@ -3,272 +3,13 @@
  * Host component implementation module.
  *
  * @remarks
- * This module contains the HostComponent class which runs inside the iframe
- * or popup and handles communication with the consumer window. It also provides
- * utilities for detecting host context and accessing hostProps.
+ * This module exposes the public host-side runtime entrypoints while the
+ * concrete bootstrap, security, props, and transport concerns live in
+ * focused internal modules under `src/core/host/`.
  */
-import type { HostProps, WindowNamePayload, PropsDefinition, DomainMatcher } from '../types';
-import { EventEmitter } from '../events/emitter';
-/**
- * Host-side component implementation.
- *
- * @remarks
- * This class runs inside the iframe or popup window and manages communication
- * with the consumer component. It provides the hostProps object with props and
- * control methods.
- *
- * @typeParam P - The props type passed from the consumer
- *
- * @example
- * ```typescript
- * // In host window
- * const { email, onLogin, close } = window.hostProps;
- * console.log('Email:', email);
- * onLogin({ id: 1, name: 'John' });
- * close();
- * ```
- *
- * @public
- */
-export declare class HostComponent<P extends Record<string, unknown>> {
-    private propDefinitions;
-    private allowedConsumerDomains?;
-    private deferInit;
-    /** The hostProps object containing props and control methods passed from the consumer. */
-    hostProps: HostProps<P>;
-    /** Event emitter for lifecycle events. */
-    event: EventEmitter;
-    /** @internal */
-    private uid;
-    /** @internal */
-    private tag;
-    /** @internal */
-    private consumerWindow;
-    /** @internal */
-    private consumerDomain;
-    /** @internal */
-    private consumerDomainVerified;
-    /** @internal */
-    private messenger;
-    /** @internal */
-    private bridge;
-    /** @internal */
-    private propsHandlers;
-    /** @internal */
-    private consumerProps;
-    /** @internal */
-    private initError;
-    /** @internal */
-    private destroyed;
-    /** @internal */
-    private initSent;
-    /** @internal */
-    private deferredInitFlushScheduled;
-    /**
-     * Creates a new HostComponent instance.
-     *
-     * @param payload - The payload parsed from window.name
-     * @param propDefinitions - Optional prop definitions for deserialization
-     * @param allowedConsumerDomains - Optional allowlist of consumer domains
-     * @param deferInit - Whether to defer INIT until a later explicit flush
-     */
-    constructor(payload: WindowNamePayload<P>, propDefinitions?: PropsDefinition<P>, allowedConsumerDomains?: DomainMatcher | undefined, deferInit?: boolean);
-    /**
-     * Ensures the INIT handshake is sent at most once.
-     * @internal
-     */
-    flushInit(): void;
-    /**
-     * Schedules deferred INIT flush on the next microtask.
-     * This preserves legacy hostProps-only usage while giving same-tick
-     * host configuration a chance to run allowlist checks first.
-     * @internal
-     */
-    private scheduleDeferredInitFlush;
-    /**
-     * Exposes hostProps on window and lazily flushes deferred init on first access.
-     * @internal
-     */
-    private exposeHostProps;
-    /**
-     * Validates that the consumer domain is allowed.
-     * @internal
-     */
-    private validateConsumerDomain;
-    /**
-     * Reads a browser-verifiable consumer origin when available.
-     * @internal
-     */
-    private getVerifiedConsumerOrigin;
-    /**
-     * Updates the tracked consumer origin and keeps trusted messaging origins in sync.
-     * @internal
-     */
-    private setConsumerDomain;
-    /**
-     * Applies host configuration that may arrive after deferred pre-initialization.
-     * @internal
-     */
-    applyHostConfiguration(propDefinitions?: PropsDefinition<P>, allowedConsumerDomains?: DomainMatcher): void;
-    /**
-     * Resolves the consumer origin from browser-provided context and falls back to the
-     * claimed bootstrap origin only when no explicit allowlist is configured.
-     * @internal
-     */
-    private resolveConsumerDomain;
-    /**
-     * Rechecks allowlist constraints against a browser-verified consumer origin.
-     * @internal
-     */
-    assertAllowedConsumerDomain(allowedConsumerDomains: DomainMatcher): void;
-    /**
-     * Reads the consumer origin from the browser-provided referrer when available.
-     * @internal
-     */
-    private getReferrerOrigin;
-    /**
-     * Reads the consumer origin directly when same-origin access is available.
-     * @internal
-     */
-    private getAccessibleConsumerOrigin;
-    /**
-     * Returns the hostProps object.
-     *
-     * @returns The hostProps object with props and control methods
-     */
-    getProps(): HostProps<P>;
-    /**
-     * Resolves the consumer window reference (iframe parent or popup opener).
-     * @internal
-     */
-    private resolveConsumerWindow;
-    /**
-     * Builds the hostProps object with deserialized props and control methods.
-     * @internal
-     */
-    private buildHostProps;
-    /**
-     * Relaxes required sameDomain props during bootstrap for verified same-origin hosts.
-     * Those props are synchronized after INIT through the live messaging channel.
-     * @internal
-     */
-    private getBootstrapValidationDefinitions;
-    /**
-     * Sends initialization message to the consumer.
-     * @internal
-     */
-    private sendInit;
-    /**
-     * Returns the initialization error if one occurred.
-     *
-     * @returns The initialization error or null if successful
-     */
-    getInitError(): Error | null;
-    /**
-     * Requests the consumer to close this component.
-     * @internal
-     */
-    private close;
-    /**
-     * Focuses this window and notifies the consumer.
-     * @internal
-     */
-    private focus;
-    /**
-     * Requests the consumer to resize this component.
-     * @internal
-     */
-    private resize;
-    /**
-     * Requests the consumer to show this component.
-     * @internal
-     */
-    private show;
-    /**
-     * Requests the consumer to hide this component.
-     * @internal
-     */
-    private hide;
-    /**
-     * Subscribes to prop updates from the consumer.
-     * @internal
-     */
-    private onProps;
-    /**
-     * Reports an error to the consumer.
-     * @internal
-     */
-    private onError;
-    /**
-     * Exports data or methods to the consumer.
-     * @internal
-     */
-    private exportData;
-    /**
-     * Exports data to the consumer for bidirectional communication.
-     * @internal
-     */
-    private consumerExport;
-    /**
-     * Gets information about peer component instances.
-     * @internal
-     */
-    private getPeerInstances;
-    /**
-     * Builds nested component factories from refs passed by the consumer.
-     * @internal
-     */
-    private buildNestedComponents;
-    /**
-     * Sets up message handlers for consumer communication.
-     * @internal
-     */
-    private setupMessageHandlers;
-    /**
-     * Removes stale prop keys that are no longer present in the latest consumer payload.
-     * @internal
-     */
-    private removeStaleHostProps;
-    /**
-     * Destroys the host component and cleans up resources.
-     */
-    destroy(): void;
-}
-/**
- * Initializes the host component if running in a ForgeFrame window.
- *
- * @remarks
- * This function detects if the current window was created by ForgeFrame
- * and sets up the host component with hostProps. Returns null if not in
- * a ForgeFrame host context.
- *
- * @typeParam P - The props type passed from the consumer
- * @param propDefinitions - Optional prop definitions for deserialization
- * @returns The host component instance or null if not in a host window
- *
- * @example
- * ```typescript
- * const host = initHost();
- * if (host) {
- *   console.log('Running in ForgeFrame host context');
- *   console.log('Props:', host.hostProps);
- * }
- * ```
- *
- * @public
- */
-export declare function initHost<P extends Record<string, unknown>>(propDefinitions?: PropsDefinition<P>, allowedConsumerDomains?: DomainMatcher, options?: {
-    deferInit?: boolean;
-}): HostComponent<P> | null;
-/**
- * Gets the current host component instance.
- *
- * @typeParam P - The props type passed from the consumer
- * @returns The host component instance or null if not initialized
- *
- * @public
- */
-export declare function getHost<P extends Record<string, unknown>>(): HostComponent<P> | null;
+import type { HostProps } from '../types';
+export { HostComponent } from './host/component';
+export { clearHostInstance, getHost, initHost, } from './host/bootstrap';
 /**
  * Checks if the current window is a ForgeFrame host context.
  *
@@ -330,9 +71,3 @@ export declare function isEmbedded(): boolean;
  * @public
  */
 export declare function getHostProps<P extends Record<string, unknown>>(): HostProps<P> | undefined;
-/**
- * Clears and destroys the global host instance.
- * Primarily intended for testing.
- * @internal
- */
-export declare function clearHostInstance(): void;

package/dist/drivers/index.d.ts

@@ -1,18 +1,16 @@
 /**
- * ForgeFrame Framework Integration Module
+ * @packageDocumentation
+ * Internal source barrel for framework integrations.
  *
  * @remarks
- * This module provides framework-specific integrations for ForgeFrame
- * components with popular UI frameworks like React. These handle the lifecycle
- * management, prop synchronization, and rendering of cross-domain components
- * within the target framework's component model.
+ * This file keeps the driver modules organized inside the source tree.
+ * The published package does not expose a `forgeframe/drivers` subpath;
+ * consumers should import the public React driver APIs from `forgeframe`.
  *
  * @example
  * ```typescript
- * import { createReactComponent, withReactComponent } from 'forgeframe/drivers';
- * import type { ReactDriverOptions, ReactComponentProps } from 'forgeframe/drivers';
+ * import { createReactComponent, withReactComponent } from 'forgeframe';
+ * import type { ReactDriverOptions, ReactComponentProps } from 'forgeframe';
  * ```
- *
- * @packageDocumentation
  */
 export { createReactComponent, withReactComponent, type ReactDriverOptions, type ReactComponentProps, type ReactComponentType, } from './react';

package/dist/drivers/react.d.ts

@@ -204,8 +204,7 @@ export declare function createReactComponent<P extends Record<string, unknown>,
  * @example
  * ```tsx
  * import React from 'react';
- * import ForgeFrame from 'forgeframe';
- * import { withReactComponent } from 'forgeframe/drivers/react';
+ * import ForgeFrame, { withReactComponent } from 'forgeframe';
  *
  * // Create a reusable component factory
  * const createComponent = withReactComponent(React);

package/dist/forgeframe.d.ts

@@ -0,0 +1,202 @@
+import { create, destroy, destroyByTag, destroyAll, isHost, isEmbedded, getHostProps, initHost } from './core';
+import { PopupOpenError } from './render/popup';
+import { isStandardSchema } from './props/schema';
+/**
+ * Main ForgeFrame API object.
+ *
+ * @remarks
+ * Provides a zoid-compatible interface for creating and managing
+ * cross-domain components. All methods and constants are accessible
+ * through this object.
+ *
+ * @example
+ * ```typescript
+ * import ForgeFrame from 'forgeframe';
+ *
+ * const Component = ForgeFrame.create({
+ *   tag: 'my-component',
+ *   url: '/component.html',
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare const ForgeFrame: {
+    /**
+     * Create a new component definition.
+     *
+     * @remarks
+     * This is the main entry point for defining components. Returns a
+     * component factory function that can be called to create instances.
+     *
+     * @example
+     * ```typescript
+     * import ForgeFrame, { prop } from 'forgeframe';
+     *
+     * const MyComponent = ForgeFrame.create({
+     *   tag: 'my-component',
+     *   url: 'https://example.com/component',
+     *   props: {
+     *     email: prop.string().email(),
+     *     onLogin: prop.function<(user: { id: string }) => void>(),
+     *   },
+     * });
+     *
+     * const instance = MyComponent({ email: 'user@example.com', onLogin: (user) => {} });
+     * await instance.render('#container');
+     * ```
+     */
+    readonly create: typeof create;
+    /**
+     * Destroy a single component instance.
+     *
+     * @param instance - The component instance to destroy
+     */
+    readonly destroy: typeof destroy;
+    /**
+     * Destroy all instances of a specific component by tag.
+     *
+     * @param tag - The component tag name
+     */
+    readonly destroyByTag: typeof destroyByTag;
+    /**
+     * Destroy all ForgeFrame component instances.
+     */
+    readonly destroyAll: typeof destroyAll;
+    /**
+     * Check if the current window is a host component context.
+     *
+     * @remarks
+     * A "host" is the embedded iframe or popup window that receives props
+     * from the consumer (the embedding app).
+     *
+     * @returns True if running inside a ForgeFrame iframe/popup
+     */
+    readonly isHost: typeof isHost;
+    /**
+     * Check if the current window is embedded by ForgeFrame.
+     *
+     * @remarks
+     * This is an alias for {@link isHost} that uses more intuitive terminology.
+     *
+     * @returns True if running inside a ForgeFrame iframe/popup
+     */
+    readonly isEmbedded: typeof isEmbedded;
+    /**
+     * Get hostProps from the current host window.
+     *
+     * @remarks
+     * Returns the props passed from the consumer plus built-in control methods.
+     *
+     * @returns The hostProps object if in host context, undefined otherwise
+     */
+    readonly getHostProps: typeof getHostProps;
+    /**
+     * Flush host initialization in embedded contexts.
+     *
+     * @remarks
+     * Only required in host pages that access `window.hostProps` directly
+     * without defining a component via `ForgeFrame.create(...)`.
+     * When `create()` is used on the host side, init is flushed automatically.
+     *
+     * @returns The host component instance if running embedded, otherwise null
+     */
+    readonly initHost: typeof initHost;
+    /**
+     * Serialization strategy constants.
+     * @see {@link PROP_SERIALIZATION}
+     */
+    readonly PROP_SERIALIZATION: {
+        readonly JSON: "json";
+        readonly BASE64: "base64";
+        readonly DOTIFY: "dotify";
+    };
+    /**
+     * Rendering context constants (IFRAME, POPUP).
+     * @see {@link CONTEXT}
+     */
+    readonly CONTEXT: {
+        readonly IFRAME: "iframe";
+        readonly POPUP: "popup";
+    };
+    /**
+     * Lifecycle event name constants.
+     * @see {@link EVENT}
+     */
+    readonly EVENT: {
+        readonly RENDER: "render";
+        readonly RENDERED: "rendered";
+        readonly PRERENDER: "prerender";
+        readonly PRERENDERED: "prerendered";
+        readonly DISPLAY: "display";
+        readonly ERROR: "error";
+        readonly CLOSE: "close";
+        readonly DESTROY: "destroy";
+        readonly PROPS: "props";
+        readonly RESIZE: "resize";
+        readonly FOCUS: "focus";
+    };
+    /**
+     * Error thrown when popup window fails to open.
+     */
+    readonly PopupOpenError: typeof PopupOpenError;
+    /**
+     * Current library version.
+     */
+    readonly VERSION: string;
+    /**
+     * Check if a value is a Standard Schema (Zod, Valibot, ArkType, etc.)
+     *
+     * @param value - The value to check
+     * @returns True if the value implements StandardSchemaV1
+     *
+     * @example
+     * ```typescript
+     * import { z } from 'zod';
+     *
+     * const schema = z.string();
+     * if (ForgeFrame.isStandardSchema(schema)) {
+     *   // schema is StandardSchemaV1
+     * }
+     * ```
+     */
+    readonly isStandardSchema: typeof isStandardSchema;
+    /**
+     * Prop schema builders for defining component props.
+     *
+     * @remarks
+     * Provides a fluent, Zod-like API for defining prop schemas with built-in
+     * validation. All schemas implement StandardSchemaV1.
+     *
+     * @example
+     * ```typescript
+     * import ForgeFrame from 'forgeframe';
+     *
+     * const Component = ForgeFrame.create({
+     *   tag: 'my-component',
+     *   url: '/component',
+     *   props: {
+     *     name: ForgeFrame.prop.string(),
+     *     count: ForgeFrame.prop.number().default(0),
+     *     onSubmit: ForgeFrame.prop.function().optional(),
+     *   },
+     * });
+     * ```
+     */
+    readonly prop: {
+        readonly string: () => import("./props").StringSchema;
+        readonly number: () => import("./props").NumberSchema;
+        readonly boolean: () => import("./props").BooleanSchema;
+        readonly function: <T extends (...args: any[]) => any = (...args: any[]) => any>() => import("./props").FunctionSchema<T>;
+        readonly array: <T = unknown>() => import("./props").ArraySchema<T>;
+        readonly object: <T extends object = Record<string, unknown>>() => import("./props").ObjectSchema<T>;
+        readonly literal: <T extends string | number | boolean>(value: T) => import("./props").LiteralSchema<T>;
+        readonly enum: <T extends string | number>(values: readonly T[]) => import("./props").EnumSchema<T>;
+        readonly any: () => import("./props").AnySchema;
+    };
+};
+/**
+ * Default export of the ForgeFrame API object.
+ * @public
+ */
+export default ForgeFrame;