@braidlabs/core 0.1.1

package/README.md

@@ -0,0 +1,123 @@
+# @braidlabs/core
+
+The Braid client runtime — compose independently deployed frontend apps into one cohesive page:
+one origin, one DOM, one accessibility tree, while each app keeps its own JavaScript world, its
+own dependencies, and its own release train.
+
+Skew handling — versioned envelopes, migration chains, and negotiation — lives alongside this
+runtime in [`@braidlabs/skew`](../skew).
+
+**Start with [Braid, explained](../../docs/braid-explained.md)** if you are new to this: it defines
+every term this README uses and walks one page load end to end. The founding architecture and its
+rationale live in [`docs/braid-architecture.md`](../../docs/braid-architecture.md).
+
+Also see: [failure modes](../../docs/braid-failure-modes.md) ·
+[working POC](../../docs/braid-poc.md) ·
+[using Braid without the gateway](../../docs/braid-without-gateway.md)
+
+## Adapters in this build
+
+| Adapter | Manifest | For | Needs a document? |
+| --- | --- | --- | --- |
+| `compat` | omit `adapter` — this is the default | whole apps that cannot be modified | yes |
+| `custom-element` | `"adapter": "custom-element"` | a fragment that *is* a web component | no |
+
+The **compat adapter** is the contained emulation layer for apps that cannot be told anything
+(a legacy monolith mid-migration), and it is the default: a manifest that doesn't declare an
+adapter gets it. Being a fragment requires zero app-code changes; config only.
+
+The **custom-element adapter** is the other end of the spectrum, and the first adapter to use the
+contract surface. Registering a fragment that already ships a custom element takes three manifest
+fields and no emulation at all:
+
+```ts
+{ id: 'rating', endpoint: 'http://localhost:4503',
+  adapter: 'custom-element', entry: '/star-rating.js', element: 'star-rating',
+  events: ['rating:change'] }
+```
+
+The element is created **inside the realm**, where it upgrades against the fragment's own
+definition, then moved into the host's DOM — adoption across documents preserves the element's
+class, so the fragment's implementation keeps running while its custom element registry stays out
+of the host's. `env.props` are applied as DOM properties; the listed `events` are republished as
+`braid:event` on the slot. Such a fragment serves no document at all, which is what
+`needsDocument: false` on the adapter declares.
+
+The rest of the contract surface (`FragmentEnv`, `BraidAdapter`) is defined and exported, and
+**contract-blob realms work** (see below), but no framework contract adapters (react/angular/vue)
+ship yet, so nothing routes to them automatically.
+
+## Realms
+
+| Kind            | URL              | History involvement                        | Used by         |
+| --------------- | ---------------- | ------------------------------------------ | --------------- |
+| `compat-http`   | `/__braid/frag/…`| initial load only (`replaceState` after)   | compat adapter  |
+| `contract-blob` | `blob:`          | none, ever                                 | contract adapters (none yet) |
+| `sandbox`       | third-party      | —                                          | not in this build |
+
+Contract-blob realms boot from a `blob:` URL the runtime authors: no network round trip, no
+gateway stub, and zero interaction with the joint session history. Each carries a `<base>` into
+the fragment's namespace and its own import map, which is how two fragments ship different
+majors of the same dependency without a shared resolution namespace.
+
+Verified empirically in Chromium: same-origin and DOM-capable, five realms add
+**zero** history entries, per-realm import maps resolve, module evaluation works, and globals do
+not leak between realms. Firefox and WebKit remain unverified here.
+
+**Known platform limitation.** `window.location` and `document.location` are
+`[LegacyUnforgeable]` — own, non-configurable properties that cannot be intercepted in any
+realm, including one we authored. So the dev-mode guidance toward `env.*`
+covers `document` members but *cannot* cover `location`: a contract fragment reading `location`
+silently gets the blob URL. This is the same platform rule that stops a blob document from
+faking an http URL, and it is why compat mode keeps http realms.
+
+## Piercing
+
+When the gateway server-renders a fragment into the page, `<fragment-slot>` **adopts** that
+content instead of fetching: the slot detects the declarative shadow root the gateway wrote,
+and the compat adapter activates the already-neutralized content in place. `reload()` always
+goes back to the network.
+
+## Usage
+
+Host page:
+
+```ts
+import { initBraid } from '@braidlabs/core';
+
+initBraid({
+  // wire your router so bound fragments observe host navigations (Braid never patches
+  // the host History API — host purity is an invariant, not a mode):
+  onHostNavigation: (notify) => router.afterEach(() => notify()),
+});
+```
+
+```html
+<fragment-slot name="legacy-billing"></fragment-slot>
+```
+
+Server: mount [`@braidlabs/gateway`](../braid-gateway) in front of your app and register a
+manifest for `legacy-billing`. No fragment code is required.
+
+## What the compat adapter does
+
+- Boots each fragment's JS in a hidden same-origin iframe realm loaded from the gateway
+  namespace (`/__braid/frag/:id/…`), restoring the fragment's route-url illusion via
+  `history.replaceState`.
+- Installs the document facade: a Proxy spliced into the realm document's prototype chain,
+  driven by a generated WebIDL audit manifest — unaudited API use surfaces as loud diagnostics
+  in dev mode.
+- Confines all main-realm interception to the fragment boundary: per-node prototype stamping,
+  born-inert scripts, and a shadow-root-scoped observer safety net.
+- **Never patches a host-page global or prototype. In any mode. Ever.**
+
+## Isolation boundaries
+
+| Scope                   | Isolation mechanism                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------------------- |
+| compat realm (window)   | constructor `hasInstance`, observer/CSSOM constructor swaps, size getters, history proxy |
+| compat realm (document) | proxy facade over the document prototype chain (WebIDL-audited)                          |
+| fragment DOM nodes      | per-node prototype stamping (insertion/clone/ownerDocument/getRootNode)                  |
+| fragment scripts        | born-inert `type` shadowing traps until activation                                       |
+
+All interception is strictly confined to the fragment's own realm and shadow DOM boundary.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@braidlabs/core",
+  "version": "0.1.1",
+  "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",
+    "composition",
+    "fragments",
+    "version-skew",
+    "web-fragments"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/braidjs/braid.git",
+    "directory": "libs/core"
+  },
+  "homepage": "https://github.com/braidjs/braid#readme",
+  "bugs": {
+    "url": "https://github.com/braidjs/braid/issues"
+  },
+  "module": "./src/index.js"
+}

