@ada-cx/messaging-bridge 1.0.0-setup.0 → 1.0.0

package/README.md

@@ -2,18 +2,26 @@
 
 Build your own chat UI (a "custom app") on Ada Messaging's bridge contract.
 
-This package carries TypeScript types, test mocks, and a thin loader. The
-bridge runtime always loads from Ada's CDN at
-`https://messaging-assets.ada.support/bridge.js`. Ada patches the runtime
-continuously, so your installed package version never pins security logic.
+This package carries TypeScript types, test mocks, and a thin loader.
+
+Ada core stamps its build identifier into your app frame's `window.name`. The loader uses it to load the matching bridge runtime.
+
+Your installed package never contains the runtime. Ada can update runtime security logic through a coordinated core release.
 
 ## Requirements
 
 - Your custom app runs inside an iframe that Ada's core frame mounts. The
   core frame is served from Ada's asset host, and it sits inside the page
   that embeds the widget. Both origins are in your app's ancestor chain.
-- You point the Web SDK at your app with its `appUrl` setting. Custom apps
-  are experimental. Contact your Ada team before you build on this feature.
+- You point the Web SDK at your app with its `appUrl` setting.
+- Your app's origin must be in your handle's **Allowed websites** list. Add
+  it in your Ada dashboard, under **Channels** > **Chat**. Until the list
+  allows your origin, a configured `appUrl` is dropped with a console
+  warning and Ada's default app mounts (with `appUrlFallback: false` the
+  activation fails instead). An entry that carries a path, query, or
+  fragment does not authorize a custom app. Add the bare origin as its own
+  entry. Local development needs no entry when both your app and the
+  embedding page run on loopback hosts.
 - If your app's responses send no `X-Frame-Options` header and no CSP
   `frame-ancestors` directive, browsers permit framing, and no server change
   is needed. If your app restricts framing, `frame-ancestors` must allow
@@ -155,64 +163,47 @@ anchors.
 
 | Option | Default | Purpose |
 | --- | --- | --- |
-| `cdnBase` | `https://messaging-assets.ada.support` | Asset origin for `bridge.js`. Must be an `https` URL. Plain `http` works only for loopback hosts such as `localhost` during local development. Override only for staging validation. |
-| `pinBuildSha` | none | Full 40-character git SHA of a deployed CDN build. Loads that build's immutable copy instead of the current root asset. Not recommended for production. See [Pin the CDN build](#pin-the-cdn-build). |
+| `cdnBase` | `https://messaging-assets.ada.support` | Asset origin for immutable bridge builds. It must use HTTPS. Plain HTTP works only for loopback development. Override it only when your Ada team directs you to during a joint validation. |
+
+### Frame-only asset URL resolution
+
+`resolveBridgeCdnUrl()` returns the bridge asset URL selected for the current custom app frame.
+It uses the same validation as `loadMessagingBridge()`.
+
+This helper is frame-only. It throws a `MessagingBridgeLoadError` outside an Ada-mounted custom app frame.
+Call it after your app starts inside that frame. Do not evaluate it at module scope in code that also runs elsewhere.
 
 Errors: `loadMessagingBridge` rejects with a `MessagingBridgeLoadError`. Its
 `code` property identifies the failure:
 
 | Code | Meaning |
 | --- | --- |
-| `invalid_cdn_base` | The `cdnBase` option is not a valid `https` URL. |
-| `invalid_build_sha` | The `pinBuildSha` option is not a full 40-character hex git SHA. |
-| `unstamped_build_sha` | The `pinBuildSha` option is the unstamped placeholder from a repository build. |
+| `invalid_cdn_base` | The `cdnBase` option violates the HTTPS or loopback HTTP policy. |
+| `missing_build_sha` | The frame's `window.name` carries no core build marker, or the mounting core predates build-marker delivery. |
+| `invalid_build_sha` | The frame-name marker matches no accepted build identifier form. |
+| `dev_marker_not_loopback` | The frame uses the `dev` marker with a non-loopback asset host. |
 | `bridge_import_failed` | The asset failed to load (network, CSP, 404). |
 | `bridge_module_invalid` | The loaded module is not an Ada bridge build. |
 
-### Pin the CDN build
+### Matching the core build
 
-The package exports `CDN_BUILD_SHA`. The value is the git commit SHA of the
-monorepo commit this npm version was published from. Ada deploys each
-commit's bridge runtime as an immutable SHA-rooted copy on the CDN. The
-value therefore names the CDN build associated with this npm version.
+Ada core mounts your frame with `window.name` set to `ada-custom-app:<build identifier>` before your app code runs. Your URL and its fragment mount untouched, so hash routes keep working.
 
-Pass the SHA as the `pinBuildSha` loader option. The loader then skips the
-root `bridge.js` asset and imports that build's immutable copy,
-`<cdnBase>/<sha>/bridge/bridge.js`, directly:
+| Marker | Meaning | Resolved asset |
+| --- | --- | --- |
+| A bare 40-character hexadecimal SHA | An immutable production build. | `<cdnBase>/<sha>/bridge/bridge.js` |
+| Lowercase `pr-<N>` | An Ada-internal preview build. | `<cdnBase>/pr-<N>/bridge/bridge.js` |
+| `dev` | An Ada-internal local core build. Customer pages never receive this marker. | `<cdnBase>/bridge/bridge.js` on loopback only. |
 
-```ts
-import {
-  CDN_BUILD_SHA,
-  isCdnBuildShaStamped,
-  loadMessagingBridge,
-} from "@ada-cx/messaging-bridge";
-
-if (isCdnBuildShaStamped()) {
-  await loadMessagingBridge({ pinBuildSha: CDN_BUILD_SHA });
-}
-```
+The loader accepts only these marker shapes. It never accepts a URL or path from the frame name.
 
-**Pinning is not recommended for production.** A pinned runtime misses Ada's
-fixes and the loader-fence rollout. A pinned runtime can also predate later
-core or server contract changes and stop working. Use a pin only to debug an
-issue, to validate a staged build, or to reproduce a report against a known
-runtime.
+The loader snapshots `window.name` when your app first evaluates the package, through either entry: `@ada-cx/messaging-bridge` or `@ada-cx/messaging-bridge/react`. Keep that import in a module your page evaluates at startup. A route-level code split evaluates too late. Code that runs first, for example a library that uses `window.name`, could overwrite the name. If the route that renders `AdaBridgeProvider` is lazily loaded, add a bare `import "@ada-cx/messaging-bridge";` to your entry module. The loader keeps the snapshot value if code overwrites `window.name` later.
 
