@nominalso/vibe-host 0.0.1 → 0.1.0

package/README.md

@@ -1,9 +1,8 @@
 # @nominalso/vibe-host
 
-Host-side SDK for embedding **Nominal Vibe Apps**. Used by the Nominal app (nom-ui) to receive requests from an
-embedded Vibe App over a typed `postMessage` protocol and dispatch them to Nominal APIs. The host ships a
-**complete, type-checked handler map** covering every protocol operation — you only supply a `clientConfig`
-pointing at the Nominal API, and the SDK wires up and dispatches all operations for you.
+Host-side SDK for embedding **Nominal Vibe Apps**. Used by the Nominal app (nom-ui) to receive requests from an embedded Vibe App over a typed `postMessage` protocol and dispatch them to Nominal APIs. The host ships a **complete, type-checked handler map** covering every protocol operation — you supply a `clientConfig` pointing at the Nominal API, and the SDK wires up and dispatches all operations for you.
+
+> **For AI agents:** you do **not** pass a `handlers` map. Provide `clientConfig` (where the Nominal API lives) and the SDK builds every handler. The iframe-side counterpart is `@nominalso/vibe-bridge`.
 
 ## Install
 
@@ -11,28 +10,93 @@ pointing at the Nominal API, and the SDK wires up and dispatches all operations
 npm install @nominalso/vibe-host
 ```
 
-## Usage
+Externalizes only `@hey-api/client-fetch`; TypeScript types are self-contained.
+
+## Quickstart
 
 ```tsx
 import { VibeAppHost } from '@nominalso/vibe-host'
 
 const host = new VibeAppHost({
+  // Iframe origin(s) allowed to talk to this host — must match exactly.
   trustedOrigins: ['https://my-vibe-app.lovable.app'],
+  // This Vibe App's base path in nom-ui (used to sync the browser URL).
   appBasePath: `/${tenant}/${subsidiary}/apps/${slug}`,
+  // Context pushed to the iframe on connect.
   getContext: () => ({ tenant, subsidiaryId, subsidiaries, user, lastClosedPeriodSlug }),
   // Points the built-in handler map at the Nominal API (e.g. nom-ui's proxy route).
-  // The SDK provides handlers for every protocol operation out of the box.
   clientConfig: { baseUrl: '/api/proxy', stripApiPrefix: true },
 })
 
-// Start listening before the iframe loads, then push context on its `load` event.
+// Start listening BEFORE the iframe loads, then push context on its `load` event.
 const unmount = host.mount()
