@braidlabs/core 0.1.1

package/src/env/create-env.js

@@ -0,0 +1,91 @@
+import { braidContext } from '../context/context-bus.js';
+function parseEnvLocation(routeUrl) {
+    const url = new URL(routeUrl, document.baseURI);
+    return {
+        href: url.href,
+        pathname: url.pathname,
+        search: url.search,
+        hash: url.hash,
+        basePath: url.pathname,
+    };
+}
+/**
+ * Builds the FragmentEnv for a fragment instance.
+ *
+ * Compat fragments never consume the env — the compat adapter installs the full illusion
+ * instead — but the runtime constructs one uniformly so the adapter interface is the same
+ * for every adapter, and contract adapters can land later without touching the slot.
+ */
+export function createFragmentEnv(options) {
+    const { contentRoot, shadowRoot, routeUrl, signal } = options;
+    let location = parseEnvLocation(routeUrl);
+    const historyListeners = new Set();
+    /** The version this fragment declared for a key, and the name to blame if it is unreachable. */
+    const contextOptions = (key) => ({
+        ...(options.contextVersions?.[key] === undefined ? {} : { as: options.contextVersions[key] }),
+        ...(options.fragmentId === undefined ? {} : { fragmentId: options.fragmentId }),
+    });
+    const applyNavigation = (url, state, replace) => {
+        const target = new URL(url, location.href);
+        if (replace) {
+            window.history.replaceState(state ?? null, '', target.href);
+        }
+        else {
+            window.history.pushState(state ?? null, '', target.href);
+        }
+        location = parseEnvLocation(target.href);
+        historyListeners.forEach((listener) => listener(location));
+    };
+    return {
+        contractVersion: '1.0',
+        root: contentRoot,
+        document: {
+            get title() {
+                return contentRoot.querySelector('title')?.textContent ?? '';
+            },
+            set title(value) {
+                const titleElement = contentRoot.querySelector('title');
+                if (titleElement) {
+                    titleElement.textContent = value;
+                }
+            },
+            appendToHead(element) {
+                (contentRoot.querySelector('braid-head') ?? contentRoot).appendChild(element);
+            },
+            get activeElement() {
+                return shadowRoot.activeElement;
+            },
+            get adoptedStyleSheets() {
+                return shadowRoot.adoptedStyleSheets;
+            },
+        },
+        get location() {
+            return location;
+        },
+        history: {
+            push: (url, state) => applyNavigation(url, state, false),
+            replace: (url, state) => applyNavigation(url, state, true),
+            back: () => window.history.back(),
+            onChange(listener) {
+                historyListeners.add(listener);
+                const unsubscribe = () => historyListeners.delete(listener);
+                signal.addEventListener('abort', unsubscribe, { once: true });
+                return unsubscribe;
+            },
+        },
+        context: {
+            get: (key) => braidContext.get(key, contextOptions(key)),
+            subscribe: (key, listener, subscribeOptions) => braidContext.subscribe(key, listener, {
+                ...contextOptions(key),
+                signal: subscribeOptions?.signal ?? signal,
+            }),
+        },
+        get props() {
+            return options.getProps();
+        },
+        onPropsChanged: options.onPropsChanged,
+        emit: options.emit,
+        signal,
+    };
+}
+//# sourceMappingURL=create-env.js.map

package/src/env/create-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-env.js","sourceRoot":"","sources":["../../../../../libs/core/src/env/create-env.ts"],"names":[],"mappings":"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"}

