@braidlabs/core 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braidlabs/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Braid client runtime — compose independently deployed frontend apps into one page. This build ships the compat adapter (the contained web-fragments-style emulation layer) as the default adapter.",
   "keywords": [
     "micro-frontends",
@@ -34,4 +34,4 @@
     "url": "https://github.com/braidjs/braid/issues"
   },
   "module": "./src/index.js"
-}
+}

package/src/adapters/adapter.d.ts

@@ -25,6 +25,10 @@ export interface AdapterBootContext {
     /**
      * The fragment's HTML, fetched from the gateway namespace, or null when {@link pierced} —
      * a pierced fragment's content is already in `contentRoot`, put there by the parser.
+     *
+     * A client-fetched document is usually in `contentRoot` already too, painted the moment it
+     * arrived, and then arrives here as `pierced` with `html: null`. Adapters should treat `pierced`
+     * as "the content is in place", not as "the server rendered it".
      */
     html: string | null;
     /**
@@ -38,6 +42,15 @@ export interface AdapterBootContext {
     /** Whether the fragment's navigation is bound to the host window's navigation. */
     bound: boolean;
     env: FragmentEnv;
+    /**
+     * The entry module, when the host supplies it directly rather than through the gateway.
+     *
+     * Gateway-composed fragments carry their entry on the realm stub, stamped from the manifest, and
+     * an adapter reads it from `realm.adapterOptions`. A gateway-free contract fragment has no stub —
+     * that is the point — so the host declares the entry in markup and it arrives here instead.
+     * Adapters that need an entry should prefer this and fall back to the stub.
+     */
+    entry?: string;
     /** Aborts when the fragment is being torn down. */
     signal: AbortSignal;
 }

package/src/adapters/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../../../libs/core/src/adapters/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAiE1C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC;AAExC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA4B,CAAC;AAE9D,MAAM,UAAU,cAAc,CAAC,OAAyB;IACtD,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAA+B,EAAE,UAAkB;IAChF,MAAM,WAAW,GAAG,IAAI,IAAI,eAAe,CAAC;IAC5C,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACnD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,UAAU,CAAC,qBAAqB,WAAW,+BAA+B,EAAE;YACpF,UAAU;YACV,KAAK,EAAE,oBAAoB;YAC3B,OAAO,EACL,WAAW,KAAK,eAAe;gBAC7B,CAAC,CAAC,kGAAkG;gBACpG,CAAC,CAAC,2MAA2M,WAAW,GAAG;SAChO,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,sBAAsB;IACpC,iBAAiB,CAAC,KAAK,EAAE,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../../../libs/core/src/adapters/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AA8E1C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC;AAExC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA4B,CAAC;AAE9D,MAAM,UAAU,cAAc,CAAC,OAAyB;IACtD,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAA+B,EAAE,UAAkB;IAChF,MAAM,WAAW,GAAG,IAAI,IAAI,eAAe,CAAC;IAC5C,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACnD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,UAAU,CAAC,qBAAqB,WAAW,+BAA+B,EAAE;YACpF,UAAU;YACV,KAAK,EAAE,oBAAoB;YAC3B,OAAO,EACL,WAAW,KAAK,eAAe;gBAC7B,CAAC,CAAC,kGAAkG;gBACpG,CAAC,CAAC,2MAA2M,WAAW,GAAG;SAChO,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,sBAAsB;IACpC,iBAAiB,CAAC,KAAK,EAAE,CAAC;AAC5B,CAAC"}

package/src/adapters/compat-adapter.d.ts

@@ -25,3 +25,10 @@ export declare const compatAdapter: InstalledAdapter;
  * saw a bare markup snippet.
  */
 export declare function parseFragmentContent(html: string, mainDocument: Document): HTMLElement;
+/**
+ * Resolves once every image that holds a document's load event has loaded or failed.
+ *
+ * Lazy images are skipped, as browsers skip them: one below the fold does not load until it is
+ * scrolled to, and waiting for it would mean the fragment's load event never fires.
+ */
+export declare function imagesSettled(contentRoot: HTMLElement): Promise<void>;

package/src/adapters/compat-adapter.js

