forgeframe 0.0.2 → 0.0.4

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`**
@@ -281,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
@@ -386,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.
@@ -507,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
 
@@ -581,7 +619,7 @@ const MyComponent = ForgeFrame.create({
 
 ---
 
-## React Integration
+## React Integration (Optional)
 
 ### Basic Usage
 
@@ -652,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.

package/dist/communication/bridge.d.ts

@@ -150,7 +150,7 @@ export declare class FunctionBridge {
  *
  * @public
  */
-export declare function serializeFunctions(obj: unknown, bridge: FunctionBridge, seen?: WeakSet<object>): unknown;
+export declare function serializeFunctions(obj: unknown, bridge: FunctionBridge, stack?: WeakSet<object>): unknown;
 /**
  * Recursively deserializes all function references in an object.
  *
@@ -163,5 +163,5 @@ export declare function serializeFunctions(obj: unknown, bridge: FunctionBridge,
  *
  * @public
  */
-export declare function deserializeFunctions(obj: unknown, bridge: FunctionBridge, targetWin: Window, targetDomain: string, seen?: WeakSet<object>): unknown;
+export declare function deserializeFunctions(obj: unknown, bridge: FunctionBridge, targetWin: Window, targetDomain: string, stack?: WeakSet<object>): unknown;
 export {};

package/dist/communication/messenger.d.ts

@@ -57,6 +57,10 @@ export declare class Messenger {
     private allowedOrigins;
     /** @internal */
     private allowedOriginPatterns;
+    /** @internal */
+    private wildcardPatternRegistry;
+    /** @internal */
+    private sourceUidRegistry;
     /**
      * Creates a new Messenger instance.
      *
@@ -86,6 +90,11 @@ export declare class Messenger {
      * @internal
      */
     private isOriginTrusted;
+    /**
+     * Resolves source identity from the browser event context.
+     * @internal
+     */
+    private resolveVerifiedSource;
     /**
      * Sends a message and waits for a response.
      *

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/consumer.d.ts

@@ -72,6 +72,8 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
     /** @internal */
     private initPromise;
     /** @internal */
+    private hostInitialized;
+    /** @internal */
     private rendered;
     /** @internal */
     private destroyed;
@@ -156,7 +158,7 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * Updates the component props and sends them to the host.
      *
      * @remarks
-     * Props are normalized and serialized before being sent to the host window.
+     * Props are normalized and validated before being sent to the host window.
      *
      * @param newProps - Partial props object to merge with existing props
      */
@@ -239,6 +241,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
@@ -269,6 +281,21 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * @internal
      */
     private setupMessageHandlers;
+    /**
+     * Sets up host lifecycle command handlers.
+     * @internal
+     */
+    private setupHostLifecycleHandlers;
+    /**
+     * Sets up host data exchange handlers.
+     * @internal
+     */
+    private setupHostDataHandlers;
+    /**
+     * Gets sibling component instances for a request.
+     * @internal
+     */
+    private getSiblingInstances;
     /**
      * Registers cleanup handlers for the instance.
      * @internal