-The option accepts any full 40-character hex git SHA of a deployed main
-build. The loader rejects any other value with the `invalid_build_sha` error
-code. Only published packages carry a real SHA. In the repository, and in a
-locally built copy, `CDN_BUILD_SHA` is a 40-zero placeholder and
-`isCdnBuildShaStamped()` returns `false`. The loader rejects the placeholder
-with the `unstamped_build_sha` error code.
+Do not persist or replay the frame-name marker. Core supplies the authoritative value for every frame load.
 
-The npm publish and the CDN deploy of the same commit run in parallel. In
-the first minutes after a release, a pin can fail with
-`bridge_import_failed` until the deploy completes. If the deploy of that
-commit failed, the pinned build never exists. The unpinned default is
-unaffected in both cases.
+Do not set or change `window.name`. The loader fails closed when your page runs outside an Ada-mounted custom app frame.
 
-`pinBuildSha` composes with `cdnBase`. The pinned copy resolves under the
-asset host you pass.
+The `dev` marker and PR preview aliases are Ada-internal workflows. Local Ada core builds stamp `ada-custom-app:dev`, which works only with a loopback `cdnBase`. An Ada preview core selects its matching preview bridge automatically. You do not need a `cdnBase` override for a joint validation when the page loads `sdk.js` from the production asset root. A preview alias against an asset host that lacks the preview fails closed.
 
 ## React
 
