@nominalso/vibe-bridge 0.5.0 → 0.7.0

package/dist/index.browser.js

@@ -0,0 +1,1172 @@
+'use client';
+
+// ../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 BRIDGE_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@nominalso/vibe-bridge:BridgeError");
+var HTTP_BRIDGE_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@nominalso/vibe-bridge:HttpBridgeError");
+var BridgeError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BridgeError";
+  }
+  /**
+   * Cross-realm-safe type guard. Prefer this over `instanceof BridgeError` when
+   * an error may have been thrown by a differently-built copy of the SDK (e.g.
+   * server bundle vs client bundle) — it matches on a process-global brand
+   * rather than class identity.
+   */
+  static isBridgeError(err) {
+    return typeof err === "object" && err !== null && err[BRIDGE_ERROR_BRAND] === true;
+  }
+};
+Object.defineProperty(BridgeError.prototype, BRIDGE_ERROR_BRAND, {
+  value: true,
+  enumerable: false
+});
+var HttpBridgeError = class extends BridgeError {
+  constructor(status, message) {
+    super("REQUEST_FAILED", message);
+    this.status = status;
+    this.name = "HttpBridgeError";
+  }
+  /**
+   * Cross-realm-safe type guard (see {@link BridgeError.isBridgeError}). Returns
+   * `true` only for `HttpBridgeError` instances, not plain `BridgeError`s.
+   */
+  static isHttpBridgeError(err) {
+    return typeof err === "object" && err !== null && err[HTTP_BRIDGE_ERROR_BRAND] === true;
+  }
+};
+Object.defineProperty(HttpBridgeError.prototype, HTTP_BRIDGE_ERROR_BRAND, {
+  value: true,
+  enumerable: false
+});
+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;
+}
+
+// package.json
+var version = "0.7.0";
+
+// src/version.ts
+var BRIDGE_VERSION = version;
+
+// 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);
+  }
+};
+
+// src/timeouts.ts
+var CONNECT_TIMEOUT_MS = 1e4;
+var CONNECT_POLL_MS = 500;
+var DEFAULT_TIMEOUTS = {
+  /** Typed Nominal API reads/writes (`GET_*` / `POST_*` / `CREATE_*` / ...). */
+  api: 3e4,
+  /** `INVALIDATE_CACHE`. */
+  invalidate: 1e4,
+  /** `UPLOAD_FILE` — large payloads + presigned S3 PUT take a while. */
+  upload: 12e4
+};
+function resolveRequestTimeout(type, requestTimeout) {
+  if (requestTimeout !== void 0) return requestTimeout;
+  switch (type) {
+    case "UPLOAD_FILE":
+      return DEFAULT_TIMEOUTS.upload;
+    case "INVALIDATE_CACHE":
+      return DEFAULT_TIMEOUTS.invalidate;
+    default:
+      return DEFAULT_TIMEOUTS.api;
+  }
+}
+
+// src/VibeAppBridge.ts
+function resolvePosthog(mod) {
+  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 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) {
+  return PREVIEW_HOST_RE.test(hostname);
+}
+function resolveActualParentOrigin() {
+  if (typeof window === "undefined") return null;
+  try {
+    const ancestors = window.location.ancestorOrigins;
+    if (ancestors && ancestors.length > 0 && ancestors[0]) return ancestors[0];
+  } catch {
+  }
+  try {
+    if (document.referrer) return new URL(document.referrer).origin;
+  } catch {
+  }
+  return null;
+}
+function resolveOriginPolicy(configured) {
+  if (typeof window !== "undefined") {
+    const override = window[PARENT_ORIGIN_OVERRIDE_KEY];
+    if (typeof override === "string" && override.length > 0) {
+      console.log(`[vibe-bridge] Using dev-bridge parentOrigin override: ${override}`);
+      return { targetOrigin: override, isTrusted: (o) => o === override };
+    }
+  }
+  const rawList = configured === void 0 ? [] : Array.isArray(configured) ? configured : [configured];
+  const allowlist = rawList.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  if (allowlist.length === 0) {
+    const actual2 = resolveActualParentOrigin();
+    if (actual2) return { targetOrigin: actual2, isTrusted: (o) => o === actual2 };
+    console.warn(
+      "[vibe-bridge] No `parentOrigin` set and the embedding host could not be auto-detected (no ancestorOrigins/referrer). Pass `parentOrigin` explicitly."
+    );
+    return { targetOrigin: null, isTrusted: () => false };
+  }
+  const exactEntries = allowlist.filter((entry) => !isOriginPattern(entry));
+  const hasPatterns = exactEntries.length !== allowlist.length;
+  if (allowlist.length === 1 && !hasPatterns) {
+    const only = allowlist[0];
+    return { targetOrigin: only, isTrusted: (o) => o === only };
+  }
+  const allowPatterns = hasPatterns && typeof window !== "undefined" && isPreviewSelfHost(window.location.hostname);
+  const isTrusted = (o) => isOriginAllowed(o, allowlist, { allowPatterns });
+  const actual = resolveActualParentOrigin();
+  let targetOrigin = null;
+  if (actual && isTrusted(actual)) {
+    targetOrigin = actual;
+  } else if (actual === null && !allowPatterns && exactEntries.length === 1) {
+    targetOrigin = exactEntries[0];
+  }
+  if (targetOrigin === null) {
+    console.warn(
+      "[vibe-bridge] Could not resolve a parent origin to post to. Check `parentOrigin` against the embedding host" + (hasPatterns && !allowPatterns ? " \u2014 pattern entries are ignored because this page is not served from a recognised preview host." : ".")
+    );
+  }
+  return { targetOrigin, isTrusted };
+}
+var VibeAppBridge = class extends BridgeDataMethods {
+  /**
+   * 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()`.
+     * Guards against a double-init and makes {@link track} a no-op until
+     * 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;
+    this.onContextReceived = null;
+    /** Rejects an in-flight connect() (used by destroy()); `null` once settled. */
+    this.rejectConnect = null;
+    /**
+     * Persistent subscriber for post-connect context changes (tenant/subsidiary
+     * switch, period close, …). Distinct from {@link onContextReceived}, which only
+     * resolves the connect handshake and is cleared afterward. `null` until
+     * {@link onContextChange} is called.
+     */
+    this.contextChangeCallback = null;
+    /**
+     * Persistent subscriber for host auth changes (Nominal logout or
+     * identity/tenant switch). `null` until {@link onAuthChange} is called.
+     */
+    this.authChangeCallback = null;
+    this.lastReportedSubroute = null;
+    this.suppressSubrouteReport = false;
+    this.subrouteCallback = null;
+    this.origPushState = null;
+    this.origReplaceState = null;
+    this.popstateHandler = null;
+    this.kindHandlers = {
+      response: (msg) => this.handleResponse(msg),
+      push: (msg) => this.dispatchPush(msg),
+      progress: (msg) => this.handleProgress(msg)
+    };
+    this.pushHandlers = {
+      CONTEXT_PUSH: (payload) => {
+        if (this.onContextReceived) {
+          this.onContextReceived(payload);
+        } else if (this.context) {
+          this.context = payload;
+          this.contextChangeCallback?.(payload);
+        }
+      },
+      // 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. 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),
+      SUBROUTE_PUSH: (payload) => {
+        const safe = normalizeSubroute(payload.subroute);
+        if (!safe) return;
+        this.withSubrouteSuppressed(() => {
+          if (this.subrouteCallback) {
+            this.subrouteCallback(safe);
+          } else {
+            history.pushState(null, "", safe);
+            window.dispatchEvent(new PopStateEvent("popstate"));
+          }
+          this.lastReportedSubroute = safe;
+        });
+      }
+    };
+    /**
+     * Commands targeting the host's UI chrome. All fire-and-forget.
+     *
+     * @example
+     * ```ts
+     * bridge.ui.setSideNav({ collapsed: true })
+     * bridge.ui.switchSubsidiary(42)
+     * ```
+     */
+    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 });
+      }
+    };
+    this.parentOriginOption = options.parentOrigin;
+    this.requestTimeout = options.requestTimeout;
+    this.boundHandleMessage = this.handleMessage.bind(this);
+  }
+  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.
+   *
+   * 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 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()
+   * // ctx.tenant, ctx.subsidiaryId, ctx.subsidiaries, ctx.user, ctx.lastClosedPeriodSlug
+   * ```
+   */
+  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(
+          "PARENT_ORIGIN_UNRESOLVED",
+          "Could not resolve a parent origin to connect to. Check `parentOrigin` against the embedding host."
+        )
+      );
+    }
+    this.connectPromise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.stopConnectPolling();
+        this.connectPromise = null;
+        this.onContextReceived = null;
+        this.rejectConnect = null;
+        reject(new BridgeError("TIMEOUT", "Bridge connect timed out"));
+      }, CONNECT_TIMEOUT_MS);
+      this.connectTimeout = timer;
+      this.rejectConnect = (error) => {
+        clearTimeout(timer);
+        this.stopConnectPolling();
+        this.connectPromise = null;
+        this.onContextReceived = null;
+        this.rejectConnect = null;
+        reject(error);
+      };
+      this.onContextReceived = (ctx) => {
+        clearTimeout(timer);
+        this.stopConnectPolling();
+        this.context = ctx;
+        this.connectPromise = null;
+        this.onContextReceived = null;
+        this.rejectConnect = null;
+        console.log(
+          `[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 !== "/") {
+          this.withSubrouteSuppressed(() => {
+            history.replaceState(null, "", initialSubroute);
+            window.dispatchEvent(new PopStateEvent("popstate"));
+            this.lastReportedSubroute = initialSubroute;
+          });
+        } else {
+          this.lastReportedSubroute = window.location.pathname + window.location.search;
+        }
+        this.setupNavigationTracking();
+        this.warnMissingListeners();
+        resolve(ctx);
+      };
+      const sendConnect = () => {
+        this.sendCommand("CONNECT", { bridgeVersion: BRIDGE_VERSION });
+      };
+      sendConnect();
+      this.connectPollInterval = setInterval(sendConnect, CONNECT_POLL_MS);
+    });
+    return this.connectPromise;
+  }
+  /**
+   * Manually reports the current subroute to the host.
+   * Usually not needed — navigation is auto-detected via the history API.
+   * 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;
+    this.sendCommand("REPORT_SUBROUTE", { subroute: normalized, replace: options?.replace });
+  }
+  /**
+   * Registers a callback for host-initiated navigation (browser back/forward).
+   * 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;
+    return () => {
+      this.subrouteCallback = null;
+    };
+  }
+  /**
+   * Subscribes to post-connect context changes (tenant/subsidiary switch, period
+   * close, …). The callback fires for each {@link ContextPayload} the host pushes
+   * *after* connect — not for the initial context, which {@link connect} already
+   * 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;
+    return () => {
+      this.contextChangeCallback = null;
+    };
+  }
+  /**
+   * Subscribes to host auth changes: a Nominal logout (`authenticated: false` —
+   * sign your backend out) or an identity/tenant switch (`authenticated: true`
+   * with a new `userId`/`tenant` — re-authenticate). Fires for each change the
+   * host pushes after connect. Returns an unsubscribe function. Single
+   * subscriber: a second call replaces the first.
+   *
+   * **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). Pure — only stores the callback.
+   */
+  onAuthChange(callback) {
+    this.authChangeCallback = callback;
+    return () => {
+      this.authChangeCallback = null;
+    };
+  }
+  /**
+   * At connect, nudge the app if it hasn't wired the change listeners: every
+   * embedded app should react to a Nominal logout ({@link onAuthChange}) and a
+   * tenant/subsidiary switch ({@link onContextChange}). Fires once during the
+   * connect flow (not speculatively later), so wire both **before** `connect()`.
+   * The skill/codegen does this by default; this catches hand-wired apps.
+   */
+  warnMissingListeners() {
+    if (!this.authChangeCallback) {
+      console.warn(
+        "[vibe-bridge] connected without onAuthChange \u2014 the app will not sign out on Nominal logout or react to an identity/tenant switch. Call bridge.onAuthChange() before connect()."
+      );
+    }
+    if (!this.contextChangeCallback) {
+      console.warn(
+        "[vibe-bridge] connected without onContextChange \u2014 the app will not react to a tenant/subsidiary/period switch. Call bridge.onContextChange() before connect()."
+      );
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Host navigation & UI commands
+  //
+  // These drive the *host* (nom-ui) chrome — its router, side nav, and
+  // subsidiary switcher — rather than the iframe's own internal routing
+  // (`reportSubroute`). Navigation/UI commands are fire-and-forget;
+  // `invalidateCache` is awaited.
+  // ---------------------------------------------------------------------------
+  /**
+   * Navigates the host to a raw path relative to this app's tenant/subsidiary
+   * base. Fire-and-forget.
+   *
+   * @example
+   * ```ts
+   * bridge.navigate('/journal-entries/123')
+   * bridge.navigate('/journal-entries/123', 'replace')
+   * ```
+   */
+  navigate(path, action = "push") {
+    assertBrowser("navigate()");
+    this.sendCommand("NAVIGATE", { path, action });
+  }
+  /**
+   * Navigates the host to a named Nominal route, with optional params for
+   * placeholder segments. Fire-and-forget.
+   *
+   * @example
+   * ```ts
+   * bridge.navigateTo('CHART_OF_ACCOUNTS')
+   * bridge.navigateTo('JOURNAL_ENTRY', { id: '123' }, 'replace')
+   * ```
+   */
+  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" });
+  }
+  /**
+   * Asks the host to invalidate cached data by path prefix and/or cache tag so
+   * subsequent reads see fresh values. Awaited.
+   *
+   * @example
+   * ```ts
+   * await bridge.invalidateCache({ tags: ['SUBSIDIARIES'], paths: ['/accounting/accounts'] })
+   * ```
+   */
+  invalidateCache(payload) {
+    return this.request("INVALIDATE_CACHE", payload);
+  }
+  /**
+   * Captures a custom product event from inside the Vibe App, attributed to the
+   * same PostHog person as the host (via the `distinctId` the host supplied at
+   * connect).
+   *
+   * **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), 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
+   * iframe instance's `$session_id` rather than the host's — events tie to the
+   * same person, but cross-boundary event↔replay timeline correlation is a known
+   * limitation.
+   *
+   * @param event Event name. Namespacing app events (e.g. `'vibe:<slug>:<action>'`)
+   *   keeps them filterable from the host's own events.
+   * @param properties Optional event properties.
+   * @example
+   * ```ts
+   * bridge.track('vibe:fixed-assets:report_exported', { format: 'csv', rows: 128 })
+   * ```
+   */
+  track(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();
+    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;
+    this.contextChangeCallback = null;
+    this.authChangeCallback = null;
+    this.subrouteCallback = null;
+    this.lastReportedSubroute = null;
+  }
+  stopConnectPolling() {
+    if (this.connectPollInterval !== null) {
+      clearInterval(this.connectPollInterval);
+      this.connectPollInterval = null;
+    }
+    if (this.connectTimeout !== null) {
+      clearTimeout(this.connectTimeout);
+      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. 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.
+   */
+  async initPostHog(config) {
+    if (!config.enabled) return;
+    if (this.posthogInitialized || this.posthogIniting) return;
+    if (typeof window === "undefined") return;
+    if (!config.token || !config.apiHost || !config.distinctId) {
+      console.warn(
+        "[vibe-bridge] PostHog enabled but token/apiHost/distinctId missing \u2014 skipping init."
+      );
+      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
+        person_profiles: "identified_only",
+        capture_pageview: false,
+        // the host owns pageviews; don't double-count
+        autocapture: false,
+        // opt-in events only, via track()
+        // Seed the host's session id so track() events share the host's
+        // $session_id and line up with the stitched replay. Replay stitching
+        // itself does not depend on this (recordCrossOriginIframes handles it).
+        ...config.sessionId ? { bootstrap: { sessionID: config.sessionId } } : {},
+        session_recording: {
+          recordCrossOriginIframes: true,
+          // REQUIRED so the parent receives our rrweb frames
+          // Mirror nom-ui's posture (PostHogProvider.tsx): unmask inputs for
+          // richer insight, but keep password fields masked.
+          maskAllInputs: false,
+          maskInputOptions: { password: true }
+        }
+      });
+      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 (so `window`/`history` are guaranteed present).
+   */
+  setupNavigationTracking() {
+    if (this.origPushState) return;
+    this.origPushState = history.pushState.bind(history);
+    this.origReplaceState = history.replaceState.bind(history);
+    const origPush = this.origPushState;
+    const origReplace = this.origReplaceState;
+    history.pushState = (...args) => {
+      origPush(...args);
+      this.reportCurrentSubroute(false);
+    };
+    history.replaceState = (...args) => {
+      origReplace(...args);
+      this.reportCurrentSubroute(true);
+    };
+    this.popstateHandler = () => this.reportCurrentSubroute(true);
+    window.addEventListener("popstate", this.popstateHandler);
+  }
+  teardownNavigationTracking() {
+    if (this.origPushState) {
+      history.pushState = this.origPushState;
+      this.origPushState = null;
+    }
+    if (this.origReplaceState) {
+      history.replaceState = this.origReplaceState;
+      this.origReplaceState = null;
+    }
+    if (this.popstateHandler) {
+      window.removeEventListener("popstate", this.popstateHandler);
+      this.popstateHandler = null;
+    }
+  }
+  /** Runs `fn` while suppressing subroute auto-reporting to prevent echo loops. */
+  withSubrouteSuppressed(fn) {
+    this.suppressSubrouteReport = true;
+    try {
+      fn();
+    } finally {
+      this.suppressSubrouteReport = false;
+    }
+  }
+  reportCurrentSubroute(replace) {
+    if (this.suppressSubrouteReport) return;
+    const subroute = normalizeSubroute(window.location.pathname + window.location.search);
+    if (subroute === null) return;
+    if (subroute === this.lastReportedSubroute) return;
+    this.lastReportedSubroute = subroute;
+    this.sendCommand("REPORT_SUBROUTE", { subroute, replace });
+  }
+  sendCommand(type, payload) {
+    this.ensureAttached();
+    this.postToParent({
+      __protocol: PROTOCOL_ID,
+      __version: PROTOCOL_VERSION,
+      kind: "command",
+      type,
+      payload
+    });
+  }
+  /**
+   * Low-level typed request for **any** operation in {@link RequestRegistry}.
+   * The named methods (e.g. {@link VibeAppBridge.getChartOfAccounts}) wrap this;
+   * use it directly for operations without a named method, or to pass an
+   * `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(
+        () => {
+          this.pendingRequests.delete(requestId);
+          reject(new BridgeError("TIMEOUT", `Vibe bridge request timed out: ${type}`));
+        },
+        resolveRequestTimeout(type, this.requestTimeout)
+      );
+      this.pendingRequests.set(requestId, {
+        resolve: (data) => {
+          clearTimeout(timer);
+          resolve(data);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+        onProgress
+      });
+      const message = {
+        __protocol: PROTOCOL_ID,
+        __version: PROTOCOL_VERSION,
+        kind: "request",
+        type,
+        requestId,
+        payload
+      };
+      this.postToParent(message);
+    });
+  }
+  /**
+   * Posts to the embedding host. No-op when no concrete target origin could be
+   * resolved (a config/embedding error) — `connect()` rejects fast in that case
+   * so calls never silently hang waiting on a timeout.
+   */
+  postToParent(message) {
+    if (this.targetOrigin === null) return;
+    window.parent.postMessage(message, this.targetOrigin);
+  }
+  handleMessage(event) {
+    if (!this.isTrustedOrigin(event.origin)) return;
+    if (!isBridgeMessage(event.data)) return;
+    this.kindHandlers[event.data.kind]?.(event.data);
+  }
+  handleResponse(msg) {
+    const pending = this.pendingRequests.get(msg.requestId);
+    if (!pending) return;
+    this.pendingRequests.delete(msg.requestId);
+    if (msg.ok) {
+      pending.resolve(msg.data);
+    } else if (msg.status !== void 0) {
+      pending.reject(new HttpBridgeError(msg.status, msg.error));
+    } else if (msg.code) {
+      pending.reject(new BridgeError(msg.code, msg.error));
+    } else {
+      pending.reject(new Error(msg.error));
+    }
+  }
+  handleProgress(msg) {
+    const pending = this.pendingRequests.get(msg.requestId);
+    pending?.onProgress?.(msg.payload);
+  }
+};
+export {
+  BRIDGE_VERSION,
+  BridgeError,
+  HttpBridgeError,
+  VibeAppBridge
+};
+//# sourceMappingURL=index.browser.js.map