package/src/adapters/adapter.d.ts

@@ -0,0 +1,75 @@
+import { FragmentEnv } from '../env/fragment-env.js';
+import { RealmHandle, RealmKind } from '../realm/realm-manager.js';
+/**
+ * The adapter authoring surface: framework adapters map a `FragmentEnv` into the
+ * framework's own extension points (Angular's `DOCUMENT` DI token, React's `createRoot`, …).
+ * Teardown is signal-driven via `env.signal`.
+ */
+export interface BraidAdapter {
+    mount(env: FragmentEnv, entry: unknown): Promise<void> | void;
+}
+/**
+ * Everything the runtime hands an installed adapter to boot a fragment instance. This is the
+ * internal counterpart of {@link BraidAdapter}: contract adapters only need `env` + `entry`,
+ * while the compat adapter — which owns the full emulation layer — additionally drives the
+ * realm and the fragment's DOM directly.
+ */
+export interface AdapterBootContext {
+    fragmentId: string;
+    /** The fragment's shadow root (owned by the <fragment-slot> element). */
+    shadowRoot: ShadowRoot;
+    /** The <braid-document> element acting as the fragment's virtual document element. */
+    contentRoot: HTMLElement;
+    /** The fragment's already-created realm. */
+    realm: RealmHandle;
+    /**
+     * 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.
+     */
+    html: string | null;
+    /**
+     * Whether the fragment's content was server-rendered into the page by the gateway. It is
+     * already neutralized (scripts inert, singletons renamed) and already in the DOM; the adapter
+     * activates it in place instead of building it.
+     */
+    pierced: boolean;
+    /** The fragment's logical route URL (pathname + search). */
+    routeUrl: string;
+    /** Whether the fragment's navigation is bound to the host window's navigation. */
+    bound: boolean;
+    env: FragmentEnv;
+    /** Aborts when the fragment is being torn down. */
+    signal: AbortSignal;
+}
+/**
+ * An installed adapter: which realm kind its fragments boot in, and the boot routine itself.
+ */
+export interface InstalledAdapter {
+    readonly name: string;
+    readonly realmKind: RealmKind;
+    /**
+     * Whether the adapter needs the fragment's *document* — the markup the gateway prepares for
+     * the host's DOM. True unless stated otherwise.
+     *
+     * Contract adapters generally build their own UI from an entry module and never look at
+     * fragment HTML. Saying so here means a fragment that serves no document (a lone custom
+     * element, say) is not reported as broken for failing to serve one.
+     */
+    readonly needsDocument?: boolean;
+    boot(ctx: AdapterBootContext): Promise<void>;
+}
+/**
+ * The adapter every fragment runs under when its manifest does not declare one.
+ *
+ * This build ships only the compat adapter — the contained emulation
+ * layer — and makes it the default, so legacy apps compose with zero app-code changes.
+ */
+export declare const DEFAULT_ADAPTER = "compat";
+export declare function installAdapter(adapter: InstalledAdapter): void;
+/**
+ * Resolves an adapter by its manifest-declared name, defaulting to {@link DEFAULT_ADAPTER}.
+ * An unknown adapter is a named error, not a silent fallback.
+ */
+export declare function resolveAdapter(name: string | null | undefined, fragmentId: string): InstalledAdapter;
+/** Exposed for tests. */
+export declare function clearInstalledAdapters(): void;