@@ -241,6 +232,13 @@ function MyChatUi() {
 }
 ```
 
+If your app lazily loads the route that renders `AdaBridgeProvider`, add a
+bare `import "@ada-cx/messaging-bridge";` to your entry module. The loader
+then snapshots the frame name at startup, before other code can overwrite
+`window.name`. A statically imported `createBridgeProvider` already evaluates
+the loader through a used binding; the bare import matters only when that
+import itself lives in a lazily loaded chunk.
+
 The provider accepts two more props for load failures. `errorFallback`
 renders when the runtime fails to load. `onError` receives the
 `MessagingBridgeLoadError`. Without them, the provider logs the error and
@@ -312,8 +310,9 @@ await handle.settled();
   pinned to your first document, so your app must not navigate or reload its
   own frame. A navigation disconnects the bridge permanently.
 - The runtime detects the custom-app frame by the frame name core sets
-  (`ada-custom-app`), or by an opaque origin under older core builds. Do not
-  change `window.name` inside your app document.
+  (`ada-custom-app:<build identifier>`), which also selects the bridge
+  build the loader imports. Do not change `window.name` inside your app
+  document.
 - The custom-app frame keeps your real origin, so your own cookies and
   storage work inside it. Browsers partition third-party storage by the
   embedding site. Cookies need `Partitioned; Secure; SameSite=None`.

package/{dist → dist-npm/contract}/bridge-client.d.ts

@@ -50,11 +50,11 @@ export interface BridgeClient {
 /**
  * Create a {@link BridgeClient} bound to the parent core frame.
  *
- * Declaration only (D21 dependency inversion): the implementation lives in
- * the private `packages/bridge-runtime` workspace and ships exclusively as
- * the CDN asset `bridge.js` — obtain it through `loadMessagingBridge()`.
- * The runtime compiles against this signature (`MessagingBridgeModule` is
- * pinned both ways by bridge-runtime's `cdn-contract.ts`), so the published
+ * Declaration only: the implementation lives in this package's private
+ * runtime source and ships exclusively as the CDN asset `bridge.js`.
+ * Obtain it through `loadMessagingBridge()`. The runtime compiles against
+ * this signature (`MessagingBridgeModule` is pinned both ways by
+ * `runtime/cdn-contract.ts`), so the published
  * type can never drift from the CDN implementation.
  *
  * Security model: the core origin is derived from `document.referrer` when

package/{dist → dist-npm/contract}/derive.d.ts

@@ -5,11 +5,10 @@ import type { AppDisplayState, Message } from "./types.js";
  * so a custom app does not have to rediscover the edge cases the hard way.
  * No DOM, no client: every helper is a pure function of state or messages.
  *
- * Declarations only (D21 dependency inversion): the implementations live in
- * the private `packages/bridge-runtime` workspace and ship exclusively on
- * the CDN runtime, typed on `MessagingBridgeModule`. The runtime compiles
- * against these signatures (pinned both ways by bridge-runtime's
- * `cdn-contract.ts`), so the published types cannot drift from the CDN
+ * Declarations only: the implementations live in `src/runtime` and ship
+ * exclusively on the CDN runtime, typed on `MessagingBridgeModule`. The
+ * runtime compiles against these signatures (pinned both ways by
+ * `runtime/cdn-contract.ts`), so the published types cannot drift from the CDN
  * implementation.
  */
 /**

package/{dist → dist-npm/contract}/operations.d.ts

@@ -257,7 +257,15 @@ export interface BridgeOperations {
      * that predates the seq, falls back to the `pending -> terminal` edge.
      * The email is trimmed; an empty result rejects immediately without
      * sending (core drops an empty email silently, so nothing would ever
-     * settle it).
+     * settle it). The request is single-flight and address-aware: a call for
+     * the SAME address as an in-flight request joins it and settles on its
+     * verdict; a call for a DIFFERENT address is rejected address-matched on
+     * `transcript.email.conflict.*` — ONLY the conflicting call's promise
+     * rejects, while the in-flight request still completes, writes the final
+     * status, and settles its own handle with the true outcome (a rejection
+     * here never means the in-flight email was not sent). On a core document
+     * that predates the conflict channel, a conflicting call settles on the
+     * in-flight verdict instead.
      */
     emailTranscript(email: string, opts?: SettleOptions): Promise<void>;
     /**

package/{dist → dist-npm/contract}/state-keys.d.ts

@@ -1,5 +1,5 @@
 /**
- * Typed constants for all bridge state keys.
+ * Typed contract constants for all bridge state keys.
  *
  * Using these constants prevents silent typos — a misspelled string literal
  * compiles without error but returns `undefined` at runtime.

package/{dist → dist-npm/contract}/types.d.ts

@@ -1,6 +1,6 @@
-import type { CsatFeedbackOption, CsatSurveySettings, FileUploadErrorData } from "./shared-utils/index.js";
+import type { CsatFeedbackOption, CsatSurveySettings, FileUploadErrorData } from "../shared-utils/index.js";
 /**
- * Bridge type definitions describing the state and events that flow between
+ * Bridge contract definitions describing the state and events that flow between
  * the messaging core frame and the display layer (app or native WebView).
  *
  * These types are the source of truth for the `@ada-cx/messaging-bridge`
@@ -374,6 +374,16 @@ export interface AppDisplayState {
      * edge never appears — correlate on this advancing to a terminal status
      * instead. Optional: absent on a core document that predates it. */
     "transcript.email.status.seq"?: number;
+    /** The trimmed address of the most recently rejected CONFLICTING email
+     * request — an `emailTranscript` for a DIFFERENT address while one was in
+     * flight. Its own channel: `emailTranscript` rejects on this advancing
+     * with ITS address, so only the conflicting caller rejects while the
+     * in-flight request settles on its own status. Optional: absent on a core
+     * document that predates it (there a conflicting caller settles on the
+     * in-flight verdict instead). */
+    "transcript.email.conflict.email"?: string | null;
+    /** Advances on every `transcript.email.conflict.email` write. */
+    "transcript.email.conflict.seq"?: number;
     /** Same lifecycle as `transcript.email.status`, for
      * `settings.transcript.download.request`. */
     "transcript.download.status": "idle" | "pending" | "success" | "error";

package/dist-npm/loader-CfCnvaTU.js

@@ -0,0 +1,197 @@
+//#region \0@oxc-project+runtime@0.122.0/helpers/typeof.js
+function _typeof(o) {
+	"@babel/helpers - typeof";
+	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
+		return typeof o;
+	} : function(o) {
+		return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+	}, _typeof(o);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.122.0/helpers/toPrimitive.js
+function toPrimitive(t, r) {
+	if ("object" != _typeof(t) || !t) return t;
+	var e = t[Symbol.toPrimitive];
+	if (void 0 !== e) {
+		var i = e.call(t, r || "default");
+		if ("object" != _typeof(i)) return i;
+		throw new TypeError("@@toPrimitive must return a primitive value.");
+	}
+	return ("string" === r ? String : Number)(t);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.122.0/helpers/toPropertyKey.js
+function toPropertyKey(t) {
+	var i = toPrimitive(t, "string");
+	return "symbol" == _typeof(i) ? i : i + "";
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.122.0/helpers/defineProperty.js
+function _defineProperty(e, r, t) {
+	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
+		value: t,
+		enumerable: !0,
+		configurable: !0,
+		writable: !0
+	}) : e[r] = t, e;
+}
+//#endregion
+//#region src/npm/loader.ts
+var DEFAULT_CDN_BASE = "https://messaging-assets.ada.support";
+var CUSTOM_APP_FRAME_NAME = "ada-custom-app";
+var BRIDGE_ENTRY_PATH = "bridge/bridge.js";
+var DEV_BUILD_MARKER = "dev";
+var PINNED_BUILD_SHA_PATTERN = /^[0-9a-f]{40}$/i;
+var PR_BUILD_ALIAS_PATTERN = /^pr-\d+$/;
+/** Typed failure raised by {@link loadMessagingBridge}. */
+var MessagingBridgeLoadError = class extends Error {
+	constructor(message, code, cause) {
+		super(message);
+		_defineProperty(this, "code", void 0);
+		this.name = "MessagingBridgeLoadError";
+		this.code = code;
+		if (cause !== void 0) this.cause = cause;
+	}
+};
+var defaultImportModule = (url) => import(
+	/* webpackIgnore: true */
+	/* @vite-ignore */
+	url
+);
+var inFlightByImporter = /* @__PURE__ */ new WeakMap();
+var LOOPBACK_HOSTS = new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]",
+	"::1"
+]);
+function isLoopbackHostname(hostname) {
+	const normalized = hostname.trim().toLowerCase();
+	return LOOPBACK_HOSTS.has(normalized) || normalized.endsWith(".localhost");
+}
+function trimTrailingSlashes(value) {
+	let end = value.length;
+	while (end > 0 && value[end - 1] === "/") end -= 1;
+	return value.slice(0, end);
+}
+function bridgeFrameOnlyMessage(message) {
+	return `${message} The bridge only runs inside an Ada-mounted custom-app frame.`;
+}
+var FRAME_NAME_MARKER_PREFIX = `${CUSTOM_APP_FRAME_NAME}:`;
+function frameNameCarriesBuild(name) {
+	return name.startsWith(FRAME_NAME_MARKER_PREFIX);
+}
+/**
+* Read the build marker core stamps into the frame's `window.name`
+* (`ada-custom-app:<marker>`). The name is Ada-owned for this frame, so the
+* marker never touches customer-owned URL state such as a hash route.
+*/
+function resolveBridgeBuildFromFrameName(name) {
+	if (name === CUSTOM_APP_FRAME_NAME) throw new MessagingBridgeLoadError("The mounting Ada core predates build-marker delivery, so it cannot select a versioned bridge. The Ada core rollout must include the marker-stamping core before the npm bridge can load.", "missing_build_sha");
+	if (!frameNameCarriesBuild(name)) throw new MessagingBridgeLoadError(`${bridgeFrameOnlyMessage("This document was not mounted by an Ada core frame: window.name carries no ada-custom-app build marker.")} If this frame is Ada-mounted, make sure @ada-cx/messaging-bridge (or its /react entry) is imported from a module your page evaluates at startup — a lazily loaded chunk evaluates after customer code could overwrite window.name.`, "missing_build_sha");
+	const value = name.slice(FRAME_NAME_MARKER_PREFIX.length);
+	if (value === DEV_BUILD_MARKER) return { kind: "dev" };
+	if (PR_BUILD_ALIAS_PATTERN.test(value)) return {
+		kind: "alias",
+		identifier: value
+	};
+	if (!PINNED_BUILD_SHA_PATTERN.test(value)) throw new MessagingBridgeLoadError(bridgeFrameOnlyMessage(`The window.name build marker must be exactly a bare 40-character hex git SHA or a lowercase pr-<N> alias. URLs and paths are not allowed: "${value}".`), "invalid_build_sha");
+	return {
+		kind: "sha",
+		identifier: value.toLowerCase()
+	};
+}
+var initialFrameName = typeof window === "undefined" ? "" : window.name;
+var initialFrameNameHasBuild = frameNameCarriesBuild(initialFrameName);
+function currentFrameName() {
+	if (initialFrameNameHasBuild) return initialFrameName;
+	return typeof window === "undefined" ? "" : window.name;
+}
+function resolveCdnBase(cdnBase) {
+	const base = trimTrailingSlashes((cdnBase ?? DEFAULT_CDN_BASE).trim());
+	let url;
+	try {
+		url = new URL(base);
+	} catch (cause) {
+		throw new MessagingBridgeLoadError(`The cdnBase option is not a valid URL: "${base}".`, "invalid_cdn_base", cause);
+	}
+	const isHttps = url.protocol === "https:";
+	const isLoopbackHttp = url.protocol === "http:" && isLoopbackHostname(url.hostname);
+	if (!isHttps && !isLoopbackHttp) throw new MessagingBridgeLoadError(`The cdnBase option must use https (plain http is allowed only for loopback hosts): "${base}".`, "invalid_cdn_base");
+	return {
+		base,
+		hostname: url.hostname
+	};
+}
+/**
+* Resolve the bridge asset URL from this frame's name marker and the CDN
+* base. Production builds always resolve the immutable SHA-rooted asset.
+* PR aliases stay under the configured CDN base. A production-base alias that
+* does not exist fails closed through the normal bridge import error.
+* Local development resolves `/bridge/bridge.js` only on a loopback base.
+*/
+function resolveBridgeCdnUrl(options) {
+	const build = resolveBridgeBuildFromFrameName(currentFrameName());
+	const { base, hostname } = resolveCdnBase(options?.cdnBase);
+	if (build.kind === "dev" && !isLoopbackHostname(hostname)) throw new MessagingBridgeLoadError(bridgeFrameOnlyMessage(`The ${FRAME_NAME_MARKER_PREFIX}${DEV_BUILD_MARKER} frame-name marker requires a loopback cdnBase.`), "dev_marker_not_loopback");
+	const assetPath = build.kind === "dev" ? `/${BRIDGE_ENTRY_PATH}` : `/${build.identifier}/${BRIDGE_ENTRY_PATH}`;
+	return new URL(`${base}${assetPath}`).toString();
+}
+var REQUIRED_BRIDGE_FUNCTION_EXPORTS = [
+	"createBridgeClient",
+	"messageKey",
+	"isHistoricalRow",
+	"findFirstUnread",
+	"selectUnread",
+	"groupMessages",
+	"filterDisplayable",
+	"resolveBotName",
+	"isAgentTyping",
+	"isConnectivityLost"
+];
+function isMessagingBridgeModule(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return candidate.STATE != null && REQUIRED_BRIDGE_FUNCTION_EXPORTS.every((key) => typeof candidate[key] === "function");
+}
+async function importBridgeModule(url, importModule) {
+	let loaded;
+	try {
+		loaded = await importModule(url);
+	} catch (cause) {
+		throw new MessagingBridgeLoadError(`The Ada bridge runtime failed to load from ${url}.`, "bridge_import_failed", cause);
+	}
+	if (!isMessagingBridgeModule(loaded)) throw new MessagingBridgeLoadError(`The module at ${url} does not expose the full Ada bridge surface; it is not a complete Ada bridge build.`, "bridge_module_invalid");
+	return loaded;
+}
+/**
+* Load the bridge runtime that matches the mounting core frame. Loads are
+* memoized per resolved URL and importer. A failed load is evicted for retry.
+*/
+function loadMessagingBridge(options = {}) {
+	const importModule = options.importModule ?? defaultImportModule;
+	let url;
+	try {
+		url = resolveBridgeCdnUrl(options);
+	} catch (error) {
+		return Promise.reject(error);
+	}
+	let inFlight = inFlightByImporter.get(importModule);
+	if (!inFlight) {
+		inFlight = /* @__PURE__ */ new Map();
+		inFlightByImporter.set(importModule, inFlight);
+	}
+	const existing = inFlight.get(url);
+	if (existing) return existing;
+	const cache = inFlight;
+	const pending = importBridgeModule(url, importModule);
+	cache.set(url, pending);
+	pending.catch(() => {
+		if (cache.get(url) === pending) cache.delete(url);
+	});
+	return pending;
+}
+//#endregion
+export { loadMessagingBridge as n, resolveBridgeCdnUrl as r, MessagingBridgeLoadError as t };
+
+//# sourceMappingURL=loader-CfCnvaTU.js.map

package/dist-npm/loader-CfCnvaTU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader-CfCnvaTU.js","names":[],"sources":["../src/npm/loader.ts"],"sourcesContent":["import type { createBridgeClient } from \"../contract/bridge-client\";\nimport type {\n\tfilterDisplayable,\n\tfindFirstUnread,\n\tgroupMessages,\n\tisAgentTyping,\n\tisConnectivityLost,\n\tisHistoricalRow,\n\tmessageKey,\n\tresolveBotName,\n\tselectUnread,\n} from \"../contract/derive\";\nimport type { STATE } from \"../contract/state-keys\";\n\nconst DEFAULT_CDN_BASE = \"https://messaging-assets.ada.support\";\n// Keep aligned with packages/core/src/app-bridge.ts; pinned by\n// scripts/core-html-contract.test.mjs.\nconst CUSTOM_APP_FRAME_NAME = \"ada-custom-app\";\nconst BRIDGE_ENTRY_PATH = \"bridge/bridge.js\";\nconst DEV_BUILD_MARKER = \"dev\";\n\n// Only canonical build identifiers may become part of an executable asset URL.\nconst PINNED_BUILD_SHA_PATTERN = /^[0-9a-f]{40}$/i;\n// Deliberately narrower than scripts/sdk.js parseVersionOverride (7-40 hex,\n// case-insensitive): deployed keys are always lowercase `pr-<N>`, and a short\n// SHA never names an uploaded tree, so the narrower grammar loses no reachable\n// build while keeping the executable-path grammar minimal.\nconst PR_BUILD_ALIAS_PATTERN = /^pr-\\d+$/;\n\n/** Why a {@link MessagingBridgeLoadError} was raised. */\nexport type MessagingBridgeLoadErrorCode =\n\t/** The `cdnBase` option violates the HTTPS or loopback HTTP policy. */\n\t| \"invalid_cdn_base\"\n\t/** The frame's `window.name` carries no core build marker. */\n\t| \"missing_build_sha\"\n\t/** The frame-name marker is not a supported bare build identifier. */\n\t| \"invalid_build_sha\"\n\t/** The `dev` marker was paired with a non-loopback CDN base. */\n\t| \"dev_marker_not_loopback\"\n\t/** The dynamic import of the CDN asset failed. */\n\t| \"bridge_import_failed\"\n\t/** The imported module does not expose the Ada bridge surface. */\n\t| \"bridge_module_invalid\";\n\n/** Typed failure raised by {@link loadMessagingBridge}. */\nexport class MessagingBridgeLoadError extends Error {\n\treadonly code: MessagingBridgeLoadErrorCode;\n\n\tconstructor(\n\t\tmessage: string,\n\t\tcode: MessagingBridgeLoadErrorCode,\n\t\tcause?: unknown,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"MessagingBridgeLoadError\";\n\t\tthis.code = code;\n\t\tif (cause !== undefined) {\n\t\t\tthis.cause = cause;\n\t\t}\n\t}\n}\n\n/** The module shape served by the SHA-matched bridge CDN asset. */\nexport interface MessagingBridgeModule {\n\tcreateBridgeClient: typeof createBridgeClient;\n\tSTATE: typeof STATE;\n\tmessageKey: typeof messageKey;\n\tisHistoricalRow: typeof isHistoricalRow;\n\tfindFirstUnread: typeof findFirstUnread;\n\tselectUnread: typeof selectUnread;\n\tgroupMessages: typeof groupMessages;\n\tfilterDisplayable: typeof filterDisplayable;\n\tresolveBotName: typeof resolveBotName;\n\tisAgentTyping: typeof isAgentTyping;\n\tisConnectivityLost: typeof isConnectivityLost;\n}\n\ntype ImportBridgeModule = (url: string) => Promise<unknown>;\n\n/** Options for {@link loadMessagingBridge}. */\nexport interface LoadMessagingBridgeOptions {\n\t/**\n\t * Asset base for staged validation. It must use HTTPS. Plain HTTP is\n\t * accepted only for loopback hosts.\n\t */\n\tcdnBase?: string;\n\t/** Import seam for unit tests. */\n\timportModule?: ImportBridgeModule;\n}\n\n// Both annotations are load-bearing. Customer bundlers must leave the\n// browser-resolved CDN URL untouched.\nconst defaultImportModule: ImportBridgeModule = (url) =>\n\timport(/* webpackIgnore: true */ /* @vite-ignore */ url);\n\nconst inFlightByImporter = new WeakMap<\n\tImportBridgeModule,\n\tMap<string, Promise<MessagingBridgeModule>>\n>();\n\nconst LOOPBACK_HOSTS = new Set([\"localhost\", \"127.0.0.1\", \"[::1]\", \"::1\"]);\n\nfunction isLoopbackHostname(hostname: string): boolean {\n\tconst normalized = hostname.trim().toLowerCase();\n\treturn LOOPBACK_HOSTS.has(normalized) || normalized.endsWith(\".localhost\");\n}\n\nfunction trimTrailingSlashes(value: string): string {\n\tlet end = value.length;\n\twhile (end > 0 && value[end - 1] === \"/\") {\n\t\tend -= 1;\n\t}\n\treturn value.slice(0, end);\n}\n\ntype BridgeBuild =\n\t| { kind: \"sha\"; identifier: string }\n\t| { kind: \"alias\"; identifier: string }\n\t| { kind: \"dev\" };\n\nfunction bridgeFrameOnlyMessage(message: string): string {\n\treturn `${message} The bridge only runs inside an Ada-mounted custom-app frame.`;\n}\n\nconst FRAME_NAME_MARKER_PREFIX = `${CUSTOM_APP_FRAME_NAME}:`;\n\nfunction frameNameCarriesBuild(name: string): boolean {\n\treturn name.startsWith(FRAME_NAME_MARKER_PREFIX);\n}\n\n/**\n * Read the build marker core stamps into the frame's `window.name`\n * (`ada-custom-app:<marker>`). The name is Ada-owned for this frame, so the\n * marker never touches customer-owned URL state such as a hash route.\n */\nexport function resolveBridgeBuildFromFrameName(name: string): BridgeBuild {\n\tif (name === CUSTOM_APP_FRAME_NAME) {\n\t\tthrow new MessagingBridgeLoadError(\n\t\t\t\"The mounting Ada core predates build-marker delivery, so it cannot select a versioned bridge. The Ada core rollout must include the marker-stamping core before the npm bridge can load.\",\n\t\t\t\"missing_build_sha\",\n\t\t);\n\t}\n\tif (!frameNameCarriesBuild(name)) {\n\t\tthrow new MessagingBridgeLoadError(\n\t\t\t`${bridgeFrameOnlyMessage(\n\t\t\t\t\"This document was not mounted by an Ada core frame: window.name carries no ada-custom-app build marker.\",\n\t\t\t)} If this frame is Ada-mounted, make sure @ada-cx/messaging-bridge (or its /react entry) is imported from a module your page evaluates at startup — a lazily loaded chunk evaluates after customer code could overwrite window.name.`,\n\t\t\t\"missing_build_sha\",\n\t\t);\n\t}\n\tconst value = name.slice(FRAME_NAME_MARKER_PREFIX.length);\n\tif (value === DEV_BUILD_MARKER) {\n\t\treturn { kind: \"dev\" };\n\t}\n\tif (PR_BUILD_ALIAS_PATTERN.test(value)) {\n\t\treturn { kind: \"alias\", identifier: value };\n\t}\n\tif (!PINNED_BUILD_SHA_PATTERN.test(value)) {\n\t\tthrow new MessagingBridgeLoadError(\n\t\t\tbridgeFrameOnlyMessage(\n\t\t\t\t`The window.name build marker must be exactly a bare 40-character hex git SHA or a lowercase pr-<N> alias. URLs and paths are not allowed: \"${value}\".`,\n\t\t\t),\n\t\t\t\"invalid_build_sha\",\n\t\t);\n\t}\n\treturn { kind: \"sha\", identifier: value.toLowerCase() };\n}\n\n// Latch window.name at module evaluation: core stamps the marker on the\n// frame element before the document loads, and customer code — for example a\n// library that uses window.name as a storage channel — could overwrite it\n// after boot. The latch therefore only holds when this package is imported\n// from the page's entry module rather than a lazily loaded chunk — the\n// boundary README_NPM.md documents and the snapshot tests in loader.test.ts\n// pin.\nconst initialFrameName = typeof window === \"undefined\" ? \"\" : window.name;\nconst initialFrameNameHasBuild = frameNameCarriesBuild(initialFrameName);\n\nfunction currentFrameName(): string {\n\tif (initialFrameNameHasBuild) {\n\t\treturn initialFrameName;\n\t}\n\treturn typeof window === \"undefined\" ? \"\" : window.name;\n}\n\nfunction resolveCdnBase(cdnBase: string | undefined): {\n\tbase: string;\n\thostname: string;\n} {\n\tconst base = trimTrailingSlashes((cdnBase ?? DEFAULT_CDN_BASE).trim());\n\tlet url: URL;\n\ttry {\n\t\turl = new URL(base);\n\t} catch (cause) {\n\t\tthrow new MessagingBridgeLoadError(\n\t\t\t`The cdnBase option is not a valid URL: \"${base}\".`,\n\t\t\t\"invalid_cdn_base\",\n\t\t\tcause,\n\t\t);\n\t}\n\tconst isHttps = url.protocol === \"https:\";\n\tconst isLoopbackHttp =\n\t\turl.protocol === \"http:\" && isLoopbackHostname(url.hostname);\n\tif (!isHttps && !isLoopbackHttp) {\n\t\tthrow new MessagingBridgeLoadError(\n\t\t\t`The cdnBase option must use https (plain http is allowed only for loopback hosts): \"${base}\".`,\n\t\t\t\"invalid_cdn_base\",\n\t\t);\n\t}\n\treturn { base, hostname: url.hostname };\n}\n\n/**\n * Resolve the bridge asset URL from this frame's name marker and the CDN\n * base. Production builds always resolve the immutable SHA-rooted asset.\n * PR aliases stay under the configured CDN base. A production-base alias that\n * does not exist fails closed through the normal bridge import error.\n * Local development resolves `/bridge/bridge.js` only on a loopback base.\n */\nexport function resolveBridgeCdnUrl(\n\toptions?: Pick<LoadMessagingBridgeOptions, \"cdnBase\">,\n): string {\n\tconst build = resolveBridgeBuildFromFrameName(currentFrameName());\n\tconst { base, hostname } = resolveCdnBase(options?.cdnBase);\n\tif (build.kind === \"dev\" && !isLoopbackHostname(hostname)) {\n\t\tthrow new MessagingBridgeLoadError(\n\t\t\tbridgeFrameOnlyMessage(\n\t\t\t\t`The ${FRAME_NAME_MARKER_PREFIX}${DEV_BUILD_MARKER} frame-name marker requires a loopback cdnBase.`,\n\t\t\t),\n\t\t\t\"dev_marker_not_loopback\",\n\t\t);\n\t}\n\tconst assetPath =\n\t\tbuild.kind === \"dev\"\n\t\t\t? `/${BRIDGE_ENTRY_PATH}`\n\t\t\t: `/${build.identifier}/${BRIDGE_ENTRY_PATH}`;\n\treturn new URL(`${base}${assetPath}`).toString();\n}\n\n// A partial CDN module (mid-deploy, or a rolled-back build missing a newer\n// export) must fail here as a typed bridge_module_invalid error, not later as\n// a TypeError on the first missing call — so every export is checked. The\n// `satisfies` clause rejects names that are not interface members; the\n// exhaustiveness type below is what forces this list to grow with it.\nconst REQUIRED_BRIDGE_FUNCTION_EXPORTS = [\n\t\"createBridgeClient\",\n\t\"messageKey\",\n\t\"isHistoricalRow\",\n\t\"findFirstUnread\",\n\t\"selectUnread\",\n\t\"groupMessages\",\n\t\"filterDisplayable\",\n\t\"resolveBotName\",\n\t\"isAgentTyping\",\n\t\"isConnectivityLost\",\n] as const satisfies readonly (keyof MessagingBridgeModule)[];\n\ntype MissingRequiredBridgeExport = Exclude<\n\tkeyof MessagingBridgeModule,\n\t(typeof REQUIRED_BRIDGE_FUNCTION_EXPORTS)[number] | \"STATE\"\n>;\n// Compile-time exhaustiveness: adding a MessagingBridgeModule member without\n// listing it in REQUIRED_BRIDGE_FUNCTION_EXPORTS (or checking it explicitly,\n// like STATE) makes the Exclude non-`never`, so the `true` assignment below\n// stops compiling.\ntype AllBridgeExportsListed = MissingRequiredBridgeExport extends never\n\t? true\n\t: never;\nconst _allBridgeExportsListed: AllBridgeExportsListed = true;\nvoid _allBridgeExportsListed;\n\nfunction isMessagingBridgeModule(\n\tvalue: unknown,\n): value is MessagingBridgeModule {\n\tif (typeof value !== \"object\" || value === null) {\n\t\treturn false;\n\t}\n\tconst candidate = value as Record<string, unknown>;\n\t// STATE is a constant object, not a function, so it gets a presence check.\n\treturn (\n\t\tcandidate.STATE != null &&\n\t\tREQUIRED_BRIDGE_FUNCTION_EXPORTS.every(\n\t\t\t(key) => typeof candidate[key] === \"function\",\n\t\t)\n\t);\n}\n\nasync function importBridgeModule(\n\turl: string,\n\timportModule: ImportBridgeModule,\n): Promise<MessagingBridgeModule> {\n\tlet loaded: unknown;\n\ttry {\n\t\tloaded = await importModule(url);\n\t} catch (cause) {\n\t\tthrow new MessagingBridgeLoadError(\n\t\t\t`The Ada bridge runtime failed to load from ${url}.`,\n\t\t\t\"bridge_import_failed\",\n\t\t\tcause,\n\t\t);\n\t}\n\tif (!isMessagingBridgeModule(loaded)) {\n\t\tthrow new MessagingBridgeLoadError(\n\t\t\t`The module at ${url} does not expose the full Ada bridge surface; it is not a complete Ada bridge build.`,\n\t\t\t\"bridge_module_invalid\",\n\t\t);\n\t}\n\treturn loaded;\n}\n\n/**\n * Load the bridge runtime that matches the mounting core frame. Loads are\n * memoized per resolved URL and importer. A failed load is evicted for retry.\n */\nexport function loadMessagingBridge(\n\toptions: LoadMessagingBridgeOptions = {},\n): Promise<MessagingBridgeModule> {\n\tconst importModule = options.importModule ?? defaultImportModule;\n\tlet url: string;\n\ttry {\n\t\turl = resolveBridgeCdnUrl(options);\n\t} catch (error) {\n\t\treturn Promise.reject(error);\n\t}\n\n\tlet inFlight = inFlightByImporter.get(importModule);\n\tif (!inFlight) {\n\t\tinFlight = new Map();\n\t\tinFlightByImporter.set(importModule, inFlight);\n\t}\n\tconst existing = inFlight.get(url);\n\tif (existing) {\n\t\treturn existing;\n\t}\n\n\tconst cache = inFlight;\n\tconst pending = importBridgeModule(url, importModule);\n\tcache.set(url, pending);\n\tpending.catch(() => {\n\t\tif (cache.get(url) === pending) {\n\t\t\tcache.delete(url);\n\t\t}\n\t});\n\treturn pending;\n}\n"],"mappings":"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"}