package/src/env/fragment-env.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `FragmentEnv` — the contract object graph a fragment sees instead of patched globals.
+ *
+ * Contract-mode fragments receive this env through their adapter's `mount(env, entry)` call and
+ * never touch realm globals. Compat-mode fragments (the only adapter shipped in this build) do
+ * not consume the env — the compat adapter installs the full document/window illusion instead —
+ * but the contract is defined here because it is the heart of the project and the adapter
+ * interface is written against it.
+ *
+ * Design rules: every member is a real object with a stable identity (no getters that change
+ * shape), every mutation path is explicit, and nothing on `FragmentEnv` requires the realm.
+ */
+export interface EnvDocument {
+    /** Sets or reads the fragment's logical document title. Bound fragments propagate it to the host. */
+    title: string;
+    /** Appends a stylesheet or other head-scoped element to the fragment's head region. */
+    appendToHead(element: HTMLElement): void;
+    readonly activeElement: Element | null;
+    readonly adoptedStyleSheets: CSSStyleSheet[];
+}
+export interface EnvLocation {
+    readonly href: string;
+    readonly pathname: string;
+    readonly search: string;
+    readonly hash: string;
+    /** The base path the fragment is mounted under; adapters feed this into router configuration. */
+    readonly basePath: string;
+}
+export interface EnvHistory {
+    push(url: string, state?: unknown): void;
+    replace(url: string, state?: unknown): void;
+    back(): void;
+    /** Subscribes to location changes; automatically unsubscribed when `env.signal` aborts. */
+    onChange(listener: (location: EnvLocation) => void): () => void;
+}
+export interface EnvContext {
+    get(key: string): unknown;
+    subscribe(key: string, listener: (value: unknown) => void, options?: {
+        signal?: AbortSignal;
+    }): () => void;
+}
+export interface FragmentEnv {
+    readonly contractVersion: '1.0';
+    /** Mount point inside the fragment's shadow root. */
+    readonly root: HTMLElement;
+    readonly document: EnvDocument;
+    readonly location: EnvLocation;
+    readonly history: EnvHistory;
+    readonly context: EnvContext;
+    readonly props: Readonly<Record<string, unknown>>;
+    onPropsChanged(listener: (props: Readonly<Record<string, unknown>>) => void): () => void;
+    /** Fragment → host event channel, surfaced as `braid:event` on the slot element. */
+    emit(type: string, detail?: unknown): void;
+    /** Fires on unmount — wire everything to it. */
+    readonly signal: AbortSignal;
+}

package/src/env/fragment-env.js

@@ -0,0 +1,14 @@
+/**
+ * `FragmentEnv` — the contract object graph a fragment sees instead of patched globals.
+ *
+ * Contract-mode fragments receive this env through their adapter's `mount(env, entry)` call and
+ * never touch realm globals. Compat-mode fragments (the only adapter shipped in this build) do
+ * not consume the env — the compat adapter installs the full document/window illusion instead —
+ * but the contract is defined here because it is the heart of the project and the adapter
+ * interface is written against it.
+ *
+ * Design rules: every member is a real object with a stable identity (no getters that change
+ * shape), every mutation path is explicit, and nothing on `FragmentEnv` requires the realm.
+ */
+export {};
+//# sourceMappingURL=fragment-env.js.map

package/src/env/fragment-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragment-env.js","sourceRoot":"","sources":["../../../../../libs/core/src/env/fragment-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/src/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The Braid error standard: every thrown or reported runtime error names the fragment,
+ * the failing stage, and — where we know it — the likely fix.
+ */
+/** The lifecycle stage in which an error occurred. */
+export type BraidErrorStage = 'slot-config' | 'fragment-fetch' | 'realm-boot' | 'adapter-resolution' | 'adapter-mount' | 'context-version';
+export interface BraidErrorInit {
+    fragmentId: string;
+    stage: BraidErrorStage;
+    cause?: unknown;
+    /** The likely fix, phrased as an instruction to the developer. */
+    fixHint?: string;
+    docsUrl?: string;
+}
+export declare class BraidError extends Error {
+    readonly fragmentId: string;
+    readonly stage: BraidErrorStage;
+    readonly fixHint?: string;
+    readonly docsUrl?: string;
+    constructor(message: string, init: BraidErrorInit);
+}

package/src/errors.js

