forgeframe 0.0.5 → 0.0.9

package/README.md

@@ -832,7 +832,7 @@ interface ComponentOptions<P> {
 const instance = MyComponent(props);
 
 await instance.render(container?, context?)  // Render
-await instance.renderTo(window, container?)  // Render to another window
+await instance.renderTo(window, container?)  // Supports only current window; throws for other windows
 await instance.close()                       // Close and destroy
 await instance.focus()                       // Focus
 await instance.resize({ width, height })     // Resize

package/dist/constants.d.ts

@@ -79,7 +79,7 @@ export declare const PROP_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") */
+    /** Explicit framed-path encoding for nested objects */
     readonly DOTIFY: "dotify";
 };
 /**

package/dist/core/component-instance-index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @packageDocumentation
+ * Internal active component instance index.
+ *
+ * @remarks
+ * This module tracks active component instances by UID and tag so peer lookups
+ * can be performed without scanning the full component registry.
+ */
+import type { ForgeFrameComponentInstance } from '../types';
+export type IndexedComponentInstance = ForgeFrameComponentInstance<Record<string, unknown>, unknown>;
+/**
+ * Adds an instance to the internal lookup index.
+ * @internal
+ */
+export declare function indexComponentInstance<P extends Record<string, unknown>, X>(tag: string, instance: ForgeFrameComponentInstance<P, X>): void;
+/**
+ * Removes an instance from the internal lookup index.
+ * @internal
+ */
+export declare function removeIndexedComponentInstance(uid: string): void;
+/**
+ * Removes all indexed instances for a specific component tag.
+ * @internal
+ */
+export declare function clearIndexedInstancesByTag(tag: string): void;
+/**
+ * Clears all active indexed instances.
+ * @internal
+ */
+export declare function clearIndexedInstances(): void;
+/**
+ * Returns active instances for a specific component tag.
+ * @internal
+ */
+export declare function getComponentInstancesByTag(tag: string): IndexedComponentInstance[];
+/**
+ * Returns all active indexed instances across tags.
+ * @internal
+ */
+export declare function getIndexedComponentInstances(): Array<{
+    tag: string;
+    instance: IndexedComponentInstance;
+}>;

package/dist/core/component.d.ts

@@ -8,6 +8,7 @@
  * creation, validation, and lifecycle management.
  */
 import type { ComponentOptions, ForgeFrameComponent, ForgeFrameComponentInstance } from '../types';