@@ -50,19 +50,24 @@ export const compatAdapter = {
         fragmentShadowRoot[compatMetadataSymbol].documentReadyState = 'interactive';
         contentRoot.dispatchEvent(new Event('readystatechange', { bubbles: false, cancelable: false }));
         contentRoot.dispatchEvent(new Event('DOMContentLoaded', { bubbles: true, cancelable: false }));
-        // In order to fire the window load event we need to wait for all the images to load. By now
-        // all styles and scripts have loaded, so images are the main kind of resource to wait for.
-        await allImagesLoaded(contentRoot);
-        // Wrap the event into a task so we don't execute too early in case there are no images.
-        setTimeout(() => {
-            if (signal.aborted)
-                return;
-            fragmentShadowRoot[compatMetadataSymbol].documentReadyState = 'complete';
-            contentRoot.dispatchEvent(new Event('readystatechange', { bubbles: false, cancelable: false }));
-            realm.window.dispatchEvent(new Event('load', { bubbles: false, cancelable: false }));
-            if (isDevMode()) {
-                console.debug(`[braid:${fragmentId}] compat fragment loaded`, { shadowRoot: fragmentShadowRoot });
-            }
+        // The window load event waits for the fragment's images, as a standalone document's would. By
+        // now all styles and scripts have loaded, so images are the main kind of resource to wait for.
+        //
+        // Not awaited: boot is done once the fragment's code has run, and the slot reports ready on
+        // boot. Holding that for every image — a hero banner, or a lazy one that may never load —
+        // delays readiness for something the fragment observes on its own timeline anyway.
+        void imagesSettled(contentRoot).then(() => {
+            // Wrap the event into a task so we don't execute too early in case there are no images.
+            setTimeout(() => {
+                if (signal.aborted)
+                    return;
+                fragmentShadowRoot[compatMetadataSymbol].documentReadyState = 'complete';
+                contentRoot.dispatchEvent(new Event('readystatechange', { bubbles: false, cancelable: false }));
+                realm.window.dispatchEvent(new Event('load', { bubbles: false, cancelable: false }));
+                if (isDevMode()) {
+                    console.debug(`[braid:${fragmentId}] compat fragment loaded`, { shadowRoot: fragmentShadowRoot });
+                }
+            });
         });
     },
 };
@@ -90,10 +95,13 @@ export function parseFragmentContent(html, mainDocument) {
     return wrapper;
 }
 /**
- * Returns a promise resolving when all images in the fragment's DOM have loaded (or errored).
+ * Resolves once every image that holds a document's load event has loaded or failed.
+ *
+ * Lazy images are skipped, as browsers skip them: one below the fold does not load until it is
+ * scrolled to, and waiting for it would mean the fragment's load event never fires.
  */
-function allImagesLoaded(contentRoot) {
-    const images = contentRoot.querySelectorAll('img');
+export function imagesSettled(contentRoot) {
+    const images = contentRoot.querySelectorAll('img:not([loading="lazy" i])');
     if (images.length === 0) {
         return Promise.resolve();
     }

package/src/adapters/compat-adapter.js.map

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

package/src/adapters/contract-adapter.d.ts

@@ -0,0 +1,21 @@
+import { InstalledAdapter } from './adapter.js';
+/**
+ * The contract adapter: a fragment that asks for a `FragmentEnv` instead of pretending to own a
+ * browser.
+ *
+ * This is the mode `braid-architecture.md` has described as the end state since before there was
+ * anything to run it — `FragmentEnv` was defined, documented as "the heart of the project", and
+ * consumed by nothing a framework application would reach for. Every normal path ran through compat
+ * mode, which meant Braid's production surface was its most expensive and most browser-quirk-
+ * dependent one: the mode whose failure modes fill `braid-failure-modes.md`.
+ *
+ * What a contract fragment gives up: the illusion. No `document` facade, no `window` patches, no
+ * history virtualisation, no script neutralisation, no singleton renaming. What it gets back is the
+ * whole of that list as *not-your-problem*, plus one structural bonus that is easy to undersell:
+ *
+ * **A contract fragment needs no gateway.** Its realm boots from a `blob:` URL the runtime writes
+ * itself, so there is no realm stub to serve, no namespace to route, and no host-origin middleware
+ * to install. A statically hosted SPA can be a Braid host for contract fragments. That was the
+ * sharpest structural criticism of the architecture, and this is the answer to it.
+ */
+export declare const contractAdapter: InstalledAdapter;

package/src/adapters/contract-adapter.js

@@ -0,0 +1,71 @@
+import { BraidError } from '../errors.js';
+import { readFragmentDefinition } from '../env/define-fragment.js';
+/**
+ * The contract adapter: a fragment that asks for a `FragmentEnv` instead of pretending to own a
+ * browser.
+ *
+ * This is the mode `braid-architecture.md` has described as the end state since before there was
+ * anything to run it — `FragmentEnv` was defined, documented as "the heart of the project", and
+ * consumed by nothing a framework application would reach for. Every normal path ran through compat
+ * mode, which meant Braid's production surface was its most expensive and most browser-quirk-
+ * dependent one: the mode whose failure modes fill `braid-failure-modes.md`.
+ *
+ * What a contract fragment gives up: the illusion. No `document` facade, no `window` patches, no
+ * history virtualisation, no script neutralisation, no singleton renaming. What it gets back is the
+ * whole of that list as *not-your-problem*, plus one structural bonus that is easy to undersell:
+ *
+ * **A contract fragment needs no gateway.** Its realm boots from a `blob:` URL the runtime writes
+ * itself, so there is no realm stub to serve, no namespace to route, and no host-origin middleware
+ * to install. A statically hosted SPA can be a Braid host for contract fragments. That was the
+ * sharpest structural criticism of the architecture, and this is the answer to it.
+ */
+export const contractAdapter = {
+    name: 'contract',
+    /**
+     * A blob realm: no network round trip, no realm stub, and — because the realm never navigates —
+     * zero interaction with the joint session history, which is the entire class of back/forward
+     * corruption that compat mode has to work around.
+     */
+    realmKind: 'contract-blob',
+    /** A contract fragment builds its own UI from its entry module; it serves no document. */
+    needsDocument: false,
+    async boot(ctx) {
+        const { fragmentId, realm, env } = ctx;
+        // Markup first, stub second: the gateway-free path has no stub to read, and a host that named
+        // an entry explicitly means it.
+        const entry = ctx.entry ?? readEntry(realm.adapterOptions, fragmentId);
+        await realm.evaluate(entry);
+        /**
+         * The entry module registers itself on the realm's global during evaluation, rather than
+         * exporting something the host reads back.
+         *
+         * `realm.evaluate()` is a dynamic import in another realm, and its module namespace object is
+         * not reachable from here in a way that survives every bundler's output shape. A registration
+         * call is boring, explicit, and works the same whether the fragment ships an ES module, a
+         * bundled IIFE, or something a build tool invented last week.
+         */
+        const definition = readFragmentDefinition(realm.window);
+        if (!definition || typeof definition.mount !== 'function') {
+            throw new BraidError(`the entry module "${entry}" did not define a fragment`, {
+                fragmentId,
+                stage: 'adapter-mount',
+                fixHint: 'the entry module must call defineFragment({ mount }) from @braidlabs/core at import time — ' +
+                    'a default export is not enough, because the host reads the registration, not the module',
+            });
+        }
+        await definition.mount(env);
+    },
+};
+function readEntry(options, fragmentId) {
+    const entry = options['entry'];
+    if (typeof entry !== 'string' || entry.length === 0) {
+        throw new BraidError('the contract adapter needs an entry module', {
+            fragmentId,
+            stage: 'adapter-resolution',
+            fixHint: `set "entry" on the fragment's manifest ("entry": "/main.js"), or declare it on the slot ` +
+                `for a gateway-free fragment: <fragment-slot adapter="contract" entry="https://…/main.js">`,
+        });
+    }
+    return entry;
+}
+//# sourceMappingURL=contract-adapter.js.map

package/src/adapters/contract-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-adapter.js","sourceRoot":"","sources":["../../../../../libs/core/src/adapters/contract-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqB;IAC/C,IAAI,EAAE,UAAU;IAEhB;;;;OAIG;IACH,SAAS,EAAE,eAAe;IAE1B,0FAA0F;IAC1F,aAAa,EAAE,KAAK;IAEpB,KAAK,CAAC,IAAI,CAAC,GAAuB;QAChC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC;QACvC,8FAA8F;QAC9F,gCAAgC;QAChC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,SAAS,CAAC,KAAK,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;QAEvE,MAAM,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAE5B;;;;;;;;WAQG;QACH,MAAM,UAAU,GAAG,sBAAsB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAExD,IAAI,CAAC,UAAU,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YAC1D,MAAM,IAAI,UAAU,CAAC,qBAAqB,KAAK,6BAA6B,EAAE;gBAC5E,UAAU;gBACV,KAAK,EAAE,eAAe;gBACtB,OAAO,EACL,6FAA6F;oBAC7F,yFAAyF;aAC5F,CAAC,CAAC;QACL,CAAC;QAED,MAAM,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC;AAEF,SAAS,SAAS,CAAC,OAA0C,EAAE,UAAkB;IAC/E,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,UAAU,CAAC,4CAA4C,EAAE;YACjE,UAAU;YACV,KAAK,EAAE,oBAAoB;YAC3B,OAAO,EACL,0FAA0F;gBAC1F,2FAA2F;SAC9F,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/src/config.d.ts

@@ -6,7 +6,26 @@
  * achieves its interception with fragment-boundary techniques confined to each fragment's own
  * realm and shadow DOM subtree.
  */
+import type { HostContract } from './weave/contract.js';
+import type { FragmentCapabilities } from './weave/capabilities.js';
 export interface BraidOptions {
+    /**
+     * What this host offers fragments, as a contract they can require a range of.
+     *
+     * Optional, and its absence means "no contract declared" rather than "version 0" — a host that
+     * declares nothing composes every fragment that requires nothing, which is every fragment that
+     * exists today.
+     */
+    contract?: HostContract;
+    /**
+     * Per-fragment capability grants, by fragment id.
+     *
+     * The registry is the usual source — the gateway stamps a trusted fragment's capabilities onto
+     * its realm stub — but the untrusted tier has no gateway, so a host composing cross-origin
+     * fragments declares them here instead. Both sources are host-controlled, which is the invariant
+     * that matters; where both speak, the registry wins.
+     */
+    capabilities?: Record<string, FragmentCapabilities>;
     /**
      * Enables development-mode diagnostics: unaudited-API warnings from the compat document
      * facade, boundary-bypass reports, and verbose boot logging. Defaults to false.
@@ -26,9 +45,19 @@ export interface BraidOptions {
      * no adapter.
      */
     onHostNavigation?: (notify: () => void) => void;
+    /**
+     * The path the Braid gateway is mounted under (`/manage`), when the host shares its domain and
+     * does not own the root. Must match the gateway's `basePath`: the client fetches realm stubs and
+     * fragment documents from `/manage/__braid/…`. Call `initBraid` before any slot connects.
+     */
+    basePath?: string;
 }
 interface ResolvedBraidConfig {
     dev: boolean;
+    /** Empty, or an absolute path with no trailing slash. */
+    basePath: string;
+    contract?: HostContract;
+    capabilities?: Record<string, FragmentCapabilities>;
     onHostNavigation?: (notify: () => void) => void;
 }
 export declare function setBraidConfig(options?: BraidOptions): void;

package/src/config.js

@@ -8,14 +8,30 @@
  */
 const config = {
     dev: false,
+    basePath: '',
 };
 export function setBraidConfig(options = {}) {
     if (options.dev !== undefined) {
         config.dev = options.dev;
     }
+    if (options.contract) {
+        config.contract = options.contract;
+    }
+    if (options.capabilities) {
+        config.capabilities = options.capabilities;
+    }
     if (options.onHostNavigation) {
         config.onHostNavigation = options.onHostNavigation;
     }
+    // Kept in sync with the gateway's normalizeBasePath: a path the URL parser would rewrite (`/café`,
+    // a dot segment) could never match the parsed pathnames the gateway compares it to.
+    if (options.basePath !== undefined) {
+        const basePath = options.basePath.replace(/\/+$/, '');
+        if (basePath && (!/^(\/[^/?#\s]+)+$/.test(basePath) || new URL(basePath, 'http://braid.invalid').pathname !== basePath)) {
+            throw new Error(`braid: basePath "${options.basePath}" must be an absolute path such as "/manage"`);
+        }
+        config.basePath = basePath;
+    }
 }
 export function getBraidConfig() {
     return config;

package/src/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../libs/core/src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA8BH,MAAM,MAAM,GAAwB;IAClC,GAAG,EAAE,KAAK;CACX,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,UAAwB,EAAE;IACvD,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAC3B,CAAC;IACD,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAC7B,MAAM,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IACrD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,MAAM,CAAC,GAAG,CAAC;AACpB,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../libs/core/src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA+DH,MAAM,MAAM,GAAwB;IAClC,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,EAAE;CACb,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,UAAwB,EAAE;IACvD,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAC3B,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IACrC,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,MAAM,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC7C,CAAC;IACD,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAC7B,MAAM,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IACrD,CAAC;IACD,mGAAmG;IACnG,oFAAoF;IACpF,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACtD,IAAI,QAAQ,IAAI,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,GAAG,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,EAAE,CAAC;YACxH,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,CAAC,QAAQ,8CAA8C,CAAC,CAAC;QACtG,CAAC;QACD,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,MAAM,CAAC,GAAG,CAAC;AACpB,CAAC"}

package/src/context/context-bus.d.ts

@@ -39,7 +39,15 @@ export interface ContextReadOptions {
     as?: number;
     fragmentId?: string;
 }
-export declare const braidContext: {
+/**
+ * A context bus.
+ *
+ * State moved from module scope to instance fields so that a page can hold more than one — see
+ * `createContextBus`. Every method body below is unchanged by that move; the semantics that make
+ * this a bus rather than an event emitter are the versioning ones, and they are per-bus by nature.
+ */
+declare class ContextBus {
+    #private;
     /**
      * Declares the contract a context key carries.
      *
@@ -61,7 +69,59 @@ export declare const braidContext: {
     set(key: string, value: unknown): void;
     get(key: string, options?: ContextReadOptions): unknown;
     subscribe(key: string, listener: ContextListener, options?: ContextSubscribeOptions): () => void;
+    /** Every key that currently holds a value. Used to seed a fragment's mirror at handshake. */
+    keys(): string[];
+    /**
+     * Observes *which* keys change, including keys that do not exist yet.
+     *
+     * `subscribe` cannot serve this: it binds to one key by name, so a mirror built from it would
+     * silently miss every key first published after the fragment mounted.
+     */
+    observe(listener: (key: string) => void): () => void;
+    /**
+     * Raises if `as` cannot be projected to from the published version.
+     *
+     * The check `subscribe` runs, exposed so it can be run *earlier* — at the boundary handshake,
+     * before a fragment has been handed any state. Decided from the declared chain rather than from
+     * a stored value, so a fragment that mounts before the first broadcast gets the same answer as
+     * one that mounts after it.
+     */
+    assertReachable(key: string, as?: number, fragmentId?: string): void;
     /** Exposed for tests. */
     clear(): void;
-};
-export {};
+}
+/**
+ * The page-level context bus: what `<fragment-slot>` routes to unless a fragment is scoped elsewhere.
+ *
+ * Still a singleton, still the default, and every existing import of it behaves exactly as before.
+ * What changed is that it is now *an instance of something*, which is what makes a second bus
+ * possible at all.
+ */
+export declare const braidContext: ContextBus;
+/**
+ * Creates a bus a fragment owns, rather than one it merely subscribes to.
+ *
+ * Keys published here never reach the page bus and are never visible to any other fragment — not
+ * their values, not their names, not the timing of their changes. Two uses, and they are the two
+ * readings the plan left open:
+ *
+ * - **A private namespace.** A fragment that wants durable, versioned, cross-realm state that is
+ *   nobody else's business gets it without inventing a second storage mechanism, and without the
+ *   host having to grant or withhold anything.
+ * - **A subtree bus**, once nested fragments exist: a parent fragment hands its own bus to the
+ *   fragments it composes, and they coordinate below the host's notice.
+ *
+ * The first works today. The second needs nested fragments to be a first-class concept, which is a
+ * larger commitment and is not made here — but nothing about this signature has to change when it
+ * is, because the routing already addresses buses by `scope` rather than by position.
+ */
+export declare function createContextBus(): ContextBus;
+export type { ContextBus };
+/**
+ * The surface a boundary router needs from a bus.
+ *
+ * Named so the router can take its bus as a constructor argument rather than importing the
+ * singleton. That was not indirection for its own sake: it is why `createContextBus()` above is a
+ * new routing target rather than a refactor of everything that touches context.
+ */
+export type ContextBusLike = Pick<ContextBus, 'get' | 'keys' | 'observe' | 'assertReachable' | 'schemaFor'>;