forgeframe 0.0.1 → 0.0.3

package/README.md

@@ -55,6 +55,7 @@ Imagine a payment company (like Stripe) wants to let merchants embed a checkout
 ## Table of Contents
 
 - [Installation](#installation)
+- [Start Here (Most Users)](#start-here-most-users)
 - [Quick Start](#quick-start)
 - [Step-by-Step Guide](#step-by-step-guide)
   - [1. Define a Component](#1-define-a-component)
@@ -63,8 +64,8 @@ Imagine a payment company (like Stripe) wants to let merchants embed a checkout
   - [4. Handle Events](#4-handle-events)
 - [Props System](#props-system)
 - [Host Window API (hostProps)](#host-window-api-hostprops)
-- [Templates](#templates)
-- [React Integration](#react-integration)
+- [Templates (Advanced)](#templates-advanced)
+- [React Integration (Optional)](#react-integration-optional)
 - [Advanced Features](#advanced-features)
 - [API Reference](#api-reference)
 - [TypeScript](#typescript)
@@ -80,6 +81,17 @@ npm install forgeframe
 
 ---
 
+## Start Here (Most Users)
+
+Use this path for typical integrations:
+
+1. Follow [Quick Start](#quick-start) to get a working component.
+2. Use [Step-by-Step Guide](#step-by-step-guide) to add typed props and callbacks.
+3. Use [Props System](#props-system) and [Host Window API (hostProps)](#host-window-api-hostprops) as your primary references.
+4. Treat sections marked **Advanced** as optional unless you specifically need them.
+
+---
+
 ## Quick Start
 
 > **`Consumer`**
@@ -108,7 +120,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 +133,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 +196,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 +210,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 +238,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>
@@ -272,6 +293,8 @@ await instance.render('#container');
 | `resize` | Component was resized |
 | `focus` | Component received focus |
 
+If all you need is embed + typed props + callbacks, you can stop here and use the API reference as needed.
+
 ---
 
 ## Props System
@@ -377,6 +400,28 @@ const MyComponent = ForgeFrame.create({
 });
 ```
 
+### Passing Props via URL or POST Body (Advanced)
+
+Use prop definition flags to include specific values in the host page's initial HTTP request:
+
+```typescript
+const Checkout = ForgeFrame.create({
+  tag: 'checkout',
+  url: 'https://payments.example.com/checkout',
+  props: {
+    sessionToken: { schema: prop.string(), queryParam: true }, // ?sessionToken=...
+    csrf: { schema: prop.string(), bodyParam: true }, // POST body field "csrf"
+    userId: { schema: prop.string(), bodyParam: 'user_id' }, // custom body field name
+  },
+});
+```
+
+- `queryParam`: appends to the URL query string for initial load.
+- `bodyParam`: sends values in a hidden form `POST` for initial load (iframe and popup).
+- `bodyParam` only affects the initial navigation; later `updateProps()` uses postMessage.
+- Object values are JSON-stringified. Function and `undefined` values are skipped.
+- Most apps do not need this unless the host server requires initial URL/body parameters.
+
 ### Updating Props
 
 Props can be updated after rendering.
@@ -404,7 +449,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 +462,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!;
 ```
 
@@ -494,7 +543,9 @@ const data = await instance.exports.getFormData();
 
 ---
 
-## Templates
+## Templates (Advanced)
+
+Use this section only when you need custom containers/loading UI beyond the default behavior.
 
 ### Container Template
 
@@ -568,7 +619,7 @@ const MyComponent = ForgeFrame.create({
 
 ---
 
-## React Integration
+## React Integration (Optional)
 
 ### Basic Usage
 
@@ -639,6 +690,8 @@ const ProfileReact = createComponent(ProfileComponent);
 
 ## Advanced Features
 
+Most integrations can skip this section initially and return only when a specific requirement appears.
+
 ### Popup Windows
 
 Render as a popup instead of iframe.
@@ -740,6 +793,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/constants.d.ts

@@ -154,8 +154,4 @@ export type MessageName = (typeof MESSAGE_NAME)[keyof typeof MESSAGE_NAME];
  * @internal
  */
 export declare const WINDOW_NAME_PREFIX = "__forgeframe__";
-/**
- * Current library version.
- * @public
- */
-export declare const VERSION = "0.0.1";
+export declare const VERSION: string;

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
@@ -210,6 +239,16 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * @internal
      */
     private buildUrl;
+    /**
+     * Builds POST body parameters from props marked with bodyParam.
+     * @internal
+     */
+    private buildBodyParams;
+    /**
+     * Submits a hidden form to navigate a target window via POST.
+     * @internal
+     */
+    private submitBodyForm;
     /**
      * Builds the window.name payload for the host window.
      * @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;