@braidlabs/core 0.1.1

package/src/realm/realm-manager.js

@@ -0,0 +1,296 @@
+import { BraidError } from '../errors.js';
+import { isDevMode } from '../config.js';
+import { BRAID_ADAPTER_META, BRAID_ADAPTER_OPTIONS_META, BRAID_PROTOCOL_META, BRAID_PROTOCOL_VERSION, braidFragmentUrl, braidRealmUrl, } from '../protocol.js';
+export async function createRealm(kind, init) {
+    switch (kind) {
+        case 'compat-http':
+            return createCompatHttpRealm(init);
+        case 'contract-blob':
+            return createContractBlobRealm(init);
+        case 'sandbox':
+            throw new BraidError('the sandbox realm kind (untrusted tier) is not available in this build', {
+                fragmentId: init.fragmentId,
+                stage: 'realm-boot',
+                fixHint: 'this build ships the trusted tier only — trusted realms are namespace isolation, not a security boundary',
+            });
+        default:
+            throw new BraidError(`unknown realm kind "${kind}"`, {
+                fragmentId: init.fragmentId,
+                stage: 'realm-boot',
+            });
+    }
+}
+/**
+ * Creates a contract-mode realm from a `blob:` URL the runtime authors itself.
+ *
+ * Booting from a blob costs no network round trip, needs no gateway stub, and — because the
+ * realm never navigates — has **zero interaction with the joint session history**, which
+ * eliminates the whole class of back/forward corruption that http-booted realms have to work
+ * around. The realm document carries the fragment's `<base>` (so relative URLs resolve into the
+ * fragment's namespace) and the fragment's own import map.
+ *
+ * Contract-mode code never reads realm globals — it receives `env.location`/`env.document` — so
+ * the realm has no illusion to maintain and needs no patches. That is exactly why blob realms
+ * are safe here and forbidden in compat mode, where `history.replaceState` must be able to
+ * rewrite the realm's URL to the fragment's route (which a blob document cannot do).
+ */
+async function createContractBlobRealm(init) {
+    const { fragmentId, importMap } = init;
+    // The base href must be absolute: a blob: URL has an opaque path, so a root-relative href
+    // has nothing meaningful to resolve against.
+    const baseHref = new URL(braidFragmentUrl(fragmentId, '/'), location.origin).href;
+    const realmDocumentHtml = `<!doctype html><meta charset="utf-8"><title>Braid realm: ${escapeHtml(fragmentId)}</title>` +
+        `<meta name="${BRAID_PROTOCOL_META}" content="${BRAID_PROTOCOL_VERSION}">` +
+        `<base href="${escapeHtml(baseHref)}">` +
+        (importMap ? `<script type="importmap">${JSON.stringify(importMap)}</script>` : '');
+    const blobUrl = URL.createObjectURL(new Blob([realmDocumentHtml], { type: 'text/html' }));
+    const iframe = document.createElement('iframe');
+    iframe.hidden = true;
+    iframe.setAttribute('aria-hidden', 'true');
+    iframe.src = blobUrl;
+    iframe.name = `braid:${fragmentId}`;
+    const { promise: loaded, resolve: resolveLoaded, reject: rejectLoaded } = Promise.withResolvers();
+    iframe.addEventListener('load', () => resolveLoaded(), { once: true });
+    iframe.addEventListener('error', () => rejectLoaded(new BraidError('the contract realm document failed to load', {
+        fragmentId,
+        stage: 'realm-boot',
+        fixHint: `allow blob: in the host page's frame-src content security policy`,
+    })), { once: true });
+    document.body.appendChild(iframe);
+    try {
+        await loaded;
+    }
+    finally {
+        // the document has been created from it; the URL itself is no longer needed
+        URL.revokeObjectURL(blobUrl);
+    }
+    const realmWindow = iframe.contentWindow;
+    const realmDocument = iframe.contentDocument;
+    if (!realmWindow || !realmDocument) {
+        throw new BraidError('the contract realm is not same-origin with the host page', {
+            fragmentId,
+            stage: 'realm-boot',
+            fixHint: `allow blob: in the host page's frame-src content security policy`,
+        });
+    }
+    const handle = createRealmHandle('contract-blob', iframe, realmWindow, realmDocument, null, {}, init);
+    if (isDevMode()) {
+        installContractRealmGuidance(realmDocument, fragmentId);
+    }
+    if (isDevMode()) {
+        console.debug(`[braid:${fragmentId}] contract-blob realm ready`, { baseHref });
+    }
+    init.signal.addEventListener('abort', () => handle.dispose(), { once: true });
+    return handle;
+}
+/**
+ * Reads the adapter's manifest options off the realm stub.
+ *
+ * Malformed JSON is a gateway bug rather than something an app can fix, so it warns and yields
+ * nothing instead of failing the boot — an adapter that needs an option reports its own absence
+ * with a far more useful message than a parse error would.
+ */
+function readAdapterOptions(realmDocument, fragmentId) {
+    const raw = realmDocument
+        .querySelector(`meta[name="${BRAID_ADAPTER_OPTIONS_META}"]`)
+        ?.getAttribute('content');
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        console.warn(`[braid:${fragmentId}] the gateway sent unparsable adapter options; ignoring them`);
+        return {};
+    }
+}
+/**
+ * Builds the shared part of a realm handle: module evaluation and disposal.
+ *
+ * Module evaluation injects a module script built with the realm's *native* `createElement` and
+ * appended to the realm's own body — a script created in another document does not execute, and
+ * a script cloned from a parser-created one carries the "already started" flag and never runs.
+ */
+function createRealmHandle(kind, iframe, realmWindow, realmDocument, manifestAdapter, adapterOptions, init) {
+    // captured before any facade or dev guidance is spliced into the document's prototype chain
+    const nativeCreateElement = Document.prototype.createElement.bind(realmDocument);
+    const realmBody = realmDocument.body;
+    let evaluationCounter = 0;
+    async function evaluateModule(source) {
+        const callbackName = `__braidModuleDone${evaluationCounter++}__`;
+        const { promise, resolve, reject } = Promise.withResolvers();
+        Object.defineProperty(realmWindow, callbackName, {
+            configurable: true,
+            value: () => resolve(true),
+        });
+        const script = nativeCreateElement('script');
+        script.type = 'module';
+        // import declarations are hoisted, so appending the completion call after the fragment's
+        // own source is valid regardless of what the source imports
+        script.textContent = `${source}\n;window.${callbackName}?.();`;
+        const onError = (event) => reject(new BraidError(`module evaluation failed in the fragment's realm: ${event.message}`, {
+            fragmentId: init.fragmentId,
+            stage: 'adapter-mount',
+            cause: event.error,
+        }));
+        realmWindow.addEventListener('error', onError, { once: true });
+        script.addEventListener('error', () => reject(new BraidError('a module script failed to load in the fragment realm', {
+            fragmentId: init.fragmentId,
+            stage: 'adapter-mount',
+            fixHint: 'check that the module url resolves inside the fragment namespace',
+        })));
+        realmBody.appendChild(script);
+        try {
+            return await promise;
+        }
+        finally {
+            realmWindow.removeEventListener('error', onError);
+            Reflect.deleteProperty(realmWindow, callbackName);
+        }
+    }
+    return {
+        kind,
+        fragmentId: init.fragmentId,
+        window: realmWindow,
+        document: realmDocument,
+        manifestAdapter,
+        adapterOptions,
+        evaluateModule,
+        async evaluate(entryUrl) {
+            // resolved against the realm's <base>, so it lands in the fragment's namespace
+            await evaluateModule(`import ${JSON.stringify(new URL(entryUrl, realmDocument.baseURI).href)};`);
+        },
+        dispose() {
+            iframe.remove();
+        },
+    };
+}
+/**
+ * Dev-only guidance for contract realms: warns once when fragment code reads
+ * the realm's `document` instead of the `env` it was handed, and points at the contract.
+ *
+ * Known limitation, verified against the platform: `window.location` and `document.location`
+ * are `[LegacyUnforgeable]` — own, non-configurable properties that cannot be intercepted in
+ * any realm, ours included. So a fragment reaching for `location` gets the blob URL with no
+ * warning. This is the same platform rule that makes blob realms unable to fake an http URL,
+ * and it is why compat mode keeps http realms.
+ */
+function installContractRealmGuidance(realmDocument, fragmentId) {
+    const originalPrototype = Object.getPrototypeOf(realmDocument);
+    let warned = false;
+    const guidanceProxy = new Proxy(originalPrototype, {
+        get(target, property, receiver) {
+            if (!warned && typeof property === 'string' && property !== 'location') {
+                warned = true;
+                console.warn(`[braid:${fragmentId}] a contract-mode fragment read 'document.${property}' from its realm.\n` +
+                    `Realm globals are explicitly out of contract: use the env your adapter received ` +
+                    `(env.document, env.root, env.location) so the fragment keeps working when the isolation backend changes.`);
+            }
+            return Reflect.get(target, property, receiver);
+        },
+    });
+    Object.setPrototypeOf(realmDocument, guidanceProxy);
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;');
+}
+async function createCompatHttpRealm(init) {
+    const { fragmentId, routeUrl, bound } = init;
+    const routeSrcUrl = new URL(routeUrl, document.baseURI);
+    if (routeSrcUrl.origin !== location.origin) {
+        throw new BraidError(`route url "${routeUrl}" is not same-origin with the host page`, {
+            fragmentId,
+            stage: 'realm-boot',
+            fixHint: 'compat fragments are served through the gateway on the host origin; use a path, not a cross-origin url',
+        });
+    }
+    /**
+     * Create the iframe we'll load the fragment's JS context into, hidden from the viewport.
+     * The src must be set before the element is inserted to avoid double loads (and, in Firefox,
+     * spurious history records for iframes that get their src one task after insertion).
+     */
+    const iframe = document.createElement('iframe');
+    iframe.hidden = true;
+    // the realm stub has its own namespace, so the fragment's asset URLs carry no header variance
+    iframe.src = braidRealmUrl(fragmentId, routeSrcUrl.pathname, routeSrcUrl.search);
+    iframe.name = `braid:${fragmentId}`;
+    const { promise: loaded, resolve: resolveLoaded, reject: rejectLoaded } = Promise.withResolvers();
+    let alreadyLoaded = false;
+    let pendingHardNavigationHref = null;
+    iframe.addEventListener('load', () => {
+        if (alreadyLoaded) {
+            // iframe reload detected: the fragment app attempted to reload or hard-navigate.
+            if (bound) {
+                // Workaround for a Safari (v26) bfcache bug: after a hard navigation away and a
+                // back-button return, Safari recreates the iframe with the old src but feeds it the
+                // new document. Intercept the first reload, park the target href, restore the
+                // host's location into the iframe, then complete the hard navigation on the host.
+                if (pendingHardNavigationHref) {
+                    location.href = pendingHardNavigationHref;
+                }
+                else {
+                    pendingHardNavigationHref = iframe.contentWindow.location.href;
+                    iframe.contentWindow.location.href = location.href;
+                }
+            }
+            else {
+                console.warn(`[braid:${fragmentId}] unbound fragment reload detected — fragment content is stale`);
+            }
+            return;
+        }
+        alreadyLoaded = true;
+        try {
+            verifyRealmStub(iframe, fragmentId);
+            // Restore the fragment's route-url illusion: the iframe was loaded from the gateway
+            // namespace, but the fragment's JS context must observe the route url as its location.
+            // The stub's <base> element is unaffected by replaceState and keeps relative url
+            // resolution inside the namespace.
+            iframe.contentWindow.history.replaceState(null, '', routeSrcUrl.pathname + routeSrcUrl.search);
+            resolveLoaded();
+        }
+        catch (error) {
+            rejectLoaded(error);
+        }
+    });
+    document.body.appendChild(iframe);
+    await loaded;
+    if (isDevMode()) {
+        console.debug(`[braid:${fragmentId}] compat-http realm ready`, { src: iframe.src });
+    }
+    const handle = createRealmHandle('compat-http', iframe, iframe.contentWindow, iframe.contentDocument, iframe.contentDocument.querySelector(`meta[name="${BRAID_ADAPTER_META}"]`)?.getAttribute('content') ?? null, readAdapterOptions(iframe.contentDocument, fragmentId), init);
+    init.signal.addEventListener('abort', () => handle.dispose(), { once: true });
+    return handle;
+}
+/**
+ * Verifies the loaded iframe document is the gateway's realm stub for this protocol version.
+ * This replaces title-check heuristics with explicit version negotiation: mismatches and
+ * misconfigurations produce named errors with the likely fix.
+ */
+function verifyRealmStub(iframe, fragmentId) {
+    const stubDocument = iframe.contentDocument;
+    if (!stubDocument) {
+        throw new BraidError(`the realm document for "${iframe.src}" is not accessible`, {
+            fragmentId,
+            stage: 'realm-boot',
+            fixHint: 'ensure the gateway response is not delivered with "X-Frame-Options: deny" and is same-origin with the host page',
+        });
+    }
+    const protocol = stubDocument.querySelector(`meta[name="${BRAID_PROTOCOL_META}"]`)?.getAttribute('content');
+    if (protocol !== BRAID_PROTOCOL_VERSION) {
+        throw new BraidError(protocol
+            ? `gateway speaks braid protocol "${protocol}" but this client speaks "${BRAID_PROTOCOL_VERSION}"`
+            : `the document loaded from "${iframe.src}" is not a braid realm stub`, {
+            fragmentId,
+            stage: 'realm-boot',
+            fixHint: protocol
+                ? 'upgrade @braidlabs/core and @braidlabs/gateway to the same package version'
+                : `ensure the braid gateway is mounted in front of this app and has a manifest registered for fragment id "${fragmentId}"`,
+        });
+    }
+}
+//# sourceMappingURL=realm-manager.js.map