+import { type IndexedComponentInstance } from './component-instance-index';
 /**
  * Creates a new ForgeFrame component definition.
  *
@@ -68,6 +69,19 @@ export declare function getRegisteredComponents(): Array<[
     string,
     ForgeFrameComponent<Record<string, unknown>>
 ]>;
+/**
+ * Returns active instances for a specific component tag using an internal index.
+ * @internal
+ */
+export declare function getComponentInstancesByTag(tag: string): IndexedComponentInstance[];
+/**
+ * Returns all active indexed instances across tags.
+ * @internal
+ */
+export declare function getIndexedComponentInstances(): Array<{
+    tag: string;
+    instance: IndexedComponentInstance;
+}>;
 /**
  * Returns the internal options metadata for a component factory.
  * @internal

package/dist/core/consumer/props-pipeline.d.ts

@@ -0,0 +1,66 @@
+import type { PropContext } from '../../types';
+import type { NormalizedOptions } from './types';
+/**
+ * Hooks used by the props pipeline to coordinate host synchronization behavior.
+ * @internal
+ */
+export interface ConsumerPropsUpdateHooks<P extends Record<string, unknown>> {
+    resolveUrl: (props: P) => string;
+    resolveUrlOrigin: (url: string) => string | null;
+    assertStableRenderedOrigin: (nextHostOrigin: string | null) => void;
+    isRendered: () => boolean;
+    syncTrustedDomainForUrl: (url: string) => void;
+    shouldSendPropsToHost: () => boolean;
+    sendPropsUpdateToHost: (nextProps: P) => Promise<void>;
+    emitPropsUpdated: (nextProps: P) => void;
+}
+/**
+ * Hooks required to queue a host sync for the current props snapshot.
+ * @internal
+ */
+export interface ConsumerPropsSyncHooks<P extends Record<string, unknown>> {
+    shouldSendPropsToHost: () => boolean;
+    sendPropsUpdateToHost: (nextProps: P) => Promise<void>;
+}
+/**
+ * Owns consumer prop normalization, validation, and update queueing.
+ * @internal
+ */
+export declare class ConsumerPropsPipeline<P extends Record<string, unknown>> {
+    private options;
+    private createPropContext;
+    /** Current normalized prop snapshot. */
+    props: P;
+    /** Last input props snapshot prior to normalization. */
+    inputProps: Partial<P>;
+    /** Active in-flight update chain when host synchronization is occurring. */
+    pendingPropsUpdate: Promise<void> | null;
+    constructor(options: NormalizedOptions<P>, initialInputProps: Partial<P>, createPropContext: (props: P) => PropContext<P>);
+    /**
+     * Builds and validates the next props snapshot.
+     */
+    buildNextProps(newProps: Partial<P>): {
+        nextInputProps: Partial<P>;
+        nextProps: P;
+    };
+    /**
+     * Applies a props update and synchronizes it to the host when connected.
+     */
+    updateProps(newProps: Partial<P>, hooks: ConsumerPropsUpdateHooks<P>): Promise<void>;
+    /**
+     * Queues a host synchronization for the current props snapshot.
+     *
+     * @remarks
+     * This shares the same serialization queue as updateProps so function bridge
+     * batches cannot overlap with user-initiated prop updates.
+     */
+    syncCurrentPropsToHost(hooks: ConsumerPropsSyncHooks<P>): Promise<void>;
+    /**
+     * Queues prop updates when a previous host sync is in flight.
+     */
+    private queuePropsUpdate;
+    /**
+     * Tracks a promise as the active queued update and clears it when settled.
+     */
+    private trackPendingUpdate;
+}

package/dist/core/consumer/renderer.d.ts

@@ -0,0 +1,85 @@
+import type { ContextType } from '../../constants';
+import type { Dimensions } from '../../types';
+import type { NormalizedOptions } from './types';
+/**
+ * Parameters required to open iframe/popup host content.
+ * @internal
+ */
+export interface ConsumerOpenParams {
+    baseUrl: string;
+    buildUrl: (baseUrl: string) => string;
+    buildBodyParams: () => URLSearchParams;
+    buildWindowName: () => string;
+    submitBodyForm: (target: string, actionUrl: string, params: URLSearchParams) => void;
+    onPopupClose: () => void;
+    registerCleanup: (cleanupFn: () => void) => void;
+}
+/**
+ * Owns consumer rendering concerns (container resolution, prerender, iframe/popup lifecycle).
+ * @internal
+ */
+export declare class ConsumerRenderer<P extends Record<string, unknown>> {
+    private options;
+    private uid;
+    private getProps;
+    private resolveDimensions;
+    private callbacks;
+    /** Active rendering context. */
+    context: ContextType;
+    /** Active iframe instance when rendering in iframe mode. */
+    iframe: HTMLIFrameElement | null;
+    /** Resolved container element. */
+    container: HTMLElement | null;
+    /** Prerender element currently displayed while host initializes. */
+    prerenderElement: HTMLElement | null;
+    /** Wrapper element created and owned by the renderer. */
+    private ownedContainer;
+    constructor(options: NormalizedOptions<P>, uid: string, getProps: () => P, resolveDimensions: () => Dimensions, callbacks: {
+        close: () => Promise<void>;
+        focus: () => Promise<void>;
+    });
+    /**
+     * Resolves a container selector or element to an HTMLElement.
+     */
+    resolveContainer(container?: string | HTMLElement): HTMLElement;
+    /**
+     * Creates and displays prerender/loading content.
+     */
+    prerender(createIframeElement: (windowName: string) => HTMLIFrameElement, buildWindowName: () => string): Promise<void>;
+    /**
+     * Creates an iframe element without setting src (for prerender phase).
+     */
+    createIframeElement(windowName: string): HTMLIFrameElement;
+    /**
+     * Opens host content in iframe or popup context.
+     */
+    open(params: ConsumerOpenParams): Window | null;
+    /**
+     * Swaps prerender content with the live iframe after host initialization.
+     */
+    swapPrerenderContentIfNeeded(): Promise<void>;
+    /**
+     * Submits a hidden form to navigate a target window via POST.
+     */
+    submitBodyForm(target: string, actionUrl: string, params: URLSearchParams): void;
+    /**
+     * Focuses iframe/popup context.
+     */
+    focus(hostWindow: Window | null): void;
+    /**
+     * Resizes iframe/popup context.
+     */
+    resize(dimensions: Dimensions, hostWindow: Window | null): void;
+    /**
+     * Shows iframe context.
+     */
+    show(): void;
+    /**
+     * Hides iframe context.
+     */
+    hide(): void;
+    /**
+     * Destroys rendered iframe/popup DOM artifacts.
+     */
+    destroy(hostWindow: Window | null): void;
+}

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