package/src/adapters/adapter.js

@@ -0,0 +1,35 @@
+import { BraidError } from '../errors.js';
+/**
+ * The adapter every fragment runs under when its manifest does not declare one.
+ *
+ * This build ships only the compat adapter — the contained emulation
+ * layer — and makes it the default, so legacy apps compose with zero app-code changes.
+ */
+export const DEFAULT_ADAPTER = 'compat';
+const installedAdapters = new Map();
+export function installAdapter(adapter) {
+    installedAdapters.set(adapter.name, adapter);
+}
+/**
+ * Resolves an adapter by its manifest-declared name, defaulting to {@link DEFAULT_ADAPTER}.
+ * An unknown adapter is a named error, not a silent fallback.
+ */
+export function resolveAdapter(name, fragmentId) {
+    const adapterName = name || DEFAULT_ADAPTER;
+    const adapter = installedAdapters.get(adapterName);
+    if (!adapter) {
+        throw new BraidError(`no adapter named "${adapterName}" is installed in this client`, {
+            fragmentId,
+            stage: 'adapter-resolution',
+            fixHint: adapterName === DEFAULT_ADAPTER
+                ? 'call initBraid() before any <fragment-slot> connects, so the default compat adapter is installed'
+                : `this build of @braidlabs/core ships only the "compat" adapter; either set "adapter": "compat" in the fragment's manifest (or omit it — compat is the default), or install a client build that provides "${adapterName}"`,
+        });
+    }
+    return adapter;
+}
+/** Exposed for tests. */
+export function clearInstalledAdapters() {
+    installedAdapters.clear();
+}
+//# sourceMappingURL=adapter.js.map

package/src/adapters/adapter.js.map

@@ -0,0 +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"}

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

@@ -0,0 +1,27 @@
+import { InstalledAdapter } from './adapter.js';
+/**
+ * The compat adapter — the emulation layer, contained.
+ *
+ * For apps that cannot be told anything (the legacy monolith mid-migration), this adapter
+ * provides the full web-fragments-style illusion: the fragment's code believes it owns the whole
+ * browser, while its DOM lives in the host page's shadow root and its JS runs in a hidden
+ * same-origin realm iframe. All interception is confined to the fragment's own realm and
+ * boundary; the host page is never patched.
+ *
+ * This is the only adapter shipped in this build, and the default (see `DEFAULT_ADAPTER`):
+ * a manifest that doesn't declare an adapter gets this one, so being a fragment requires zero
+ * app-code changes — config only.
+ */
+export declare const compatAdapter: InstalledAdapter;
+/**
+ * Parses gateway-prepared fragment markup into nodes owned by the host document.
+ *
+ * The markup arrives already transformed (`braid-html`/`braid-head`/`braid-body` stand-ins,
+ * inert scripts, namespaced subresource URLs), so this only parses and adopts it — parsing
+ * happens in a detached `DOMParser` document, where nothing executes.
+ *
+ * The stand-ins are unknown elements, so the parser leaves them in `body`; the fragment's root
+ * is `braid-html` when the gateway saw a full document, and a wrapper is synthesized when it
+ * saw a bare markup snippet.
+ */
+export declare function parseFragmentContent(html: string, mainDocument: Document): HTMLElement;

