forgeframe 0.0.12 → 0.0.13

package/README.md

@@ -1,6 +1,9 @@
 # ForgeFrame
 
-A TypeScript-first framework for embedding cross-domain iframes and popups with seamless communication. Pass data and callbacks across domains — perfect for payment forms, auth widgets, third-party integrations, and micro-frontends. Zero dependencies, ~21KB gzipped (ESM) / ~12KB gzipped (UMD).
+[![npm version](https://img.shields.io/npm/v/forgeframe.svg)](https://www.npmjs.com/package/forgeframe)
+[![GitHub Release](https://img.shields.io/github/v/release/jshsmth/ForgeFrame)](https://github.com/jshsmth/ForgeFrame/releases)
+
+A TypeScript-first framework for embedding cross-domain iframes and popups with seamless communication. Pass data and callbacks across domains for payment forms, auth widgets, third-party integrations, and micro-frontends. Zero runtime dependencies with ESM and UMD builds.
 
 ### Terminology
 
@@ -133,10 +136,8 @@ 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();
-
+// Importing the runtime registers deferred host initialization for window.hostProps.
+// Call ForgeFrame.initHost() only if you need init before the first read below.
 const { amount, onSuccess, close } = window.hostProps;
 
 document.getElementById('total')!.textContent = `$${amount}`;
@@ -147,6 +148,7 @@ document.getElementById('pay-btn')!.onclick = async () => {
 ```
 
 That's it! ForgeFrame handles all the cross-domain communication automatically.
+If you need to force host initialization before first `window.hostProps` access, see [Manual Host Init with initHost](#manual-host-init-with-inithost).
 
 ---
 
@@ -210,10 +212,8 @@ 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();
-
+// Importing the runtime registers deferred host initialization for window.hostProps.
+// Call ForgeFrame.initHost() only if you need init before the first read below.
 const { email, onLogin, onCancel, close } = window.hostProps;
 
 if (email) document.getElementById('email')!.value = email;
@@ -223,7 +223,6 @@ document.getElementById('login-form')!.onsubmit = async (e) => {
   await onLogin({
     id: 1,
     name: 'John Doe',
-    email: document.getElementById('email')!.value,
   });
   await close();
 };
@@ -238,7 +237,7 @@ document.getElementById('cancel')!.onclick = async () => {
 <summary>Explanation</summary>
 
 - **`HostProps<LoginProps>`**: Combines your props with built-in methods (`close`, `resize`, etc.)
-- **`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.
+- **Host init**: Importing `forgeframe` in the host bundle registers deferred host initialization. Accessing `window.hostProps` then flushes it automatically; use `ForgeFrame.initHost()` only when you need to force init before first `hostProps` access.
 - **`window.hostProps`**: Contains all props passed from the consumer plus built-in methods
 - **`close()`**: Built-in method to close the iframe/popup
 
@@ -400,6 +399,50 @@ const MyComponent = ForgeFrame.create({
 });
 ```
 
+Note: ForgeFrame runs schema validation synchronously. Schemas with async `~standard.validate` are not supported.
+
+### Advanced Prop Definitions
+
+Use the object form when a prop needs transport rules in addition to validation.
+
+```typescript
+import ForgeFrame, { prop, PROP_SERIALIZATION } from 'forgeframe';
+
+const SecureWidget = ForgeFrame.create({
+  tag: 'secure-widget',
+  url: 'https://widgets.example.com/secure',
+  props: {
+    profile: {
+      schema: prop.object(),
+      serialization: PROP_SERIALIZATION.DOTIFY,
+    },
+    secret: {
+      schema: prop.string(),
+      sameDomain: true,
+    },
+    auditId: {
+      schema: prop.string(),
+      queryParam: true,
+    },
+    internalState: {
+      schema: prop.any(),
+      sendToHost: false,
+    },
+  },
+});
+```
+
+| Option | Description |
+|--------|-------------|
+| `sendToHost` | Skip sending the prop to the host when set to `false` |
+| `sameDomain` | Only deliver the prop after the loaded host is verified to be same-origin. It is not included in the initial bootstrap payload |
+| `trustedDomains` | Only send the prop to matching host domains |
+| `serialization` | Choose how object props are transferred: `JSON` (default), `BASE64`, or `DOTIFY` |
+| `queryParam` / `bodyParam` | Include the prop in the host page's initial HTTP request |
+
+- Use `sameDomain` for values that should never be exposed during cross-origin bootstrap.
+- `DOTIFY` safely preserves nested object keys that contain separators such as `.`, `&`, or `=`.
+
 ### Passing Props via URL or POST Body (Advanced)
 
 Use prop definition flags to include specific values in the host page's initial HTTP request:
@@ -440,12 +483,23 @@ window.hostProps.onProps((newProps) => {
 });
 ```
 
+Built-in `window.hostProps` names are reserved. Consumer props with names such as
+`uid`, `tag`, `close`, `focus`, `resize`, `show`, `hide`, `onProps`, `onError`,
+`getConsumer`, `getConsumerDomain`, `export`, `consumer`, `getPeerInstances`, and
+`children` are kept in `hostProps.consumer.props`, but they do not override the
+top-level ForgeFrame methods and metadata exposed on `window.hostProps`.
+
 ---
 
 ## Host Window API (hostProps)
 
 In host windows, `window.hostProps` provides access to props and control methods.
 
+When rendering in iframe mode, ForgeFrame applies a default sandbox of
+`allow-scripts allow-same-origin allow-forms allow-popups` unless you explicitly
+set `attributes.sandbox` on the consumer component. An explicit `sandbox` value is
+used as-is.
+
 ### TypeScript Setup
 
 ```typescript
@@ -462,13 +516,21 @@ 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();
-
+// Import the runtime in your host bundle so ForgeFrame can expose window.hostProps.
 const { email, onLogin, close, resize } = window.hostProps!;
 ```
 
+### Manual Host Init with initHost
+
+`ForgeFrame.initHost()` is optional and only needed to force the host handshake early.
+
+Use it when:
+- You need initialization to complete before the first read of `window.hostProps`.
+- Your host boot flow delays that first `window.hostProps` access (for example: lazy-loaded modules, async startup, or gated initialization).
+- You want deterministic init timing in tests or instrumentation.
+
+You can skip it when the host bundle imports `forgeframe` at runtime and normal startup reads `window.hostProps` directly, since that first access flushes host initialization automatically.
+
 ### Available Methods
 
 ```typescript
@@ -485,16 +547,17 @@ await props.resize({ width: 500, height: 400 });
 await props.show();
 await props.hide();
 
-props.onProps((newProps) => { /* handle updates */ });
-props.onError(new Error('Something failed'));
+const { cancel } = props.onProps((newProps) => { /* handle updates */ });
+await props.onError(new Error('Something failed'));
 await props.export({ validate: () => true });
 
 props.getConsumer();
 props.getConsumerDomain();
 props.consumer.props;
-props.consumer.export(data);
+await props.consumer.export(data);
 
 const peers = await props.getPeerInstances();
+cancel();
 ```
 
 <details>
@@ -505,16 +568,18 @@ const peers = await props.getPeerInstances();
 | `email`, `onLogin` | Your custom props and callbacks |
 | `uid`, `tag` | Built-in identifiers |
 | `close()` | Close the component |
-| `focus()` | Focus (popup only) |
+| `focus()` | Request focus for iframe/popup |
 | `resize()` | Resize the component |
 | `show()`, `hide()` | Toggle visibility |
-| `onProps()` | Listen for prop updates |
+| `onProps()` | Listen for prop updates (returns `{ cancel() }`) |
 | `onError()` | Report errors to consumer |
 | `export()` | Export methods/data to consumer |
 | `getConsumer()` | Get consumer window reference |
 | `getConsumerDomain()` | Get consumer origin |
 | `consumer.props` | Access consumer's props |
+| `consumer.export()` | Send data to consumer from host context |
 | `getPeerInstances()` | Get peer component instances from the same consumer |
+| `children` | Nested component factories provided by consumer (if configured) |
 
 </details>
 
@@ -525,7 +590,7 @@ Host components can export methods/data for the consumer to use.
 > **`Host`**
 
 ```typescript
-window.hostProps.export({
+await window.hostProps.export({
   validate: () => document.getElementById('form').checkValidity(),
   getFormData: () => ({ email: document.getElementById('email').value }),
 });
@@ -624,7 +689,7 @@ const MyComponent = ForgeFrame.create({
 ### Basic Usage
 
 ```tsx
-import React from 'react';
+import React, { useState } from 'react';
 import ForgeFrame, { prop, createReactComponent } from 'forgeframe';
 
 const LoginComponent = ForgeFrame.create({
@@ -721,6 +786,7 @@ const AutoResizeComponent = ForgeFrame.create({
 ### Domain Security
 
 Restrict which domains can embed or communicate.
+String domain patterns support `*` wildcards (for example, `'https://*.myapp.com'`), and arrays can mix strings and `RegExp`.
 
 ```typescript
 const SecureComponent = ForgeFrame.create({
@@ -793,13 +859,15 @@ 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.initHost()             // Optional: flush host handshake before first hostProps access
 ForgeFrame.getHostProps()         // Get hostProps in host context
 ForgeFrame.isStandardSchema(val)  // Check if value is a Standard Schema
 
 ForgeFrame.prop                   // Prop schema builders (also exported as `prop`)
+ForgeFrame.PROP_SERIALIZATION     // Prop serialization constants
 ForgeFrame.CONTEXT                // Context constants (IFRAME, POPUP)
 ForgeFrame.EVENT                  // Event name constants
+ForgeFrame.PopupOpenError         // Popup blocker/open failures
 ForgeFrame.VERSION                // Library version
 ```
 
@@ -809,20 +877,20 @@ ForgeFrame.VERSION                // Library version
 interface ComponentOptions<P> {
   tag: string;
   url: string | ((props: P) => string);
-  dimensions?: { width?: number | string; height?: number | string };
+  dimensions?: { width?: number | string; height?: number | string } | ((props: P) => { width?: number | string; height?: number | string });
   autoResize?: { width?: boolean; height?: boolean; element?: string };
   props?: PropsDefinition<P>;
   defaultContext?: 'iframe' | 'popup';
-  containerTemplate?: (ctx: TemplateContext) => HTMLElement;
-  prerenderTemplate?: (ctx: TemplateContext) => HTMLElement;
-  domain?: string;
-  allowedConsumerDomains?: Array<string | RegExp>;
+  containerTemplate?: (ctx: TemplateContext<P>) => HTMLElement | null;
+  prerenderTemplate?: (ctx: TemplateContext<P>) => HTMLElement | null;
+  domain?: DomainMatcher;
+  allowedConsumerDomains?: DomainMatcher;
   eligible?: (opts: { props: P }) => { eligible: boolean; reason?: string };
   validate?: (opts: { props: P }) => void;
-  attributes?: IframeAttributes;
-  style?: CSSProperties;
+  attributes?: IframeAttributes | ((props: P) => IframeAttributes);
+  style?: IframeStyles | ((props: P) => IframeStyles);
   timeout?: number;
-  children?: () => Record<string, ForgeFrameComponent>;
+  children?: (opts: { props: P }) => Record<string, ForgeFrameComponent>;
 }
 ```
 
@@ -831,14 +899,14 @@ interface ComponentOptions<P> {
 ```typescript
 const instance = MyComponent(props);
 
-await instance.render(container?, context?)  // Render
+await instance.render(container, context?)   // Render into a container (container is required)
 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
 await instance.show()                        // Show
 await instance.hide()                        // Hide
-await instance.updateProps(newProps)         // Update props
+await instance.updateProps(newProps)         // Update props (normalized + validated)
 instance.clone()                             // Clone with same props
 instance.isEligible()                        // Check eligibility
 
@@ -881,7 +949,7 @@ import ForgeFrame, {
 ### Typing Host hostProps
 
 ```typescript
-import { type HostProps } from 'forgeframe';
+import ForgeFrame, { type HostProps } from 'forgeframe';
 
 interface MyProps {
   name: string;
@@ -894,6 +962,7 @@ declare global {
   }
 }
 
+// Import the runtime in your host bundle so ForgeFrame can expose window.hostProps.
 window.hostProps!.name;
 window.hostProps!.onSubmit;
 window.hostProps!.close;
@@ -904,16 +973,9 @@ window.hostProps!.resize;
 
 ## Browser Support
 
-ForgeFrame requires modern browser features (ES2022+).
-
-| Browser | Minimum Version |
-|---------|-----------------|
-| Chrome | 80+ |
-| Firefox | 75+ |
-| Safari | 14+ |
-| Edge | 80+ |
+ForgeFrame ships ES2022 output. Use modern evergreen browsers or transpile the package for older targets in your consumer build pipeline.
 
-**Note:** Internet Explorer is not supported. For IE support, use [Zoid](https://github.com/krakenjs/zoid).
+**Note:** Internet Explorer is not supported. If you require IE-era compatibility, use [Zoid](https://github.com/krakenjs/zoid).
 
 ---
 

package/dist/communication/index.d.ts

@@ -1,11 +1,12 @@
 /**
  * @packageDocumentation
- * Cross-domain communication module for ForgeFrame.
+ * Internal source barrel for ForgeFrame communication primitives.
  *
  * @remarks
- * This module provides the postMessage-based communication layer for
- * cross-domain consumer-host component interaction. It includes message
- * serialization, function bridging, and request/response handling.
+ * This file groups the postMessage protocol, function bridge, and messenger
+ * internals for source organization. The published package does not expose a
+ * `forgeframe/communication` subpath, so consumers should treat this barrel as
+ * internal implementation structure.
  */
 export { Messenger, type MessageHandler } from './messenger';
 export { FunctionBridge, serializeFunctions, deserializeFunctions, } from './bridge';

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

@@ -0,0 +1,19 @@
+/**
+ * @packageDocumentation
+ * Consumer callback helper module.
+ *
+ * @remarks
+ * Centralizes consumer-side prop callback invocation and error dispatch so the
+ * main consumer component can stay focused on lifecycle orchestration.
+ */
+import type { EventEmitter } from '../../events/emitter';
+/**
+ * Calls a prop callback if it exists while isolating sync and async failures.
+ * @internal
+ */
+export declare function invokePropCallback(props: Record<string, unknown>, name: string, ...args: unknown[]): void;
+/**
+ * Emits a consumer error event and forwards it to the `onError` prop callback.
+ * @internal
+ */
+export declare function emitConsumerError(event: EventEmitter, props: Record<string, unknown>, error: Error): void;

package/dist/core/consumer/child-refs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @packageDocumentation
+ * Consumer child-reference helper module.
+ *
+ * @remarks
+ * Converts nested consumer child definitions into the serializable host
+ * component references included in the consumer window payload.
+ */
+import type { HostComponentRef } from '../../types';
+import type { NormalizedOptions } from './types';
+/**
+ * Builds component references for nested host components.
+ * @internal
+ */
+export declare function buildNestedHostRefs<P extends Record<string, unknown>>(options: Pick<NormalizedOptions<P>, 'children'>, props: P): Record<string, HostComponentRef> | undefined;

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

@@ -0,0 +1,23 @@
+/**
+ * @packageDocumentation
+ * Consumer sibling lookup helper module.
+ *
+ * @remarks
+ * Encapsulates the indexed-instance queries used to answer host requests for
+ * sibling consumer instances without keeping that logic inside the façade.
+ */
+import type { GetPeerInstancesOptions, SiblingInfo } from '../../types';
+/**
+ * Request shape used for consumer sibling lookups.
+ * @internal
+ */
+export interface ConsumerSiblingRequest {
+    uid: string;
+    tag: string;
+    options?: GetPeerInstancesOptions;
+}
+/**
+ * Returns sibling component instances for a host peer lookup.
+ * @internal
+ */
+export declare function getSiblingInstances(request: ConsumerSiblingRequest): SiblingInfo[];

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

@@ -1,14 +1,18 @@
-import type { ConsumerExports, Dimensions, GetPeerInstancesOptions, HostComponentRef, PropsDefinition, SerializedProps, SiblingInfo } from '../../types';
+/**
+ * @packageDocumentation
+ * Consumer transport subsystem module.
+ *
+ * @remarks
+ * Owns consumer-side messaging, function bridging, trust management, and host
+ * handshake concerns for embedded iframe and popup instances.
+ */
+import type { ConsumerExports, Dimensions, 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 { ConsumerSiblingRequest } from './siblings';
 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
@@ -23,7 +27,7 @@ export interface ConsumerTransportHandlers<X> {
     onError: (error: Error) => void;
     onExport: (exports: X) => void;
     onConsumerExport: (data: unknown) => void;
-    onGetSiblings: (request: PeerRequest) => SiblingInfo[] | Promise<SiblingInfo[]>;
+    onGetSiblings: (request: ConsumerSiblingRequest) => SiblingInfo[] | Promise<SiblingInfo[]>;
 }
 /**
  * Owns consumer transport concerns (messenger, function bridge, trust management, handshake).
@@ -108,4 +112,3 @@ export declare class ConsumerTransport<P extends Record<string, unknown>, X = un
      */
     destroy(): void;
 }
-export {};

package/dist/core/consumer.d.ts

@@ -60,54 +60,6 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
     private destroyed;
     /** @internal */
     private closing;
-    /** @internal */
-    private get props();
-    /** @internal */
-    private set props(value);
-    /** @internal */
-    private get inputProps();
-    /** @internal */
-    private set inputProps(value);
-    /** @internal */
-    private get pendingPropsUpdate();
-    /** @internal */
-    private set pendingPropsUpdate(value);
-    /** @internal */
-    private get context();
-    /** @internal */
-    private set context(value);
-    /** @internal */
-    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 get messenger();
-    /** @internal */
-    private get bridge();
     /**
      * Creates a new ConsumerComponent instance.
      *
@@ -204,11 +156,6 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * @internal
      */
     private sendPropsUpdateToHost;
-    /**
-     * Emits prop update lifecycle hooks.
-     * @internal
-     */
-    private emitPropsUpdated;
     /**
      * Creates a clone of this instance with the same props.
      *
@@ -302,11 +249,6 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * @internal
      */
     private buildWindowName;
-    /**
-     * Builds component references for nested host components.
-     * @internal
-     */
-    private buildNestedHostRefs;
     /**
      * Creates the exports object sent to the host.
      * @internal
@@ -337,26 +279,11 @@ export declare class ConsumerComponent<P extends Record<string, unknown>, X = un
      * @internal
      */
     private hasSameDomainPropDefinition;
-    /**
-     * Gets sibling component instances for a request.
-     * @internal
-     */
-    private getSiblingInstances;
     /**
      * Registers cleanup handlers for the instance.
      * @internal
      */
     private setupCleanup;
-    /**
-     * Handles errors by emitting events and calling callbacks.
-     * @internal
-     */
-    private handleError;
-    /**
-     * Calls a prop callback if it exists.
-     * @internal
-     */
-    private callPropCallback;
     /**
      * Destroys the component and cleans up all resources.
      * @internal

package/dist/core/host/auto-init.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @packageDocumentation
+ * Internal root-entrypoint host pre-initialization helper.
+ *
+ * @remarks
+ * Keeps root import-time host setup colocated with the host bootstrap
+ * internals instead of mixing it into the public package entrypoint.
+ */
+/**
+ * Pre-initializes host state when the public root entrypoint is imported in a
+ * browser window.
+ *
+ * @remarks
+ * INIT remains deferred until `initHost()` is explicitly flushed or a host
+ * component definition does so.
+ *
+ * @internal
+ */
+export declare function preinitHostOnImport(): void;

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

@@ -0,0 +1,15 @@
+/**
+ * @packageDocumentation
+ * Host bootstrap and singleton lifecycle helpers.
+ *
+ * @remarks
+ * This internal module owns host instance creation, singleton reuse, deferred
+ * init flushing decisions, and cleanup for `initHost()`/`clearHostInstance()`.
+ */
+import type { DomainMatcher, PropsDefinition } from '../../types';
+import { HostComponent } from './component';
+export declare function initHost<P extends Record<string, unknown>>(propDefinitions?: PropsDefinition<P>, allowedConsumerDomains?: DomainMatcher, options?: {
+    deferInit?: boolean;
+}): HostComponent<P> | null;
+export declare function getHost<P extends Record<string, unknown>>(): HostComponent<P> | null;
+export declare function clearHostInstance(): void;

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

@@ -0,0 +1,32 @@
+/**
+ * @packageDocumentation
+ * Host runtime coordinator.
+ *
+ * @remarks
+ * This internal module keeps `HostComponent` focused on orchestration. It wires
+ * together security checks, message transport, and host props state while
+ * preserving the public host runtime surface exported from `src/core/host.ts`.
+ */
+import { EventEmitter } from '../../events/emitter';
+import type { DomainMatcher, HostProps, PropsDefinition, WindowNamePayload } from '../../types';
+export declare class HostComponent<P extends Record<string, unknown>> {
+    event: EventEmitter;
+    private uid;
+    private tag;
+    private consumerWindow;
+    private consumerDomain;
+    private consumerDomainVerified;
+    private allowedConsumerDomains?;
+    private transport;
+    private propsRuntime;
+    private destroyed;
+    constructor(payload: WindowNamePayload<P>, propDefinitions?: PropsDefinition<P>, allowedConsumerDomains?: DomainMatcher, deferInit?: boolean);
+    get hostProps(): HostProps<P>;
+    set hostProps(value: HostProps<P>);
+    flushInit(): void;
+    getProps(): HostProps<P>;
+    getInitError(): Error | null;
+    applyHostConfiguration(propDefinitions?: PropsDefinition<P>, allowedConsumerDomains?: DomainMatcher): void;
+    assertAllowedConsumerDomain(allowedConsumerDomains: DomainMatcher): void;
+    destroy(): void;
+}

package/dist/core/host/props-runtime.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @packageDocumentation
+ * Host props state and reconciliation helpers.
+ *
+ * @remarks
+ * This internal module owns `hostProps` construction, reserved key filtering,
+ * bootstrap validation, live prop reconciliation, nested child creation, and
+ * `window.hostProps` exposure behavior.
+ */
+import type { HostProps, PropsDefinition, SerializedProps, WindowNamePayload } from '../../types';
+import type { HostPropsRuntimeOptions } from './types';
+export declare class HostPropsRuntime<P extends Record<string, unknown>> {
+    private propDefinitions;
+    private options;
+    hostProps: HostProps<P>;
+    consumerProps: P;
+    propsHandlers: Set<(props: P) => void>;
+    constructor(propDefinitions: PropsDefinition<P> | undefined, options: HostPropsRuntimeOptions);
+    initializeHostProps(payload: WindowNamePayload<P>): HostProps<P>;
+    exposeHostProps(): void;
+    applyHostConfiguration(propDefinitions: PropsDefinition<P>): void;
+    applySerializedProps(serializedProps: SerializedProps): {
+        success: true;
+    };
+    destroy(): void;
+    private onProps;
+    private deserialize;
+    private getBootstrapValidationDefinitions;
+    private buildNestedComponents;
+    private removeStaleHostProps;
+}