@@ -0,0 +1,107 @@
+import type { ConsumerExports, Dimensions, GetPeerInstancesOptions, HostComponentRef, PropsDefinition, SerializedProps, SiblingInfo } from '../../types';
+import { Messenger } from '../../communication/messenger';
+import { FunctionBridge } from '../../communication/bridge';
+import { createDeferred } from '../../utils/promise';
+import type { ContextType } from '../../constants';
+import type { NormalizedOptions } from './types';
+interface PeerRequest {
+    uid: string;
+    tag: string;
+    options?: GetPeerInstancesOptions;
+}
+/**
+ * Callbacks used by transport to map inbound host messages to component behavior.
+ * @internal
+ */
+export interface ConsumerTransportHandlers<X> {
+    onInit?: () => void | Promise<void>;
+    onClose: () => Promise<void>;
+    onResize: (dimensions: Dimensions) => Promise<void>;
+    onFocus: () => Promise<void>;
+    onShow: () => Promise<void>;
+    onHide: () => Promise<void>;
+    onError: (error: Error) => void;
+    onExport: (exports: X) => void;
+    onConsumerExport: (data: unknown) => void;
+    onGetSiblings: (request: PeerRequest) => SiblingInfo[] | Promise<SiblingInfo[]>;
+}
+/**
+ * Owns consumer transport concerns (messenger, function bridge, trust management, handshake).
+ * @internal
+ */
+export declare class ConsumerTransport<P extends Record<string, unknown>, X = unknown> {
+    private uid;
+    private options;
+    private resolveUrl;
+    private resolveUrlOrigin;
+    /** Messenger for host communication. */
+    messenger: Messenger;
+    /** Function bridge for serializing callable props across windows. */
+    bridge: FunctionBridge;
+    /** Connected host window reference. */
+    hostWindow: Window | null;
+    /** Origin of currently opened host content. */
+    openedHostDomain: string | null;
+    /** Dynamic origin currently trusted due to resolved URL. */
+    dynamicUrlTrustedOrigin: string | null;
+    /** Deferred host initialization handshake promise. */
+    initPromise: ReturnType<typeof createDeferred<void>> | null;
+    /** Whether host initialization handshake has completed. */
+    hostInitialized: boolean;
+    constructor(uid: string, options: NormalizedOptions<P>, resolveUrl: () => string, resolveUrlOrigin: (url: string) => string | null);
+    /**
+     * Builds trusted domains used to initialize messenger security checks.
+     */
+    private buildTrustedDomains;
+    /**
+     * Returns true when the domain option explicitly includes this origin.
+     */
+    isExplicitDomainTrust(origin: string): boolean;
+    /**
+     * Ensures the messenger trusts the origin for a resolved host URL.
+     */
+    syncTrustedDomainForUrl(url: string): void;
+    /**
+     * Returns the current host domain target used for messaging.
+     */
+    getHostDomain(): string;
+    /**
+     * Returns true when the host window is connected and not closed.
+     */
+    isHostConnected(): boolean;
+    /**
+     * Serializes host props while keeping function bridge references in sync.
+     */
+    serializePropsForHost(propsForHost: Record<string, unknown>, propDefinitions: PropsDefinition<Record<string, unknown>>, options?: {
+        finishBatch?: boolean;
+    }): SerializedProps;
+    /**
+     * Sends the current props snapshot to the host window when available.
+     */
+    sendPropsUpdateToHost(nextProps: P, propDefinitions: PropsDefinition<P>): Promise<void>;
+    /**
+     * Builds the window.name payload for host initialization.
+     */
+    buildWindowName(options: {
+        tag: string;
+        context: ContextType;
+        props: P;
+        propDefinitions: PropsDefinition<P>;
+        hostDomain?: string;
+        children?: Record<string, HostComponentRef>;
+        exports: ConsumerExports;
+    }): string;
+    /**
+     * Waits for the host to send the initialization handshake.
+     */
+    waitForHost(timeout: number, tag: string, onError: (error: Error) => void): Promise<void>;
+    /**
+     * Sets up host message handlers.
+     */
+    setupMessageHandlers(handlers: ConsumerTransportHandlers<X>): void;
+    /**
+     * Destroys transport resources.
+     */
+    destroy(): void;
+}
+export {};

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