package/src/adapters/compat-adapter.js

@@ -0,0 +1,113 @@
+import { compatMetadataSymbol } from '../compat/metadata.js';
+import { initializeRealmContext } from '../compat/realm-patches.js';
+import { executeScriptsInFragmentContent } from '../compat/script-execution.js';
+import { isDevMode } from '../config.js';
+/**
+ * The compat adapter — the emulation layer, contained.
+ *
+ * For apps that cannot be told anything (the legacy monolith mid-migration), this adapter
+ * provides the full web-fragments-style illusion: the fragment's code believes it owns the whole
+ * browser, while its DOM lives in the host page's shadow root and its JS runs in a hidden
+ * same-origin realm iframe. All interception is confined to the fragment's own realm and
+ * boundary; the host page is never patched.
+ *
+ * This is the only adapter shipped in this build, and the default (see `DEFAULT_ADAPTER`):
+ * a manifest that doesn't declare an adapter gets this one, so being a fragment requires zero
+ * app-code changes — config only.
+ */
+export const compatAdapter = {
+    name: 'compat',
+    realmKind: 'compat-http',
+    async boot(ctx) {
+        const { fragmentId, shadowRoot, contentRoot, realm, html, pierced, bound, signal } = ctx;
+        const fragmentShadowRoot = Object.assign(shadowRoot, {
+            [compatMetadataSymbol]: { documentReadyState: 'loading' },
+        });
+        if (!pierced) {
+            // The gateway prepared this markup exactly as it prepares pierced content — singletons
+            // renamed, scripts neutralized, subresource URLs re-rooted — so the client only has to
+            // parse it. Re-applying those transforms here would be actively harmful: neutralizing an
+            // already-inert script would record `inert` as its "real" type and it would never run.
+            const content = parseFragmentContent(html ?? '', contentRoot.ownerDocument);
+            // Insert the (fully inert) content before the boundary exists; the boundary stamps the
+            // whole tree when it is created below — same order as the pierced flow.
+            contentRoot.appendChild(content);
+        }
+        // The abort controller tears down every listener/observer the compat machinery installs;
+        // it aborts when the fragment unmounts (slot disconnect) or the realm unloads.
+        const fragmentAbortController = new AbortController();
+        signal.addEventListener('abort', () => fragmentAbortController.abort(), { once: true });
+        // Install the full compat illusion onto the realm (window patches, document facade,
+        // boundary stamping, born-inert scripts).
+        const realmContext = initializeRealmContext(realm, fragmentShadowRoot, contentRoot, bound, fragmentAbortController);
+        // Now activate the fragment's scripts, in document order, in the realm's JS context.
+        executeScriptsInFragmentContent(contentRoot, realm.document);
+        // The fragment's own code has run, so its router has resolved whatever initial route it was
+        // going to resolve. From here a navigation is the user's, and a bound fragment may drive the
+        // host URL with it.
+        realmContext.bootComplete();
+        // Replicate the document lifecycle the fragment would observe standalone.
+        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 });
+            }
+        });
+    },
+};
+/**
+ * Parses gateway-prepared fragment markup into nodes owned by the host document.
+ *
+ * The markup arrives already transformed (`braid-html`/`braid-head`/`braid-body` stand-ins,
+ * inert scripts, namespaced subresource URLs), so this only parses and adopts it — parsing
+ * happens in a detached `DOMParser` document, where nothing executes.
+ *
+ * The stand-ins are unknown elements, so the parser leaves them in `body`; the fragment's root
+ * is `braid-html` when the gateway saw a full document, and a wrapper is synthesized when it
+ * saw a bare markup snippet.
+ */
+export function parseFragmentContent(html, mainDocument) {
+    const parsed = new DOMParser().parseFromString(html, 'text/html');
+    const braidHtml = parsed.body.querySelector('braid-html');
+    if (braidHtml) {
+        return mainDocument.importNode(braidHtml, true);
+    }
+    const wrapper = mainDocument.createElement('braid-html');
+    const braidBody = mainDocument.createElement('braid-body');
+    braidBody.append(...[...parsed.body.childNodes].map((node) => mainDocument.importNode(node, true)));
+    wrapper.append(braidBody);
+    return wrapper;
+}
+/**
+ * Returns a promise resolving when all images in the fragment's DOM have loaded (or errored).
+ */
+function allImagesLoaded(contentRoot) {
+    const images = contentRoot.querySelectorAll('img');
+    if (images.length === 0) {
+        return Promise.resolve();
+    }
+    const imagePromises = [...images].map((image) => {
+        return new Promise((resolve) => {
+            if (image.complete) {
+                resolve();
+            }
+            else {
+                image.addEventListener('load', () => resolve());
+                image.addEventListener('error', () => resolve());
+            }
+        });
+    });
+    return Promise.all(imagePromises).then(() => undefined);
+}
+//# sourceMappingURL=compat-adapter.js.map

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

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