package/{dist → dist-npm/npm}/bridge-react.d.ts

@@ -1,6 +1,6 @@
-import type { BridgeClient } from "./bridge-client.js";
+import type { BridgeClient } from "../contract/bridge-client.js";
+import type { AppDisplayState } from "../contract/types.js";
 import type { MessagingBridgeModule } from "./loader.js";
-import type { AppDisplayState } from "./types.js";
 export declare const BridgeContext: import("react").Context<BridgeClient | null>;
 /**
  * Provide a {@link BridgeClient} to the React tree.

package/{dist/npm-index.d.ts → dist-npm/npm/index.d.ts}

@@ -6,12 +6,11 @@
  * `loadMessagingBridge()` so Ada can patch security-bearing logic without a
  * customer release. Never add runtime implementation to this entry.
  */
-export type { FileUploadErrorData, FileUploadErrorReason, } from "./shared-utils/index.js";
-export type { BridgeClient } from "./bridge-client.js";
-export { CDN_BUILD_SHA, isCdnBuildShaStamped } from "./build-info.js";
-export type { MessageGroupingEntry, UnreadSelection } from "./derive.js";
+export type { FileUploadErrorData, FileUploadErrorReason, } from "../shared-utils/index.js";
+export type { BridgeClient } from "../contract/bridge-client.js";
+export type { MessageGroupingEntry, UnreadSelection } from "../contract/derive.js";
+export type { BridgeClientDestroyedError, BridgeOperations, BridgeOperationsHost, CaptureHandle, CsatSubmitHandle, EndChatEligibilityResult, FileUploadHandle, ObserveOptions, OperationResult, SendHandle, SettleOptions, } from "../contract/operations.js";
+export type { StateKey } from "../contract/state-keys.js";
+export type { AppDisplayState, AppEvents, CaptureData, CsatMessage, CsatScaleType, DownloadableMessage, FallbackUiConfig, LinkMessage, ListSelectionData, LiveChatStateData, Message, NotificationPermissionMessage, OptionItem, OptionsMessage, PictureMessage, PresenceMessage, QueueBotBlockMessage, QuickRepliesMessage, QuickReply, SdkPlatform, SeamlessOAuthMessage, SelectableListItem, SelectableListMessage, SignInMessage, TextMessage, VideoMessage, WidgetMessage, } from "../contract/types.js";
 export type { LoadMessagingBridgeOptions, MessagingBridgeLoadErrorCode, MessagingBridgeModule, } from "./loader.js";
 export { loadMessagingBridge, MessagingBridgeLoadError, resolveBridgeCdnUrl, } from "./loader.js";