@@ -0,0 +1,24 @@
+import type { ComponentOptions, Dimensions, PropsDefinition } from '../../types';
+import type { ContextType } from '../../constants';
+/**
+ * Normalized and validated component options.
+ * @internal
+ */
+export interface NormalizedOptions<P extends Record<string, unknown>> {
+    tag: string;
+    url: string | ((props: P) => string);
+    props: PropsDefinition<P>;
+    defaultContext: ContextType;
+    dimensions: Dimensions | ((props: P) => Dimensions);
+    timeout: number;
+    domain?: ComponentOptions<P>['domain'];
+    allowedConsumerDomains?: ComponentOptions<P>['allowedConsumerDomains'];
+    containerTemplate?: ComponentOptions<P>['containerTemplate'];
+    prerenderTemplate?: ComponentOptions<P>['prerenderTemplate'];
+    eligible?: ComponentOptions<P>['eligible'];
+    validate?: ComponentOptions<P>['validate'];
+    attributes?: ComponentOptions<P>['attributes'];
+    style?: ComponentOptions<P>['style'];
+    autoResize?: ComponentOptions<P>['autoResize'];
+    children?: ComponentOptions<P>['children'];
+}

package/dist/core/consumer.d.ts

@@ -14,9 +14,8 @@ import { EventEmitter } from '../events/emitter';
  * Consumer-side component implementation.
  *
  * @remarks
- * This class manages the lifecycle of a component from the consumer (embedding app) perspective.
- * It handles rendering the component into iframes or popups, communicating with
- * the host window via postMessage, and managing component state.
+ * This class coordinates focused subsystems for rendering, transport, and
+ * prop synchronization while preserving the existing public API.
  *
  * @typeParam P - The props type passed to the component
  * @typeParam X - The exports type that the host can expose to the consumer
@@ -48,39 +47,67 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
     /** @internal */
     private options;
     /** @internal */
-    private props;
+    private cleanup;
     /** @internal */
-    private inputProps;
+    private transport;
     /** @internal */
-    private context;
+    private renderer;
     /** @internal */
-    private messenger;
+    private propsPipeline;
     /** @internal */
-    private bridge;
+    private rendered;
     /** @internal */
-    private cleanup;
+    private destroyed;
     /** @internal */
-    private hostWindow;
+    private closing;
     /** @internal */
-    private openedHostDomain;
+    private get props();
     /** @internal */
-    private dynamicUrlTrustedOrigin;
+    private set props(value);
     /** @internal */
-    private iframe;
+    private get inputProps();
     /** @internal */
-    private container;
+    private set inputProps(value);
     /** @internal */
-    private prerenderElement;
+    private get pendingPropsUpdate();
     /** @internal */
-    private initPromise;
+    private set pendingPropsUpdate(value);
     /** @internal */
-    private hostInitialized;
+    private get context();
     /** @internal */
-    private rendered;
+    private set context(value);
     /** @internal */