package/src/adapters/custom-element-adapter.d.ts

@@ -0,0 +1,21 @@
+import { InstalledAdapter } from './adapter.js';
+/**
+ * The custom-element adapter — a fragment that ships an ordinary custom element.
+ *
+ * This is contract-mode: no document facade, no window patches, no boundary stamping. A
+ * well-behaved custom element does not need to believe it owns the browser; it needs a mount
+ * point, its props, and a teardown signal — which is exactly what `FragmentEnv` provides. The
+ * whole adapter is the code below.
+ *
+ * **How the element gets into the host page.** Custom element registries are per-window, so an
+ * element defined in the fragment's realm only upgrades elements created by *that* realm's
+ * document. So the element is created in the realm — where it upgrades against the fragment's
+ * own definition — and then moved into the host's DOM. Adoption preserves the element's class
+ * and behavior (the spec calls `adoptedCallback` and the instance keeps its definition), which
+ * is what lets a fragment's element live in the host page while its code stays isolated.
+ *
+ * The isolation this buys is real: two fragments may define the same tag name differently, or
+ * ship different majors of the same component library, and nothing collides — each definition
+ * lives in its own registry.
+ */
+export declare const customElementAdapter: InstalledAdapter;

package/src/adapters/custom-element-adapter.js

@@ -0,0 +1,91 @@
+import { BraidError } from '../errors.js';
+import { isDevMode } from '../config.js';
+/**
+ * The custom-element adapter — a fragment that ships an ordinary custom element.
+ *
+ * This is contract-mode: no document facade, no window patches, no boundary stamping. A
+ * well-behaved custom element does not need to believe it owns the browser; it needs a mount
+ * point, its props, and a teardown signal — which is exactly what `FragmentEnv` provides. The
+ * whole adapter is the code below.
+ *
+ * **How the element gets into the host page.** Custom element registries are per-window, so an
+ * element defined in the fragment's realm only upgrades elements created by *that* realm's
+ * document. So the element is created in the realm — where it upgrades against the fragment's
+ * own definition — and then moved into the host's DOM. Adoption preserves the element's class
+ * and behavior (the spec calls `adoptedCallback` and the instance keeps its definition), which
+ * is what lets a fragment's element live in the host page while its code stays isolated.
+ *
+ * The isolation this buys is real: two fragments may define the same tag name differently, or
+ * ship different majors of the same component library, and nothing collides — each definition
+ * lives in its own registry.
+ */
+export const customElementAdapter = {
+    name: 'custom-element',
+    /**
+     * An http realm, not a blob realm, only because the client learns which adapter a fragment
+     * uses by reading the realm stub — so the stub has to exist before the adapter is chosen.
+     * Nothing else here needs it, and moving to `contract-blob` (no round trip, no history
+     * interaction) is a change to the realm manager alone.
+     */
+    realmKind: 'compat-http',
+    /**
+     * The element is built from the entry module, so the fragment's HTML is never read. A widget
+     * that ships only a script is a complete fragment.
+     */
+    needsDocument: false,
+    async boot(ctx) {
+        const { fragmentId, realm, env, signal } = ctx;
+        const options = readOptions(realm.adapterOptions, fragmentId);
+        // define the element inside the fragment's own realm
+        await realm.evaluate(options.entry);
+        if (!realm.window.customElements.get(options.element)) {
+            throw new BraidError(`the entry module did not define a custom element named "${options.element}"`, {
+                fragmentId,
+                stage: 'adapter-mount',
+                fixHint: `check the "element" in this fragment's manifest against the tag name its entry module ` +
+                    `registers with customElements.define()`,
+            });
+        }
+        // created in the realm so it upgrades against the fragment's definition, then moved into
+        // the host's DOM — adoption keeps the class, so it behaves the same in either document
+        const element = realm.document.createElement(options.element);
+        applyProps(element, env.props);
+        env.root.append(element);
+        env.onPropsChanged((props) => applyProps(element, props));
+        // the fragment's own events, republished on the host boundary as braid:event
+        for (const type of options.events) {
+            element.addEventListener(type, (event) => env.emit(type, event.detail), { signal });
+        }
+        signal.addEventListener('abort', () => element.remove(), { once: true });
+        if (isDevMode()) {
+            console.debug(`[braid:${fragmentId}] mounted <${options.element}>`, {
+                entry: options.entry,
+                forwarding: options.events,
+            });
+        }
+    },
+};
+function readOptions(raw, fragmentId) {
+    const entry = typeof raw['entry'] === 'string' ? raw['entry'] : '';
+    const element = typeof raw['element'] === 'string' ? raw['element'] : '';
+    if (!entry || !element) {
+        throw new BraidError(`the custom-element adapter needs "entry" and "element" in this fragment's manifest`, {
+            fragmentId,
+            stage: 'adapter-resolution',
+            fixHint: `add them to the manifest, e.g. { "adapter": "custom-element", "entry": "/widget.js", "element": "star-rating" }`,
+        });
+    }
+    return {
+        entry,
+        element,
+        events: Array.isArray(raw['events']) ? raw['events'].filter((e) => typeof e === 'string') : [],
+    };
+}
+/**
+ * Props are assigned as element *properties*, which is the custom-element convention for
+ * structured values — attributes would stringify them.
+ */
+function applyProps(element, props) {
+    Object.assign(element, props);
+}
+//# sourceMappingURL=custom-element-adapter.js.map

