@nominalso/vibe-bridge 0.5.0 → 0.7.0

package/dist/index.js

@@ -1,368 +1,15 @@
-// package.json
-var version = "0.5.0";
-
-// ../protocol-types/dist/index.js
-function normalizeSubroute(subroute) {
-  const normalized = subroute.startsWith("/") ? subroute : `/${subroute}`;
-  const path = normalized.split(/[?#]/)[0];
-  let decoded = path;
-  let prev;
-  do {
-    prev = decoded;
-    decoded = decoded.replace(/%25/gi, "%").replace(/%2e/gi, ".").replace(/%2f/gi, "/");
-  } while (decoded !== prev);
-  if (decoded.split("/").some((segment) => segment === "..")) return null;
-  return normalized;
-}
-var PROTOCOL_ID = "nominal-vibe-bridge";
-var PROTOCOL_VERSION = 2;
-var BRIDGE_KINDS = ["request", "response", "push", "command", "progress"];
-var CORRELATED_KINDS = ["request", "response", "progress"];
-var BRIDGE_KINDS_SET = new Set(BRIDGE_KINDS);
-var CORRELATED_KINDS_SET = new Set(CORRELATED_KINDS);
-function isBridgeMessage(data) {
-  if (typeof data !== "object" || data === null) return false;
-  const d = data;
-  if (d.__protocol !== PROTOCOL_ID) return false;
-  if (d.__version !== PROTOCOL_VERSION) return false;
-  if (typeof d.kind !== "string" || !BRIDGE_KINDS_SET.has(d.kind)) return false;
-  if (typeof d.type !== "string") return false;
-  if (CORRELATED_KINDS_SET.has(d.kind) && typeof d.requestId !== "string") return false;
-  return true;
-}
-var BridgeError = class extends Error {
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-    this.name = "BridgeError";
-  }
-};
-var HttpBridgeError = class extends BridgeError {
-  constructor(status, message) {
-    super("REQUEST_FAILED", message);
-    this.status = status;
-    this.name = "HttpBridgeError";
-  }
-};
-function isOriginPattern(entry) {
-  return entry.includes("*");
-}
-var patternCache = /* @__PURE__ */ new Map();
-function patternToRegExp(pattern) {
-  const cached = patternCache.get(pattern);
-  if (cached) return cached;
-  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const body = escaped.replace(/\\\*/g, "[^./:@?#\\s]+");
-  const compiled = new RegExp(`^${body}$`);
-  patternCache.set(pattern, compiled);
-  return compiled;
-}
-function matchesOrigin(origin, entry) {
-  if (!isOriginPattern(entry)) return origin === entry;
-  return patternToRegExp(entry).test(origin);
-}
-function isOriginAllowed(origin, allowlist, { allowPatterns }) {
-  for (const entry of allowlist) {
-    if (isOriginPattern(entry)) {
-      if (allowPatterns && matchesOrigin(origin, entry)) return true;
-    } else if (origin === entry) {
-      return true;
-    }
-  }
-  return false;
-}
-
-// src/VibeAppBridge.ts
-import posthogDefault from "posthog-js";
-
-// src/data-methods.ts
-var BridgeDataMethods = class {
-  // ---------------------------------------------------------------------------
-  // Operations — Accounting: chart of accounts
-  //
-  // Each method is a typed wrapper over `request('<OP>', payload)`. The payload
-  // and return types come straight from the Nominal API (`RequestRegistry`).
-  // For any operation without a named method, call `request('<OP>', payload)`.
-  // ---------------------------------------------------------------------------
-  /**
-   * Fetch the flat chart of accounts for a subsidiary.
-   *
-   * @example
-   * ```ts
-   * const ctx = await bridge.connect()
-   * const accounts = await bridge.getChartOfAccounts({
-   *   path: { subsidiary_id: ctx.subsidiaryId },
-   * })
-   * ```
-   */
-  getChartOfAccounts(payload) {
-    return this.request("GET_CHART_OF_ACCOUNTS", payload);
-  }
-  /** Fetch the chart of accounts as a hierarchical tree for a subsidiary. */
-  getCoaTree(payload) {
-    return this.request("GET_COA_TREE", payload);
-  }
-  /** Fetch a simplified flat chart of accounts for a subsidiary. */
-  getCoaFlatSimple(payload) {
-    return this.request("GET_COA_FLAT_SIMPLE", payload);
-  }
-  /** Fetch the flat chart of accounts grouped by account group. */
-  getCoaGrouped(payload) {
-    return this.request("GET_COA_GROUPED", payload);
-  }
-  /** Fetch a single chart-of-accounts account by id within a subsidiary. */
-  getCoaAccount(payload) {
-    return this.request("GET_COA_ACCOUNT", payload);
-  }
-  /** List the currencies available to a subsidiary's chart of accounts. */
-  getSubsidiaryAvailableCurrencies(payload) {
-    return this.request("GET_SUBSIDIARY_AVAILABLE_CURRENCIES", payload);
-  }
-  /** Fetch accounts at the tenant level. */
-  getAccounts(payload) {
-    return this.request("GET_ACCOUNTS", payload);
-  }
-  /** Fetch a single account by id. */
-  getAccount(payload) {
-    return this.request("GET_ACCOUNT", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Accounting: exchange rates
-  // ---------------------------------------------------------------------------
-  /** Fetch currency conversion rates for a currency. */
-  getConversionRates(payload) {
-    return this.request("GET_CONVERSION_RATES", payload);
-  }
-  /** Fetch the effective consolidation exchange rate. */
-  getEffectiveExchangeRate(payload) {
-    return this.request("GET_EFFECTIVE_EXCHANGE_RATE", payload);
-  }
-  /** Fetch the exchange-rate period covering a given input date. */
-  getExchangeRateByDate(payload) {
-    return this.request("GET_EXCHANGE_RATE_BY_DATE", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Accounting: dimensions
-  // ---------------------------------------------------------------------------
-  /** List accounting dimensions. */
-  getDimensions(payload) {
-    return this.request("GET_DIMENSIONS", payload);
-  }
-  /** List values for accounting dimensions. */
-  getDimensionValues(payload) {
-    return this.request("GET_DIMENSION_VALUES", payload);
-  }
-  /** List dimension values in hierarchical form. */
-  getDimensionValuesHierarchical(payload) {
-    return this.request("GET_DIMENSION_VALUES_HIERARCHICAL", payload);
-  }
-  /** List account assignments for a dimension/account pair. */
-  getDimensionAccountAssignments(payload) {
-    return this.request("GET_DIMENSION_ACCOUNT_ASSIGNMENTS", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Accounting: journal entries
-  // ---------------------------------------------------------------------------
-  /**
-   * Fetch journal entries for a subsidiary, optionally filtered by date range.
-   *
-   * @example
-   * ```ts
-   * const entries = await bridge.getJournalEntries({
-   *   path: { subsidiary_id: ctx.subsidiaryId },
-   *   query: { from_date: '2026-01-01', to_date: '2026-03-31' },
-   * })
-   * ```
-   */
-  getJournalEntries(payload) {
-    return this.request("GET_JOURNAL_ENTRIES", payload);
-  }
-  /** Fetch journal entry lines for a subsidiary. */
-  getJournalLines(payload) {
-    return this.request("GET_JOURNAL_LINES", payload);
-  }
-  /** Fetch a single journal entry by id within a subsidiary. */
-  getJournalEntry(payload) {
-    return this.request("GET_JOURNAL_ENTRY", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Activity: period instances
-  // ---------------------------------------------------------------------------
-  /** List accounting period instances. */
-  getPeriods(payload) {
-    return this.request("GET_PERIODS", payload);
-  }
-  /** Fetch a single period instance by id. */
-  getPeriodInstance(payload) {
-    return this.request("GET_PERIOD_INSTANCE", payload);
-  }
-  /** Fetch a period instance by its display slug (e.g. `"mar-2026"`). */
-  getPeriodInstanceBySlug(payload) {
-    return this.request("GET_PERIOD_INSTANCE_BY_SLUG", payload);
-  }
-  /** Fetch the close-progress breakdown for a period (by slug). */
-  getPeriodProgressBreakdown(payload) {
-    return this.request("GET_PERIOD_PROGRESS_BREAKDOWN", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Activity: activity definitions
-  // ---------------------------------------------------------------------------
-  /** List activity definitions. */
-  getActivityDefinitions(payload) {
-    return this.request("GET_ACTIVITY_DEFINITIONS", payload);
-  }
-  /** Fetch a single activity definition by id. */
-  getActivityDefinition(payload) {
-    return this.request("GET_ACTIVITY_DEFINITION", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Activity: activity instances
-  // ---------------------------------------------------------------------------
-  /** List activity instances. */
-  getActivityInstances(payload) {
-    return this.request("GET_ACTIVITY_INSTANCES", payload);
-  }
-  /** Fetch a single activity instance by id. */
-  getActivityInstance(payload) {
-    return this.request("GET_ACTIVITY_INSTANCE", payload);
-  }
-  /** Fetch an activity instance for a given period + activity definition. */
-  getActivityInstanceByPeriod(payload) {
-    return this.request("GET_ACTIVITY_INSTANCE_BY_PERIOD", payload);
-  }
-  /** List task instances for an activity instance. */
-  getActivityInstanceTasks(payload) {
-    return this.request("GET_ACTIVITY_INSTANCE_TASKS", payload);
-  }
-  /** List task instances for an activity in a given period. */
-  getActivityPeriodTasks(payload) {
-    return this.request("GET_ACTIVITY_PERIOD_TASKS", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Activity: task definitions
-  // ---------------------------------------------------------------------------
-  /** List task definitions. */
-  getTaskDefinitions(payload) {
-    return this.request("GET_TASK_DEFINITIONS", payload);
-  }
-  /** Fetch a single task definition by id. */
-  getTaskDefinition(payload) {
-    return this.request("GET_TASK_DEFINITION", payload);
-  }
-  /** Create a task definition. */
-  createTaskDefinition(payload) {
-    return this.request("CREATE_TASK_DEFINITION", payload);
-  }
-  /** Update a task definition by id. */
-  updateTaskDefinition(payload) {
-    return this.request("UPDATE_TASK_DEFINITION", payload);
-  }
-  /** Query task definitions by filter. */
-  getTaskDefinitionsByFilter(payload) {
-    return this.request("GET_TASK_DEFINITIONS_BY_FILTER", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Activity: task instances
-  // ---------------------------------------------------------------------------
-  /** List task instances. */
-  getTaskInstances(payload) {
-    return this.request("GET_TASK_INSTANCES", payload);
-  }
-  /** Fetch a single task instance by id. */
-  getTaskInstance(payload) {
-    return this.request("GET_TASK_INSTANCE", payload);
-  }
-  /**
-   * Submit a Close-Management task output. This is the **only write path** back
-   * into Nominal — Vibe Apps never write Nominal data directly.
-   *
-   * @example
-   * ```ts
-   * // `body` carries the task-specific output shape.
-   * await bridge.postTaskOutput({
-   *   path: { task_instance_id: 'task-1' },
-   *   body: {},
-   * })
-   * ```
-   */
-  postTaskOutput(payload) {
-    return this.request("POST_TASK_OUTPUT", payload);
-  }
-  /** Query task instances by filter. */
-  getTaskInstancesByFilter(payload) {
-    return this.request("GET_TASK_INSTANCES_BY_FILTER", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Audit trail
-  // ---------------------------------------------------------------------------
-  /** List audit-trail events. */
-  getAuditEvents(payload) {
-    return this.request("GET_AUDIT_EVENTS", payload);
-  }
-  /** List audit-trail events for a specific entity. */
-  getEntityAuditEvents(payload) {
-    return this.request("GET_ENTITY_AUDIT_EVENTS", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Period manager: fiscal calendars
-  // ---------------------------------------------------------------------------
-  /** List fiscal calendars for a subsidiary. */
-  getFiscalCalendars(payload) {
-    return this.request("GET_FISCAL_CALENDARS", payload);
-  }
-  /** Fetch a single fiscal calendar by id. */
-  getFiscalCalendar(payload) {
-    return this.request("GET_FISCAL_CALENDAR", payload);
-  }
-  // ---------------------------------------------------------------------------
-  // Operations — Tenancy
-  // ---------------------------------------------------------------------------
-  /** List subsidiaries for the tenant. */
-  getSubsidiaries(payload) {
-    return this.request("GET_SUBSIDIARIES", payload);
-  }
-  /** Fetch a single subsidiary by id. */
-  getSubsidiary(payload) {
-    return this.request("GET_SUBSIDIARY", payload);
-  }
-  /** List parent currencies for a subsidiary. */
-  getSubsidiaryParentCurrencies(payload) {
-    return this.request("GET_SUBSIDIARY_PARENT_CURRENCIES", payload);
-  }
-  /** List users for the tenant. */
-  getTenantUsers(payload) {
-    return this.request("GET_TENANT_USERS", payload);
-  }
-  /**
-   * Uploads a file through the host. Converts the `File` to an `ArrayBuffer`
-   * before sending — sandboxed iframes cannot pass `File` handles across
-   * windows. Resolves once Nominal has stored the file.
-   *
-   * @example
-   * ```ts
-   * const input = document.querySelector<HTMLInputElement>('#file')!
-   * const file = input.files![0]
-   * const result = await bridge.upload(file, {
-   *   entityType: 'JOURNAL_ENTRY',
-   *   entityId: '123',
-   *   onProgress: (p) => console.log(`${p.progress}%`),
-   * })
-   * // result.attachmentId, result.name
-   * ```
-   */
-  async upload(file, options) {
-    const buffer = await file.arrayBuffer();
-    const payload = {
-      buffer,
-      fileName: file.name,
-      fileType: file.type,
-      entityType: options.entityType,
-      entityId: options.entityId
-    };
-    const onProgress = options.onProgress ? (p) => options.onProgress(p) : void 0;
-    return this.request("UPLOAD_FILE", payload, onProgress);
-  }
-};
+import {
+  BRIDGE_VERSION,
+  BridgeDataMethods,
+  BridgeError,
+  HttpBridgeError,
+  PROTOCOL_ID,
+  PROTOCOL_VERSION,
+  isBridgeMessage,
+  isOriginAllowed,
+  isOriginPattern,
+  normalizeSubroute
+} from "./chunk-QAMP6I2C.js";
 
 // src/timeouts.ts
 var CONNECT_TIMEOUT_MS = 1e4;
@@ -389,13 +36,23 @@ function resolveRequestTimeout(type, requestTimeout) {
 
 // src/VibeAppBridge.ts
 function resolvePosthog(mod) {
-  let candidate = mod;
-  while (candidate && typeof candidate.init !== "function" && candidate.default) {
-    candidate = candidate.default;
-  }
-  return candidate;
+  const hasInit = (o) => typeof o?.init === "function";
+  const d1 = mod?.default;
+  if (hasInit(d1)) return d1;
+  const d2 = d1?.default;
+  if (hasInit(d2)) return d2;
+  if (hasInit(mod)) return mod;
+  return null;
+}
+function serverEnvError(method) {
+  return new BridgeError(
+    "SERVER_ENVIRONMENT",
+    `VibeAppBridge.${method} was called outside a browser (no \`window\`). The bridge only runs in the browser \u2014 call it from a client component or effect, not during SSR, in a React Server Component, or in a Worker.`
+  );
+}
+function assertBrowser(method) {
+  if (typeof window === "undefined") throw serverEnvError(method);
 }
-var posthog = resolvePosthog(posthogDefault);
 var PARENT_ORIGIN_OVERRIDE_KEY = "__NOM_VIBE_PARENT_ORIGIN__";
 var PREVIEW_HOST_RE = /(?:^|\.)(?:vercel\.app|lovable\.app|lovable\.dev|lovableproject\.com)$|^(?:localhost|127\.0\.0\.1)$/;
 function isPreviewSelfHost(hostname) {
@@ -455,9 +112,22 @@ function resolveOriginPolicy(configured) {
   return { targetOrigin, isTrusted };
 }
 var VibeAppBridge = class extends BridgeDataMethods {
-  constructor({ parentOrigin, requestTimeout } = {}) {
+  /**
+   * Stores options only — **pure and side-effect-free**. No `window`,
+   * `document`, `history`, `postMessage`, `crypto`, or `posthog-js` access
+   * happens here, so constructing a bridge is safe during SSR / in a Server
+   * Component / in a Worker. Browser wiring is deferred to {@link connect} /
+   * {@link attach}.
+   */
+  constructor(options = {}) {
     super();
+    /** Concrete origin to `postMessage` to, or `null` until resolved at {@link attach}. */
+    this.targetOrigin = null;
+    /** Validates an inbound `event.origin`; rejects everything until {@link attach}. */
+    this.isTrustedOrigin = () => false;
     this.pendingRequests = /* @__PURE__ */ new Map();
+    /** Whether {@link attach} has installed the message listener + resolved origin. */
+    this.attached = false;
     this.context = null;
     /**
      * Set once {@link initPostHog} has successfully called `posthog.init()`.
@@ -465,6 +135,16 @@ var VibeAppBridge = class extends BridgeDataMethods {
      * recording is actually live.
      */
     this.posthogInitialized = false;
+    /** The lazily-imported `posthog-js` singleton, once recording is initialized. */
+    this.posthogInstance = null;
+    /**
+     * Set for the duration of an in-flight {@link initPostHog} (which is async — it
+     * awaits `import('posthog-js')`). Serializes initialization so two overlapping
+     * `POSTHOG_PUSH`es can't both call `posthog.init()`.
+     */
+    this.posthogIniting = false;
+    /** So the "posthog-js not installed" warning is logged at most once. */
+    this.posthogUnavailableWarned = false;
     this.connectPromise = null;
     this.connectPollInterval = null;
     this.connectTimeout = null;
@@ -505,8 +185,12 @@ var VibeAppBridge = class extends BridgeDataMethods {
       },
       // Persistent (not nulled after connect): the host delivers PostHog once at
       // connect via its own push, and initPostHog is idempotent, so this can run
-      // whenever the message arrives, independent of how connect() resolved.
-      POSTHOG_PUSH: (payload) => this.initPostHog(payload),
+      // whenever the message arrives, independent of how connect() resolved. Fire
+      // and forget — initPostHog is async (lazy-imports posthog-js) and swallows
+      // its own errors.
+      POSTHOG_PUSH: (payload) => {
+        void this.initPostHog(payload);
+      },
       // Persistent: the host pushes auth changes (logout, identity/tenant
       // switch) at any time after connect.
       AUTH_CHANGED: (payload) => this.authChangeCallback?.(payload),
@@ -536,42 +220,72 @@ var VibeAppBridge = class extends BridgeDataMethods {
     this.ui = {
       /** Collapse or expand the host's side navigation. */
       setSideNav: (payload) => {
+        assertBrowser("ui.setSideNav()");
         this.sendCommand("SET_SIDE_NAV", payload);
       },
       /** Switch the host to a different subsidiary. */
       switchSubsidiary: (subsidiaryId) => {
+        assertBrowser("ui.switchSubsidiary()");
         this.sendCommand("SWITCH_SUBSIDIARY", { subsidiaryId });
       }
     };
-    const policy = resolveOriginPolicy(parentOrigin);
-    this.targetOrigin = policy.targetOrigin;
-    this.isTrustedOrigin = policy.isTrusted;
-    this.requestTimeout = requestTimeout;
+    this.parentOriginOption = options.parentOrigin;
+    this.requestTimeout = options.requestTimeout;
     this.boundHandleMessage = this.handleMessage.bind(this);
-    window.addEventListener("message", this.boundHandleMessage);
   }
   dispatchPush(msg) {
     const handler = this.pushHandlers[msg.type];
     handler(msg.payload);
   }
+  /**
+   * Installs the browser wiring: resolves the parent-origin policy and starts
+   * listening for host `postMessage`s. **Idempotent** and safe to call before
+   * {@link connect} if you want the bridge receiving pushes early; {@link
+   * connect} calls it for you, so most apps never call this directly.
+   *
+   * @throws `BridgeError` code `'SERVER_ENVIRONMENT'` if called where there is no
+   *   `window`.
+   */
+  attach() {
+    assertBrowser("attach()");
+    if (this.attached) return;
+    const policy = resolveOriginPolicy(this.parentOriginOption);
+    this.targetOrigin = policy.targetOrigin;
+    this.isTrustedOrigin = policy.isTrusted;
+    window.addEventListener("message", this.boundHandleMessage);
+    this.attached = true;
+  }
+  /**
+   * Lazily installs the browser wiring on first transport use. Keeps the
+   * constructor pure while ensuring that any method reaching the wire (a data
+   * `request`, a fire-and-forget command) works without an explicit prior
+   * `attach()`/`connect()` — attach stays idempotent, so `connect()` is
+   * unaffected.
+   */
+  ensureAttached() {
+    if (!this.attached) this.attach();
+  }
   /**
    * Connects to the host and returns the tenant/user {@link ContextPayload}.
    * **Call this once on app init and await it before any other method** — data
    * methods, `upload()`, and subroute reporting all require an established
    * connection. Concurrent calls return the same promise.
    *
-   * Sends a `CONNECT` handshake, re-sending every 500ms until the host replies
-   * by pushing the context (so it works even if the host mounts after the
-   * iframe loads). Context is only ever delivered by push. Rejects with `Bridge
-   * connect timed out` after 10 seconds if no context arrives (usually a
-   * `parentOrigin` mismatch or the host hasn't mounted).
+   * First {@link attach | attaches} the browser wiring (message listener +
+   * origin resolution), then sends a `CONNECT` handshake, re-sending every 500ms
+   * until the host replies by pushing the context (so it works even if the host
+   * mounts after the iframe loads). Context is only ever delivered by push.
+   * Rejects with `Bridge connect timed out` after 10 seconds if no context
+   * arrives (usually a `parentOrigin` mismatch or the host hasn't mounted).
    *
    * After connecting, if the context includes an initial subroute (e.g. from
    * a deep link), the bridge navigates to it and starts auto-tracking
    * internal navigation via the history API.
    *
    * @returns The tenant/user/subsidiary context for this app session.
-   * @throws If no context is received within 10 seconds.
+   * @throws Rejects with `BridgeError` code `'SERVER_ENVIRONMENT'` if called
+   *   where there is no `window`, `'PARENT_ORIGIN_UNRESOLVED'` if no embedding
+   *   origin could be resolved, or `'TIMEOUT'` if no context arrives in 10s.
    * @example
    * ```ts
    * const ctx = await bridge.connect()
@@ -579,8 +293,10 @@ var VibeAppBridge = class extends BridgeDataMethods {
    * ```
    */
   connect() {
+    if (typeof window === "undefined") return Promise.reject(serverEnvError("connect()"));
     if (this.context) return Promise.resolve(this.context);
     if (this.connectPromise) return this.connectPromise;
+    this.attach();
     if (this.targetOrigin === null) {
       return Promise.reject(
         new BridgeError(
@@ -614,7 +330,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
         this.onContextReceived = null;
         this.rejectConnect = null;
         console.log(
-          `[vibe-bridge] Connected \u2014 bridge: ${version}, host: ${ctx.hostVersion}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
+          `[vibe-bridge] Connected \u2014 bridge: ${BRIDGE_VERSION}, host: ${ctx.hostVersion}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
         );
         const initialSubroute = ctx.subroute ? normalizeSubroute(ctx.subroute) : null;
         if (initialSubroute && initialSubroute !== "/") {
@@ -631,7 +347,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
         resolve(ctx);
       };
       const sendConnect = () => {
-        this.sendCommand("CONNECT", { bridgeVersion: version });
+        this.sendCommand("CONNECT", { bridgeVersion: BRIDGE_VERSION });
       };
       sendConnect();
       this.connectPollInterval = setInterval(sendConnect, CONNECT_POLL_MS);
@@ -644,6 +360,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
    * Use this for hash-based routers or non-standard navigation patterns.
    */
   reportSubroute(subroute, options) {
+    assertBrowser("reportSubroute()");
     const normalized = normalizeSubroute(subroute);
     if (normalized === null) return;
     this.lastReportedSubroute = normalized;
@@ -654,6 +371,8 @@ var VibeAppBridge = class extends BridgeDataMethods {
    * If no callback is registered, the SDK uses `history.pushState` + a
    * `popstate` event, which works for most SPA routers automatically.
    * Returns an unsubscribe function.
+   *
+   * Pure — only stores the callback, so it is safe to call before {@link connect}.
    */
   onSubrouteRequest(callback) {
     this.subrouteCallback = callback;
@@ -668,6 +387,8 @@ var VibeAppBridge = class extends BridgeDataMethods {
    * returns. Returns an unsubscribe function. Single subscriber: a second call
    * replaces the first. Wire it **before {@link connect}** (the bridge warns at
    * connect if it isn't).
+   *
+   * Pure — only stores the callback, so it is safe to call before {@link connect}.
    */
   onContextChange(callback) {
     this.contextChangeCallback = callback;
@@ -684,7 +405,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
    *
    * **Wire this before {@link connect}** — without it the embedded app won't
    * sign out when the user logs out of Nominal (the bridge warns at connect if
-   * it isn't wired).
+   * it isn't wired). Pure — only stores the callback.
    */
   onAuthChange(callback) {
     this.authChangeCallback = callback;
@@ -730,6 +451,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
    * ```
    */
   navigate(path, action = "push") {
+    assertBrowser("navigate()");
     this.sendCommand("NAVIGATE", { path, action });
   }
   /**
@@ -743,10 +465,12 @@ var VibeAppBridge = class extends BridgeDataMethods {
    * ```
    */
   navigateTo(route, routeParams, action = "push") {
+    assertBrowser("navigateTo()");
     this.sendCommand("NAVIGATE", { route, routeParams, action });
   }
   /** Refreshes the host's current route (re-fetches its server data). Fire-and-forget. */
   refresh() {
+    assertBrowser("refresh()");
     this.sendCommand("NAVIGATE", { action: "refresh" });
   }
   /**
@@ -768,8 +492,9 @@ var VibeAppBridge = class extends BridgeDataMethods {
    *
    * **No-op until {@link connect} has resolved with PostHog enabled by the
    * host** — if the host didn't send a `posthog` block (older host, or recording
-   * disabled for this env/app), nothing is sent. App authors don't import
-   * `posthog-js` themselves; this is the supported event surface.
+   * disabled for this env/app), or `posthog-js` isn't installed (it is an
+   * optional dependency), nothing is sent. App authors don't import `posthog-js`
+   * themselves; this is the supported event surface.
    *
    * The event is sent **directly** from the iframe's own PostHog instance (only
    * the session *recording* is forwarded to the parent), so it carries the
@@ -786,20 +511,33 @@ var VibeAppBridge = class extends BridgeDataMethods {
    * ```
    */
   track(event, properties) {
-    if (!this.posthogInitialized) return;
-    posthog.capture(event, properties);
+    assertBrowser("track()");
+    if (!this.posthogInitialized || !this.posthogInstance) return;
+    this.posthogInstance.capture(event, properties);
   }
+  /**
+   * Tears down the bridge: stops the connect handshake, removes the message
+   * listener, restores patched history methods, and rejects any in-flight calls
+   * with a `'DESTROYED'` error. **Idempotent and safe on the server** — calling
+   * it when {@link connect}/{@link attach} never ran (or where there is no
+   * `window`) is a no-op, so it is safe as a React effect cleanup.
+   */
   destroy() {
     this.teardownNavigationTracking();
     this.rejectConnect?.(new BridgeError("DESTROYED", "Bridge destroyed"));
     this.stopConnectPolling();
-    window.removeEventListener("message", this.boundHandleMessage);
+    if (this.attached && typeof window !== "undefined") {
+      window.removeEventListener("message", this.boundHandleMessage);
+    }
+    this.attached = false;
     for (const pending of this.pendingRequests.values()) {
       pending.reject(new BridgeError("DESTROYED", "Bridge destroyed"));
     }
     this.pendingRequests.clear();
     this.context = null;
     this.posthogInitialized = false;
+    this.posthogInstance = null;
+    this.posthogIniting = false;
     this.connectPromise = null;
     this.onContextReceived = null;
     this.rejectConnect = null;
@@ -818,23 +556,34 @@ var VibeAppBridge = class extends BridgeDataMethods {
       this.connectTimeout = null;
     }
   }
+  warnPosthogUnavailable() {
+    if (this.posthogUnavailableWarned) return;
+    this.posthogUnavailableWarned = true;
+    console.warn(
+      "[vibe-bridge] The host enabled session recording but `posthog-js` is not installed (it is an optional dependency). Recording and track() are disabled. Run `npm i posthog-js` to enable them."
+    );
+  }
   /**
    * Initializes PostHog session recording + analytics from the host-supplied
    * config carried by a one-time `POSTHOG_PUSH`, **only when the host opted in**
    * (`config.enabled`).
    *
+   * `posthog-js` is an **optional dependency**, loaded lazily via `await
+   * import('posthog-js')` the first time recording is enabled — so it stays out
+   * of the import graph (and out of any server bundle) for apps that never
+   * record. If it isn't installed, this warns once and no-ops (never throws).
+   *
    * The host is the single source of truth: when it sends no `POSTHOG_PUSH`
    * (recording disabled for this env/app) or `enabled: false`, this does
-   * nothing — `enabled` is the kill-switch even though `posthog-js` is bundled
-   * into the bridge. Cross-origin replay needs `recordCrossOriginIframes` on both
-   * sides so the parent receives the iframe's rrweb frames into one stitched
-   * recording, and `identify()` ties the iframe's recording + events to the same
-   * person as the host. Idempotent (the `posthogInitialized` guard) and wrapped
-   * in try/catch so a duplicate push or a PostHog failure is harmless.
+   * nothing. Cross-origin replay needs `recordCrossOriginIframes` on both sides
+   * so the parent receives the iframe's rrweb frames into one stitched recording,
+   * and `identify()` ties the iframe's recording + events to the same person as
+   * the host. Idempotent (the `posthogInitialized` guard) and wrapped in
+   * try/catch so a duplicate push or a PostHog failure is harmless.
    */
-  initPostHog(config) {
+  async initPostHog(config) {
     if (!config.enabled) return;
-    if (this.posthogInitialized) return;
+    if (this.posthogInitialized || this.posthogIniting) return;
     if (typeof window === "undefined") return;
     if (!config.token || !config.apiHost || !config.distinctId) {
       console.warn(
@@ -842,7 +591,20 @@ var VibeAppBridge = class extends BridgeDataMethods {
       );
       return;
     }
+    this.posthogIniting = true;
     try {
+      let posthog;
+      try {
+        posthog = resolvePosthog(await import("posthog-js"));
+      } catch {
+        this.warnPosthogUnavailable();
+        return;
+      }
+      if (!posthog) {
+        this.warnPosthogUnavailable();
+        return;
+      }
+      if (!this.attached) return;
       posthog.init(config.token, {
         api_host: config.apiHost,
         // absolute ingestion host, NOT a relative /ingest proxy
@@ -865,16 +627,19 @@ var VibeAppBridge = class extends BridgeDataMethods {
         }
       });
       posthog.identify(config.distinctId);
+      this.posthogInstance = posthog;
       this.posthogInitialized = true;
       console.log("[vibe-bridge] PostHog session recording initialized");
     } catch (err) {
       console.warn("[vibe-bridge] PostHog init failed \u2014 continuing without recording.", err);
+    } finally {
+      this.posthogIniting = false;
     }
   }
   /**
    * Monkey-patches `history.pushState` and `history.replaceState` to
    * auto-detect SPA navigation and report it to the host. Called after
-   * connect() resolves.
+   * connect() resolves (so `window`/`history` are guaranteed present).
    */
   setupNavigationTracking() {
     if (this.origPushState) return;
@@ -925,6 +690,7 @@ var VibeAppBridge = class extends BridgeDataMethods {
     this.sendCommand("REPORT_SUBROUTE", { subroute, replace });
   }
   sendCommand(type, payload) {
+    this.ensureAttached();
     this.postToParent({
       __protocol: PROTOCOL_ID,
       __version: PROTOCOL_VERSION,
@@ -940,12 +706,18 @@ var VibeAppBridge = class extends BridgeDataMethods {
    * `onProgress` callback. `type` autocompletes to every operation name and
    * narrows `payload`/return to that operation's types.
    *
+   * @throws Rejects with `BridgeError` code `'SERVER_ENVIRONMENT'` if called
+   *   where there is no `window`.
    * @example
    * ```ts
    * const accounts = await bridge.request('GET_ACCOUNTS', { query: { account_ids: ['acc-1'] } })
    * ```
    */
   request(type, payload, onProgress) {
+    if (typeof window === "undefined") {
+      return Promise.reject(serverEnvError(`request(${String(type)})`));
+    }
+    this.ensureAttached();
     return new Promise((resolve, reject) => {
       const requestId = crypto.randomUUID();
       const timer = setTimeout(
@@ -1011,8 +783,9 @@ var VibeAppBridge = class extends BridgeDataMethods {
   }
 };
 export {
-  version as BRIDGE_VERSION,
+  BRIDGE_VERSION,
   BridgeError,
   HttpBridgeError,
   VibeAppBridge
 };
+//# sourceMappingURL=index.js.map