-    private destroyed;
+    private get hostWindow();
+    /** @internal */
+    private set hostWindow(value);
+    /** @internal */
+    private get openedHostDomain();
+    /** @internal */
+    private set openedHostDomain(value);
+    /** @internal */
+    private get dynamicUrlTrustedOrigin();
+    /** @internal */
+    private set dynamicUrlTrustedOrigin(value);
+    /** @internal */
+    private get iframe();
+    /** @internal */
+    private set iframe(value);
+    /** @internal */
+    private get container();
+    /** @internal */
+    private set container(value);
+    /** @internal */
+    private get initPromise();
+    /** @internal */
+    private set initPromise(value);
+    /** @internal */
+    private get hostInitialized();
+    /** @internal */
+    private set hostInitialized(value);
     /** @internal */
-    private pendingPropsUpdate;
+    private get messenger();
+    /** @internal */
+    private get bridge();
     /**
      * Creates a new ConsumerComponent instance.
      *
@@ -88,11 +115,6 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * @param props - Initial props to pass to the component
      */
     constructor(options: ComponentOptions<P>, props?: Partial<P>);
-    /**
-     * Builds the list of trusted domains for messenger communication.
-     * @internal
-     */
-    private buildTrustedDomains;
     /**
      * Renders the component into a DOM container.
      *
@@ -116,14 +138,14 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * Renders the component into a container in a different window.
      *
      * @remarks
-     * Currently delegates to regular render. Full cross-window rendering
-     * would require additional complexity.
+     * Only rendering into the current window is supported. Passing a
+     * different window throws explicitly to prevent silent misuse.
      *
-     * @param _win - Target window (currently unused)
+     * @param win - Target window
      * @param container - CSS selector or HTMLElement to render into
      * @param context - Override the default rendering context
      */
-    renderTo(_win: Window, container?: string | HTMLElement, context?: ContextType): Promise<void>;
+    renderTo(win: Window, container?: string | HTMLElement, context?: ContextType): Promise<void>;
     /**
      * Closes and destroys the component.
      *
@@ -172,11 +194,6 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * @internal
      */
     private applyPropsUpdate;
-    /**
-     * Builds and validates the next props snapshot.
-     * @internal
-     */
-    private buildNextProps;
     /**
      * Prevents origin changes after render for security and routing consistency.
      * @internal
@@ -192,21 +209,6 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * @internal
      */
     private emitPropsUpdated;
-    /**
-     * Queues prop updates when a previous host sync is in flight.
-     * @internal
-     */
-    private queuePropsUpdate;
-    /**
-     * Tracks pending updates only when host synchronization is active.
-     * @internal
-     */
-    private trackPendingUpdateIfHostConnected;
-    /**
-     * Tracks a promise as the active queued update and clears it when settled.
-     * @internal
-     */
-    private trackPendingUpdate;
     /**
      * Creates a clone of this instance with the same props.
      *
@@ -300,11 +302,6 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * @internal
      */
     private buildWindowName;
-    /**
-     * Serializes host props while keeping function bridge references in sync.
-     * @internal
-     */
-    private serializePropsForHost;
     /**
      * Builds component references for nested host components.
      * @internal
@@ -331,15 +328,15 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      */
     private setupMessageHandlers;
     /**
-     * Sets up host lifecycle command handlers.
+     * Synchronizes sameDomain props after the host proves its loaded origin via INIT.
      * @internal
      */
-    private setupHostLifecycleHandlers;
+    private syncSameDomainPropsAfterInit;
     /**
-     * Sets up host data exchange handlers.
+     * Returns true when any prop definition is restricted to same-origin hosts.
      * @internal
      */
-    private setupHostDataHandlers;
+    private hasSameDomainPropDefinition;
     /**
      * Gets sibling component instances for a request.
      * @internal

package/dist/core/host.d.ts

@@ -47,6 +47,8 @@ export declare class HostComponent<P extends Record<string, unknown>> {
     /** @internal */
     private consumerDomain;
     /** @internal */
+    private consumerDomainVerified;
+    /** @internal */
     private messenger;
     /** @internal */
     private bridge;
@@ -93,6 +95,42 @@ export declare class HostComponent<P extends Record<string, unknown>> {
      * @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.
      *
@@ -109,6 +147,12 @@ export declare class HostComponent<P extends Record<string, unknown>> {
      * @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