package/src/realm/realm-manager.js.map

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

package/src/utils/assert.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A generic assertion function.
+ *
+ * Typescript doesn't consider `console.assert` to be an assertion function, hence this wrapper.
+ * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+ */
+export declare function assert(value: boolean, message: string): asserts value;

package/src/utils/assert.js

@@ -0,0 +1,10 @@
+/**
+ * A generic assertion function.
+ *
+ * Typescript doesn't consider `console.assert` to be an assertion function, hence this wrapper.
+ * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+ */
+export function assert(value, message) {
+    console.assert(value, message);
+}
+//# sourceMappingURL=assert.js.map

package/src/utils/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../../../../../libs/core/src/utils/assert.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,KAAc,EAAE,OAAe;IACpD,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/src/utils/selector-helpers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * For CSS selectors that contain html, head, and body tag names, rewrite the selector with the
+ * braid-* prefix (the custom elements standing in for those singletons inside a fragment's DOM).
+ *
+ * Breakdown of the regex:
+ * (?<=^|[\s>+~,(]) - lookbehind to only match when preceded by start of string, whitespace and combinators
+ * \b(body|head|html)\b - match body|head|html exactly, but only at word boundaries
+ * (?=[\s>+~),:.#[\]]|$) - lookahead to only match when followed by end of string or combinators
+ */
+export declare const rewriteQuerySelector: (selector: string) => string;

package/src/utils/selector-helpers.js

@@ -0,0 +1,13 @@
+/**
+ * For CSS selectors that contain html, head, and body tag names, rewrite the selector with the
+ * braid-* prefix (the custom elements standing in for those singletons inside a fragment's DOM).
+ *
+ * Breakdown of the regex:
+ * (?<=^|[\s>+~,(]) - lookbehind to only match when preceded by start of string, whitespace and combinators
+ * \b(body|head|html)\b - match body|head|html exactly, but only at word boundaries
+ * (?=[\s>+~),:.#[\]]|$) - lookahead to only match when followed by end of string or combinators
+ */
+export const rewriteQuerySelector = (selector) => selector
+    ?.toString()
+    .replace(/(?<=^|[\s>+~,(])\b(body|head|html)\b(?=[\s>+~),:.#[\]]|$)/gi, (match) => `braid-${match.toLowerCase()}`) ?? selector;
+//# sourceMappingURL=selector-helpers.js.map

package/src/utils/selector-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector-helpers.js","sourceRoot":"","sources":["../../../../../libs/core/src/utils/selector-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,QAAgB,EAAE,EAAE,CACvD,QAAQ;IACN,EAAE,QAAQ,EAAE;KACX,OAAO,CACN,6DAA6D,EAC7D,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,KAAK,CAAC,WAAW,EAAE,EAAE,CAC1C,IAAI,QAAQ,CAAC"}