-export type { BridgeClientDestroyedError, BridgeOperations, BridgeOperationsHost, CaptureHandle, CsatSubmitHandle, EndChatEligibilityResult, FileUploadHandle, ObserveOptions, OperationResult, SendHandle, SettleOptions, } from "./operations.js";
-export type { StateKey } from "./state-keys.js";
-export type { AppDisplayState, AppEvents, CaptureData, CsatMessage, CsatScaleType, DownloadableMessage, FallbackUiConfig, LinkMessage, ListSelectionData, LiveChatStateData, Message, NotificationPermissionMessage, OptionItem, OptionsMessage, PictureMessage, PresenceMessage, QueueBotBlockMessage, QuickRepliesMessage, QuickReply, SdkPlatform, SeamlessOAuthMessage, SelectableListItem, SelectableListMessage, SignInMessage, TextMessage, VideoMessage, WidgetMessage, } from "./types.js";

package/dist-npm/npm/index.js

@@ -0,0 +1,2 @@
+import { n as loadMessagingBridge, r as resolveBridgeCdnUrl, t as MessagingBridgeLoadError } from "../loader-CfCnvaTU.js";
+export { MessagingBridgeLoadError, loadMessagingBridge, resolveBridgeCdnUrl };

package/dist-npm/npm/loader.d.ts