package/src/adapters/custom-element-adapter.js.map

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

package/src/compat/born-inert-scripts.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Born-inert scripts.
+ *
+ * Every script element created by fragment code (via the document facade's
+ * `createElement`/`createElementNS`) is neutralized at creation: its `type` attribute is set to
+ * `inert` before fragment code can attach content or insert it. This guarantees that no script
+ * reachable by fragment code can ever execute in the main JS context, no matter how it is
+ * inserted — even through code paths the boundary does not intercept synchronously.
+ *
+ * So that fragment code doesn't observe the neutralization, the script's `type` property and its
+ * `getAttribute`/`setAttribute` methods are shadowed to read and write the real type from/to the
+ * `data-script-type` attribute (the same attribute the gateway uses when neutralizing SSR
+ * content). The shadowing own-properties are removed before the script is activated.
+ */
+export declare function makeScriptBornInert(script: HTMLScriptElement): void;
+export declare function isBornInertScript(script: HTMLScriptElement): boolean;
+/**
+ * Removes the type-shadowing own-properties, leaving the script in the standard inert form
+ * (`type="inert"` plus the real type in `data-script-type`) that the script execution machinery
+ * understands. Used on the asynchronous (boundary observer) activation path, where the script is
+ * already attached to the fragment's DOM in inert form.
+ */
+export declare function removeBornInertShadowing(script: HTMLScriptElement): void;
+/**
+ * Fully reverts a born-inert script to the live form the application intended (real `type`
+ * attribute, no `data-script-type`). Used on the synchronous (stamped insertion) activation
+ * path, which re-neutralizes the script itself before performing the actual DOM insertion — the
+ * script is never attached to the DOM in live form.
+ */
+export declare function unwrapBornInertScriptToLive(script: HTMLScriptElement): void;