-// host.pushContextTo(iframe.contentWindow)
+// once the iframe has loaded: host.pushContextTo(iframe.contentWindow)
 ```
 
-The iframe side is [`@nominalso/vibe-bridge`](https://www.npmjs.com/package/@nominalso/vibe-bridge). See the
-[repository](https://github.com/nominalso/vibe-apps-sdk#readme) for the full protocol, architecture, and the
-SSR / iframe-mounting notes.
+## API
+
+### `new VibeAppHost(options)`
+
+| Option           | Type                    | Description                                                                                               |
+| ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
+| `trustedOrigins` | `string[]`              | Iframe origins allowed to talk to this host. Messages from other origins are ignored.                     |
+| `getContext`     | `() => HostContext`     | Returns the current context to send to the iframe (`hostVersion` is injected automatically).              |
+| `appBasePath`    | `string`                | Base URL path of this Vibe App in nom-ui, e.g. `/acme/1/apps/fixed-assets`.                               |
+| `clientConfig`   | `VibeApiClientOptions?` | Points the built-in handler map at the Nominal API. Defaults to `{ baseUrl: '', stripApiPrefix: false }`. |
+
+`VibeApiClientOptions` is `{ baseUrl: string; stripApiPrefix?: boolean }`. Set `stripApiPrefix: true` when routing through a proxy whose convention expects paths without the `/api` prefix.
+
+### `mount(iframeWindow?): () => void`
+
+Starts listening for bridge messages and sets up browser back/forward sync. Returns a cleanup function. Pass `iframeWindow` to immediately push context; if omitted, the host answers `GET_CONTEXT` polls but won't proactively push until you call `pushContextTo`.
+
+### `pushContextTo(iframeWindow): void`
+
+Pushes the current context to the iframe and stores the window reference for future pushes (e.g. subroute sync). Call once the iframe has loaded if you called `mount()` with no argument.
+
+### Exports
+
+`VibeAppHost`, and the types `VibeAppHostOptions`, `HostContext`, `HostHandlers`, `RequestHandlers`, `ContextPayload`, `VibeApiClientOptions`.
+
+## Mounting inside Next.js (nom-ui)
+
+The iframe is server-rendered, so it may start loading before React hydrates, and cross-origin `contentDocument` is always `null`. The robust pattern: `mount()` (no arg) immediately to start listening, then `pushContextTo(iframe.contentWindow)` from the iframe's `load` event.
+
+```tsx
+'use client'
+import { useEffect, useRef } from 'react'
+import { VibeAppHost } from '@nominalso/vibe-host'
+
+function VibeAppFrame({ host, src }: { host: VibeAppHost; src: string }) {
+  const iframeRef = useRef<HTMLIFrameElement>(null)
+
+  useEffect(() => {
+    const iframe = iframeRef.current
+    if (!iframe) return
+    const unmount = host.mount() // listen before the iframe loads
+    const onLoad = () => iframe.contentWindow && host.pushContextTo(iframe.contentWindow)
+    iframe.addEventListener('load', onLoad)
+    return () => {
+      iframe.removeEventListener('load', onLoad)
+      unmount()
+    }
+  }, [host])
+
+  return (
+    <iframe
+      ref={iframeRef}
+      src={src}
+      sandbox="allow-scripts allow-forms allow-same-origin allow-popups"
+    />
+  )
+}
+```
+
+Calling `contentWindow.postMessage` while the iframe is still at `about:blank` throws a `DOMException` — that's why context is pushed from the `load` event, not on effect setup.
+
+## How it fits together
+
+The iframe side is [`@nominalso/vibe-bridge`](https://www.npmjs.com/package/@nominalso/vibe-bridge). See the [repository](https://github.com/nominalso/vibe-apps-sdk#readme) for the full protocol and architecture.
 
 ## License
 

package/dist/index.cjs

@@ -25,7 +25,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.0.1";
+var version = "0.1.0";
 
 // ../protocol-types/dist/index.js
 var PROTOCOL_ID = "nominal-vibe-bridge";

package/dist/index.d.cts

@@ -3447,6 +3447,11 @@ interface VibeApiClientOptions {
 type HostHandlers = Omit<RequestHandlers, 'GET_CONTEXT'>;
 type HostContext = Omit<ContextPayload, 'hostVersion'>;
 interface VibeAppHostOptions {
+    /**
+     * Iframe origins allowed to talk to this host. Messages from any other origin
+     * are ignored, and context/pushes are only sent to these origins. Must match
+     * the Vibe App's origin exactly (e.g. `'https://my-vibe-app.lovable.app'`).
+     */
     trustedOrigins: string[];
     /** Returns the current context to send to the iframe on connect. */
     getContext: () => HostContext;
@@ -3455,8 +3460,44 @@ interface VibeAppHostOptions {
      * Used to sync the browser URL with the iframe's internal subroute.
      */
     appBasePath: string;
+    /**
+     * Points the built-in handler map at the Nominal API (e.g. nom-ui's proxy
+     * route). The host provides handlers for every protocol operation out of the
+     * box; this just tells them where to send requests. Defaults to
+     * `{ baseUrl: '', stripApiPrefix: false }`.
+     */
     clientConfig?: VibeApiClientOptions;
 }
+/**
+ * Host-side counterpart to `VibeAppBridge`. Construct it with the trusted
+ * iframe origin(s), a `getContext` callback, the app's base path, and a
+ * `clientConfig` pointing at the Nominal API; then call {@link VibeAppHost.mount}
+ * to start listening. The handler map for all protocol operations is built
+ * automatically — you do not pass handlers.
+ *
+ * @example
+ * ```tsx
+ * // In a React (nom-ui) component:
+ * const host = new VibeAppHost({
+ *   trustedOrigins: ['https://my-vibe-app.lovable.app'],
+ *   appBasePath: `/${tenant}/${subsidiary}/apps/${slug}`,
+ *   getContext: () => ({ tenant, subsidiaryId, subsidiaries, user, lastClosedPeriodSlug }),
+ *   clientConfig: { baseUrl: '/api/proxy', stripApiPrefix: true },
+ * })
+ *
+ * useEffect(() => {
+ *   const iframe = iframeRef.current
+ *   if (!iframe) return
+ *   const unmount = host.mount() // listen before the iframe loads
+ *   const onLoad = () => iframe.contentWindow && host.pushContextTo(iframe.contentWindow)
+ *   iframe.addEventListener('load', onLoad)
+ *   return () => {
+ *     iframe.removeEventListener('load', onLoad)
+ *     unmount()
+ *   }
+ * }, [host])
+ * ```
+ */
 declare class VibeAppHost {
     private readonly trustedOrigins;
     private readonly handlers;
@@ -3494,4 +3535,4 @@ declare class VibeAppHost {
     private respond;
 }
 
-export { type HostContext, type HostHandlers, type RequestHandlers, VibeAppHost, type VibeAppHostOptions };
+export { type ContextPayload, type HostContext, type HostHandlers, type RequestHandlers, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };

package/dist/index.d.ts

@@ -3447,6 +3447,11 @@ interface VibeApiClientOptions {
 type HostHandlers = Omit<RequestHandlers, 'GET_CONTEXT'>;
 type HostContext = Omit<ContextPayload, 'hostVersion'>;
 interface VibeAppHostOptions {
+    /**
+     * Iframe origins allowed to talk to this host. Messages from any other origin
+     * are ignored, and context/pushes are only sent to these origins. Must match
+     * the Vibe App's origin exactly (e.g. `'https://my-vibe-app.lovable.app'`).
+     */
     trustedOrigins: string[];
     /** Returns the current context to send to the iframe on connect. */
     getContext: () => HostContext;
@@ -3455,8 +3460,44 @@ interface VibeAppHostOptions {
      * Used to sync the browser URL with the iframe's internal subroute.
      */
     appBasePath: string;
+    /**
+     * Points the built-in handler map at the Nominal API (e.g. nom-ui's proxy
+     * route). The host provides handlers for every protocol operation out of the
+     * box; this just tells them where to send requests. Defaults to
+     * `{ baseUrl: '', stripApiPrefix: false }`.
+     */
     clientConfig?: VibeApiClientOptions;
 }
+/**
+ * Host-side counterpart to `VibeAppBridge`. Construct it with the trusted
+ * iframe origin(s), a `getContext` callback, the app's base path, and a
+ * `clientConfig` pointing at the Nominal API; then call {@link VibeAppHost.mount}
+ * to start listening. The handler map for all protocol operations is built
+ * automatically — you do not pass handlers.
+ *
+ * @example
+ * ```tsx
+ * // In a React (nom-ui) component:
+ * const host = new VibeAppHost({
+ *   trustedOrigins: ['https://my-vibe-app.lovable.app'],
+ *   appBasePath: `/${tenant}/${subsidiary}/apps/${slug}`,
+ *   getContext: () => ({ tenant, subsidiaryId, subsidiaries, user, lastClosedPeriodSlug }),
+ *   clientConfig: { baseUrl: '/api/proxy', stripApiPrefix: true },
+ * })
+ *
+ * useEffect(() => {
+ *   const iframe = iframeRef.current
+ *   if (!iframe) return
+ *   const unmount = host.mount() // listen before the iframe loads
+ *   const onLoad = () => iframe.contentWindow && host.pushContextTo(iframe.contentWindow)
+ *   iframe.addEventListener('load', onLoad)
+ *   return () => {
+ *     iframe.removeEventListener('load', onLoad)
+ *     unmount()
+ *   }
+ * }, [host])
+ * ```
+ */
 declare class VibeAppHost {
     private readonly trustedOrigins;
     private readonly handlers;
@@ -3494,4 +3535,4 @@ declare class VibeAppHost {
     private respond;
 }
 
-export { type HostContext, type HostHandlers, type RequestHandlers, VibeAppHost, type VibeAppHostOptions };
+export { type ContextPayload, type HostContext, type HostHandlers, type RequestHandlers, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };

package/dist/index.js

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.0.1";
+var version = "0.1.0";
 
 // ../protocol-types/dist/index.js
 var PROTOCOL_ID = "nominal-vibe-bridge";

package/package.json

@@ -1,18 +1,8 @@
 {
   "name": "@nominalso/vibe-host",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Host-side SDK for embedding Nominal Vibe Apps — receives bridge requests over a typed postMessage protocol and dispatches them to Nominal APIs (used by nom-ui).",
   "license": "UNLICENSED",
-  "keywords": [
-    "nominal",
-    "vibe-apps",
-    "vibe-app",
-    "sdk",
-    "iframe",
-    "postmessage",
-    "host",
-    "embed"
-  ],
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",
   "bugs": {
     "url": "https://github.com/nominalso/vibe-apps-sdk/issues"