@@ -0,0 +1,76 @@
+import type { createBridgeClient } from "../contract/bridge-client.js";
+import type { filterDisplayable, findFirstUnread, groupMessages, isAgentTyping, isConnectivityLost, isHistoricalRow, messageKey, resolveBotName, selectUnread } from "../contract/derive.js";
+import type { STATE } from "../contract/state-keys.js";
+/** Why a {@link MessagingBridgeLoadError} was raised. */
+export type MessagingBridgeLoadErrorCode = 
+/** The `cdnBase` option violates the HTTPS or loopback HTTP policy. */
+"invalid_cdn_base"
+/** The frame's `window.name` carries no core build marker. */
+ | "missing_build_sha"
+/** The frame-name marker is not a supported bare build identifier. */
+ | "invalid_build_sha"
+/** The `dev` marker was paired with a non-loopback CDN base. */
+ | "dev_marker_not_loopback"
+/** The dynamic import of the CDN asset failed. */
+ | "bridge_import_failed"
+/** The imported module does not expose the Ada bridge surface. */
+ | "bridge_module_invalid";
+/** Typed failure raised by {@link loadMessagingBridge}. */
+export declare class MessagingBridgeLoadError extends Error {
+    readonly code: MessagingBridgeLoadErrorCode;
+    constructor(message: string, code: MessagingBridgeLoadErrorCode, cause?: unknown);
+}
+/** The module shape served by the SHA-matched bridge CDN asset. */
+export interface MessagingBridgeModule {
+    createBridgeClient: typeof createBridgeClient;
+    STATE: typeof STATE;
+    messageKey: typeof messageKey;
+    isHistoricalRow: typeof isHistoricalRow;
+    findFirstUnread: typeof findFirstUnread;
+    selectUnread: typeof selectUnread;
+    groupMessages: typeof groupMessages;
+    filterDisplayable: typeof filterDisplayable;
+    resolveBotName: typeof resolveBotName;
+    isAgentTyping: typeof isAgentTyping;
+    isConnectivityLost: typeof isConnectivityLost;
+}
+type ImportBridgeModule = (url: string) => Promise<unknown>;
+/** Options for {@link loadMessagingBridge}. */
+export interface LoadMessagingBridgeOptions {
+    /**
+     * Asset base for staged validation. It must use HTTPS. Plain HTTP is
+     * accepted only for loopback hosts.
+     */
+    cdnBase?: string;
+    /** Import seam for unit tests. */
+    importModule?: ImportBridgeModule;
+}
+type BridgeBuild = {
+    kind: "sha";
+    identifier: string;
+} | {
+    kind: "alias";
+    identifier: string;
+} | {
+    kind: "dev";
+};
+/**
+ * Read the build marker core stamps into the frame's `window.name`
+ * (`ada-custom-app:<marker>`). The name is Ada-owned for this frame, so the
+ * marker never touches customer-owned URL state such as a hash route.
+ */
+export declare function resolveBridgeBuildFromFrameName(name: string): BridgeBuild;
+/**
+ * Resolve the bridge asset URL from this frame's name marker and the CDN
+ * base. Production builds always resolve the immutable SHA-rooted asset.
+ * PR aliases stay under the configured CDN base. A production-base alias that
+ * does not exist fails closed through the normal bridge import error.
+ * Local development resolves `/bridge/bridge.js` only on a loopback base.
+ */
+export declare function resolveBridgeCdnUrl(options?: Pick<LoadMessagingBridgeOptions, "cdnBase">): string;
+/**
+ * Load the bridge runtime that matches the mounting core frame. Loads are
+ * memoized per resolved URL and importer. A failed load is evicted for retry.
+ */
+export declare function loadMessagingBridge(options?: LoadMessagingBridgeOptions): Promise<MessagingBridgeModule>;
+export {};

