forgeframe 0.0.1 → 0.0.2

package/README.md

@@ -108,7 +108,7 @@ await payment.render('#payment-container');
 > **`Host`**
 
 ```typescript
-import { type HostProps } from 'forgeframe';
+import ForgeFrame, { type HostProps } from 'forgeframe';
 
 interface PaymentProps {
   amount: number;
@@ -121,6 +121,10 @@ declare global {
   }
 }
 
+// Required when the host page doesn't use ForgeFrame.create().
+// If your host defines a component via create(), init is handled automatically.
+ForgeFrame.initHost();
+
 const { amount, onSuccess, close } = window.hostProps;
 
 document.getElementById('total')!.textContent = `$${amount}`;
@@ -180,7 +184,7 @@ const LoginForm = ForgeFrame.create<LoginProps>({
 The host page runs inside the iframe at the URL you specified. It receives props via `window.hostProps`.
 
 ```typescript
-import { type HostProps } from 'forgeframe';
+import ForgeFrame, { type HostProps } from 'forgeframe';
 
 interface LoginProps {
   email?: string;
@@ -194,6 +198,10 @@ declare global {
   }
 }
 
+// Required when the host page doesn't use ForgeFrame.create().
+// If your host defines a component via create(), init is handled automatically.
+ForgeFrame.initHost();
+
 const { email, onLogin, onCancel, close } = window.hostProps;
 
 if (email) document.getElementById('email')!.value = email;
@@ -218,7 +226,8 @@ document.getElementById('cancel')!.onclick = async () => {
 <summary>Explanation</summary>
 
 - **`HostProps<LoginProps>`**: Combines your props with built-in methods (`close`, `resize`, etc.)
-- **`window.hostProps`**: Automatically available in ForgeFrame hosts, contains all props passed from the consumer
+- **`ForgeFrame.initHost()`**: Flushes host initialization so the consumer can complete render. Only required when the host page doesn't use `ForgeFrame.create()` — if your host defines a component via `create()`, init is handled automatically.
+- **`window.hostProps`**: Contains all props passed from the consumer plus built-in methods
 - **`close()`**: Built-in method to close the iframe/popup
 
 </details>
@@ -404,7 +413,7 @@ In host windows, `window.hostProps` provides access to props and control methods
 ### TypeScript Setup
 
 ```typescript
-import { type HostProps } from 'forgeframe';
+import ForgeFrame, { type HostProps } from 'forgeframe';
 
 interface MyProps {
   email: string;
@@ -417,6 +426,10 @@ declare global {
   }
 }
 
+// Required when the host page doesn't use ForgeFrame.create().
+// If your host defines a component via create(), init is handled automatically.
+ForgeFrame.initHost();
+
 const { email, onLogin, close, resize } = window.hostProps!;
 ```
 
@@ -740,6 +753,7 @@ ForgeFrame.destroyByTag(tag)      // Destroy all instances of a tag
 ForgeFrame.destroyAll()           // Destroy all instances
 ForgeFrame.isHost()               // Check if in host context
 ForgeFrame.isEmbedded()           // Alias for isHost() - more intuitive naming
+ForgeFrame.initHost()             // Flush host handshake (only needed when create() is not used on the host)
 ForgeFrame.getHostProps()         // Get hostProps in host context
 ForgeFrame.isStandardSchema(val)  // Check if value is a Standard Schema
 

package/dist/communication/messenger.d.ts

@@ -72,6 +72,12 @@ export declare class Messenger {
      * @param domain - Domain pattern to trust (string, RegExp, or array)
      */
     addTrustedDomain(domain: DomainMatcher): void;
+    /**
+     * Removes a trusted domain from this messenger.
+     *
+     * @param domain - Domain pattern to remove (string, RegExp, or array)
+     */
+    removeTrustedDomain(domain: DomainMatcher): void;
     /**
      * Checks if an origin is trusted.
      *

package/dist/core/component.d.ts

@@ -60,6 +60,11 @@ export declare function create<P extends Record<string, unknown> = Record<string
  * @public
  */
 export declare function getComponent<P extends Record<string, unknown> = Record<string, unknown>, X = unknown>(tag: string): ForgeFrameComponent<P, X> | undefined;
+/**
+ * Returns the internal options metadata for a component factory.
+ * @internal
+ */
+export declare function getComponentOptions<P extends Record<string, unknown> = Record<string, unknown>, X = unknown>(component: ForgeFrameComponent<P, X>): ComponentOptions<P> | undefined;
 /**
  * Destroys a single component instance.
  *

package/dist/core/consumer.d.ts

@@ -60,6 +60,10 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
     /** @internal */
     private hostWindow;
     /** @internal */
+    private openedHostDomain;
+    /** @internal */
+    private dynamicUrlTrustedOrigin;
+    /** @internal */
     private iframe;
     /** @internal */
     private container;
@@ -174,6 +178,31 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * @internal
      */
     private normalizeOptions;
+    /**
+     * Resolves the host URL from static or function options.
+     * @internal
+     */
+    private resolveUrl;
+    /**
+     * Resolves dimensions from static or function options.
+     * @internal
+     */
+    private resolveDimensions;
+    /**
+     * Resolves a URL to an origin, supporting relative URLs.
+     * @internal
+     */
+    private resolveUrlOrigin;
+    /**
+     * Returns true when the domain option explicitly includes this origin.
+     * @internal
+     */
+    private isExplicitDomainTrust;
+    /**
+     * Ensures the messenger trusts the origin for a resolved host URL.
+     * @internal
+     */
+    private syncTrustedDomainForUrl;
     /**
      * Creates the prop context passed to prop callbacks and validators.
      * @internal

package/dist/core/host.d.ts

@@ -7,7 +7,7 @@
  * or popup and handles communication with the consumer window. It also provides
  * utilities for detecting host context and accessing hostProps.
  */
-import type { HostProps, WindowNamePayload, PropsDefinition } from '../types';
+import type { HostProps, WindowNamePayload, PropsDefinition, DomainMatcher } from '../types';
 import { EventEmitter } from '../events/emitter';
 /**
  * Host-side component implementation.
@@ -32,6 +32,8 @@ import { EventEmitter } from '../events/emitter';
  */
 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. */
@@ -54,13 +56,43 @@ export declare class HostComponent<P extends Record<string, unknown>> {
     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
      */
-    constructor(payload: WindowNamePayload<P>, propDefinitions?: PropsDefinition<P>);
+    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;
     /**
      * Returns the hostProps object.
      *
@@ -176,7 +208,9 @@ export declare class HostComponent<P extends Record<string, unknown>> {
  *
  * @public
  */
-export declare function initHost<P extends Record<string, unknown>>(propDefinitions?: PropsDefinition<P>): HostComponent<P> | null;
+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.
  *
@@ -247,3 +281,9 @@ 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;