@@ -0,0 +1,21 @@
+/**
+ * The Braid error standard: every thrown or reported runtime error names the fragment,
+ * the failing stage, and — where we know it — the likely fix.
+ */
+export class BraidError extends Error {
+    fragmentId;
+    stage;
+    fixHint;
+    docsUrl;
+    constructor(message, init) {
+        const hint = init.fixHint ? `\nLikely fix: ${init.fixHint}` : '';
+        const docs = init.docsUrl ? `\nDocs: ${init.docsUrl}` : '';
+        super(`[braid:${init.fragmentId}] ${init.stage}: ${message}${hint}${docs}`, { cause: init.cause });
+        this.name = 'BraidError';
+        this.fragmentId = init.fragmentId;
+        this.stage = init.stage;
+        this.fixHint = init.fixHint;
+        this.docsUrl = init.docsUrl;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../libs/core/src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,UAAU,CAAS;IACnB,KAAK,CAAkB;IACvB,OAAO,CAAU;IACjB,OAAO,CAAU;IAE1B,YAAY,OAAe,EAAE,IAAoB;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,KAAK,CAAC,UAAU,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,KAAK,KAAK,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACnG,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9B,CAAC;CACF"}

package/src/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @braidlabs/core — the Braid client runtime.
+ *
+ * This build ships the compat adapter as the only — and default — adapter: legacy apps
+ * compose as fragments with zero app-code changes, config only.
+ *
+ * ```ts
+ * import { initBraid } from '@braidlabs/core';
+ * initBraid();
+ * ```
+ * ```html
+ * <fragment-slot name="checkout"></fragment-slot>
+ * ```
+ */
+import { BraidOptions } from './config.js';
+export { BraidError } from './errors.js';
+export type { BraidErrorStage } from './errors.js';
+export type { BraidOptions } from './config.js';
+export type { FragmentEnv, EnvDocument, EnvLocation, EnvHistory, EnvContext } from './env/fragment-env.js';
+export type { BraidAdapter } from './adapters/adapter.js';
+export { DEFAULT_ADAPTER } from './adapters/adapter.js';
+export { customElementAdapter } from './adapters/custom-element-adapter.js';
+export { FragmentSlot } from './elements/fragment-slot.js';
+export type { FragmentSlotState } from './elements/fragment-slot.js';
+export { braidContext } from './context/context-bus.js';
+export { registerBraidServiceWorker } from './compat/register-worker.js';
+export type { RegisterBraidServiceWorkerOptions } from './compat/register-worker.js';
+export type { ContextSubscribeOptions, ContextReadOptions } from './context/context-bus.js';
+export { createRealm } from './realm/realm-manager.js';
+export type { RealmKind, RealmHandle, RealmInit, RealmImportMap } from './realm/realm-manager.js';
+export { BRAID_FRAGMENT_PREFIX, BRAID_REALM_PREFIX, BRAID_DOCUMENT_PREFIX, BRAID_PROTOCOL_VERSION, } from './protocol.js';
+/**
+ * Initializes the Braid client: applies configuration, installs the default compat adapter,
+ * and registers the `<fragment-slot>` element. Call once, before any slot connects.
+ */
+export declare function initBraid(options?: BraidOptions): void;

package/src/index.js

@@ -0,0 +1,40 @@
+/**
+ * @braidlabs/core — the Braid client runtime.
+ *
+ * This build ships the compat adapter as the only — and default — adapter: legacy apps
+ * compose as fragments with zero app-code changes, config only.
+ *
+ * ```ts
+ * import { initBraid } from '@braidlabs/core';
+ * initBraid();
+ * ```
+ * ```html
+ * <fragment-slot name="checkout"></fragment-slot>
+ * ```
+ */
+import { setBraidConfig } from './config.js';
+import { installAdapter } from './adapters/adapter.js';
+import { compatAdapter } from './adapters/compat-adapter.js';
+import { customElementAdapter } from './adapters/custom-element-adapter.js';
+import { FragmentSlot } from './elements/fragment-slot.js';
+export { BraidError } from './errors.js';
+export { DEFAULT_ADAPTER } from './adapters/adapter.js';
+export { customElementAdapter } from './adapters/custom-element-adapter.js';
+export { FragmentSlot } from './elements/fragment-slot.js';
+export { braidContext } from './context/context-bus.js';
+export { registerBraidServiceWorker } from './compat/register-worker.js';
+export { createRealm } from './realm/realm-manager.js';
+export { BRAID_FRAGMENT_PREFIX, BRAID_REALM_PREFIX, BRAID_DOCUMENT_PREFIX, BRAID_PROTOCOL_VERSION, } from './protocol.js';
+/**
+ * Initializes the Braid client: applies configuration, installs the default compat adapter,
+ * and registers the `<fragment-slot>` element. Call once, before any slot connects.
+ */
+export function initBraid(options = {}) {
+    setBraidConfig(options);
+    installAdapter(compatAdapter);
+    installAdapter(customElementAdapter);
+    if (!customElements.get('fragment-slot')) {
+        customElements.define('fragment-slot', FragmentSlot);
+    }
+}
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/core/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAgB,cAAc,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAKzC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAGzE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,UAAwB,EAAE;IAClD,cAAc,CAAC,OAAO,CAAC,CAAC;IACxB,cAAc,CAAC,aAAa,CAAC,CAAC;IAC9B,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAErC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;QACzC,cAAc,CAAC,MAAM,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}

package/src/protocol.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Client side of the Braid composition protocol.
+ *
+ * These constants are deliberately duplicated in `@braidlabs/gateway/src/protocol.ts`:
+ * the client and gateway bundles do not share modules, but always ship in the same package
+ * version, and the protocol version below is how a mismatch is detected and reported as a
+ * named error instead of a silent misbehavior.
+ */
+/**
+ * The three reserved namespaces, one per kind of thing the gateway serves.
+ *
+ * They are separate paths rather than one path distinguished by request headers, so that
+ * `/__braid/frag/*` — the fragment's own assets, which is nearly all the traffic — has no
+ * request-header variance and caches on URL alone.
+ */
+export declare const BRAID_FRAGMENT_PREFIX = "/__braid/frag/";
+export declare const BRAID_REALM_PREFIX = "/__braid/realm/";
+export declare const BRAID_DOCUMENT_PREFIX = "/__braid/doc/";
+/**
+ * Version of the client ↔ gateway composition protocol. The gateway stamps its version onto the
+ * realm stub document; the client verifies it at realm boot and fails with a named error on
+ * mismatch. v2 split the single fragment namespace into frag/realm/doc.
+ */
+export declare const BRAID_PROTOCOL_VERSION = "2";
+/** Name of the `<meta>` element carrying the protocol version in the realm stub document. */
+export declare const BRAID_PROTOCOL_META = "braid-protocol";
+/** Name of the `<meta>` element carrying the fragment's manifest-declared adapter in the realm stub. */
+export declare const BRAID_ADAPTER_META = "braid-adapter";
+/** Name of the `<meta>` carrying adapter-specific options as JSON (see the gateway's copy). */
+export declare const BRAID_ADAPTER_OPTIONS_META = "braid-adapter-options";
+/** Response/request header carrying a fragment id for diagnostics. */
+export declare const BRAID_FRAGMENT_ID_HEADER = "x-braid-fragment-id";
+/** The fragment's asset namespace: what its own relative URLs resolve into. */
+export declare function braidFragmentUrl(fragmentId: string, pathname: string, search?: string): string;
+/** The realm stub document a fragment's hidden iframe boots from. */
+export declare function braidRealmUrl(fragmentId: string, pathname: string, search?: string): string;
+/** The fragment's document, prepared by the gateway for life inside the host page's DOM. */
+export declare function braidDocumentUrl(fragmentId: string, pathname: string, search?: string): string;

package/src/protocol.js

@@ -0,0 +1,45 @@
+/**
+ * Client side of the Braid composition protocol.
+ *
+ * These constants are deliberately duplicated in `@braidlabs/gateway/src/protocol.ts`:
+ * the client and gateway bundles do not share modules, but always ship in the same package
+ * version, and the protocol version below is how a mismatch is detected and reported as a
+ * named error instead of a silent misbehavior.
+ */
+/**
+ * The three reserved namespaces, one per kind of thing the gateway serves.
+ *
+ * They are separate paths rather than one path distinguished by request headers, so that
+ * `/__braid/frag/*` — the fragment's own assets, which is nearly all the traffic — has no
+ * request-header variance and caches on URL alone.
+ */
+export const BRAID_FRAGMENT_PREFIX = '/__braid/frag/';
+export const BRAID_REALM_PREFIX = '/__braid/realm/';
+export const BRAID_DOCUMENT_PREFIX = '/__braid/doc/';
+/**
+ * Version of the client ↔ gateway composition protocol. The gateway stamps its version onto the
+ * realm stub document; the client verifies it at realm boot and fails with a named error on
+ * mismatch. v2 split the single fragment namespace into frag/realm/doc.
+ */
+export const BRAID_PROTOCOL_VERSION = '2';
+/** Name of the `<meta>` element carrying the protocol version in the realm stub document. */
+export const BRAID_PROTOCOL_META = 'braid-protocol';
+/** Name of the `<meta>` element carrying the fragment's manifest-declared adapter in the realm stub. */
+export const BRAID_ADAPTER_META = 'braid-adapter';
+/** Name of the `<meta>` carrying adapter-specific options as JSON (see the gateway's copy). */
+export const BRAID_ADAPTER_OPTIONS_META = 'braid-adapter-options';
+/** Response/request header carrying a fragment id for diagnostics. */
+export const BRAID_FRAGMENT_ID_HEADER = 'x-braid-fragment-id';
+/** The fragment's asset namespace: what its own relative URLs resolve into. */
+export function braidFragmentUrl(fragmentId, pathname, search = '') {
+    return `${BRAID_FRAGMENT_PREFIX}${encodeURIComponent(fragmentId)}${pathname}${search}`;
+}
+/** The realm stub document a fragment's hidden iframe boots from. */
+export function braidRealmUrl(fragmentId, pathname, search = '') {
+    return `${BRAID_REALM_PREFIX}${encodeURIComponent(fragmentId)}${pathname}${search}`;
+}
+/** The fragment's document, prepared by the gateway for life inside the host page's DOM. */
+export function braidDocumentUrl(fragmentId, pathname, search = '') {
+    return `${BRAID_DOCUMENT_PREFIX}${encodeURIComponent(fragmentId)}${pathname}${search}`;
+}
+//# sourceMappingURL=protocol.js.map

package/src/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../../libs/core/src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,gBAAgB,CAAC;AACtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,qBAAqB,GAAG,eAAe,CAAC;AAErD;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C,6FAA6F;AAC7F,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAEpD,wGAAwG;AACxG,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAElD,+FAA+F;AAC/F,MAAM,CAAC,MAAM,0BAA0B,GAAG,uBAAuB,CAAC;AAElE,sEAAsE;AACtE,MAAM,CAAC,MAAM,wBAAwB,GAAG,qBAAqB,CAAC;AAE9D,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,QAAgB,EAAE,MAAM,GAAG,EAAE;IAChF,OAAO,GAAG,qBAAqB,GAAG,kBAAkB,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,MAAM,EAAE,CAAC;AACzF,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,UAAkB,EAAE,QAAgB,EAAE,MAAM,GAAG,EAAE;IAC7E,OAAO,GAAG,kBAAkB,GAAG,kBAAkB,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,MAAM,EAAE,CAAC;AACtF,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,QAAgB,EAAE,MAAM,GAAG,EAAE;IAChF,OAAO,GAAG,qBAAqB,GAAG,kBAAkB,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,MAAM,EAAE,CAAC;AACzF,CAAC"}

package/src/realm/realm-manager.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Realm manager. A realm is the isolated JS context a fragment executes in — a hidden
+ * same-origin iframe, the only browser primitive providing a synchronous, DOM-capable second
+ * JavaScript context.
+ *
+ * Realm kinds:
+ * - `compat-http` — boots from a real `http:` URL inside the gateway namespace
+ *   (`/__braid/frag/:id/…`), because only a real URL can make the global `location`/`history`
+ *   illusion truthful (`history.replaceState` cannot rewrite a `blob:` document to an `http:`
+ *   URL). The stub's `<base>` keeps relative subresource requests inside the namespace; the
+ *   fragment's route-url illusion is restored via `replaceState` once the iframe loads.
+ * - `contract-blob` — boots from a runtime-authored `blob:` URL; zero interaction with the
+ *   joint session history. Not shipped in this build (compat-only).
+ * - `sandbox` — a real sandboxed cross-origin iframe for the untrusted tier. Not shipped in
+ *   this build.
+ */
+export type RealmKind = 'contract-blob' | 'compat-http' | 'sandbox';
+/** An import map, scoped to a single realm's document. */
+export interface RealmImportMap {
+    imports?: Record<string, string>;
+    scopes?: Record<string, Record<string, string>>;
+}
+export interface RealmInit {
+    fragmentId: string;
+    /** The fragment's logical route URL (pathname + search) restored after boot. */
+    routeUrl: string;
+    /** Whether the fragment's navigation is bound to the host window's navigation. */
+    bound: boolean;
+    /** Abort signal owned by the fragment instance; disposal is wired to it. */
+    signal: AbortSignal;
+    /**
+     * The fragment's own import map (contract-blob realms only). Because every fragment gets its
+     * own realm document, each gets its own import map for free — which is how two fragments can
+     * ship different majors of the same dependency without a shared resolution namespace.
+     */
+    importMap?: RealmImportMap;
+}
+export interface RealmHandle {
+    readonly kind: RealmKind;
+    /** The fragment this realm belongs to. */
+    readonly fragmentId: string;
+    readonly window: Window & typeof globalThis;
+    readonly document: Document;
+    /**
+     * The adapter name the gateway stamped onto the realm stub from the fragment's manifest.
+     * Null for realms the runtime authors itself (there is no stub to read it from).
+     */
+    readonly manifestAdapter: string | null;
+    /**
+     * Adapter-specific options the gateway stamped onto the realm stub from the manifest — which
+     * custom element to mount, which entry module to evaluate. Empty for realms with no stub.
+     */
+    readonly adapterOptions: Readonly<Record<string, unknown>>;
+    /** Loads and evaluates a module by URL inside the realm. */
+    evaluate(entryUrl: string): Promise<void>;
+    /** Evaluates module source inside the realm. Resolves once the module has run. */
+    evaluateModule(source: string): Promise<boolean>;
+    dispose(): void;
+}
+export declare function createRealm(kind: RealmKind, init: RealmInit): Promise<RealmHandle>;