package/{dist/npm-react.d.ts → dist-npm/npm/react.d.ts}

@@ -5,9 +5,9 @@
  * created by the CDN-loaded runtime. Never import `createBridgeClient` here —
  * the security-bearing runtime must not reach the npm tarball.
  */
-export type { BridgeClient } from "./bridge-client.js";
+export type { BridgeClient } from "../contract/bridge-client.js";
+export type { AppDisplayState, AppEvents } from "../contract/types.js";
 export type { LoadedBridgeProviderProps } from "./bridge-react.js";
 export { BridgeProvider, createBridgeProvider, useBridgeClient, useBridgeState, useBridgeStateKey, } from "./bridge-react.js";
 export type { LoadMessagingBridgeOptions, MessagingBridgeLoadErrorCode, MessagingBridgeModule, } from "./loader.js";
 export { loadMessagingBridge, MessagingBridgeLoadError, resolveBridgeCdnUrl, } from "./loader.js";
-export type { AppDisplayState, AppEvents } from "./types.js";

package/{dist/npm-react.js → dist-npm/npm/react.js}

@@ -1,7 +1,7 @@
-import { n as loadMessagingBridge, r as resolveBridgeCdnUrl, t as MessagingBridgeLoadError } from "./loader-CVynp73o.js";
+import { n as loadMessagingBridge, r as resolveBridgeCdnUrl, t as MessagingBridgeLoadError } from "../loader-CfCnvaTU.js";
 import { createContext, useCallback, useContext, useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment, jsx } from "react/jsx-runtime";
-//#region src/bridge-react.tsx
+//#region src/npm/bridge-react.tsx
 var BridgeContext = createContext(null);
 /**
 * Provide a {@link BridgeClient} to the React tree.
@@ -43,7 +43,7 @@ function useBridgeState() {
 */
 function useBridgeStateKey(key) {
 	const client = useBridgeClient();
-	const subscribe = useCallback((onStoreChange) => typeof client.subscribeKey === "function" ? client.subscribeKey(key, onStoreChange) : client.subscribe(onStoreChange), [client, key]);
+	const subscribe = useCallback((onStoreChange) => client.subscribeKey(key, onStoreChange), [client, key]);
 	const getSnapshot = useCallback(() => {
 		const state = client.getState();
 		if (state === null) return null;
@@ -110,4 +110,4 @@ function createBridgeProvider(load = loadMessagingBridge) {
 //#endregion
 export { BridgeProvider, MessagingBridgeLoadError, createBridgeProvider, loadMessagingBridge, resolveBridgeCdnUrl, useBridgeClient, useBridgeState, useBridgeStateKey };
 
-//# sourceMappingURL=npm-react.js.map
+//# sourceMappingURL=react.js.map